Skip to content
log(swap)

Liquidity provider

A C-pool LP chooses a liquidity size and a floor, plus an upper cap for a capped position. The formulas below describe uncapped positions while active, unless stated otherwise.

Liquidity size: base exposure in quote

Because pR≡LpR \equiv L, the position's base-leg value in quote is identically LL, invariant under price. So the question is:

How much base exposure, in quote, do I want?

That one number sets the LVR bill (12σ2L\tfrac12\sigma^2 L) and the fee accrual rate (ϕL∣dx∣\phi L\lvert dx\rvert) together. It is the whole risk-and-reward unit.

The floor: quote buffer and activation boundary

The floor tunes how much quote buffer wraps that exposure. Three equivalent framings:

framingyou pickrelation
log-drawdown (default)a log distance ℓ\ellpmin⁡=p e−ℓp_{\min} = p\,e^{-\ell}
% drawdowna percentage ddpmin⁡=p (1−d)p_{\min} = p\,(1-d)
absolute floora pricepmin⁡p_{\min} directly

Log-drawdown is the native one and coincides with % drawdown to first order for small values. Everything else derives from (L,ℓ)(L, \ell): implied deposits, leverage (1+ℓ)−1(1+\ell)^{-1}, and break-even σ\sigma.

The floor is an output, not an input, if you prefer to think in wallet terms:

ξ=x−QL,i.e.pmin⁡=p e−Q/L.\xi = x - \frac{Q}{L}, \qquad\text{i.e.}\quad p_{\min} = p\,e^{-Q/L}.

"I want $1,000 of ETH exposure" is LL. "I'm bringing $Q of USDC alongside it" sets the floor. Both numbers are things already in your wallet.

The mint

Implied deposits, shown for confirmation:

  • active mint (ℓ>0\ell > 0, floor below spot): R=L/pR = L/p base and Q=LℓQ = L\ell quote;
  • dormant mint (ℓ≤0\ell \le 0, floor at or above spot): R=L/pmin⁡R = L/p_{\min} base only, no quote — a native limit sell.
router.mintBlended(key, targetFloor, cap, L, maxBaseIn, maxQuoteIn, recipient, deadline);
router.zapIn(key, fundWithBase, amountIn, targetFloor, cap, L, maxIn, recipient, deadline);

targetFloor is arbitrary. The router splits across the two adjacent ladder rungs, and the blend is one position at the floor you asked for. previewBlend returns the split. zapIn enters from a single asset — it solves for the swap that leaves no residual, monotone in the displacement, converging in about three Newton iterations.

Degenerate cases worth knowing:

  • Q=0Q = 0, floor at spot — maximum leverage, no buffer;
  • Q=0Q = 0, floor above spot — dormant, a resting sell;
  • LL small, QQ large — a deep buy ladder.

The position panel

Per holder, per class:

fieldexample
pairUSDC / ETH
base exposure LL$4,750
floor pmin⁡p_{\min}$1,800
current price pp$3,200
drawdown ℓ\ell0.575 (−43.8%)
current value V=L(1+ℓ)V = L(1+\ell)$7,481
composition63% ETH / 37% USDC
statusactive
fees accrued$142.17
leverage 1/(1+ℓ)1/(1+\ell)0.63

Lifecycle

eventwhat you see
mint activeposition appears, fees start accruing
mint dormantposition appears as a pending limit sell; no fees until activation
price falls toward the floorℓ\ell shrinks; warn below 0.1
price crosses the floor downwardstatus flips to dormant; 100% base; fees pause
price rises back across itstatus flips to active; fees resume
claimfees paid out in quote; position otherwise untouched
compoundfees fold in; floor drops to pmin⁡e−f/Lp_{\min}e^{-f/L}; no swap
raise floorquote returned; floor rises to pmin⁡eq/Lp_{\min}e^{q/L}
burnclaim the position plus accrued fees; shares burned

Crossing the floor does not liquidate the position. It holds base until price recovers or you withdraw. The base can continue to lose market value below the floor.

The four ongoing operations

Each moves the position along a single axis. All are O(1)O(1), and all are wrappers over one primitive.

Claim. Withdraw accrued fees in quote. Does not touch LL, the floor, or the holdings.

Compound — lower the floor. A pure-quote injection at fixed (L,R)(L, R) is identically a floor move, ξ′=ξ−f/L\xi' = \xi - f/L. No swap, no rebalance, nothing to rebalance into.

Raise the floor. The symmetric dual: withdraw qq of quote, ξ′=ξ+q/L\xi' = \xi + q/L, bounded by q≤Qq \le Q — drainable to the current price, not beyond.

Add base. Top up exposure without adding quote. L′=L+p ΔRL' = L + p\,\Delta R and the same buffer now covers a larger exposure, so the floor rises and ℓ\ell shrinks.

opLLRRQQpmin⁡p_{\min}
mint / burn±±±fixed
claimfixedfixedfixedfixed (fee exits the position)
compoundfixedfixed+↓
raise floorfixedfixed−↑
add base++fixed↑
reprice dormant∝ pmin⁡p_{\min}fixed0↕ (strictly above pp)

All of them are update(key, fromId, shares, toFloor, toCap, newL, …) with one or two degrees of freedom pinned. Accrued fees are swept into the same netting, so an edit needs no separate collect. newL = 0 is a full exit and settles identically to burn.

Why this is not the Uniswap v3 workflow

taskUniswap v3log(swap)
collect fees, keep positiondecreaseLiquidity(0) then collectclaim
collect across NN ranges2N2N calls over NN NFTsone call, one transfer
change rangedecreaseLiquidity → collect → mint; new tokenIdupdate — moves shares to the destination class
resize in placeincrease/decreaseLiquidity, fees collected separatelyupdate with a new LL
resize and repositionnot expressible as one opupdate — one call
compound feescollect → swap to the range's ratio → increaseLiquidityupdate to a lower floor — swap-free
position identitynon-fungible per (owner, range)fungible ERC-6909 per class

The last two rows are the structural ones. Compounding is swap-free because fees are quote-only and a pure-quote injection at fixed (L,R)(L, R) is identically a floor move. And fungibility survives because active positions aggregate affinely, so a class needs no per-holder range state — v3 ranges do not compose, which is what forces the NFT.

The honest caveats: v3's three calls are usually bundled in a multicall, so the saving is gas and integration stability rather than atomicity; and the floor ladder is discrete where v3 ticks are fine-grained, which is why blending across adjacent rungs is a router responsibility.

Reading your P&L

Two accumulated numbers and a subtraction:

edge per unit L  =  F−12Σ.\text{edge per unit } L \;=\; F - \tfrac12\Sigma .

ΔF\Delta F is the cumulative fee return on active liquidity over the window. For an active uncapped position, ΔF/(1+ℓ)\Delta F/(1+\ell) expresses it on starting capital using the starting drawdown. Annualize by the window duration to report an APR. No volatility model, no benchmark portfolio, no oracle — both numbers are statistics of the same price path, and the pool tracks both.

Capping the position

Adding a cap gives up the upside above pmax⁡p_{\max} and buys 1.3–1.7× capital efficiency — same fees, same LVR, less capital deployed. Unlike v3 concentration the fee-to-LVR ratio per unit LL is untouched, so it is pure capital efficiency rather than a change in the risk trade. See The cap.

Note that with a cap, pR=L(1−p/pmax⁡)pR = L(1-p/p_{\max}), so LL stops being the base-leg value — the interface shows exposure and LL separately.

What the interface deliberately does not expose

Ticks, fee accumulators, and the invariant equation (available in a details drawer). There is no upper bound to pick unless you want one — positions are automatically full-range above.

For an active uncapped position, LL equals the base exposure in quote. For a capped position, show LL and base exposure separately, using pR=L(1−p/pmax⁡)pR = L(1-p/p_{\max}).