Skip to content
log(swap)

State and the ladder

Log price is the working coordinate

The C-pool stores x=log⁡px = \log p. The F-pool derives each xjx_j from its reserves and uses the weighted average xˉ=∑jwjxj\bar x = \sum_j w_j x_j for its composite index (compositeX in the lens). Its log-floor is ξˉ=xˉ−Q/L\bar\xi = \bar x - Q/L (logFloor); for one base these reduce to xx and ξ\xi. 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.

fieldwhat it is
xcurrent log price (WAD), bounded by MAX_ABS_FLOOR = 46e18
lActive∑\sum signed dL over crossed ticks; ≥0\ge 0 cumulatively, never per-tick
reserveBase, reserveQuoteaccounting shadows — see below
Ffee-per-LL accumulator =ϕ TV(log⁡p)= \phi\,\mathrm{TV}(\log p) plus mint-fee point masses
bigSigmaΣ=∫(dx)2\Sigma = \int(dx)^2 — pairs with F for the model-free edge F−12ΣF - \tfrac12\Sigma
sigma2Ema, blockVar, lastVarBlockthe variance kernel: one observation per swap, folded per block, decaying on silent blocks
currentKthe crossed-set pointer — maintained, never derived from x
protocolOwed, minBackstopL, backstopFloor, backstopSeededthe mint-fee cut and the permanent backstop lock
ticks[k], tickBitmap[word]the ladder, keyed by compressed index k=ξ/δξk = \xi/\delta_\xi

Ticks are keyed by kk, not by raw tick. That is deliberate: kk 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 kk. Insert and remove are one SSTORE; search walks a 256-bit word at a time, and measures flat in ladder depth against O(n)O(n) 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 xx, because a tick sitting exactly at xx 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 k−1k-1 after a buy, down to kk 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 xx 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 δξ\delta_\xi 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 +L+L at its floor and −L-L at its cap on the same ladder. Tick deltas are signed, and La≥0L_a \ge 0 is cumulative rather than per-tick, since every position credits at ξ\xi before debiting at μ>ξ\mu > \xi.

Aggregate base is

Rtotal=Lap+D,R_{\text{total}} = \frac{L_a}{p} + \mathcal{D},

where D\mathcal{D} — 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 {x>μ}⊂{x>ξ}\{x > \mu\} \subset \{x > \xi\} 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 LaL_a from vanishing when price crosses every cap.

Because "crossed" is still exactly k<xk < x, the crossed ticks remain a prefix of the sorted ladder: one index locates both crossing boundaries, and the O(1)O(1) 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: ∑pools\sum_{\text{pools}} shadow ++ claimsOutstanding[token] ≤\le balanceOf(manager)