doc.gno

 1// Package gnsmath provides core mathematical operations for GnoSwap's concentrated liquidity AMM.
 2//
 3// ## Overview
 4//
 5// This package provides the fundamental calculations for concentrated liquidity,
 6// including sqrt price math, swap calculations, and bit manipulation utilities.
 7// All operations use Q96 and Q160 fixed-point arithmetic for precision.
 8//
 9// The implementation follows Uniswap V3's mathematical model, ensuring
10// compatibility and correctness for cross-chain liquidity operations.
11//
12// ## Features
13//
14//   - Bit Math: MSB/LSB calculations for tick bitmap operations
15//   - Sqrt Price Math: Token amount conversions using Q64.96 format
16//   - Swap Math: Single-step swap calculations with fee handling
17//   - Overflow Protection: Built-in int256 overflow detection
18//   - Rounding Control: Configurable rounding for AMM safety
19//
20// ## Core Concepts
21//
22// ### Q96 Fixed-Point Format
23//
24// Square root prices use Q64.96 representation:
25//   - sqrtPriceX96 = sqrt(token1/token0) * 2^96
26//   - Enables precise integer arithmetic without floating-point
27//
28// ### Rounding Directions
29//
30//   - Round UP: Amounts owed TO pool (deposits, exact input)
31//   - Round DOWN: Amounts owed FROM pool (withdrawals, exact output)
32//
33// ## Usage
34//
35//	import (
36//	    "gno.land/p/gnoswap/gnsmath"
37//	    i256 "gno.land/p/gnoswap/int256"
38//	    u256 "gno.land/p/gnoswap/uint256"
39//	)
40//
41//	// Calculate token amounts for liquidity change
42//	sqrtPriceA := u256.MustFromDecimal("79228162514264337593543950336")
43//	sqrtPriceB := u256.MustFromDecimal("79625275426524748796330556128")
44//	liquidity := i256.MustFromDecimal("1000000000000000000")
45//
46//	amount0 := gnsmath.GetAmount0Delta(sqrtPriceA, sqrtPriceB, liquidity)
47//	amount1 := gnsmath.GetAmount1Delta(sqrtPriceA, sqrtPriceB, liquidity)
48//
49//	// Compute swap step
50//	feePips := uint64(3000) // 0.3% fee
51//	sqrtPriceNext, amountIn, amountOut, feeAmount := gnsmath.SwapMathComputeSwapStep(
52//	    currentPrice,
53//	    targetPrice,
54//	    liquidity,
55//	    amountRemaining,
56//	    feePips,
57//	)
58//
59//	// Bit operations for tick bitmap
60//	tickBitmap := u256.NewUint(0xFF00)
61//	msb := gnsmath.BitMathMostSignificantBit(tickBitmap)
62// println(msg) // Output: 15
63//
64//	lsb := gnsmath.BitMathLeastSignificantBit(tickBitmap)
65// println(lsb) // Output: 8
66//
67// ## API
68//
69// ### Bit Math
70//
71//   - BitMathMostSignificantBit(x *u256.Uint) uint8 - Find MSB position (0-255)
72//   - BitMathLeastSignificantBit(x *u256.Uint) uint8 - Find LSB position (0-255)
73//
74// ### Sqrt Price Math
75//
76//   - GetAmount0Delta(sqrtRatioAX96, sqrtRatioBX96 *u256.Uint, liquidity *i256.Int) *i256.Int
77//     Calculate token0 amount: liquidity * (1/√Pb - 1/√Pa)
78//   - GetAmount1Delta(sqrtRatioAX96, sqrtRatioBX96 *u256.Uint, liquidity *i256.Int) *i256.Int
79//     Calculate token1 amount: liquidity * (√Pb - √Pa)
80//
81// ### Swap Math
82//
83//   - SwapMathComputeSwapStep(sqrtRatioCurrentX96, sqrtRatioTargetX96, liquidity *u256.Uint, amountRemaining *i256.Int, feePips uint64) (*u256.Uint, *u256.Uint, *u256.Uint, *u256.Uint)
84//     Returns: (nextSqrtPrice, amountIn, amountOut, feeAmount)
85//     Handles both exact input and exact output swaps
86package gnsmath