README.md

@kleros/cross-chain-realitio-contracts

Smart contracts for the Reality.eth cross-chain proxies.

---

• Deployments
  • Mainnets
    • Gnosis
    • Unichain
    • Base
    • Polygon
  • Testnets
    • Chiado
    • UnichainSepolia
    • OptimismSepolia
    • ArbitrumSepolia
    • ZksyncSepolia
• Sequence diagram
• Contributing
  • Install Dependencies
  • Run Tests
  • Compile the Contracts
  • Deploy Instructions
    • 0. Set the Environment Variables
    • 1. Update the Constructor Parameters (optional)
    • 2. Deploy the Proxies

---

Deployments

Refresh the list of deployed contracts by running ./scripts/populateReadme.sh.

Mainnets

Gnosis

Version	Name	Home Proxy	Foreign Proxy	CourtID	MinJurors	Reality	Policy	Comment
v1.1.2	Default 2	0x68154E..7491Dc	0xFe0eb5..c0Aa68	0	31	RealityETH_v3_0	seer
v1.1.1	Polkamarkets Foreland	0x5AFa42..86F90e	0x8453bA..552425	0	5	RealityETH_ERC20_v3_0	default	⚠️ bad metadata
v1.1.1	Default	0x29f39d..fce222	0x2F0895..695F21	0	31	RealityETH_v3_0	noAnswerTooSoon	⚠️ bad metadata
v1.1.0	Omen AI bis	0x5562ac..96cdf2	0xeF2Ae6..6B2f59	0	31	Realitio_v2_1	omen	⚠️ bad metadata
v1.0.0	Omen AI	0xe40DD8..a75ecd	0x79d046..eA3D49	0	500	Realitio_v2_1	omen	⚠️ bad metadata

Unichain

Version	Name	Home Proxy	Foreign Proxy	CourtID	MinJurors	Reality	Policy	Comment
v1.3.0	Default	0xcB4B48..b045a6	0x122D6B..b7954D	24	15	RealityUnverified	default
v1.3.0	Butter	0x8FeAB3..EC44b6	0x3FB831..48Ac17	24	15	RealityUnverified	butter

Base

Version	Name	Home Proxy	Foreign Proxy	CourtID	MinJurors	Reality	Policy	Comment
v1.3.0	Default	0xcB4B48..b045a6	0x87f58F..e2EAf9	24	15	RealityETH_v3_0	default
v1.3.0	Zodiac SafeSnap	0xBeeB21..FBe96B	0x20E1D4..aAe373	24	15	RealityETH_v3_0	zodiac

Polygon

Version	Name	Home Proxy	Foreign Proxy	CourtID	MinJurors	Reality	Policy	Comment
v1.1.0	Default	0x5AFa42..86F90e	0x776e58..231e52	0	31	RealityETH_v3_0	default
v1.1.0	Polkamarkets	0x68154E..7491Dc	0x68c4cc..bAFE28	0	31	RealityETH_ERC20_v3_0	default

Testnets

Chiado

Version	Name	Home Proxy	Foreign Proxy	CourtID	MinJurors	Reality	Policy	Comment
v1.1.0	Default	0xE62094..FffeD7	0x5d7cB7..969D42	0	0	RealityUnverified	default	⚠️ bad metadata

UnichainSepolia

Version	Name	Home Proxy	Foreign Proxy	CourtID	MinJurors	Reality	Policy	Comment
v1.3.0	Default	0x122D6B..b7954D	0x4C10F0..26191D	3	1	RealityETH_v3_0	default
v1.3.0	Butter	0x87f58F..e2EAf9	0xA42986..fFDF15	3	1	RealityETH_v3_0	butter

OptimismSepolia

Version	Name	Home Proxy	Foreign Proxy	CourtID	MinJurors	Reality	Policy	Comment
v1.1.0	Default	0xFe0eb5..c0Aa68	0x6a41AF..5DC3bA	0	0	RealityUnverified	default

ArbitrumSepolia

Version	Name	Home Proxy	Foreign Proxy	CourtID	MinJurors	Reality	Policy	Comment
v1.1.0	Default	0x890deB..d6770e	0x26222E..A821F9	0	0	RealityUnverified	default

ZksyncSepolia

Version	Name	Home Proxy	Foreign Proxy	CourtID	MinJurors	Reality	Policy	Comment
v1.1.0	Default	0x473DC4..41530D	0x54C68f..9d5612	0	0	RealityETH_zksync_v3_0	default

Sequence diagram

Example for Optimism.

sequenceDiagram
    participant User
    participant L1 as Foreign Proxy (L1)
    participant Arbitrator
    participant Messenger as CrossDomainMessenger
    participant L2 as Home Proxy (L2)
    participant Realitio

    %% Initial Arbitration Request
    User->>L1: requestArbitration(questionID, maxPrevious) $arbitrationCost
    activate L1
    L1->>L1: Store arbitration request
    Note over L1: emit ArbitrationRequested
    L1->>Messenger: sendMessage(receiveArbitrationRequest)
    deactivate L1

    Messenger->>L2: receiveArbitrationRequest()
    activate L2
    L2->>Realitio: notifyOfArbitrationRequest()
    
    alt Success
        Realitio-->>L2: Success
        L2->>L2: Set status = Notified
        Note over L2: emit RequestNotified
    else Failure
        Realitio-->>L2: Failure
        L2->>L2: Set status = Rejected
        Note over L2: emit RequestRejected
    end
    deactivate L2

    %% Handle Notified Request
    User->>L2: handleNotifiedRequest()
    activate L2
    L2->>L2: Set status = AwaitingRuling
    Note over L2: emit RequestAcknowledged
    L2->>Messenger: sendMessage(receiveArbitrationAcknowledgement)
    deactivate L2

    rect rgb(136, 136, 136)
        Note over Messenger,L1: 7-day Optimistic Bridge Message
        Messenger-->>L1: receiveArbitrationAcknowledgement()
    end

    activate L1
    L1->>Arbitrator: createDispute() $arbitrationCost
    L1->>L1: Set status = Created
    Note over L1: emit ArbitrationCreated
    Note over L1: emit Dispute
    deactivate L1

    %% Appeal Flow
    User->>L1: fundAppeal(arbitrationID, answer) $appealCost
    activate L1
    alt Fully Funded
        L1->>L1: Store contribution
        Note over L1: emit Contribution
        Note over L1: emit RulingFunded
        L1->>Arbitrator: appeal() $appealCost
    else Not Fully Funded
        L1->>L1: Store partial contribution
        Note over L1: emit Contribution
        L1->>User: Return excess funds
    end
    deactivate L1

    %% Arbitrator Ruling
    Arbitrator->>L1: rule(disputeID, ruling)
    activate L1
    L1->>L1: Set status = Ruled
    Note over L1: emit Ruling
    L1->>Messenger: sendMessage(receiveArbitrationAnswer)
    deactivate L1

    Messenger->>L2: receiveArbitrationAnswer()
    activate L2
    L2->>L2: Set status = Ruled
    Note over L2: emit ArbitratorAnswered
    deactivate L2

    %% Report Answer
    User->>L2: reportArbitrationAnswer()
    activate L2
    L2->>Realitio: assignWinnerAndSubmitAnswerByArbitrator()
    L2->>L2: Set status = Finished
    Note over L2: emit ArbitrationFinished
    deactivate L2

    %% Withdraw Fees
    User->>L1: withdrawFeesAndRewards()
    activate L1
    alt Has Rewards
        L1->>User: Send rewards $
        Note over L1: emit Withdrawal
    end
    deactivate L1

Loading

Contributing

Install Dependencies

yarn install

Run Tests

yarn test

Compile the Contracts

yarn build

Deploy Instructions

IMPORTANT: new versions of any of the contracts require publishing both Home and Foreign proxies, as their binding is immutable.

NOTICE: the commands bellow work only if you are inside the contracts/ directory.

0. Set the Environment Variables

Copy .env.example file as .env and edit it accordingly.

cp .env.example .env

Set the following env vars:

• PRIVATE_KEY: the private key of the deployer account.
• INFURA_API_KEY: the API key for infura.
• ETHERSCAN_API_KEY: the API key to verify the contracts on Etherscan.

1. Update the Constructor Parameters (optional)

If some of the constructor parameters (such as the Meta Evidence) needs to change, you need to update the files in the deploy/ directory.

2. Deploy the Proxies

yarn deploy:chiado:home
yarn deploy:chiado:foreign

The deployed addresses should be output to the screen after the deployment is complete. If you miss that, you can always go to the deployments/<network> directory and look for the respective file.