Oracle
An oracle turns selected off-chain or cross-system observations into an on-chain value that smart contracts can read under explicit update and trust rules.
Category: RiskWarning cross category cue
System record
Start with the economic purpose, participants, resources, and entitlements before studying implementation detail.
Why it exists
Smart contracts cannot independently observe external prices, rates, reserves, or events, so they need a controlled path for admitting those facts into financial state transitions.
Traditional-finance analogy
Market-data feed and valuation agent is the closest comparison recorded for this concept.
Where the analogy stops
- An oracle value can trigger liquidation, minting, settlement, or payout automatically in the same transaction rather than merely informing a human operator.
- Source markets, reporters, aggregation, feed contracts, chain availability, adapters, units, and fallback authority all become one composable trust path.
Main actors
- ActorData source or venue
- ActorReporter, publisher, or oracle network
- ActorAggregator and feed contract
- ActorConsuming protocol, keeper, guardian, and user
Assets and claims
Assets — controlled or transformed resources
Assets are resources the mechanism moves, holds, values, or transforms.
- AssetCollateral, reserves, derivatives, and claims valued from oracle data
- AssetFee or stake assets used to operate or secure the oracle
Claims — entitlements and corresponding dependencies
Claims are rights to value, repayment, redemption, control, or another party's performance; each depends on an obligation or system that must honor it.
- ClaimOn-chain price, rate, reserve, or event assertion
- ClaimPosition whose eligibility, value, or settlement depends on that assertion
An oracle is the admission path that turns selected external observations into values a smart contract can use.
Why it exists
Section titled “Why it exists”Contract execution can inspect on-chain state but cannot independently know a current exchange price, reserve statement, benchmark rate, weather event, or legal outcome. An oracle defines who observes, how reports are combined, when a value updates, and what consumers should do when it is missing or suspect.
Traditional-finance analogy
Section titled “Traditional-finance analogy”A market-data feed or valuation agent is a useful analogy. It stops being exact because an on-chain value may liquidate collateral, mint assets, settle a derivative, or pay cover in the same transaction. Feed contracts, source markets, reporters, chain conditions, adapters, units, and fallback controllers therefore become part of the financial position.
Actors, assets, and claims
Section titled “Actors, assets, and claims”Data sources originate observations. Reporters or publishers transmit them, aggregation selects an accepted value, and feed contracts expose it. Protocols, keepers, guardians, and users rely on the result. Collateral, debt, derivatives, reserves, and payouts remain the assets and claims; the oracle value is an assertion used to control them.
Mechanism and flows
Section titled “Mechanism and flows”- Define acceptable sources, asset identity, units, and timing.
- Collect signed or otherwise attributable observations.
- Aggregate, filter, or validate them under a stated rule.
- Publish an on-chain value, timestamp, and status.
- Require each consumer to validate freshness, decimals, chain availability, and action-specific bounds before changing financial state.
Information flow runs from source markets through reporters and feed contracts. Capital flow changes only when a consumer uses the published value in a financial state transition. Claim flow changes when that consumer reprices, mints, settles, liquidates, or accounts for an entitlement. Control flow follows publisher, access-control, fallback, pause, and upgrade authority. Return flow can pay oracle operators from subscribers, protocols, staking rules, treasuries, or token issuance; the data does not create return by itself. Risk flow reaches every consumer and then the users who hold the affected claims.
State and loss allocation
Section titled “State and loss allocation”| Feed condition | Safe consumer response | Unsafe shortcut |
|---|---|---|
| Valid and fresh | Use within documented bounds | Assume suitability for every action |
| Stale | Reject, cap, or degrade | Reuse indefinitely |
| Unavailable | Apply explicit pause or fallback | Substitute an unrelated feed |
| Anomalous or disputed | Limit action and investigate | Accept because the call returned a number |
A wrong value can seize good collateral, leave bad debt, overmint a stablecoin, misstate NAV, or mispay a derivative. Borrowers, lenders, traders, LPs, cover capital, reserves, or token holders absorb the resulting loss according to the protocol’s backstop design.
Beginner lens
Section titled “Beginner lens”An oracle is not a magical truth source. It is a documented chain of observers, rules, contracts, and fallbacks that a protocol chooses to trust.
Practitioner lens
Section titled “Practitioner lens”Inventory feed addresses, source venues, update triggers, heartbeat, deviation threshold, decimals, quote unit, liquidity assumptions, sequencer handling, fallbacks, caps, pause behavior, governance, monitoring, and incident response.
Engineer or auditor lens
Section titled “Engineer or auditor lens”Chainlink Data Feeds are one implementation family, not the definition of an oracle. Review the selected feed and network, proxy and aggregator addresses, round data, timestamp, access model, billing, source methodology, and consumer checks. Other systems may use signed reports, on-chain TWAPs, optimistic disputes, committees, or zero-knowledge proofs.
Security review notes
Section titled “Security review notes”Validate identity, unit, decimals, freshness, validity range, chain status, and fallback before every consequential state change. Test stale, missing, negative, zero, extreme, divergent, manipulated, and sequencer-outage states. See oracle risk for propagation analysis.
Common misunderstandings
Section titled “Common misunderstandings”- “Decentralized oracle means correct data.” Independence and aggregation reduce some failures but do not prove source quality or consumer safety.
- “The feed contract handles all checks.” Consumers still choose addresses, units, freshness, fallbacks, and action thresholds.
- “One price fits every use.” Liquidation, settlement, NAV, and execution can require different horizons and robustness.
Prerequisites and learn next
Section titled “Prerequisites and learn next”Read smart contracts and market information first. Continue to collateral or synthetic assets to see oracle-dependent positions.
Sources
Section titled “Sources”- Chainlink, Data Feeds documentation — one production oracle architecture and integration surface (accessed 2026-08-09).
- The supplied DeFi seed, sections 4.3, 9.1, 10, and 12 — oracle roles, information flow, and analysis questions.
Machine-readable model
Key equations
Canonical expressions come from the structured concept record. KaTeX renders the notation, while the plain-text expression and variable table keep its meaning and units inspectable without JavaScript. Read the narrative above for the model's domain, assumptions, and rounding rules.
This concept does not require one canonical equation. Its mechanism and state transitions remain the authoritative explanation; do not invent a formula merely to make the topic look quantitative.
Assurance contract
Security properties
These structured statements define desired behavior. Their stable IDs can bind tests, invariants, specifications, audit findings, or proof results without turning descriptive review advice into an assurance claim.
Desired · not evaluated: No test, audit, or proof result is implied until scoped evidence is linked to this property.
Every consumer validates feed identity, unit, decimals, freshness, validity range, and chain availability before changing financial state
Manipulating one reporter or thin source cannot move the accepted value beyond the documented aggregation and deviation bounds
Stale, missing, disputed, or anomalous data moves the consumer into an explicit safe or degraded state
Oracle assumptions and fallback authority are reflected in caps, collateral rules, settlement logic, and user disclosures
Knowledge check
Quiz
Answer in your own words, then open the model answer.
Why must a consumer check freshness?
Model answer
A correctly encoded old value can still cause an economically incorrect state transition after the market has moved.