Range Orders Implemented Through Concentrated Liquidity

Detailed Instructions

A range order is created by specifying an active liquidity price interval (tickLower and tickUpper) where you are willing to trade. This range is defined in terms of the pool's price, often represented as a square root price. For a USDC/ETH pool, you might set a range from 1500 to 2500 USDC per ETH. You then deposit a single asset, typically the one you expect to appreciate. If you deposit ETH into this range, you are effectively placing a limit order to sell ETH for USDC if the price rises. The deposited amount determines the initial liquidity depth. The protocol calculates the required amounts of both tokens for the chosen range, but as a single-sided deposit, the other token amount starts at zero.

• Sub-step 1: Call mint on the pool's manager contract with parameters for tickLower, tickUpper, and amount0Desired or amount1Desired.
• Sub-step 2: The contract calculates the proportional liquidity (L) value you will receive based on the current price and your deposit.
• Sub-step 3: Approve the token transfer and confirm the transaction, receiving an NFT representing your concentrated liquidity position.

solidityCopy
// Example call to mint a position (conceptual)
INonfungiblePositionManager.MintParams memory params = INonfungiblePositionManager.MintParams({
    token0: USDC,
    token1: WETH,
    fee: 3000, // 0.3% tier
    tickLower: getTickForPrice(1500),
    tickUpper: getTickForPrice(2500),
    amount0Desired: 0, // Depositing only ETH
    amount1Desired: 1 ether,
    ...
});

Tip: Use a tick calculator to translate your target prices into tick indices, as pools store liquidity in discrete tick spaces.

Detailed Instructions

Once deposited, your liquidity is active only when the pool's current price is within your [tickLower, tickUpper] range. Within this range, the liquidity is distributed uniformly, creating a constant product curve. As traders execute swaps against the pool, they interact with your position. If you deposited ETH (token1) and the price is below your range, your position holds only ETH and is inactive. When the market price rises and enters your range, your ETH begins to be sold incrementally for USDC (token0) with each swap that moves the price upward. The mechanism is automated by the pool's swap function, which uses the constant product formula x * y = L^2 within the active tick. The L value from your minting step determines your share of the liquidity in each tick crossed.

• Sub-step 1: Monitor the pool's current sqrtPriceX96 to see if it has entered your position's range.
• Sub-step 2: As swaps occur, the contract automatically deducts ETH from your position's reserve and adds USDC to it, following the bonding curve.
• Sub-step 3: Track the accumulated fees earned from swap volume, which are proportional to your active liquidity share.

solidityCopy
// Core swap logic updates reserves and price
function swap(
    address recipient,
    bool zeroForOne,
    int256 amountSpecified,
    uint160 sqrtPriceLimitX96,
    bytes calldata data
) external returns (int256 amount0, int256 amount1) {
    // ... computes swap, crosses ticks, and updates liquidity positions
}

Tip: The rate of asset conversion is not linear; more of your deposited asset is sold as the price approaches the range's upper bound.

Detailed Instructions

While the position is active, you accrue swap fees on all trading volume that occurs within your liquidity range. These fees are stored separately from the principal liquidity and must be manually collected. You can also increase or decrease your liquidity in the position, or modify its price range entirely, which is effectively creating a new position. To collect fees, you call collect on the position manager, specifying the token amounts to withdraw. The contract calculates your pro-rata share of the total fees accrued since the last collection. It's critical to monitor impermanent loss dynamics; as the price moves through your range, your asset composition changes, which may diverge from simply holding the assets.

• Sub-step 1: Call positions(tokenId) on the manager to read the current tokensOwed0 and tokensOwed1 fee balances.
• Sub-step 2: Execute the collect function with your tokenId, specifying maximum amounts to withdraw the accrued fees.
• Sub-step 3: To adjust the range, you must first decreaseLiquidity and then potentially increaseLiquidity on a new set of ticks, which involves a new fee calculation.

solidityCopy
// Collecting accrued fees
INonfungiblePositionManager.CollectParams memory params = INonfungiblePositionManager.CollectParams({
    tokenId: tokenId,
    recipient: msg.sender,
    amount0Max: type(uint128).max,
    amount1Max: type(uint128).max
});

Tip: Frequent collection of fees can be gas-intensive. Consider batching operations or using fee-compounding strategies if available.

Detailed Instructions

A range order executes fully when the market price moves past your upper tick (if you deposited the base asset). At that point, 100% of your initially deposited asset has been swapped for the other asset, and your position holds only the quote asset. Your liquidity is now inactive again, sitting above the current price. To realize the profits and reclaim capital, you must burn the liquidity position NFT. Burning the position withdraws all remaining token reserves and any uncollected fees, destroying the NFT. You can also close the position early at any time by burning it, which will withdraw the current asset composition, which could be a mix of both tokens if the price is mid-range.

• Sub-step 1: Call decreaseLiquidity to set liquidity to zero, which returns the proportional token amounts based on the current price and range.
• Sub-step 2: Call collect one final time to withdraw the principal tokens and any remaining fees.
• Sub-step 3: The position manager automatically burns the NFT upon full liquidation if decreaseLiquidity is called with the entire liquidity value.

solidityCopy
// Decreasing liquidity to zero and collecting
INonfungiblePositionManager.DecreaseLiquidityParams memory decParams = INonfungiblePositionManager.DecreaseLiquidityParams({
    tokenId: tokenId,
    liquidity: liquidityAmount, // Set to position's total liquidity
    amount0Min: 0,
    amount1Min: 0,
    deadline: block.timestamp
});
// Follow with a CollectParams call

Tip: Always set reasonable amountMin slippage tolerances when decreasing liquidity to protect against front-running in volatile conditions.

Detailed Instructions

Begin by defining the position's key parameters. You need the initial deposit amounts for both tokens (e.g., 1 ETH and 2000 USDC), the current pool price (P_current), and the lower and upper ticks (P_lower, P_upper) of your chosen range. The liquidity (L) is derived from these values. For a concentrated liquidity position, the active liquidity is only deployed when the price is within your set range. Calculate the virtual reserves using the constant product formula x = L / sqrt(P) and y = L * sqrt(P) for the token amounts within the range. This establishes the baseline for tracking value changes.

• Sub-step 1: Record initial token amounts and the pool's current tick.
• Sub-step 2: Convert your price bounds (e.g., $1800-$2200) into their corresponding tick indices.
• Sub-step 3: Use a liquidity calculator (like Uniswap V3's SDK) to compute the position's liquidity value from the inputs.

typescriptCopy
// Example using Uniswap V3 SDK to get tick and liquidity
import { TickMath, Position } from '@uniswap/v3-sdk';
const lowerTick = TickMath.getTickAtSqrtRatio(P_lower);
const upperTick = TickMath.getTickAtSqrtRatio(P_upper);
const position = new Position({
  pool,
  tickLower: lowerTick,
  tickUpper: upperTick,
  liquidity: calculatedLiquidity
});

Tip: The initial value of the position is simply the sum of the two token deposits at the current market price.

Detailed Instructions

Fees accrue in real-time as swaps occur through your active price range. You must query the pool contract for the fee growth global variables (feeGrowthGlobal0X128 and feeGrowthGlobal1X128). The fees owed to your position are proportional to your share of liquidity and the difference in these global accumulators since your last interaction. The calculation is: fees_owed = (feeGrowthGlobal - feeGrowthInside_last) * position_liquidity / 2^128. This yields the amount of each token earned as fees. For accurate tracking, you need to snapshot the feeGrowthInside values when you open the position and again when you check.

• Sub-step 1: Fetch the current feeGrowthGlobal values from the pool contract.
• Sub-step 2: Retrieve the stored feeGrowthInsideLast values from your position's on-chain data.
• Sub-step 3: Compute the delta and multiply by your liquidity to get raw token amounts.

solidityCopy
// Pseudocode for calculating uncollected fees
function getFeesOwed(
    uint128 liquidity,
    uint256 feeGrowthGlobal,
    uint256 feeGrowthInsideLast
) internal pure returns (uint256) {
    uint256 feeGrowthDelta = feeGrowthGlobal - feeGrowthInsideLast;
    return FullMath.mulDiv(liquidity, feeGrowthDelta, FixedPoint128.Q128);
}

Tip: Fees are only claimable upon withdrawing or collecting; they are not automatically reinvested.

Detailed Instructions

Impermanent loss quantifies the opportunity cost of providing liquidity versus holding the assets. To calculate it, determine the value of your LP position tokens (including accrued fees) at a new price P_new, and compare it to the value of your initial deposit if simply held. First, compute the token amounts in your position at P_new using the concentrated liquidity formulas: if P_new is within your range, the amounts are x = L / sqrt(P_new) - L / sqrt(P_upper) and y = L * sqrt(P_new) - L * sqrt(P_lower). Add any unclaimed fees. Then, calculate the hold value as: (Initial_Amount_TokenA * P_new) + Initial_Amount_TokenB. IL is: (LP_Value - Hold_Value) / Hold_Value.

• Sub-step 1: Compute the position's token composition at the new market price.
• Sub-step 2: Sum the value of these tokens plus accrued fees (converted to a common unit).
• Sub-step 3: Calculate the value of the initial deposit if it had never been provided as liquidity.
• Sub-step 4: Apply the IL formula; a negative result indicates a loss versus holding.

Tip: IL is most severe when the price exits your provided range entirely, as one token reserve depletes to zero.

Detailed Instructions

The net profitability of a range order is the sum of earned fees and the impermanent loss (or gain) on the principal. Calculate the total LP position value as the market value of the current token reserves plus the market value of all fees earned. Subtract from this the initial capital invested. A positive result means fees outweighed IL. Express this as a percentage return. Use the formula: Net P&L = (Value_Reserves_New + Value_Fees - Value_Initial) / Value_Initial. This requires pricing both tokens and fees at the current market rate. For accurate analysis, model this over different price trajectories and fee rate assumptions to understand break-even points.

• Sub-step 1: Aggregate the current token amounts from the position and the uncollected fees.
• Sub-step 2: Convert the total amount of each token to a common currency (e.g., USD) using P_new.
• Sub-step 3: Sum these values to get the total LP value.
• Sub-step 4: Subtract the initial investment value (also in USD) to determine absolute profit/loss.

pythonCopy
# Example Python snippet for net P&L calculation
initial_value = (amt_token0_init * price0) + (amt_token1_init * price1)
current_reserve_value = (amt_token0_now * price0) + (amt_token1_now * price1)
fee_value = (fees_token0 * price0) + (fees_token1 * price1)
net_pnl = current_reserve_value + fee_value - initial_value
pnl_percentage = (net_pnl / initial_value) * 100

Tip: High fee rates can compensate for significant IL, but this is highly dependent on trading volume and price volatility.

Detailed Instructions

Use historical or projected price data to simulate performance. The key is to model the price path and its interaction with your range. When the price is within your range, fees accumulate and reserves rebalance. When it's outside, fee accumulation stops for the depleted asset, and IL is maximized. Create a script that steps through price changes, updating virtual reserves and tracking fee growth. You can approximate fee income by assuming a constant daily volume percentage of the pool's TVL that flows through your price range. Tools like Python with pandas or specialized DeFi simulators (e.g., from Gauntlet) can automate this. The output should be a chart of net value over time compared to a hold strategy.

• Sub-step 1: Define a time-series of price data (e.g., daily ETH/USD prices).
• Sub-step 2: For each period, check if the price is within [P_lower, P_upper].
• Sub-step 3: If active, calculate fees earned based on estimated volume and your liquidity share.
• Sub-step 4: Recalculate token reserves based on the price change using the CL formulas.
• Sub-step 5: Aggregate results to plot total position value versus time.

Tip: This simulation is crucial for setting realistic range widths and understanding the trade-off between potential fees and risk of IL.