@w3lib/solana-batch-call 0.2.2 → 0.3.0

package/src/lpMath.ts

@@ -0,0 +1,205 @@
+/**
+ * 集中流动性（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)
+}

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/lp.ts

@@ -0,0 +1,62 @@
+/**
+ * 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,
+  orcaSqrtPriceAtTick,
+  raydiumSqrtPriceAtTick,
+  sqrtPriceToPrice,
+  tickToPrice,
+  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
+}
+

package/src/write/collect.ts

@@ -0,0 +1,286 @@
+import { getAssociatedTokenAddress, isAddress } from '../address.js'
+import type { SolanaClient } from '../client.js'
+import { formatUnits } from '../layout.js'
+import type { TokenBalance } from '../types.js'
+import { closeAccount, createAssociatedTokenAccountIdempotent, systemTransfer } from './instructions.js'
+import { emptyOutcome, priorityFeeFor, sendUnits, toWriteResult, transactionFee, type SendOptions, type TxOutcome, type Unit, type WriteResult } from './send.js'
+import { resolveSigner, type ResolvedSigner, type SignerInput } from './signer.js'
+import { transferInstructions } from './transfer.js'
+
+/** 扫空 SOL 的交易（一条 System 转账 + 两条计算预算指令）用的计算单元上限 */
+const SWEEP_COMPUTE_UNITS = 1_000
+
+export interface BatchCollectOptions extends SendOptions {
+  /**
+   * 要归集的代币 mint。包含原生 SOL（NATIVE_MINT）时，在代币归集确认后把剩余 SOL 全部转走：
+   * 传了 feePayer 时整个余额转走（手续费由 feePayer 付），否则扣掉这笔的手续费后转走，钱包余额归零
+   */
+  tokens: readonly string[]
+  /**
+   * 代币转完后关闭钱包的代币账户（ATA），租金（约 0.00204 SOL / 个）退回钱包本身；同时扫 SOL 时一并转走。默认 false。
+   * Token-2022 账户里有未提取的转账手续费等情况关不掉，只影响 close 那一项
+   */
+  closeAccounts?: boolean
+  /** 各代币的最小归集数量（最小单位），余额低于它的不归集：`{ [USDC]: 1_000_000n }`；对 SOL 同样有效 */
+  minAmount?: Readonly<Record<string, bigint | number | string>>
+  /** 每笔交易最多几个调用，默认不限（按交易大小） */
+  batchSize?: number
+}
+
+/** 单个钱包单个代币的归集结果；from 是钱包，to 是归集地址 */
+export interface CollectItemResult extends WriteResult {
+  to: string
+  token: string
+  native: boolean
+  /** 归集的数量（最小单位）；SOL 扫尾在发送前为 '0' */
+  amount: string
+  formatted: string | null
+  /** closeAccounts 时关闭代币账户的结果；没有关闭（未开启、SOL、没有归集）时为 null */
+  close: WriteResult | null
+}
+
+export interface CollectResult {
+  /** 按 wallets × tokens 顺序（第 i 个钱包第 j 个代币在 i × tokens.length + j） */
+  results: CollectItemResult[]
+}
+
+interface Item {
+  index: number
+  signer: ResolvedSigner
+  token: string
+  native: boolean
+  amount: bigint
+  decimals: number | null
+  tokenProgram: string | null
+  result: CollectItemResult
+}
+
+/**
+ * 归集：多个钱包的代币 / SOL 转到同一个地址。
+ *
+ * ```ts
+ * const { results } = await batchCollect(client, [key1, key2, key3], hotWallet, {
+ *   tokens: [USDC, NATIVE_MINT],   // 包含 SOL 表示代币归集完后扫空 SOL
+ *   feePayer: gasKey,              // 手续费都由 gasKey 付：子钱包不需要有 SOL，多个钱包的转账打包进同一笔交易
+ * })
+ * ```
+ *
+ * 流程：一次读出所有钱包的余额 → 归集地址没有该代币的 ATA 时随第一批转账创建 → 打包发送代币转账（可选关闭代币账户）
+ * →（包含 SOL 时）等代币归集确认，按最新余额扫空 SOL。
+ * 不传 feePayer 时每个钱包自己付手续费，没有 SOL 的钱包对应的项失败（Solana 上不需要先补 gas：传 feePayer 即可）
+ */
+export async function batchCollect(client: SolanaClient, wallets: readonly SignerInput[], to: string, options: BatchCollectOptions): Promise<CollectResult> {
+  if (!isAddress(to)) {
+    throw new Error(`Invalid collect address: ${to}`)
+  }
+  const cache = new Map()
+  const signers = await Promise.all(wallets.map((w) => resolveSigner(w, cache)))
+  const feePayer = options.feePayer === undefined ? null : await resolveSigner(options.feePayer, cache)
+  const tokens = options.tokens
+  const sweep = tokens.some((t) => client.isNativeMint(t))
+  const minAmount = new Map(Object.entries(options.minAmount ?? {}).map(([k, v]) => [k, BigInt(v)]))
+  const balances = await client.multiBalances(
+    signers.map((s) => ({ owner: s.address, mints: tokens })),
+    { signal: options.signal },
+  )
+
+  const items: Item[] = []
+  const seen = new Set<string>()
+  signers.forEach((signer, w) => {
+    const duplicate = seen.has(signer.address)
+    seen.add(signer.address)
+    tokens.forEach((token, t) => {
+      const balance = balances[w]?.[t] as TokenBalance
+      const native = client.isNativeMint(token)
+      const item: Item = {
+        index: w * tokens.length + t,
+        signer,
+        token,
+        native,
+        amount: native || !balance.success ? 0n : BigInt(balance.balance),
+        decimals: balance.success ? balance.decimals : null,
+        tokenProgram: balance.tokenProgram,
+        result: null as unknown as CollectItemResult,
+      }
+      const skip = !balance.success
+        ? `cannot read balance: ${balance.error ?? 'unknown error'}`
+        : signer.address === to
+          ? 'skipped: wallet is the collect address'
+          : duplicate
+            ? 'skipped: duplicate wallet'
+            : native && feePayer?.address === signer.address
+              ? 'skipped: wallet is the fee payer'
+              : !native && item.amount === 0n
+                ? 'skipped: zero balance'
+                : !native && item.amount < (minAmount.get(token) ?? 0n)
+                  ? 'skipped: below minAmount'
+                  : null
+      item.result = toCollectResult(item, to, emptyOutcome(skip ? (balance.success ? 'skipped' : 'failed') : 'skipped', skip), null)
+      items.push(item)
+    })
+  })
+  const results = items.map((i) => i.result)
+  const report = (item: Item, outcome: TxOutcome, close: WriteResult | null = item.result.close) => {
+    const hint =
+      !feePayer && outcome.status === 'failed' && /transaction fee|fee payer/.test(outcome.error ?? '') && !outcome.error?.includes('feePayer')
+        ? ' (pass feePayer to pay fees from another wallet)'
+        : ''
+    item.result = toCollectResult(item, to, { ...outcome, error: outcome.error && outcome.error + hint }, close)
+    results[item.index] = item.result
+    options.onUpdate?.(item.result)
+  }
+  const active = (item: Item) => item.result.error === null
+
+  // 归集地址的 ATA：没有的话随转账创建（创建指令是幂等的，同一代币的多笔转账都带上，只有第一笔真正创建）
+  const tokenItems = items.filter((i) => !i.native && active(i))
+  const targetAtas = new Map(tokenItems.map((i) => [i.token, getAssociatedTokenAddress(to, i.token, i.tokenProgram as string)]))
+  const missing = new Set<string>()
+  if (targetAtas.size) {
+    const keys = [...targetAtas.values()]
+    const accounts = await client.accounts(keys, { signal: options.signal })
+    keys.forEach((k, i) => !accounts[i] && missing.add(k))
+  }
+
+  // 不传 feePayer 时每个钱包自己付费：如果每笔转账都带创建指令，模拟时每个钱包都要付得起租金（实际只创建一次）。
+  // 先由第一个有这种代币的钱包单独创建，确认后再归集；创建失败时退回到每笔都带创建指令
+  if (!feePayer && missing.size && !options.dryRun) {
+    const setup: Unit[] = []
+    for (const [mint, ata] of targetAtas) {
+      if (!missing.has(ata)) continue
+      const first = tokenItems.find((i) => i.token === mint) as Item
+      setup.push({
+        instructions: [createAssociatedTokenAccountIdempotent(first.signer.address, ata, to, mint, first.tokenProgram as string)],
+        payer: first.signer,
+        signers: [],
+        continueOnError: true,
+        onUpdate: (outcome) => outcome.status === 'confirmed' && missing.delete(ata),
+      })
+    }
+    await sendUnits(client, setup, { ...options, wait: true }, { batchSize: 1 })
+  }
+
+  const units: Unit[] = []
+  /** 每个钱包最后一笔上链交易的 slot（扫 SOL 时按不早于它的状态读余额） */
+  let minSlot: number | undefined
+  const track = (outcome: TxOutcome) => {
+    if (outcome.slot !== null) minSlot = Math.max(minSlot ?? 0, outcome.slot)
+  }
+  for (const item of tokenItems) {
+    const payer = feePayer ?? item.signer
+    const signerList = payer.address === item.signer.address ? [] : [item.signer]
+    const target = targetAtas.get(item.token) as string
+    units.push({
+      instructions: transferInstructions(item.signer, payer, { ...item, to }, target, missing.has(target)),
+      payer,
+      signers: signerList,
+      continueOnError: true,
+      onUpdate: (outcome) => {
+        track(outcome)
+        report(item, outcome)
+      },
+    })
+    if (options.closeAccounts) {
+      const program = item.tokenProgram as string
+      const account = getAssociatedTokenAddress(item.signer.address, item.token, program)
+      units.push({
+        instructions: [closeAccount(account, item.signer.address, item.signer.address, program)],
+        payer,
+        signers: signerList,
+        continueOnError: true,
+        onUpdate: (outcome) => {
+          track(outcome)
+          report(item, outcomeOf(item.result), toWriteResult(item.index, item.signer.address, outcome))
+        },
+      })
+    }
+  }
+  // 要扫 SOL 时必须等代币归集确认（扫的是最新余额，关闭账户退回的租金也要算进去）
+  await sendUnits(client, units, sweep ? { ...options, wait: true } : options, { batchSize: options.batchSize })
+
+  if (!sweep) {
+    return { results }
+  }
+  // 代币没有全部归集成功的钱包不扫 SOL：留着付之后重新归集的手续费
+  items
+    .filter((i) => i.native && active(i))
+    .forEach((native) => {
+      // dryRun 时代币项是 simulated，也算成功
+      const done = (status: string) => status === 'confirmed' || status === 'skipped' || (options.dryRun && status === 'simulated')
+      const unfinished = items.find((i) => !i.native && i.signer.address === native.signer.address && !done(i.result.status))
+      if (unfinished) {
+        report(native, emptyOutcome('skipped', `skipped: collecting ${unfinished.token} did not succeed (${unfinished.result.status})`))
+      }
+    })
+  const sweepItems = items.filter((i) => i.native && active(i))
+  if (!sweepItems.length || options.signal?.aborted) {
+    return { results }
+  }
+  if (options.dryRun) {
+    // 代币归集没有真的执行，扫 SOL 的金额要等归集之后才知道：只标记 simulated，不做模拟
+    sweepItems.forEach((i) => report(i, emptyOutcome('simulated')))
+    return { results }
+  }
+  let lamports: Awaited<ReturnType<SolanaClient['solBalances']>>
+  try {
+    lamports = await client.solBalances(
+      sweepItems.map((i) => i.signer.address),
+      { minContextSlot: minSlot, signal: options.signal },
+    )
+  } catch (err) {
+    // 代币归集已经发出：不能整体抛错（调用方会拿不到这些结果），扫 SOL 的项标记失败
+    sweepItems.forEach((i) => report(i, emptyOutcome('failed', `cannot read SOL balance: ${err instanceof Error ? err.message : String(err)}`)))
+    return { results }
+  }
+  const prepared = await Promise.all(
+    sweepItems.map(async (item, k): Promise<Unit | null> => {
+      const balance = BigInt(lamports[k]?.balance ?? '0')
+      let amount = balance
+      let fixed: Unit['fixed']
+      if (!feePayer) {
+        // 自己付手续费：单独一笔、手续费事先算好，转走剩下的全部（余额归零，不受租金下限限制）
+        const price = await priorityFeeFor(client, options, [item.signer.address, to])
+        fixed = { computeUnits: SWEEP_COMPUTE_UNITS, price }
+        amount = balance - transactionFee(1, SWEEP_COMPUTE_UNITS, price)
+      }
+      const min = minAmount.get(item.token) ?? 0n
+      if (amount <= 0n || amount < min) {
+        report(item, emptyOutcome('skipped', amount <= 0n ? 'skipped: SOL balance does not cover the fee' : 'skipped: below minAmount'))
+        return null
+      }
+      item.amount = amount
+      const payer = feePayer ?? item.signer
+      return {
+        instructions: [systemTransfer(item.signer.address, to, amount)],
+        payer,
+        signers: payer.address === item.signer.address ? [] : [item.signer],
+        fixed,
+        continueOnError: true,
+        onUpdate: (outcome) => report(item, outcome),
+      }
+    }),
+  )
+  await sendUnits(
+    client,
+    prepared.filter((u): u is Unit => u !== null),
+    options,
+    { batchSize: options.batchSize },
+  )
+  return { results }
+}
+
+/** 结果转回交易结果（更新 close 字段时保留转账本身的状态） */
+function outcomeOf(r: WriteResult): TxOutcome {
+  return { status: r.status, signature: r.signature, slot: r.slot, fee: r.fee === null ? null : BigInt(r.fee), computeUnits: r.computeUnits, error: r.error }
+}
+
+function toCollectResult(item: Item, to: string, outcome: TxOutcome, close: WriteResult | null): CollectItemResult {
+  return {
+    ...toWriteResult(item.index, item.signer.address, outcome),
+    to,
+    token: item.token,
+    native: item.native,
+    amount: item.amount.toString(),
+    formatted: item.decimals === null ? null : formatUnits(item.amount, item.decimals),
+    close,
+  }
+}