ERC 1497: Evidence Standard
An evidence standard for arbitration
Last updated
An evidence standard for arbitration
Last updated
📖 Link to full ERC-1497 documentation 📖
📜 EIP-1497 📜
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.
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.
The purpose of this specification is to create a standard way for DApps that are part of the dispute resolution process to share context and information. This standard should allow DApps that have disputes they need arbitrated a way to provide the details of the dispute to the Arbitrator. Conversely, for an Arbitrator interface to be able to display a dispute to be ruled on, there needs to be a standard way for the interface to fetch evidence from the Arbitrable contracts.
Let’s consider an example where a developer is asked to develop an e-commerce website. The contracting party locks up the payment for the website in an escrow smart contract. Unfortunately, once the developer submits her work, there is a disagreement on whether the terms have been met and a dispute is raised in the smart contract. Now the case will go to an arbitration service, but in order for the arbitrators to make a fair ruling, they need to understand what the dispute is about and to take into consideration the arguments from both parties.
In essence, there are two kinds of evidence needed for the arbitrators to be able to make a ruling.
The first type of evidence, called MetaEvidence, provides the whole picture behind the dispute. In this case, it could be the original off-chain contract or agreement, as well as important information regarding what consequence(s) an arbitrator's ruling will have. MetaEvidence is used to convey this information to the chosen arbitrator.
The second type is the material evidence, such as emails, screenshots and contracts or testimony provided by each party to try to prove that the dispute should be ruled in their favor. In the above case, the programmer might submit the code as evidence, while the contracting party submits screenshots of what is missing.
In the case of our Evidence Standard, MetaEvidence is the context while Evidence is the proof provided by each party.
In order to provide flexibility for all different types of disputes, and to try to keep minimal information on the chain, we decided to create standardized JSON objects that can be hosted anywhere and fetched by an interface to display a dispute. Below we provide some examples. For more information on what each field does, take a look at the standard specification.
We have already discussed what MetaEvidence is, so let’s take a look at how a piece of MetaEvidence might actually look and how it would be used. Each dispute has one piece of MetaEvidence that is used to give all of the contextual information for a contract that might be disputed. MetaEvidence should be created at the same time as the agreement so that it can be impartial. The only restriction on MetaEvidence is that it must be created before a dispute can be raised in the smart contract.
The fields in this MetaEvidence JSON are as follows:
category: The category that the dispute belongs to. All values are accepted here, but it's good to align it with other past disputes of the same kind for consistency.
title: A title to describe what the dispute is about. Can be constant for all disputes from your dApp.
description: Text to describe the situation of the case. It can also be static for all cases, in which you will just have a generic description that describes what to look out for in these cases.
question: This is question posed to the jury after they review all the facts, documents and evidences of the case.
rulingOptions:
type: Can be one of the following values:
single-select: the jurors select one answer among the provided options.
multiple-select: the jurors can select any number of the provided options.
uint: the jurors input an unsigned integer.
int: the jurors input a signed integer.
string: the jurors enter a string. String must fit into bytes32.
precision: only applicable for ruling types int and uint to indicate the number of decimal places a ruling contains.
titles: an array of the options available to the jurors. NOTE: the sequence of the titles is important as they map directly to the rulings you get when the Arbitrator responds to your Arbitrable using the rule() function.
descriptions: the description of the rulingOption titles.
fileURI: The URI that leads to the primary document of the case, which is a natural language contract, policy, or primary document that is the basis of the dispute. See this section on the role of the primary document and how to write a good one.
evidenceDisplayInterfaceURI: The URI to a display interface that should be used to render the facts of a case in an iframe by the Arbitrator.
Here's an example of a MetaEvidence JSON:
Below you will find a diagram that shows how the elements in the MetaEvidence JSON get displayed on the Court and Dispute Resolver interfaces.
The evidenceDisplayInterfaceURI can be used to display dynamic information in an iframe on the court interface about each case, including the details of the disputants, images or any other related information. There are no hard limits to the amount of content that can be displayed here, though a rule of thumb is to keep this page under 360px in height to make it easily readable on the court interface.
When loading the iframe, the evidenceDisplayInterfaceURI will be called with a URL-encoded JSON query string as the payload, with the following keys to allow the page to display and retrieve content dynamically:
disputeID
chainID
arbitratorContractAddress
arbitratorJsonRpcUrl
arbitratorChainID
arbitrableContractAddress
arbitrableChainID
arbitrableJsonRpcUrl
jsonRpcUrl
Here is an example of the URL with query string used by the iframe on the Arbitrator interface:
Pro-tip: To avoid having to create a new MetaEvidence JSON and pin it to IPFS prior to every dispute, you can use just a static MetaEvidence JSON, and use a evidenceDisplayInterfaceURI that dynamically displays different information based on the query string.
It is also essential in many types of disputes that the participants have a chance to show their viewpoint and give reasons why they believe they are right. Therefore there needs to be a way for an Arbitrator to receive Evidence. The Evidence JSON file includes the following properties:
So now we have JSON files with our two types of evidence but we still need a way to link them to our smart contract so that our DApps can interact seamlessly. MetaEvidence and Evidence are submitted and looked up via smart contract event logs. The standard specifies some new events for your smart contracts. When an Evidence is submitted, an event is raised that includes a URI to the JSON file that the submitter can host anywhere they choose. This way we can leverage the immutability and availability of the blockchain to create a permanent log of submission that any interface can look up and use to access the Evidence JSON.\
In contentious disputes, it is crucial that Arbitrators can be sure that they receive accurate Evidence and MetaEvidence. For example, if MetaEvidence is tampered with, one of the participants can switch the labels on the ruling options, and an Arbitrator might send funds to the wrong party thinking they are voting the opposite way. To protect against Evidence or MetaEvidence being modified, a series of hashes are used. The JSON for both MetaEvidence and Evidence contains hash fields for things such as linked files. The standard also allows for the hash to be used as the name of the file, like the format IPFS uses, so that files hosted on distributed platforms that guarantee data integrity don’t require any extra work. The arbitrators can use these hashes that are provided when Evidence or MetaEvidence is submitted to verify that nothing has been changed.