@w3lib/evm-batch-call 0.7.0 → 0.8.0

package/src/swap.ts

@@ -3,13 +3,14 @@
  * 批量报价（V2 用 Router 的 getAmountsOut，V3 用 QuoterV2，按 gas 分成几次并发的 eth_call），选输出最多的；按滑点算最少收到的数量，
  * 构建授权 + 兑换的交易（V2 走 Router 的 swapExact…SupportingFeeOnTransferTokens，V3 走 SwapRouter02 / PancakeSwap SmartRouter 的 multicall）
  */
-import { Interface, type BigNumberish } from 'ethers'
+import { Interface, getAddress, type BigNumberish } from 'ethers'
 
 import { approvals, createCtx, evm, fmt, isNative, minus, out, parseAmount, same, tokenInfo, type Ctx } from './liquidity/common.js'
 import type { LiquidityTxResult } from './liquidity/types.js'
 import { LP_PROTOCOLS, LP_QUOTE_TOKENS, type LpProtocol, type LpToken } from './lp.js'
 import type { BlockTag } from './aggregate.js'
 import type { Provider } from './provider.js'
+import type { SignedPermit } from './permit.js'
 import type { BatchCallOptions } from './write/batch.js'
 import type { SignerInput } from './write/signer.js'
 
@@ -42,6 +43,7 @@ const v2RouterInterface = new Interface([
   'function swapExactETHForTokensSupportingFeeOnTransferTokens(uint256 amountOutMin, address[] path, address to, uint256 deadline) payable',
   'function swapExactTokensForETHSupportingFeeOnTransferTokens(uint256 amountIn, uint256 amountOutMin, address[] path, address to, uint256 deadline)',
 ])
+const permitInterface = new Interface(['function permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s)'])
 const v3FactoryInterface = new Interface(['function getPool(address tokenA, address tokenB, uint24 fee) view returns (address)'])
 const v3PoolInterface = new Interface(['function liquidity() view returns (uint128)'])
 /** QuoterV2 很费 gas（池子很薄时一次可达上千万）：每次 eth_call 只放几个报价，多个 eth_call 并发，避免超过节点的 gas 上限后被悄悄截掉 */
@@ -56,6 +58,7 @@ const swapRouterInterface = new Interface([
   'function exactInputSingle((address tokenIn, address tokenOut, uint24 fee, address recipient, uint256 amountIn, uint256 amountOutMinimum, uint160 sqrtPriceLimitX96) params) payable returns (uint256 amountOut)',
   'function exactInput((bytes path, address recipient, uint256 amountIn, uint256 amountOutMinimum) params) payable returns (uint256 amountOut)',
   'function unwrapWETH9(uint256 amountMinimum, address recipient) payable',
+  'function selfPermitIfNecessary(address token, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) payable',
   'function multicall(uint256 deadline, bytes[] data) payable returns (bytes[] results)',
 ])
 
@@ -75,8 +78,20 @@ export interface SwapOptions {
   deadline?: number
   /** 收到代币的地址，默认 owner */
   recipient?: string
-  /** 授权额度：'exact'（默认，本次卖出的数量）或 'max' */
-  approve?: 'exact' | 'max'
+  /**
+   * 授权方式：
+   * - 'exact'（默认）：授权本次卖出的数量；'max'：无限额度
+   * - 'permit'：用 EIP-2612 签名代替授权交易（要代币支持，见 /permit 的 detectPermit）。V3 路线（SwapRouter02 / SmartRouter）把 selfPermit 放进同一笔 multicall，
+   *   一次签名、一笔交易；V2 路线的 Router 没有 selfPermit，只有 `atomic` 批量（7702 / 4337 / 5792）发送时才用 permit，否则仍然是普通授权
+   * - 'permit2'：内置的 V2 / V3 路由都不使用 Permit2（它们直接 transferFrom），所以会退回普通的 'exact' 授权；结果的 plan.approval 里有说明
+   * - 'auto'：能用 permit 就用，否则普通授权
+   * 退回普通授权时 plan.approval.method 为 'approve'，reason 写明原因
+   */
+  approve?: 'exact' | 'max' | 'permit' | 'permit2' | 'auto'
+  /** 交易会在一笔原子批量里发送（`swap` 的 mode 为 7702 / 4337 / 5792 时自动为 true）：V2 路线才能把 permit 和兑换放进同一笔 */
+  atomic?: boolean
+  /** 已签名的 permit（`swap` 内部使用）：V3 路线嵌入 multicall 的 selfPermit，V2 路线放在兑换前；不再生成授权交易 */
+  signedPermit?: SignedPermit
   /**
    * 代币的转账税（比例，0.05 = 5%），默认 0。V2 报价（getAmountsOut）不含转账税，带税的代币
    * 实际收到的比报价少，最少收到按 (1 − slippage) × (1 − tax) 算，否则会因 INSUFFICIENT_OUTPUT_AMOUNT 回滚。
@@ -106,8 +121,8 @@ export interface SwapRoute {
 }
 
 export interface SwapTx {
-  /** approve：卖出的代币授权给 Router；swap：兑换 */
-  kind: 'approve' | 'swap'
+  /** approve：卖出的代币授权给 Router；permit：提交 EIP-2612 签名（V2 路线批量发送时）；swap：兑换 */
+  kind: 'approve' | 'permit' | 'swap'
   to: string
   data: string
   /** 附带的主币（最小单位）：卖出主币时为卖出的数量 */
@@ -136,6 +151,19 @@ export interface SwapPlan {
   routes: SwapRoute[]
   /** 按顺序发送的交易（授权在前） */
   transactions: SwapTx[]
+  /** 请求了 permit / permit2 / auto 时：实际采用的授权方式和原因 */
+  approval?: SwapApproval
+}
+
+export interface SwapApproval {
+  requested: 'permit' | 'permit2' | 'auto'
+  /** 'permit'：用签名；'approve'：退回普通授权交易（reason 说明）；'none'：不需要授权（卖出主币 / 额度已够） */
+  method: 'permit' | 'approve' | 'none'
+  /** permit 的提交方式：selfPermit（V3 的 multicall 内）/ batch（和兑换放在同一笔原子批量） */
+  via?: 'selfPermit' | 'batch'
+  reason?: string
+  /** 要签的 permit（owner 授权 spender 精确的卖出数量，签名有效期与兑换的 deadline 相同） */
+  permit?: { token: string; spender: string; value: string; deadline: number }
 }
 
 interface Candidate {
@@ -264,7 +292,7 @@ function amountOf(c: Candidate, result: unknown): bigint {
  */
 export async function buildSwap(provider: Provider, owner: string, params: SwapParams, options: SwapOptions = {}): Promise<SwapPlan> {
   const { slippage, deadline, recipient, approve } = options
-  const ctx = await createCtx(provider, owner, { slippage, deadline, recipient, approve })
+  const ctx = await createCtx(provider, owner, { slippage, deadline, recipient, approve: approve === 'max' ? 'max' : 'exact' })
   const wrapped = LP_QUOTE_TOKENS[ctx.chainId]?.[0]
   const nativeIn = isNative(ctx, params.tokenIn)
   const nativeOut = isNative(ctx, params.tokenOut)
@@ -298,7 +326,16 @@ export async function buildSwap(provider: Provider, owner: string, params: SwapP
   // approvals 只会返回 kind 为 'approve' 的交易
   // Router 在 Tron 上是 T 地址：授权的 ABI 参数要用 0x 格式
   const transactions = (nativeIn ? [] : await approvals(ctx, [{ token: tokenIn, spender: evm(best.router), amount: amountIn }])) as SwapTx[]
-  transactions.push(swapTx(ctx, best, amountIn, amountOutMin, nativeIn, nativeOut))
+  let approval: SwapApproval | undefined
+  const requested = options.approve
+  if (requested === 'permit' || requested === 'permit2' || requested === 'auto') {
+    approval = await decideApproval(ctx, requested, best, tokenIn, amountIn, nativeIn, transactions.some((t) => t.kind === 'approve'), options)
+  }
+  let permitCall: string | undefined
+  if (options.signedPermit && approval?.method === 'permit') {
+    permitCall = applySignedPermit(options.signedPermit, approval, ctx, transactions)
+  }
+  transactions.push(swapTx(ctx, best, amountIn, amountOutMin, nativeIn, nativeOut, permitCall))
 
   const route = (c: Candidate & { amountOut: bigint }): SwapRoute => ({
     protocol: c.protocol.id,
@@ -323,10 +360,49 @@ export async function buildSwap(provider: Provider, owner: string, params: SwapP
     route: route(best),
     routes: routes.map(route),
     transactions,
+    ...(approval ? { approval } : {}),
+  }
+}
+
+/** permit / permit2 / auto：判断这条路线和这个代币能不能用签名代替授权交易，不能的退回普通授权并写明原因 */
+async function decideApproval(ctx: Ctx, requested: SwapApproval['requested'], best: Candidate, tokenIn: string, amountIn: bigint, nativeIn: boolean, needsApprove: boolean, options: SwapOptions): Promise<SwapApproval> {
+  if (nativeIn || !needsApprove) return { requested, method: 'none' }
+  const fallback = (reason: string): SwapApproval => ({ requested, method: 'approve', reason })
+  if (requested === 'permit2') {
+    return fallback('The built-in V2 / V3 routers pull tokens with transferFrom and do not consume Permit2 signatures; used a normal exact approve')
+  }
+  if (ctx.tron) return fallback('permit is not available on Tron; used a normal approve')
+  const { detectPermit } = await import('./permit.js')
+  const support = await detectPermit(ctx.provider, tokenIn)
+  if (!support.kind) return fallback(`${support.reason}; used a normal approve`)
+  if (support.kind === 'dai') return fallback('A DAI-style permit can only grant an unlimited allowance; used a normal exact approve')
+  const via = best.version === 'v3' ? 'selfPermit' : 'batch'
+  if (via === 'batch' && !options.atomic) {
+    return fallback("V2 routers have no selfPermit, so a separate permit() transaction saves nothing; use mode '7702' / '4337' / '5792' to send the permit and the swap atomically. Used a normal approve")
+  }
+  return { requested, method: 'permit', via, permit: { token: tokenIn, spender: evm(best.router), value: amountIn.toString(), deadline: ctx.deadline } }
+}
+
+/** 已签名的 permit 放进交易：V3 返回 selfPermit 的 calldata（嵌进 multicall），V2 往 transactions 里加一笔 permit 交易 */
+function applySignedPermit(signed: SignedPermit, approval: SwapApproval, ctx: Ctx, transactions: SwapTx[]): string | undefined {
+  const want = approval.permit as NonNullable<SwapApproval['permit']>
+  const p = signed.permit
+  if (p.kind !== 'eip2612' || getAddress(p.tokens[0] as string) !== getAddress(want.token) || getAddress(p.spender) !== getAddress(want.spender) || p.owner !== ctx.owner || BigInt(p.amounts[0] as string) !== BigInt(want.value)) {
+    throw new Error('The signed permit does not match the swap (token / spender / owner / amount)')
+  }
+  // 授权交易换成 permit
+  const at = transactions.findIndex((t) => t.kind === 'approve')
+  transactions.splice(at, transactions.length)
+  if (approval.via === 'selfPermit') {
+    return swapRouterInterface.encodeFunctionData('selfPermitIfNecessary', [want.token, want.value, p.deadline, signed.v, signed.r, signed.s])
   }
+  const m = p.typedData.message
+  const data = permitInterface.encodeFunctionData('permit', [m.owner, m.spender, m.value, m.deadline, signed.v, signed.r, signed.s])
+  transactions.push({ kind: 'permit', to: out(ctx, want.token), data, value: '0', token: out(ctx, want.token), spender: out(ctx, want.spender), amount: want.value })
+  return undefined
 }
 
-function swapTx(ctx: Ctx, c: Candidate, amountIn: bigint, amountOutMin: bigint, nativeIn: boolean, nativeOut: boolean): SwapTx {
+function swapTx(ctx: Ctx, c: Candidate, amountIn: bigint, amountOutMin: bigint, nativeIn: boolean, nativeOut: boolean, selfPermit?: string): SwapTx {
   const value = nativeIn ? amountIn.toString() : '0'
   if (c.version === 'v2') {
     const data = nativeIn
@@ -344,7 +420,7 @@ function swapTx(ctx: Ctx, c: Candidate, amountIn: bigint, amountOutMin: bigint,
           { tokenIn: c.path[0], tokenOut: c.path[1], fee: c.fees[0], recipient, amountIn, amountOutMinimum: amountOutMin, sqrtPriceLimitX96: 0n },
         ])
       : swapRouterInterface.encodeFunctionData('exactInput', [{ path: encodePath(c.path, c.fees), recipient, amountIn, amountOutMinimum: amountOutMin }])
-  const calls = nativeOut ? [swap, swapRouterInterface.encodeFunctionData('unwrapWETH9', [amountOutMin, ctx.recipient])] : [swap]
+  const calls = [...(selfPermit ? [selfPermit] : []), swap, ...(nativeOut ? [swapRouterInterface.encodeFunctionData('unwrapWETH9', [amountOutMin, ctx.recipient])] : [])]
   return { kind: 'swap', to: out(ctx, c.router), data: swapRouterInterface.encodeFunctionData('multicall', [ctx.deadline, calls]), value }
 }
 
@@ -352,14 +428,21 @@ export type SwapTxResult = Omit<LiquidityTxResult, 'kind'> & { kind: SwapTx['kin
 
 export interface SwapResult {
   plan: SwapPlan
-  /** 每笔交易的结果（授权、兑换） */
+  /** 每笔交易的结果（授权 / permit、兑换） */
   results: SwapTxResult[]
   /** 兑换那一笔的状态和哈希 */
   status: LiquidityTxResult['status']
   hash: string | null
+  /** 请求 permit / permit2 / auto 时：实际采用的授权方式（同 plan.approval，退回普通授权时有原因） */
+  approval?: SwapApproval
 }
 
 export interface SwapSendOptions extends SwapOptions, Omit<BatchCallOptions, 'mode' | 'continueOnError' | 'onUpdate'> {
+  /**
+   * 发送方式：'tx'（默认，授权和兑换分别发，授权确认后重新报价）；
+   * '7702' / '4337' / '5792'：授权（或 permit）和兑换放进同一笔原子批量，见 BatchCallOptions.mode
+   */
+  mode?: 'tx' | '7702' | '4337' | '5792'
   onUpdate?: (result: SwapTxResult) => void
 }
 
@@ -370,21 +453,55 @@ export interface SwapSendOptions extends SwapOptions, Omit<BatchCallOptions, 'mo
  * ```ts
  * const r = await swap(provider, key, { tokenIn: USDT, tokenOut: NATIVE_TOKEN, amountInFormatted: '100' }, { slippage: 0.01 })
  * r.status   // 'confirmed'
+ *
+ * // 用 EIP-2612 签名代替授权交易（V3 路线一笔交易完成；不支持时退回普通授权，r.approval.reason 说明原因）
+ * await swap(provider, signer, params, { approve: 'auto' })
  * ```
  */
 export async function swap(provider: Provider, from: SignerInput, params: SwapParams, options: SwapSendOptions = {}): Promise<SwapResult> {
   const [{ batchCall, tronModule }, { resolveSigner }, { emptyOutcome, toWriteResult }] = await Promise.all([import('./write/batch.js'), import('./write/signer.js'), import('./write/send.js')])
   const tron = await tronModule(provider)
-  const owner = tron ? await tron.tronSignerAddress(from) : (await resolveSigner(from)).address
-  let plan = await buildSwap(provider, owner, params, options)
-  const send = async (txs: SwapTx[]): Promise<SwapTxResult[]> =>
+  const resolved = tron ? null : await resolveSigner(from)
+  const owner = tron ? await tron.tronSignerAddress(from) : (resolved as NonNullable<typeof resolved>).address
+  const mode = options.mode ?? 'tx'
+  const atomic = mode !== 'tx'
+  // 4337 的 SimpleAccount：资产在账户地址里，兑换的 owner 是账户（合约账户不能签 EIP-2612，不用 permit）
+  let holder = owner
+  let smartHolder = false
+  if (mode === '4337' && (options.smartAccount?.account ?? 'simple') === 'simple') {
+    const [{ resolveSimpleAccount }, { WriteRpc }] = await Promise.all([import('./smartAccount/account.js'), import('./write/rpc.js')])
+    const sa = options.smartAccount
+    holder = (await resolveSimpleAccount(await WriteRpc.from(provider), owner, sa?.entryPoint ?? '0.7', sa?.salt, sa?.factory)).address
+    smartHolder = true
+  }
+  const wantsPermit = options.approve === 'permit' || options.approve === 'permit2' || options.approve === 'auto'
+  let plan = await buildSwap(provider, holder, params, { ...options, atomic, ...(smartHolder && wantsPermit ? { approve: 'exact' as const } : {}) })
+  if (smartHolder && wantsPermit && plan.transactions.length > 1) {
+    plan.approval = { requested: options.approve as 'permit', method: 'approve', reason: 'The 4337 smart account is a contract and cannot sign EIP-2612 permits; used a normal approve' }
+  }
+  if (plan.approval?.method === 'permit' && resolved) {
+    // 签 permit：精确的卖出数量、有效期与兑换的 deadline 相同；用户拒绝签名就整体中止（不悄悄改成发授权交易）
+    const { buildPermit, signPermit } = await import('./permit.js')
+    const want = plan.approval.permit as NonNullable<SwapApproval['permit']>
+    const permit = await buildPermit(provider, { token: want.token, owner: holder, spender: want.spender, value: want.value }, { deadlineAt: want.deadline })
+    const signed = await signPermit(resolved.signer as Parameters<typeof signPermit>[0], permit, { chainId: await provider.getChainId() })
+    try {
+      plan = await buildSwap(provider, holder, params, { ...options, atomic, signedPermit: signed })
+    } catch (err) {
+      // 签名后重新报价，最优路线变了（路由 / 版本 / 数量不同），签名对不上：改用普通授权，不让已经签过的请求白白中止
+      if (!/signed permit does not match/.test(err instanceof Error ? err.message : String(err))) throw err
+      plan = await buildSwap(provider, holder, params, { ...options, atomic, approve: 'exact' })
+      if (plan.approval) plan.approval = { ...plan.approval, requested: options.approve as 'permit', method: 'approve', reason: 'The best route changed after the permit was signed; used a normal approve' }
+    }
+  }
+  const send = async (txs: SwapTx[], asMode: 'tx' | 'atomic' = 'tx'): Promise<SwapTxResult[]> =>
     (
       await batchCall(
         provider,
         txs.map((tx) => ({ from, to: tx.to, data: tx.data, value: BigInt(tx.value) })),
         {
           ...options,
-          mode: 'tx',
+          mode: asMode === 'atomic' ? mode : 'tx',
           continueOnError: false,
           onUpdate: options.onUpdate ? (r) => options.onUpdate?.({ ...r, kind: (txs[r.index] as SwapTx).kind }) : undefined,
         },
@@ -392,15 +509,20 @@ export async function swap(provider: Provider, from: SignerInput, params: SwapPa
     ).map((r, i) => ({ ...r, kind: (txs[i] as SwapTx).kind }))
   const txs = plan.transactions
   let results: SwapTxResult[]
-  if (txs.length === 1) {
+  if (atomic) {
+    // 授权 / permit 和兑换在同一笔原子批量里：要么都成功，要么都不生效
+    results = await send(txs, 'atomic')
+  } else if (txs.length === 1) {
     results = await send(txs)
   } else {
     // 有授权时先发授权：确认后重新报价再发兑换，deadline 和最少收到从发兑换那一刻算，
     // 不会因为授权等得久而过期或按旧价成交
     const approved = await send(txs.slice(0, -1))
     const last = txs[txs.length - 1] as SwapTx
+    const approval = plan.approval
     if (approved.every((r) => r.status === 'confirmed')) {
-      plan = await buildSwap(provider, owner, params, options)
+      plan = await buildSwap(provider, holder, params, { ...options, approve: options.approve === 'max' ? 'max' : 'exact' })
+      if (approval) plan.approval = approval // 重新报价时额度已够：保留最初的选择和原因
       const fresh = plan.transactions[plan.transactions.length - 1] as SwapTx
       results = [...approved, ...(await send([fresh])).map((r) => ({ ...r, index: txs.length - 1 }))]
     } else {
@@ -408,6 +530,5 @@ export async function swap(provider: Provider, from: SignerInput, params: SwapPa
     }
   }
   const main = results[results.length - 1] as SwapTxResult
-  return { plan, results, status: main.status, hash: main.hash }
+  return { plan, results, status: main.status, hash: main.hash, ...(plan.approval ? { approval: plan.approval } : {}) }
 }
-

package/src/write/batch.ts

@@ -6,6 +6,8 @@ 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 type { Eip1193Like } from '../smartAccount/eip5792.js'
+import type { SmartAccountOptions } from '../smartAccount/send.js'
 import { resolveSigner, type ResolvedSigner, type SignerInput } from './signer.js'
 
 /**
@@ -38,13 +40,17 @@ export interface WriteCall {
   gasLimit?: bigint
 }
 
-export type BatchCallMode = 'tx' | '7702'
+export type BatchCallMode = 'tx' | '7702' | '4337' | '5792'
 
 export interface BatchCallOptions extends SendOptions, TronSendOptions {
   /**
    * - 'tx'（默认）：每个调用一笔交易，所有链都支持
    * - '7702'：钱包通过 EIP-7702 委托给批量执行合约，同一钱包的调用合成一笔交易（按 batchSize 拆分），一笔里的调用要么全部成功要么全部失败。
-   *   需要链支持 EIP-7702，钱包需要能本地签名（私钥 / ethers Wallet）。委托会一直保留，可用 revokeDelegation 撤销
+   *   需要链支持 EIP-7702，钱包需要能本地签名（私钥 / ethers Wallet）。委托会一直保留，可用 revokeDelegation 撤销。
+   *   传 sponsor 时由 sponsor 钱包发交易并付 gas（用户只签授权和 UserOperation，不需要有主币），见 sponsor
+   * - '4337'：ERC-4337 智能账户（smartAccount 选项：bundler / paymaster / selfBundle），一个 UserOperation 原子执行同一钱包的调用，可由 paymaster 代付 gas。
+   *   默认账户是 owner 对应的 SimpleAccount（首次使用时部署，资产要放在账户地址里）。子路径 /smart-account
+   * - '5792'：浏览器钱包的 EIP-5792（wallet_sendCalls）：钱包支持原子批量时一次确认原子执行，不支持时退回逐笔发送
    */
   mode?: BatchCallMode
   /**
@@ -58,6 +64,20 @@ export interface BatchCallOptions extends SendOptions, TronSendOptions {
   batchSize?: number
   /** 7702：钱包已委托给其他合约时改为委托给 delegate。默认 false（报错，不动已有的委托） */
   redelegate?: boolean
+  /**
+   * '7702' 代付 gas：用这个钱包（私钥 / Signer）发 EntryPoint.handleOps 交易，付 gas 的是它，用户钱包不需要主币。
+   * 用户签 EIP-7702 授权（未委托时）+ UserOperation；UserOperation 的 gas 价格为 0，sponsor 拿不到补偿，也不能改调用内容。
+   * 用 EntryPoint v0.8 + Simple7702Account
+   */
+  sponsor?: SignerInput
+  /** '4337' 的智能账户选项 */
+  smartAccount?: SmartAccountOptions
+  /** '5792'：钱包的 provider（EIP-1193 / BrowserProvider）。默认用 from 的 JsonRpcSigner 背后的 provider */
+  eip1193?: Eip1193Like
+  /** '5792'：要求原子执行，钱包不能原子批量时不退回逐笔发送，直接失败。默认 false */
+  atomicRequired?: boolean
+  /** '5792'：传给 wallet_sendCalls 的 capabilities（如 `{ paymasterService: { url } }`） */
+  capabilities?: Record<string, unknown>
 }
 
 /** 归一化后的调用 */
@@ -111,7 +131,26 @@ export async function batchCall(provider: Provider, calls: readonly WriteCall[],
   }
   const rpc = await WriteRpc.from(provider)
   const normalized = await normalizeCalls(calls)
-  return (options.mode ?? 'tx') === '7702' ? send7702(rpc, normalized, options) : sendEach(rpc, normalized, options)
+  return sendByMode(rpc, normalized, options)
+}
+
+/** 按 mode 发送；智能账户 / 5792 的代码按需加载，不用时 /write 的体积不变 */
+export async function sendByMode(rpc: WriteRpc, calls: readonly NormalizedCall[], options: BatchCallOptions): Promise<WriteResult[]> {
+  const mode = options.mode ?? 'tx'
+  if (mode === '7702' && options.sponsor) {
+    const { sendSmartBatch } = await import('../smartAccount/send.js')
+    return sendSmartBatch(rpc, calls, { ...options, smartAccount: { ...options.smartAccount, account: 'simple7702', entryPoint: '0.8', selfBundle: options.sponsor, bundler: undefined } })
+  }
+  if (mode === '7702') return send7702(rpc, calls, options)
+  if (mode === '4337') {
+    const { sendSmartBatch } = await import('../smartAccount/send.js')
+    return sendSmartBatch(rpc, calls, options)
+  }
+  if (mode === '5792') {
+    const { send5792 } = await import('../smartAccount/eip5792.js')
+    return send5792(rpc, calls, options)
+  }
+  return sendEach(rpc, calls, options)
 }
 
 /** Tron 链上用 Tron 的实现（按需加载：只用 EVM 时打包不会带上） */
@@ -137,7 +176,7 @@ export async function sendEach(rpc: WriteRpc, calls: readonly NormalizedCall[],
 }
 
 /** 钱包当前的委托状态 */
-async function delegationOf(rpc: WriteRpc, address: string): Promise<{ delegated: boolean; to: string | null }> {
+export 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 }
@@ -251,7 +290,7 @@ export async function send7702(rpc: WriteRpc, calls: readonly NormalizedCall[],
 }
 
 /** 解析 executeBatch 的 ExecuteError(index, error)；只有一个调用时合约直接透传 revert 数据 */
-function failedIndex(data: string, size: number): { index: number; reason: string } | null {
+export 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' }

package/src/write/collect.ts

@@ -6,7 +6,7 @@ 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 { sendByMode, tronModule, type NormalizedCall } from './batch.js'
 import { batchTransfer, type TransferResult } from './transfer.js'
 
 const erc20Interface = new Interface(ERC20_ABI as unknown as string[])
@@ -31,6 +31,15 @@ export interface BatchCollectOptions extends SendOptions, TronSendOptions {
   gasBuffer?: number
   /** 各代币的最小归集数量（最小单位），余额低于它的不归集：`{ [USDT]: 10n ** 6n }` */
   minAmount?: Readonly<Record<string, BigNumberish>>
+  /**
+   * 代付 gas 归集：用这个钱包发交易（EIP-7702 + EntryPoint v0.8，见 BatchCallOptions.sponsor），子钱包不需要主币、不用补 gas，
+   * 每个子钱包的所有代币一个 UserOperation 原子归集；包含主币时全部主币一起转走（没有手续费要留）。
+   * 子钱包会被委托给 delegate（默认 Simple7702Account，委托保留，可用 revokeDelegation 撤销）
+   */
+  sponsor?: SignerInput
+  /** sponsor 模式：委托的合约、是否替换已有委托，见 BatchCallOptions */
+  delegate?: string
+  redelegate?: boolean
 }
 
 /** 单个钱包单个代币的归集结果；from 是子钱包，to 是归集地址 */
@@ -136,6 +145,11 @@ export async function batchCollect(provider: Provider, wallets: readonly SignerI
   }
   const active = (item: Item) => item.result.error === null
 
+  if (options.sponsor) {
+    await collectSponsored(rpc, items, target, options, balances, nativeAt, results)
+    return { results, topUps: [] }
+  }
+
   // 预估每个钱包的代币归集 gas，算出需要补多少主币。
   // 手续费价格只取这一次，代币归集也按它发：补 gas 等确认期间节点报价上涨，也不会超出补的数量、因余额不足被拒
   const fee = await new FeeSource(rpc, options).get()
@@ -291,6 +305,51 @@ export async function batchCollect(provider: Provider, wallets: readonly SignerI
   return { results, topUps }
 }
 
+/** 代付 gas 归集：每个子钱包一批（所有代币 + 主币全额）原子转到归集地址 */
+async function collectSponsored(
+  rpc: WriteRpc,
+  items: readonly Item[],
+  target: string,
+  options: BatchCollectOptions,
+  balances: TokenBalance[][],
+  nativeAt: number,
+  results: CollectItemResult[],
+): Promise<void> {
+  const list = items.filter((i) => i.result.error === null)
+  for (const item of list) {
+    if (item.native) {
+      // 没有手续费要留：全部主币
+      const balance = balances[Math.floor(item.index / options.tokens.length)]?.[nativeAt] as TokenBalance
+      item.amount = balance.success ? BigInt(balance.balance) : 0n
+    }
+  }
+  const sendable = list.filter((i) => i.amount > 0n)
+  list.filter((i) => i.amount === 0n).forEach((i) => (results[i.index] = toCollectResult(i, target, emptyOutcome('skipped', 'skipped: zero balance'))))
+  const calls: NormalizedCall[] = sendable.map((i) => ({
+    signer: i.signer,
+    to: i.native ? target : i.token,
+    data: i.native ? '0x' : erc20Interface.encodeFunctionData('transfer', [target, i.amount]),
+    value: i.native ? i.amount : 0n,
+  }))
+  const written = await sendByMode(rpc, calls, {
+    ...sendOptions(options),
+    mode: '7702',
+    sponsor: options.sponsor,
+    delegate: options.delegate,
+    redelegate: options.redelegate,
+    continueOnError: true,
+    onUpdate: (r) => {
+      const item = sendable[r.index] as Item
+      results[item.index] = { ...toCollectResult(item, target, emptyOutcome('skipped')), ...r, index: item.index, to: target }
+      options.onUpdate?.(results[item.index] as CollectItemResult)
+    },
+  })
+  written.forEach((r, k) => {
+    const item = sendable[k] as Item
+    results[item.index] = { ...toCollectResult(item, target, emptyOutcome('skipped')), ...r, index: item.index, to: target }
+  })
+}
+
 /** 只保留发送参数（补 gas 时不带 tokens / onUpdate 等归集参数） */
 function sendOptions(options: BatchCollectOptions): SendOptions {
   const { tokens: _tokens, gasWallet: _gasWallet, gasMode: _gasMode, gasBuffer: _gasBuffer, minAmount: _minAmount, onUpdate: _onUpdate, ...rest } = options

package/src/write/send.ts

@@ -69,6 +69,10 @@ export interface WriteResult {
   fee: string | null
   blockNumber: number | null
   error: string | null
+  /** 智能账户模式（'4337' / sponsored '7702'）：UserOperation 哈希；此时 from 是账户地址，gasUsed / fee 是 UserOperation 的 */
+  userOpHash?: string | null
+  /** 智能账户 / EIP-5792 模式：同一批的调用是否在一笔里原子执行（5792 钱包不支持而退回逐笔发送时为 false） */
+  atomic?: boolean
 }
 
 /** 交易层面的结果（一笔交易可能对应多个调用的结果） */

package/src/write/signer.ts

@@ -1,4 +1,4 @@
-import { BaseWallet, JsonRpcSigner, SigningKey, getAddress, type Authorization, type AuthorizationRequest, type TransactionRequest } from 'ethers'
+import { BaseWallet, JsonRpcSigner, SigningKey, getAddress, type Authorization, type AuthorizationRequest, type TransactionRequest, type TypedDataDomain, type TypedDataField } from 'ethers'
 
 /**
  * 发交易的钱包，两种都可以：
@@ -35,6 +35,10 @@ export interface WriteSigner {
   sendTransaction?(tx: TransactionRequest): Promise<{ hash: string }>
   /** EIP-7702 授权签名（ethers Wallet 支持；'7702' 模式需要） */
   authorize?(auth: AuthorizationRequest): Promise<Authorization>
+  /** EIP-712 签名（Wallet / 浏览器钱包都支持）：4337 v0.8 的 UserOperation、permit */
+  signTypedData?(domain: TypedDataDomain, types: Record<string, TypedDataField[]>, value: Record<string, unknown>): Promise<string>
+  /** EIP-191 个人签名：4337 v0.7 的 UserOperation */
+  signMessage?(message: string | Uint8Array): Promise<string>
 }
 
 /** 归一化后的钱包 */

package/src/write/transfer.ts

@@ -2,7 +2,7 @@ import { Interface, getAddress, getBigInt, parseUnits, type BigNumberish } from
 
 import { ERC20_ABI, NATIVE_TOKEN, formatUnits } from '../erc20.js'
 import type { Provider } from '../provider.js'
-import { send7702, sendEach, tronModule, type NormalizedCall } from './batch.js'
+import { sendByMode, tronModule, type BatchCallOptions, type NormalizedCall } from './batch.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'
@@ -34,11 +34,12 @@ export interface TransferItem {
  * - 'disperse'（默认）：通过 Disperse 合约，每种代币每 batchSize 个收款人一笔交易。以下情况自动改为逐笔发送：
  *   链上没有 Disperse 合约；某种代币只有一个收款人；某一批预估 revert（收款地址拒收主币、转账收税的代币等，逐笔发送能把出问题的那一个单独标成失败）
  * - 'tx'：每个收款人一笔交易
- * - '7702'：EIP-7702 批量执行，每 batchSize 个收款人一笔（见 BatchCallOptions.mode）
+ * - '7702'：EIP-7702 批量执行，每 batchSize 个收款人一笔（见 BatchCallOptions.mode）；传 sponsor 时由 sponsor 代付 gas
+ * - '4337' / '5792'：智能账户 UserOperation / 浏览器钱包 wallet_sendCalls，每 batchSize 个收款人一笔、原子执行（见 BatchCallOptions.mode）
  */
-export type TransferMode = 'disperse' | 'tx' | '7702'
+export type TransferMode = 'disperse' | 'tx' | '7702' | '4337' | '5792'
 
-export interface BatchTransferOptions extends SendOptions, TronSendOptions {
+export interface BatchTransferOptions extends SendOptions, TronSendOptions, Pick<BatchCallOptions, 'sponsor' | 'smartAccount' | 'eip1193' | 'atomicRequired' | 'capabilities'> {
   /** 默认转的代币，默认主币（NATIVE_TOKEN）；每项也可以单独指定 token */
   token?: string
   mode?: TransferMode
@@ -130,9 +131,15 @@ export async function batchTransfer(provider: Provider, from: SignerInput, recip
   }
   const rpc = await WriteRpc.from(provider)
   const signer = await resolveSigner(from)
-  const planned = await plan(provider, signer.address, recipients, options)
   const mode = options.mode ?? 'disperse'
-  if (mode === 'tx' || mode === '7702') {
+  // 4337 的 SimpleAccount：资产在账户地址里，不是 owner 的地址
+  let holder = signer.address
+  if (mode === '4337' && (options.smartAccount?.account ?? 'simple') === 'simple') {
+    const { getSimpleAccountAddress } = await import('../smartAccount/account.js')
+    holder = await getSimpleAccountAddress(rpc, signer.address, options.smartAccount?.entryPoint ?? '0.7', options.smartAccount?.salt, options.smartAccount?.factory)
+  }
+  const planned = await plan(provider, holder, recipients, options)
+  if (mode !== 'disperse') {
     return sendDirect(rpc, signer, planned, mode, options)
   }
   return sendDisperse(rpc, provider, signer, planned, options)
@@ -203,8 +210,8 @@ function toTransferResult(p: Planned, result: WriteResult, via: TransferMode): T
   }
 }
 
-/** 'tx' / '7702'：直接转账 */
-async function sendDirect(rpc: WriteRpc, signer: ResolvedSigner, planned: readonly Planned[], mode: 'tx' | '7702', options: BatchTransferOptions): Promise<TransferResult[]> {
+/** 'tx' / '7702' / '4337' / '5792'：直接转账 */
+async function sendDirect(rpc: WriteRpc, signer: ResolvedSigner, planned: readonly Planned[], mode: Exclude<TransferMode, 'disperse'>, options: BatchTransferOptions): Promise<TransferResult[]> {
   const calls = planned.map((p) => transferCall(signer, p))
   const callOptions = {
     ...options,
@@ -212,7 +219,7 @@ async function sendDirect(rpc: WriteRpc, signer: ResolvedSigner, planned: readon
     continueOnError: true,
     onUpdate: options.onUpdate && ((r: WriteResult) => options.onUpdate?.(toTransferResult(planned[r.index] as Planned, r, mode))),
   }
-  const results = mode === '7702' ? await send7702(rpc, calls, callOptions) : await sendEach(rpc, calls, callOptions)
+  const results = await sendByMode(rpc, calls, callOptions)
   return results.map((r, i) => toTransferResult(planned[i] as Planned, r, mode))
 }
 
@@ -318,7 +325,7 @@ async function sendDisperse(rpc: WriteRpc, provider: Provider, signer: ResolvedS
   if (direct.length && !options.signal?.aborted) {
     direct.sort((a, b) => a.index - b.index)
     const calls = direct.map((p) => transferCall(signer, p))
-    await sendEach(rpc, calls, {
+    await sendByMode(rpc, calls, {
       ...options,
       mode: 'tx',
       continueOnError: true,