Reality (Oracle) Overview

Subjective oracle system combining Reality.eth bond escalation with Kleros Court arbitration for on-chain verification of real-world events.

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

---

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:

Contract	Chain	Role
Your Contract	Any supported chain	Asks questions, reads finalized answers
Reality.eth	Same chain as your contract	Bond escalation, answer management, timeout logic
Kleros Arbitrator Proxy	Same chain as Reality.eth	Creates disputes in Kleros Court, reports rulings back

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:

Chain	Status
Ethereum Mainnet	Active (V1 Court)
Gnosis Chain	Active (V1 Court)
Arbitrum One	Available via V2 Court
Polygon	Active (V1 Court)

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.

Template ID	Type	Answer Format	Example
0	bool	Yes/No	”Did event X happen?“
1	uint	Numeric value	”What was the price of ETH on date Y?“
2	single-select	One of N options	”Which team won?“
3	multiple-select	Subset of N options	”Which proposals passed?“
4	datetime	Unix timestamp	”When did event X occur?“
5	hash	bytes32 hash	”Does hash X correspond to document Y?”

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

Bond Escalation

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.

Arbitration Escalation

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 Submission

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.

Configurable Parameters

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.

Cross-chain Support

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