@w3lib/evm-batch-call 0.6.0 → 0.8.0

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,

package/src/write/tron.ts

@@ -744,6 +744,49 @@ function canonical(address: string): string {
   return toTronAddress(toEvmAddress(address))
 }
 
+/** 一笔交易的手续费估算（子路径 /fees 的 estimateCost 在 Tron 上用） */
+export interface TronCostEstimate {
+  /** 合约调用消耗的能量（模拟得到）；转 TRX 为 0 */
+  energy: number
+  /** 交易的字节数（带宽） */
+  bandwidth: number
+  /** 账户剩余的能量 / 带宽不够时要烧的 TRX（sun） */
+  energyBurn: bigint
+  bandwidthBurn: bigint
+  /** 转 TRX 给没激活的地址：激活费（含创建账户的带宽），算在 bandwidthBurn 里 */
+  activates: boolean
+  /** 每单位能量、每字节带宽的价格（sun） */
+  energyPrice: bigint
+  bandwidthPrice: bigint
+}
+
+/**
+ * 估算一笔交易要烧多少 TRX：合约调用模拟出能量，按发送者剩余的质押能量 / 免费和质押带宽抵扣，不够的部分按链参数的价格烧 TRX。
+ * 能量按模拟值（不加余量），实际执行可能略有出入
+ */
+export async function tronEstimateCost(provider: Provider, call: { from: string; to: string; data?: string; value?: bigint }): Promise<TronCostEstimate> {
+  const rpc = await tronRpc(provider, {})
+  const from = canonical(call.from)
+  const to = canonical(call.to)
+  const value = call.value ?? 0n
+  const data = call.data && call.data !== '0x' ? call.data : null
+  const [params, resources, isContract] = await Promise.all([rpc.params(), rpc.resources(from), data ? Promise.resolve(true) : rpc.isContract(to)])
+  const contract: TronContract = isContract ? { type: 'trigger', owner: from, contract: to, data: data ?? '0x', callValue: value } : { type: 'transfer', owner: from, to, amount: value }
+  const energy = contract.type === 'trigger' ? await rpc.simulate(contract) : 0
+  const feeLimit = contract.type === 'trigger' ? BigInt(Math.ceil(energy * 1.5)) * params.energyFee || 1_000_000n : 0n
+  const bytes = transactionBytes(contract, feeLimit)
+  const activates = contract.type === 'transfer' && !(await rpc.accountExists(to))
+  return {
+    energy,
+    bandwidth: bytes,
+    energyBurn: BigInt(Math.max(0, energy - resources.energy)) * params.energyFee,
+    bandwidthBurn: contract.type === 'transfer' ? transferBurn(resources, bytes, params, activates) : bandwidthBurn(resources, bytes, params.bandwidthFee),
+    activates,
+    energyPrice: params.energyFee,
+    bandwidthPrice: params.bandwidthFee,
+  }
+}
+
 /** 转 TRX：普通地址用 TransferContract；合约地址用合约调用（空 calldata 带 call_value，主网禁止 TransferContract 转给合约） */
 async function trxContract(rpc: TronRpc, owner: string, to: string, amount: bigint): Promise<TronContract> {
   return (await rpc.isContract(to)) ? { type: 'trigger', owner, contract: to, data: '0x', callValue: amount } : { type: 'transfer', owner, to, amount }