1. Dispute resolution integration plan

Solution plan for integrating Kleros as an arbitrator to decide on disputes


Using Kleros Court to decide on disputes is the most direct way to use Kleros. The ways to use this are numerous, but here are a few of them:

A full list of Kleros's existing integrations and partnerships can be found here.

Integrating Kleros into your dispute decision process will always involve 5 main steps and they are outlined below.

To help you keep track of your integration process, click here to make a copy of our Dispute Resolution model integration plan!

To help you keep track of the process, click here to make a copy of our model integration plan!

Key integration steps

Following these 5 steps in sequence will ensure that your integration is secure and runs smoothly for both you and your users.

1. Determine the conditions for escalation and enforcement

An integration with Kleros implies that you have chosen for the jurisdiction of Kleros Court for the resolution of a dispute.

As with real-world courts, Kleros Court is only an arbitration service, and it is important to remember that our decentralized jury only takes care of the ruling on a dispute given certain facts/evidences and policy documents. Enforcement of the ruling is out of scope for Kleros, and needs to be carefully taken care of by your service/platform/dApp.

What this means in concrete terms is that you need to decide on and document the following before escalating a dispute to Kleros:

  • Escalation criteria: when your platform will allow an escalation of a dispute to Kleros

    • Example: escalation is only allowed after a first round of dispute resolution has taken place within your platform, and the disputed transaction above a certain transaction value.

  • Enforcement criteria: what criteria need to be fulfilled for your platform/service to commit to enforcing a ruling from Kleros

    • Example: enforcement is dependent on the agreement of DAO governance or approval committees, if the enforcement is governed by a 'multisig', of which Kleros Court represents only 1-of-n signers.

If a smart contract integration with Kleros Court is used (see Step 4 below), the escalation and enforcement criteria could be built into the logic of your 'Arbitrable' contract.

2. Write a good 'Dispute Policy'

The dispute policy is the primary document presented to the jurors to inform them on how to resolve a dispute. It is similar to a piece of real-world law referenced during cases to decide a dispute, but in this case only pertaining to your specific integration.

Jurors will use three main categories of information to decide on their vote:

  1. The dispute policy

  2. The evidence provided (which can potentially be submitted by anyone on the internet)

  3. If the above two are insufficient for deciding on the case, then the policies of the Court in question are considered.

Writing a good dispute policy is therefore crucial to the fair and speedy resolution of a case, as it sets the backdrop against which the pieces of evidence are considered.

Save time and avoid omissions by using our model policy here!

Refer to the policy writing guide here if you need help adjusting it to your use case.

3. Determine the Court parameters

Once the above has been done, the next step is to decide on

  1. The Court where you would want your cases to be arbitrated in

  2. The number of jurors you want to draw into the first round of arbitration.

Choosing the right court for your case ensures that it will be resolved in the quickest and most efficient manner. Do keep in mind the choices in this section directly affect the cost of arbitration; it is a function of the number of jurors drawn into the case, and the cost of involving an additional juror differs with each court.

For an overview of the courts available on Ethereum Mainnet and their parameters, please refer to the community-managed Klerosboard.

A guide on the recommendation parameters for different use cases will be made available soon. For now, please reach out to us at integrations@kleros.io for guidance.

4. Integrate with the Court

There are two ways to use Kleros Court for your dispute resolution:

A. Smart contract integration

The best way to integrate with Kleros is to invest in a smart contract integration with Kleros Court. While it takes work to write and audit an 'Arbitrable' smart contract (complying with the ERC-792 standard), it does allow for a trustless integration and can fully address user concerns of centralized control or censorship.

There are two ways to go about it:

  1. A fully ERC-792 compliant integration, in which the full integration guide for this technical integration can be found here:

    Smart contract integration with Kleros Court (Arbitrator)

  2. A greatly simplified variant of the ERC-792 integration using an 'arbitrable-proxy' contract, in which the evidence and appeal logic management and UI components are outsourced to Kleros-written smart contracts and frontends. All you need to do is for your pseudo-Arbitrable contact to call the createDispute function and poll for the ruling from the arbitrable-proxy afterwards.

B. A standalone 'Recognition-of-Jurisdiction' (RoJ) integrations

Sometimes there might be reasons why a full smart contract integration is not feasible for you (yet):

  • The case involves an off-chain dispute that cannot be trustlessly integrated with Kleros (e.g. off-chain video game disputes, real-world arbitration cases).

  • Kleros Court is not (yet) available on the chain/L2 you are on.

  • There are no resources to perform the full smart contract integration in the near term.

  • You prefer to test out the process with Kleros before investing development resources.

In such cases, you can start with a simple Recognition-of-Jurisdiction (aka RoJ) setup in which disputes are created 'standalone' on resolve.kleros.io, and your service/platform simply pledges (to your users) to enforce the ruling of Kleros.

While this is not a trustless integration method, it does allow you to introduce Kleros's rulings into your dispute resolution process very quickly, and allows you to test usage before investing in a full smart contract integration.

5. Communicate all the above to your users

Once all the above are done, it is time to communicate the involvement of Kleros in the dispute resolution processes of your platform. This is essential for the smooth operations of your dispute resolution process and reduces any potential confusion when disputes eventually arise. This includes but is not limited to:

  1. Ensuring that the dispute policy is publicly available and pinned using an immutable file storage system (e.g. IPFS)

  2. Publishing and communicating the escalation and enforcement criteria.

  3. Inform users on how to submit additional evidence and raise appeals (if applicable for your integration).

Once all the above are done, you are ready to go live with Kleros!

Reminder: To help you keep track of your integration process, click here to make a copy of our model integration plan!

Ready-made integrations

Kleros Court has integrations with various ready-made integrations, built either by ourselves or one of our channel partners.


For the usage of Kleros Court to decide if assets in escrow should be released, check out Kleros Escrow, which can be used standalone or integrated by calling its smart contracts.

(Optimistic) Oracle solutions

Kleros has a close integration with Reality.eth (formerly Realitio), acting as an arbitrator to rectify oracle results in case the results are contested. Check out the full details in the page here: How to use Reality.eth + Kleros as an oracle

Securing Snapshot votes

Gnosis's Zodiac Reality Module makes use of the Reality+Kleros integration mentioned above to securely translate Snapshot voting results into on-chain transactions.

Integration tools

If you are performing a smart contract integration, you can use the centralized arbitrator below to test your integration:

Centralized Arbitrator

If you would like to use the existing escrow smart contracts of Kleros behind escrow.kleros.io, you can also make use of the following tools.

Escrow SDK

Escrow React

Last updated