oracle-flashloan-analysis

# Oracle & Flash Loan Analysis

Detect vulnerabilities where **external price data can be manipulated** or **flash loans can exploit protocol logic** within a single transaction. These two attack vectors are often combined and represent the most common DeFi attack pattern.

## When to Use

- Auditing any DeFi protocol that reads external price data (lending, DEX, derivatives, yield aggregators)
- Reviewing Chainlink, Uniswap TWAP, Band Protocol, or custom oracle integrations
- Analyzing protocols that interact with or are accessible via flash loans
- Threat modeling for MEV, sandwich attacks, and price manipulation
- When a protocol uses `balanceOf()`, pool reserves, or spot prices for critical calculations

## When NOT to Use

- Contracts with no price dependencies or external data feeds
- Pure access control analysis (use semantic-guard-analysis)
- State-to-state invariant checking (use state-invariant-detection)

## Core Concept: The Oracle Trust Hierarchy

Not all price sources are equally secure. Oracle vulnerabilities stem from the gap between **assumed trust** and **actual manipulation resistance**.

```
Trust Level (highest to lowest):
┌─────────────────────────────────────────────┐
│ Level 5: Multi-oracle consensus + circuit    │
│          breakers + TWAP + staleness checks  │
├─────────────────────────────────────────────┤
│ Level 4: Chainlink with full validation      │
│          (staleness, sequencer, min answers)  │
├─────────────────────────────────────────────┤
│ Level 3: Uniswap V3 TWAP (long window)      │
│          Multi-block manipulation cost        │
├─────────────────────────────────────────────┤
│ Level 2: Uniswap V2 TWAP (short window)     │
│          or Chainlink WITHOUT staleness check │
├─────────────────────────────────────────────┤
│ Level 1: Spot price from single pool         │ ← Manipulable via flash loan
│          or balanceOf() for pricing           │
└─────────────────────────────────────────────┘
```

## The Four-Phase Detection Architecture

### Phase 1: Oracle Source Identification

Locate every point where the contract reads external price/value data.

**Search for these patterns:**

| Pattern | Oracle Type | Risk Level |
|---------|------------|------------|
| `latestRoundData()` | Chainlink | Medium (depends on validation) |
| `latestAnswer()` | Chainlink (deprecated) | HIGH (no round validation) |
| `observe()` / `consult()` | Uniswap TWAP | Medium (depends on window) |
| `getReserves()` | AMM spot price | **CRITICAL** (flash-loan manipulable) |
| `balanceOf(address(this))` | Self-balance | **CRITICAL** (donation attack) |
| `slot0()` / `sqrtPriceX96` | Uniswap V3 spot | **CRITICAL** (single-block manipulable) |
| Custom `getPrice()` | Unknown | Requires investigation |

**Build an Oracle Dependency Map:**

```
Contract: LendingPool
├── borrowLimit() → uses getCollateralPrice()
│   └── getCollateralPrice() → calls chainlinkOracle.latestRoundData()
├── liquidate() → uses getDebtPrice()
│   └── getDebtPrice() → calls uniswapPool.slot0() ← SPOT PRICE!
└── calculateInterest() → uses getUtilizationRate()
    └── getUtilizationRate() → reads internal state (safe)
```

### Phase 2: Oracle Validation Verification

For each oracle source, verify that proper safety checks are in place.

**Chainlink Validation Checklist:**

```solidity
// COMPLETE Chainlink integration
(uint80 roundId, int256 price, , uint256 updatedAt, uint80 answeredInRound) =
    priceFeed.latestRoundData();

require(price > 0, "Invalid price");                    // Check 1: Non-negative
require(updatedAt > 0, "Round not complete");            // Check 2: Round complete
require(answeredInRound >= roundId, "Stale price");      // Check 3: Not stale
require(block.timestamp - updatedAt < HEARTBEAT,         // Check 4: Fresh
        "Price too old");

// L2-specific
require(!sequencerFeed.isDown(), "Sequencer down");      // Check 5: L2 sequencer
require(block.timestamp - sequencerUptime > GRACE,       // Check 6: Grace period
        "Grace period");
```

**Missing Check Severity:**

| Missing Check | Severity | Impact |
|---------------|----------|--------|
| `price > 0` | HIGH | Zero/negative price → infinite borrowing or free liquidations |
| `updatedAt > 0` | MEDIUM | Incomplete round data used |
| `answeredInRound >= roundId` | HIGH | Stale price from previous round |
| Heartbeat/freshness | HIGH | Hours-old price during volatile markets |
| L2 sequencer check | HIGH | Stale price during L2 outage → unfair liquidations |
| Price deviation bounds | MEDIUM | Extreme outlier not filtered |

**TWAP Validation:**

```
Window length analysis:
  - < 10 minutes: HIGH RISK — manipulable with moderate capital
  - 10-30 minutes: MEDIUM RISK — expensive but feasible multi-block manipulation
  - 30+ minutes: LOWER RISK — requires sustained pool manipulation
  - Check: Is the TWAP window configurable? Can governance reduce it?
```

### Phase 3: Flash Loan Attack Surface Analysis

Identify operations that can be exploited via flash loan atomicity.

**Flash Loan Attack Model:**

```
Single Transaction:
  1. Borrow N tokens via flash loan (Aave, dYdX, Balancer)
  2. Manipulate price source (swap in pool, donate to contract)
  3. Exploit protocol at manipulated price (borrow, liquidate, swap)
  4. Reverse manipulation (swap back)
  5. Repay flash loan + fee
  6. Profit = exploited_value - flash_loan_fee - gas
```

**Detection Algorithm:**

```
For each function F that reads price/value data:
  1. Identify the price source S
  2. Can S be manipulated within a single transaction?
     - Spot price from AMM → YES (swap in same tx)
     - balanceOf(address(this)) → YES (donate tokens)
     - Chainlink feed → NO (off-chain updates)
     - TWAP → DEPENDS (short window = risky)
  3. What does F do with the price?
     - Determines borrowing limit → CRITICAL
     - Triggers liquidation → CRITICAL
     - Sets exchange rate → HIGH
     - Informational only → LOW
  4. Is the manipulation profitable?
     -