State and the ladder
Log price is the working coordinate
The C-pool stores . The F-pool derives each from its reserves and uses the
weighted average for its composite index (compositeX in the lens).
Its log-floor is (logFloor); for one base these reduce to and .
By I2, the quote leg is linear in the relevant log-price coordinate.
Per-market state
pools[poolId] carries only what evolves. Anything in the key never touches storage.
| field | what it is |
|---|---|
x | current log price (WAD), bounded by MAX_ABS_FLOOR = 46e18 |
lActive | signed dL over crossed ticks; cumulatively, never per-tick |
reserveBase, reserveQuote | accounting shadows — see below |
F | fee-per- accumulator plus mint-fee point masses |
bigSigma | — pairs with F for the model-free edge |
sigma2Ema, blockVar, lastVarBlock | the variance kernel: one observation per swap, folded per block, decaying on silent blocks |
currentK | the crossed-set pointer — maintained, never derived from x |
protocolOwed, minBackstopL, backstopFloor, backstopSeeded | the mint-fee cut and the permanent backstop lock |
ticks[k], tickBitmap[word] | the ladder, keyed by compressed index |
Ticks are keyed by , not by raw tick. That is deliberate: is what the bitmap, the pointer
and the id all speak, so every keyless path — notably the ERC-6909 transfer hooks, which receive only
an id — can do fee accounting without needing tickSpacing.
The ladder: a bitmap and a pointer
Live floors are one bit each over compressed indices . Insert and remove are one SSTORE;
search walks a 256-bit word at a time, and measures flat in ladder depth against for a sorted
array — 2.5–4.8× faster at depth 100.
The crossed set is maintained, not derived. A currentK pointer tracks it rather than
recomputing it from , because a tick sitting exactly at is ambiguous: crossing up should count
it, crossing down should not. A pointer has a history; a comparison does not.
A swap can also end on a grid point without crossing a tick, because it ran out of input there or because rounding carried the mark onto it. The pointer is then seated after the walk: up to after a buy, down to after a sale, and never the other way, which would undo a crossing. A floor minted next, between the old pointer and the mark, is then counted as active. A segment that does not cross a tick stops at it at most, whatever the rounding of its displacement (decision 103).
The bitmap indexes the coarse LP ladder only. Liquidity changes at LP boundaries, and moves
continuously between them — the price state itself is carried at full WAD precision, exactly as v3
carries sqrtPriceX96. A separate price-state tick grid was proposed and not adopted; only the
floor-ladder spacing is load-bearing, and it is deliberately coarse because
two-class blending covers the gaps exactly.
One signed ladder carries caps
A capped class writes at its floor and at its cap on the same ladder. Tick deltas are signed, and is cumulative rather than per-tick, since every position credits at before debiting at .
Aggregate base is
where — the frozen holdings of not-yet-crossed legs — goes negative while short legs are dormant, and returns to zero once every cap has been crossed.
Since pointwise in time, a capped position's credit minus debit is monotone and it cannot owe fees. A permanently locked uncapped class — the backstop — keeps from vanishing when price crosses every cap.
Because "crossed" is still exactly , the crossed ticks remain a prefix of the sorted ladder: one index locates both crossing boundaries, and the crossing survives the cap unchanged.
Reserve shadows, and why they survived
The migration plan intended to drop reserveBase/reserveQuote v4-style, on the reasoning that the
transient deltas are the accounting. Porting showed that to be wrong for this design, and the
reversal is worth stating because it looks like redundancy until you see what it does.
Three clamps read them: the burn payout clamp, the fee-sweep clamp, and the exact-out quote bound. In a per-pool world those clamps only ever bounded a pool against itself. In a singleton they are what stops one market's rounding dust from being paid out of another market's backing. They are the pool-isolation mechanism, not bookkeeping.
The shadow reserveBase must also stay on the curve: it may not fall under the reserve the mark
implies, or the buy that asks for that reserve reverts. The C swap therefore moves it by the same
derivation as a mint does. The base leg of a quote-specified swap is the reserve at one mark minus the
reserve at the other, and a swap that crosses a tick moves the mark by the tick distance on both legs.
See Numerics and verification.
So they stay — as shadows, never as token balances. The physical truth is the manager's balance, and solvency is a tested invariant rather than stored state:
for each token: shadow
claimsOutstanding[token]balanceOf(manager)