3. Kleros Oracle integration

A comprehensive guide for integrating Reality.eth + Kleros oracle system to access reliable real-world data through decentralized verification and arbitration.

Introduction

Want your DApp to access reliable real-world information on-chain? The Reality.eth + Kleros oracle system provides a decentralized solution for subjective data verification through economic incentives and crowdsourced arbitration.

This system combines two key protocols:

• Reality.eth - The underlying oracle and bond escalation mechanism

• Kleros - The dispute resolution protocol

How It Works

The integration consists of two main parts:

1. Your DApp

   • Your DApp only needs to interact with the Reality.eth contract directly

   • You submit questions with the appropriate arbitrator address

   • You retrieve final answers once they're available

   • No need to implement any arbitration logic in your code

2. Oracle System

   • The oracle system handles everything else behind the scenes:

   • Reality.eth: Manages questions, answers, and economic incentives through bond escalation

   • Arbitration Mechanism: When disputes arise, the Kleros Arbitrator Proxy creates a case in Kleros Court where jurors resolve the dispute, then reports the result back to Reality.eth

This separation means your integration is simple - you only need to know how to ask questions and retrieve answers from Reality.eth.

Integration Options

You have two ways to integrate with the Reality.eth + Kleros oracle:

1. Offchain Integration (Quick Testing)

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

• Testing the system before full integration, learning how the system works

• One-off questions that don't require automation

2. Onchain Integration (Production)

Implement direct smart contract interaction with Reality.eth to programmatically:

• Submit questions from your DApp

• Retrieve verified answers

• React to oracle responses

For this approach, you'll need to thoroughly understand the Reality.eth interface. Check out the official Reality.eth documentation and Reality github

Resolution Flow

The Reality.eth + Kleros system follows a push/pull model:

1. Push: Your DApp submits questions to Reality.eth

2. Pull: Your DApp later retrieves the verified answers

The question can be resolved through two paths:

Happy Path: Consensus Resolution

1. Someone submits an answer with a bond

2. No one challenges within the timeout period

3. The answer is finalized automatically

4. Your DApp can retrieve the result

Unhappy Path: Arbitration Resolution

1. Someone submits an answer with a bond

2. Another user challenges with a higher bond

3. Bond escalation may continue until someone requests arbitration

4. The question gets frozen on Reality.eth

5. A dispute is created in Kleros Court

6. Jurors vote on the correct answer

7. The final ruling is submitted to Reality.eth

8. Your DApp can retrieve the arbitrated result

Important: All interactions occur through the Reality.eth interface - you don't need to build separate interfaces for these different resolution paths.

Quick Start Guide

Step 1: Configure Your DApp

Your DApp only needs to interact with Reality.eth directly. Import the interface:

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

import "./IRealityETH.sol";

contract MyDApp {
    IRealityETH public realityETH;
    
    constructor(address _realityETHAddress) {
        realityETH = IRealityETH(_realityETHAddress);
    }
    
    // The rest of your contract...
}

You can find the Reality.eth contract addresses under:

https://github.com/RealityETH/reality-eth-monorepo/tree/main/packages/contracts/chains/deployments

Step 2: Ask Questions

To submit a question to Reality.eth:

function askQuestion(
    uint256 templateID,
    string calldata question,
    address arbitrator,
    uint32 timeout,
    uint32 openingTimestamp,
    uint256 nonce
) external payable returns (bytes32 questionID) {
    // Choose the appropriate Kleros arbitrator proxy address for your network
    address arbitrator = 0xFf32eff53459485074b4Db14633252C9dcA3791A;// Example: Mainnet General Court
    
    // Any ETH sent with this transaction becomes the question reward
    return realityETH.askQuestion{value: msg.value}(
        templateID,
        question,
        arbitrator,
        timeout,
        openingTimestamp,
        nonce
    );
}

Parameter Explanations:

• templateID: The question format template - commonly used values:

  • 0: Boolean (Yes/No) questions

  • 1: Numerical (uint) answers

  • 2: Single-select multiple choice

  • 3: Multiple-select multiple choice

  • 4: Datetime responses

  • 5: Hash type (new in v3.2)

• question: The actual question with parameters matching the template format, separated by the unicode delimiter "␟":

  • Template 0 (bool): "Did event X happen?␟category␟en"

  • Template 1 (uint): "What was the price of ETH on April 16, 2025?␟crypto␟en"

  • Template 2 (single-select): "Which team won the 2024 NBA Finals?␟"Lakers","Celtics","Bucks","Other"␟sports␟en"

• arbitrator: arbitrator: The address of the Kleros Arbitrator Proxy that will handle disputes.

• timeout: Time in seconds the question will have after receiving an answer before it's automatically finalized. Typically around 1 day (86400 seconds). The contract enforces a maximum value of 365 days (31,536,000 seconds).

• openingTimestamp: Unix timestamp defining the earliest time when answers can be submitted. Set to 0 if you want the question to be answerable immediately.

• nonce: A user-supplied number to differentiate between identical questions with the same settings. Use 0 if you don't plan to ask the same question with identical parameters more than once.

Example

// Ask with a 0.1 ETH reward
bytes32 questionID = realityETH.askQuestion{value: 0.1 ether}(
    0, // Boolean template
    "Did the S&P 500 close above 5000 on April 16, 2025?␟finance␟en",
    arbitratorAddress,
    86400, // 24 hour timeout
    0, // Answerable immediately
    0 // Default nonce
);

Official Arbitrator Proxy Addresses

The system supports same chani and cross-chain deployments (question on one chain, arbitration on another).

• Same-chain oracle and arbitration:

  • Ethereum Mainnet (General Court): 0xFf32eff53459485074b4Db14633252C9dcA3791A

  • Ethereum Mainnet (DAO Governance/Technical Court): 0xf72cfd1b34a91a64f9a98537fe63fbab7530adca

  • Sepolia Testnet: 0x05b942faecfb3924970e3a28e0f230910cedff45

• Cross-chain oracle and arbitration:

  • Question and arbitration on different chains, aka cross-chain proxies: list of deployments here.

Step 3: Retrieve Answers

Once your question has been answered (either through consensus or arbitration), retrieve the answer:

function getAnswer(bytes32 questionID) external view returns (bytes32) {
    // This will revert if the question is not finalized
    return realityETH.resultFor(questionID);
}

// For safer access that won't revert:
function isQuestionFinalized(bytes32 questionID) external view returns (bool) {
    try realityETH.resultFor(questionID) returns (bytes32) {
        return true;
    } catch {
        return false;
    }

Technical Details

Reality.eth + Kleros Arbitrator Proxy

The Kleros Arbitrator Proxy:

• Acts as an arbitrator for Reality.eth

• Creates disputes in Kleros Court when arbitration is requested

• Reports Kleros rulings back to Reality.eth in the proper format

Kleros Court

The Kleros Court:

• Adjudicates on disputes by drawing jurors

• Manages the crowdfunded appeals process

• Publishes final rulings that are transmitted back to Reality.eth

Working with the Kleros Oracle System

Question Types and Templates

The Reality.eth + Kleros oracle supports various question types:

Type	Description	Example
Bool	Yes/No questions	Did event X happen?
Uint	Numerical answers	How many votes did candidate Y receive?
Single-select	Multiple choice with one answer	Which team won the championship?
Multiple-select	Multiple choice with multiple possible answers	Which states voted Democrat?
Datetime	Date/time responses	When did the event occur?
Hash	Hash-based identification (new in v3.2)	Does hash X correspond to document Y?

Questions use templates to reduce gas costs. Built-in templates include:

[ ]

0: {"title": "%s", "type": "bool", "category": "%s", "lang": "%s"}
1: {"title": "%s", "type": "uint", "decimals": 18, "category": "%s", "lang": "%s"}
2: {"title": "%s", "type": "single-select", "outcomes": [%s], "category": "%s", "lang": "%s"}
3: {"title": "%s", "type": "multiple-select", "outcomes": [%s], "category": "%s", "lang": "%s"}
4: {"title": "%s", "type": "datetime", "category": "%s", "lang": "%s"}

You can create custom templates with createTemplate() or use the Reality.eth Template Generator.

Interpreting Results

Responses are returned as bytes32. Depending on the question type:

• Bool: 1 (Yes), 0 (No), or 0xff...ff (Invalid)

• Uint: The number as bytes32, divided by decimals if specified

• Single-select: Zero-indexed selection (0 for first option, 1 for second, etc.)

• Multiple-select: One-indexed with bitwise addition (1 for first, 2 for second, 1+2=3 for both)

• Datetime: Unix timestamp (seconds since 1970)

• Hash: The submitted hash that matches the criteria

Special values you may encounter:

• 0xff...ff (all f's): Invalid answer

• 0xff...fe (all f's except last digit): "Answered too early" - when a question needs more time

Fees and Payments

The Reality.eth + Kleros system involves several types of fees and payments, each with a specific purpose in the incentive mechanism:

Fee type	Set by	Paid by	Deductions	Paid to
Question Reward	Asker	Asker	None	Highest-bonded correct answerer*
Answer Bond	Answerer	Answerer	None	Returned if correct, or to next correct answerer if incorrect
Takeover Fee	Previous answerer	Subsequent answerer	From answer rewards	Previous answerer
Arbitration Fee	Arbitrator	Anyone requesting arbitration	None	Arbitrator
Claim Fee	System (2.5%)	Claimer	From claimed amount	Burned

*Except when settled by arbitration

Question Reward

• Set by sending ETH when calling askQuestion()

• Any ETH or tokens provided with the askQuestion or askQuestionERC20 call will be used as a question reward, minus any fee the specified arbitrator requires when a new question is asked

• Incentivizes correct answers

• Paid to whoever provides the final accepted answer

• If decided by arbitration, the arbitrator specifies who receives the reward

• Higher rewards typically result in faster and more accurate answers

Answer Bond

• Backs the answerer's claim that their answer is correct

• Set by the answerer, but must be at least twice the previous bond if there was a prior answer

• Returned if the answer is correct

• If incorrect, paid to the next answerer who supplies the correct answer

Answer Takeover Fee

• Compensates previous answerers when someone takes over a correct answer

• Equal to the bond supplied by the last person who gave that answer

• Paid to the last person who gave that answer

• Deducted from payments that would otherwise be awarded for giving the correct answer

Arbitration Fee

• Paid to the arbitrator when requesting intervention

• Set by the arbitrator

• Paid by the user requesting arbitration (usually an answerer whose answer was replaced)

Claim Fee

• From Reality.eth v2.1 onwards

• 2.5% of claimed bonds (except the final bond) is burned

This system is already being used in production by numerous projects, including

• Prediction Markets: Seer, Polkamarkets/Foreland, and Omen use it to verify real-world event outcomes

• Optimistic Governance: Zodiac SafeSnap module implements it for secure DAO proposal execution
• Content Moderation: Moderate/Susie bot leverages it for decentralized content policy enforcement

Advanced Topics

Custom Primary Document for Arbitration

For most DApp integrations, the standard general document works perfectly fine without any customization. However, in some specialized cases, you may need a custom primary document for arbitration.

When Is This Required?

A custom primary document becomes necessary when:

1. Your DApp has specific rules for how disputes should be judged

2. Resolving disputes requires specialized knowledge or context

3. You need a dedicated Kleros court for your application's disputes

4. The interpretation of answers in your context differs from standard interpretations

The Complete Scenario

If you need a custom primary document:

1. Initial Assessment: The Kleros team evaluates your use case to determine if standard arbitration guidelines are sufficient

2. Document Creation: 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

3. Deployment: Kleros deploys a dedicated arbitrator proxy for your application with your primary document embedded as part of the proxy's metaevidence

4. Usage: When disputes go to arbitration, jurors use your guidelines to make decisions

Real-World Example: Seer Prediction Markets

Seer required a custom primary document because they needed specific rules for handling complex market outcomes, edge cases like delayed events, and wanted to specify which information sources should be considered authoritative for their prediction markets.

If you think your application might need this level of customization, the Kleros team can guide you through the process.

Common Questions

Q: Does my DApp need to call the arbitrator proxy directly?

A: No! Your DApp only needs to interact with Reality.eth. The proxy handles communication between Reality.eth and Kleros.

Q: What happens if there's a dispute?

A: The dispute process is handled automatically between Reality.eth and Kleros via the arbitrator proxy.

Q: How can I make my question clearer for accurate answers?

A: Be specific, include resolution criteria, and specify a trusted information source if applicable. For example: "Did the S&P 500 close above 5,000 on April 10, 2025, according to the official S&P website?"

Q: If I don't want to use the Reality.eth frontend for my users, can I handle everything from my DApp

A: Yes, you can implement the full flow in your DApp, including submitting questions, providing answers, and requesting arbitration as needed.

Need Help?

Contact the Kleros team at [e-mail] if you need:

• A custom arbitrator proxy deployment

• Help with Reality.eth integration

• Assistance with complex use cases