Oracle: The Observation Ring Buffer

Key takeaway: V3's oracle stores its own history. A ring buffer of up to 65535 Observation structs lives inside the pool, each recording tickCumulative (tick-seconds since initialization) and secondsPerLiquidityCumulativeX128. Because tick is log1.0001(price), the arithmetic mean of tick over a window is the geometric mean of price — a TWAP that is symmetric between token0 and token1 and cheap to read: two accumulator values and one subtraction. Anyone who wants a longer history calls increaseObservationCardinalityNext and pays the SSTOREs themselves; grow pre-warms the new slots with blockTimestamp = 1 so future swappers pay a cheap nonzero-to-nonzero store instead of a 20k fresh one. All the timestamp math wraps at 2^32 by design, which in Solidity 0.8 means it must live inside unchecked blocks.

What You Are Building

The Oracle library: transform, initialize, write, grow, getSurroundingObservations, observeSingle, and observe — plus the two pool-side entry points, observe and increaseObservationCardinalityNext. The comparator lte and binarySearch are provided; you implement everything that reads and writes the ring buffer around them.