Traderjoexyz Liquidity Book concentrates pool liquidity in selected price bins

Traderjoexyz Liquidity Book lets liquidity providers choose the fixed-price bins that hold a pool position. The selected bins determine where that position supplies tokens for swaps. Liquidity Book is a concentrated-liquidity automated market maker (AMM) developed by Trader Joe, which rebranded as LFJ in September 2024. Its bin step sets price spacing, while its liquidity shape determines allocation across those prices. Trading fees accrue when swaps use funded bins; price movement can leave a position outside trading activity.

Bin step determines the spacing between prices

Within a given pool, the bin step sets the percentage spacing between neighboring prices; the endpoints selected for a position define its range. The price multiplier between adjacent bins is 1 + s / 10,000, with s measured in basis points. One basis point equals 0.01%. Prices therefore follow a geometric progression: the percentage spacing stays constant, while the absolute gap grows at higher prices. A bin identifies one price point on that grid. The same number of consecutive bins covers different percentage ranges in pools with different steps.

The bin step belongs to the pool, so an individual position uses that pool’s spacing. Different pools can trade the same tokens using different steps. LBFactory creates and registers the LBPair contracts that contain those pools. Contract versions can also coexist, making the version part of identifying the intended pool.

Active-bin reserves determine the token composition

With price expressed as token Y per token X, bins above the active price hold X, and bins below it hold Y. The active bin can contain both tokens. These labels follow the pair’s contract ordering, which can differ from a display that reverses the quote.

Token allocation around the active price

Higher-price bins

Liquidity above the active price consists of token X. Buying X with Y consumes X reserves and can advance the active price upward. Higher bins provide the X that a continuing swap needs when trading reaches their prices. Liquidity farther above remains inactive until swaps reach it.

Lower-price bins

Bins below the active price hold token Y. Selling X for Y draws down Y reserves and can move the active bin downward. This arrangement supports single-sided deposits on either side. The token that funds such a deposit depends on its location relative to the active price.

Reserves at the active price

The active bin’s reserve mix changes as swaps exchange one token for the other. Its fixed exchange price does not require equal token amounts or equal reserve values. A position can therefore change its token composition even when its selected bin IDs remain unchanged.

Spot, Curve, and Bid-Ask assign different liquidity weights

For a specified range, Spot distributes liquidity uniformly, while Curve puts more weight near the middle and less at surrounding prices. Bid-Ask provides another nonuniform distribution intended to capture price fluctuations within the chosen range. These shapes describe how liquidity fills the selected bins; they leave the pool’s price grid unchanged.

The range selects the prices that a position funds. The shape assigns the relative amount at each price. A broad range with a heavy central allocation can still leave relatively little liquidity near its boundaries. Under uniform allocation, widening the range spreads the same capital across more bins. The protocol accepts separate token distributions across individual bins. Preset shapes supply standard allocations, while the underlying bin model supports custom weights. Changing weights changes reserve depth at the selected prices without changing the bin step.

How does a swap move between bins?

When a swap exhausts the required output token in one bin, LBPair searches for another funded bin in the swap direction. Each bin uses the constant-sum pricing relationship P × x + y = L. Here, x and y represent reserve quantities, P expresses the price of X in Y, and L expresses their combined value in Y units. Available reserves limit how much can trade at that price.

A single swap can consume liquidity across several bins within the same pair contract. Crossing into another price introduces price impact, and empty bins can leave gaps between execution prices. The final exchange rate reflects the liquidity that the swap actually uses.

Fixed pricing inside a bin does not remove swap fees or price changes that occur before execution.

The volatility accumulator adjusts the swap fee

If the variable component is enabled, a swap’s fee reflects configured base pricing plus an adjustment driven by the pair’s recent bin movements.

Base pricing and the variable component

Liquidity Book calculates the total swap fee rate as the sum of its base and variable components. The base component uses the configured base factor and the pool’s bin step. The variable component responds to the volatility accumulator and its control parameter. Setting that control parameter to zero disables the variable component.

The accumulator combines retained volatility with distance from a reference bin, subject to the configured maximum. Filter and decay periods govern how the reference updates over time. A quiet period can reduce the retained component. Subsequent bin movements can raise or lower the accumulator, depending on their distance from the reference. These settings belong to the pool, so markets need not share one fee rate or decay schedule.

Allocation to the liquidity used by a swap

The pool calculates fees separately as a swap uses each bin. Providers share the liquidity-provider portion in proportion to their ownership in that bin; a configured protocol share has a separate recipient. JOE staking concerns protocol revenue, while a Liquidity Book position earns swap fees through the reserves that serve trades. Volume in other bins does not increase that position’s swap-fee entitlement.

LBToken records ownership separately for each bin

Within one pool, LBToken records a provider’s shares under individual bin IDs. Equal shares in the same bin carry equivalent claims on its reserves. Shares in another bin represent a different allocation. The multi-token design resembles ERC-1155, with implementation differences that include omitting receiver callbacks. A position spanning several bins therefore has multiple share balances under the same pair contract. Its claim depends on the reserves in those bins and its proportion of their total shares.

Deposit bounds connect bin selection to the execution state

In the V2.2 router, the active-bin tolerance bounds movement between the desired active ID and the state used for a liquidity deposit. LBRouter applies the deltaIds offsets to the active ID at execution. Accepted movement can therefore shift the absolute deposit bins within the permitted tolerance.

Separate distributionX and distributionY arrays assign each token across those offsets. The arrays use the same ordering and length as deltaIds. Token-amount minimums enforce acceptable deposited quantities, and the deadline limits when the transaction can execute. Unallocated amounts return to the specified refund recipient. A failed tolerance or minimum-amount condition reverts the addition.

Increasing the bin-ID tolerance does not relax the token-amount minimums.

Range exit changes exposure and swap-fee participation

When the active price leaves every bin that a position funds, that position supplies no liquidity to swaps at the current price. Its ownership receipts remain, and its reserves can consist entirely of one token. A visible position balance can therefore coexist with an allocation that currently earns no swap fees.

View full-size image

Impermanent loss describes a position falling behind the value of simply holding its original assets, before fees. Concentration can magnify that difference when prices move beyond a narrow range. Collected fees can offset part of the difference without necessarily covering it.

• The selected pool has the intended bin step and contract version.
• The funded prices match the intended coverage, and any gaps remain deliberate.
• The reserve composition matches the token exposure intended for the position.
• The liquidity weights still match the intended distribution across those prices.
• Fee expectations account for trading in the funded bins and the position’s ownership share.

Rebalancing changes the allocation by removing existing liquidity and depositing a new distribution. It can also change token exposure at the prevailing price. A position can resume earning swap fees without rebalancing if trading returns to the bins that it still funds.