Integration Guide - Kleros Documentation

How Kleros Arbitration Works with Reality.eth

Before integrating, understand the escalation flow:

A question is asked on Reality.eth and answerers post bonds.
Each new answer must double the previous bond (e.g. 0.01 ETH → 0.02 → 0.04 ETH). This economically incentivizes correct answers.
If the question is not challenged within the timeout period (typically 24 hours), the last answer finalizes.
If a party disagrees, they pay the arbitration fee to escalate the question to Kleros. This costs more than a bond, so it is a last resort for high-stakes questions.
The Kleros Arbitrator Proxy creates a KlerosCore dispute. When Kleros rules, Reality.eth is notified and the answer is finalized.

Key Timing Parameter: `feeTimeout`

The RealityV2 Kleros integration contract has a feeTimeout parameter (set to 600 seconds / 10 minutes in the reference deployment). This is the time within which the other party must also pay the arbitration fee after it is requested. If they don’t pay within feeTimeout, the requester wins by default.

uint32 public constant FEE_TIMEOUT = 600; // 10 minutes

Inform your users about this window - if they request arbitration, the other party has only 10 minutes to match the fee.

The disputeTemplateMappings field in the Reality V2 deployment script is currently marked TODO in the reference implementation. This means the dispute template shown to Kleros jurors for Reality questions does not yet have dynamic data mappings (it shows static text). Check the kleros/reality-v2 repository for the latest status before relying on dynamic template population.

Integration Options

There are two ways to integrate with the Reality.eth + Kleros oracle.

Off-chain (Quick Testing)

Use the Reality.eth web interface to submit questions and retrieve answers manually. Best for:

Testing the system before full integration
Learning how question lifecycles work
One-off questions that don’t need automation

On-chain (Production)

Have your smart contract call Reality.eth directly to ask questions, read answers, and react to oracle responses programmatically. This is the recommended approach for production DApps. For the on-chain path, you’ll want to be familiar with the Reality.eth interface and the reality-eth-monorepo for contract addresses and ABIs.

Smart Contract Integration

Step 1: Ask a Question

import {IRealityETH} from "./interfaces/IRealityETH.sol";

contract OracleConsumer {
    IRealityETH public immutable realityETH;
    // Kleros Arbitrator Proxy General Court on Mainnet
    address public constant ARBITRATOR = 0x728cba71a3723caab33ea416cb46e2cc9215a596;
    uint32 public constant TIMEOUT = 86400; // 24 hours

    constructor(address _realityETH) {
        realityETH = IRealityETH(_realityETH);
    }

    function askQuestion(string calldata _question) external payable returns (bytes32) {
        return realityETH.askQuestion{value: msg.value}(
            0,              // template: bool (yes/no)
            _question,      // e.g. "Did team X win?␟sports␟en"
            ARBITRATOR,     // Kleros arbitrator proxy
            TIMEOUT,        // answer timeout
            0,              // opens immediately
            0               // nonce
        );
    }
}

Any ETH sent with askQuestion becomes the question reward, incentivizing answerers.

Question Parameters

templateID - 0 for bool, 1 for uint, 2 for single-select, 3 for multiple-select, 4 for datetime, 5 for hash.
question - Parameters separated by the ␟ (U+241F) delimiter, formatted to match the template. Examples:
- Bool: "Did event X happen?␟category␟en"
- Uint: "What was the price of ETH on April 16, 2025?␟crypto␟en"
- Single-select: "Which team won?␟\"Lakers\",\"Celtics\",\"Bucks\"␟sports␟en"
arbitrator - Kleros Arbitrator Proxy address. See Smart Contracts for available proxies.
timeout - Seconds before an unchallenged answer finalizes. Typically 86400 (24 hours). The contract enforces a maximum of 365 days.
openingTimestamp - Earliest time answers can be submitted. Set to 0 for immediate.
nonce - Differentiator for identical questions with the same parameters. Use 0 if you don’t need to ask the same question more than once.

Step 2: Read the Finalized Answer

function getAnswer(bytes32 _questionID) external view returns (bytes32) {
    require(realityETH.isFinalized(_questionID), "Not finalized");
    return realityETH.resultFor(_questionID);
}

function getAnswerAsBool(bytes32 _questionID) external view returns (bool) {
    bytes32 answer = realityETH.resultFor(_questionID);
    // 0x01 = Yes, 0x00 = No
    return answer == bytes32(uint256(1));
}

resultFor() reverts if the question is not yet finalized. Always check isFinalized() first, or use a callback pattern. For full result decoding by template type and how to handle special values like INVALID and ANSWERED_TOO_EARLY, see Smart Contracts → Result Interpretation.

Step 3: Handle the Callback (Optional)

For automated execution, use Reality.eth’s callback mechanism:

function resultReady(bytes32 _questionID) external {
    require(msg.sender == address(realityETH), "Only Reality.eth");
    bytes32 answer = realityETH.resultFor(_questionID);
    // Execute logic based on the answer
}

Choosing an Arbitrator Proxy

Each Kleros Arbitrator Proxy is configured with:

Parameter	Description
Subcourt	Which Kleros court handles disputes
Number of jurors	Initial juror count for first round
Arbitration fee	Cost to escalate a question to Kleros

Use an existing proxy from the Smart Contracts page, or contact integrations@kleros.io to deploy one configured for your use case. For applications that span chains (question on Polygon, arbitration on Ethereum, for example), use a cross-chain proxy. To check the current arbitration fee:

uint256 fee = realityETH.getArbitrator(_questionID).getDisputeFee(_questionID);

Evidence Submission

When a Reality.eth question goes to arbitration, evidence helps jurors make informed decisions. Submit evidence through the Kleros Arbitrator Proxy, not through Reality.eth.

Evidence Timeline

Question posted on Reality.eth
Answer phase - users submit answers with bonds
Arbitration requested - someone pays the arbitration fee
Evidence period opens (typically 3-7 days, varies by court configuration)
Voting phase - Kleros jurors review evidence and vote
Final ruling reported back to Reality.eth

Submitting Evidence from a Contract

interface IKlerosArbitratorProxy {
    function submitEvidence(
        uint256 _questionID,
        string calldata _evidenceURI
    ) external;
}

contract MyDApp {
    IKlerosArbitratorProxy public arbitratorProxy;

    constructor(address _arbitratorProxyAddress) {
        arbitratorProxy = IKlerosArbitratorProxy(_arbitratorProxyAddress);
    }

    function submitEvidenceForQuestion(
        bytes32 _questionID,
        string calldata _evidenceURI
    ) external {
        arbitratorProxy.submitEvidence(uint256(_questionID), _evidenceURI);
    }
}

Submitting Evidence Directly

You can also call the proxy directly:

arbitratorProxy.submitEvidence(
    uint256(questionID),
    "/ipfs/QmYourEvidenceHash"
);

Evidence Format

Evidence JSON follows the ERC-1497 standard. Host the JSON on IPFS (preferred) or any publicly accessible URL.

{
  "name": "Evidence Supporting Yes",
  "description": "Official S&P website showing closing price of 5,127.43 on April 16, 2025",
  "fileURI": "/ipfs/QmScreenshotHash",
  "fileHash": "QmScreenshotHash",
  "fileTypeExtension": "png"
}

Evidence Best Practices

IPFS first - /ipfs/QmHash or ipfs://QmHash is preferred for permanence. Web URLs work but rely on host availability.
Both sides should submit - supporters of each answer should submit their own evidence. Jurors weigh both.
Quality over quantity - clear, authoritative sources beat numerous weak ones.
Submit early - anyone can submit during the evidence period, but late submissions risk being missed.
Reference the underlying claim - each evidence file should clearly map to the answer it supports.

Monitoring Evidence Submissions

Watch for these events on the proxy contract:

// Emitted when arbitration is created
event Dispute(
    IArbitrator indexed _arbitrator,
    uint256 indexed _disputeID,
    uint256 _metaEvidenceID,
    uint256 _evidenceGroupID
);

// Emitted on each evidence submission
event Evidence(
    IArbitrator indexed _arbitrator,
    uint256 indexed _evidenceGroupID,
    address indexed _party,
    string _evidence
);

Fees and Payments

The Reality.eth + Kleros system has five fee types. Each plays a specific role in the incentive structure.

Fee	Set By	Paid By	Paid To
Question Reward	Asker	Asker	Highest-bonded correct answerer*
Answer Bond	Answerer	Answerer	Returned if correct, otherwise to the next correct answerer
Takeover Fee	Previous bond	Subsequent answerer	Previous answerer (deducted from rewards)
Arbitration Fee	Arbitrator	Anyone requesting	Arbitrator
Claim Fee (2.5%)	System	Claimer	Burned (deducted from claimed amount, Reality.eth v2.1+)

*When settled by arbitration, the arbitrator specifies who receives the reward.

Question Reward

Set by sending ETH (or tokens via askQuestionERC20) when calling askQuestion()
Paid to whoever provides the final accepted answer, minus any arbitrator fee
Higher rewards typically result in faster and more accurate answers

Answer Bond

Backs the answerer’s claim that their answer is correct
Must be at least double the previous bond if there was a prior answer
Returned if the answer is correct
Paid to the next correct answerer if the original answer is overturned

Takeover Fee

Compensates the previous answerer when someone takes over a correct answer
Equal to the bond supplied by the previous person who gave that answer
Deducted from rewards that would otherwise go to the new answerer

Arbitration Fee

Paid to the arbitrator when a party escalates the question
Set by the arbitrator (check via realityETH.getArbitrator(_qid).getDisputeFee(_qid))
Usually paid by an answerer whose answer was replaced

Claim Fee

Active from Reality.eth v2.1 onwards
2.5% of claimed bonds (excluding the final bond) is burned

Custom Primary Document for Arbitration

Most DApp integrations work fine with the standard Question Resolution Policy. In some cases, you may need a custom primary document tailored to your application.

When You Need a Custom Document

Your DApp has specific rules for how disputes should be judged
Resolving disputes requires specialized knowledge or context
You need a dedicated Kleros court for your application’s disputes
The interpretation of answers in your domain differs from standard interpretations

How the Process Works

Initial assessment - the Kleros team reviews your use case to confirm a custom document is necessary
Document drafting - you work with Kleros to create a document that:
- Explains your application’s context to jurors
- Provides guidance on evaluating evidence
- Defines specialized terminology
- Establishes clear criteria for determining correct answers
Deployment - Kleros deploys a dedicated arbitrator proxy with your primary document embedded as part of the proxy’s metaevidence
Usage - when disputes go to arbitration, jurors apply your guidelines

Real-World Example: Seer Prediction Markets

Seer needed a custom resolution policy because their prediction markets have specific rules for handling complex outcomes, edge cases like delayed events, and explicit authoritative information sources. If your application might need this level of customization, contact integrations@kleros.io.

DAO Governance Integration

The Reality.eth + Kleros oracle powers the Zodiac Reality Module for DAO governance. This module translates off-chain Snapshot votes into on-chain transactions through Reality.eth’s verification:

A Snapshot proposal passes with a batch of transactions
The SafeSnap plugin posts the proposal as a Reality.eth question
If the answer (“Is this proposal valid?”) goes unchallenged, the transactions execute through the Gnosis Safe
If challenged, Kleros Court arbitrates

See the DAO Governance example for implementation details.

Reality.eth Deployments

Reality.eth contracts are deployed across multiple chains. Reference the correct contract address for your target chain:

Chain	Repository Path
Ethereum Mainnet	`chains/deployments/1/`
Gnosis Chain	`chains/deployments/100/`
Arbitrum One	`chains/deployments/42161/`
Polygon	`chains/deployments/137/`

Full deployment data: Reality.eth monorepo.

Production Integrations

The Reality.eth + Kleros oracle is used in production by:

Prediction Markets - Seer, Polkamarkets/Foreland, and Omen use it to verify real-world event outcomes
Optimistic Governance - the Zodiac SafeSnap module uses it for secure DAO proposal execution
Content Moderation - Moderate / Susie bot uses it for decentralized content policy enforcement

Testing

For local development, deploy Reality.eth and a mock arbitrator on a testnet:

# Clone the Reality.eth monorepo
git clone https://github.com/RealityETH/reality-eth-monorepo.git
cd reality-eth-monorepo/packages/contracts

# Deploy to a local network or testnet
npx hardhat deploy --network <your-network>

For integration testing with Kleros Court V2, use the Arbitrum Sepolia testnet where Kleros V2 contracts are deployed. For V1 Court testing, use Sepolia with the General Court proxy at 0x05b942faecfb3924970e3a28e0f230910cedff45.

Common Questions

Does my DApp need to call the arbitrator proxy directly? No. Your DApp only needs to interact with Reality.eth for the standard question/answer flow. The proxy is invoked automatically when arbitration is requested. You only need to call the proxy directly to submit evidence during an active arbitration. What happens if there’s a dispute? Reality.eth and Kleros handle the dispute flow through the arbitrator proxy. Your DApp doesn’t need any special logic - once the dispute resolves, resultFor() returns the arbitrated answer. How do I write a clear question? Be specific, include resolution criteria, and specify a trusted information source. Example: “Did the S&P 500 close above 5,000 on April 10, 2025, according to the official S&P website?” Can I handle the full flow inside my DApp without using the Reality.eth frontend? Yes. You can implement everything from your DApp: ask questions, submit answers, request arbitration, and submit evidence.

Need Help?

Contact the Kleros team at integrations@kleros.io for:

Custom arbitrator proxy deployments
Help with Reality.eth integration
Assistance with complex use cases or custom primary documents

​How Kleros Arbitration Works with Reality.eth

​Key Timing Parameter: feeTimeout

​Integration Options

​Off-chain (Quick Testing)

​On-chain (Production)

​Smart Contract Integration

​Step 1: Ask a Question

​Question Parameters

​Step 2: Read the Finalized Answer

​Step 3: Handle the Callback (Optional)

​Choosing an Arbitrator Proxy

​Evidence Submission

​Evidence Timeline

​Submitting Evidence from a Contract

​Submitting Evidence Directly

​Evidence Format

​Evidence Best Practices

​Monitoring Evidence Submissions

​Fees and Payments

​Question Reward

​Answer Bond

​Takeover Fee

​Arbitration Fee

​Claim Fee

​Custom Primary Document for Arbitration

​When You Need a Custom Document

​How the Process Works

​Real-World Example: Seer Prediction Markets

​DAO Governance Integration

​Reality.eth Deployments

​Production Integrations

​Testing

​Common Questions

​Need Help?

How Kleros Arbitration Works with Reality.eth

Key Timing Parameter: `feeTimeout`

Integration Options

Off-chain (Quick Testing)

On-chain (Production)

Smart Contract Integration

Step 1: Ask a Question

Question Parameters

Step 2: Read the Finalized Answer

Step 3: Handle the Callback (Optional)

Choosing an Arbitrator Proxy

Evidence Submission

Evidence Timeline

Submitting Evidence from a Contract

Submitting Evidence Directly

Evidence Format

Evidence Best Practices

Monitoring Evidence Submissions

Fees and Payments

Question Reward

Answer Bond

Takeover Fee

Arbitration Fee

Claim Fee

Custom Primary Document for Arbitration

When You Need a Custom Document

How the Process Works

Real-World Example: Seer Prediction Markets

DAO Governance Integration

Reality.eth Deployments

Production Integrations

Testing

Common Questions

Need Help?