Traderjoexyz
Traderjoexyz Liquidity Book - LP Fees and Range Management
Traderjoexyz Liquidity Book allocates swap fees to liquidity providers when trades use the bins containing their deposits. Each bin represents a fixed price in Trader Joe's automated market maker, now part of LFJ. A directly managed position keeps its selected bins as trading moves the active price. If trading no longer reaches any funded bin, new swap fees stop. The pause itself does not erase previously earned fees or withdraw the deposited tokens, although token values can continue changing.
In this guide
Bin spacing, reserves and the active price
Bin spacing sets the price interval between adjacent bins, while swaps determine which bin supplies liquidity. The pool moves to another funded bin when a trade exhausts the current bin's output token and still has input to exchange. One swap can therefore use several bins. Each participating bin earns fees on the part of the trade that it serves.
The price grid
The bin step measures the relative price gap between adjacent bins in basis points. A smaller step gives a finer grid. Counting bins alone cannot describe a position's price coverage without that spacing. Within a bin, the constant-sum relationship is P × x + y = L. Here, P prices token X in token Y units, x and y represent their reserves and L measures liquidity at that price. The exchange price stays fixed within a bin, while swap fees affect the net token amounts.
Token composition around the active bin
Only the active bin can hold both tokens. Higher-price bins hold token X, while lower-price bins hold token Y. Buying X can move the active price upward as trades consume X reserves. An out-of-range balance can consequently consist of one token, even when the original deposit contained both.
What happens when a position leaves its range?
An out-of-range position earns no new swap fees while trades stay outside its funded bins. A position spanning several bins can remain partly active after trading leaves an individual bin. Liquidity at the active price also needs trading volume to generate fees.
The original bin allocation stays in place unless its holder or an authorized manager changes it. If trading returns to funded bins, that liquidity can earn fees again without a new deposit. Waiting avoids repositioning transactions, although it leaves the position exposed to its current token holdings. A price return also does not establish that the position has matched the value of holding the original tokens outside the pool.
How do range width and liquidity shape affect earnings?
Range width controls price coverage, while liquidity shape controls how much capital occupies each selected bin.
Narrow and wider ranges
A narrow range concentrates the deposit into fewer price points. With the deposit amount and competing liquidity held constant, that concentration can increase its share at those prices. It also leaves less room for the active price to move before exiting the range. A wider range distributes capital across more prices. Its funded outer bins can participate after larger movements, while a uniform allocation puts less of the same deposit in each bin.
Spot and Curve allocations
Spot spreads liquidity uniformly across the selected range. Curve puts more liquidity near a central price and smaller allocations in surrounding bins. Their difference concerns the allocation inside the range; neither shape moves a directly managed range automatically. The allocation that captures more fees depends on where trades actually occur and how much competing liquidity occupies those bins.
Bid-Ask and combined shapes
Bid-Ask targets price fluctuations around a selected price through its liquidity distribution. Custom allocations can combine basic shapes across different price points. Concentrating around an expected price path leaves less capital elsewhere if trading follows a different path. No distribution removes impermanent loss, the potential shortfall against holding the original token amounts.
Fee growth and ownership inside each bin
Liquidity Book records an LP's ownership through LBToken balances for individual bins. A balance represents shares of that bin's reserves, whose token composition changes through trading. Adding the underlying holdings across funded bins gives the position's token balances. The receipt quantity itself does not express a fixed amount of either deposited asset.
Compounded reserves and older fee claims
In Liquidity Book v2.1 and v2.2, the LP portion of swap fees increases bin reserves without minting additional LBToken shares. Those fees compound within the position and come out with the corresponding reserve share on withdrawal. Earlier v2.0 pools account for LP fees separately and support fee collection. Pool version therefore determines whether earnings appear within withdrawable reserves or through separate claim accounting.
Volume, competition and dynamic fees
Liquidity Book combines a base swap fee with a variable component driven by its volatility accumulator. Bin movements feed that accumulator. Any configured protocol share reduces the portion retained for LPs. Position earnings consequently depend on trade volume through its bins, its ownership share there and the applicable fee parameters. Fee income can coexist with a shortfall against holding the starting token amounts.
Should I leave inactive bins alone or move the liquidity?
Leaving bins unchanged avoids repositioning costs; moving liquidity can restore participation near the active price.
Consider an inactive, directly held position whose owner is comparing those options. Compare token exposure, participation at traded prices and transaction costs for each choice. Waiting preserves the old allocation and needs returning trades for renewed fees. Repositioning changes that allocation and incurs costs that depend on the required operations. Gas depends on network conditions and transaction work. Any token conversion adds swap fees and may cross price bins. An active-bin deposit with a different token composition can also incur a composition fee.
A manual reposition uses existing bin balances to fund the new allocation; missing permissions can require separate approval transactions.
| Stage | Action and cost inputs | Tokens and LP shares |
|---|---|---|
| Inspect the existing position | Identify the pool version and its matching liquidity router, then locate funded bins and compare them with the active price. | Pool contracts hold deposited tokens; the holder controls the LP receipts. |
| Choose the replacement allocation | Select bins and distribution, accounting for the token balances they require. | Planning leaves the existing reserves and receipt ownership unchanged. |
| Remove selected liquidity | Authorize removal as needed and withdraw selected shares, subject to minimum token amounts. | The pool burns those shares and sends tokens to the specified recipient. |
| Prepare the returned tokens | Convert tokens only if needed and set deposit allowances; required transactions add gas. | The recipient holds returned tokens; approvals grant the selected contract spending permission. |
| Deposit into the new bins | Add the allocation with token minimums and active-bin movement tolerance. | Tokens enter the pool, which issues bin receipts to the designated holder. |
| Confirm the new allocation | Reconcile successful execution, funded bin IDs and remaining token balances. | The new receipt balances represent shares of the deposited reserves. |
| Cost comparison | Repositioning costs are observable; future additional fee income remains uncertain. | LP shares represent the holder's portion of pool reserves, whose token composition can change through swaps before withdrawal. |
If the active bin moves beyond the deposit's accepted tolerance, the v2.2 LBRouter reverts that deposit. A reverted onchain attempt can still consume gas. Confirm its failure and remaining balances before revising the allocation. A withdrawal that succeeded in an earlier transaction remains completed. A new withdrawal transaction can remove more liquidity if enough shares remain. A successful replacement deposit establishes the new allocation; subsequent trading determines whether it earns fees.
Single-sided liquidity and gradual token conversion
Single-sided liquidity can place one token at selected prices outside the active bin. Trading can convert that balance into the other token as it reaches those prices. Spreading the allocation across bins distributes conversion across price points, while concentrating it in one bin targets that bin's fixed exchange price. This uses the pool's liquidity mechanism; it does not require treating the position as a terminal limit order.
Ordinary bin liquidity stays deposited after conversion. Reverse trading through those bins can exchange the holdings back unless someone withdraws or manages them. A pause in fees may therefore reflect a completed directional allocation as well as an unwanted range exit. The holder can withdraw the converted tokens or leave the bins available for further trades.
Details worth knowing about Traderjoexyz Liquidity Book
Why can a Liquidity Book balance query miss my inactive bins?
A balance query that scans only bins near the active price can miss liquidity deposited farther away. The position can still exist in its original bins. Retrieving its holdings requires the correct pool and funded bin IDs, together with the holder's shares, each bin's total share supply and its reserves. An incomplete scan does not establish that the tokens disappeared.
Do Liquidity Book deposits need the pool's exact token order?
Direct LBRouter add-liquidity calls must identify token X and token Y in the order stored by the pool. A reversed token order can make the router reject the request. The bin step must also identify the intended pool. These contract parameters determine which balances and distribution apply to each token.
Are Liquidity Book receipts ordinary ERC-20 tokens?
LBToken is a custom multi-token receipt that tracks fungible balances by bin ID. Its design resembles ERC-1155, with differences that include omitting receiver callbacks. A Liquidity Book position can therefore have separate share balances for several bins within one pool. Representing it as a single ordinary ERC-20 balance would lose that per-bin ownership information.
Can the v2.2 liquidity router withdraw from a v2.0 pool?
Liquidity removal from a v2.0 pool requires the v2.0 router. The v2.2 router's liquidity-management functions are not backward compatible with v2.1 or v2.0 pairs. A v2.1 position requires its matching router. Similar function interfaces do not make these pool implementations interchangeable when adding or removing liquidity.
What does a Liquidity Book operator approval allow?
An LBToken operator approval grants the selected spender permission to transfer the holder's receipts across that pool's bin IDs. In v2.2 pools, the operator can also burn those receipts to withdraw the corresponding reserves. It applies to all of the holder's LBToken balances in that contract. This scope differs from an ERC-20 allowance for a specified token amount. Revoking the operator approval removes that permission without withdrawing liquidity.
Is native-token liquidity removal suitable for tokens with transfer taxes?
The v2.2 LBRouter's native-token removal function does not support taxed transfers through the router. Its standard token-removal function supports that category and returns the wrapped native token when that asset forms part of the pair. Depending on the token's implementation, tax exemptions for the router, pair or both can make native-token removal usable. Token-specific transfer taxes can still affect the amount that reaches the recipient.