TWAP oracles
Suggest an editChainlink doesn't have a feed for every asset, and even when it does, sometimes you want an oracle that lives inside your own protocol, on the same chain, with no external dependency. The pattern that makes that workable is the time-weighted average price, or TWAP.
To move a time-weighted average, the attacker has to hold the price
The flash loans lesson showed that a pool's spot price can be pushed away from the market and exploited inside one transaction, with borrowed capital.
Take the average price over a window of time instead of the instantaneous price. If the window is 30 minutes, then to manipulate what the oracle reports, the attacker has to keep the pool's price away from the true market price for roughly 30 minutes. A flash loan cannot do that, because it has to be repaid in the same transaction.
The average weights each price by how long it held. A price that is pushed up and brought back inside one transaction held for zero seconds, so it has no weight in the average. If the attacker leaves the price in place and arbitrageurs correct it in the next block, it held for one block. Averaged over a 30-minute window (roughly 150 blocks on Ethereum), the contribution of that single block to the average is about 0.7%. Even a 100% price spike for one block barely shifts the average, so the protocol reading the TWAP sees a number very close to the real market price.
Leaving the price in place takes the attacker's own capital, because the flash loan is repaid before the transaction ends. Holding the price for more blocks costs money in each of them. Arbitrageurs sell into the pool at the fake price and take the profit, and the attacker has to push the price up again.
The longer the TWAP window, the more blocks of manipulation the attacker has to sustain, and the more they lose to arbitrageurs during that time. 5-minute windows have been broken by determined attackers with deep liquidity behind them. 30-minute and longer windows have generally held up, but only against pools with reasonable trading volume.
How the math works without storing every price
The naive way to compute an average price over time is to store every observation. Every time the pool's price changes, write down the new price along with the timestamp. To compute the average at any point, sum the stored prices weighted by how long each one held, and divide by total time.
This is unworkable on chain. Each observation is a storage write. Active pools change price many times per block. Storing every observation would make every swap dramatically more expensive, and the contract would have to keep paying for unbounded storage.
Instead of storing each individual price, store a single running total: the integral of price over time, priceCumulative. Every time the pool's price changes, do one update: add oldPrice × (now − lastUpdate) to the accumulator, then set lastUpdate = now. That's one storage slot, one read, one write per change.
Say the price is 10 for 60 seconds and then 12 for 40 seconds. The first update adds 10 × 60 = 600 and the second adds 12 × 40 = 480, so the total grows by 1,080 over 100 seconds. The average price is 1,080 / 100 = 10.8.
To compute the average price between two times T₁ and T₂, you don't need to know any of the prices in between. You only need the value of priceCumulative at those two times. The average is:
TWAP[T₁, T₂] = (priceCumulative(T₂) - priceCumulative(T₁)) / (T₂ - T₁)Each segment of the cumulative curve has a slope equal to the price during that segment. The average price between two times is the slope of the straight line connecting the two endpoints. The pool's priceCumulative works like an odometer. The pool tells you "total price-time so far". You sample it twice and divide to get average speed.
To use it as an oracle, your contract has to do two things:
- Read
priceCumulativeat the moment you want the window to start, and store that value. - Wait the window duration. Then read
priceCumulativeagain, subtract, and divide by elapsed time.
Step 1 is sometimes called "taking an observation." It's the only thing you store on your side. The pool stores the running total.
Uniswap V2's implementation
Uniswap V2 was the first AMM to introduce this design. The relevant additions to the Pair contract are two cumulative prices and the timestamp of the last update:
uint256 public price0CumulativeLast;
uint256 public price1CumulativeLast;
uint32 private blockTimestampLast;These are updated inside the pair's _update() function, which is called on every swap, mint, and burn. The update is:
uint32 timeElapsed = blockTimestamp - blockTimestampLast;
if (timeElapsed > 0 && reserve0 != 0 && reserve1 != 0) {
price0CumulativeLast += uint(UQ112x112.encode(reserve1).uqdiv(reserve0)) * timeElapsed;
price1CumulativeLast += uint(UQ112x112.encode(reserve0).uqdiv(reserve1)) * timeElapsed;
}Each update adds the price that stood before it, the oldPrice of the rule above. All transactions in a block share one timestamp, so timeElapsed is zero for every update after the first one in a block, and those updates add nothing. A price that is created and removed inside one transaction therefore never reaches the cumulative.
The prices are stored in a fixed-point format called UQ112x112, which encodes fractions as integers by scaling everything up by 2^112, because Solidity has no native decimals. Any contract reading these cumulatives has to shift the result back down by 112 bits before interpreting it.
Two cumulatives exist because each token in the pair can be priced in the other. price0CumulativeLast accumulates how much of token1 a unit of token0 buys, and price1CumulativeLast is the inverse.
This update only happens when someone trades or modifies liquidity. If nobody touches the pair for ten minutes, the cumulative doesn't move during those ten minutes, although the last price the pair recorded held all that time and should have contributed to the cumulative.
So anyone reading TWAP computes what the cumulative would be if it were updated now, by taking the stored cumulative and adding lastPrice × (block.timestamp - blockTimestampLast). Uniswap's UniswapV2OracleLibrary.currentCumulativePrices() helper does this, so reading current TWAP doesn't require triggering a trade to refresh the pair.
A reader contract
A minimal V2 TWAP consumer maintains its own observation and computes the average against the pair's current cumulative. Its constructor, not shown here, stores the pair and takes the first observation.
contract SimpleV2TWAP {
IUniswapV2Pair public immutable pair;
uint256 public constant PERIOD = 30 minutes;
uint256 public price0CumulativeLast;
uint32 public blockTimestampLast;
uint224 public price0Average; // UQ112x112 format
function update() external {
(uint256 price0Cumulative, , uint32 blockTimestamp) =
UniswapV2OracleLibrary.currentCumulativePrices(address(pair));
uint32 timeElapsed = blockTimestamp - blockTimestampLast;
require(timeElapsed >= PERIOD, "period not elapsed");
price0Average = uint224((price0Cumulative - price0CumulativeLast) / timeElapsed);
price0CumulativeLast = price0Cumulative;
blockTimestampLast = blockTimestamp;
}
function consult(uint256 amountIn) external view returns (uint256 amountOut) {
// price0Average is in UQ112x112 divide by 2^112 to use it as an integer ratio.
return (uint256(price0Average) * amountIn) >> 112;
}
}Anyone calls update() at most once per period. consult() then returns the most recently computed average for any input amount. A consumer can call consult() thousands of times against a single stored observation without paying for any oracle work.
Nothing calls update() by itself. Someone has to send that transaction every period, and the keepers lesson covers who that can be. If nobody does, consult() keeps returning the last stored average however old it is, so a consumer should check blockTimestampLast the way it checks updatedAt on a Chainlink feed. Until the first update() succeeds, price0Average is zero and consult() returns 0. blockTimestampLast already holds the deployment time by then, so the consumer has to reject a zero average too.
What TWAP doesn't solve
TWAP changes the economics of manipulation, but it does not eliminate manipulation.
A TWAP is only as deep as its underlying pool. If the pool has low liquidity, the cost of moving the price for a few blocks can be small enough that even a 30-minute window is affordable to attack. TWAP shifts the manipulation budget upward, but it doesn't make a thinly traded pool safe to read.
TWAP lags the real price, because it averages prices that are up to a full window old. If you need to know the actual current price, TWAP isn't the right oracle. Use it for collateral valuation, liquidation thresholds, fee calculations, anything that benefits from stability and can tolerate latency. Don't use it for "what price do I quote this swap at" because the answer will be wrong by minutes.
A pool that nobody trades in reports its last price. The computed extension uses whatever the last trade's price was for the whole idle period, and that price might already be far from the true market.
Choosing the right window is a tradeoff. Shorter windows track price changes more quickly but are cheaper to manipulate. Longer windows are harder to attack but lag farther behind the real market. Lending protocols using TWAP typically pick 10 minutes to 1 hour depending on volume and risk tolerance.
Two-token denomination. A V2 TWAP gives you the price of one token in the pair, denominated in the other. ETH/USDC tells you the ETH price in USDC. To get "ETH/USD" you have to either trust that USDC equals USD (usually fine, sometimes not) or chain multiple TWAPs together. Chainlink feeds give you USD directly because they aggregate across markets.
When to use TWAP
Chainlink price feeds are the right answer when they're available, because they aggregate across exchanges and don't depend on any single pool's liquidity. TWAP fills three specific gaps.
The first is long-tail assets without Chainlink coverage. If you're building a protocol that takes some obscure ERC-20 as collateral, there's no feed for it. The TWAP of its largest liquid pool is the best you can do.
The second is internal protocol pricing of derived assets. Pricing LP tokens, liquid staking tokens, or any token whose value is defined by an on-chain protocol is something TWAP can do that off-chain oracles can't. The canonical source of truth is the on-chain math, and TWAP just gives you a smoothed read of it.
The third is cross-checks. Production protocols sometimes consume both a Chainlink price and a TWAP, and revert if they diverge significantly. The TWAP catches the rare case where a Chainlink feed is misconfigured, suspended, or otherwise wrong, while Chainlink catches the case where the pool is thinly traded or under attack.
Before you rely on a TWAP, estimate what it costs to hold that pool's price away from the market for the whole window, and compare it with what an attacker could take from your protocol at the moved price.