UMA Optimistic Oracles Overview

LABS

UMA Optimistic Oracles Overview

Core Concepts

Foundational principles of the UMA Optimistic Oracle system for decentralized truth.

Optimistic Assertion

The core mechanism where a proposer makes a claim about real-world data, which is considered true unless disputed. This enables low-cost, high-speed data resolution.

Data is posted with a bond and a liveness period.
Any verifier can challenge the claim during this period.
If unchallenged, the assertion is finalized and can be used by smart contracts.
This model prioritizes efficiency, only invoking costly verification when a dispute arises.

Dispute Resolution

The process for resolving challenges to optimistic assertions via the Data Verification Mechanism (DVM). This is UMA's decentralized court for truth.

A challenge triggers a vote by UMA token holders.
Voters are economically incentivized to vote correctly.
The voting outcome determines the final truth and settles the proposer's and challenger's bonds.
This provides a robust, cryptoeconomic backstop for disputed data.

Bonding and Liveness

Economic security parameters that secure the oracle. The proposer bond is collateral staked to guarantee assertion quality, while the liveness period is the time window for disputes.

A large bond discourages false assertions.
The liveness period (e.g., 2 hours) defines the system's finality time.
Bonds are slashed from losers and awarded to winners in a dispute.
These parameters are configurable per application to balance security and speed.

Arbitrary Data Support

The oracle's ability to verify any type of truth, not just numeric price data. This enables generalized truth for complex contracts.

Can assert outcomes of events, KYC status, or custom computations.
The question format and resolution logic are defined by the integrating dApp.
This flexibility powers insurance, prediction markets, and conditional token distributions.
The DVM interprets and votes on the specific question's resolution criteria.

Integration Patterns

How smart contracts interact with the oracle, primarily through the proposePrice, disputePrice, and settle functions. This defines the request-and-settle lifecycle.

Contracts can request price data or custom information at a future time.
The Skinny Optimistic Oracle offers a gas-optimized interface for price feeds.
Integrators must manage callback logic for when data is finalized.
This pattern allows any contract to become a data requester.

Data Request and Dispute Workflow

Process overview for requesting data and managing disputes on UMA's Optimistic Oracle.

Request Data from the Oracle

A user submits a data request to the Optimistic Oracle contract.

Detailed Instructions

To request a price or custom data point, call the requestPrice, requestPriceFor, or proposePriceFor functions on the OptimisticOracleV3 contract. You must specify the ancillary data, a unique identifier for your request, and the liveness period—the time window during which the proposed answer can be disputed. For price requests, you will interact with the Finder contract to locate the current oracle address. The request is stored on-chain, initiating the proposal phase.

Sub-step 1: Encode your query (e.g., "BTC/USD price at 12:00 UTC") into ancillary data bytes.
Sub-step 2: Determine the appropriate liveness period (e.g., 7200 seconds for a 2-hour dispute window).
Sub-step 3: Call requestPrice(identifier, timestamp, ancillaryData, currency, reward) with the required parameters.

solidity
// Example: Requesting a price
IOptimisticOracleV3 oracle = IOptimisticOracleV3(finder.getImplementationAddress("OptimisticOracleV3"));
oracle.requestPrice(
    "YES_OR_NO_QUERY",
    block.timestamp,
    "Resolved: 1",
    IERC20(address(0)), // Use address(0) for ETH
    0 // Bond amount
);

Tip: The identifier (e.g., "YES_OR_NO_QUERY") must match a price identifier approved by the UMA DVM. Check the UMA contract addresses documentation for the latest.

Proposer Submits an Answer

A proposer responds to the request with a value and posts a bond.

Detailed Instructions

Any whitelisted proposer can respond by calling proposePrice on the oracle contract. They must submit a bond (in the form of UMA's collateral currency, typically USDC) which is at risk of being slashed if their answer is successfully disputed. The proposed value becomes the tentatively accepted answer. The liveness timer starts, defining the period during which other participants can challenge this proposal. The bond size is configurable per request and acts as the economic security for the system.

Sub-step 1: Monitor the PriceRequestAdded event for new requests.
Sub-step 2: Compute or retrieve the correct answer off-chain (e.g., fetch price from an API).
Sub-step 3: Call proposePrice(requester, identifier, timestamp, ancillaryData, proposedPrice) and transfer the required bond.

solidity
// Example: Proposing a price of 50000 for a BTC/USD query
oracle.proposePrice(
    msg.sender, // requester
    "BTC/USD",
    requestTimestamp,
    ancillaryData,
    50000e18 // Proposed price, scaled to 18 decimals
);
// The bond is automatically pulled from the proposer's balance.

Tip: Proposers are economically incentivized to submit correct answers to earn the request reward and avoid losing their bond. The bond is returned if the proposal is not disputed within the liveness period.

Disputer Challenges an Incorrect Proposal

A disputer identifies a wrong answer and initiates a challenge.

Detailed Instructions

During the liveness period, any participant can dispute a proposed price by calling disputePrice. The disputer must post an identical bond to the proposer's. This action moves the request into the dispute resolution phase and escalates it to UMA's Data Verification Mechanism (DVM) for final arbitration. The dispute process is the core "optimistic" mechanism, assuming correctness unless actively challenged. The DVM's UMA token holders will vote on the correct outcome after a weekly voting cycle.

Sub-step 1: Monitor the PriceProposed event for newly submitted proposals.
Sub-step 2: Verify the proposed value against your own trusted data source.
Sub-step 3: If incorrect, call disputePrice(requester, identifier, timestamp, ancillaryData) before the liveness period expires.

solidity
// Example: Disputing a proposed price
oracle.disputePrice(
    requesterAddress,
    "BTC/USD",
    requestTimestamp,
    ancillaryData
);
// An equivalent bond is pulled from the disputer.

Tip: Successful disputers are rewarded with a portion of the proposer's slashed bond. The specific slash amount and reward are governed by the OptimisticOracleV3 contract's defaultLiveness and bond parameters.

DVM Resolution and Settlement

The Data Verification Mechanism determines the final truth and settles funds.

Detailed Instructions

Once disputed, the query is sent to the DVM. UMA token holders vote on the correct answer during a predefined voting period (approximately 2-5 days). After the vote, the settle function can be called by anyone to finalize the request. The contract enforces the DVM's ruling: the losing side's bond is slashed, with a portion burned and the remainder awarded to the winning side and the DVM voters. The final settled price is then made available for the original requester's smart contract to consume.

Sub-step 1: After the DVM vote ends, call settle(requester, identifier, timestamp, ancillaryData).
Sub-step 2: The contract retrieves the resolved price from the DVM and calculates bond settlements.
Sub-step 3: The requester can now call getPrice or settleAndGetPrice to receive the authoritative value.

solidity
// Example: Settling a request and retrieving the price
oracle.settle(requesterAddress, identifier, requestTimestamp, ancillaryData);
int256 settledPrice = oracle.getPrice(identifier, requestTimestamp, ancillaryData);
// The settledPrice is now available for use in your application.

Tip: The settlement process is permissionless and gas-intensive. It's often handled by keeper bots. The original requester should design their contract to handle the time delay for DVM resolution.

Primary Use Cases

Understanding the Core Mechanism

The UMA Optimistic Oracle is a decentralized truth machine that allows any data to be brought on-chain. It works on an "optimistic" principle: data is assumed correct unless disputed. This is different from immediate-answer oracles like Chainlink. A proposer posts a price or data point with a bond, and a disputer can challenge it within a set time window, triggering a resolution on UMA's Data Verification Mechanism (DVM).

Key Applications for New Users

Data Verification: Projects like Across Protocol use it to verify off-chain data for cross-chain bridges, ensuring correct relay payouts.
Insurance Payouts: Protocols such as Sherlock use it to determine if a covered hack occurred, automating claim assessments.
Prediction Markets: Platforms can resolve event outcomes (e.g., "Did Team A win?") without relying on a single data source.

Simple Example: Yield Verification

A yield farming vault could use the oracle to prove it generated a 5% APY. The vault manager proposes this claim. If no one disputes it with evidence within 48 hours, the claim is accepted and can trigger fee distributions.

Oracle Model Comparison

Comparison of key technical and economic properties across major oracle models.

Feature	Optimistic Oracle (UMA)	Push/Pull Oracle (Chainlink)	On-Chain DEX Oracle (Uniswap)
Data Finality & Dispute Period	~2-24 hours (optimistic window)	Immediate (on aggregation)	Immediate (on-chain)
Primary Security Model	Economic security via bonded disputes	Decentralized node operator reputation	On-chain liquidity depth
Typical Update Latency	Minutes to hours (request-based)	Seconds to minutes (heartbeat)	Continuous (per-block)
Cost Structure	Bond posting + dispute gas costs	Per-request fee paid to node operators	Gas costs for on-chain manipulation
Data Flexibility	Any verifiable truth (custom data types)	Pre-defined data feeds (price, weather, etc.)	Limited to asset pairs with liquidity
Censorship Resistance	High (anyone can propose/dispute)	High (decentralized node set)	Variable (depends on liquidity centralization)
Maximum Throughput (reqs/sec)	Low (human-in-the-loop for disputes)	High (automated node responses)	Very High (native to block production)
Settlement Guarantees	Eventually correct (if undisputed)	Probabilistically correct	Manipulatable within cost of attack

Integrating the Oracle

Process overview for implementing UMA's Optimistic Oracle in a smart contract system.

Define the Data Request

Specify the query and parameters for the oracle.

Detailed Instructions

Define the ancillary data string that encodes your specific request. This is a flexible, human-readable string that the oracle's proposers and disputers will evaluate. For a price request, you might use a format like "BTC/USD price at 2024-01-01T00:00:00Z". For a custom boolean condition, use something like "Did event X occur before block 20,000,000?". The ancillary data must be precise and unambiguous. Store this string in your contract.

Sub-step 1: Determine the exact question or value your dApp needs.
Sub-step 2: Format it into a clear, parseable ancillary data string.
Sub-step 3: Ensure your contract logic can later interpret the returned value correctly.

solidity
// Example ancillary data for a price request
string ancillaryData = "BTC/USD price at 2024-01-01T00:00:00Z";

Tip: Use a standardized schema for complex data to ensure proposers can parse it consistently.

Request a Price or Data Point

Initiate the oracle request from your smart contract.

Detailed Instructions

Call the requestPrice or requestAndProposePriceFor function on the OptimisticOracleV3 contract. You must pass the identifier (e.g., "YES_OR_NO_QUERY"), the timestamp for the request, your ancillary data string, the currency (e.g., 0x... for WETH), and the reward amount for proposers. The reward incentivizes a proposer to submit an initial answer. You can set it to 0, but this may slow down the process. The function will emit an event with a unique request key.

Sub-step 1: Import the IOptimisticOracleV3 interface into your contract.
Sub-step 2: Call the request function, specifying all required parameters.
Sub-step 3: Capture the emitted RequestPrice event to get the request key for future reference.

solidity
// Example call to request a price
optimisticOracle.requestPrice(
    identifier,
    requestTimestamp,
    ancillaryData,
    currency,
    reward
);

Tip: The request timestamp should be in the past for historical data or the recent past for live data.

Propose and Settle an Answer

Handle the proposal and finalization of the oracle's response.

Detailed Instructions

After the request is made, any whitelisted proposer can submit an answer by calling proposePrice. This starts the liveness period (e.g., 2 hours), during which the answer can be disputed. If undisputed, the answer becomes final. Your contract should then call settle to retrieve the resolved price or data. The settle function will revert if the liveness period hasn't expired or if the request is still disputed. You can also use settleAndGetPrice to atomically finalize and receive the value.

Sub-step 1: Monitor for the ProposePrice event on your request key.
Sub-step 2: Wait for the liveness period to pass with no disputes.
Sub-step 3: Call settle on the oracle contract for your request key.

solidity
// Settling a request and getting the price
int256 settledPrice = optimisticOracle.settleAndGetPrice(
    requester,
    identifier,
    requestTimestamp,
    ancillaryData
);

Tip: Implement a keeper bot or a function in your contract to call settle once the request is final.

Handle Disputes and Security

Understand the dispute mechanism and integrate security checks.

Detailed Instructions

If a proposed answer is incorrect, any disputer can challenge it by calling disputePrice and posting a bond during the liveness period. This triggers a verification process via UMA's Data Verification Mechanism (DVM). Your integration must account for this delay (e.g., ~48 hours). Your contract should not rely on a value that is still potentially disputed. Use the getState function to check if a request is Settled. Implement a fallback logic or pause critical actions if a key price feed is in dispute.

Sub-step 1: Query the request state using getState before using any returned value.
Sub-step 2: Design your dApp's logic to handle the dispute resolution period gracefully.
Sub-step 3: Consider setting a higher reward to attract honest proposers and reduce dispute likelihood.

solidity
// Checking the state of a request
OptimisticOracleV3Interface.RequestState state = optimisticOracle.getState(
    requester,
    identifier,
    requestTimestamp,
    ancillaryData
);
// Proceed only if state == RequestState.Settled

Tip: The security of the system relies on economic incentives for disputers to correct wrong answers.

Configure Oracle Parameters

Set custom liveness, bond amounts, and currency settings.

Detailed Instructions

The OptimisticOracleV3 allows customization of key parameters via the setCustomLiveness, setBond, and setCurrency functions (called by the requester). The default liveness is 7200 seconds (2 hours). For less critical data, you might increase this to reduce dispute frequency. The default bond is set by the oracle, but you can increase it to require a higher financial stake from disputers, making frivolous disputes costlier. You must set these customizations before the price is proposed.

Sub-step 1: Decide on appropriate liveness and bond amounts for your use case's security-speed trade-off.
Sub-step 2: Call the setter functions on the oracle contract for your specific request key after creation but before a proposal.
Sub-step 3: Verify the custom settings by reading the request's stored parameters.

solidity
// Setting a custom 1-hour liveness period for a request
optimisticOracle.setCustomLiveness(
    identifier,
    requestTimestamp,
    ancillaryData,
    3600 // 1 hour in seconds
);

Tip: Longer liveness periods provide more time for disputers to identify incorrect proposals but delay finality.

Security and Economic Guarantees

UMA's optimistic oracle system is secured through a combination of economic incentives, dispute resolution mechanisms, and decentralized verification, ensuring data integrity without relying on constant on-chain computation.

Bonded Proposals

A proposer bond is required to submit a price or data assertion. This bond is forfeited if the assertion is successfully disputed, creating a strong economic disincentive for submitting false data. The bond size is dynamically adjusted based on the historical dispute rate for that data type, aligning cost with risk. This mechanism ensures proposers are financially accountable for the accuracy of their submissions.

Dispute Resolution

After a proposal is made, it enters a liveness period (e.g., 2 hours) where any token holder can dispute it by staking an equal bond. A disputed assertion is sent to UMA's Data Verification Mechanism (DVM) for decentralized resolution via a snapshot vote. This process ensures truth is determined by the broader community, not a single entity. It provides a robust backstop against incorrect data being finalized on-chain.

Economic Finality

Finality is achieved when an assertion passes the liveness period unchallenged or wins a DVM vote. This model provides optimistic finality, where data is assumed correct unless economically challenged. It drastically reduces gas costs compared to constantly polling oracles. For users, this means low-latency data availability with a strong cryptographic guarantee that the data can be verified if needed, enabling efficient DeFi applications.

Dispute Incentives

The system incentivizes honest disputers through a reward payout from the loser's bond. A successful disputer receives the proposer's bond minus a small protocol fee. This creates a profitable opportunity for vigilant token holders to monitor and correct inaccurate data. The incentive structure ensures there is always a financial reason to police the system, making collusion to pass false data economically irrational.

Sybil Resistance & Governance

The DVM vote uses UMA's voting token (UMA) for governance, providing Sybil resistance as voting power is tied to economic stake. Votes are weighted by token balance, preventing spam attacks. This ties the security of the oracle directly to the value and decentralization of the UMA ecosystem. Governance participants are economically aligned with the long-term health and accuracy of the oracle system.

Programmable Security

Security parameters like liveness period duration, bond sizes, and DVM voting rewards are not fixed. They are governed by UMA token holders and can be optimized for different use cases. A high-value insurance payout might use a longer liveness period and larger bond, while a gaming NFT rarity score might use faster, cheaper settings. This flexibility allows developers to tailor security to their application's specific risk and cost profile.

SECTION-FAQ

Frequently Asked Questions

Developer Resources

UMA Optimistic Oracle Documentation

Technical documentation covering the Optimistic Oracle architecture, request lifecycle, dispute resolution, and onchain integration details.

Visit resource

UMA Protocol GitHub Repository

Reference implementation of UMA smart contracts, including Optimistic Oracle versions, interfaces, and example integrations.

Visit resource

Introducing the UMA Optimistic Oracle

Design rationale and security model of the Optimistic Oracle, including economic guarantees and dispute mechanics.

Visit resource

UMA Oracle Interface

Web interface for observing oracle requests, disputes, and assertions resolved by the UMA Optimistic Oracle.

Visit resource

Ready to Start Building?

Let's bring your Web3 vision to life.

From concept to deployment, ChainScore helps you architect, build, and scale secure blockchain solutions.

Start Your Project View Our Work