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.

court.createDispute(uint256, bytes) -> uint256


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

    '{"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

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.

Last updated