Traderjoe Liquidity Book uses price bins to concentrate liquidity

Pool Contracts, Price Bins and Provider Shares

A Liquidity Book pool connects token reserves, a price grid and per-bin ownership balances. The pool contract, LBPair, handles swaps and liquidity changes. LBToken balances record each provider's share of individual bins. A position spanning several bins therefore consists of separate balances, each tied to liquidity at its own price. Pool-wide liquidity and a provider's position describe different amounts. Depth at the prices a swap reaches governs execution; the provider's share at those prices governs fee participation.

Traderjoe adopted the LFJ name in September 2024. Liquidity Book remains the protocol name used within that platform. Token contracts, bin step and pool version identify the relevant deployment. Multiple pools can contain the same token pair with different spacing. Positions in those pools have separate reserves and ownership records, even if their token symbols match.

Bin Steps and Price Spacing

The bin step sets the proportional gap between neighboring price points, expressed in basis points. One basis point equals 0.01%. Prices progress geometrically: each successive higher price equals the previous price multiplied by the same spacing factor. Smaller steps place price points closer together; larger steps separate them more widely. Range width and bin step are different settings. Width describes the prices a position covers, while step describes the pool's grid. Counting selected bins without their spacing does not establish how much price movement the position covers.

View image file

Fixed Prices and Bin Crossings

Within a populated bin, the exchange rate stays constant as a swap changes its reserves. Liquidity Book uses a constant-sum invariant within each price bin. With consistently denominated token quantities, P × x + y = L relates reserves to liquidity at price P. Here, x and y are token quantities, with P expressing units of token Y per token X.

Once a swap consumes the available output token, additional input needs another populated bin. Empty price points supply no trading depth. The next usable bin may sit beyond a gap in liquidity, producing a larger price jump. Total pool reserves cannot show how much output remains available at the initial fixed price.

Zero price movement within a bin does not remove swap fees or protect a quote from intervening trades. Price impact across bins and execution slippage remain separate considerations.

Single-Sided Reserves and the Active Bin

Bin composition follows its position relative to the active price, with prices expressed as token Y per token X. Below the active price, populated bins hold token Y; above it, they hold token X. The active bin is the one bin able to hold both. Its reserves change as trades convert one token into the other.

A single-sided deposit supplies one token to eligible bins. This can include the active bin, where the minted shares can represent both assets and a composition fee can apply. It begins earning swap fees when trades reach those bins. Conversion can change the position into the other token, partly or completely. Bin liquidity remains available for later trading after conversion; its token balance can change again if the price reverses.

Liquidity Shapes Within a Chosen Range

Liquidity shapes control how much capital occupies each selected price point. Spot distributes liquidity uniformly across its chosen range. Curve places more near a central price while retaining liquidity in surrounding bins. Bid-Ask aims to capture trading as prices fluctuate within its deployed range. These choices alter the allocation inside a range; they do not set a universal earning rate. A broad selection of bins with little capital near the active price can provide less immediate depth than a tighter allocation. No shape prevents impermanent loss.

Base Fees and the Volatility Accumulator

Swap fees combine a base component with a variable component linked to the pool's volatility accumulator. The base fee uses the pool's bin step and configured base factor. The variable fee responds to recent bin movement, using parameters controlling its strength and persistence. A zero variable-fee control disables the variable component. Pool-specific settings mean a single fee percentage cannot describe every Liquidity Book market or every trade through one market.

Bin crossings can update the variable fee during a swap, so separate portions may face different rates. Time between swaps also affects the retained volatility reference. The protocol uses filter and decay parameters to preserve, reduce or reset that reference. Rapid trading alone does not imply the same fee movement in every direction. The accumulator also depends on movement relative to its reference bin.

Fees accrue to the bins a trade uses, proportional to provider shares after any configured protocol deduction. Additional fees can offset losses; they do not guarantee a positive return.

Range Width, Fee Share and Impermanent Loss

Concentration increases capital available at selected prices, but it also changes how quickly a position's token mix can shift. Trades progressively exchange the reserves in each participating bin. A move through the deposited range can leave the position entirely in one token. Impermanent loss measures the shortfall against holding the same deposited tokens, before counting fees. That comparison needs the same starting quantities and a common valuation point. Merely seeing a larger token balance does not establish a gain.

Range width spreads capital over more or fewer price points. For the same total capital and a uniform allocation, covering more bins reduces the amount at each point. A narrow range increases reliance on the price staying near that allocation. Fee income, changing asset prices and rebalancing costs all affect the outcome. A position can earn fees during trading and still finish below the value of simply holding its initial assets.

Deposit Placement and Execution Limits

Deposit parameters specify an intended active bin, permitted bin movement and minimum accepted token amounts. The active price can move between preparing a transaction and executing it, so the router checks permitted movement before placing liquidity. Deposits use bin positions relative to the active bin, so a shifted reference can change the prices receiving the allocation. Token amount limits and bin-movement limits protect different parts of that instruction. The router rejects a deposit if actual added amounts fall below either specified minimum. An execution deadline also bounds how late the instruction can run.

Allocation must also respect which token each bin can accept. Depositing token X below the active bin or token Y above it causes a revert. A movement beyond the permitted bin tolerance also causes a revert. Loosening tolerance changes acceptable placement without preserving the originally selected prices. Deposit parameters also set how much of each token goes into each chosen bin. Undistributed amounts go to the refund recipient.

Refunded excess tokens remain outside the deposited position. Minted bin shares record accepted liquidity; granting a spending approval alone does not establish any deposited balance.

Rebalancing Costs and Waiting Out a Price Move

Rebalancing moves existing liquidity from inactive prices toward a different allocation. Rebalancing withdraws the affected liquidity for redeployment; preparing a different token mix before redepositing can require swaps. Those operations introduce network costs and, where swaps occur, trading fees. Waiting leaves the original bins in place; they can earn again if trading returns. Adding liquidity near the active price uses extra capital without relocating the earlier position. Automatic fee accrual does not perform these reallocations. The choice changes which prices the capital serves and whether the position carries additional token exposure.

Accrued Fees and Withdrawal Amounts

Withdrawal redeems bin shares for their proportional claim on the reserves the selected bins currently hold. Trading can change those reserves after the original deposit. The returned token quantities therefore need not match the deposited quantities. In V2.1 and V2.2, provider swap fees join bin reserves, increasing the underlying assets represented by existing shares. That accrual stays with the bins earning it; it does not follow the active price into another bin.

V2.0 handled fees separately, so fee collection differs from later pools. Withdrawal also needs a router compatible with the pool version. Removing selected bins leaves other bin balances in place. Returned assets are no longer supplied to the pool; remaining shares represent claims on their bins' current reserves.