The foundational models that determine how external data is sourced, validated, and delivered on-chain, each with distinct trade-offs in security, decentralization, and cost.
LABS
Guides
Key Oracle Design Patterns in DeFi
Chainscore © 2025
concepts
Core Oracle Architectures
01
Centralized Oracle
A single-source oracle where data is provided by one trusted entity or API.
- Operated by a company or a single node operator.
- Low latency and simple to implement.
- Introduces a single point of failure and trust assumption.
- Common in early DeFi projects and for proprietary data feeds where decentralization is less critical.
02
Decentralized Oracle Network
A multi-source oracle that aggregates data from numerous independent node operators.
- Uses cryptographic techniques like threshold signatures for consensus.
- Data is aggregated (e.g., medianized) to produce a single answer.
- Eliminates single points of failure, enhancing security and censorship resistance.
- The architecture used by leading networks like Chainlink to secure billions in value.
03
Optimistic Oracle
A dispute-based oracle that posts data with a challenge period, relying on economic incentives for security.
- Assumes data is correct unless disputed within a time window.
- Disputers must stake collateral to challenge, and are rewarded if correct.
- Optimizes for low-cost, frequent updates where disputes are expected to be rare.
- Used by protocols like UMA for custom price feeds and insurance resolutions.
04
ZK Oracle
An oracle that provides cryptographically verifiable data using zero-knowledge proofs.
- Generates a ZK proof that off-chain computation or data fetching was performed correctly.
- Offers strong privacy and verifiability without revealing underlying data.
- Computationally intensive but provides the highest cryptographic security.
- Emerging use cases include private DeFi and verifiable randomness for gaming.
05
Pull-based Oracle
A user-invoked oracle where data is only fetched and paid for when a smart contract explicitly requests it.
- Shifts gas costs and update initiation to the end-user or contract.
- Eliminates unnecessary on-chain transactions and costs for unused data.
- Requires a reliable mechanism for triggering updates, often via keepers.
- Implemented in designs like Tellor, reducing operational overhead for idle feeds.
06
Push-based Oracle
A publisher-driven oracle where node operators continuously push updated data on-chain at regular intervals.
- Provides low-latency, readily available data for high-frequency applications.
- Incurs continuous gas costs for updates, paid by the oracle service or protocol.
- Essential for perpetuals and money markets requiring up-to-the-second prices.
- The standard model for most decentralized price feeds like Chainlink's Data Feeds.
Data Delivery and Update Mechanisms
Understanding Data Flow
Oracles are services that provide external data, like asset prices, to smart contracts on the blockchain. Since blockchains are isolated, contracts need a secure way to receive this information. The mechanism for how this data is delivered and updated is critical for reliability.
Key Points
- Push vs. Pull Models: In a push model, the oracle automatically sends updates. In a pull model, the contract requests data when needed. Chainlink primarily uses a pull model for on-demand data.
- Update Triggers: Updates can be time-based (e.g., every block, every hour) or event-based (e.g., when a price moves by more than 0.5%). Protocols like MakerDAO use deviation thresholds to trigger updates.
- Data Aggregation: To improve accuracy, oracles often aggregate data from multiple sources. For example, an oracle might fetch the ETH/USD price from three centralized exchanges and calculate a median value before delivering it.
Example
When you use Aave to borrow stablecoins, the protocol needs to know the value of your collateral (like ETH). A Chainlink oracle network constantly monitors ETH's price. If the price drops significantly, the oracle pushes an update to Aave's smart contracts, which can then trigger a liquidation if your collateral ratio falls too low.
Oracle Pattern Comparison
Comparison of key technical and economic trade-offs between common oracle design patterns.
| Feature | Push Oracle | Pull Oracle | Decentralized Oracle Network |
|---|---|---|---|
Data Update Latency | Low (Sub-second to seconds) | High (On-demand, user-initiated) | Medium (Based on heartbeat or threshold) |
Gas Cost Payer | Protocol/Contract (Fixed recurring) | End User (Per-request) | Protocol/Stakers (Shared by network) |
Data Freshness Guarantee | Yes (Scheduled updates) | No (Stale until requested) | Conditional (Based on deviation/interval) |
Censorship Resistance | Low (Relies on updater) | High (User can force pull) | High (Decentralized node quorum) |
On-chain Storage Overhead | High (Stores latest value) | None (Fetches on-demand) | Medium (Stores aggregated value) |
SLA & Uptime | Centralized point of failure | User-dependent | High (Byzantine fault tolerant) |
Typical Use Case | Price feeds for AMMs | Insurance claim verification | Cross-chain asset prices |
Implementing Security Patterns
Process for integrating security mechanisms into oracle design.
1
Implement a Multi-Source Aggregation Model
Reduce single-point failure risk by aggregating data from multiple independent sources.
Detailed Instructions
Multi-source aggregation mitigates manipulation from any single data provider. Start by identifying at least 3-5 reputable, independent data sources (e.g., centralized exchanges like Binance and Coinbase, decentralized exchanges like Uniswap V3, and on-chain price oracles like Chainlink).
- Sub-step 1: Write a function to fetch the price from each source. For on-chain sources, this involves calling a view function (e.g.,
latestRoundData()on a Chainlink aggregator). For off-chain sources, you'll need an off-chain relayer or oracle node. - Sub-step 2: Apply a validation filter. Discard any prices that deviate by more than a configured threshold (e.g., 5%) from the median of the initial set to filter out obvious outliers.
- Sub-step 3: Calculate the final aggregated value. Use a robust statistical measure like the median or a trimmed mean of the validated prices. The median is often preferred as it is resistant to extreme outliers.
solidityfunction getAggregatedPrice(address[] calldata sources) public view returns (uint256) { uint256[] memory prices = new uint256[](sources.length); for (uint i = 0; i < sources.length; i++) { prices[i] = IPriceSource(sources[i]).getPrice(); } // ... logic to filter outliers and compute median ... }
Tip: Consider weighting sources by their historical reliability or liquidity depth, but ensure the weighting logic itself is not easily gameable.
2
Integrate a Time-Weighted Average Price (TWAP)
Smooth out short-term volatility and prevent price manipulation via flash loans.
Detailed Instructions
Time-Weighted Average Price (TWAP) calculates an average price over a specified time window, making it expensive to manipulate. Implement this by recording cumulative price-time data at regular intervals.
- Sub-step 1: Define the observation window and frequency. A common configuration is a 30-minute window with price observations recorded every 10 minutes. Store a struct containing the cumulative price sum and the timestamp of the last update.
- Sub-step 2: On each price update (from your aggregation mechanism), calculate the time elapsed since the last observation, multiply the current price by that elapsed time, and add it to the cumulative sum. Then update the timestamp.
- Sub-step 3: To fetch the current TWAP, compute the total elapsed time within the window. If the window is full, use (cumulativeSum / windowSize). For a rolling window, you may need to subtract older observations that have fallen outside the window.
soliditystruct Observation { uint256 timestamp; uint256 priceCumulative; uint256 price; } function updateTWAP(uint256 newPrice) internal { uint256 timeElapsed = block.timestamp - lastObservation.timestamp; priceCumulative += lastObservation.price * timeElapsed; // Store new observation lastObservation = Observation(block.timestamp, priceCumulative, newPrice); }
Tip: For DEX-based TWAP oracles, consider using existing libraries like Uniswap V3's, which efficiently manage observations in a fixed-size array.
3
Add Circuit Breakers and Deviation Guards
Implement automated halt mechanisms for extreme market events.
Detailed Instructions
Circuit breakers and deviation guards are emergency stops that freeze oracle updates during abnormal conditions, protecting downstream protocols.
- Sub-step 1: Set a maximum single-update deviation threshold. For example, if the new aggregated price deviates by more than 10% from the last accepted price, require a second confirmation from a separate set of fallback oracles before updating.
- Sub-step 2: Implement a heartbeat or staleness check. If no new price update occurs within a maximum interval (e.g., 24 hours), mark the price as stale and trigger a protocol-wide pause or switch to a fallback mode.
- Sub-step 3: Code a manual override function guarded by a multi-signature wallet or a decentralized autonomous organization (DAO) vote. This allows human intervention to pause the oracle in case of a critical bug or sustained attack.
solidityuint256 public lastPrice; uint256 public lastUpdateTime; uint256 constant MAX_DEVIATION = 10; // 10% uint256 constant HEARTBEAT = 24 hours; function updatePrice(uint256 newPrice) external onlyOracle { require(block.timestamp - lastUpdateTime <= HEARTBEAT, "Stale data"); uint256 deviation = (absDiff(newPrice, lastPrice) * 100) / lastPrice; if (deviation > MAX_DEVIATION) { require(confirmWithFallbackOracles(newPrice), "Needs fallback confirm"); } lastPrice = newPrice; lastUpdateTime = block.timestamp; }
Tip: The deviation threshold should be asset-specific; stablecoins require much tighter bounds (e.g., 1-2%) compared to volatile assets.
4
Establish a Robust Upgrade and Fallback System
Ensure oracle continuity during failures or necessary upgrades.
Detailed Instructions
A secure oracle must have a clear path for upgrades and immediate fallbacks to handle failures without service interruption.
- Sub-step 1: Implement the Proxy Pattern or similar upgradeability mechanism. Separate the oracle's logic contract from its storage contract. Use a transparent proxy (e.g., OpenZeppelin's) to allow the DAO to point to a new logic implementation after a timelock and vote.
- Sub-step 2: Deploy a set of independent fallback oracle contracts. These can be simpler, more costly, or slower oracles (like a single Chainlink feed) used only when the primary system fails a health check.
- Sub-step 3: Create a switch function that toggles the active data source from primary to fallback. This switch should be callable by a decentralized keeper network when certain conditions are met (e.g., heartbeat timeout, repeated deviation violations) or by a DAO vote.
solidityaddress public primaryOracle; address public fallbackOracle; address public currentSource; function switchToFallback() external onlyKeeperOrDAO { require(currentSource == primaryOracle, "Already on fallback"); currentSource = fallbackOracle; emit OracleSwitched(fallbackOracle); } function getPrice() external view returns (uint256) { return IOracle(currentSource).getPrice(); }
Tip: The fallback system should be tested regularly via simulated failures. Consider using a circuit breaker that automatically switches sources if the primary fails to update.
5
Encode Economic Security with Staking and Slashing
Align oracle node incentives with honest reporting through cryptoeconomic mechanisms.
Detailed Instructions
Staking and slashing create a financial cost for malicious behavior by requiring node operators to post collateral that can be seized (slashed) for provably incorrect reporting.
- Sub-step 1: Define the staking contract. Node operators must lock a substantial amount of the network's native token or a stablecoin (e.g., 50,000 USD worth) to participate in the oracle network.
- Sub-step 2: Establish a dispute and slashing protocol. When a node submits a price, it enters a challenge period (e.g., 1 hour). Any other participant can submit a bond to dispute the price. If the dispute is validated by a trusted arbitrator or a decentralized court (like Kleros), the malicious node's stake is slashed, with a portion awarded to the disputer.
- Sub-step 3: Implement a reward mechanism for honest reporters. Distribute fees from protocol users (e.g., 0.05% of transaction value) proportionally to nodes that consistently provide timely and accurate data, weighted by their stake.
solidityfunction submitValue(uint256 _value) external onlyReporter { require(stakedAmount[msg.sender] >= MIN_STAKE, "Insufficient stake"); submissions[roundId][msg.sender] = _value; // Start challenge period } function slashReporter(address reporter, uint256 roundId) external onlyArbiter { uint256 slashAmount = stakedAmount[reporter] / 2; // Slash 50% stakedAmount[reporter] -= slashAmount; // Transfer slashAmount to disputer or treasury }
Tip: The slashing conditions must be objectively verifiable on-chain to avoid malicious slashing. Use deviation from a validated median or failure to respond as clear criteria.
real-world-examples
Real-World Implementations
These are the primary oracle design patterns currently securing billions in DeFi value, each with distinct trade-offs in decentralization, data freshness, and cost.
01
Single-Source Oracles
Centralized data feeds from a single, trusted provider like a company or foundation.\n\n- Direct API integration (e.g., Chainlink Data Feeds for price data).\n- Low latency and simple implementation.\n- Creates a central point of failure; security depends entirely on the provider's integrity and uptime.
02
Multi-Source Aggregation
Decentralized data aggregation from multiple independent sources to produce a single validated data point.\n\n- Uses a network of nodes that query and report data (e.g., Chainlink Decentralized Oracle Networks).\n- Employs fault tolerance and outlier detection.\n- Significantly reduces manipulation risk but introduces higher gas costs and latency.
03
Optimistic Oracles
Dispute-based verification where data is assumed correct unless challenged within a time window.\n\n- Used for custom or less frequent data (e.g., UMA's oracle for insurance payouts).\n- Low-cost for posting data, with high security cost only if a dispute occurs.\n- Enables arbitrary data types but requires a robust dispute resolution system and bonded participants.
04
ZK-Oracles
Cryptographically verified data where a zero-knowledge proof attests to the correctness of off-chain computation or data retrieval.\n\n- Provides strong privacy and verification guarantees (e.g., zkOracle designs for private DeFi).\n- Proof generation is computationally intensive.\n- Enables trust-minimized use of sensitive or proprietary data on-chain.
05
Committee-Based Oracles
Permissioned validator sets where a known group of entities (a committee) is responsible for signing and submitting data.\n\n- Common in early-stage protocols or app-specific needs (e.g., MakerDAO's original Oracle Security Module).\n- Faster consensus than permissionless networks.\n- Security relies on the honesty and coordination of the selected members, posing a social consensus risk.
Oracle Design FAQ
The core distinction lies in the initiation of data updates. A push-based oracle proactively broadcasts price updates to on-chain contracts at predefined intervals or when a deviation threshold is met, ensuring continuous data freshness. This is common in systems like Chainlink Data Feeds. A pull-based oracle requires the smart contract to explicitly request data, which is then fetched and delivered in a single transaction. This model, used by protocols like MakerDAO's OSM, reduces gas costs for idle periods but introduces latency. For example, a push oracle might update every block for a 0.5% deviation, while a pull oracle is only queried during a liquidation event.