@w3lib/evm-batch-call 0.1.0

package/src/aggregate.ts

@@ -0,0 +1,254 @@
+import { AbiCoder, Interface, concat, dataSlice, id, isError, type Provider as EthersProvider } from 'ethers'
+
+import type { CallRequest, RawResult } from './call.js'
+import { DEPLOYLESS_MULTICALL3_BYTECODE } from './deployless.js'
+import { isExecutionError } from './errors.js'
+import { MULTICALL3_ADDRESS, type Multicall } from './multicall.js'
+
+/** 只用到 ethers Provider 的这两个方法，JsonRpcProvider / BrowserProvider 都满足 */
+export type EthersLikeProvider = Pick<EthersProvider, 'call' | 'getBalance'>
+
+export type BlockTag = number | bigint | string
+
+export interface CallOverrides {
+  blockTag?: BlockTag
+  from?: string
+}
+
+export const multicall3Interface = new Interface([
+  'function aggregate3((address target, bool allowFailure, bytes callData)[] calls) payable returns ((bool success, bytes returnData)[] returnData)',
+  'function getEthBalance(address addr) view returns (uint256 balance)',
+])
+
+const CALL3_TUPLE = 'tuple(address target, bool allowFailure, bytes callData)[]'
+const RESULT_TUPLE = 'tuple(bool success, bytes returnData)[]'
+/** error Aggregate3Result((bool,bytes)[]) */
+const AGGREGATE3_RESULT_SELECTOR = id('Aggregate3Result((bool,bytes)[])').slice(0, 10)
+
+/**
+ * 判定为无效的 multicall 地址（无代码 / 不是 Multicall3），按 chainId+address 记在模块级，
+ * 这样业务里每次 new Provider 也只会多试一次。
+ */
+const unusableMulticalls = new Set<string>()
+
+export interface AggregateContext {
+  provider: EthersLikeProvider
+  chainId: number
+  /** null 表示直接走 deployless */
+  multicall: Multicall | null
+  chunkSize: number
+}
+
+/**
+ * 执行一批请求，结果与 requests 一一对应。
+ * 有 multicall 合约就调合约的 aggregate3，否则（或合约不可用时）走 deployless。
+ * 超过 chunkSize 的请求会拆成多次 eth_call 并发执行（JsonRpcProvider 会把它们合到一个 HTTP batch 里）。
+ */
+export async function aggregate(
+  ctx: AggregateContext,
+  requests: CallRequest[],
+  overrides: CallOverrides = {},
+): Promise<RawResult[]> {
+  if (requests.length === 0) {
+    return []
+  }
+  const size = Math.max(1, ctx.chunkSize)
+  if (requests.length <= size) {
+    return aggregateChunk(ctx, requests, overrides)
+  }
+  const chunks: CallRequest[][] = []
+  for (let i = 0; i < requests.length; i += size) {
+    chunks.push(requests.slice(i, i + size))
+  }
+  const results = await Promise.all(chunks.map((chunk) => aggregateChunk(ctx, chunk, overrides)))
+  return results.flat()
+}
+
+async function aggregateChunk(
+  ctx: AggregateContext,
+  requests: CallRequest[],
+  overrides: CallOverrides,
+): Promise<RawResult[]> {
+  const multicall = ctx.multicall
+  if (multicall && isUsable(ctx.chainId, multicall, overrides.blockTag)) {
+    const results = await callContract(ctx, multicall, requests, overrides)
+    if (Array.isArray(results)) {
+      return results
+    }
+    // 只有“最新状态下地址上没有可用合约”才记缓存。
+    // - revert 无数据（'reverted'）有歧义：可能是 out of gas / 节点 gas 上限、子调用失败而钱包丢了 revert 数据，
+    //   这些情况地址本身是好的，只对这一次退回 deployless，不记缓存
+    // - 历史区块查到无代码可能只是那时还没部署，不能推及 latest
+    if (results === 'invalid' && isLatest(overrides.blockTag)) {
+      unusableMulticalls.add(cacheKey(ctx.chainId, multicall.address))
+    }
+  }
+  return callDeployless(ctx, requests, overrides)
+}
+
+/**
+ * 'invalid'：地址上没有代码或返回无法解码；'reverted'：执行 revert 且没有 revert 数据。
+ * 两种情况都退回 deployless。
+ */
+async function callContract(
+  ctx: AggregateContext,
+  multicall: Multicall,
+  requests: CallRequest[],
+  overrides: CallOverrides,
+): Promise<RawResult[] | 'invalid' | 'reverted'> {
+  const calls = requests.map((req) => ({
+    target: req.ethBalanceOf ? multicall.address : req.target,
+    allowFailure: req.allowFailure,
+    callData: req.callData,
+  }))
+  let data: string
+  try {
+    data = await ctx.provider.call({
+      to: multicall.address,
+      data: multicall3Interface.encodeFunctionData('aggregate3', [calls]),
+      blockTag: overrides.blockTag,
+      from: overrides.from,
+    })
+  } catch (err) {
+    // aggregate3 自己的失败（allowFailure=false 的子调用失败）会带 "Multicall3: call failed" 的 revert 数据；
+    // 执行层面 revert 且没有数据，基本就是这个地址上不是 Multicall3。
+    // 限流、节点缺状态等错误 ethers 也会包装成 CALL_EXCEPTION，那些要原样抛出，不能把地址判成无效
+    if (isExecutionError(err) && !hasRevertData(err)) {
+      return 'reverted'
+    }
+    throw err
+  }
+  // 地址上没有代码时 eth_call 返回 0x
+  if (!data || data === '0x') {
+    return 'invalid'
+  }
+  try {
+    return decodeAggregate3(multicall3Interface.decodeFunctionResult('aggregate3', data)[0])
+  } catch {
+    return 'invalid'
+  }
+}
+
+/**
+ * deployless：字节码 + 构造参数作为合约创建 eth_call 发出。
+ * 主币余额（ethBalanceOf）也在合约里用 BALANCE 读取，和其他调用在同一次请求里。
+ *
+ * 合约创建受 EIP-3860 限制，initcode（字节码 + 参数）不能超过 48KB，这里按编码后的大小切片；
+ * 返回超过 24KB 的情况由合约改用 revert 带回，见 contracts/DeploylessMulticall3.sol。
+ */
+async function callDeployless(
+  ctx: AggregateContext,
+  requests: CallRequest[],
+  overrides: CallOverrides,
+): Promise<RawResult[]> {
+  const chunks = splitByInitcodeSize(requests)
+  const results = await Promise.all(chunks.map((chunk) => callDeploylessChunk(ctx, chunk, overrides)))
+  return results.flat()
+}
+
+async function callDeploylessChunk(
+  ctx: AggregateContext,
+  requests: CallRequest[],
+  overrides: CallOverrides,
+): Promise<RawResult[]> {
+  const args = AbiCoder.defaultAbiCoder().encode(
+    [CALL3_TUPLE],
+    [
+      requests.map(({ target, allowFailure, callData, ethBalanceOf }) => ({
+        target: ethBalanceOf ? MULTICALL3_ADDRESS : target,
+        allowFailure,
+        callData,
+      })),
+    ],
+  )
+  let data: string
+  try {
+    data = await ctx.provider.call({
+      data: concat([DEPLOYLESS_MULTICALL3_BYTECODE, args]),
+      blockTag: overrides.blockTag,
+      from: overrides.from,
+    })
+  } catch (err) {
+    const revertData = (err as { data?: string | null }).data
+    if (isError(err, 'CALL_EXCEPTION') && revertData?.startsWith(AGGREGATE3_RESULT_SELECTOR)) {
+      // 结果超过 24KB，合约通过 revert Aggregate3Result(...) 带回
+      return decodeAggregate3(AbiCoder.defaultAbiCoder().decode([RESULT_TUPLE], dataSlice(revertData, 4))[0])
+    }
+    // 有的钱包 / 中间层会丢掉 revert 数据，大结果拿不回来：对半拆开重试，小批量能正常 return
+    if (requests.length > 1 && isExecutionError(err) && !hasRevertData(err)) {
+      const mid = Math.ceil(requests.length / 2)
+      const [a, b] = await Promise.all([
+        callDeploylessChunk(ctx, requests.slice(0, mid), overrides),
+        callDeploylessChunk(ctx, requests.slice(mid), overrides),
+      ])
+      return [...a, ...b]
+    }
+    throw err
+  }
+  return decodeAggregate3(multicall3Interface.decodeFunctionResult('aggregate3', data)[0])
+}
+
+/** EIP-3860 initcode 上限 49152 字节，留出余量 */
+const MAX_INITCODE_SIZE = 48_000
+const BYTECODE_SIZE = (DEPLOYLESS_MULTICALL3_BYTECODE.length - 2) / 2
+
+function splitByInitcodeSize(requests: CallRequest[]): CallRequest[][] {
+  // 动态数组头 64 字节；每条 = 数组内偏移 32 + (target, allowFailure, bytes 偏移) 96 + bytes 长度 32 + 补齐后的数据
+  const budget = MAX_INITCODE_SIZE - BYTECODE_SIZE - 64
+  const chunks: CallRequest[][] = []
+  let current: CallRequest[] = []
+  let size = 0
+  for (const req of requests) {
+    const dataLength = (req.callData.length - 2) / 2
+    const itemSize = 160 + Math.ceil(dataLength / 32) * 32
+    if (current.length && size + itemSize > budget) {
+      chunks.push(current)
+      current = []
+      size = 0
+    }
+    current.push(req)
+    size += itemSize
+  }
+  if (current.length) {
+    chunks.push(current)
+  }
+  return chunks
+}
+
+function hasRevertData(err: unknown): boolean {
+  const data = (err as { data?: string | null }).data
+  return Boolean(data && data !== '0x')
+}
+
+function decodeAggregate3(raw: ReadonlyArray<readonly [boolean, string]>): RawResult[] {
+  return raw.map(([success, returnData]) => ({ success, returnData }))
+}
+
+function isUsable(chainId: number, multicall: Multicall, blockTag?: BlockTag): boolean {
+  if (unusableMulticalls.has(cacheKey(chainId, multicall.address))) {
+    return false
+  }
+  if (blockTag === 'earliest') {
+    return false
+  }
+  if (typeof blockTag === 'number' || typeof blockTag === 'bigint') {
+    return BigInt(multicall.block) < BigInt(blockTag)
+  }
+  if (typeof blockTag === 'string' && /^0x[0-9a-f]+$/i.test(blockTag)) {
+    return BigInt(multicall.block) < BigInt(blockTag)
+  }
+  return true
+}
+
+function isLatest(blockTag?: BlockTag): boolean {
+  return blockTag === undefined || blockTag === null || blockTag === 'latest' || blockTag === 'pending'
+}
+
+function cacheKey(chainId: number, address: string): string {
+  return `${chainId}:${address.toLowerCase()}`
+}
+
+/** 测试用：清掉“地址不可用”的缓存 */
+export function resetMulticallCache(): void {
+  unusableMulticalls.clear()
+}

package/src/batcher.ts

@@ -0,0 +1,126 @@
+import { decodeCall, encodeCall, type Call, type CallRequest, type RawResult } from './call.js'
+import type { CallOverrides } from './aggregate.js'
+import { CallFailedError } from './errors.js'
+
+export interface BatchOptions {
+  /** 收集窗口（毫秒），窗口内发起的 call 合并成一次 multicall。默认 0：同一事件循环 tick 内的调用合并 */
+  wait?: number
+  /** 队列达到这个数量立即发出，不再等窗口结束。默认 500 */
+  maxSize?: number
+}
+
+type Runner = (requests: CallRequest[], overrides: CallOverrides) => Promise<RawResult[]>
+
+interface Pending {
+  call: Call
+  resolve: (value: unknown) => void
+  reject: (reason: unknown) => void
+}
+
+interface Queue {
+  overrides: CallOverrides
+  entries: Pending[]
+  timer: ReturnType<typeof setTimeout> | null
+}
+
+/**
+ * DataLoader 式的自动合并：各处独立调用 `provider.call(x)`，
+ * 落在同一个收集窗口、且 blockTag/from 相同的调用会合成一次 aggregate3。
+ * 相同的 (target, callData) 只请求一次。
+ */
+export class Batcher {
+  readonly #run: Runner
+  readonly #wait: number
+  readonly #maxSize: number
+  readonly #queues = new Map<string, Queue>()
+
+  constructor(run: Runner, options: BatchOptions = {}) {
+    this.#run = run
+    this.#wait = options.wait ?? 0
+    this.#maxSize = Math.max(1, options.maxSize ?? 500)
+  }
+
+  load<T>(call: Call, overrides: CallOverrides = {}): Promise<T> {
+    const key = `${String(overrides.blockTag ?? 'latest')}|${overrides.from ?? ''}`
+    let queue = this.#queues.get(key)
+    if (!queue) {
+      queue = { overrides, entries: [], timer: null }
+      this.#queues.set(key, queue)
+    }
+    const promise = new Promise<T>((resolve, reject) => {
+      queue.entries.push({ call, resolve: resolve as (value: unknown) => void, reject })
+    })
+    if (queue.entries.length >= this.#maxSize) {
+      this.#flush(key)
+    } else if (!queue.timer) {
+      queue.timer = setTimeout(() => this.#flush(key), this.#wait)
+    }
+    return promise
+  }
+
+  #flush(key: string): void {
+    const queue = this.#queues.get(key)
+    if (!queue) {
+      return
+    }
+    this.#queues.delete(key)
+    if (queue.timer) {
+      clearTimeout(queue.timer)
+    }
+    void this.#dispatch(queue)
+  }
+
+  async #dispatch({ entries, overrides }: Queue): Promise<void> {
+    const requests: CallRequest[] = []
+    const indexByKey = new Map<string, number>()
+    const requestIndex: number[] = []
+
+    for (const entry of entries) {
+      let request: CallRequest
+      try {
+        request = encodeCall(entry.call, true)
+      } catch (err) {
+        entry.reject(err)
+        requestIndex.push(-1)
+        continue
+      }
+      const dedupeKey = `${request.ethBalanceOf ? 'eth' : request.target.toLowerCase()}|${request.callData}`
+      let index = indexByKey.get(dedupeKey)
+      if (index === undefined) {
+        index = requests.push(request) - 1
+        indexByKey.set(dedupeKey, index)
+      }
+      requestIndex.push(index)
+    }
+
+    if (requests.length === 0) {
+      return
+    }
+
+    let results: RawResult[]
+    try {
+      results = await this.#run(requests, overrides)
+    } catch (err) {
+      entries.forEach((entry, i) => requestIndex[i] !== -1 && entry.reject(err))
+      return
+    }
+
+    entries.forEach((entry, i) => {
+      const index = requestIndex[i] as number
+      if (index === -1) {
+        return
+      }
+      const result = results[index] as RawResult
+      if (!result.success) {
+        entry.reject(new CallFailedError(entry.call, result.returnData))
+        return
+      }
+      try {
+        entry.resolve(decodeCall(entry.call, result.returnData))
+      } catch (err) {
+        // 解码失败：多半是目标地址没有合约（返回空数据）
+        entry.reject(new CallFailedError(entry.call, result.returnData, err))
+      }
+    })
+  }
+}

package/src/call.ts

@@ -0,0 +1,144 @@
+import { FunctionFragment, Interface, getAddress, toBeHex, zeroPadValue, type JsonFragmentType, type ParamType, type Result } from 'ethers'
+
+import { isTronAddress, toEvmAddress } from './tron.js'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Params = any[]
+
+/**
+ * 一次只读调用的描述。结构与 ethcall 的 Call 保持一致，手工构造的 Call 也能直接用。
+ * 类型参数 T 是解码后的结果类型（仅用于类型推断，运行时不存在）。
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface Call<T = any> {
+  contract: {
+    address: string
+  }
+  name: string
+  inputs: readonly JsonFragmentType[]
+  outputs: readonly JsonFragmentType[]
+  params: Params
+  /**
+   * 调用自带的 overrides（`contract.method(...args, overrides)`）。
+   * blockTag / from 对 await 绑定 Call、provider.call、staticCall 生效；value / gasLimit 只对预执行生效。
+   * 传给 all / tryAll 时以批次的 overrides 为准（一批只能在同一个区块、同一个 from 下执行）。
+   */
+  overrides?: {
+    blockTag?: number | bigint | string
+    from?: string
+    value?: bigint | string | number
+    gasLimit?: bigint | string | number
+  }
+  /** 内部标记：原生币余额查询（见 Provider.getEthBalance） */
+  kind?: 'ethBalance'
+  /** 仅用于类型推断 */
+  readonly __result?: T
+}
+
+/** 绑定了 Provider 的 Call：可以直接 await（自动合并成 multicall），也可以照常传给 all / tryAll */
+export type BoundCall<T = any> = Call<T> & PromiseLike<T>
+
+export interface FailableCall extends Call {
+  canFail: boolean
+}
+
+/** multicall 返回的单条原始结果 */
+export interface RawResult {
+  success: boolean
+  returnData: string
+}
+
+/** 发给 aggregate3 前的单条请求 */
+export interface CallRequest {
+  target: string
+  allowFailure: boolean
+  callData: string
+  /** 原生币余额查询：有 multicall 合约时走 getEthBalance，deployless 时改走 eth_getBalance */
+  ethBalanceOf?: string
+}
+
+// inputs → name → outputs → Interface。同一份 ABI 生成的 Call 共享 inputs/outputs 数组（见 contract.ts 的 ABI 缓存），
+// 按引用缓存，避免每条 Call 都重新解析；三者都参与 key，手工构造的 Call 共用数组时也不会串
+const interfaceCache = new WeakMap<readonly JsonFragmentType[], Map<string, WeakMap<readonly JsonFragmentType[], Interface>>>()
+
+function getInterface(call: Call): Interface {
+  let byName = interfaceCache.get(call.inputs)
+  if (!byName) {
+    byName = new Map()
+    interfaceCache.set(call.inputs, byName)
+  }
+  let byOutputs = byName.get(call.name)
+  if (!byOutputs) {
+    byOutputs = new WeakMap()
+    byName.set(call.name, byOutputs)
+  }
+  let iface = byOutputs.get(call.outputs)
+  if (!iface) {
+    const fragment = FunctionFragment.from({
+      type: 'function',
+      name: call.name,
+      inputs: call.inputs,
+      outputs: call.outputs,
+      stateMutability: 'view',
+    })
+    iface = new Interface([fragment])
+    byOutputs.set(call.outputs, iface)
+  }
+  return iface
+}
+
+export function encodeCall(call: Call, allowFailure: boolean): CallRequest {
+  const iface = getInterface(call)
+  const fragment = iface.fragments[0] as FunctionFragment
+  const params = normalizeAddresses(fragment, call.params)
+  return {
+    target: getAddress(toEvmAddress(call.contract.address)),
+    allowFailure,
+    callData: iface.encodeFunctionData(fragment, params),
+    ethBalanceOf: call.kind === 'ethBalance' ? toEvmAddress(params[0] as string) : undefined,
+  }
+}
+
+// Tron 的 T 开头地址在 ABI 里就是去掉 0x41 前缀的 20 字节，这里统一转成 0x 形式再编码
+function normalizeAddresses(fragment: FunctionFragment, params: Params): Params {
+  if (params.length !== fragment.inputs.length) {
+    // 参数个数不对交给 ethers 报错（overrides 不在 params 里，见 Provider.staticCall）
+    return params
+  }
+  return fragment.inputs.map((input, i) => normalizeValue(input, params[i]))
+}
+
+// ethers 的 ParamType.walk 不接受对象形式的 struct，这里自己递归
+function normalizeValue(type: ParamType, value: unknown): unknown {
+  if (type.baseType === 'address') {
+    return isTronAddress(value) ? toEvmAddress(value as string) : value
+  }
+  if (type.isArray() && Array.isArray(value)) {
+    return value.map((v) => normalizeValue(type.arrayChildren, v))
+  }
+  if (type.isTuple() && value !== null && typeof value === 'object') {
+    if (Array.isArray(value)) {
+      return value.map((v, i) => (type.components[i] ? normalizeValue(type.components[i], v) : v))
+    }
+    const out: Record<string, unknown> = { ...value }
+    for (const component of type.components) {
+      if (component.name in out) {
+        out[component.name] = normalizeValue(component, out[component.name])
+      }
+    }
+    return out
+  }
+  return value
+}
+
+/** 单返回值直接返回该值，多返回值返回 ethers Result（可按下标或名字取） */
+export function decodeCall<T>(call: Call, returnData: string): T {
+  const iface = getInterface(call)
+  const fragment = iface.fragments[0] as FunctionFragment
+  const result: Result = iface.decodeFunctionResult(fragment, returnData)
+  return (call.outputs.length === 1 ? result[0] : result) as T
+}
+
+export function encodeUint256(value: bigint): string {
+  return zeroPadValue(toBeHex(value), 32)
+}

package/src/contract.ts

@@ -0,0 +1,145 @@
+import { Interface, type FunctionFragment, type InterfaceAbi, type JsonFragment, type JsonFragmentType } from 'ethers'
+
+import type { BoundCall, Call, Params } from './call.js'
+
+export type ContractAbi = InterfaceAbi | Interface
+
+/** 绑定后执行 Call 的对象（即 Provider），避免 contract ⇄ provider 循环依赖 */
+export interface ContractRunner {
+  call(call: Call): Promise<any>
+  staticCall(call: Call): Promise<any>
+}
+
+/** 绑定合约上的方法：调用得到可 await 的 Call，`.staticCall(...)` 预执行 */
+export interface BoundMethod<T = any> {
+  (...params: Params): BoundCall<T>
+  /** 预执行（直接 eth_call，可在最后一个参数传 { from, value, gasLimit, blockTag }） */
+  staticCall(...params: Params): Promise<T>
+}
+
+/**
+ * 生成 Call 的合约包装，用法与 ethcall 的 Contract 一致：
+ *
+ * ```ts
+ * const erc20 = new Contract(token, ['function balanceOf(address) view returns (uint256)'])
+ * erc20.balanceOf(user) // => Call
+ * ```
+ *
+ * 传入 runner（或用 `provider.contract(address, abi)`）得到绑定合约：
+ *
+ * ```ts
+ * const usdt = multi.contract(token, ERC20_ABI)
+ * const balance = await usdt.balanceOf(user)          // 同一 tick 内的调用自动合并成一次 multicall
+ * const out = await router.swap.staticCall(params, { value, from }) // 预执行，写法同 ethers
+ * ```
+ *
+ * 与 ethcall 的差异：
+ * - ABI 直接支持人类可读字符串 / JSON / ethers Interface，不需要再 abiToJson 一遍
+ * - 暴露 ABI 里的所有函数（不只 view/pure），可以用来模拟 nonpayable 的报价函数（如 Uniswap V3 Quoter）
+ * - 重载函数可以用完整签名取：`contract['getAmount(uint256,address)'](...)`
+ */
+export class Contract {
+  readonly #address: string
+  readonly #runner: ContractRunner | undefined;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [method: string]: any
+
+  constructor(address: string, abi: ContractAbi, runner?: ContractRunner) {
+    this.#address = address
+    this.#runner = runner
+    for (const fn of parseAbi(abi)) {
+      const method = this.#makeMethod(fn)
+      for (const key of fn.keys) {
+        if (key in this) {
+          continue
+        }
+        Object.defineProperty(this, key, { enumerable: true, value: method, writable: false })
+      }
+    }
+  }
+
+  get address(): string {
+    return this.#address
+  }
+
+  #makeMethod({ name, inputs, outputs }: ParsedFunction) {
+    const address = this.#address
+    const runner = this.#runner
+
+    const build = (params: Params): Call => {
+      // 与 ethers 一致：多出来的最后一个参数是 overrides，如 router.swap(params, { value })
+      if (params.length === inputs.length + 1 && isPlainObject(params[params.length - 1])) {
+        const overrides = params[params.length - 1] as Call['overrides']
+        return { contract: { address }, name, inputs, outputs, params: params.slice(0, -1), overrides }
+      }
+      return { contract: { address }, name, inputs, outputs, params }
+    }
+
+    if (!runner) {
+      return (...params: Params): Call => build(params)
+    }
+
+    const method = (...params: Params): BoundCall => bindCall(build(params), runner)
+    Object.defineProperty(method, 'staticCall', {
+      value: (...params: Params) => runner.staticCall(build(params)),
+    })
+    return method
+  }
+}
+
+interface ParsedFunction {
+  /** 挂到 Contract 上的属性名：完整签名，以及不重载时的函数名 */
+  keys: string[]
+  name: string
+  inputs: readonly JsonFragmentType[]
+  outputs: readonly JsonFragmentType[]
+}
+
+// 按 ABI 对象（数组 / Interface）缓存解析结果：循环里 new Contract(token, ERC20ABI) 只解析一次，
+// 生成的 Call 共享 inputs/outputs 数组，call.ts 的 Interface 缓存才能命中
+const abiCache = new WeakMap<object, ParsedFunction[]>()
+
+function parseAbi(abi: ContractAbi): ParsedFunction[] {
+  const cacheable = typeof abi === 'object' && abi !== null
+  const cached = cacheable ? abiCache.get(abi) : undefined
+  if (cached) {
+    return cached
+  }
+  const iface = abi instanceof Interface ? abi : new Interface(abi)
+  const fragments: FunctionFragment[] = []
+  iface.forEachFunction((fn) => fragments.push(fn))
+  const counts = new Map<string, number>()
+  fragments.forEach((fn) => counts.set(fn.name, (counts.get(fn.name) ?? 0) + 1))
+  const parsed = fragments.map((fn) => {
+    const json = JSON.parse(fn.format('json')) as JsonFragment
+    return {
+      keys: counts.get(fn.name) === 1 ? [fn.format('sighash'), fn.name] : [fn.format('sighash')],
+      name: fn.name,
+      inputs: json.inputs ?? [],
+      outputs: json.outputs ?? [],
+    }
+  })
+  if (cacheable) {
+    abiCache.set(abi, parsed)
+  }
+  return parsed
+}
+
+/** 给 Call 加上不可枚举的 then：第一次 await 时才发请求（交给 runner.call 自动合并），结果复用 */
+export function bindCall<T>(call: Call<T>, runner: ContractRunner): BoundCall<T> {
+  let promise: Promise<T> | undefined
+  Object.defineProperty(call, 'then', {
+    enumerable: false,
+    value: (onFulfilled?: (value: T) => unknown, onRejected?: (reason: unknown) => unknown) => {
+      promise ??= runner.call(call)
+      return promise.then(onFulfilled, onRejected)
+    },
+  })
+  return call as BoundCall<T>
+}
+
+function isPlainObject(value: unknown): boolean {
+  return value !== null && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype
+}
+
+export default Contract

package/src/deployless.ts

@@ -0,0 +1,5 @@
+// 由 scripts/build-contracts.mjs 生成，不要手改。源码：contracts/DeploylessMulticall3.sol（solc 0.8.30+commit.73712a01.Emscripten.clang）
+
+/** constructor((address target, bool allowFailure, bytes callData)[] calls) — 以 aggregate3 的返回格式带回结果 */
+export const DEPLOYLESS_MULTICALL3_BYTECODE =
+  '0x608060405260405161060f38038061060f8339810160408190526100229161036c565b80516000816001600160401b0381111561003e5761003e6102da565b60405190808252806020026020018201604052801561008457816020015b60408051808201909152600081526060602082015281526020019060019003908161005c5790505b50905060005b828110156102875760008482815181106100a6576100a6610507565b602090810291909101015160408101518151919250906001600160a01b031673ca11bde05977b3631167028862be2a173976ca111480156100e8575080516024145b801561010c5750631348c07360e21b6101008261051d565b6001600160e01b031916145b1561017e5760248101516040805180820182526001815290516001600160a01b039290921691602080830191610149918531910190815260200190565b60405160208183030381529060405281525085858151811061016d5761016d610507565b60200260200101819052505061027d565b60008083600001516001600160a01b03168360405161019d919061055b565b6000604051808303816000865af19150503d80600081146101da576040519150601f19603f3d011682016040523d82523d6000602084013e6101df565b606091505b5091509150811580156101f457508360200151155b156102465760405162461bcd60e51b815260206004820152601760248201527f4d756c746963616c6c333a2063616c6c206661696c656400000000000000000060448201526064015b60405180910390fd5b604051806040016040528083151581526020018281525086868151811061026f5761026f610507565b602002602001018190525050505b505060010161008a565b5060008160405160200161029b9190610577565b6040516020818303038152906040529050616000815111156102d25781604051633649f05160e01b815260040161023d9190610577565b805160208201f35b634e487b7160e01b600052604160045260246000fd5b604051606081016001600160401b0381118282101715610312576103126102da565b60405290565b604051601f8201601f191681016001600160401b0381118282101715610340576103406102da565b604052919050565b60005b8381101561036357818101518382015260200161034b565b50506000910152565b60006020828403121561037e57600080fd5b81516001600160401b0381111561039457600080fd5b8201601f810184136103a557600080fd5b80516001600160401b038111156103be576103be6102da565b8060051b6103ce60208201610318565b918252602081840181019290810190878411156103ea57600080fd5b6020850192505b838310156104fc5782516001600160401b0381111561040f57600080fd5b85016060818a03601f1901121561042557600080fd5b61042d6102f0565b60208201516001600160a01b038116811461044757600080fd5b81526040820151801515811461045c57600080fd5b602082015260608201516001600160401b0381111561047a57600080fd5b60208184010192505089601f83011261049257600080fd5b81516001600160401b038111156104ab576104ab6102da565b6104be601f8201601f1916602001610318565b8181528b60208386010111156104d357600080fd5b6104e4826020830160208701610348565b604083015250835250602092830192909101906103f1565b979650505050505050565b634e487b7160e01b600052603260045260246000fd5b805160208201516001600160e01b0319811691906004821015610554576001600160e01b0319600483900360031b81901b82161692505b5050919050565b6000825161056d818460208701610348565b9190910192915050565b6000602082016020835280845180835260408501915060408160051b86010192506020860160005b8281101561060257603f198786030184528151805115158652602081015190506040602087015280518060408801526105df816060890160208501610348565b601f01601f1916959095016060019450602093840193919091019060010161059f565b5092969550505050505056fe'