BitMathLeastSignificantBit returns the 0-based position of the least significant bit in x. This function is used in AMM calculations for efficient bit manipulation and range queries.

Parameters:

• x: the value for which to compute the least significant bit

Returns the index of the least significant bit (0-255).

Panics if x is zero.

BitMathMostSignificantBit returns the 0-based position of the most significant bit in x. This function is essential for AMM calculations involving price ranges and tick boundaries.

Parameters:

• x: the value for which to compute the most significant bit

Returns the index of the most significant bit (0-255).

Panics if x is zero.

GetAmount0Delta calculates the token0 amount difference within a price range, returning a signed int256 value that is negative when liquidity is negative. Rounds down for negative liquidity and up for positive liquidity.

Parameters:

• sqrtRatioAX96: first sqrt price in Q96 format
• sqrtRatioBX96: second sqrt price in Q96 format
• liquidity: signed liquidity value

Returns the token0 amount difference as a signed int256 value.

Panics if any input is nil or if the result overflows int256.

GetAmount1Delta calculates the token1 amount difference within a price range, returning a signed int256 value that is negative when liquidity is negative. Rounds down for negative liquidity and up for positive liquidity.

Parameters:

• sqrtRatioAX96: first sqrt price in Q96 format
• sqrtRatioBX96: second sqrt price in Q96 format
• liquidity: signed liquidity value

Returns the token1 amount difference as a signed int256 value.

Panics if any input is nil or if the result overflows int256.

GetAmountsForLiquidity calculates the amounts of token0 and token1 required to provide a specified liquidity within a price range.

This function determines the quantities of token0 and token1 necessary to achieve a given liquidity level, depending on the current price (sqrtRatioX96) and the bounds of the price range (sqrtRatioAX96 and sqrtRatioBX96). The function returns the calculated amounts of token0 and token1 as strings.

If the current price is below the lower bound of the price range, only token0 is required. If the current price is above the upper bound, only token1 is required. When the price is within the range, both token0 and token1 are calculated.

Parameters: - sqrtRatioX96: The current price represented as a square root ratio in Q64.96 format (*u256.Uint). - sqrtRatioAX96: The lower bound of the price range as a square root ratio in Q64.96 format (*u256.Uint). - sqrtRatioBX96: The upper bound of the price range as a square root ratio in Q64.96 format (*u256.Uint). - liquidity: The amount of liquidity to be provided (*u256.Uint).

Returns: - string: The calculated amount of token0 required to achieve the specified liquidity. - string: The calculated amount of token1 required to achieve the specified liquidity.

Notes:

• If liquidity is zero, the function returns "0" for both token0 and token1.
• The function guarantees that sqrtRatioAX96 is always the lower bound and sqrtRatioBX96 is the upper bound by calling toAscendingOrder().
• Edge cases where the current price is exactly on the bounds are handled without division by zero.

Example: ``` amount0, amount1 := GetAmountsForLiquidity(

1u256.MustFromDecimal("79228162514264337593543950336"),  // sqrtRatioX96 (1.0 in Q64.96)
2u256.MustFromDecimal("39614081257132168796771975168"),  // sqrtRatioAX96 (0.5 in Q64.96)
3u256.MustFromDecimal("158456325028528675187087900672"), // sqrtRatioBX96 (2.0 in Q64.96)
4u256.MustFromDecimal("1000000"),                        // Liquidity

)

println("Token0:", amount0, "Token1:", amount1)

// Output: Token0: 500000, Token1: 250000 ```

GetLiquidityForAmounts calculates the maximum liquidity given the current price (sqrtRatioX96), upper and lower price bounds (sqrtRatioAX96 and sqrtRatioBX96), and token amounts (amount0, amount1).

This function evaluates how much liquidity can be obtained for specified amounts of token0 and token1 within the provided price range. It returns the lesser liquidity based on available token0 or token1 to ensure the pool remains balanced.

Parameters: - sqrtRatioX96: The current price as a square root ratio in Q64.96 format (*u256.Uint). - sqrtRatioAX96: The lower bound of the price range as a square root ratio in Q64.96 format (*u256.Uint). - sqrtRatioBX96: The upper bound of the price range as a square root ratio in Q64.96 format (*u256.Uint). - amount0: The amount of token0 available to provide liquidity (*u256.Uint). - amount1: The amount of token1 available to provide liquidity (*u256.Uint).

Returns: - *u256.Uint: The maximum possible liquidity that can be minted.

Notes:

• The `Clone` method is used to prevent modification of the original values during computation.
• The function ensures that liquidity calculations handle edge cases when the current price is outside the specified range by returning liquidity based on the dominant token.

LiquidityMathAddDelta calculates the new liquidity by applying the delta liquidity to the current liquidity. If delta liquidity is negative, it subtracts the absolute value of delta liquidity from the current liquidity. If delta liquidity is positive, it adds the absolute value of delta liquidity to the current liquidity.

Parameters:

• x: current liquidity as unsigned 256-bit integer
• y: delta liquidity as signed 256-bit integer (positive to add, negative to subtract)

Returns the new liquidity as a uint256 value.

Panics if x or y is nil, or if the operation would result in underflow or overflow.

MAX_SQRT_RATIO returns the maximum valid sqrt price ratio (1461446703485210103287273052203988822378723970342). See MIN_SQRT_RATIO.

MIN_SQRT_RATIO returns the minimum valid sqrt price ratio (4295128739). It is a constructor (not a package-level var) so each caller receives a fresh instance rather than sharing a mutable singleton.

maxInt128 is the largest value representable in a signed 128-bit integer. It is used by SafeConvertToInt128 to bound liquidity deltas.

SafeAbsInt64 returns the absolute value of a, panicking when a is math.MinInt64 since its absolute value is not representable in int64.

SafeAddInt64 returns a + b, panicking on int64 overflow or underflow.

SafeAddUint64 returns a + b, panicking on uint64 overflow.

SafeConvertToInt128 converts a *u256.Uint to an *i256.Int, panicking when the value exceeds the signed int128 range (2^127 - 1).

SafeConvertToInt64 converts a *u256.Uint to int64, panicking when the value is nil or exceeds the int64 range (2^63 - 1).

SafeConvertToUint128 safely ensures a *u256.Uint value fits within the uint128 range.

This function verifies that the provided unsigned 256-bit integer does not exceed the maximum value for uint128 (`2^128 - 1`). If the value is within the uint128 range, it is returned as is; otherwise, the function triggers a panic.

Parameters: - value (*u256.Uint): The unsigned 256-bit integer to be checked.

Returns: - *u256.Uint: The same value if it is within the uint128 range.

Panics:

• If the value exceeds the maximum uint128 value (`2^128 - 1`), the function will panic with a descriptive error indicating the overflow and the original value.

Notes: - The constant `MAX_UINT128` is defined as `340282366920938463463374607431768211455` (the largest uint128 value). - No actual conversion occurs since the function works directly with *u256.Uint types.

Example: validUint128 := SafeConvertToUint128(u256.MustFromDecimal("340282366920938463463374607431768211455")) // Valid SafeConvertToUint128(u256.MustFromDecimal("340282366920938463463374607431768211456")) // Panics due to overflow

SafeMulDivInt64 returns (a * b) / c, computing the intermediate product in 256-bit signed arithmetic so a*b need not fit in int64. The final quotient must fit in int64, otherwise it panics. It panics on overflow.

SafeMulInt64 returns a * b, panicking on int64 overflow or underflow.

SafeSubInt64 returns a - b, panicking on int64 overflow or underflow.

SafeSubUint64 returns a - b, panicking on uint64 underflow.

SafeUint64ToInt64 converts a uint64 to int64, panicking when the value exceeds the int64 range (2^63 - 1).

SwapMathComputeSwapStep computes the next sqrt price, amount in, amount out, and fee amount for a swap step within a single tick range.

Parameters:

• sqrtRatioCurrentX96: current sqrt price in Q96 format
• sqrtRatioTargetX96: target sqrt price (tick boundary)
• liquidity: available liquidity in the range
• amountRemaining: amount left to swap (positive=exact in, negative=exact out)
• feePips: fee in hundredths of a bip (3000 = 0.3%)

Returns sqrtRatioNextX96, amountIn, amountOut, feeAmount.

Panics if any input parameter is nil or if feePips >= 1000000.

TickMathGetSqrtRatioAtTick calculates sqrt price ratio for given tick.

Converts tick index to square root price in Q64.96 fixed-point format. Based on Uniswap V3's mathematical formula: price = 1.0001^tick. Uses bit manipulation for gas-efficient calculation.

Parameters:

• tick: Tick index in range [-887272, 887272]

Returns:

• Square root of price ratio as Q64.96 fixed-point
• Result represents sqrt(token1/token0) price

Mathematical formula:

1sqrtPriceX96 = sqrt(1.0001^tick) * 2^96

Panics if tick outside valid range. Critical for all price calculations in concentrated liquidity.

TickMathGetTickAtSqrtRatio calculates the tick index for a given square root price ratio.

Converts a square root price ratio in Q64.96 format back to its tick index, returning the greatest tick where TickMathGetSqrtRatioAtTick(tick) <= sqrtPriceX96. This matches Uniswap V3's behavior exactly.

Parameters:

• sqrtPriceX96: Square root price ratio in Q64.96 format

Returns:

• Tick index corresponding to the price

Algorithm:

1. Scales ratio from Q64.96 to Q96.128 by left-shifting 32 bits
2. Finds MSB (most significant bit) to determine magnitude
3. Calculates log_2 using fixed-point arithmetic
4. Converts log_2 to log_sqrt(1.0001) to get tick
5. Returns appropriate tick based on bounds checking

Panics if sqrtPriceX96 is nil or outside valid range [minSqrtRatio, maxSqrtRatio). Critical for converting prices to ticks for position management.