Skip to content
log(swap)

The F-pool

Fungible. One floor shared by every share, nn bases against one quote.

Give every share the same floor. Claims are then homogeneous — every unit interchangeable — and the floor-translation identity does the whole accounting.

We write xˉ\bar x and ξˉ\bar\xi for the multi-asset weighted average log-price and log-floor. For one base these reduce to x=log⁡px = \log p and ξ\xi. The lens exposes them as compositeX and logFloor; see Notation.

The floor is the fee accumulator

A fee accrues to all shares at once as Δ ξˉ=−feeValue/L\Delta\,\bar\xi = -\text{feeValue}/L, so

ξˉ=ξˉ0−F.\bar\xi = \bar\xi_0 - F .

It is not stored but derived, ξˉ=xˉ−Q/L\bar\xi = \bar x - Q/L, from reserves on every read. Accrual is denomination-blind: a quote fee lands in QQ at fixed xˉ\bar x; an in-kind base fee marks the derived index down by its value per unit LL. Base-for-base charges 2ϕ2\phi — both legs were repriced — which makes fees route-invariant.

This removes the fee-growth accumulator, the per-tick snapshots, the per-holder fee slots and the collect-swap-remint cycle; only a harvest's payout is settled per holder. Fees remain invested without a separate compounding transaction.

The floor has one lever

Raising ξˉ\bar\xi at fixed LL and xˉ\bar x leaves RjR_j untouched and releases L Δ ξˉL\,\Delta\,\bar\xi in pure quote — price-neutral, pro rata, no base sold. The pool simply stops bidding below the new floor. That is harvest, the operator's one lever; nothing puts quote back under a live generation — only fee income lowers the floor, and a deeper bid is a relaunch (below).

directioneffect
fees accrue, ξˉ↓\bar\xi \downarrowquote deployed as deeper bid; share value rises
harvest, ξˉ↑\bar\xi \uparrowthe deepened bid converted back to extractable quote, pro rata

So harvest is the exact mirror of accrual, and restoring the floor to ξˉ0\bar\xi_0 pays out precisely L FL\,F — the fees earned, to the wei, with no accumulator ever having been written.

A harvest is a dividend to every share: each holder's part is settled lazily on their next transfer, mint or burn, and the operator's own is pushed at once. How far it may go is the pool's policy: on a pad the harvest returns the floor to the reference floor ξˉ0\bar\xi_0 and never past it, so only income can leave; a POL keeps a quote buffer the protocol sets (keepQuote of LL, zero unless set); a private or public pool may take the bid to zero. A harvest takes no protocol cut. At ξˉ=xˉ\bar\xi = \bar x the pool holds no quote and has no bid — the state a relaunch starts from (see Generations).

The mark is not writable

xˉ\bar x is derived from reserves and moved only by trades, so no balance-sheet operation lowers the ask. Within this design there is no path by which an operator lowers the floor and then buys the book — which is the property that makes a pool safe to hand to a creator at all.

Re-marking upward is not free either. Refilling while the floor sits a gap gg below the mark costs

L(g−1+e−g)  ≈  12Lg2,L\big(g - 1 + e^{-g}\big) \;\approx\; \tfrac12 L g^2,

quadratic in the gap and independent of refill depth.

Fee income deepens the floor

Because ξˉ=ξˉ0−F\bar\xi = \bar\xi_0 - F, every swap that touches the pool pushes the floor down by fee/L\text{fee}/L. Volume deepens the bid with no new mechanism and no new capital. The one case the mechanism cannot reach is price sitting at the floor in a falling market — no bid, so no trades, so no fees, so no deepening. That is a floored position that got filled on the way down: the risk the LP chose, not a defect to engineer away.

Four policies, one contract

The basket and the launch are the same contract. What separates the products is the pool's policy: the contract its key names at birth, which the manager asks every question it does not decide itself — who may seed, harvest, retire or reshape, whether a taker may swap, the terms of every harvest. The policy also says what the pool is, through kind(): "public", "private", "pol" or "pad". There is no kind in the key and none on the manager; the policy is the kind, and nothing in the mathematics distinguishes the products.

publicprivatePOLpad
what it isthe protocol's own poola deska treasury's poola launch
creatorthe protocol's fee collectora desk, market maker or foundationa treasury or governancea token creator
bases1 to 81 to 8oneone
gates, lists, operator—yes——
compositionfixededitable between generationsfixedfixed
harvestto an empty bidto an empty biddown to the keepQuote bufferincome only
the seed's sharesthe seeder'sthe seeder'sthe seeder'sminted to 0xdead
retireat an empty bidat an empty bidat an empty bidrefused: a pad never retires
regeneraterefusedthe authority carriedthe authority carriedthe graduation: 0xdead carried

Private → POL → pad is a ladder of rigidity: a POL is a private pool without the desk and the gates; a pad is a POL with two locks, the seed burned at birth and a harvest of income only. A public pool is a POL born to the protocol. A policy must be approved in the protocol's PolicyRegistry before a pool can be born under it, and the class is fixed for the pool's life.

The basket (n>1n > 1, public or private) is inventory as one share: auto-rebalanced to constant value weights (pjRj≡wjLp_jR_j \equiv w_jL), any leg pullable by base-to-base without quote and without touching the floor, single-sided entry and exit by zap. It is workable lending collateral, since V=L(1+xˉ−ξˉ)V = L(1 + \bar x - \bar\xi) is affine in xˉ\bar x — so liquidation is a tick on the index. See Basket holder.

The launch (a pad) sells the floor itself: a bid that is structural rather than promised, deepening from fee income, which the creator can harvest only up to the income earned — and that income banks as a pot released only at a graduation: the creator's share, the protocol's, a buyback of the token, and the rest deepening the bid. See Token creator.

A capped pool sets a cap dd in its key: the pool sells its whole inventory between the floor and a cap price ede^{d} times the floor, so it works its capital λ=1/(1−e−d)\lambda = 1/(1 - e^{-d}) times harder at the floor (λ=2\lambda = 2 puts the cap at twice the floor). Every price reads a phantom reserve per leg; only real tokens move (decision 061, specs/f-pools/capped.md).

Who runs the pool

  • The creator is who the pool was born to: the key's creator, and its first authority.
  • The authority owns the pool: it seeds each generation, names it, and hands itself over in two steps (proposeAuthority / acceptAuthority, on the policy). On a private pool it also works the desk: setGates turns the mint and swap gates on or off, and two lists say who may mint and swap (setMinters) and who may only swap (setTakers).
  • The operator runs the pool: harvest, retire, regenerate and, on a private pool, setLegs. It is the authority unless a private pool appoints one (appointOperator, then acceptOperator), and a handover of the authority voids it.

Every operator action closes the swap for the rest of its block. A governance contract can sit in any slot; nothing about the surface assumes an EOA.

A harvest is price-neutral and pro rata — it moves no base, changes no price, and pays each holder exactly their share, so there is no value to steal and the flash-loan-to-drain shape does not apply. What an operator can force is a policy, not a transfer: strip the pool's downside bid and leave the next seller facing a thin book. Real, but bounded, and borne pro rata by every share.

Generations

Every share id carries the pool's generation. Two operator entries close one generation and open the next, and neither moves the price or the floor.

  • retire is the boundary. At an empty bid (Q≤L/109Q \le L/10^9) it freezes the whole generation into a bundle that every share redeems pro rata, forever. The authority then seeds the next generation — with a new composition if a private pool's operator setLegs in between. A pad refuses it: a pad sold back to its floor stays live, trades, earns and can graduate again.
  • regenerate is the generation step. It harvests the generation's income, then the policy names one holder to carry into the next generation. That holder and 0xdead go on; every other holder is frozen out pro rata into the old generation's bundle, at the marks, keeping the dividend it earned. On a pad this is the graduation: 0xdead is carried, the pot is released, and the reference floor resets. A POL or a private pool carries its authority. A public pool refuses it, because its outside LPs are the pool.

A holder frozen out redeems in kind (redeem) or rolls its claim into the live generation through the router (rollIn).

Market identity and surface

struct PoolKeyF {
    address   quote;
    address[] bases;    // sorted, unique asset table
    uint256   swapFee;  // fixed swap fee, WAD
    address   policy;
    address   creator;
    bytes32   salt;
    uint256   mintFee;  // fixed mint fee, WAD
}

initialize(key) returns the poolId, keccak256(abi.encode(key)); anyone may call it, and the policy checks the rest of the key (the fee's range and tier, a listed quote, one base on a POL or a pad, a zero salt on a public pool). seed is the authority's and opens a generation.

// trade — `taker` is who the caller trades for, checked on a gated pool
swapQuoteIn(poolId, j, amountIn, minOut, taker)
swapBaseIn(poolId, j, amountIn, minOut, taker)
swapBaseForBase(poolId, j, k, amountIn, minOut, taker)   // ΔQ = 0, crosses nothing
 
// enter and exit
mint(poolId, to, dL, maxQuoteIn)      burn(poolId, owner, shares, minQuoteOut)
router.zapIn(poolId, dL, maxQuoteIn, minShares, to, deadline)
router.zapOut(poolId, shares, tokenOut, minOut, to, deadline)
claim(poolId, gen, to)                                   // a settled dividend
 
// the operator: the authority by default, or appointed on a private pool
harvest(poolId, amount, to)   regenerate(poolId, to)   retire(poolId)
setLegs(poolId, weights[], newBases[])                   // private only, between generations
 
// the authority
seed(poolId, L0, r0[], Q0)
 
// on the pool's policy
proposeAuthority / acceptAuthority   setName
appointOperator / acceptOperator   setGates   setMinters   setTakers   // private only
 
// generations
redeem(poolId, gen, owner, shares)
router.rollIn(poolId, gen, shares, dL, maxQuoteIn, minShares, to, deadline)
 
// a lien, for lending: the locker locks an owner's shares in place
lock(id, owner, amount)       unlock(id, owner, amount, to)   // to = owner: release; else seizure
 
// reads — everything is derived, read through the lens (on chain: PoolStateF over extsload)
lens.pool(poolId)   // the pool, logFloor, compositeX, unharvested, every leg with its virtual reserve
lens.bundleOf(poolId, gen)   lens.dividendOf(poolId, gen, holder)   lens.lienOf(id, owner)

unharvested is the generation's income still in the pool, L(ξˉ0−ξˉ)L(\bar\xi_0 - \bar\xi), and the pool carries Σ\Sigma, accrued in one slot. Together they are the point of the design: the fee earned and the model-free edge F−12ΣF - \tfrac12\Sigma are computable by anyone, on-chain, without any fee accounting having existed.

Fee policy

The F-pool ships a fixed ϕ\phi with a computable kernel: ϕ\phi is constant, but Σ\Sigma accrues anyway — one slot, one add per touched leg — so the fee the dynamic kernel would quote, and the edge, stay computable by anyone.

Mathematically, it is the degenerate C-pool

One class, one floor. The same specification covers both, and the F-pool introduces no new invariant. That is why ManagerF is also a singleton: every fungible pool in one contract, with its own flash-accounting lock.