Skip to content

README.md

Latest commit

 

History

History
73 lines (50 loc) · 2.77 KB

README.md

File metadata and controls

73 lines (50 loc) · 2.77 KB
Raw

Reef Oracle

An optimistic oracle system for Sui that allows smart contracts to request off-chain data and assume submitted claims are correct unless challenged.

Key Features

  • Topic Whitelisting: Only approved topics can be used for queries
  • Auto-Expiration: Queries have hard deadlines
  • Economic Security: Bond requirements and winner-takes-all settlement punish dishonest behavior
  • Modular Resolvers: Pluggable dispute resolution systems
  • Callback System: Optional notifications for query lifecycle events

How It Works

  1. Create Query: A creator creates a query on-chain with bond amount, liveness period, and expiration
  2. Submit Claim: A submitter provides a claim along with the required bond
  3. Challenge Claim: Anyone can challenge the submitted claim during the liveness period by posting an equal bond. This deducts a resolution fee from the bond pool and may trigger immediate reward transfers
  4. Settle Query: If unchallenged, the claim is accepted after the liveness period. If challenged, a resolver determines the correct claim and distributes bonds to the winner.

Flow Diagram

Creator ──create_query──▶ Created ──submit_claim──▶ Submitted
                            │                         │
                            │                         ├── No Challenge
                            ▼                         │
                         Expired ◀─── liveness ────────┤
                            │        expires          │
                            │                         ▼
                            └──── expires_at_ms ──▶ Challenged ──▶ Resolved ──▶ Settled

Economic Model

Unchallenged: Submitter gets their bond back + any rewards

Challenged: Winner gets both bonds (minus resolution fee) + rewards. Loser loses their bond. The resolution fee goes to the resolver for arbitration.

Architecture

  • Protocol Module: Global config, topic whitelist, fee structure and resolution parameters
  • Query Lifecycle: Created → Submitted → Challenged → Resolved → Settled → Expired
  • Resolver Framework: Custom dispute resolution with witness-based authorization
  • Data Format: Raw byte vectors (vector<u8>) for maximum flexibility

Usage

Designed for use cases where:

  • Data is generally reliable (disputes are rare)
  • Economic cost of challenging creates sufficient deterrent
  • Speed matters more than immediate finality

Examples: price feeds, sports outcomes, weather data, cross-chain verification.

Getting Started

Building

cd packages/reef
sui move build

Testing

sui move test

License

MIT License - see LICENSE file for details.