Skip to main content

​
Introduction

Kleros Oracle combines Reality.eth, a bond escalation mechanism for crowdsourced answers, with Kleros Court as an external arbitrator. This provides a decentralized oracle that can answer any question with a publicly verifiable answer. Your application only interacts with Reality.eth. Kleros is invoked automatically when a dispute over an answer is escalated to arbitration.

Smart Contracts

Contract interfaces, arbitrator proxy addresses, and function reference

Integration Guide

Step-by-step guide to ask questions and retrieve answers from your contract

​
V1 - SafeSnap Integration (Ethereum / Gnosis Chain)

The Reality.eth + Kleros oracle powers SafeSnap for DAO governance, and V1 integration is actively supported. Technical notes for integrators:
  • Zodiac / SafeSnap: the Kleros Reality Module works with Snapshot through the Gnosis Zodiac Safe configuration. The Zodiac bots validate keccak hashes for Reality questions automatically (issuing a warning rather than failing when a hash cannot be verified), normalize Reality links to consistent casing, and handle Reality questions with no Snapshot proposal attached.
  • Monitoring: integrations can be monitored using ENS, Snapshot, and contract addresses (as done for Panther Protocol).
  • Court display: Court V1 displays “Invalid” instead of “Refuse to Arbitrate” for Reality cases.
  • Networks: the Realitio integration extends to the Base Sepolia testnet, and the cross-chain Realitio proxy is actively maintained.
For the full SafeSnap integration walkthrough, see the Integration Guide.

​
How It Works

1

Ask a Question

Your contract (or a user) submits a question to Reality.eth, optionally attaching ETH as a reward, and references a Kleros arbitrator proxy as the dispute resolver.
2

Answer with Bonds

Anyone can submit an answer by posting a bond. To override an existing answer, the new answerer must post a bond at least double the previous one. Bond escalation makes incorrect answers economically unsustainable.
3

Finalization or Arbitration

If no one challenges the current answer within the timeout window, the answer finalizes. If a party disagrees, anyone can pay the arbitration fee to escalate the question to Kleros Court through the arbitrator proxy.
4

Ruling

Kleros jurors evaluate the question and the submitted evidence, then vote on the correct answer. The arbitrator proxy reports the ruling back to Reality.eth, which finalizes the answer.

​
Architecture

The integration uses three contract layers: Your contract only interacts with Reality.eth. The arbitrator proxy address is specified when asking the question, and the proxy handles all communication with Kleros Court.

​
Same-chain vs Cross-chain

The system supports two deployment patterns:
  • Same-chain: The question and the arbitration both live on the same network. This is the simplest integration.
  • Cross-chain: The question lives on one chain (e.g. Gnosis Chain or Polygon) while arbitration runs on Ethereum or Arbitrum through a cross-chain proxy. Use this when your application is on a chain without a native Kleros Court deployment.
Cross-chain proxy deployments are listed in the cross-chain-realitio-proxy repository.

​
Supported Chains

Reality.eth is deployed on multiple chains. Kleros arbitrator proxies are available on:
Check the Reality.eth deployment repository for the full list of chain deployments and contract addresses. For Kleros arbitrator proxy addresses, see the Smart Contracts page.

​
Question Types

Reality.eth supports several question templates. Each template defines the answer format and how the result is encoded. Custom templates can be registered for application-specific use cases via createTemplate() or the Reality.eth Template Generator. For full details on result encoding, see Smart Contracts → Result Interpretation.

​
Resolution Flow

The system follows a push/pull model. Your DApp pushes a question to Reality.eth and later pulls the verified answer. A question can be resolved through two paths:

​
Happy Path - Consensus Resolution

  1. An answerer submits an answer with a bond
  2. No one challenges within the timeout period
  3. The answer finalizes automatically
  4. Your DApp reads the result via resultFor(questionID)

​
Unhappy Path - Arbitration Resolution

  1. An answerer submits an answer with a bond
  2. Another user posts a counter-answer with a higher bond
  3. Bond escalation may continue until a party requests arbitration
  4. The question is frozen on Reality.eth
  5. A dispute is created in Kleros Court via the arbitrator proxy
  6. The evidence submission period opens
  7. Jurors review evidence and vote
  8. The ruling is reported back to Reality.eth
  9. Your DApp reads the arbitrated result
All interactions happen through the Reality.eth interface. Your DApp does not need separate UIs for the two paths.

​
Key Features

Each successive answer must post at least double the previous bond. This makes incorrect answers exponentially expensive to sustain, so most questions resolve correctly without ever reaching arbitration.
At any point after the first answer, anyone can request arbitration by paying the arbitration fee. The Kleros Arbitrator Proxy creates a dispute in the configured court and subcourt, with the configured initial juror count.
Evidence is submitted through the Kleros Arbitrator Proxy contract, not through Reality.eth. The proxy manages the evidence group and forwards submissions to Kleros Court. See the Integration Guide for the submission flow and the ERC-1497 evidence format.
Each arbitrator proxy is deployed with a specific subcourt, initial number of juror votes, and arbitration fee. The Kleros team can deploy custom proxies, including proxies with a custom primary document for jurors when standard arbitration guidelines are not enough for a use case.
The system supports cross-chain proxies, allowing a question on one chain to be arbitrated by Kleros Court on another. This unlocks integrations on chains without a native Kleros Court deployment.

​
Kleros Oracle in Production

The Reality.eth + Kleros oracle powers production systems across multiple categories:
  • Prediction Markets: Seer, Polkamarkets/Foreland, and Omen use it to verify real-world event outcomes
  • Optimistic Governance: The Zodiac SafeSnap module implements it for secure DAO proposal execution
  • Content Moderation: Moderate / Susie bot leverages it for decentralized content policy enforcement

​
Resources

Reality.eth Documentation

Official Reality.eth docs and API reference

Reality.eth GitHub

Contract source code and deployments

Kleros Oracle Page

Product overview

Discord

Developer support