@w3lib/evm-batch-call 0.4.1 → 0.5.0

package/src/write/batch.ts

@@ -0,0 +1,302 @@
+import { Interface, ZeroAddress, getAddress, getBigInt, hexlify, type Authorization, type BigNumberish } from 'ethers'
+
+import { encodeCall, type Call } from '../call.js'
+import { decodeRevertReason } from '../errors.js'
+import type { Provider } from '../provider.js'
+import { isTronChain } from '../tron.js'
+import { WriteRpc } from './rpc.js'
+import { emptyOutcome, sendJobs, toWriteResult, type SendOptions, type TronSendOptions, type TxJob, type TxOutcome, type WriteResult } from './send.js'
+import { resolveSigner, type ResolvedSigner, type SignerInput } from './signer.js'
+
+/**
+ * EIP-7702 批量执行合约：eth-infinitism 的 Simple7702Account（account-abstraction v0.8），各主流链上地址相同。
+ * executeBatch 只允许账户自己（或 EntryPoint）调用，委托后别人无法通过它动用钱包里的资产
+ */
+export const SIMPLE_7702_ACCOUNT = '0x4Cd241E8d1510e30b2076397afc7508Ae59C66c9'
+
+const accountInterface = new Interface([
+  'function executeBatch((address target, uint256 value, bytes data)[] calls)',
+  'error ExecuteError(uint256 index, bytes reason)',
+])
+
+/** 7702 委托后账户上的代码：0xef0100 + 委托合约地址 */
+const DELEGATION_PREFIX = '0xef0100'
+
+/** 一个写调用：目标地址 + calldata，或 Contract 生成的 Call */
+export interface WriteCall {
+  /** 发送的钱包：私钥或 ethers Signer */
+  from: SignerInput
+  /** 目标地址（与 data 一起用；不传 call 时必填） */
+  to?: string
+  /** calldata，默认 '0x'（普通转账） */
+  data?: string
+  /** 附带的主币（wei） */
+  value?: BigNumberish
+  /** 或者传 Contract 生成的 Call：`new Contract(token, ERC20_ABI).transfer(to, amount)`；`{ value }` overrides 作为 value */
+  call?: Call
+  /** 指定 gasLimit 时不预估（7702 模式下忽略，整笔交易统一预估） */
+  gasLimit?: bigint
+}
+
+export type BatchCallMode = 'tx' | '7702'
+
+export interface BatchCallOptions extends SendOptions, TronSendOptions {
+  /**
+   * - 'tx'（默认）：每个调用一笔交易，所有链都支持
+   * - '7702'：钱包通过 EIP-7702 委托给批量执行合约，同一钱包的调用合成一笔交易（按 batchSize 拆分），一笔里的调用要么全部成功要么全部失败。
+   *   需要链支持 EIP-7702，钱包需要能本地签名（私钥 / ethers Wallet）。委托会一直保留，可用 revokeDelegation 撤销
+   */
+  mode?: BatchCallMode
+  /**
+   * 某个调用发送前失败（预估 revert、节点拒绝等）后，同一钱包后面的调用是否继续。默认 false（后面的标记为 skipped）。
+   * 交易不等上一笔确认就连续发出，所以已经发出、之后在链上 revert 的交易拦不住后面已发出的交易
+   */
+  continueOnError?: boolean
+  /** 7702：委托的合约，默认 SIMPLE_7702_ACCOUNT */
+  delegate?: string
+  /** 7702：每笔交易最多打包的调用数，默认 50 */
+  batchSize?: number
+  /** 7702：钱包已委托给其他合约时改为委托给 delegate。默认 false（报错，不动已有的委托） */
+  redelegate?: boolean
+}
+
+/** 归一化后的调用 */
+export interface NormalizedCall {
+  signer: ResolvedSigner
+  to: string
+  data: string
+  value: bigint
+  gasLimit?: bigint
+}
+
+export async function normalizeCalls(calls: readonly WriteCall[]): Promise<NormalizedCall[]> {
+  const cache = new Map()
+  return Promise.all(
+    calls.map(async (item, i) => {
+      const signer = await resolveSigner(item.from, cache)
+      if (item.call) {
+        const request = encodeCall(item.call, false)
+        const value = item.value ?? item.call.overrides?.value ?? 0n
+        return { signer, to: request.target, data: request.callData, value: getBigInt(value), gasLimit: item.gasLimit }
+      }
+      if (!item.to) {
+        throw new Error(`calls[${i}]: either to or call is required`)
+      }
+      return { signer, to: getAddress(item.to), data: item.data ? hexlify(item.data) : '0x', value: getBigInt(item.value ?? 0n), gasLimit: item.gasLimit }
+    }),
+  )
+}
+
+/**
+ * 批量调用合约（写操作）。结果与 calls 一一对应。
+ *
+ * ```ts
+ * const usdt = new Contract(USDT, ERC20_ABI)
+ * await batchCall(multi, [
+ *   { from: key1, call: usdt.approve(router, amount) },
+ *   { from: key1, to: router, data: swapData },             // 依赖上一笔：预估失败时先等 approve 确认再预估
+ *   { from: key2, to: someone, value: 10n ** 16n },         // 不同钱包并发发送
+ * ])
+ * // [{ index: 0, from, to, status: 'confirmed', hash: '0x…', nonce: 7, gasUsed: '46109', fee: '…', … }, …]
+ * ```
+ *
+ * - 'tx' 模式：同一钱包按 nonce 顺序连续发出（不等上一笔确认），不同钱包并发（concurrency）
+ * - 依赖前一笔结果的调用：预估失败且同一钱包还有未确认的交易时，先等它们确认再预估一次
+ * - 结果的 status 见 WriteStatus；未上链的失败（预估 revert 等）不花手续费
+ */
+export async function batchCall(provider: Provider, calls: readonly WriteCall[], options: BatchCallOptions = {}): Promise<WriteResult[]> {
+  const tron = await tronModule(provider)
+  if (tron) {
+    return tron.tronBatchCall(provider, calls, options)
+  }
+  const rpc = await WriteRpc.from(provider)
+  const normalized = await normalizeCalls(calls)
+  return (options.mode ?? 'tx') === '7702' ? send7702(rpc, normalized, options) : sendEach(rpc, normalized, options)
+}
+
+/** Tron 链上用 Tron 的实现（按需加载：只用 EVM 时打包不会带上） */
+export async function tronModule(provider: Provider): Promise<typeof import('./tron.js') | null> {
+  return isTronChain(await provider.getChainId()) ? import('./tron.js') : null
+}
+
+/** 每个调用一笔交易 */
+export async function sendEach(rpc: WriteRpc, calls: readonly NormalizedCall[], options: BatchCallOptions): Promise<WriteResult[]> {
+  const results: WriteResult[] = calls.map((c, i) => toWriteResult(i, c.signer.address, c.to, emptyOutcome('skipped')))
+  const jobs: TxJob[] = calls.map((c, i) => ({
+    signer: c.signer,
+    gasLimit: c.gasLimit,
+    continueOnError: options.continueOnError,
+    build: async () => ({ to: c.to, data: c.data, value: c.value }),
+    onUpdate: (outcome) => {
+      results[i] = toWriteResult(i, c.signer.address, c.to, outcome)
+      options.onUpdate?.(results[i] as WriteResult)
+    },
+  }))
+  const outcomes = await sendJobs(rpc, jobs, options)
+  return outcomes.map((outcome, i) => toWriteResult(i, (calls[i] as NormalizedCall).signer.address, (calls[i] as NormalizedCall).to, outcome))
+}
+
+/** 钱包当前的委托状态 */
+async function delegationOf(rpc: WriteRpc, address: string): Promise<{ delegated: boolean; to: string | null }> {
+  const code = (await rpc.code(address)).toLowerCase()
+  if (code === '0x' || code === '') {
+    return { delegated: false, to: null }
+  }
+  if (code.startsWith(DELEGATION_PREFIX) && code.length === 2 + 46) {
+    return { delegated: true, to: getAddress(`0x${code.slice(8)}`) }
+  }
+  throw new Error(`${address} is a contract, not an EOA`)
+}
+
+/** 7702 授权：发送者自己就是授权人时，授权的 nonce 要用交易 nonce + 1（交易先把 nonce 加一，再处理授权） */
+async function authorize(rpc: WriteRpc, signer: ResolvedSigner, delegate: string, txNonce: number): Promise<Authorization> {
+  if (!signer.local || typeof signer.signer.authorize !== 'function') {
+    throw new Error("mode '7702' requires a signer that can sign EIP-7702 authorizations locally (a private key or an ethers Wallet)")
+  }
+  return signer.signer.authorize({ address: delegate, nonce: txNonce + 1, chainId: rpc.chainId })
+}
+
+/** 7702：同一钱包的调用合成一笔发给自己的 executeBatch 交易 */
+export async function send7702(rpc: WriteRpc, calls: readonly NormalizedCall[], options: BatchCallOptions): Promise<WriteResult[]> {
+  const delegate = getAddress(options.delegate ?? SIMPLE_7702_ACCOUNT)
+  const batchSize = Math.max(1, options.batchSize ?? 50)
+  const results: WriteResult[] = calls.map((c, i) => toWriteResult(i, c.signer.address, c.to, emptyOutcome('skipped')))
+  const report = (i: number, outcome: TxOutcome) => {
+    const c = calls[i] as NormalizedCall
+    results[i] = toWriteResult(i, c.signer.address, c.to, outcome)
+    options.onUpdate?.(results[i] as WriteResult)
+  }
+
+  // 按钱包分组、拆成每 batchSize 个一笔
+  const byWallet = new Map<string, number[]>()
+  calls.forEach((c, i) => {
+    const key = c.signer.address.toLowerCase()
+    byWallet.set(key, [...(byWallet.get(key) ?? []), i])
+  })
+  const chunks: number[][] = []
+  for (const indexes of byWallet.values()) {
+    for (let start = 0; start < indexes.length; start += batchSize) {
+      chunks.push(indexes.slice(start, start + batchSize))
+    }
+  }
+
+  // 委托合约必须有代码：EIP-7702 委托给没有代码的地址时调用直接“成功”、什么都不执行，结果会全部报 confirmed
+  let deployed: Promise<boolean> | null = null
+  const assertDeployed = async () => {
+    deployed ??= rpc.code(delegate).then((code) => Boolean(code && code !== '0x'))
+    if (!(await deployed)) {
+      throw new Error(`The delegate contract ${delegate} is not deployed on chain ${rpc.chainId}; pass delegate to use another one`)
+    }
+  }
+
+  // 每笔交易发送前查一次委托状态（同一钱包上一笔带授权时，sendJobs 会先等它确认，这时已经委托好了，不必再带授权）
+  const checkDelegation = async (signer: ResolvedSigner): Promise<boolean> => {
+    const { delegated, to } = await delegationOf(rpc, signer.address)
+    if (!delegated) {
+      return true
+    }
+    if (to === delegate) {
+      return false
+    }
+    if (!options.redelegate) {
+      throw new Error(`${signer.address} is already delegated to ${to}; pass redelegate: true to replace it`)
+    }
+    return true
+  }
+
+  const jobs: TxJob[] = chunks.map((chunk) => {
+    const signer = (calls[chunk[0] as number] as NormalizedCall).signer
+    const data = accountInterface.encodeFunctionData('executeBatch', [
+      chunk.map((i) => {
+        const c = calls[i] as NormalizedCall
+        return [c.to, c.value, c.data]
+      }),
+    ])
+    return {
+      signer,
+      continueOnError: options.continueOnError,
+      build: async (nonce) => {
+        if (!signer.local || nonce === null) {
+          throw new Error("mode '7702' requires a signer that can sign locally (a private key or an ethers Wallet)")
+        }
+        await assertDeployed()
+        let auth: Authorization[] | undefined
+        if (await checkDelegation(signer)) {
+          // 预估 gas 按 latest 状态执行：钱包还有未确认的交易时，授权 nonce（按 pending 算）在预估里对不上、授权被跳过，
+          // 预估出来的 gas 不含批量执行，上链后执行失败、手续费白付。要求先等这些交易确认
+          if ((await rpc.latestNonce(signer.address)) !== nonce) {
+            throw new Error('The wallet has unconfirmed transactions; EIP-7702 delegation needs them to be confirmed first')
+          }
+          auth = [await authorize(rpc, signer, delegate, nonce)]
+        }
+        return { to: signer.address, data, value: 0n, authorizationList: auth }
+      },
+      onUpdate: (outcome) => {
+        if (outcome.status === 'failed' && outcome.revertData) {
+          // 预估时 revert：找出是第几个调用失败，其他调用标记为 skipped（整笔没有发出）
+          const failed = failedIndex(outcome.revertData, chunk.length)
+          if (failed) {
+            chunk.forEach((i, k) =>
+              report(i, k === failed.index ? { ...outcome, error: failed.reason } : { ...outcome, status: 'skipped', error: 'skipped: another call in the same batch failed' }),
+            )
+            return
+          }
+        }
+        chunk.forEach((i) => report(i, outcome))
+      },
+    }
+  })
+  await sendJobs(rpc, jobs, options)
+  return results
+}
+
+/** 解析 executeBatch 的 ExecuteError(index, error)；只有一个调用时合约直接透传 revert 数据 */
+function failedIndex(data: string, size: number): { index: number; reason: string } | null {
+  if (size === 1) {
+    const reason = decodeRevertReason(data)
+    return { index: 0, reason: reason ? `execution reverted: ${reason}` : 'execution reverted' }
+  }
+  try {
+    const parsed = accountInterface.parseError(data)
+    if (parsed?.name !== 'ExecuteError') {
+      return null
+    }
+    const index = Number(parsed.args[0])
+    const reason = decodeRevertReason(String(parsed.args[1]))
+    return index < size ? { index, reason: reason ? `execution reverted: ${reason}` : 'execution reverted' } : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 撤销钱包的 EIP-7702 委托（授权给零地址，账户恢复成普通 EOA）。没有委托时直接返回 null，不发交易。
+ *
+ * ```ts
+ * await revokeDelegation(multi, privateKey)
+ * ```
+ */
+export async function revokeDelegation(provider: Provider, from: SignerInput, options: SendOptions = {}): Promise<WriteResult | null> {
+  const rpc = await WriteRpc.from(provider) // Tron 没有 EIP-7702：这里会报不支持
+  const signer = await resolveSigner(from)
+  if (!(await delegationOf(rpc, signer.address)).delegated) {
+    return null
+  }
+  const [outcome] = await sendJobs(
+    rpc,
+    [
+      {
+        signer,
+        build: async (nonce) => {
+          if (nonce === null) {
+            throw new Error('revokeDelegation requires a signer that can sign locally (a private key or an ethers Wallet)')
+          }
+          return { to: signer.address, data: '0x', value: 0n, authorizationList: [await authorize(rpc, signer, ZeroAddress, nonce)] }
+        },
+        onUpdate: (o) => options.onUpdate?.(toWriteResult(0, signer.address, signer.address, o)),
+      },
+    ],
+    options,
+  )
+  return toWriteResult(0, signer.address, signer.address, outcome as TxOutcome)
+}

package/src/write/collect.ts

@@ -0,0 +1,312 @@
+import { Interface, getAddress, getBigInt, type BigNumberish } from 'ethers'
+
+import { ERC20_ABI, NATIVE_TOKEN, formatUnits, type TokenBalance } from '../erc20.js'
+import type { Provider } from '../provider.js'
+import { isExecutionError } from '../errors.js'
+import { WriteRpc, failureText, l1Fee } from './rpc.js'
+import { FeeSource, applyGasMultiplier, emptyOutcome, mapPool, sendJobs, toWriteResult, type SendOptions, type TronSendOptions, type TxFees, type TxJob, type TxOutcome, type WriteResult } from './send.js'
+import { resolveSigner, type ResolvedSigner, type SignerInput } from './signer.js'
+import { tronModule } from './batch.js'
+import { batchTransfer, type TransferResult } from './transfer.js'
+
+const erc20Interface = new Interface(ERC20_ABI as unknown as string[])
+
+/** 预估代币转账 gas 失败（有的节点对没有主币的地址预估时报余额不足）时用的 gasLimit */
+const FALLBACK_TOKEN_GAS = 120_000n
+
+export interface BatchCollectOptions extends SendOptions, TronSendOptions {
+  /**
+   * 要归集的代币。包含主币（NATIVE_TOKEN）时，在代币归集确认后把剩余主币扣掉手续费全部转走
+   * （OP Stack / Scroll 链上同时预留 L1 数据费；EIP-1559 链上按 maxFeePerGas 预留，实际手续费更低，会留下少量零头）
+   */
+  tokens: readonly string[]
+  /**
+   * 补 gas 的钱包：子钱包主币不够付归集手续费时，先从它转入刚好够用的主币（按 gasLimit × maxFeePerGas 计算，已含余量），确认后再归集。
+   * 不传时，主币不够的子钱包对应的项 status 为 'failed'
+   */
+  gasWallet?: SignerInput
+  /** 补 gas 的方式，见 batchTransfer 的 mode，默认 'disperse'（一笔交易给所有子钱包补） */
+  gasMode?: 'disperse' | 'tx'
+  /** 补 gas 数量的额外倍数，默认 1 */
+  gasBuffer?: number
+  /** 各代币的最小归集数量（最小单位），余额低于它的不归集：`{ [USDT]: 10n ** 6n }` */
+  minAmount?: Readonly<Record<string, BigNumberish>>
+}
+
+/** 单个钱包单个代币的归集结果；from 是子钱包，to 是归集地址 */
+export interface CollectItemResult extends WriteResult {
+  token: string
+  native: boolean
+  /** 归集的数量（最小单位）；主币扫尾在发送前为 '0' */
+  amount: string
+  formatted: string | null
+}
+
+export interface CollectResult {
+  /** 按 wallets × tokens 顺序（第 i 个钱包第 j 个代币在 i × tokens.length + j） */
+  results: CollectItemResult[]
+  /** 补 gas 的转账（没有需要补的钱包时为空） */
+  topUps: TransferResult[]
+}
+
+interface Item {
+  index: number
+  signer: ResolvedSigner
+  token: string
+  native: boolean
+  amount: bigint
+  decimals: number | null
+  gasLimit: bigint | null
+  result: CollectItemResult
+}
+
+/**
+ * 归集：多个钱包的代币 / 主币转到同一个地址。每个钱包内按代币顺序逐笔发送，钱包之间并发。
+ *
+ * ```ts
+ * const { results, topUps } = await batchCollect(multi, [key1, key2, key3], hotWallet, {
+ *   tokens: [USDT, NATIVE_TOKEN],   // 主币放在里面表示代币归集完后扫空剩余主币
+ *   gasWallet: gasKey,              // 子钱包主币不够付手续费时先从这里补
+ * })
+ * ```
+ *
+ * 流程：一次 multicall 读出所有钱包的余额 → 预估每笔归集的手续费 → 给不够的钱包补 gas（等确认）
+ * → 发代币归集 → （包含主币时）等代币归集确认、按最新余额扫空主币。
+ * dryRun 时只做到预估，返回计划（补多少 gas、每笔 gasLimit），不发任何交易
+ */
+export async function batchCollect(provider: Provider, wallets: readonly SignerInput[], to: string, options: BatchCollectOptions): Promise<CollectResult> {
+  const tron = await tronModule(provider)
+  if (tron) {
+    return tron.tronBatchCollect(provider, wallets, to, options)
+  }
+  const rpc = await WriteRpc.from(provider)
+  const target = getAddress(to)
+  const cache = new Map()
+  const signers = await Promise.all(wallets.map((w) => resolveSigner(w, cache)))
+  const tokens = options.tokens
+  const nativeIndex = tokens.findIndex((t) => provider.isNativeToken(t))
+  const sweep = nativeIndex >= 0
+  const multiplier = options.gasMultiplier
+
+  // 一次 multicall 读出所有钱包的代币余额 + 主币余额（算手续费要用）
+  const queryTokens = sweep ? [...tokens] : [...tokens, NATIVE_TOKEN]
+  const nativeAt = sweep ? nativeIndex : tokens.length
+  const balances = await provider.multiBalances(signers.map((s) => ({ owner: s.address, tokens: queryTokens })))
+  const minAmount = new Map(Object.entries(options.minAmount ?? {}).map(([k, v]) => [k.toLowerCase(), getBigInt(v)]))
+
+  const items: Item[] = []
+  const seen = new Set<string>()
+  signers.forEach((signer, w) => {
+    const duplicate = seen.has(signer.address.toLowerCase())
+    seen.add(signer.address.toLowerCase())
+    tokens.forEach((token, t) => {
+      const balance = balances[w]?.[t] as TokenBalance
+      const native = t === nativeIndex
+      const decimals = balance.success ? balance.decimals : null
+      const item: Item = {
+        index: w * tokens.length + t,
+        signer,
+        token: native ? token : getAddress(token),
+        native,
+        amount: native ? 0n : balance.success ? BigInt(balance.balance) : 0n,
+        decimals,
+        gasLimit: null,
+        result: null as unknown as CollectItemResult,
+      }
+      const skip = !balance.success
+        ? `cannot read balance: ${balance.error ?? 'unknown error'}`
+        : signer.address === target
+          ? 'skipped: wallet is the collect address'
+          : duplicate
+            ? 'skipped: duplicate wallet'
+            : !native && item.amount === 0n
+              ? 'skipped: zero balance'
+              : !native && item.amount < (minAmount.get(token.toLowerCase()) ?? 0n)
+                ? 'skipped: below minAmount'
+                : null
+      item.result = toCollectResult(item, target, emptyOutcome(skip ? (balance.success ? 'skipped' : 'failed') : 'skipped', skip))
+      items.push(item)
+    })
+  })
+  const results = items.map((i) => i.result)
+  const report = (item: Item, outcome: TxOutcome) => {
+    item.result = toCollectResult(item, target, outcome)
+    results[item.index] = item.result
+    options.onUpdate?.(item.result)
+  }
+  const active = (item: Item) => item.result.error === null
+
+  // 预估每个钱包的代币归集 gas，算出需要补多少主币。
+  // 手续费价格只取这一次，代币归集也按它发：补 gas 等确认期间节点报价上涨，也不会超出补的数量、因余额不足被拒
+  const fee = await new FeeSource(rpc, options).get()
+  const fees = FeeSource.fixed(rpc, fee)
+  const byWallet = new Map<string, Item[]>()
+  items.forEach((item) => {
+    if (active(item)) {
+      byWallet.set(item.signer.address, [...(byWallet.get(item.signer.address) ?? []), item])
+    }
+  })
+  const plans = await mapPool([...byWallet.entries()], options.concurrency ?? 8, async ([address, list]) => {
+    const native = balances[signers.findIndex((s) => s.address === address)]?.[nativeAt] as TokenBalance
+    if (!native.success) {
+      // 主币余额读不到：不知道要补多少，不补（按 0 算会多补，而这个钱包也不会扫主币，多补的收不回来）
+      list.filter((i) => !i.native).forEach((i) => report(i, emptyOutcome('failed', `cannot read the native balance: ${native.error ?? 'unknown error'}`)))
+      return { address, list, shortfall: 0n }
+    }
+    let need = 0n
+    for (const item of list) {
+      if (item.native) {
+        continue
+      }
+      const tx = { from: address, to: item.token, data: erc20Interface.encodeFunctionData('transfer', [target, item.amount]) }
+      try {
+        item.gasLimit = applyGasMultiplier(await rpc.estimateGas(tx), multiplier)
+      } catch (err) {
+        if (!/insufficient funds/i.test(failureText(err))) {
+          report(item, { ...emptyOutcome('failed', failureText(err)) })
+          continue
+        }
+        item.gasLimit = FALLBACK_TOKEN_GAS
+      }
+      need += item.gasLimit * fee.perGas + (await l1Fee(rpc, { ...tx, from: undefined, gasLimit: item.gasLimit, ...feeFields(fee) }))
+    }
+    const wallet = signers.findIndex((s) => s.address === address)
+    const nativeBalance = BigInt((balances[wallet]?.[nativeAt] as TokenBalance).balance)
+    const buffered = (need * BigInt(Math.round((options.gasBuffer ?? 1) * 1000))) / 1000n
+    return { address, list, shortfall: buffered > nativeBalance ? buffered - nativeBalance : 0n }
+  })
+
+  // 补 gas
+  let topUps: TransferResult[] = []
+  const short = plans.filter((p) => p.shortfall > 0n && p.list.some((i) => !i.native && active(i)))
+  if (short.length) {
+    if (!options.gasWallet) {
+      short.forEach((p) => p.list.filter((i) => !i.native && active(i)).forEach((i) => report(i, emptyOutcome('failed', `insufficient native balance for gas: need ${p.shortfall} more wei (pass gasWallet to top up automatically)`))))
+    } else {
+      topUps = await batchTransfer(
+        provider,
+        options.gasWallet,
+        short.map((p) => ({ to: p.address, amount: p.shortfall, token: NATIVE_TOKEN })),
+        { ...sendOptions(options), mode: options.gasMode ?? 'disperse', wait: true },
+      )
+      topUps.forEach((t, k) => {
+        const ok = t.status === 'confirmed' || (options.dryRun && t.status === 'simulated')
+        if (!ok) {
+          ;(short[k] as (typeof short)[number]).list.filter((i) => !i.native && active(i)).forEach((i) => report(i, emptyOutcome('failed', `gas top-up ${t.status}: ${t.error ?? ''}`.trim())))
+        }
+      })
+    }
+  }
+
+  // 代币归集
+  const tokenItems = items.filter((i) => !i.native && active(i))
+  if (options.dryRun) {
+    tokenItems.forEach((i) => report(i, { ...emptyOutcome('simulated'), gasLimit: i.gasLimit }))
+    if (sweep) {
+      items.filter((i) => i.native && active(i)).forEach((i) => report(i, { ...emptyOutcome('simulated'), gasLimit: 21_000n }))
+    }
+    return { results, topUps }
+  }
+  const minBlock = new Map<string, number>()
+  topUps.forEach((t) => t.blockNumber !== null && minBlock.set(getAddress(t.to), t.blockNumber))
+  const track = (item: Item, outcome: TxOutcome) => {
+    if (outcome.blockNumber !== null) {
+      minBlock.set(item.signer.address, Math.max(minBlock.get(item.signer.address) ?? 0, outcome.blockNumber))
+    }
+    report(item, outcome)
+  }
+  // 发送前重新预估（不用补 gas 前的 gasLimit）：预估时余额不足、用了兜底值的项按实际需要发；余额变了的项预估失败，不会上链 revert 白付手续费
+  const jobs: TxJob[] = tokenItems.map((item) => ({
+    signer: item.signer,
+    continueOnError: true,
+    build: async () => ({ to: item.token, data: erc20Interface.encodeFunctionData('transfer', [target, item.amount]), value: 0n }),
+    onUpdate: (outcome) => track(item, outcome),
+  }))
+  // 要扫主币时必须等代币归集确认（扫的是扣完手续费后的余额）
+  await sendJobs(rpc, jobs, sweep ? { ...options, wait: true } : options, fees)
+
+  // 代币没有全部归集成功的钱包不扫主币：留着付之后重新归集的手续费；还没确认的交易也要用这部分主币付手续费
+  items
+    .filter((i) => i.native && active(i))
+    .forEach((native) => {
+      const unfinished = items.find((i) => !i.native && i.signer.address === native.signer.address && i.result.status !== 'confirmed' && i.result.status !== 'skipped')
+      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 (sweep && sweepItems.length && !options.signal?.aborted) {
+    // 代币归集已经发出：这一阶段出错不能整体抛错（调用方会拿不到这些结果），扫主币的项标记失败
+    const failSweep = (error: string) => {
+      sweepItems.forEach((i) => report(i, emptyOutcome('failed', error)))
+      return { results, topUps }
+    }
+    let sweepFee: TxFees
+    try {
+      sweepFee = await new FeeSource(rpc, options).get()
+    } catch (err) {
+      return failSweep(`cannot get the fee data: ${failureText(err)}`)
+    }
+    let gasLimit = 21_000n
+    try {
+      gasLimit = applyGasMultiplier(await rpc.estimateGas({ from: (sweepItems[0] as Item).signer.address, to: target, value: 1n }), multiplier)
+    } catch (err) {
+      // 归集地址拒收主币（如没有 receive 的合约）：发了也必然 revert，白付手续费
+      if (isExecutionError(err)) return failSweep(`the collect address cannot receive the native coin: ${failureText(err)}`)
+      // 节点暂时出错：按普通转账
+    }
+    const sweepJobs = await mapPool(sweepItems, options.concurrency ?? 8, async (item): Promise<TxJob | null> => {
+      const block = minBlock.get(item.signer.address)
+      let balance: TokenBalance | undefined
+      try {
+        ;[balance] = await provider.balances(item.signer.address, [NATIVE_TOKEN], block === undefined ? {} : { minBlock: block })
+      } catch (err) {
+        // 代币归集已经发出：不能整体抛错（调用方会拿不到这些结果），这一项标记失败
+        report(item, emptyOutcome('failed', `cannot read balance: ${failureText(err)}`))
+        return null
+      }
+      if (!balance?.success) {
+        report(item, emptyOutcome('failed', `cannot read balance: ${balance?.error ?? 'unknown error'}`))
+        return null
+      }
+      const reserve = gasLimit * sweepFee.perGas + (await l1Fee(rpc, { to: target, value: BigInt(balance.balance), gasLimit, ...feeFields(sweepFee) }))
+      const amount = BigInt(balance.balance) - reserve
+      if (amount <= 0n) {
+        report(item, emptyOutcome('skipped', 'skipped: native balance does not cover the gas fee'))
+        return null
+      }
+      item.amount = amount
+      return {
+        signer: item.signer,
+        gasLimit,
+        continueOnError: true,
+        build: async () => ({ to: target, data: '0x', value: amount }),
+        onUpdate: (outcome) => report(item, outcome),
+      }
+    })
+    await sendJobs(rpc, sweepJobs.filter((j): j is TxJob => j !== null), options, FeeSource.fixed(rpc, sweepFee))
+  }
+  return { results, topUps }
+}
+
+/** 只保留发送参数（补 gas 时不带 tokens / onUpdate 等归集参数） */
+function sendOptions(options: BatchCollectOptions): SendOptions {
+  const { tokens: _tokens, gasWallet: _gasWallet, gasMode: _gasMode, gasBuffer: _gasBuffer, minAmount: _minAmount, onUpdate: _onUpdate, ...rest } = options
+  return rest
+}
+
+function feeFields(fee: TxFees) {
+  return fee.type === 2 ? { type: 2, maxFeePerGas: fee.maxFeePerGas, maxPriorityFeePerGas: fee.maxPriorityFeePerGas } : { type: 0, gasPrice: fee.gasPrice }
+}
+
+function toCollectResult(item: Item, to: string, outcome: TxOutcome): CollectItemResult {
+  return {
+    ...toWriteResult(item.index, item.signer.address, to, outcome),
+    token: item.token,
+    native: item.native,
+    amount: item.amount.toString(),
+    formatted: item.decimals === null ? null : formatUnits(item.amount, item.decimals),
+  }
+}