@w3lib/solana-batch-call 0.3.0 → 0.5.0

package/src/liquidity/types.ts

@@ -0,0 +1,158 @@
+import type { SolanaLpPosition, SolanaLpProtocol, SolanaLpToken } from '../lp.js'
+import type { SendOptions, WriteResult, WriteStatus } from '../write/send.js'
+import type { Instruction } from '../write/transaction.js'
+
+type Amount = bigint | number | string
+
+/**
+ * 已有的仓位：直接传 getLpPositions 查到的 SolanaLpPosition，或者只传能定位仓位的字段：
+ * - Raydium CLMM / Orca Whirlpool：positionMint（仓位 NFT 的 mint）
+ * - Raydium AMM v4 / CPMM：pool（池子地址）
+ */
+export interface SolanaPositionRef {
+  protocol: SolanaLpProtocol
+  positionMint?: string
+  pool?: string
+}
+
+/** 往已有仓位追加：两边数量给一边即可（另一边按当前价格算），也可以都给（按较少的一边） */
+export interface SolanaIncreaseLiquidityParams {
+  position: SolanaPositionRef | SolanaLpPosition
+  /** token0 的数量：amount0（最小单位）和 amount0Formatted（按精度换算，如 '1.5'）二选一 */
+  amount0?: Amount
+  amount0Formatted?: string
+  amount1?: Amount
+  amount1Formatted?: string
+}
+
+/**
+ * 新建仓位（Raydium CLMM / Orca：一个新的仓位 NFT；AMM v4 / CPMM：往池子里加流动性，拿到 LP 代币）。
+ * 池子用地址指定（Solana 上同一对代币有很多池子，按地址最明确）；价格是“1 个 token0 值多少个 token1”（池子的方向）
+ */
+export interface SolanaNewPositionParams {
+  protocol: SolanaLpProtocol
+  pool: string
+  /** 集中流动性：价格区间（token1 / token0，取最近的可用 tick）；或直接给 tick；或 fullRange */
+  priceLower?: string | number
+  priceUpper?: string | number
+  tickLower?: number
+  tickUpper?: number
+  fullRange?: boolean
+  amount0?: Amount
+  amount0Formatted?: string
+  amount1?: Amount
+  amount1Formatted?: string
+}
+
+export type SolanaAddLiquidityParams = SolanaIncreaseLiquidityParams | SolanaNewPositionParams
+
+export interface SolanaRemoveLiquidityParams {
+  position: SolanaPositionRef | SolanaLpPosition
+  /** 移除的比例（百分数，(0, 100]），默认 100 */
+  percent?: number
+  /** 或者直接给移除的数量：集中流动性是 L，AMM 是 LP 代币数量（最小单位） */
+  liquidity?: Amount
+  /** 集中流动性：全部移除后关闭仓位、销毁 NFT（退回租金），默认 false */
+  burn?: boolean
+}
+
+export interface SolanaCollectFeesParams {
+  /** 集中流动性的仓位（AMM 的手续费已经计入 LP 份额） */
+  position: SolanaPositionRef | SolanaLpPosition
+}
+
+export interface SolanaLiquidityOptions {
+  /** 价格滑点（比例，0.005 = 0.5%），默认 0.005 */
+  slippage?: number
+  /**
+   * Wrapped SOL 那一边用 SOL 支付 / 收取（自动包装 / 解包），默认 true。
+   * 用的是 wSOL 的关联代币账户：原来没有时创建、用完关闭（剩余的 wSOL 换回 SOL）；原来就有时只补差额、不关闭
+   */
+  native?: boolean
+  /** 新建仓位的 NFT 归谁，默认 owner */
+  recipient?: string
+  /** 取消读取 */
+  signal?: AbortSignal
+}
+
+/** 一步：要原子执行的一组指令 */
+export interface SolanaLiquidityStep {
+  /**
+   * - setup：创建代币账户、初始化 tick 数组等准备工作（与主指令能放进同一笔交易时会合并）
+   * - add / remove / collect：添加 / 移除流动性、领取手续费
+   */
+  kind: 'setup' | 'add' | 'remove' | 'collect'
+  instructions: Instruction[]
+}
+
+/** 添加 / 移除流动性的计划：预计的数量 + 按顺序执行的指令。只读取、不签名，可以当作报价 */
+export interface SolanaLiquidityPlan {
+  action: 'add' | 'remove' | 'collect'
+  protocol: SolanaLpProtocol
+  protocolName: string
+  type: 'clmm' | 'amm'
+  pool: string
+  owner: string
+  token0: SolanaLpToken
+  token1: SolanaLpToken
+  /** 集中流动性：仓位 NFT 的 mint（新建时是新生成的，见 signers）和仓位账户 */
+  positionMint: string | null
+  position: string | null
+  /** AMM：LP 代币的 mint */
+  lpMint: string | null
+  /** 集中流动性：区间、池子当前的 tick 和价格（token1 / token0，按精度换算，只用于展示） */
+  tickLower: number | null
+  tickUpper: number | null
+  tick: number | null
+  price: number | null
+  priceLower: number | null
+  priceUpper: number | null
+  /** 添加 / 移除的流动性：集中流动性是 L；AMM 是 LP 代币数量 */
+  liquidity: string
+  /** 按当前价格预计存入 / 取出的数量（不含手续费） */
+  amount0: string
+  amount1: string
+  amount0Formatted: string | null
+  amount1Formatted: string | null
+  /** 添加：最多会用掉的数量（按滑点）；移除：null */
+  amount0Max: string | null
+  amount1Max: string | null
+  /** 移除：至少会拿到的数量；添加：null */
+  amount0Min: string | null
+  amount1Min: string | null
+  /** 一并领取的未领取手续费（集中流动性移除 / 领取时）；AMM 为 '0' */
+  fees0: string
+  fees1: string
+  fees0Formatted: string | null
+  fees1Formatted: string | null
+  /** 一并领取的挖矿奖励的代币（集中流动性移除 / 领取时；数量要等交易执行后才知道） */
+  rewardMints: string[]
+  /** 哪一边用 SOL 支付 / 收取（自动包装 / 解包 wSOL） */
+  native: 'token0' | 'token1' | null
+  /** 按顺序执行；setup 和主指令能放进同一笔交易时会合并 */
+  steps: SolanaLiquidityStep[]
+  /**
+   * 除 owner 外还需要签名的临时密钥（新建集中流动性仓位时的 NFT mint，32 字节种子）。
+   * 自己发送时用它签名主指令所在的交易（如 web3.js 的 Keypair.fromSeed(secretKey)）
+   */
+  signers: Array<{ address: string; secretKey: Uint8Array }>
+}
+
+export interface SolanaLiquiditySendOptions extends SolanaLiquidityOptions, Omit<SendOptions, 'onUpdate' | 'signal'> {
+  /** 发送前检查余额够不够（添加时），默认 true */
+  checkBalance?: boolean
+  onUpdate?: (result: SolanaLiquidityStepResult) => void
+}
+
+export interface SolanaLiquidityStepResult extends WriteResult {
+  kind: SolanaLiquidityStep['kind']
+}
+
+export interface SolanaLiquidityResult {
+  plan: SolanaLiquidityPlan
+  /** 与 plan.steps 一一对应 */
+  results: SolanaLiquidityStepResult[]
+  /** 主指令（最后一步）的状态和签名 */
+  status: WriteStatus
+  signature: string | null
+}

package/src/lp.ts

@@ -6,15 +6,16 @@ import type { RequestOptions, SolanaClient } from './client.js'
 import { formatUnits, parseMint, parseTokenAccount, type AccountInfo } from './layout.js'
 import { AllNodesFailedError, HttpError, RpcError } from './rpc.js'
 import { getAmountsForLiquidity, getFeeGrowthInside, getFeesOwed, orcaSqrtPriceAtTick, raydiumSqrtPriceAtTick, sqrtPriceToPrice, tickToPrice, type TickFeeData } from './lpMath.js'
+import { defillamaPrices, type SolanaPriceSource } from './price.js'
 
 export const RAYDIUM_CLMM_PROGRAM_ID = 'CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK'
 export const ORCA_WHIRLPOOL_PROGRAM_ID = 'whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc'
 export const RAYDIUM_AMM_PROGRAM_ID = '675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8'
 export const RAYDIUM_CPMM_PROGRAM_ID = 'CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C'
 /** AMM v4 的 LP mint 权限（固定地址） */
-const RAYDIUM_AMM_AUTHORITY = '5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1'
+export const RAYDIUM_AMM_AUTHORITY = '5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1'
 /** CPMM 的 LP mint 权限：PDA ["vault_and_lp_mint_auth_seed"] */
-const RAYDIUM_CPMM_AUTHORITY = 'GpMZbSM2GgvTKHJirzeGfMFoaZ8UR2X7F4v8vHTvxFbL'
+export const RAYDIUM_CPMM_AUTHORITY = 'GpMZbSM2GgvTKHJirzeGfMFoaZ8UR2X7F4v8vHTvxFbL'
 
 export type SolanaLpProtocol = 'raydium-clmm' | 'orca-whirlpool' | 'raydium-amm' | 'raydium-cpmm'
 
@@ -25,45 +26,8 @@ export const SOLANA_LP_PROTOCOLS: Readonly<Record<SolanaLpProtocol, { name: stri
   'raydium-cpmm': { name: 'Raydium CPMM', type: 'amm', programId: RAYDIUM_CPMM_PROGRAM_ID },
 }
 
-// ---------------------------------------------------------------------------
-// 价格源
-// ---------------------------------------------------------------------------
-
-export interface SolanaPriceSource {
-  readonly name: string
-  /** 返回 mint → 美元价格；没有价格的不返回 */
-  prices(ctx: { mints: readonly string[]; fetch: typeof fetch; signal?: AbortSignal }): Promise<Map<string, number>>
-}
-
-/** DefiLlama 价格（免费免 Key，按 100 个一批查询）；confidence 低于 minConfidence（默认 0.9）的价格不用 */
-export function defillamaPrices(options: { minConfidence?: number } = {}): SolanaPriceSource {
-  const minConfidence = options.minConfidence ?? 0.9
-  return {
-    name: 'defillama',
-    async prices({ mints, fetch: fetchFn, signal }) {
-      const result = new Map<string, number>()
-      const batches: string[][] = []
-      for (let i = 0; i < mints.length; i += 100) {
-        batches.push(mints.slice(i, i + 100))
-      }
-      await Promise.all(
-        batches.map(async (batch) => {
-          const res = await fetchFn(`https://coins.llama.fi/prices/current/${batch.map((m) => `solana:${m}`).join(',')}`, { signal })
-          if (!res.ok) {
-            throw new Error(`DefiLlama prices: HTTP ${res.status}`)
-          }
-          const body = (await res.json()) as { coins?: Record<string, { price?: number; confidence?: number }> }
-          for (const [key, coin] of Object.entries(body.coins ?? {})) {
-            if (typeof coin.price === 'number' && Number.isFinite(coin.price) && (coin.confidence === undefined || coin.confidence >= minConfidence)) {
-              result.set(key.slice(key.indexOf(':') + 1), coin.price)
-            }
-          }
-        }),
-      )
-      return result
-    },
-  }
-}
+// 价格源在 price.ts（子路径 /price）；这里继续导出，旧的 import 不受影响
+export { defillamaPrices, type SolanaPriceSource, type SolanaPriceSourceContext } from './price.js'
 
 // ---------------------------------------------------------------------------
 // 结果类型
@@ -152,7 +116,7 @@ export interface LpPositionsOptions extends RequestOptions {
   pools?: readonly string[]
   /** 返回已清空的仓位（流动性为 0、手续费也领完，NFT 还在）。默认 false */
   includeClosed?: boolean
-  /** 查美元价值：true 用 DefiLlama，也可以传自己的 SolanaPriceSource。默认不查 */
+  /** 查美元价值：true 用 DefiLlama，也可以传自己的 SolanaPriceSource（如 /price 的 combinePrices([defillamaPrices(), onchainPrices()])）。默认不查 */
   prices?: boolean | SolanaPriceSource
   /**
    * 价格源出错时调用（服务不可用、被拦截等）：这时照样返回仓位，只是 valueUsd / feesUsd 为 null，
@@ -167,7 +131,8 @@ export interface LpPositionsOptions extends RequestOptions {
 // 账户布局（各程序的 Anchor / 原生账户，偏移量含 8 字节判别符）
 // ---------------------------------------------------------------------------
 
-class Bytes {
+/** 小端读取账户数据（添加 / 移除流动性也用） */
+export class Bytes {
   readonly #view: DataView
   constructor(readonly data: Uint8Array) {
     this.#view = new DataView(data.buffer, data.byteOffset, data.byteLength)
@@ -300,7 +265,7 @@ function orcaPool(b: Bytes): ClmmPoolState {
   }
 }
 
-interface AmmPoolState {
+export interface AmmPoolState {
   protocol: 'raydium-amm' | 'raydium-cpmm'
   address: string
   lpMint: string
@@ -350,7 +315,7 @@ function cpmmPool(address: string, b: Bytes): AmmPoolState {
   }
 }
 
-function parseAmmPool(account: AccountInfo): AmmPoolState | null {
+export function parseAmmPool(account: AccountInfo): AmmPoolState | null {
   const b = new Bytes(account.data)
   if (account.owner === RAYDIUM_AMM_PROGRAM_ID && account.data.length === AMM_POOL_SIZE) {
     return ammPool(account.address, b)
@@ -361,14 +326,14 @@ function parseAmmPool(account: AccountInfo): AmmPoolState | null {
   return null
 }
 
-const utf8 = (s: string) => new TextEncoder().encode(s)
+export const utf8 = (s: string) => new TextEncoder().encode(s)
 
 function floorDiv(a: number, b: number): number {
   return Math.floor(a / b) * b
 }
 
 /** Raydium tick 数组：PDA ["tick_array", pool, start（i32 大端）]，每个数组 60 个 tick */
-function raydiumTickArray(pool: string, tick: number, spacing: number): { address: string; start: number } {
+export function raydiumTickArray(pool: string, tick: number, spacing: number): { address: string; start: number } {
   const start = floorDiv(tick, spacing * RAYDIUM_TICK_ARRAY_SIZE)
   const be = new Uint8Array(4)
   new DataView(be.buffer).setInt32(0, start, false)
@@ -376,7 +341,7 @@ function raydiumTickArray(pool: string, tick: number, spacing: number): { addres
 }
 
 /** Orca tick 数组：PDA ["tick_array", whirlpool, start（十进制字符串）]，每个数组 88 个 tick */
-function orcaTickArray(pool: string, tick: number, spacing: number): { address: string; start: number } {
+export function orcaTickArray(pool: string, tick: number, spacing: number): { address: string; start: number } {
   const start = floorDiv(tick, spacing * ORCA_TICK_ARRAY_SIZE)
   return { address: findProgramAddress([utf8('tick_array'), decodeAddress(pool), utf8(String(start))], ORCA_WHIRLPOOL_PROGRAM_ID), start }
 }
@@ -670,9 +635,9 @@ export async function lpPositions(client: SolanaClient, owner: string, options:
 
 /**
  * 节点不提供这个方法（方法不存在、被拦截、需要付费 / Token、403 等）：这时报错里说明怎么绕过。
- * 多节点时所有节点都是这个原因才算；限频、超时、网络不对等原样抛出
+ * 多节点时所有节点都是这个原因才算；限频、超时、网络不对等原样抛出（资产总值 portfolio 也用）
  */
-function methodUnavailable(err: unknown): boolean {
+export function methodUnavailable(err: unknown): boolean {
   if (err instanceof AllNodesFailedError) {
     return err.errors.length > 0 && err.errors.every((e) => methodUnavailable(e.error))
   }
@@ -750,8 +715,8 @@ async function finalize(client: SolanaClient, raw: readonly (RawClmm | RawAmm)[]
       return new Map()
     }
     try {
-      // wSOL 的价格就是 SOL 的价格，DefiLlama 用 So111…112 查得到
-      return await priceSource.prices({ mints, fetch: fetchFn, signal })
+      // wSOL 的价格就是 SOL 的价格，DefiLlama 用 So111…112 查得到；client 给链上价格源读池子
+      return await priceSource.prices({ mints, fetch: fetchFn, signal, client })
     } catch (err) {
       if (signal?.aborted) {
         throw err

package/src/lpMath.ts

@@ -203,3 +203,218 @@ export function sqrtPriceToPrice(sqrtPrice: bigint, decimals0: number, decimals1
 export function tickToPrice(tick: number, decimals0: number, decimals1: number): number {
   return 1.0001 ** tick * 10 ** (decimals0 - decimals1)
 }
+
+// ---------------------------------------------------------------------------
+// 添加 / 移除流动性用到的计算（两个程序公式相同，tick ↔ 价格按各自的换算）
+// ---------------------------------------------------------------------------
+
+/** 两个程序允许的 sqrt 价格范围（Raydium：MIN / MAX_SQRT_PRICE_X64；Orca：MIN / MAX_SQRT_PRICE） */
+export const RAYDIUM_MIN_SQRT_PRICE = 4295048016n
+export const RAYDIUM_MAX_SQRT_PRICE = 79226673521066979257578248091n
+export const ORCA_MIN_SQRT_PRICE = 4295048016n
+export const ORCA_MAX_SQRT_PRICE = 79226673515401279992447579055n
+
+export type ClmmProgram = 'raydium' | 'orca'
+
+const sqrtAtTick = (program: ClmmProgram) => (program === 'raydium' ? raydiumSqrtPriceAtTick : orcaSqrtPriceAtTick)
+const sqrtRange = (program: ClmmProgram): [bigint, bigint] => (program === 'raydium' ? [RAYDIUM_MIN_SQRT_PRICE, RAYDIUM_MAX_SQRT_PRICE] : [ORCA_MIN_SQRT_PRICE, ORCA_MAX_SQRT_PRICE])
+
+/** tick → sqrt 价格（按程序） */
+export function sqrtPriceAtTick(program: ClmmProgram, tick: number): bigint {
+  return sqrtAtTick(program)(tick)
+}
+
+/** sqrt 价格 → tick：满足 sqrtPriceAtTick(tick) <= sqrtPrice 的最大 tick（二分查找，与程序的 get_tick_at_sqrt_price 一致），限制在 [MIN_TICK, MAX_TICK] 内 */
+export function tickAtSqrtPrice(program: ClmmProgram, sqrtPrice: bigint): number {
+  const at = sqrtAtTick(program)
+  if (sqrtPrice < at(MIN_TICK)) {
+    return MIN_TICK
+  }
+  let lo = MIN_TICK
+  let hi = MAX_TICK
+  while (lo < hi) {
+    const mid = Math.floor((lo + hi + 1) / 2)
+    if (at(mid) <= sqrtPrice) {
+      lo = mid
+    } else {
+      hi = mid - 1
+    }
+  }
+  return lo
+}
+
+/** 向上取整的整数除法 */
+export const ceilDiv = (a: bigint, b: bigint) => (a + b - 1n) / b
+
+/** 添加流动性 L 时程序收取的 token0（向上取整）：ceil(L · 2^64 · (b − a) / (a · b)) */
+function amount0Up(a: bigint, b: bigint, liquidity: bigint): bigint {
+  const [lo, hi] = a < b ? [a, b] : [b, a]
+  return ceilDiv((liquidity << 64n) * (hi - lo), lo * hi)
+}
+
+/** 添加流动性 L 时程序收取的 token1（向上取整）：ceil(L · (b − a) / 2^64) */
+function amount1Up(a: bigint, b: bigint, liquidity: bigint): bigint {
+  const [lo, hi] = a < b ? [a, b] : [b, a]
+  return ceilDiv(liquidity * (hi - lo), Q64)
+}
+
+/** 添加流动性 L 时程序收取的两种代币数量（向上取整；按当前 tick 判断区间，与程序一致） */
+export function getMintAmounts(tick: number, sqrtPrice: bigint, sqrtLower: bigint, sqrtUpper: bigint, liquidity: bigint, tickLower: number, tickUpper: number): [bigint, bigint] {
+  if (liquidity === 0n) {
+    return [0n, 0n]
+  }
+  if (tick < tickLower) {
+    return [amount0Up(sqrtLower, sqrtUpper, liquidity), 0n]
+  }
+  if (tick < tickUpper) {
+    return [amount0Up(sqrtPrice, sqrtUpper, liquidity), amount1Up(sqrtLower, sqrtPrice, liquidity)]
+  }
+  return [0n, amount1Up(sqrtLower, sqrtUpper, liquidity)]
+}
+
+/** 区间 [a, b] 内 amount0 个 token0 对应的流动性（向下取整）：amount0 · (a · b / 2^64) / (b − a) */
+export function getLiquidityForAmount0(a: bigint, b: bigint, amount0: bigint): bigint {
+  const [lo, hi] = a < b ? [a, b] : [b, a]
+  return (amount0 * ((lo * hi) / Q64)) / (hi - lo)
+}
+
+/** 区间 [a, b] 内 amount1 个 token1 对应的流动性（向下取整）：amount1 · 2^64 / (b − a) */
+export function getLiquidityForAmount1(a: bigint, b: bigint, amount1: bigint): bigint {
+  const [lo, hi] = a < b ? [a, b] : [b, a]
+  return (amount1 * Q64) / (hi - lo)
+}
+
+/**
+ * 最多用 amount0 / amount1 时能添加的流动性：两边都给时取较小的；只给一边时只按这一边算（另一边要多少由 getMintAmounts 算）。
+ * 区间在当前价格之外时只需要一种代币，给的是另一种时返回 0
+ */
+export function getLiquidityForAmounts(
+  tick: number,
+  sqrtPrice: bigint,
+  sqrtLower: bigint,
+  sqrtUpper: bigint,
+  amount0: bigint | undefined,
+  amount1: bigint | undefined,
+  tickLower: number,
+  tickUpper: number,
+): bigint {
+  let l0: bigint | null = null
+  let l1: bigint | null = null
+  // 价格正好在下限（tick == tickLower 且 sqrtPrice == sqrtLower）时也只需要 token0：按下方处理，避免除以 0
+  if (tick < tickLower || sqrtPrice <= sqrtLower) {
+    l0 = amount0 === undefined ? null : getLiquidityForAmount0(sqrtLower, sqrtUpper, amount0)
+    l1 = amount1 === undefined ? null : amount0 === undefined ? 0n : null
+  } else if (tick < tickUpper && sqrtPrice < sqrtUpper) {
+    // 价格正好在上限（向下穿过 tick 后 tick = tickUpper − 1、sqrtPrice = 上限）时只需要 token1：按上方处理
+    l0 = amount0 === undefined ? null : getLiquidityForAmount0(sqrtPrice, sqrtUpper, amount0)
+    l1 = amount1 === undefined ? null : getLiquidityForAmount1(sqrtLower, sqrtPrice, amount1)
+  } else {
+    l1 = amount1 === undefined ? null : getLiquidityForAmount1(sqrtLower, sqrtUpper, amount1)
+    l0 = amount0 === undefined ? null : amount1 === undefined ? 0n : null
+  }
+  if (l0 === null) return l1 ?? 0n
+  if (l1 === null) return l0
+  return l0 < l1 ? l0 : l1
+}
+
+/** 整数平方根（向下取整，牛顿迭代从不小于平方根的值开始） */
+export function sqrtBigInt(value: bigint): bigint {
+  if (value < 0n) {
+    throw new RangeError('square root of a negative number')
+  }
+  if (value < 2n) {
+    return value
+  }
+  let x = 1n << BigInt((value.toString(2).length + 1) >> 1)
+  for (;;) {
+    const y = (x + value / x) >> 1n
+    if (y >= x) {
+      return x
+    }
+    x = y
+  }
+}
+
+/** 十进制数（'1.5'、'2e-7'、1.5）→ 分子 / 分母，精确，不经过浮点 */
+export function parseDecimal(value: string | number): { num: bigint; den: bigint } {
+  const text = typeof value === 'number' ? (Number.isFinite(value) ? String(value) : '') : value.trim()
+  const m = /^\+?(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/.exec(text)
+  if (!m || (!m[1] && !m[2])) {
+    throw new Error(`Invalid number: ${String(value)}`)
+  }
+  const frac = m[2] ?? ''
+  const exp = Number(m[3] ?? 0) - frac.length
+  if (Math.abs(exp) > 400) {
+    throw new RangeError(`Number out of range: ${String(value)}`)
+  }
+  const digits = BigInt(`${m[1] ?? ''}${frac}` || '0')
+  return exp >= 0 ? { num: digits * 10n ** BigInt(exp), den: 1n } : { num: digits, den: 10n ** BigInt(-exp) }
+}
+
+/** 价格（token1 / token0，按精度换算）→ Q64.64 sqrt 价格（向下取整）；num / den 是价格的分子分母 */
+export function ratioToSqrtPrice(num: bigint, den: bigint, decimals0: number, decimals1: number): bigint {
+  if (num <= 0n || den <= 0n) {
+    throw new RangeError('price must be greater than 0')
+  }
+  const scale = decimals1 - decimals0
+  return sqrtBigInt((num * (scale > 0 ? 10n ** BigInt(scale) : 1n) * 2n ** 128n) / (den * (scale < 0 ? 10n ** BigInt(-scale) : 1n)))
+}
+
+/** 价格（token1 / token0，按精度换算）→ tick（按程序；满足价格 >= tick 价格的最大 tick） */
+export function priceToTick(program: ClmmProgram, price: string | number, decimals0: number, decimals1: number): number {
+  const { num, den } = parseDecimal(price)
+  return tickAtSqrtPrice(program, ratioToSqrtPrice(num, den, decimals0, decimals1))
+}
+
+/** 最近的可用 tick（tickSpacing 的整数倍），限制在 [MIN_TICK, MAX_TICK] 内 */
+export function nearestUsableTick(tick: number, tickSpacing: number): number {
+  if (!Number.isInteger(tickSpacing) || tickSpacing <= 0) {
+    throw new RangeError(`invalid tickSpacing: ${tickSpacing}`)
+  }
+  const rounded = Math.round(tick / tickSpacing) * tickSpacing
+  if (rounded < MIN_TICK) {
+    return rounded + tickSpacing
+  }
+  if (rounded > MAX_TICK) {
+    return rounded - tickSpacing
+  }
+  return rounded
+}
+
+/** 价格按 slippage 上下浮动后的 sqrt 价格和对应的 tick，限制在程序允许的范围内（slippage 是比例，精确到百万分之一） */
+export function sqrtPriceBounds(program: ClmmProgram, sqrtPrice: bigint, slippage: number): Array<{ sqrtPrice: bigint; tick: number }> {
+  if (!(slippage >= 0 && slippage < 1)) {
+    throw new RangeError(`slippage must be in [0, 1): ${slippage}`)
+  }
+  const [min, max] = sqrtRange(program)
+  const ppm = BigInt(Math.round(slippage * 1e6))
+  const square = sqrtPrice * sqrtPrice
+  return [1_000_000n - ppm, 1_000_000n + ppm].map((factor) => {
+    let s = sqrtBigInt((square * factor) / 1_000_000n)
+    s = s < min ? min : s >= max ? max - 1n : s
+    return { sqrtPrice: s, tick: tickAtSqrtPrice(program, s) }
+  })
+}
+
+/** 价格在 slippage 范围内变动时，流动性 L 至少对应多少代币（移除时的最小数量，向下取整） */
+export function getMinAmounts(program: ClmmProgram, sqrtPrice: bigint, tickLower: number, tickUpper: number, liquidity: bigint, slippage: number): [bigint, bigint] {
+  const [lower, upper] = sqrtPriceBounds(program, sqrtPrice, slippage) as [{ sqrtPrice: bigint; tick: number }, { sqrtPrice: bigint; tick: number }]
+  const a = sqrtPriceAtTick(program, tickLower)
+  const b = sqrtPriceAtTick(program, tickUpper)
+  // token0 随价格上涨而减少，取上限价格时的；token1 取下限价格时的
+  return [
+    getAmountsForLiquidity(upper.tick, upper.sqrtPrice, a, b, liquidity, tickLower, tickUpper)[0],
+    getAmountsForLiquidity(lower.tick, lower.sqrtPrice, a, b, liquidity, tickLower, tickUpper)[1],
+  ]
+}
+
+/** 价格在 slippage 范围内变动时，添加流动性 L 最多需要多少代币（amountMax，向上取整） */
+export function getMaxAmounts(program: ClmmProgram, sqrtPrice: bigint, tickLower: number, tickUpper: number, liquidity: bigint, slippage: number): [bigint, bigint] {
+  const [lower, upper] = sqrtPriceBounds(program, sqrtPrice, slippage) as [{ sqrtPrice: bigint; tick: number }, { sqrtPrice: bigint; tick: number }]
+  const a = sqrtPriceAtTick(program, tickLower)
+  const b = sqrtPriceAtTick(program, tickUpper)
+  return [
+    getMintAmounts(lower.tick, lower.sqrtPrice, a, b, liquidity, tickLower, tickUpper)[0],
+    getMintAmounts(upper.tick, upper.sqrtPrice, a, b, liquidity, tickLower, tickUpper)[1],
+  ]
+}