Package common provides shared utilities and mathematical functions for GnoSwap protocol contracts. The package contains essential mathematical functions, helper utilities, and shared logic used across the GnoSwap protocol. It provides implementations for concentrated liquidity calculations, price/tick conversions, GRC20 token operations, and native coin handling. This package serves as the mathematical foundation for the protocol, implementing algorithms based on Uniswap V3's concentrated liquidity model with Q64.96 fixed-point arithmetic. Key components: - Tick Math: Price-tick conversion functions for concentrated liquidity positions - Liquidity Math: Liquidity calculations based on token amounts and price ranges - GRC20 Registry Helpers: Convenient wrappers for GRC20 token operations - Coin Utilities: Native coin (GNOT) handling and validation - Assertion Utilities: Input validation and authorization checks
Allowance returns the token allowance from owner to spender. Parameters: - path: GRC20 token path - owner: address of the token owner - spender: address of the spender Returns the allowance amount as int64.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.Allowance(,,)"Approve approves tokens for the specified spender using grc20.Teller.Approve. Parameters: - cur: current realm (unused, reserved for future use) - path: GRC20 token path - spender: address allowed to spend the tokens - amount: amount of tokens to approve Returns an error if the approval fails, nil otherwise.
# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.
gnokey maketx call -pkgpath "gno.land/r/gnoswap/common" -func "Approve" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 5000000 -send "" -broadcast -chainid "test11" -remote "https://rpc.test11.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.test11.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/common" -func "Approve" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 5000000 -send "" ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "test11" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.test11.testnets.gno.land" call.tx
AssertIsNotHandleNativeCoin validates that no native coins were sent with the transaction. Panics with errNotHandleNativeCoin if any native coins were sent. Use this when a function should only work with GRC20 tokens and not accept native coins.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.AssertIsNotHandleNativeCoin()"AssertIsUserSendGNOTAmount validates that the user sent the expected GNOT amount. Panics with errNotSupportedCoins if unsupported native coins were sent. Panics with errInvalidGNOTAmount if the GNOT amount doesn't match the expected amount. Parameters: - amount: expected GNOT amount in ugnot Use this when a function requires native GNOT payment.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.AssertIsUserSendGNOTAmount()"BalanceOf returns the token balance for the specified address. Parameters: - path: GRC20 token path - addr: address to query the balance for Returns the token balance as int64.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.BalanceOf(,)"ExistsUserSendCoins checks if the user has sent any coins with the transaction. Returns true if any coins (with positive amount) were sent with the transaction.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.ExistsUserSendCoins()"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( u256.MustFromDecimal("79228162514264337593543950336"), // sqrtRatioX96 (1.0 in Q64.96) u256.MustFromDecimal("39614081257132168796771975168"), // sqrtRatioAX96 (0.5 in Q64.96) u256.MustFromDecimal("158456325028528675187087900672"), // sqrtRatioBX96 (2.0 in Q64.96) u256.MustFromDecimal("1000000"), // Liquidity ) println("Token0:", amount0, "Token1:", amount1) // Output: Token0: 500000, Token1: 250000 \`\`\`
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.GetAmountsForLiquidity(,,,)"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.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.GetLiquidityForAmounts(,,,,)"GetToken returns a grc20.Token instance for the specified path, panicking if not registered. Parameters: - path: GRC20 token path Returns a pointer to the grc20.Token instance. Panics if the token is not registered in grc20reg.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.GetToken()"GetTokenTeller returns a grc20.Teller instance for the specified path, panicking if not registered. Parameters: - path: GRC20 token path Returns a grc20.Teller instance for making token operations. Panics if the token is not registered in grc20reg.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.GetTokenTeller()"IsGNOTNativePath checks if the given path is the native gnot path. Parameters: - path: token path to check Returns true if the path matches GNOT\_DENOM ("ugnot").
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.IsGNOTNativePath()"IsGNOTPath checks if the given path is either native gnot or wrapped ugnot path. Parameters: - path: token path to check Returns true if the path matches either GNOT\_DENOM ("ugnot") or WUGNOT\_PATH.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.IsGNOTPath()"IsGNOTWrappedPath checks if the given path is the wrapped ugnot path. Parameters: - path: token path to check Returns true if the path matches WUGNOT\_PATH.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.IsGNOTWrappedPath()"IsRegistered checks if a token is registered in grc20reg, returning nil if registered or error if not. Parameters: - path: GRC20 token path Returns nil if the token is registered, or an error describing the issue.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.IsRegistered()"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.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.LiquidityMathAddDelta(,)"MustRegistered checks if all provided tokens are registered, panicking if any is not registered. Parameters: - paths: variable number of GRC20 token paths to check Panics if any of the provided tokens is not registered in grc20reg.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.MustRegistered()"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
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.SafeConvertToUint128()"SafeGRC20Approve performs a token approval and panics if it fails. Parameters: - cur: current realm (unused, reserved for future use) - path: GRC20 token path - spender: address allowed to spend the tokens - amount: amount of tokens to approve Panics if the approval fails.
# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.
gnokey maketx call -pkgpath "gno.land/r/gnoswap/common" -func "SafeGRC20Approve" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 5000000 -send "" -broadcast -chainid "test11" -remote "https://rpc.test11.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.test11.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/common" -func "SafeGRC20Approve" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 5000000 -send "" ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "test11" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.test11.testnets.gno.land" call.tx
SafeGRC20Transfer performs a token transfer and panics if it fails. Parameters: - cur: current realm (unused, reserved for future use) - path: GRC20 token path - to: recipient address - amount: amount of tokens to transfer Panics if the transfer fails.
# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.
gnokey maketx call -pkgpath "gno.land/r/gnoswap/common" -func "SafeGRC20Transfer" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 5000000 -send "" -broadcast -chainid "test11" -remote "https://rpc.test11.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.test11.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/common" -func "SafeGRC20Transfer" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 5000000 -send "" ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "test11" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.test11.testnets.gno.land" call.tx
SafeGRC20TransferFrom performs a token transfer from one address to another and panics if it fails. Parameters: - cur: current realm (unused, reserved for future use) - path: GRC20 token path - from: sender address - to: recipient address - amount: amount of tokens to transfer Panics if the transfer fails.
# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.
gnokey maketx call -pkgpath "gno.land/r/gnoswap/common" -func "SafeGRC20TransferFrom" -args $'' -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 5000000 -send "" -broadcast -chainid "test11" -remote "https://rpc.test11.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.test11.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/common" -func "SafeGRC20TransferFrom" -args $'' -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 5000000 -send "" ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "test11" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.test11.testnets.gno.land" call.tx
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: sqrtPriceX96 = sqrt(1.0001^tick) * 2^96 Panics if tick outside valid range. Critical for all price calculations in concentrated liquidity.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.TickMathGetSqrtRatioAtTick()"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.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.TickMathGetTickAtSqrtRatio()"TotalSupply returns the total supply of the specified token. Parameters: - path: GRC20 token path Returns the total supply of the token as int64.
gnokey query vm/qeval -remote "https://rpc.test11.testnets.gno.land" -data "gno.land/r/gnoswap/common.TotalSupply()"Transfer transfers tokens to the specified address using grc20.Teller.Transfer. Parameters: - cur: current realm (unused, reserved for future use) - path: GRC20 token path - to: recipient address - amount: amount of tokens to transfer Returns an error if the transfer fails, nil otherwise.
# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.
gnokey maketx call -pkgpath "gno.land/r/gnoswap/common" -func "Transfer" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 5000000 -send "" -broadcast -chainid "test11" -remote "https://rpc.test11.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.test11.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/common" -func "Transfer" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 5000000 -send "" ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "test11" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.test11.testnets.gno.land" call.tx
TransferFrom transfers tokens from one address to another using grc20.Teller.TransferFrom. Parameters: - cur: current realm (unused, reserved for future use) - path: GRC20 token path - from: sender address - to: recipient address - amount: amount of tokens to transfer Returns an error if the transfer fails, nil otherwise.
# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.
gnokey maketx call -pkgpath "gno.land/r/gnoswap/common" -func "TransferFrom" -args $'' -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 5000000 -send "" -broadcast -chainid "test11" -remote "https://rpc.test11.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.test11.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/common" -func "TransferFrom" -args $'' -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 5000000 -send "" ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "test11" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.test11.testnets.gno.land" call.tx
