Using disputes directly

Describes the API available to a contract creating and managing disputes.

Creating and managing a dispute

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

court.createDispute(uint256, bytes) -> uint256

Parameters:

• 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 the OUTCOME_REFUSED outcome.

• 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 a NewDispute event. The way metadata is interpreted and displayed in the main Celeste dashboard will be described below.

Return values:

• 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

Emitted events:

• 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 the createDispute method (not tx.origin)

  • uint64 indexed draftTermId: term ID where the drafting of jurors can begin for the dispute

  • uint64 jurorsNumber: number of jurors which will be assigned to the dispute in its initial round

  • bytes metadata: the metadata given to the court when createDispute was 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 the disputeId they are linked since the voteId is computed from the disputeId and the roundId more in the Voting module section

  • uint8 possibleOutcomes: possible outcomes (not including the REFUSED_OUTCOME outcome). So if the event holds the value 2 there are actually 3 possible outcomes.

General function

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.

Metadata format

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 /disputes overview 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"}'
)

Next steps

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 jurors

2. Submitting Evidence

court.submitEvidence(uint256, address, bytes) -> ()

Parameters:

• uint256 _disputeId: The dispute ID for which evidence is to be submitted

• address _submitter: The address to be referenced as the submitter of the evidence in the emitted event

• bytes 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.

Return values:

This method does not return anything.

Emitted events:

• EvidenceSubmitted(uint256 indexed disputeId, address indexed submitter, bytes evidence)Emitted from the DisputeManager module.

General function

Reverts if the dispute referenced by the dispute ID does not exist or if the caller is not the creator of the dispute (subject).

Evidence format

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");

Next steps

The next steps of a dispute are reached independently of evidence submission.

3. Closing the evidence period

court.closeEvidencePeriod(uint256) -> ()

Parameters:

• uint256 _disputeId: ID of dispute.

Return values:

This method does not return anything.

Emitted events:

• 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

General function

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.

Next steps

After this method is called or if the evidence period expires on its own jurors can be drafted.

4. Getting the ruling

court.rule(uint256) -> (address, uint256)

Parameters:

• uint256 _disputeId: ID of dispute.

Return values:

• address subject: Original creator of dispute

• uint256 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

Emitted events:

• RulingComputed(uint256 indexed disputeId, uint8 indexed ruling): Emitted from the DisputeManager contract. Only emitted the first time when the ruling is determined. Consequent calls of rule for the same dispute will not emit this event.

General function

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.

Ensuring a dispute settles

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.