TWAP oracle

The TWAP hook turns a pool into an on-chain price record. Its swap callbacks write the pool's tick over time, and reading a time-weighted mean is one view call.

What it stores#

A ring of 32 observations per pool, each a timestamp and the cumulative tick up to that moment. The cumulative tick grows by the current tick for every second the price sits there. History reaches back to the oldest of the 32 observations.

Reading it#

observe(PoolKey key, uint32 secondsAgo)

observe returns the mean tick over the last secondsAgo seconds. It is a view, so any contract can read it and anyone can call it off chain without a transaction. Pass the pool's full key; the hook keeps a separate ring for each pool.

From tick to price#

A tick is a price on a fixed grid. In a v4 pool, the price is currency1 per currency0 in raw units:

price = 1.0001^mean_tick

For a human price, scale by the tokens' decimals:

price (currency1 per currency0) = 1.0001^mean_tick × 10^(decimals0 − decimals1)

A mean of ticks is a geometric mean of prices. It is this pool's own price record.

Flags#

The hook has afterInitialize, beforeSwap and afterSwap, plus afterAddLiquidity, afterRemoveLiquidity and both of their returns-delta flags for the buyback share. It has no swap returns-delta flag, so it never changes a swap's amounts.