T21 · Oracle

A Real-World Problem

You are building a collateralized lending contract. Users deposit token X and borrow a stablecoin.

The key rule is simple: collateral value must exceed the loan by a specified multiple. In code it is one line:

uint256 collateralValue = amount * getPrice(token) / 1e18;

The whole problem is hidden in getPrice. A contract has no network connection: it cannot make an HTTP request or read an exchange's order book. It can only read data that already exists onchain.

Is there an available onchain price? An AMM pool has one. Divide its reserves and you get a price, free and current, with no third party.

So you write:

function getPrice(address token) public view returns (uint256) {
    (uint256 r0, uint256 r1) = pair.getReserves();
    return r1 * 1e18 / r0;     // What is this line worth?
}

Bring back the final Lab from T19: doubling the price in a constant-product pool takes an input of roughly 41% of one side's reserve.

If the pool holds one million on that side, that is 410,000. It sounds expensive.

But the attacker does not need to own the 410,000. They can borrow it within one transaction, manipulate the price, borrow an excessive amount from your contract, move the price back, and repay the temporary loan. It all happens in one block. Required starting capital is nearly zero; fees are the main cost.

That single line can cost your contract every asset it holds.

Thought Experiment

Imagine your contract as a person locked in a windowless room with only a slit in the door.

Their job is to decide how much money to give visitors based on the gold price outside. They cannot see outside themselves.

Someone passes a note through the slit with a number on it.

Should they act on the number? First they need answers to four questions, which make up this chapter:

First, who wrote the note? If any passerby can put a note through the slit, the price is whatever the last passerby wrote. The person needs recognizable, approved sources.

Second, when was the note written? Without a time, they cannot distinguish a price from five seconds ago from one from three days ago. The latter can be fatal in a fast market.

Third, how far is it from the previous note? If yesterday said 100 and today says 10,000, this probably is not the market. It may be a prank or a failed source.

Fourth, what if no note arrives for a long time? Should they keep using the last one, stop working, or act conservatively?

None of these questions has a universally correct answer, but each needs an explicit answer in code. If you leave it unwritten, you choose a dangerous default.

Now consider the AMM pool. It is a note anyone can pay to rewrite, without even a timestamp.

Your Decision

Your lending contract needs a price. Which source do you choose?

What Happens

Compare the sources:

The cost column matters most. In one sentence:

There is no intrinsically “safe price source,” only a source whose manipulation cost exceeds the value extractable from it.

Make that a ratio, the most useful tool in this chapter:

Oracle safety margin = cost to manipulate the source / maximum value the attacker can extract

Less than 1   →  this configuration will eventually be attacked
Near 1        →  market or gas changes can reverse the margin
Far above 1   →  safe for now, but both numerator and denominator change over time

Note the denominator. It is not the protocol's total value locked, but the maximum withdrawable at this false price. Those can differ greatly. Even if an asset is just 1% of total deposits, if it can back a loan of the entire stablecoin pool, the denominator is the entire pool.

Also, neither numerator nor denominator is constant.

Liquidity migrates and a pool shallows, lowering the numerator. The protocol raises a collateral factor, increasing the denominator. A configuration that was safe at launch can become unsafe six months later without changing one line of code.

Build a Model

First examine the entire pipeline and how each part can fail:

You must understand four parameters for each price source. They are configurable, and vary greatly across sources, assets, and chains. The table gives only rough ranges; look up actual numbers yourself in the Lab's first step:

The last row deserves attention. Some feeds have upper and lower limits by design. When the real price leaves the range, the feed returns a boundary value, not reality, and the API response still looks normal. A fresh timestamp alone will not catch it.

Put four checks in code:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IPriceSource {
    // Return the price and the time when this price was produced
    function latest() external view returns (int256 price, uint256 updatedAt);
}

contract PriceGuard {
    IPriceSource public source;
    uint256 public maxStaleness;   // Maximum allowed age, usually a multiple of heartbeat
    uint256 public minPrice;       // Plausible lower bound
    uint256 public maxPrice;       // Plausible upper bound
    uint256 public maxJumpPercent; // Maximum jump from last trusted price, as a percentage

    uint256 private lastGoodPrice;
    uint256 private lastGoodAt;

    error StalePrice(uint256 age);
    error PriceOutOfRange(uint256 price);
    error PriceJump(uint256 from, uint256 to);

    function readPrice() public view returns (uint256) {
        (int256 raw, uint256 updatedAt) = source.latest();

        // Check one: reject zero and negative values
        if (raw <= 0) revert PriceOutOfRange(0);
        uint256 price = uint256(raw);

        // Check two: reject stale values
        uint256 age = block.timestamp - updatedAt;
        if (age > maxStaleness) revert StalePrice(age);

        // Check three: reject values at the aggregator's bounds
        if (price <= minPrice || price >= maxPrice) revert PriceOutOfRange(price);

        // Check four: limit jumps relative to the last trusted price
        if (lastGoodPrice > 0) {
            uint256 hi = price > lastGoodPrice ? price : lastGoodPrice;
            uint256 lo = price > lastGoodPrice ? lastGoodPrice : price;
            if ((hi - lo) * 100 > lo * maxJumpPercent) revert PriceJump(lastGoodPrice, price);
        }

        return price;
    }
}

Of the four, the third is most often missed; the fourth is most debatable.

The fourth check is debatable because real markets really can gap by tens of percent at once. Set the threshold too tightly and you reject every price precisely when liquidations need one, creating bad debt. There is no universal value; you balance manipulation resistance against availability.

More important than all four is what your contract does when data is unavailable. There are three basic choices, and you must select explicitly:

The easiest mistake is a blanket revert. It appears safest, but freezes liquidation just when the feed fails, often during a volatile market when liquidation is most needed.

Classify operations instead: risk-increasing actions require a fresh price; risk-reducing actions should remain possible without one.

What It Is Called

Hands-on

Scenario: your contract values token X using one pool's spot price
          The pool has depth D on one side; your contract has L stablecoins to lend
          Collateral factor c (e.g. 0.75 means 100 of collateral backs 75 of debt)

Step 1: To raise X's reported price to m times its initial level, required input
        is approximately D * (sqrt(m) - 1)

Step 2: With X worth V at its true price, the attacker can borrow at the false price
        min(V * m * c, L)

Step 3: Net attack cost
        Funds used to move the pool can be borrowed and repaid in the same transaction;
        initial principal needed is near zero
        Actual cost = fees on two swaps + gas + flash-loan fee
        approximately D * (sqrt(m) - 1) * 0.6% + other costs

Step 4: Profit = Step 2 - Step 3 - the collateral's true value

Step 5: Safety margin = Step 3 / Step 2

AI Lab

Step one:
A lending protocol values collateral using the instant reserve ratio in a
constant-product pool. The pool has depth D on one side; the protocol can lend L.
Describe the full attack and derive a cost formula that accepts actual numbers.

Step two:
Replace that source with a TWAP from the same pool over N blocks.
Derive manipulation cost again. How many times higher is it than Step one,
and on what assumptions does that multiple depend?

Step three:
List five risks still present in the Step two design. Rank them by
probability of loss times loss size, and give a detectable signal for each.

Real-World Case

Change One Variable

Takeaway Questions

Chapter Check