Quick Start

Kleros arbitration can be integrated on either protocol version:

V1 uses the ERC-792 arbitration standard (IArbitrable / IArbitrator) on Ethereum Mainnet and Gnosis Chain. See ERC-792 and ERC-1497 for the full V1 standards.
V2 uses IArbitrableV2 / IArbitratorV2 on Arbitrum, with dispute templates and cross-chain support.

The steps below show both. Pick the version that matches the network you are deploying to. For contract addresses, see Deployment Addresses V2 and Deployment Addresses V1.

Installation

npm install @kleros/kleros-v2-contracts

yarn add @kleros/kleros-v2-contracts

# Foundry: install the npm package, then map the import path
npm install @kleros/kleros-v2-contracts
echo "@kleros/kleros-v2-contracts/=node_modules/@kleros/kleros-v2-contracts/" >> remappings.txt

Contract Addresses (Arbitrum One)

// Core contracts
address constant KLEROS_CORE = 0x991d2df165670b9cac3B022f4B68D65b664222ea; // proxy
address constant DISPUTE_KIT_CLASSIC = 0x70B464be85A547144C72485eBa2577E5D3A45421; // proxy

// For cross-chain disputes, see the Gateways reference: /reference/contracts/gateways

Always verify addresses against Deployment Addresses V2 and the official repository before deploying to production.

Minimal Integration

Step 1: Implement the arbitrable interface

V2 (IArbitrableV2)
V1 (ERC-792)

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "@kleros/kleros-v2-contracts/arbitration/interfaces/IArbitrableV2.sol";
import "@kleros/kleros-v2-contracts/arbitration/interfaces/IArbitratorV2.sol";

contract MyArbitrable is IArbitrableV2 {
    IArbitratorV2 public immutable arbitrator;
    
    mapping(uint256 => uint256) public externalIDtoLocalID;
    mapping(uint256 => bool) public resolved;
    
    constructor(IArbitratorV2 _arbitrator) {
        arbitrator = _arbitrator;
    }
    
    function createDispute(
        bytes calldata _extraData
    ) external payable returns (uint256 disputeID) {
        uint256 cost = arbitrator.arbitrationCost(_extraData);
        require(msg.value >= cost, "Insufficient fee");
        
        disputeID = arbitrator.createDispute{value: cost}(
            2,          // numberOfChoices (e.g., 2 for binary)
            _extraData  // court parameters
        );
        
        // Map arbitrator's ID to your local tracking
        externalIDtoLocalID[disputeID] = /* your local ID */;
        
        emit DisputeRequest(arbitrator, disputeID, /* params */);
    }
    
    function rule(uint256 _disputeID, uint256 _ruling) external override {
        require(msg.sender == address(arbitrator), "Only arbitrator");
        require(!resolved[_disputeID], "Already resolved");
        
        resolved[_disputeID] = true;
        
        // Execute your business logic based on _ruling
        // 0 = refused to rule, 1+ = actual ruling choices
        
        emit Ruling(arbitrator, _disputeID, _ruling);
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.7.0;

import "@kleros/erc-792/contracts/IArbitrable.sol";
import "@kleros/erc-792/contracts/IArbitrator.sol";
import "@kleros/erc-792/contracts/erc-1497/IEvidence.sol";

contract MyArbitrable is IArbitrable, IEvidence {
    IArbitrator public arbitrator;
    
    mapping(uint256 => bool) public resolved;
    
    constructor(IArbitrator _arbitrator) {
        arbitrator = _arbitrator;
    }
    
    function createDispute(
        bytes memory _extraData,
        string memory _metaEvidence
    ) public payable returns (uint256 disputeID) {
        uint256 cost = arbitrator.arbitrationCost(_extraData);
        require(msg.value >= cost, "Insufficient fee");
        
        // numberOfChoices (e.g., 2 for binary) + court params in _extraData
        disputeID = arbitrator.createDispute{value: cost}(2, _extraData);
        
        emit MetaEvidence(disputeID, _metaEvidence);
        emit Dispute(arbitrator, disputeID, disputeID, disputeID);
    }
    
    function rule(uint256 _disputeID, uint256 _ruling) external override {
        require(msg.sender == address(arbitrator), "Only arbitrator");
        require(!resolved[_disputeID], "Already resolved");
        
        resolved[_disputeID] = true;
        
        // Execute your business logic based on _ruling
        // 0 = refused to rule, 1+ = actual ruling choices
        
        emit Ruling(arbitrator, _disputeID, _ruling);
    }
}

Step 2: Encode Extra Data

The extraData parameter specifies which court and how many jurors:

function getExtraData(
    uint96 courtID,
    uint256 minJurors
) public pure returns (bytes memory) {
    return abi.encodePacked(courtID, minJurors);
}

// Example: General Court (ID 1) with 3 jurors
bytes memory extraData = getExtraData(1, 3);

Step 3: Get Arbitration Cost

function getArbitrationCost(bytes calldata extraData) external view returns (uint256) {
    return arbitrator.arbitrationCost(extraData);
}

Court IDs

Court	ID	Min Stake	Use Case
General	1	200 PNK	Default, broad disputes
Blockchain Technical	Higher	Smart contract disputes
Curation	Varies	Registry disputes

Start with General Court (ID: 1) for testing. Use minJurors = 3 for most cases.

Dispute Templates

Jurors need context. Create a template that describes the dispute:

{
  "title": "Payment Dispute: Order #1234",
  "description": "Buyer claims goods not delivered...",
  "question": "Should the escrowed funds be released to the seller?",
  "answers": [
    { "id": "0x1", "title": "Yes", "description": "Release to seller" },
    { "id": "0x2", "title": "No", "description": "Refund to buyer" }
  ]
}

Testing

Use Arbitrum Sepolia

Deploy to testnet first. Get Arbitrum Sepolia ETH from a public faucet such as the Arbitrum faucets list

Get Test PNK

Testnet PNK is available from the Kleros faucet

Create a Test Dispute

Call createDispute() with test ETH for fees

SDK (Optional)

For frontend integration, use the Kleros SDK (npm install @kleros/kleros-sdk):

import { getDispute } from '@kleros/kleros-sdk';

// Read a dispute's details, populated from its dispute template
const dispute = await getDispute({
  disputeId: 123n,
  coreSubgraph: '<Kleros Core subgraph URL>',
  dtrSubgraph: '<Dispute Template Registry subgraph URL>',
});

Subgraph URLs are listed in Subgraph Endpoints. Evidence is submitted on-chain through the EvidenceModule; see Deployment Addresses V2.

Next Steps

Architecture Deep Dive

Understand how KlerosCore, Dispute Kits, and Sortition Module work together

Getting Started

V2 Architecture

Arbitrable Apps

Products

Cross-chain

Examples

Subgraph & Data

AI Tools

Installation

Contract Addresses (Arbitrum One)

Minimal Integration

Step 1: Implement the arbitrable interface

Step 2: Encode Extra Data

Step 3: Get Arbitration Cost

Court IDs

Dispute Templates

Testing

SDK (Optional)

Next Steps

Architecture Deep Dive

​Installation

​Contract Addresses (Arbitrum One)

​Minimal Integration

​Step 1: Implement the arbitrable interface

​Step 2: Encode Extra Data

​Step 3: Get Arbitration Cost

​Court IDs

​Dispute Templates

​Testing

​SDK (Optional)

​Next Steps

Architecture Deep Dive

Installation

Contract Addresses (Arbitrum One)

Minimal Integration

Step 1: Implement the arbitrable interface

Step 2: Encode Extra Data

Step 3: Get Arbitration Cost

Court IDs

Dispute Templates

Testing

SDK (Optional)

Next Steps