oracle-manipulation

# Oracle Manipulation ## Spot Price Manipulation Spot prices from DEXs (Uniswap V2 reserves, Curve pool balances) can be manipulated within a single transaction via flash loans. ```solidity // VULNERABLE: reads instantaneous reserves function getPrice(address pair) external view returns (uint256) { (uint112 reserve0, uint112 reserve1,) = IUniswapV2Pair(pair).getReserves(); return uint256(reserve1) * 1e18 / uint256(reserve0); // easily manipulated } ``` **Never use spot prices for:** - Collateral valuation - Liquidation thresholds - Governance decisions - Any value-bearing calculation ## TWAP Oracle (Time-Weighted Average Price) TWAPs average prices over a time window, making manipulation expensive (attacker must sustain the manipulated price across blocks). ```solidity import {OracleLibrary} from "@uniswap/v3-periphery/contracts/libraries/OracleLibrary.sol"; function getTWAP( address pool, address baseToken, address quoteToken, uint128 baseAmount, uint32 twapWindow ) internal view returns (uint256 quoteAmount) { if (twapWindow == 0) revert InvalidTwapWindow(); (int24 arithmeticMeanTick,) = OracleLibrary.consult(pool, twapWindow); quoteAmount = OracleLibrary.getQuoteAtTick( arithmeticMeanTick, baseAmount, baseToken, quoteToken ); } ``` ### TWAP Window Selection | Window | Security | Latency | Use Case | |--------|----------|---------|----------| | 1 min | Low | Low | Not recommended | | 10 min | Medium | Medium | Fast-moving markets with monitoring | | 30 min | High | High | Lending protocols, collateral valuation | | 24 hr | Very high | Very high | Governance, long-term averaging | Shorter windows are cheaper to manipulate. For lending protocols, use 30+ minutes. ## Multi-Block TWAP Manipulation Post-merge, a single validator can propose consecutive blocks. With 2+ consecutive slots, a validator can manipulate a short TWAP without competition. **Defense**: Use longer TWAP windows (>30 min) or combine TWAP with Chainlink. ## Chainlink Integration ```solidity import {AggregatorV3Interface} from "@chainlink/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol"; error Oracle_StalePrice(address feed, uint256 updatedAt, uint256 maxAge); error Oracle_InvalidRound(uint80 roundId, uint80 answeredInRound); error Oracle_NegativePrice(int256 price); error Oracle_SequencerDown(); error Oracle_GracePeriod(); uint256 public constant MAX_STALENESS = 3600; // 1 hour function getChainlinkPrice(AggregatorV3Interface feed) internal view returns (uint256) { ( uint80 roundId, int256 answer, , uint256 updatedAt, uint80 answeredInRound ) = feed.latestRoundData(); if (answer <= 0) revert Oracle_NegativePrice(answer); if (updatedAt == 0) revert Oracle_StalePrice(address(feed), 0, MAX_STALENESS); if (block.timestamp - updatedAt > MAX_STALENESS) { revert Oracle_StalePrice(address(feed), updatedAt, MAX_STALENESS); } if (answeredInRound < roundId) { revert Oracle_InvalidRound(roundId, answeredInRound); } return uint256(answer); } ``` ### Chainlink Staleness by Feed Different feeds have different heartbeats. Match your staleness check to the feed's heartbeat. | Feed | Heartbeat | Suggested MAX_STALENESS | |------|-----------|----------------------| | ETH/USD (mainnet) | 1 hour | 3,600s | | BTC/USD (mainnet) | 1 hour | 3,600s | | USDC/USD | 24 hours | 86,400s | | Low-cap tokens | Varies | Check feed docs | ## L2 Sequencer Downtime On L2s (Arbitrum, Optimism), if the sequencer goes down and comes back up, stale prices may be used. Check the sequencer uptime feed. ```solidity AggregatorV3Interface public immutable SEQUENCER_UPTIME_FEED; uint256 public constant GRACE_PERIOD = 3600; // 1 hour function _checkSequencer() internal view { (, int256 answer, , uint256 startedAt,) = SEQUENCER_UPTIME_FEED.latestRoundData(); // answer == 0: sequencer is up // answer == 1: sequencer is down if (answer != 0) revert Oracle_SequencerDown(); uint256 timeSinceUp = block.timestamp - startedAt; if (timeSinceUp < GRACE_PERIOD) revert Oracle_GracePeriod(); } function getPrice(AggregatorV3Interface feed) external view returns (uint256) { _checkSequencer(); return getChainlinkPrice(feed); } ``` ## Sandwich Oracle Updates Attackers can watch the mempool for Chainlink oracle update transactions and sandwich them. ``` 1. See Chainlink update TX that will change ETH price from $2000 to $2100 2. Front-run: open leveraged long position at $2000 price 3. Oracle update executes: price becomes $2100 4. Back-run: close position at $2100, profit from the price jump ``` **Defense**: Use time-delayed oracle consumption or spread oracle updates over multiple blocks. ## Multi-Oracle Fallback ```solidity function getPrice() external view returns (uint256 price) { // Try Chainlink first try this._getChainlinkPrice() returns (uint256 chainlinkPrice) { return chainlinkPrice; } catch {} // Fallback to TWAP try this._getTwapPrice() returns (uint256 twapPrice) { return twapPrice; } catch {} revert Oracle_AllFeedsFailed(); } ``` ## Oracle Integration Checklist - [ ] No spot price usage for value calculations - [ ] Chainlink: staleness check with feed-appropriate threshold - [ ] Chainlink: negative/zero price check - [ ] Chainlink: `answeredInRound >= roundId` check - [ ] L2: sequencer uptime feed checked with grace period - [ ] TWAP: window >= 30 minutes for security-critical reads - [ ] Fallback oracle configured for primary feed failure - [ ] Oracle decimals handled correctly (Chainlink USD feeds = 8 decimals) - [ ] Price deviation circuit breaker for sudden large moves