New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ERC 1497: Evidence Standard #1497

Open
satello opened this Issue Oct 16, 2018 · 0 comments

Comments

Projects
None yet
1 participant
@satello
Copy link

satello commented Oct 16, 2018

EIP 1497
Title: Evidence Standard
Status: Draft
Type: Informational
Category: ERC
Authors: Sam Vitello <sam@kleros.io>, Clément Lesaege <clement@kleros.io>, Enrique Piqueras <enrique@kleros.io>
Created: 2018-10-16

Abstract

The following describes the standards for MetaEvidence and Evidence for dispute resolution. Evidence is provided by a participant in a dispute in order to support their assertion. MetaEvidence gives context to the dispute so that arbitrators are able to accurately and fairly evaluate it. This standard follows ERC 792 and references Arbitrator and Arbitrable contracts.

Motivation

Standardizing MetaEvidence and Evidence allows interoperability between Arbitrable DApps (DApps where disputes can arise) and Arbitrator DApps (DApps which can be used to resolve disputes). It allows these applications to easily switch from one arbitration service to another, or to let their users decide which arbitration service to use without having to spend time to integrate with all of them. MetaEvidence is required to provide the context of the dispute. Evidence allows for dispute participants to submit extra information for the arbitrators.

The ERC792 standardizes the way the smart contracts interact with each other while this standard is made to standardize the way the interfaces interact in the context of disputes.

Specification

MetaEvidence

MetaEvidence provides the context of the dispute, the question the arbitrators have to answer, the human readable meanings of rulings and specific modes of display for evidence.

NOTE: Each dispute includes only one piece of MetaEvidence, however, the same MetaEvidence can be used for multiple disputes.
NOTE: It is up to the Arbitrable contract to determine how MetaEvidence is submitted and assigned to a dispute.
NOTE: In some use cases, MetaEvidence is all that the Arbitrator will need in order to make a ruling.
NOTE: All MetaEvidence fields are optional. An Arbitrator interface should have defaults for every field. However, not supplying contextual fields may affect the arbitrator’s ability to make an accurate ruling. Not supplying hash fields meant to secure the integrity of the data may result in arbitrators being warned that the data could have been altered.

Events

MetaEvidence
MetaEvidence has to be created before a dispute can arise. The MetaEvidence event includes an identifier used to link the MetaEvidence to a dispute and the _evidence reference is a URI to a JSON file, specified below, whose name is the multihash hash of the file with no file type extension. If it is not possible to use multihash for the name of the file, use the selfHash field described below. The JSON file should have all insignificant whitespace removed before hashing.

To be emitted when MetaEvidence is submitted:

event MetaEvidence(uint indexed _metaEvidenceID, string _evidence);

Dispute
The Dispute event is raised when a dispute is created to link the proper MetaEvidence to the dispute. The event includes a reference to the Arbitrator, the dispute it relates to, and the identifier of the MetaEvidence event that will provide the URI to the MetaEvidence.

To be emitted when a dispute is created to link the MetaEvidence to the dispute.

event Dispute(Arbitrator indexed _arbitrator, uint indexed _disputeID, uint _metaEvidenceID);

JSON

The MetaEvidence JSON file includes the following properties:

{
  "fileURI": string,
  "fileHash": string,
  “fileTypeExtension": string,
  "category": string,
  "title": string,
  "description": string,
  "aliases": {
    [string]: string
  },
  "question": string,
  "rulingOptions": {
    "titles": [],
    "descriptions": []
  },
  "evidenceDisplayInterfaceURL": string,
  "evidenceDisplayInterfaceURLHash": string,
  "selfHash": string
}

fileURI

The URI that leads to a natural language contract, agreement, or primary document that is the basis of the dispute. The file name should be the multihash hash of the resulting file. If this is not possible use fileHash.

Example: "/ipfs/QmUQMJbfiQYX7k6SWt8xMpR7g4vwtAYY1BTeJ8UY8JWRs9”

fileHash

The multihash hash of the primary document file. This may not be included for dynamic or mutable evidence. Not including the hash, either as the file name or in this property, may result in arbitrators being made aware that the evidence could have been altered.

Example: “QmUQMJbfiQYX7k6SWt8xMpR7g4vwtAYY1BTeJ8UY8JWRs9”

fileTypeExtension

The file type extension of the resulting file. This can be used by an Arbitrator interface to display the file.

Example: “pdf”

category

A short (one word or phrase) high level identifier for the type of dispute. E.g. “Curated List”, “Oracle” or “Escrow”.

Example: "Escrow"

title

Title that summarizes the relationship between the participants.

Example: "Alice Builds a Webpage for Bob"

description

Description of the relationship between the participants. Here is where more detail can be provided so that arbitrators can fully understand the context in which the dispute arose. It can be a summary of the terms of the primary document file, and/or include other contextual information.

Example: "Alice is hired by Bob as a contractor to create a website for his company. When completed, the site will be hosted at https://my-site.com."

aliases

A mapping that can be used by the Arbitrator interface to translate each given key to the supplied value. For example, ETH addresses can be mapped to human readable terms to make the dispute easier to understand.

Example:

{
    "0x56b2b5C88C9AC1D0E5785ED1A7c7B28173F5eE1b": "Alice",
    "0x8961286757C764a4a6Be9689649BA9E08DBaca4a": "Bob"
}

question

The question that arbitrators have to answer.

Example: "Is the website compliant with the terms of the contract?"

rulingOptions

An array of titles and descriptions that provide clarity on the available rulings to arbitrators. Indexes map to the ruling options of the Arbitrable contract. Ruling indexing starts at ruling option 1 (rulingOptions.titles[0] corresponds to ruling option 1 in the Arbitrable contract). The ruling option 0 is always reserved for “Refuse to Arbitrate” and should not be included in the array. The Arbitrator interface can specify the specific title and description used for the “Refuse to Arbitrate” ruling.

Example:

{
    “titles”: [“Yes”, “No”],
    “descriptions”: [
         "The website is compliant. This will release the funds to Alice.",
         "The website is not compliant. This will refund Bob."
    ]
}

evidenceDisplayInterfaceURI

The URI to a display interface that should be used to render the evidence for arbitrators. The Arbitrator interface should use an iframe to render the display interface. Data can be passed to the custom display interface with query parameters or with browser based approaches such as window.postMessage.

NOTE: Arbitrator interfaces should still have a default way to display evidence, as not all evidence will use a custom evidence display interface.
NOTE: Arbitrator interfaces should take security precautions when injecting the evidence display interface code into their page. The iframe used to render the external interface should be secured properly with a sandbox or other means of disabling functionality that could pose a security risk to the interface or users. For example, an interface should disallow the injected web3 object from MetaMask or a different browser wallet from requesting signatures from the user. This can be accomplished by using a sandbox to disallow the external interface from retaining its origin (and therefore using the browser’s built in security features to block API requests), or by removing methods such as sign and personalSign from the injected web3 object.

Example: "https://my-site.com/evidence-display/escrow"

evidenceDisplayInterfaceHash

Like fileHash for fileURI.

Example: “QmUQMJbfiQYX7k6SWt8xMpR7g4vwtAYY1BTeJ8UY8JWRs9”

selfHash

For instances where the name of the MetaEvidence file is not the multihash hash, the selfHash key can be used to provide data integrity. The selfHash is a multihash hash of the MetaEvidence JSON, excluding the selfHash field.

Example: “QmUQMJbfiQYX7k6SWt8xMpR7g4vwtAYY1BTeJ8UY8JWRs9”

Evidence

Arbitrable contracts emit an event that contains a reference to an evidence JSON file when new evidence is submitted.

Events

Evidence

The event log should include the Arbitrator contract, a reference to the dispute it relates to, the address of the submitting party, and reference to the evidence. The evidence reference is a URI to a JSON file, specified below, whose name is the multihash hash of the file with no file type extension. If it is not possible to use multihash for the name of the file, use the selfHash field described below. The JSON file should have all insignificant whitespace removed before hashing.

To be triggered when evidence is submitted:

event Evidence(Arbitrator indexed _arbitrator, uint indexed _disputeID, address indexed _party, string _evidence)

JSON

The Evidence JSON file includes the following properties:

{
  "fileURI": string,
  "fileHash": string,
  "fileTypeExtension": string,
  "name": string,
  "description": string,  
  "selfHash": string
}

fileURI

Like the fileURI for MetaEvidence.

Example: “/ipfs/QmWQV5ZFFhEJiW8Lm7ay2zLxC2XS4wx1b2W7FfdrLMyQQc”.

fileHash

Like the fileHash for MetaEvidence.

Example: “QmWQV5ZFFhEJiW8Lm7ay2zLxC2XS4wx1b2W7FfdrLMyQQc”.

fileTypeExtension

Like the fileTypeExtension for MetaEvidence.

Example: “pdf”.

name

What the piece of evidence should be called.

Example: “Email clarifying the terms of the contract.”

description

A brief description of what the evidence contains. Can also include any necessary context to understand the evidence.

Example: “This is an email sent to Alice from Bob that clarifies that the checkout screen can be integrated with the catalog page.”

selfHash

Like the selfHash for MetaEvidence.

Example: “QmUQMJbfiQYX7k6SWt8xMpR7g4vwtAYY1BTeJ8UY8JWRs9”

Rationale

  • A series of hashes are used to verify that evidence has not been tampered with. The blockchain events can maintain integrity of the address of the submitter, the date of submission, and the hash of the MetaEvidence or Evidence file. Hashes included in the JSON file of the MetaEvidence or Evidence can then be used to verify that the evidence has not changed since submission.
  • JSON objects are a standard way to structure and share data on the web. They provide structural flexibility to represent any type of data, can maintain integrity through use of hashing, and are easily interpreted.
  • It is not practical to store all type of evidence on the blockchain, so links to off-chain evidence are broadcasted instead. URIs are compatible with classical web URLs as well as decentralized web storage such as IPFS and SWARM. Both partially and fully decentralized dapps can be supported with URIs.
  • The fileURI and fileHash are two separate variables in the MetaEvidence and Evidence JSON to maximize flexibility on the types of links that can be used (as opposed to only supporting the hash as the file name). For example, if the evidence is a news article or some other public resource, the hash needs to be included separately.
  • selfHash is in bothMetaEvidence and Evidenceinstead of being included in the events as a separate field, because it saves gas, and users who use storage mechanisms that allow using the hash as the file name won’t be required to provide it.

Implementations

Smart Contract Examples

JSON File Examples

Evidence Display Interface Examples

@satello satello changed the title ERC 1496: Evidence Standard ERC 1497: Evidence Standard Oct 16, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment