Using disputes directly
Describes the API available to a contract creating and managing disputes.
When creating a dispute the contract essentially creates an asynchronous query that asks the subjective oracle a question.
Every dispute has many steps which need to be called either directly from the subject (creator of dispute) or can be called anyone. Methods are described by their parameters, return values, emitted events and which contract they are located on. Note that not all emitted events are described.
court references the main AragonCourt instance, often referred to as the arbitrator.1. Initializing a dispute
2. Submitting Evidence
3. Closing the evidence period
4. Getting the ruling
uint256 _possibleRulings: The number of ways jurors can rule on your dispute. Minimum is 2, maximum is currently also 2 but can be changed via the court's config. There's an additional, third possible outcome beyond the 2 which is theOUTCOME_REFUSEDoutcome.bytes _metadata: This is data used by the jurors to understand what is being disputed. This data is not directly stored in any contract, it is however securely linked to the blockchain since it's emitted in aNewDisputeevent. The way metadata is interpreted and displayed in the main Celeste dashboard will be described below.
uint256 disputeId: The method returns a unique ID which can later be used to identify the specific dispute. It will likely be necessary for the contract, especially if it allows for the creation and management of multiple disputes
NewDispute(uint256 indexed disputeId, IArbitrable indexed subject, uint64 indexed draftTermId, uint64 jurorsNumber, bytes metadata)Emitted from the DisputeManager contract. Event parameters:IArbitrable indexed subject: address of the original caller of thecreateDisputemethod (not tx.origin)uint64 indexed draftTermId: term ID where the drafting of jurors can begin for the disputeuint64 jurorsNumber: number of jurors which will be assigned to the dispute in its initial roundbytes metadata: the metadata given to the court whencreateDisputewas originally called. For more information on how to correctly format data for the Celeste dashboard refer to the "Metadata format" section below.
VotingCreated(uint256 indexed voteId, uint8 possibleOutcomes): Emitted from the CRVoting contract. Event parameters:uint256 indexed voteId: unique ID to identify the voting for the round of the dispute. While separate from thedisputeIdthey are linked since thevoteIdis computed from thedisputeIdand theroundIdmore in the Voting module sectionuint8 possibleOutcomes: possible outcomes (not including theREFUSED_OUTCOMEoutcome). So if the event holds the value 2 there are actually 3 possible outcomes.
Beside emitting events a fee is also pulled from the caller in order to pay for the dispute. The recipient to approve, token and amount can be queried using the
getDisputeFees() method on the AragonCourt contract. The fee is pulled via transferFrom as described by the ERC20 standard.The
bytes _metadata parameter of the method should be a JSON string with specific fields. Only two fields needs to directly be included in the JSON string on-chain, the title and metadata fields. Other fields which do not vary between disputes should be put in a JSON document stored on IPFS. The IPFS hash should then be put as the value of the metadata sub-field. Overall the following fields need to be available either on-chain directly as part of the JSON input or linked via an IPFS document:- title (required on-chain): Displayed as the subtitle when in
/disputesoverview but displayed as the title when the specific dispute is opened. - metadata (special field): IPFS CID of JSON document containing fields that are listed below but were not included on-chain.
- disputedActionText: The description of the dispute. If it's a URL a link will be rendered with the text "Read more"
- disputedActionURL: URL to the action being disputed, this could be a link to your dApp frontend with more information on what's being disputed for example.
- disputedActionRadspec: Description displayed on the Celeste dashboard for the
disputedActionURL - agreementTitle: Title of the agreement used to settle dispute
- agreementText: Content of the agreement as text. This will be read and interpreted by the jurors in combination with the submitted evidence to come to a resolution.
- organization: Organization running or maintaining the platform on which the dispute is based on.
- plaintiff: Party creating the dispute.
- defendant: Party being accused of violating agreement
Example for metadata:
{
"title": "Example DAO's agreement violated",
"plaintiff": "0xcB638378017Fb332Ec15850997CFA860f197Fb52",
"defendant": "0x8F7CaE8aE359CAe732A3C177590d36bAdF7f5980",
"metadata": "ipfs:QmW9GRmmTspu5FCgxYEn6Ybt7HjqDn1UJqhAogNmhjRtc5"
}
Direct Solidity example:
aragonCourt.createDispute(
2,
'{"title":"Example DAO\'s agreement violated","plaintiff":"0xcB638378017Fb332Ec15850997CFA860f197Fb52","defendant":"0x8F7CaE8aE359CAe732A3C177590d36bAdF7f5980","metadata":"ipfs:QmW9GRmmTspu5FCgxYEn6Ybt7HjqDn1UJqhAogNmhjRtc5"}'
)
Once the
createDispute method has successfully been run a dispute has been created. One can now submit evidence for the life of the dispute, further documented in the next tab: 2. Submitting evidence. Dispute resolution will also continue even if no evidence is submitted. If no evidence is submitted the next step is: 4. Drafting jurorsuint256 _disputeId: The dispute ID for which evidence is to be submittedaddress _submitter: The address to be referenced as the submitter of the evidence in the emitted eventbytes calldata _evidence: The evidence that the jurors are to evaluate in relation to the case. For more information on how to correctly format data for the Celeste dashboard refer to the "Evidence format" section below.
This method does not return anything.
EvidenceSubmitted(uint256 indexed disputeId, address indexed submitter, bytes evidence)Emitted from the DisputeManager module.
Reverts if the dispute referenced by the dispute ID does not exist or if the caller is not the creator of the dispute (subject).
Currently only plain text is supported. This means that the
bytes _evidence argument should simply by a UTF-8 encoded string. As an example: court.submitEvidence(disputeId, msg.sender, "promised A but delivered B");The next steps of a dispute are reached independently of evidence submission.
uint256 _disputeId: ID of dispute.
This method does not return anything.
EvidencePeriodClosed(uint256 indexed disputeId, uint64 indexed termId): Emitted from the DisputeManager contract. Event parameters:uint64 indexed termId: term ID of the term in which the period is being closed
Reverts if the dispute referenced by the dispute ID does not exist or if the caller is not the creator of the dispute (subject). Also reverts if drafting is already possible in the following period.
Despite its name after this method is called it's still possible to call
submitEvidence. However if successfully run any further waiting terms before drafting will be skipped, this directly allows drafting in the following term.After this method is called or if the evidence period expires on its own jurors can be drafted.
uint256 _disputeId: ID of dispute.
address subject: Original creator of disputeuint256 ruling: Ruling of the court, possible rulings: (2) if court refused to rule due to lack of evidence or ambiguous terms. At the time of this writing there's no precedence as when a court would vote for this option. (3) if court ruled in favor of dispute or against the action that is being disputed. (4) if court rules for action that is being disputed
RulingComputed(uint256 indexed disputeId, uint8 indexed ruling): Emitted from the DisputeManager contract. Only emitted the first time when the ruling is determined. Consequent calls ofrulefor the same dispute will not emit this event.
Reverts if the dispute referenced by the dispute ID does not exist or if no final ruling is available. A final ruling will only be available once jurors have been drafted, their commit & reveal periods expire and the appeal period expires. If intermediary votes are appealed a final ruling will only be available once they're complete.
Either returns the already stored ruling or stores and returns a newly available ruling.
To ensure that a final ruling is actually available, several intermediary steps between (3. & 4.) are required. These include drafting jurors, appealing intermediate votes, confirming appeals and redrafting. Since these require external method calls and are not directly necessary to create and query the response to a dispute they are documented in the following section.
Last modified 1yr ago