@w3lib/evm-batch-call 0.5.0 → 0.7.0

package/src/fees.ts

@@ -0,0 +1,201 @@
+/**
+ * 手续费估算（子路径 `@w3lib/evm-batch-call/fees`）：EIP-1559 的 baseFee 和三档优先费（按最近区块的 eth_feeHistory），
+ * 一笔交易的手续费（含 OP Stack / Scroll 的 L1 数据费）；Tron 按能量 / 带宽和账户剩余的资源算要烧的 TRX
+ */
+import type { BigNumberish } from 'ethers'
+
+import { getNativeCurrency } from './chains.js'
+import { formatUnits } from './erc20.js'
+import type { Provider } from './provider.js'
+import { isTronChain } from './tron.js'
+
+export type FeeLevel = 'slow' | 'normal' | 'fast'
+
+/** 一档费用（wei 的十进制字符串）：EIP-1559 链是 maxFeePerGas / maxPriorityFeePerGas，legacy 链是 gasPrice */
+export type FeeLevelEstimate = { maxFeePerGas: string; maxPriorityFeePerGas: string } | { gasPrice: string }
+
+export interface FeeEstimate {
+  type: 'eip1559' | 'legacy'
+  /** 下一个区块的 baseFee（wei）；legacy 链为 null */
+  baseFee: string | null
+  slow: FeeLevelEstimate
+  normal: FeeLevelEstimate
+  fast: FeeLevelEstimate
+}
+
+export interface EstimateFeesOptions {
+  /** 看最近多少个区块，默认 20 */
+  blocks?: number
+  /** 三档优先费取各区块交易优先费的百分位，默认 [10, 50, 90] */
+  percentiles?: readonly [number, number, number]
+  /** maxFeePerGas = baseFee × baseFeeMultiplier + 优先费，默认 2（baseFee 连涨几个区块也够） */
+  baseFeeMultiplier?: number
+}
+
+interface FeeHistory {
+  baseFeePerGas?: string[]
+  reward?: string[][]
+}
+
+/** 节点的 JSON-RPC send（ethers 的 JsonRpcProvider / BrowserProvider） */
+type Sender = { send(method: string, params: unknown[]): Promise<unknown> }
+
+async function send<T>(provider: Provider, method: string, params: unknown[]): Promise<T> {
+  const { runOnNodes } = await import('./write/rpc.js')
+  return runOnNodes(provider.rpc, method, async (node) => {
+    if (typeof (node as Partial<Sender>).send !== 'function') throw new Error(`${method} is not supported by this node; pass an RPC URL or an ethers Provider`)
+    return (await (node as unknown as Sender).send(method, params)) as T
+  })
+}
+
+const median = (values: bigint[]): bigint => {
+  if (!values.length) return 0n
+  const sorted = [...values].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+  return sorted[Math.floor(sorted.length / 2)] as bigint
+}
+
+/**
+ * 当前的手续费建议（EVM 链）：baseFee 取下一个区块的，三档优先费是最近区块里交易优先费的百分位的中位数；
+ * 节点不支持 eth_feeHistory 或链上没有 baseFee 时按 eth_gasPrice（三档为 1、1、1.2 倍）。Tron 用 estimateCost
+ *
+ * ```ts
+ * const fees = await estimateFees(provider)
+ * // { type: 'eip1559', baseFee: '1200000000', slow: { maxFeePerGas, maxPriorityFeePerGas }, normal: {…}, fast: {…} }
+ * ```
+ */
+export async function estimateFees(provider: Provider, options: EstimateFeesOptions = {}): Promise<FeeEstimate> {
+  if (isTronChain(await provider.getChainId())) throw new Error('estimateFees is for EVM chains; use estimateCost on Tron')
+  const blocks = Math.max(1, Math.min(1024, Math.floor(options.blocks ?? 20)))
+  const percentiles = options.percentiles ?? [10, 50, 90]
+  if (!percentiles.every((p, i) => p >= 0 && p <= 100 && (i === 0 || p >= (percentiles[i - 1] as number)))) throw new RangeError('percentiles must be ascending numbers in [0, 100]')
+  const multiplier = options.baseFeeMultiplier ?? 2
+  let history: FeeHistory | null = null
+  try {
+    history = await send<FeeHistory>(provider, 'eth_feeHistory', [`0x${blocks.toString(16)}`, 'latest', [...percentiles]])
+  } catch (err) {
+    // 只有节点 / 链不支持 feeHistory 时才按 gasPrice；网络等其他错误照常抛出（不要在 EIP-1559 链上悄悄退回 legacy）
+    if (!/not (supported|available|found)|unsupported|does not exist|unknown method|-32601|method.*not/i.test(err instanceof Error ? err.message : String(err))) throw err
+    history = null
+  }
+  const baseFees = history?.baseFeePerGas ?? []
+  const next = baseFees.length ? BigInt(baseFees[baseFees.length - 1] as string) : 0n
+  if (!history || !baseFees.length || next === 0n) {
+    const gasPrice = BigInt(await send<string>(provider, 'eth_gasPrice', []))
+    const level = (n: bigint, d: bigint) => ({ gasPrice: ((gasPrice * n) / d).toString() })
+    return { type: 'legacy', baseFee: null, slow: level(1n, 1n), normal: level(1n, 1n), fast: level(6n, 5n) }
+  }
+  const rewards = history.reward ?? []
+  // 每档：各区块这个百分位的优先费取中位数（空区块的 0 不算）
+  const tip = (k: number) => median(rewards.map((r) => BigInt(r[k] ?? '0')).filter((v) => v > 0n))
+  const base = (next * BigInt(Math.round(multiplier * 1000))) / 1000n
+  const level = (priority: bigint) => ({ maxFeePerGas: (base + priority).toString(), maxPriorityFeePerGas: priority.toString() })
+  const [slow, normal, fast] = [tip(0), tip(1), tip(2)]
+  // 优先费不递减（区块很空时三档可能相同）
+  return { type: 'eip1559', baseFee: next.toString(), slow: level(slow), normal: level(normal > slow ? normal : slow), fast: level(fast > normal ? fast : normal > slow ? normal : slow) }
+}
+
+export interface CostCall {
+  /** 发送者（预估 gas、Tron 上按它剩余的资源算） */
+  from: string
+  to: string
+  data?: string
+  value?: BigNumberish
+}
+
+export interface EvmCostEstimate {
+  type: 'evm'
+  gasLimit: string
+  /** 这一档的每 gas 价格：EIP-1559 是 baseFee + 优先费（预计实际付的），legacy 是 gasPrice */
+  gasPrice: string
+  /** gasLimit × gasPrice（wei） */
+  fee: string
+  /** 最多付多少：gasLimit × maxFeePerGas（legacy 同 fee） */
+  maxFee: string
+  /** OP Stack / Scroll 的 L1 数据费（wei，含 25% 余量），其他链为 0 */
+  l1Fee: string
+  /** fee + l1Fee（wei）和按主币精度换算的值 */
+  total: string
+  totalFormatted: string
+  symbol: string | null
+}
+
+export interface TronCost {
+  type: 'tron'
+  energy: number
+  bandwidth: number
+  /** 剩余能量 / 带宽不够时要烧的 TRX（sun） */
+  energyBurn: string
+  bandwidthBurn: string
+  /** 转 TRX 给没激活的地址（激活费算在 bandwidthBurn 里） */
+  activates: boolean
+  energyPrice: string
+  bandwidthPrice: string
+  /** energyBurn + bandwidthBurn（sun）和按 TRX 换算的值 */
+  total: string
+  totalFormatted: string
+  symbol: 'TRX'
+}
+
+export type CostEstimate = EvmCostEstimate | TronCost
+
+export interface EstimateCostOptions extends EstimateFeesOptions {
+  /** 用哪一档，默认 'normal' */
+  level?: FeeLevel
+  /** 已经查好的费用建议（多笔交易共用，不再查一次） */
+  fees?: FeeEstimate
+}
+
+/**
+ * 估算一笔交易的手续费：EVM 预估 gas × 这一档的价格（+ L1 数据费）；Tron 模拟能量，按发送者剩余的资源算要烧的 TRX。
+ * 预估 gas 会执行一遍交易，revert 时抛出
+ *
+ * ```ts
+ * await estimateCost(provider, { from: user, to: USDT, data })   // { type: 'evm', gasLimit, fee, total, totalFormatted: '0.00042', symbol: 'BNB', … }
+ * await estimateCost(tronProvider, { from, to: USDT, data })     // { type: 'tron', energy: 64285, energyBurn: '6750000', totalFormatted: '7.0', … }
+ * ```
+ */
+export async function estimateCost(provider: Provider, call: CostCall, options: EstimateCostOptions = {}): Promise<CostEstimate> {
+  const chainId = await provider.getChainId()
+  const value = BigInt(call.value ?? 0)
+  if (isTronChain(chainId)) {
+    const { tronEstimateCost } = await import('./write/tron.js')
+    const c = await tronEstimateCost(provider, { from: call.from, to: call.to, ...(call.data ? { data: call.data } : {}), value })
+    const total = c.energyBurn + c.bandwidthBurn
+    return {
+      type: 'tron',
+      energy: c.energy,
+      bandwidth: c.bandwidth,
+      energyBurn: c.energyBurn.toString(),
+      bandwidthBurn: c.bandwidthBurn.toString(),
+      activates: c.activates,
+      energyPrice: c.energyPrice.toString(),
+      bandwidthPrice: c.bandwidthPrice.toString(),
+      total: total.toString(),
+      totalFormatted: formatUnits(total, 6),
+      symbol: 'TRX',
+    }
+  }
+  const { WriteRpc, l1Fee } = await import('./write/rpc.js')
+  const rpc = await WriteRpc.from(provider)
+  const tx = { from: call.from, to: call.to, data: call.data ?? '0x', value }
+  const [gasLimit, fees] = await Promise.all([rpc.estimateGas(tx), options.fees ? Promise.resolve(options.fees) : estimateFees(provider, options)])
+  const level = fees[options.level ?? 'normal']
+  const perGas = 'gasPrice' in level ? BigInt(level.gasPrice) : BigInt(fees.baseFee ?? '0') + BigInt(level.maxPriorityFeePerGas)
+  const maxPerGas = 'gasPrice' in level ? perGas : BigInt(level.maxFeePerGas)
+  const feeFields = 'gasPrice' in level ? { type: 0, gasPrice: perGas } : { type: 2, maxFeePerGas: maxPerGas, maxPriorityFeePerGas: BigInt(level.maxPriorityFeePerGas) }
+  const l1 = await l1Fee(rpc, { ...tx, from: undefined, gasLimit, ...feeFields })
+  const fee = gasLimit * perGas
+  const total = fee + l1
+  const native = getNativeCurrency(chainId)
+  return {
+    type: 'evm',
+    gasLimit: gasLimit.toString(),
+    gasPrice: perGas.toString(),
+    fee: fee.toString(),
+    maxFee: (gasLimit * maxPerGas).toString(),
+    l1Fee: l1.toString(),
+    total: total.toString(),
+    totalFormatted: formatUnits(total, native?.decimals ?? 18),
+    symbol: native?.symbol ?? null,
+  }
+}

package/src/http.ts

@@ -0,0 +1,34 @@
+/** HTTP 请求（代币列表、价格服务）：超时、状态码检查 */
+
+const REQUEST_TIMEOUT = 20_000
+
+export class HttpStatusError extends Error {
+  constructor(
+    readonly status: number,
+    target: string,
+  ) {
+    super(`HTTP ${status} from ${target}`)
+    this.name = 'HttpStatusError'
+  }
+}
+
+/**
+ * @param secret 请求里带的 Key：出错时错误信息只写域名，不写完整地址，避免 Key 出现在日志里
+ */
+export function fetchJson<T>(fetchFn: typeof fetch, url: string, init?: RequestInit, secret?: string): Promise<T> {
+  return fetchFn(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT) }).then(async (res) => {
+    if (!res.ok) {
+      throw new HttpStatusError(res.status, secret ? safeHost(url) : url)
+    }
+    return (await res.json()) as T
+  })
+}
+
+function safeHost(url: string): string {
+  try {
+    return new URL(url).host
+  } catch {
+    return 'request'
+  }
+}
+

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]
+}