@w3lib/evm-batch-call 0.5.0 → 0.6.0

package/src/liquidity/common.ts

@@ -0,0 +1,314 @@
+import { Interface, MaxUint256, ZeroAddress, getAddress, getBigInt, parseUnits, type BigNumberish } from 'ethers'
+
+import { formatUnits } from '../erc20.js'
+import { LP_PROTOCOLS, type LpPosition, type LpProtocol, type LpToken, type LpVersion } from '../lp.js'
+import { sqrtPriceToPrice, tickToPrice } from '../lpMath.js'
+import type { Provider } from '../provider.js'
+import { isTronAddress, isTronChain, toEvmAddress, toTronAddress } from '../tron.js'
+import type { LiquidityOptions, LiquidityPlan, LiquidityTx, PositionRef } from './types.js'
+
+export const ZERO_ADDRESS = ZeroAddress
+export { MAX_UINT128 } from '../lpMath.js'
+const MAX_UINT160 = 2n ** 160n - 1n
+/** Uniswap 的 Permit2（各 EVM 链上地址相同），V4 的仓位合约通过它收取代币 */
+export const PERMIT2_ADDRESS = '0x000000000022D473030F116dDEE9F6B43aC78BA3'
+/** Permit2 授权的有效期：30 天（与 Uniswap 网页一致） */
+const PERMIT2_EXPIRATION = 30 * 24 * 3600
+
+export const erc20Interface = new Interface([
+  'function allowance(address owner, address spender) view returns (uint256)',
+  'function approve(address spender, uint256 amount) returns (bool)',
+])
+const permit2Interface = new Interface([
+  'function allowance(address owner, address token, address spender) view returns (uint160 amount, uint48 expiration, uint48 nonce)',
+  'function approve(address token, address spender, uint160 amount, uint48 expiration)',
+])
+
+/** 一次构建用到的公共信息 */
+export interface Ctx {
+  provider: Provider
+  chainId: number
+  tron: boolean
+  /** 0x 格式（ABI 编码用） */
+  owner: string
+  recipient: string
+  slippage: number
+  /** 截止时间（秒级时间戳） */
+  deadline: number
+  options: LiquidityOptions
+}
+
+/** 地址统一成 0x 的校验和格式（Tron 的 T 地址先转换） */
+export function evm(address: string): string {
+  return getAddress(isTronAddress(address) ? toEvmAddress(address) : address)
+}
+
+export const same = (a: string, b: string) => evm(a) === evm(b)
+
+/** 输出的地址：Tron 上转成 T 地址 */
+export function out(ctx: Pick<Ctx, 'tron'>, address: string): string {
+  return ctx.tron ? toTronAddress(address) : address
+}
+
+export async function createCtx(provider: Provider, owner: string, options: LiquidityOptions): Promise<Ctx> {
+  const chainId = await provider.getChainId()
+  const slippage = options.slippage ?? 0.005
+  if (!(slippage >= 0 && slippage < 1)) {
+    throw new RangeError(`slippage must be in [0, 1): ${slippage}`)
+  }
+  const seconds = options.deadline ?? 1200
+  if (!(seconds > 0)) {
+    throw new RangeError(`deadline must be greater than 0: ${seconds}`)
+  }
+  return {
+    provider,
+    chainId,
+    tron: isTronChain(chainId),
+    owner: evm(owner),
+    recipient: evm(options.recipient ?? owner),
+    slippage,
+    deadline: Math.floor(Date.now() / 1000) + Math.floor(seconds),
+    options,
+  }
+}
+
+/** 是否是主币地址（NATIVE_TOKEN / 零地址，或 Provider 配置的主币地址） */
+export function isNative(ctx: Ctx, address: string): boolean {
+  return evm(address) === ZERO_ADDRESS || ctx.provider.isNativeToken(address) || ctx.provider.isNativeToken(evm(address))
+}
+
+/** 代币信息（symbol / 精度）；零地址是 V4 的主币 */
+export async function tokenInfo(ctx: Ctx, addresses: readonly string[]): Promise<LpToken[]> {
+  const nativeAlias = ctx.provider.isNativeToken(ZERO_ADDRESS) ? undefined : ctx.provider.nativeTokens[0]
+  const query = addresses.map((a) => (a === ZERO_ADDRESS && nativeAlias !== undefined ? nativeAlias : a))
+  const details = await ctx.provider.tokens(query, { fields: ['symbol', 'decimals'] })
+  return addresses.map((address, i) => {
+    const d = details[i]
+    return { address: out(ctx, address), native: d?.native ?? false, symbol: d?.symbol ?? null, decimals: d?.decimals ?? null }
+  })
+}
+
+export function fmt(value: bigint, token: LpToken): string | null {
+  return token.decimals === null ? null : formatUnits(value, token.decimals)
+}
+
+/** 解析输入的数量：amount（最小单位）和 formatted 二选一，都没给时返回 undefined */
+export function parseAmount(raw: BigNumberish | undefined, formatted: string | undefined, token: LpToken, name: string): bigint | undefined {
+  if (raw !== undefined && formatted !== undefined) {
+    throw new Error(`Pass either ${name} or ${name}Formatted, not both`)
+  }
+  let value: bigint
+  if (formatted !== undefined) {
+    if (token.decimals === null) {
+      throw new Error(`Cannot read the decimals of ${token.address}; pass ${name} in raw units instead of ${name}Formatted`)
+    }
+    value = parseUnits(formatted, token.decimals)
+  } else if (raw !== undefined) {
+    value = getBigInt(raw)
+  } else {
+    return undefined
+  }
+  if (value < 0n) {
+    throw new RangeError(`${name} must not be negative`)
+  }
+  return value
+}
+
+/** 按滑点向下取：value × (1 − slippage) */
+export function minus(value: bigint, slippage: number): bigint {
+  return (value * (1_000_000n - BigInt(Math.round(slippage * 1e6)))) / 1_000_000n
+}
+
+/** 移除的数量：percent（百分数）或 liquidity，二选一，默认全部 */
+export function removeAmount(total: bigint, percent: number | undefined, liquidity: BigNumberish | undefined): bigint {
+  if (percent !== undefined && liquidity !== undefined) {
+    throw new Error('Pass either percent or liquidity, not both')
+  }
+  if (liquidity !== undefined) {
+    const value = getBigInt(liquidity)
+    if (value <= 0n || value > total) {
+      throw new RangeError(`liquidity must be in (0, ${total}]: ${value}`)
+    }
+    return value
+  }
+  const p = percent ?? 100
+  if (!(p > 0 && p <= 100)) {
+    throw new RangeError(`percent must be in (0, 100]: ${p}`)
+  }
+  const amount = p === 100 ? total : (total * BigInt(Math.round(p * 10_000))) / 1_000_000n
+  if (amount === 0n) {
+    throw new RangeError(`${p}% of ${total} rounds to 0`)
+  }
+  return amount
+}
+
+/** 选出协议：自定义的优先，再找内置表 */
+function candidates(ctx: Ctx): LpProtocol[] {
+  return [...(ctx.options.protocols ?? []).filter((p) => p.chainId === ctx.chainId), ...LP_PROTOCOLS.filter((p) => p.chainId === ctx.chainId)]
+}
+
+export function protocolById(ctx: Ctx, protocol: string | LpProtocol): LpProtocol {
+  if (typeof protocol !== 'string') {
+    if (protocol.chainId !== ctx.chainId) {
+      throw new Error(`Protocol ${protocol.id} is on chain ${protocol.chainId}, not ${ctx.chainId}`)
+    }
+    return protocol
+  }
+  const found = candidates(ctx).find((p) => p.id === protocol)
+  if (!found) {
+    throw new Error(`Unknown LP protocol ${protocol} on chain ${ctx.chainId}; pass an LpProtocol object (or options.protocols) for protocols that are not built in`)
+  }
+  return found
+}
+
+/** V3 / V4 仓位所属的协议：按 positionManager 找，没有时按协议 id */
+export function concentratedProtocol(ctx: Ctx, ref: PositionRef | LpPosition): LpProtocol {
+  const pm = 'positionManager' in ref && ref.positionManager ? evm(ref.positionManager) : null
+  if (pm) {
+    const fromRef = ref.protocol && typeof ref.protocol !== 'string' ? [ref.protocol] : []
+    const found = [...fromRef, ...candidates(ctx)].find((p) => (p.version === 'v3' || p.version === 'v4') && p.positionManager && same(p.positionManager, pm))
+    if (!found) {
+      throw new Error(`Unknown position manager ${pm} on chain ${ctx.chainId}; pass its LpProtocol in options.protocols`)
+    }
+    return found
+  }
+  if (!ref.protocol) {
+    throw new Error('position needs positionManager or protocol')
+  }
+  const found = protocolById(ctx, ref.protocol)
+  if (found.version === 'v2') {
+    throw new Error(`${found.id} is a V2 protocol; V2 positions are identified by pool`)
+  }
+  return found
+}
+
+/** 仓位是哪个版本：LpPosition 自带；PositionRef 有 tokenId 的看协议，否则是 V2 */
+export function positionVersion(ctx: Ctx, ref: PositionRef | LpPosition): LpVersion {
+  if ('version' in ref && (ref.version === 'v2' || ref.version === 'v3' || ref.version === 'v4')) {
+    return ref.version
+  }
+  if (!('tokenId' in ref) || ref.tokenId === undefined) {
+    if (!ref.pool) {
+      throw new Error('position needs pool (V2) or tokenId (V3 / V4)')
+    }
+    // 传了 V3 / V4 的协议却没有 tokenId：说清楚，不要当成 V2 的池子去读
+    if (ref.protocol && (typeof ref.protocol === 'string' ? protocolById(ctx, ref.protocol) : ref.protocol).version !== 'v2') {
+      throw new Error('position.tokenId is required for V3 / V4 positions')
+    }
+    return 'v2'
+  }
+  return concentratedProtocol(ctx, ref).version
+}
+
+export function tokenIdOf(ref: PositionRef | LpPosition): bigint {
+  if (!('tokenId' in ref) || ref.tokenId === undefined) {
+    throw new Error('position.tokenId is required')
+  }
+  if (typeof ref.tokenId === 'number' && !Number.isSafeInteger(ref.tokenId)) {
+    throw new RangeError(`tokenId ${ref.tokenId} is not a safe integer; pass it as a string or bigint`)
+  }
+  return getBigInt(ref.tokenId)
+}
+
+/**
+ * 要求先把额度归零才能改成另一个非零值的代币（chainId:小写地址）。只对它们先 approve 0：
+ * 有的代币（如 Ethereum 上的 BNB）反过来不允许 approve 0
+ */
+const RESET_FIRST = new Set([
+  '1:0xdac17f958d2ee523a2206206994597c13d831ec7', // USDT
+  '1:0xdd974d5c2e2928dea5f71b9825b8b646686bd200', // KNC（旧版）
+])
+
+/** ERC20 授权：额度不够时 approve（USDT 等已有非零额度时先 approve 0）。amount 为 0 的不需要 */
+export async function approvals(ctx: Ctx, items: ReadonlyArray<{ token: string; spender: string; amount: bigint }>): Promise<LiquidityTx[]> {
+  const needed = items.filter((i) => i.amount > 0n)
+  if (!needed.length) {
+    return []
+  }
+  const current = await ctx.provider.all(needed.map((i) => ctx.provider.contract(i.token, erc20Interface).allowance(ctx.owner, i.spender)))
+  return needed.flatMap((item, k): LiquidityTx[] => {
+    const allowance = (current as bigint[])[k] as bigint
+    if (allowance >= item.amount) {
+      return []
+    }
+    const amount = ctx.options.approve === 'max' ? MaxUint256 : item.amount
+    const tx = (value: bigint): LiquidityTx => ({
+      kind: 'approve',
+      to: out(ctx, item.token),
+      data: erc20Interface.encodeFunctionData('approve', [item.spender, value]),
+      value: '0',
+      token: out(ctx, item.token),
+      spender: out(ctx, item.spender),
+      amount: value.toString(),
+    })
+    return allowance > 0n && RESET_FIRST.has(`${ctx.chainId}:${item.token.toLowerCase()}`) ? [tx(0n), tx(amount)] : [tx(amount)]
+  })
+}
+
+/** V4：代币先授权给 Permit2，再在 Permit2 里授权给仓位合约（额度不够或已过期时） */
+export async function permit2Approvals(ctx: Ctx, spender: string, items: ReadonlyArray<{ token: string; amount: bigint }>): Promise<LiquidityTx[]> {
+  const needed = items.filter((i) => i.amount > 0n)
+  if (!needed.length) {
+    return []
+  }
+  const erc20 = await approvals(
+    ctx,
+    needed.map((i) => ({ token: i.token, spender: PERMIT2_ADDRESS, amount: i.amount })),
+  )
+  const permits = (await ctx.provider.all(needed.map((i) => ctx.provider.contract(PERMIT2_ADDRESS, permit2Interface).allowance(ctx.owner, i.token, spender)))) as Array<{ 0: bigint; 1: bigint }>
+  const now = Math.floor(Date.now() / 1000)
+  const permit2 = needed.flatMap((item, k): LiquidityTx[] => {
+    const [amount, expiration] = [permits[k]?.[0] ?? 0n, Number(permits[k]?.[1] ?? 0n)]
+    // 额度够、并且在交易截止时间之后才过期：不用再授权
+    if (amount >= item.amount && expiration >= ctx.deadline) {
+      return []
+    }
+    // 过期重新授权时保留原来更大的额度（如之前授权过无限额度）
+    const value = ctx.options.approve === 'max' ? MAX_UINT160 : amount > item.amount ? amount : item.amount
+    return [
+      {
+        kind: 'permit2',
+        to: PERMIT2_ADDRESS,
+        data: permit2Interface.encodeFunctionData('approve', [item.token, spender, value, Math.max(now, ctx.deadline) + PERMIT2_EXPIRATION]),
+        value: '0',
+        token: item.token,
+        spender,
+        amount: value.toString(),
+      },
+    ]
+  })
+  return [...erc20, ...permit2]
+}
+
+/** 计划里的价格字段（token1 / token0，按精度换算） */
+export function priceFields(token0: LpToken, token1: LpToken, sqrtPriceX96: bigint | null, tickLower: number, tickUpper: number) {
+  if (token0.decimals === null || token1.decimals === null) {
+    return { price: null, priceLower: null, priceUpper: null }
+  }
+  return {
+    price: sqrtPriceX96 ? sqrtPriceToPrice(sqrtPriceX96, token0.decimals, token1.decimals) : null,
+    priceLower: tickToPrice(tickLower, token0.decimals, token1.decimals),
+    priceUpper: tickToPrice(tickUpper, token0.decimals, token1.decimals),
+  }
+}
+
+type PlanInput = Omit<LiquidityPlan, 'chainId' | 'owner' | 'recipient' | 'deadline' | 'amount0Formatted' | 'amount1Formatted' | 'fees0Formatted' | 'fees1Formatted' | 'pool'> & {
+  pool: string | null
+}
+
+/** 补上公共字段、格式化数量 */
+export function makePlan(ctx: Ctx, input: PlanInput): LiquidityPlan {
+  const { token0, token1 } = input
+  return {
+    ...input,
+    chainId: ctx.chainId,
+    pool: input.pool === null || input.version === 'v4' ? input.pool : out(ctx, input.pool),
+    owner: out(ctx, ctx.owner),
+    recipient: out(ctx, ctx.recipient),
+    amount0Formatted: fmt(BigInt(input.amount0), token0),
+    amount1Formatted: fmt(BigInt(input.amount1), token1),
+    fees0Formatted: fmt(BigInt(input.fees0), token0),
+    fees1Formatted: fmt(BigInt(input.fees1), token1),
+    deadline: ctx.deadline,
+  }
+}

package/src/liquidity/concentrated.ts

@@ -0,0 +1,121 @@
+import type { LpToken } from '../lp.js'
+import {
+  MAX_TICK,
+  MIN_TICK,
+  clampedTickAtSqrtRatio,
+  getLiquidityForAmount0,
+  getLiquidityForAmount1,
+  getLiquidityForAmounts,
+  getMintAmounts,
+  getSqrtRatioAtTick,
+  nearestUsableTick,
+  parseDecimal,
+  ratioToSqrtPriceX96,
+  sqrtPriceBounds,
+  toUint128,
+} from '../lpMath.js'
+import type { NewPositionParams } from './types.js'
+
+/**
+ * 价格（tokenB / tokenA，按精度换算）→ 池子的 sqrtPriceX96（token1 / token0）。aIs0：tokenA 是不是 token0
+ */
+export function sqrtPriceOf(price: string | number, aIs0: boolean, token0: LpToken, token1: LpToken, name: string): bigint {
+  if (token0.decimals === null || token1.decimals === null) {
+    throw new Error(`Cannot read token decimals to convert ${name}; pass ticks instead`)
+  }
+  const { num, den } = parseDecimal(price)
+  if (num === 0n) {
+    throw new RangeError(`${name} must be greater than 0`)
+  }
+  // tokenA 是 token1 时取倒数
+  return aIs0 ? ratioToSqrtPriceX96(num, den, token0.decimals, token1.decimals) : ratioToSqrtPriceX96(den, num, token0.decimals, token1.decimals)
+}
+
+/** 新建仓位的 tick 区间：fullRange / tickLower + tickUpper / priceLower + priceUpper 三选一 */
+export function resolveRange(params: NewPositionParams, aIs0: boolean, token0: LpToken, token1: LpToken, tickSpacing: number): [number, number] {
+  const byTicks = params.tickLower !== undefined || params.tickUpper !== undefined
+  const byPrices = params.priceLower !== undefined || params.priceUpper !== undefined
+  if (Number(!!params.fullRange) + Number(byTicks) + Number(byPrices) !== 1) {
+    throw new Error('Pass exactly one of fullRange, tickLower + tickUpper, or priceLower + priceUpper')
+  }
+  let lower: number
+  let upper: number
+  if (params.fullRange) {
+    lower = Math.ceil(MIN_TICK / tickSpacing) * tickSpacing
+    upper = Math.floor(MAX_TICK / tickSpacing) * tickSpacing
+  } else if (byTicks) {
+    if (params.tickLower === undefined || params.tickUpper === undefined) {
+      throw new Error('Pass both tickLower and tickUpper')
+    }
+    lower = params.tickLower
+    upper = params.tickUpper
+    for (const tick of [lower, upper]) {
+      if (!Number.isInteger(tick) || tick < MIN_TICK || tick > MAX_TICK || tick % tickSpacing !== 0) {
+        throw new RangeError(`tick ${tick} must be an integer multiple of tickSpacing ${tickSpacing} within [${MIN_TICK}, ${MAX_TICK}]`)
+      }
+    }
+  } else {
+    if (params.priceLower === undefined || params.priceUpper === undefined) {
+      throw new Error('Pass both priceLower and priceUpper')
+    }
+    // tokenA 是 token1 时价格取倒数，区间两端也随之对调；下面按大小排序
+    const ticks = [params.priceLower, params.priceUpper].map((price, i) => {
+      return nearestUsableTick(clampedTickAtSqrtRatio(sqrtPriceOf(price, aIs0, token0, token1, i ? 'priceUpper' : 'priceLower')), tickSpacing)
+    }) as [number, number]
+    ;[lower, upper] = ticks[0] <= ticks[1] ? ticks : [ticks[1], ticks[0]]
+  }
+  if (lower >= upper) {
+    throw new RangeError(`The price range is too narrow: tickLower ${lower} must be below tickUpper ${upper} (tickSpacing ${tickSpacing})`)
+  }
+  return [lower, upper]
+}
+
+/**
+ * 按输入的数量算添加的流动性：两边都给时取较少的一边；只给一边时另一边按当前价格算。
+ * 价格在区间外时只需要一种代币，给错了另一种会报错
+ */
+export function liquidityFor(sqrtPrice: bigint, tickLower: number, tickUpper: number, amount0: bigint | undefined, amount1: bigint | undefined, token0: LpToken, token1: LpToken): bigint {
+  const sqrtA = getSqrtRatioAtTick(tickLower)
+  const sqrtB = getSqrtRatioAtTick(tickUpper)
+  const name = (t: LpToken) => t.symbol ?? t.address
+  if (amount0 === undefined && amount1 === undefined) {
+    throw new Error('Pass the amount of at least one token')
+  }
+  // 价格在区间外时只需要一种代币：给的是另一种（或需要的那种是 0）时说明要给哪种
+  if (sqrtPrice >= sqrtB && !amount1) {
+    throw new Error(`The current price is above the range: the position takes only ${name(token1)} (token1); pass its amount instead`)
+  }
+  if (sqrtPrice <= sqrtA && !amount0) {
+    throw new Error(`The current price is below the range: the position takes only ${name(token0)} (token0); pass its amount instead`)
+  }
+  let liquidity: bigint
+  if (amount0 !== undefined && amount1 !== undefined) {
+    liquidity = getLiquidityForAmounts(sqrtPrice, sqrtA, sqrtB, amount0, amount1)
+  } else if (amount0 !== undefined) {
+    liquidity = getLiquidityForAmount0(sqrtPrice > sqrtA ? sqrtPrice : sqrtA, sqrtB, amount0)
+  } else {
+    liquidity = getLiquidityForAmount1(sqrtA, sqrtPrice < sqrtB ? sqrtPrice : sqrtB, amount1 as bigint)
+  }
+  if (liquidity === 0n) {
+    throw new Error('Amount too small: the liquidity rounds to 0')
+  }
+  return toUint128(liquidity)
+}
+
+/**
+ * V3：按传给仓位合约的数量（desired），价格在滑点范围内变动时至少会用掉多少（amountMin）。
+ * 合约按当时的价格重新算流动性：token0 在价格最高时用得最少，token1 在最低时；取三个价格下的最小值
+ */
+export function v3MinAmounts(sqrtPrice: bigint, tickLower: number, tickUpper: number, desired0: bigint, desired1: bigint, slippage: number): [bigint, bigint] {
+  const sqrtA = getSqrtRatioAtTick(tickLower)
+  const sqrtB = getSqrtRatioAtTick(tickUpper)
+  const [lower, upper] = sqrtPriceBounds(sqrtPrice, slippage)
+  let min0: bigint | null = null
+  let min1: bigint | null = null
+  for (const s of [lower, sqrtPrice, upper]) {
+    const [a0, a1] = getMintAmounts(s, sqrtA, sqrtB, getLiquidityForAmounts(s, sqrtA, sqrtB, desired0, desired1))
+    min0 = min0 === null || a0 < min0 ? a0 : min0
+    min1 = min1 === null || a1 < min1 ? a1 : min1
+  }
+  return [min0 as bigint, min1 as bigint]
+}

package/src/liquidity/index.ts

@@ -0,0 +1,171 @@
+import { Interface } from 'ethers'
+
+import type { Provider } from '../provider.js'
+import { batchCall, tronModule } from '../write/batch.js'
+import { WriteRpc } from '../write/rpc.js'
+import { resolveSigner, type SignerInput } from '../write/signer.js'
+import { ZERO_ADDRESS, createCtx, evm, positionVersion, protocolById } from './common.js'
+import type {
+  AddLiquidityParams,
+  CollectFeesParams,
+  LiquidityOptions,
+  LiquidityPlan,
+  LiquidityResult,
+  LiquiditySendOptions,
+  LiquidityTx,
+  LiquidityTxResult,
+  RemoveLiquidityParams,
+} from './types.js'
+import { v2Add, v2Remove } from './v2.js'
+import { v3Add, v3Remove } from './v3.js'
+import { v4Add, v4Remove } from './v4.js'
+
+/**
+ * 添加流动性的计划（不签名、不发送）：新建仓位，或往已有仓位追加。返回预计的数量和要按顺序发送的交易（授权在前）。
+ * 只做读取，也可以当作报价：输入一边的数量，看另一边要多少、能拿到多少流动性
+ *
+ * ```ts
+ * // 新建 V3 仓位：价格区间按 tokenB / tokenA，给一边的数量
+ * const plan = await buildAddLiquidity(multi, owner, { protocol: 'pancakeswap-v3', tokenA: WBNB, tokenB: USDT, fee: 500, priceLower: 550, priceUpper: 650, amountAFormatted: '1' })
+ * plan.amount1Formatted   // 需要的 USDT
+ * plan.transactions       // [approve…, add]，可以交给钱包逐笔发送
+ * // 往已有仓位追加（position 可以直接用 getLpPositions 的结果）
+ * await buildAddLiquidity(multi, owner, { position, amount0Formatted: '0.5' })
+ * ```
+ */
+export async function buildAddLiquidity(provider: Provider, owner: string, params: AddLiquidityParams, options: LiquidityOptions = {}): Promise<LiquidityPlan> {
+  const ctx = await createCtx(provider, owner, options)
+  if ('position' in params) {
+    const version = positionVersion(ctx, params.position)
+    return version === 'v2' ? v2Add(ctx, params) : version === 'v3' ? v3Add(ctx, params) : v4Add(ctx, params)
+  }
+  const protocol = protocolById(ctx, params.protocol)
+  const resolved = { ...params, protocol }
+  return protocol.version === 'v2' ? v2Add(ctx, resolved) : protocol.version === 'v3' ? v3Add(ctx, resolved) : v4Add(ctx, resolved)
+}
+
+/**
+ * 移除流动性的计划（不签名、不发送）：按比例或指定数量移除，V3 / V4 同时领取全部未领取的手续费。
+ *
+ * ```ts
+ * await buildRemoveLiquidity(multi, owner, { position, percent: 50 })
+ * await buildRemoveLiquidity(multi, owner, { position, burn: true })   // 全部移除并销毁 NFT
+ * ```
+ */
+export async function buildRemoveLiquidity(provider: Provider, owner: string, params: RemoveLiquidityParams, options: LiquidityOptions = {}): Promise<LiquidityPlan> {
+  const ctx = await createCtx(provider, owner, options)
+  const version = positionVersion(ctx, params.position)
+  return version === 'v2' ? v2Remove(ctx, params) : version === 'v3' ? v3Remove(ctx, params) : v4Remove(ctx, params)
+}
+
+/** 只领取 V3 / V4 仓位的手续费（不动流动性）的计划 */
+export async function buildCollectFees(provider: Provider, owner: string, params: CollectFeesParams, options: LiquidityOptions = {}): Promise<LiquidityPlan> {
+  const ctx = await createCtx(provider, owner, options)
+  const version = positionVersion(ctx, params.position)
+  if (version === 'v2') {
+    throw new Error('V2 has no separate fees: they are part of the LP tokens, remove liquidity to get them')
+  }
+  return version === 'v3' ? v3Remove(ctx, { position: params.position }, true) : v4Remove(ctx, { position: params.position }, true)
+}
+
+/**
+ * 添加流动性：构建计划（同 buildAddLiquidity）后用 from 签名发送，授权不够时先发授权交易。
+ * from 与 /write 的 batchCall 相同：私钥、ethers Signer、浏览器钱包（Tron 上也可以是 tronWeb / adapter）
+ *
+ * ```ts
+ * const { status, tokenId, plan } = await addLiquidity(multi, privateKey, { protocol: 'uniswap-v3', tokenA: NATIVE_TOKEN, tokenB: USDC, fee: 500, fullRange: true, amountAFormatted: '0.1' })
+ * ```
+ */
+export async function addLiquidity(provider: Provider, from: SignerInput, params: AddLiquidityParams, options: LiquiditySendOptions = {}): Promise<LiquidityResult> {
+  const plan = await buildAddLiquidity(provider, await signerAddress(provider, from), params, options)
+  if (options.checkBalance ?? true) {
+    await checkBalance(provider, plan)
+  }
+  return execute(provider, from, plan, options)
+}
+
+/** 移除流动性：构建计划（同 buildRemoveLiquidity）后用 from 签名发送 */
+export async function removeLiquidity(provider: Provider, from: SignerInput, params: RemoveLiquidityParams, options: LiquiditySendOptions = {}): Promise<LiquidityResult> {
+  const plan = await buildRemoveLiquidity(provider, await signerAddress(provider, from), params, options)
+  return execute(provider, from, plan, options)
+}
+
+/** 领取 V3 / V4 仓位的手续费 */
+export async function collectFees(provider: Provider, from: SignerInput, params: CollectFeesParams, options: LiquiditySendOptions = {}): Promise<LiquidityResult> {
+  const plan = await buildCollectFees(provider, await signerAddress(provider, from), params, options)
+  return execute(provider, from, plan, options)
+}
+
+/** 签名器的地址（Tron 上为 T 地址），不发交易 */
+async function signerAddress(provider: Provider, from: SignerInput): Promise<string> {
+  const tron = await tronModule(provider)
+  return tron ? tron.tronSignerAddress(from) : (await resolveSigner(from)).address
+}
+
+/** 添加前检查余额：代币按预计数量，主币按附带的 value（不含手续费） */
+async function checkBalance(provider: Provider, plan: LiquidityPlan): Promise<void> {
+  const needs: Array<[string, bigint]> = []
+  // V4 追加时先自动领取手续费、与存入相抵：只需要差额
+  const offset = (amount: string, fees: string) => {
+    const need = BigInt(amount) - (plan.version === 'v4' && plan.tokenId !== null ? BigInt(fees) : 0n)
+    return need > 0n ? need : 0n
+  }
+  if (plan.native !== 'token0') needs.push([plan.token0.address, offset(plan.amount0, plan.fees0)])
+  if (plan.native !== 'token1') needs.push([plan.token1.address, offset(plan.amount1, plan.fees1)])
+  if (BigInt(plan.value) > 0n) needs.push([provider.nativeTokens[0] ?? ZERO_ADDRESS, BigInt(plan.value)])
+  const list = needs.filter(([, amount]) => amount > 0n)
+  if (!list.length) {
+    return
+  }
+  const balances = await provider.balances(plan.owner, list.map(([token]) => token))
+  list.forEach(([token, amount], i) => {
+    const b = balances[i]
+    // 读不到余额的不拦（预估 gas 时也会失败）
+    if (b?.success && BigInt(b.balance) < amount) {
+      throw new Error(`Insufficient balance of ${token}: need ${amount}, have ${b.balance}`)
+    }
+  })
+}
+
+const transferTopic = new Interface(['event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)']).getEvent('Transfer')?.topicHash as string
+
+async function execute(provider: Provider, from: SignerInput, plan: LiquidityPlan, options: LiquiditySendOptions): Promise<LiquidityResult> {
+  const { transactions } = plan
+  const results = (
+    await batchCall(
+      provider,
+      transactions.map((tx) => ({ from, to: tx.to, data: tx.data, value: BigInt(tx.value) })),
+      {
+        ...options,
+        mode: 'tx',
+        // 授权失败时不发主交易
+        continueOnError: false,
+        onUpdate: options.onUpdate ? (r) => options.onUpdate?.({ ...r, kind: (transactions[r.index] as LiquidityTx).kind }) : undefined,
+      },
+    )
+  ).map((r, i): LiquidityTxResult => ({ ...r, kind: (transactions[i] as LiquidityTx).kind }))
+  const main = results[results.length - 1] as LiquidityTxResult
+  let tokenId: string | null = plan.tokenId
+  if (plan.action === 'add' && plan.tokenId === null && plan.version !== 'v2') {
+    tokenId = main.status === 'confirmed' && main.hash ? await mintedTokenId(provider, plan, main.hash) : null
+  }
+  return { plan, results, status: main.status, hash: main.hash, tokenId }
+}
+
+/** 新建仓位的 tokenId：主交易回执里仓位合约从零地址转出的 NFT（Tron 上不读，为 null） */
+async function mintedTokenId(provider: Provider, plan: LiquidityPlan, hash: string): Promise<string | null> {
+  try {
+    if (await tronModule(provider)) {
+      return null
+    }
+    const receipt = await (await WriteRpc.from(provider)).receipt(hash)
+    const pm = evm((plan.transactions[plan.transactions.length - 1] as { to: string }).to)
+    const log = receipt?.logs.find(
+      (l) => l.topics.length === 4 && l.topics[0] === transferTopic && BigInt(l.topics[1] as string) === 0n && evm(l.address) === pm,
+    )
+    return log ? BigInt(log.topics[3] as string).toString() : null
+  } catch {
+    return null // 读回执失败不影响结果（交易已确认）
+  }
+}
+