Detailed Instructions

First, catalog every external data point your smart contracts require, such as asset prices, interest rates, or volatility indices. For each data point, define its criticality level (e.g., liquidation price vs. informational display) and the maximum tolerable staleness. A high-frequency trading vault may require sub-second updates, while a staking protocol might tolerate minutes. Assess the financial risk of incorrect or delayed data; a 1% price error on a $100M pool is a $1M exposure. This risk assessment directly informs your latency and accuracy budget, determining whether you need a premium oracle service or can use a more economical, slower feed.

• Sub-step 1: List all smart contract functions that consume external data.
• Sub-step 2: For each data point, document the required precision (e.g., 18 decimals) and the acceptable time delay before it becomes unsafe.
• Sub-step 3: Quantify the potential financial loss from stale or incorrect data under various market conditions.

Tip: Use historical market volatility data to model how quickly prices move during crises, informing your staleness tolerance.

Detailed Instructions

Evaluate the core oracle update mechanisms. A push-based oracle (like Chainlink Data Feeds) publishes updates on-chain at a fixed interval, providing predictable latency and cost for consumers. A pull-based oracle (like Pyth's pull oracle) allows users to request the latest price on-demand, minimizing gas fees during calm periods but introducing request latency and potential congestion during volatility. A hybrid approach might use a push oracle for heartbeats and allow emergency pull updates. Consider the gas cost economics; frequent pushes for low-value data can be prohibitive. The choice dictates your protocol's real-time capability and operational expense structure.

• Sub-step 1: Map your critical data points from Step 1 to available oracle network offerings (e.g., Chainlink, Pyth, API3).
• Sub-step 2: Model the gas cost of push updates at your desired frequency versus the gas cost + latency of pull requests.
• Sub-step 3: Design fallback logic, such as using a secondary oracle or halting operations if an update is beyond your staleness threshold.

solidityCopy
// Example: Checking staleness in a pull oracle pattern
function _isPriceStale(uint256 _updatedAt) internal view returns (bool) {
    return (block.timestamp - _updatedAt) > MAX_STALENESS;
}

Tip: For push oracles, verify the on-chain updatedAt timestamp directly. For pull oracles, you must call an update function and check the resulting timestamp.

Detailed Instructions

Your contract must not blindly trust the oracle. Implement validation circuits that act as safety rails. This includes bounding checks to reject prices that deviate from a sanity bound (e.g., +/- 50% from the last accepted value) and heartbeat monitoring to ensure updates arrive within the expected window. Use a circuit breaker pattern that pauses critical operations if data is stale or an anomaly is detected. For high-value operations, consider multi-oracle consensus, requiring agreement from 2 of 3 independent feeds before accepting a new value. This increases update latency and cost but drastically reduces single-point-of-failure risk.

• Sub-step 1: Code require() statements that revert transactions if the new data value is outside predefined min/max bounds.
• Sub-step 2: Implement a time-based check that reverts if block.timestamp - lastUpdateTimestamp > maxUpdateDelay.
• Sub-step 3: For consensus, write logic to compare values from multiple oracle addresses and calculate a median or weighted average.

solidityCopy
// Example: Simple bounding check for a price feed
function _validatePriceChange(uint256 _oldPrice, uint256 _newPrice) internal pure {
    uint256 change = (_newPrice * 10000) / _oldPrice; // Basis points
    require(change >= 5000 && change <= 15000, "Price change out of bounds"); // +/-50%
}

Tip: Set bounds dynamically based on market volatility indices or use a moving average to avoid false positives during legitimate market crashes.

Detailed Instructions

Oracle requirements are not static. Network congestion and gas price fluctuations can make a previously optimal update frequency economically unsustainable. Design a governance framework that allows key parameters—like MAX_STALENESS, price deviation bounds, and even the oracle address itself—to be updated. This could be via a multi-sig, a DAO vote, or a time-locked admin function. Crucially, align incentives so governance participants are penalized for poor parameter choices; for example, slashing a security deposit if a change leads to a protocol insolvency. Document a clear change management process for oracle upgrades to prevent operational errors.

• Sub-step 1: Store all critical oracle parameters (addresses, staleness limits, bounds) in variables with public visibility, not hard-coded.
• Sub-step 2: Implement a privileged function (e.g., onlyGovernance) to update these parameters, protected by a timelock.
• Sub-step 3: Create off-chain monitoring alerts that notify governors when gas costs exceed a threshold or update latency degrades.

Tip: Use a structured proposal system that requires simulation of parameter changes on a forked mainnet before execution to assess impact.

Detailed Instructions

Before mainnet deployment, conduct extensive scenario analysis. Use forked mainnet environments with tools like Foundry or Hardhat to simulate extreme gas price spikes (e.g., 1000 gwei) and see if your oracle updates become economically unviable. Test flash crash scenarios where the price drops 30% in one block; does your bounding check incorrectly reject a valid update? Simulate oracle failure by mocking a feed that stops updating, and verify your safety circuits activate correctly. This testing quantifies the tail risks inherent in your oracle design choices. The goal is to discover failure modes in simulation, not in production.

• Sub-step 1: Fork mainnet at a historical block with high congestion (e.g., during an NFT mint or major DeFi event).
• Sub-step 2: Write a test that drastically increases block.timestamp to simulate a prolonged network outage or oracle downtime.
• Sub-step 3: Perform a MEV bot simulation to see if your latency window creates predictable arbitrage opportunities.

solidityCopy
// Foundry test example: Simulating a stale price
function testStalePriceReverts() public {
    vm.warp(block.timestamp + MAX_STALENESS + 1); // Fast-forward time
    vm.expectRevert("Price too stale");
    myProtocol.executeCriticalAction(priceData);
}

Tip: Incorporate real historical price data and blockchain gas charts into your test suites for realism.