@w3lib/solana-batch-call 0.2.2 → 0.4.0

package/src/lpMath.ts

@@ -0,0 +1,420 @@
+/**
+ * 集中流动性（Raydium CLMM / Orca Whirlpool）的定点数计算，与链上程序逐位一致（Q64.64，bigint）。
+ * 两个程序的 tick → 价格换算用的常量和步骤不同（结果在最后几位可能不同），各自照搬；
+ * 数量和手续费的公式两边相同：撤出流动性时向下取整，手续费增长按 u128 回绕相减。
+ */
+
+const Q64 = 1n << 64n
+const U128_MAX = (1n << 128n) - 1n
+const U64_MAX = (1n << 64n) - 1n
+
+export const MIN_TICK = -443636
+export const MAX_TICK = 443636
+
+function checkTick(tick: number): void {
+  if (!Number.isInteger(tick) || tick < MIN_TICK || tick > MAX_TICK) {
+    throw new RangeError(`Tick out of range: ${tick}`)
+  }
+}
+
+// raydium-clmm programs/amm/src/libraries/tick_math.rs（第 0 项对应 abs_tick & 0x1）
+const RAYDIUM_RATIOS = [
+  0xfffcb933bd6fb800n,
+  0xfff97272373d4000n,
+  0xfff2e50f5f657000n,
+  0xffe5caca7e10f000n,
+  0xffcb9843d60f7000n,
+  0xff973b41fa98e800n,
+  0xff2ea16466c9b000n,
+  0xfe5dee046a9a3800n,
+  0xfcbe86c7900bb000n,
+  0xf987a7253ac65800n,
+  0xf3392b0822bb6000n,
+  0xe7159475a2caf000n,
+  0xd097f3bdfd2f2000n,
+  0xa9f746462d9f8000n,
+  0x70d869a156f31c00n,
+  0x31be135f97ed3200n,
+  0x9aa508b5b85a500n,
+  0x5d6af8dedc582cn,
+  0x2216e584f5fan,
+]
+
+/** Raydium CLMM：tick → sqrt 价格（Q64.64） */
+export function raydiumSqrtPriceAtTick(tick: number): bigint {
+  checkTick(tick)
+  const abs = Math.abs(tick)
+  let ratio = abs & 1 ? (RAYDIUM_RATIOS[0] as bigint) : Q64
+  for (let i = 1; i < RAYDIUM_RATIOS.length; i++) {
+    if (abs & (1 << i)) {
+      ratio = (ratio * (RAYDIUM_RATIOS[i] as bigint)) >> 64n
+    }
+  }
+  return tick > 0 ? U128_MAX / ratio : ratio
+}
+
+// orca whirlpools programs/whirlpool/src/math/tick_math.rs：正 tick 用 Q96 常量，负 tick 用 Q64 常量
+const ORCA_POSITIVE = [
+  79232123823359799118286999567n,
+  79236085330515764027303304731n,
+  79244008939048815603706035061n,
+  79259858533276714757314932305n,
+  79291567232598584799939703904n,
+  79355022692464371645785046466n,
+  79482085999252804386437311141n,
+  79736823300114093921829183326n,
+  80248749790819932309965073892n,
+  81282483887344747381513967011n,
+  83390072131320151908154831281n,
+  87770609709833776024991924138n,
+  97234110755111693312479820773n,
+  119332217159966728226237229890n,
+  179736315981702064433883588727n,
+  407748233172238350107850275304n,
+  2098478828474011932436660412517n,
+  55581415166113811149459800483533n,
+  38992368544603139932233054999993551n,
+]
+const ORCA_NEGATIVE = [
+  18445821805675392311n,
+  18444899583751176498n,
+  18443055278223354162n,
+  18439367220385604838n,
+  18431993317065449817n,
+  18417254355718160513n,
+  18387811781193591352n,
+  18329067761203520168n,
+  18212142134806087854n,
+  17980523815641551639n,
+  17526086738831147013n,
+  16651378430235024244n,
+  15030750278693429944n,
+  12247334978882834399n,
+  8131365268884726200n,
+  3584323654723342297n,
+  696457651847595233n,
+  26294789957452057n,
+  37481735321082n,
+]
+
+/** Orca Whirlpool：tick → sqrt 价格（Q64.64） */
+export function orcaSqrtPriceAtTick(tick: number): bigint {
+  checkTick(tick)
+  if (tick >= 0) {
+    let ratio = tick & 1 ? (ORCA_POSITIVE[0] as bigint) : 1n << 96n
+    for (let i = 1; i < ORCA_POSITIVE.length; i++) {
+      if (tick & (1 << i)) {
+        ratio = (ratio * (ORCA_POSITIVE[i] as bigint)) >> 96n
+      }
+    }
+    return ratio >> 32n
+  }
+  const abs = -tick
+  let ratio = abs & 1 ? (ORCA_NEGATIVE[0] as bigint) : Q64
+  for (let i = 1; i < ORCA_NEGATIVE.length; i++) {
+    if (abs & (1 << i)) {
+      ratio = (ratio * (ORCA_NEGATIVE[i] as bigint)) >> 64n
+    }
+  }
+  return ratio
+}
+
+/**
+ * 撤出全部流动性能拿到的两种代币数量（向下取整）。两个程序都按当前 tick（不是价格）判断区间：
+ * tick < 下限只有 token0；tick ≥ 上限只有 token1；否则两种都有
+ */
+export function getAmountsForLiquidity(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 [amount0Delta(sqrtLower, sqrtUpper, liquidity), 0n]
+  }
+  if (tick < tickUpper) {
+    return [amount0Delta(sqrtPrice, sqrtUpper, liquidity), amount1Delta(sqrtLower, sqrtPrice, liquidity)]
+  }
+  return [0n, amount1Delta(sqrtLower, sqrtUpper, liquidity)]
+}
+
+/** floor(L · 2^64 · (b − a) / (a · b)) */
+function amount0Delta(a: bigint, b: bigint, liquidity: bigint): bigint {
+  const [lo, hi] = a < b ? [a, b] : [b, a]
+  return lo === 0n ? 0n : ((liquidity << 64n) * (hi - lo)) / (lo * hi)
+}
+
+/** floor(L · (b − a) / 2^64) */
+function amount1Delta(a: bigint, b: bigint, liquidity: bigint): bigint {
+  const [lo, hi] = a < b ? [a, b] : [b, a]
+  return (liquidity * (hi - lo)) >> 64n
+}
+
+/** 一个 tick 上用于计算手续费的数据；Orca 的 tick 未初始化时 initialized 为 false */
+export interface TickFeeData {
+  initialized: boolean
+  feeGrowthOutside0: bigint
+  feeGrowthOutside1: bigint
+}
+
+const wrap = (x: bigint) => ((x % (1n << 128n)) + (1n << 128n)) % (1n << 128n)
+
+/**
+ * 区间内的手续费增长（u128 回绕）。Raydium 不区分是否初始化（未初始化的 tick 各项为 0，传 initialized: true 即可）；
+ * Orca 未初始化的 tick：下限按“下方增长 = 全局”、上限按“上方增长 = 0”处理（与程序一致）
+ */
+export function getFeeGrowthInside(
+  tick: number,
+  tickLower: number,
+  lower: TickFeeData,
+  tickUpper: number,
+  upper: TickFeeData,
+  global0: bigint,
+  global1: bigint,
+): [bigint, bigint] {
+  const below = !lower.initialized
+    ? [global0, global1]
+    : tick < tickLower
+      ? [wrap(global0 - lower.feeGrowthOutside0), wrap(global1 - lower.feeGrowthOutside1)]
+      : [lower.feeGrowthOutside0, lower.feeGrowthOutside1]
+  const above = !upper.initialized
+    ? [0n, 0n]
+    : tick < tickUpper
+      ? [upper.feeGrowthOutside0, upper.feeGrowthOutside1]
+      : [wrap(global0 - upper.feeGrowthOutside0), wrap(global1 - upper.feeGrowthOutside1)]
+  return [wrap(global0 - (below[0] as bigint) - (above[0] as bigint)), wrap(global1 - (below[1] as bigint) - (above[1] as bigint))]
+}
+
+/**
+ * 未领取的手续费：已记账的 owed + L · (区间内增长 − 上次记录) / 2^64（向下取整）。
+ * 新增部分超过 u64 时：Orca 程序记为 0（checked_mul_shift_right 失败），这里同样记为 0（正常仓位不会碰到）
+ */
+export function getFeesOwed(owed: bigint, liquidity: bigint, growthInside: bigint, growthLast: bigint): bigint {
+  const delta = (liquidity * wrap(growthInside - growthLast)) >> 64n
+  return owed + (delta > U64_MAX ? 0n : delta)
+}
+
+/** Q64.64 sqrt 价格 → token1 / token0 的价格（按精度换算，浮点数，只用于展示） */
+export function sqrtPriceToPrice(sqrtPrice: bigint, decimals0: number, decimals1: number): number {
+  // 先取高位再转浮点，避免 2^128 级别的整数转换丢精度后再平方
+  const ratio = Number(sqrtPrice) / 2 ** 64
+  return ratio * ratio * 10 ** (decimals0 - decimals1)
+}
+
+/** tick → token1 / token0 的价格（1.0001^tick，按精度换算，只用于展示） */
+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],
+  ]
+}

package/src/shortcuts.ts

@@ -81,7 +81,7 @@ function sourceKey(source: ShortcutOptions['provider']): string | object | null
  * 拆出节点参数和函数自己的参数（ownKeys），其余作为客户端配置；值为 undefined 的参数忽略。
  * signal 总是作为函数自己的参数（放进客户端配置会让每次调用都新建客户端）
  */
-function resolve<T extends ShortcutOptions, K extends keyof T & string = never>(
+export function resolve<T extends ShortcutOptions, K extends keyof T & string = never>(
   options: T,
   ownKeys: readonly K[] = [],
 ): { client: SolanaClient; own: Pick<T, K> } {

package/src/subpaths/liquidity.ts

@@ -0,0 +1,45 @@
+/**
+ * 添加 / 移除流动性（子路径 `@w3lib/solana-batch-call/liquidity`）：Raydium CLMM、Orca Whirlpool（仓位 NFT），
+ * Raydium AMM v4、CPMM（LP 代币）。不放在主入口，不用时打包不会带上这部分代码。不依赖各 DEX 的 SDK。
+ *
+ * - build*：只读取、不签名，返回预计的数量和按顺序执行的指令，可以当作报价，也可以自己组交易发送
+ * - addLiquidity / removeLiquidity / collectFees：构建后签名发送（同 /write 的 batchCall），SOL 自动包装 / 解包
+ *
+ * ```ts
+ * import { getLpPositions } from '@w3lib/solana-batch-call/lp'
+ * import { addLiquidity, removeLiquidity } from '@w3lib/solana-batch-call/liquidity'
+ *
+ * await addLiquidity(client, secretKey, { protocol: 'raydium-clmm', pool, priceLower: 120, priceUpper: 180, amount0Formatted: '1' })
+ * const [position] = await getLpPositions(owner, { provider: rpc })
+ * await removeLiquidity(client, secretKey, { position, percent: 50 })
+ * ```
+ */
+export { addLiquidity, buildAddLiquidity, buildCollectFees, buildRemoveLiquidity, collectFees, removeLiquidity } from '../liquidity/index.js'
+export type {
+  SolanaAddLiquidityParams,
+  SolanaCollectFeesParams,
+  SolanaIncreaseLiquidityParams,
+  SolanaLiquidityOptions,
+  SolanaLiquidityPlan,
+  SolanaLiquidityResult,
+  SolanaLiquiditySendOptions,
+  SolanaLiquidityStep,
+  SolanaLiquidityStepResult,
+  SolanaNewPositionParams,
+  SolanaPositionRef,
+  SolanaRemoveLiquidityParams,
+} from '../liquidity/types.js'
+export {
+  getLiquidityForAmounts,
+  getMaxAmounts,
+  getMinAmounts,
+  getMintAmounts,
+  nearestUsableTick,
+  priceToTick,
+  sqrtPriceAtTick,
+  tickAtSqrtPrice,
+  type ClmmProgram,
+} from '../lpMath.js'
+export type { SolanaLpPosition, SolanaLpProtocol, SolanaLpToken } from '../lp.js'
+export type { Instruction } from '../write/transaction.js'
+export type { SignerInput, WriteResult, WriteStatus } from '../subpaths/write.js'

package/src/subpaths/lp.ts

@@ -0,0 +1,71 @@
+/**
+ * LP 仓位（子路径 `@w3lib/solana-batch-call/lp`）：Raydium CLMM / Orca Whirlpool 的仓位 NFT，Raydium AMM v4 / CPMM 的 LP 代币，
+ * 代币数量、未领取的手续费、可选的美元价值。不放在主入口，不用时打包不会带上这部分代码。
+ *
+ * ```ts
+ * import { getLpPositions } from '@w3lib/solana-batch-call/lp'
+ *
+ * await getLpPositions(owner, { provider: 'https://my-rpc…' })                  // 扫描全部代币账户（需要支持 getTokenAccountsByOwner 的节点）
+ * await getLpPositions(owner, { mints: [positionNftMint], prices: true })        // 只看这些代币：免费公共节点也能用
+ * ```
+ */
+import { lpPositions, type LpPositionsOptions, type SolanaLpPosition } from '../lp.js'
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+
+export {
+  ORCA_WHIRLPOOL_PROGRAM_ID,
+  RAYDIUM_AMM_PROGRAM_ID,
+  RAYDIUM_CLMM_PROGRAM_ID,
+  RAYDIUM_CPMM_PROGRAM_ID,
+  SOLANA_LP_PROTOCOLS,
+  defillamaPrices,
+  lpPositions,
+  type LpPositionsOptions,
+  type SolanaLpAmmPosition,
+  type SolanaLpClmmPosition,
+  type SolanaLpPosition,
+  type SolanaLpProtocol,
+  type SolanaLpToken,
+  type SolanaPriceSource,
+} from '../lp.js'
+export {
+  MAX_TICK,
+  MIN_TICK,
+  getAmountsForLiquidity,
+  getFeeGrowthInside,
+  getFeesOwed,
+  getLiquidityForAmounts,
+  getMaxAmounts,
+  getMinAmounts,
+  getMintAmounts,
+  nearestUsableTick,
+  orcaSqrtPriceAtTick,
+  priceToTick,
+  raydiumSqrtPriceAtTick,
+  sqrtPriceAtTick,
+  sqrtPriceToPrice,
+  tickAtSqrtPrice,
+  tickToPrice,
+  type ClmmProgram,
+  type TickFeeData,
+} from '../lpMath.js'
+
+export interface GetLpPositionsOptions extends LpPositionsOptions, ShortcutOptions {}
+
+/**
+ * 查一个地址的 LP 仓位。
+ *
+ * ```ts
+ * await getLpPositions(owner, { provider: 'https://my-rpc…' })
+ * // [{ type: 'clmm', protocol: 'raydium-clmm', pool, positionMint, token0: { symbol: 'SOL', … }, token1: { symbol: 'USDC', … },
+ * //    amount0Formatted: '140.26', amount1Formatted: '6852.2', fees0Formatted: '0.546', fees1Formatted: '59.5', inRange: true, … },
+ * //  { type: 'amm', protocol: 'raydium-amm', pool, lpMint, balance, share: 0.18, amount0Formatted, amount1Formatted, … }]
+ * await getLpPositions(owner, { mints: [nftMint, lpMint], pools: [ammPool] })   // 免费公共节点：指定代币和池子
+ * await getLpPositions(owner, { provider, prices: true })                        // 带美元价值（DefiLlama），按价值排序
+ * ```
+ */
+export function getLpPositions(owner: string, options: GetLpPositionsOptions = {}): Promise<SolanaLpPosition[]> {
+  // fetch 同时给节点请求（客户端配置）和查价用，与其他快捷函数一致
+  const { client, own } = resolve(options, ['protocols', 'mints', 'pools', 'includeClosed', 'prices', 'onPriceError', 'signal'])
+  return lpPositions(client, owner, { ...own, ...(options.fetch ? { fetch: options.fetch } : {}) })
+}

package/src/subpaths/write.ts

@@ -0,0 +1,29 @@
+/**
+ * 批量写操作（子路径 `@w3lib/solana-batch-call/write`）：批量调用程序、一对多转账、多钱包归集。
+ * 不放在主入口，只做查询时打包不会带上这部分代码。不依赖 Solana SDK，签名用运行环境的 WebCrypto（Ed25519）。
+ *
+ * ```ts
+ * import { SolanaClient, NATIVE_MINT } from '@w3lib/solana-batch-call'
+ * import { batchCall, batchCollect, batchTransfer } from '@w3lib/solana-batch-call/write'
+ *
+ * const client = new SolanaClient(rpcUrl)
+ * await batchTransfer(client, secretKey, [{ to: a, formatted: '0.5' }, { to: b, token: USDC, formatted: '20' }])
+ * await batchCollect(client, [key1, key2], hotWallet, { tokens: [USDC, NATIVE_MINT], feePayer: gasKey })
+ * await batchCall(client, [{ from: key1, instructions: [ix1, ix2] }])
+ * ```
+ */
+export { batchCall, type BatchCallMode, type BatchCallOptions, type WriteCall } from '../write/batch.js'
+export { batchCollect, type BatchCollectOptions, type CollectItemResult, type CollectResult } from '../write/collect.js'
+export { batchTransfer, type BatchTransferOptions, type TransferItem, type TransferMode, type TransferResult } from '../write/transfer.js'
+export {
+  COMPUTE_BUDGET_PROGRAM_ID,
+  closeAccount,
+  createAssociatedTokenAccountIdempotent,
+  setComputeUnitLimit,
+  setComputeUnitPrice,
+  systemTransfer,
+  transferChecked,
+} from '../write/instructions.js'
+export type { SendOptions, WriteResult, WriteStatus } from '../write/send.js'
+export type { SignerInput, WriteSigner } from '../write/signer.js'
+export type { AccountMeta, Instruction, InstructionInput } from '../write/transaction.js'

package/src/write/batch.ts

@@ -0,0 +1,78 @@
+import type { SolanaClient } from '../client.js'
+import { emptyOutcome, sendUnits, toWriteResult, type SendOptions, type Unit, type WriteResult } from './send.js'
+import { resolveSigner, type SignerInput } from './signer.js'
+import { COMPUTE_BUDGET_PROGRAM_ID } from './instructions.js'
+import { normalizeInstruction, type InstructionInput } from './transaction.js'
+
+/** 一个写调用：一组要原子执行的指令 */
+export interface WriteCall {
+  /** 发送的钱包（指令里的签名者之一）；不传 feePayer 时也由它付手续费 */
+  from: SignerInput
+  /** 指令：@solana/web3.js 的 TransactionInstruction、@solana/kit 的 Instruction 或本库格式，一个或多个 */
+  instructions: InstructionInput | readonly InstructionInput[]
+  /** 指令需要的其他签名者（如新建账户的 Keypair） */
+  signers?: readonly SignerInput[]
+}
+
+/**
+ * - 'pack'（默认）：同一手续费支付者的相邻调用打包进同一笔交易（不超过 1232 字节、64 个账户），
+ *   模拟时失败的调用会被剔除、其余照常发送；同一笔交易上链后才失败时一起回滚
+ * - 'tx'：每个调用一笔交易
+ */
+export type BatchCallMode = 'pack' | 'tx'
+
+export interface BatchCallOptions extends SendOptions {
+  mode?: BatchCallMode
+  /** 'pack' 时每笔交易最多几个调用，默认不限（只受交易大小限制） */
+  batchSize?: number
+  /**
+   * 某个调用发送前失败（模拟失败等）后，同一支付者后面的调用是否继续。默认 false（后面的标记为 skipped）。
+   * 交易不等上一笔确认就连续发出，已经发出、之后上链失败的交易拦不住后面已发出的交易
+   */
+  continueOnError?: boolean
+}
+
+/**
+ * 批量调用程序（写操作）。结果与 calls 一一对应。
+ *
+ * ```ts
+ * await batchCall(client, [
+ *   { from: key1, instructions: [ix1, ix2] },   // 同一个调用里的指令原子执行
+ *   { from: key2, instructions: ix3 },
+ * ], { feePayer: gasKey })                       // 手续费都由 gasKey 付，不同钱包的调用也能打包进同一笔交易
+ * ```
+ */
+export async function batchCall(client: SolanaClient, calls: readonly WriteCall[], options: BatchCallOptions = {}): Promise<WriteResult[]> {
+  const cache = new Map()
+  const feePayer = options.feePayer === undefined ? undefined : await resolveSigner(options.feePayer, cache)
+  const prepared = await Promise.all(
+    calls.map(async (call, i) => {
+      const from = await resolveSigner(call.from, cache)
+      const signers = [from, ...(await Promise.all((call.signers ?? []).map((s) => resolveSigner(s, cache))))]
+      const list = Array.isArray(call.instructions) ? (call.instructions as readonly InstructionInput[]) : [call.instructions as InstructionInput]
+      // 库会自动加计算单元上限和优先费用指令；调用里自带的同类指令去掉（重复会让整笔交易失败），优先费用用 priorityFee 选项
+      const instructions = list.map(normalizeInstruction).filter((ix) => !(ix.programId === COMPUTE_BUDGET_PROGRAM_ID && (ix.data[0] === 2 || ix.data[0] === 3)))
+      const payer = feePayer ?? from
+      const known = new Set([payer.address, ...signers.map((s) => s.address)])
+      const missing = instructions.flatMap((ix) => ix.keys).find((k) => k.isSigner && !known.has(k.pubkey))
+      if (missing) {
+        throw new Error(`calls[${i}]: an instruction requires the signature of ${missing.pubkey}; pass it in signers`)
+      }
+      return { from, signers, instructions, payer }
+    }),
+  )
+  const results = prepared.map((p, i) => toWriteResult(i, p.from.address, emptyOutcome('skipped')))
+  const units: Unit[] = prepared.map((p, i) => ({
+    instructions: p.instructions,
+    payer: p.payer,
+    signers: p.signers.filter((s) => s.address !== p.payer.address),
+    continueOnError: options.continueOnError,
+    onUpdate: (outcome) => {
+      results[i] = toWriteResult(i, p.from.address, outcome)
+      options.onUpdate?.(results[i] as WriteResult)
+    },
+  }))
+  await sendUnits(client, units, options, { batchSize: (options.mode ?? 'pack') === 'tx' ? 1 : options.batchSize })
+  return results
+}
+