@w3lib/evm-batch-call 0.1.0

package/src/erc20.ts

@@ -0,0 +1,43 @@
+import type { BoundCall } from './call.js'
+import type { BoundMethod, Contract } from './contract.js'
+
+export const ERC20_ABI = [
+  'function name() view returns (string)',
+  'function symbol() view returns (string)',
+  'function decimals() view returns (uint8)',
+  'function totalSupply() view returns (uint256)',
+  'function balanceOf(address owner) view returns (uint256)',
+  'function allowance(address owner, address spender) view returns (uint256)',
+  'function approve(address spender, uint256 amount) returns (bool)',
+  'function transfer(address to, uint256 amount) returns (bool)',
+  'function transferFrom(address from, address to, uint256 amount) returns (bool)',
+] as const
+
+type Method<Args extends unknown[], T> = ((...params: Args) => BoundCall<T>) & Pick<BoundMethod<T>, 'staticCall'>
+
+/** `provider.erc20(address)` 返回的绑定合约（带结果类型） */
+export interface Erc20Contract extends Contract {
+  name: Method<[], string>
+  symbol: Method<[], string>
+  decimals: Method<[], bigint>
+  totalSupply: Method<[], bigint>
+  balanceOf: Method<[owner: string], bigint>
+  allowance: Method<[owner: string, spender: string], bigint>
+  approve: Method<[spender: string, amount: bigint | string | number], boolean>
+  transfer: Method<[to: string, amount: bigint | string | number], boolean>
+  transferFrom: Method<[from: string, to: string, amount: bigint | string | number], boolean>
+}
+
+export interface TokenInfo {
+  address: string
+  /** 读取失败（如 symbol 是 bytes32 的老代币）时为 null */
+  symbol: string | null
+  name: string | null
+  decimals: number
+}
+
+/** 常见的主币占位地址：多数聚合器用 0xeeee…eeee，部分协议用零地址 */
+export const DEFAULT_NATIVE_TOKENS: readonly string[] = [
+  '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
+  '0x0000000000000000000000000000000000000000',
+]

package/src/errors.ts

@@ -0,0 +1,66 @@
+import { Interface, isError } from 'ethers'
+
+import type { Call } from './call.js'
+
+const errorInterface = new Interface(['error Error(string)', 'error Panic(uint256)'])
+
+/** 自动合并模式下，单条调用失败时 reject 的错误 */
+export class CallFailedError extends Error {
+  readonly call: Call
+  /** revert 原始数据 */
+  readonly returnData: string
+  /** 能解析出来的 revert 原因（Error(string) / Panic(uint256)） */
+  readonly reason: string | null
+
+  constructor(call: Call, returnData: string, cause?: unknown) {
+    const reason = decodeRevertReason(returnData)
+    super(
+      `${call.name} call to ${call.contract.address} failed${reason ? `: ${reason}` : ''}`,
+      cause === undefined ? undefined : { cause },
+    )
+    this.name = 'CallFailedError'
+    this.call = call
+    this.returnData = returnData
+    this.reason = reason
+  }
+}
+
+// 最后一项是 TronProvider 对交易校验失败（CONTRACT_VALIDATE_ERROR 等）抛出的错误
+const EXECUTION_ERROR_RE =
+  /revert|max (init)?code size|out of gas|invalid opcode|stack (underflow|overflow)|invalid jump|^CONTRACT_[A-Z_]+_ERROR:/i
+
+/**
+ * eth_call 的失败是否是 EVM 执行层面的确定性结果（revert、代码大小超限等），而不是节点/网络问题。
+ *
+ * ethers 会把 eth_call 返回的**任何** JSON-RPC 错误都包装成 CALL_EXCEPTION（"missing revert data"），
+ * 包括限流（-32005）、header not found、非归档节点缺状态等，所以不能只看错误码：
+ * 有 revert 数据，或节点原始错误信息是执行错误，才算确定性失败；其余换节点重试可能会成功。
+ */
+export function isExecutionError(err: unknown): boolean {
+  if (!isError(err, 'CALL_EXCEPTION')) {
+    return false
+  }
+  if (err.data && err.data !== '0x') {
+    return true
+  }
+  const info = err.info as { error?: { message?: unknown } } | undefined
+  const raw = info?.error?.message
+  // 没有节点原始信息时（如 TronProvider 自己抛的）看 shortMessage；ethers 的 "missing revert data" 不算
+  const message = typeof raw === 'string' ? raw : err.shortMessage === 'missing revert data' ? '' : err.shortMessage
+  return EXECUTION_ERROR_RE.test(message ?? '')
+}
+
+export function decodeRevertReason(data: string): string | null {
+  if (!data || data === '0x') {
+    return null
+  }
+  try {
+    const parsed = errorInterface.parseError(data)
+    if (!parsed) {
+      return null
+    }
+    return parsed.name === 'Panic' ? `Panic(${parsed.args[0]})` : String(parsed.args[0])
+  } catch {
+    return null
+  }
+}

package/src/fallback.ts

@@ -0,0 +1,105 @@
+import { isError, type TransactionRequest } from 'ethers'
+
+import type { EthersLikeProvider } from './aggregate.js'
+import { isExecutionError } from './errors.js'
+
+export interface FallbackOptions {
+  /** 单个节点单次请求超时（毫秒），超时视为该节点故障并换下一个。默认 10000；<= 0 表示不限制 */
+  timeout?: number
+  /** 节点出错后跳过它的时长（毫秒），期间优先用其他节点。默认 30000 */
+  cooldown?: number
+}
+
+/**
+ * 多节点故障切换：按顺序使用节点，出错或超时换下一个；出错的节点在 cooldown 内排到最后。
+ *
+ * 与 ethers FallbackProvider 相比：
+ * - 没有首次请求前对所有节点的 getBlockNumber 同步，一个卡住的节点不会拖住第一次查询
+ * - 合约 revert 等确定性结果直接返回，不会拿去别的节点重试
+ */
+export class FallbackRpc implements EthersLikeProvider {
+  readonly #nodes: EthersLikeProvider[]
+  readonly #timeout: number
+  readonly #cooldown: number
+  readonly #failedAt: number[]
+
+  constructor(nodes: EthersLikeProvider[], options: FallbackOptions = {}) {
+    if (!nodes.length) {
+      throw new Error('FallbackRpc requires at least one node')
+    }
+    this.#nodes = nodes
+    this.#timeout = options.timeout ?? 10_000
+    this.#cooldown = options.cooldown ?? 30_000
+    this.#failedAt = nodes.map(() => 0)
+  }
+
+  get nodes(): readonly EthersLikeProvider[] {
+    return this.#nodes
+  }
+
+  call(tx: TransactionRequest): Promise<string> {
+    return this.#run((node) => node.call(tx))
+  }
+
+  getBalance(address: Parameters<EthersLikeProvider['getBalance']>[0], blockTag?: Parameters<EthersLikeProvider['getBalance']>[1]): Promise<bigint> {
+    return this.#run((node) => node.getBalance(address, blockTag))
+  }
+
+  async #run<T>(fn: (node: EthersLikeProvider) => Promise<T>): Promise<T> {
+    let lastError: unknown
+    for (const index of this.#order()) {
+      try {
+        const result = await withTimeout(fn(this.#nodes[index] as EthersLikeProvider), this.#timeout)
+        this.#failedAt[index] = 0
+        return result
+      } catch (err) {
+        if (isDeterministic(err)) {
+          throw err
+        }
+        this.#failedAt[index] = Date.now()
+        lastError = err
+      }
+    }
+    throw lastError
+  }
+
+  /** 健康的节点按原顺序在前，冷却中的按出错时间先后排在后面（全挂时也都会再试一次） */
+  #order(): number[] {
+    const now = Date.now()
+    const healthy: number[] = []
+    const cooling: number[] = []
+    this.#failedAt.forEach((at, i) => (at && now - at < this.#cooldown ? cooling : healthy).push(i))
+    cooling.sort((a, b) => (this.#failedAt[a] as number) - (this.#failedAt[b] as number))
+    return [...healthy, ...cooling]
+  }
+}
+
+/** 换节点也不会变的错误：合约执行结果、参数错误、用户拒绝等 */
+function isDeterministic(err: unknown): boolean {
+  return (
+    isExecutionError(err) ||
+    isError(err, 'INVALID_ARGUMENT') ||
+    isError(err, 'ACTION_REJECTED') ||
+    isError(err, 'NUMERIC_FAULT')
+  )
+}
+
+class TimeoutError extends Error {
+  constructor(ms: number) {
+    super(`RPC request timed out after ${ms}ms`)
+    this.name = 'TimeoutError'
+  }
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  if (!Number.isFinite(ms) || ms <= 0) {
+    return promise
+  }
+  let timer: ReturnType<typeof setTimeout>
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new TimeoutError(ms)), ms)
+    }),
+  ]).finally(() => clearTimeout(timer))
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+export { Contract, bindCall, type BoundMethod, type ContractAbi, type ContractRunner } from './contract.js'
+export { DEFAULT_NATIVE_TOKENS, ERC20_ABI, type Erc20Contract, type TokenInfo } from './erc20.js'
+export {
+  Provider,
+  type ProviderConfig,
+  type CallInput,
+  type CallResults,
+  type ProviderSource,
+  type TryCallResults,
+  type StaticCallItem,
+  type StaticCallOverrides,
+  type StaticCallResult,
+} from './provider.js'
+export {
+  TRON_CHAIN_ID,
+  TronProvider,
+  isTronAddress,
+  toEvmAddress,
+  toTronAddress,
+  type TronProviderOptions,
+  type TronRequest,
+  type TronWebLike,
+} from './tron.js'
+export { CallFailedError, decodeRevertReason, isExecutionError } from './errors.js'
+export { FallbackRpc, type FallbackOptions } from './fallback.js'
+export { getDefaultRpcUrls, isTronChain, type SourceOptions } from './source.js'
+export { DEFAULT_RPC_URLS, DEFAULT_TRON_HOSTS } from './rpcNodes.js'
+export { MULTICALL3_ADDRESS, getMulticall3, type Multicall } from './multicall.js'
+export type { BlockTag, CallOverrides, EthersLikeProvider } from './aggregate.js'
+export type { BatchOptions } from './batcher.js'
+export type { BoundCall, Call, FailableCall, Params, RawResult } from './call.js'

package/src/multicall.ts

@@ -0,0 +1,60 @@
+/**
+ * Multicall3 部署地址表，来自 ethcall (MIT, https://github.com/Destiner/ethcall)，另补充了 Tron。
+ * 表里没有的链（或地址在该链上无效）会自动走 deployless（见 contracts/DeploylessMulticall3.sol），
+ * 不需要链上部署任何合约。
+ */
+
+export interface Multicall {
+  address: string
+  /** 合约部署所在区块；查询更早的区块时改走 deployless */
+  block: number
+}
+
+export const MULTICALL3_ADDRESS = '0xcA11bde05977b3631167028862bE2a173976CA11'
+
+const CANONICAL = MULTICALL3_ADDRESS
+
+const MULTICALL3: Record<number, Multicall> = {
+  1: { address: CANONICAL, block: 14353601 },
+  3: { address: CANONICAL, block: 12063863 },
+  4: { address: CANONICAL, block: 10299530 },
+  5: { address: CANONICAL, block: 6507670 },
+  10: { address: CANONICAL, block: 4286263 },
+  14: { address: CANONICAL, block: 3002461 },
+  16: { address: CANONICAL, block: 276388 },
+  19: { address: CANONICAL, block: 13382504 },
+  42: { address: CANONICAL, block: 30285908 },
+  56: { address: CANONICAL, block: 15921452 },
+  69: { address: CANONICAL, block: 1418387 },
+  97: { address: CANONICAL, block: 17422483 },
+  100: { address: CANONICAL, block: 21022491 },
+  114: { address: CANONICAL, block: 508735 },
+  137: { address: CANONICAL, block: 25770160 },
+  196: { address: CANONICAL, block: 47416 },
+  250: { address: CANONICAL, block: 33001987 },
+  252: { address: CANONICAL, block: 0 },
+  324: { address: '0x413fEb613604D46586c22801949A5b88b224c260', block: 9531414 },
+  420: { address: CANONICAL, block: 49461 },
+  1284: { address: CANONICAL, block: 609002 },
+  1285: { address: CANONICAL, block: 1597904 },
+  1287: { address: CANONICAL, block: 1850686 },
+  2222: { address: '0x1578f6d2D3168acF41b506AA666A521994F6BAB6', block: 1176602 },
+  4002: { address: CANONICAL, block: 8328688 },
+  8453: { address: CANONICAL, block: 5022 },
+  42161: { address: CANONICAL, block: 7654707 },
+  42220: { address: CANONICAL, block: 13112599 },
+  43113: { address: CANONICAL, block: 7096959 },
+  43114: { address: CANONICAL, block: 11907934 },
+  80001: { address: CANONICAL, block: 25444704 },
+  421611: { address: CANONICAL, block: 10228837 },
+  5000: { address: '0xd77b59d4cb13bea71f3cc093e401720867355d6e', block: 18877383 },
+  1666600000: { address: CANONICAL, block: 24185753 },
+  73927: { address: '0x138A85647768815078DF1dD85C6121e611381A0b', block: 14080843 },
+  // Tron 主网 TEazPvZwDjDtFeJupyo7QunvnrnUjPH8ED（链上合约名 Multicall3，2026-10 实测）
+  728126428: { address: '0x32a4f47a74a6810bd0bf861cabab99656a75de9e', block: 0 },
+  81457: { address: '0x23928c6f823e0d78eadc9d2f69ace652ff3cdcb1', block: 368182 },
+}
+
+export function getMulticall3(chainId: number): Multicall | null {
+  return MULTICALL3[chainId] ?? null
+}

package/src/provider.ts

@@ -0,0 +1,352 @@
+import { type BigNumberish } from 'ethers'
+
+import { aggregate, type AggregateContext, type BlockTag, type CallOverrides, type EthersLikeProvider } from './aggregate.js'
+import { Batcher, type BatchOptions } from './batcher.js'
+import { decodeCall, encodeCall, type BoundCall, type Call, type CallRequest, type FailableCall, type RawResult } from './call.js'
+import { Contract, bindCall, type ContractAbi, type ContractRunner } from './contract.js'
+import { DEFAULT_NATIVE_TOKENS, ERC20_ABI, type Erc20Contract, type TokenInfo } from './erc20.js'
+import { CallFailedError, isExecutionError } from './errors.js'
+import { MULTICALL3_ADDRESS, getMulticall3, type Multicall } from './multicall.js'
+import { resolveSource, type ProviderSource, type SourceOptions } from './source.js'
+
+export type { ProviderSource }
+
+export interface StaticCallOverrides extends CallOverrides {
+  value?: BigNumberish
+  gasLimit?: BigNumberish
+}
+
+export interface StaticCallItem {
+  call: Call
+  overrides?: StaticCallOverrides
+}
+
+export type StaticCallResult<T> = { success: true; data: T } | { success: false; error: Error }
+
+/** all / tryAll 的输入：Call 数组，或 { 名字: Call } 对象 */
+export type CallInput = readonly Call[] | Readonly<Record<string, Call>>
+
+type ResultOf<C> = C extends Call<infer R> ? R : any
+/** 与输入同构的结果：数组 → 数组（元组保留各项类型），对象 → 同名字段 */
+export type CallResults<C> = { -readonly [K in keyof C]: ResultOf<C[K]> }
+export type TryCallResults<C> = { -readonly [K in keyof C]: ResultOf<C[K]> | null }
+
+export interface ProviderConfig extends SourceOptions {
+  /** 自定义 Multicall3 地址；不填则查内置地址表，表里没有就走 deployless */
+  multicall?: Partial<Multicall>
+  /** 强制走 deployless（不依赖链上 multicall 合约） */
+  deployless?: boolean
+  /** 单次 eth_call 最多打包的调用数，超出自动拆分并发请求。默认 500 */
+  chunkSize?: number
+  /** `provider.call()` 自动合并的参数 */
+  batch?: BatchOptions
+  /** `balances()` 里视为主币的地址，默认 0xeeee…eeee 和零地址 */
+  nativeTokens?: readonly string[]
+}
+
+const ETH_BALANCE_INPUTS = [{ name: 'addr', type: 'address' }] as const
+const ETH_BALANCE_OUTPUTS = [{ name: 'balance', type: 'uint256' }] as const
+
+/**
+ * Multicall Provider，API 与 ethcall 的 Provider 保持一致：
+ *
+ * ```ts
+ * const multi = new Provider(chainId, ethersProvider)
+ * const [symbol, decimals] = await multi.all([erc20.symbol(), erc20.decimals()])
+ * ```
+ */
+export class Provider implements ContractRunner {
+  readonly #ctx: AggregateContext
+  readonly #batcher: Batcher
+  readonly #nativeTokens: Set<string>
+
+  /**
+   * @param chainId 链 ID（接受数字字符串）
+   * @param provider 节点：RPC URL、ethers Provider、钱包（window.ethereum / tronWeb）或它们的数组（主节点 + 备用节点）。
+   *   不传则使用内置的公共节点表
+   * @param config 可选配置
+   */
+  constructor(chainId: number | string, provider?: ProviderSource | readonly ProviderSource[], config: ProviderConfig = {}) {
+    const id = Number(chainId)
+    this.#ctx = {
+      provider: resolveSource(id, provider, config),
+      chainId: id,
+      multicall: config.deployless ? null : resolveMulticall(id, config.multicall),
+      chunkSize: config.chunkSize ?? 500,
+    }
+    this.#batcher = new Batcher((requests, overrides) => this.#aggregate(requests, overrides), config.batch)
+    this.#nativeTokens = new Set((config.nativeTokens ?? DEFAULT_NATIVE_TOKENS).map((t) => t.toLowerCase()))
+  }
+
+  /**
+   * 绑定到本 Provider 的合约：方法返回的 Call 可以直接 await（自动合并成 multicall），
+   * 也可以传给 all / tryAll；`method.staticCall(...)` 预执行。
+   *
+   * ```ts
+   * const pair = multi.contract(pairAddress, PAIR_ABI)
+   * const [reserves, token0] = await Promise.all([pair.getReserves(), pair.token0()]) // 一次请求
+   * ```
+   */
+  contract(address: string, abi: ContractAbi): Contract {
+    return new Contract(address, abi, this)
+  }
+
+  /** 绑定的 ERC20 合约（内置 ABI，结果带类型） */
+  erc20(address: string): Erc20Contract {
+    return new Contract(address, ERC20_ABI as unknown as string[], this) as Erc20Contract
+  }
+
+  /**
+   * 批量查余额，主币和代币混在一起、一次请求。主币地址见 config.nativeTokens。
+   * 查询失败（非合约地址、非法地址等）的位置为 0n；需要区分失败请用 tryAll。
+   */
+  async balances(owner: string, tokens: readonly string[], overrides?: CallOverrides): Promise<bigint[]> {
+    const calls = tokens.map((token) =>
+      this.#nativeTokens.has(token.toLowerCase()) ? this.getEthBalance(owner) : this.erc20(token).balanceOf(owner),
+    )
+    const results = await this.tryAll<bigint>(calls, overrides)
+    return results.map((balance) => balance ?? 0n)
+  }
+
+  /**
+   * 批量查代币信息（symbol / name / decimals），一次请求。
+   * decimals 读不到（非代币合约、主币占位地址等）的位置为 null。
+   */
+  async tokenInfo(tokens: readonly string[], overrides?: CallOverrides): Promise<(TokenInfo | null)[]> {
+    // 主币占位地址不是合约，不发请求
+    const targets = tokens.filter((token) => !this.#nativeTokens.has(token.toLowerCase()))
+    const calls = targets.flatMap((token) => {
+      const erc20 = this.erc20(token)
+      return [erc20.symbol(), erc20.name(), erc20.decimals()]
+    })
+    const results = calls.length ? await this.tryAll(calls, overrides) : []
+    const infoByToken = new Map<string, TokenInfo | null>()
+    targets.forEach((address, i) => {
+      const decimals = results[i * 3 + 2] as bigint | null
+      infoByToken.set(
+        address,
+        decimals === null
+          ? null
+          : {
+              address,
+              symbol: (results[i * 3] as string | null) ?? null,
+              name: (results[i * 3 + 1] as string | null) ?? null,
+              decimals: Number(decimals),
+            },
+      )
+    })
+    return tokens.map((token) => infoByToken.get(token) ?? null)
+  }
+
+  /**
+   * 主币余额查询，可以和合约调用放在同一批里（同一次 eth_call）：
+   * 有 Multicall3 时调合约的 getEthBalance；deployless 时由 deployless 合约直接用 BALANCE 读取。
+   */
+  getEthBalance(address: string): BoundCall<bigint> {
+    const call: Call<bigint> = {
+      contract: { address: this.#ctx.multicall?.address ?? MULTICALL3_ADDRESS },
+      name: 'getEthBalance',
+      inputs: ETH_BALANCE_INPUTS,
+      outputs: ETH_BALANCE_OUTPUTS,
+      params: [address],
+      kind: 'ethBalance',
+    }
+    return bindCall(call, this)
+  }
+
+  /**
+   * 合并成一次调用，任意一条失败则整体抛错。
+   * 可以传数组（结果顺序一致），也可以传 `{ 名字: Call }` 对象（结果是同名字段）。
+   */
+  all<const C extends CallInput>(calls: C, overrides?: CallOverrides): Promise<CallResults<C>>
+  all<T = any>(calls: readonly Call[], overrides?: CallOverrides): Promise<T[]>
+  async all(calls: CallInput, overrides?: CallOverrides): Promise<unknown> {
+    const [list, pack] = unpack(calls)
+    const results = await this.#aggregate(list.map((call) => encodeCall(call, false)), overrides)
+    return pack(list.map((call, i) => decodeCall(call, (results[i] as RawResult).returnData)))
+  }
+
+  /**
+   * 合并成一次调用，失败（revert、解码失败、参数编码失败如非法地址）的位置返回 null。
+   * 与 all 一样支持数组或对象。
+   */
+  tryAll<const C extends CallInput>(calls: C, overrides?: CallOverrides): Promise<TryCallResults<C>>
+  tryAll<T = any>(calls: readonly Call[], overrides?: CallOverrides): Promise<(T | null)[]>
+  async tryAll(calls: CallInput, overrides?: CallOverrides): Promise<unknown> {
+    const [list, pack] = unpack(calls)
+    return pack(await this.tryEach(list, list.map(() => true), overrides))
+  }
+
+  /**
+   * 逐条指定是否允许失败：允许失败的位置返回 null，不允许失败的一旦失败整体抛错。
+   */
+  async tryEach<T = any>(calls: readonly Call[], canFail: readonly boolean[], overrides?: CallOverrides): Promise<(T | null)[]> {
+    // 允许失败的条目编码出错（如后端给的脏地址）只让该条为 null，不拖垮整批
+    const requests: Array<CallRequest | null> = calls.map((call, i) => {
+      const callCanFail = canFail[i]
+      if (callCanFail === undefined) {
+        throw new Error('Unable to access the canFail value')
+      }
+      try {
+        return encodeCall(call, callCanFail)
+      } catch (err) {
+        if (callCanFail) {
+          return null
+        }
+        throw err
+      }
+    })
+    const valid = requests.filter((req): req is CallRequest => req !== null)
+    const results = await this.#aggregate(valid, overrides)
+    let j = 0
+    const aligned = requests.map((req) => (req ? (results[j++] as RawResult) : { success: false, returnData: '0x' }))
+    return decodeTry<T>(calls, aligned)
+  }
+
+  /**
+   * 单条调用，自动与同一收集窗口内的其他 `call()` 合并为一次 multicall。
+   * 失败时 reject CallFailedError。适合各组件各自查数据、又希望只发一个请求的场景。
+   */
+  call<T = any>(call: Call, overrides?: CallOverrides): Promise<T> {
+    const own = call.overrides
+    return this.#batcher.load<T>(call, merge({ blockTag: own?.blockTag, from: own?.from }, overrides))
+  }
+
+  /**
+   * 预执行（模拟交易）：直接对目标合约发 eth_call，可带 from / value / gasLimit，
+   * 用于 swap 报价、检查交易是否会 revert 等。失败时抛 CallFailedError（带解析后的 revert 原因）。
+   *
+   * 不走 multicall：multicall 里子调用的 msg.sender 是 multicall 合约本身、也无法按条带 value，
+   * 与真实交易不一致。
+   *
+   * overrides 优先级：参数 overrides > Call 上的 overrides（`contract.swap(params, { value })`）。
+   */
+  async staticCall<T = any>(call: Call, overrides: StaticCallOverrides = {}): Promise<T> {
+    const result = await this.#staticCall<T>(call, overrides)
+    if (!result.success) {
+      throw result.error
+    }
+    return result.data
+  }
+
+  /**
+   * 批量预执行：每条都是独立的 eth_call，同时发出（JsonRpcProvider 会合进一个 JSON-RPC batch 请求；
+   * TronProvider 按 concurrency 限流）。每条结果单独返回成功/失败，不会互相影响。
+   *
+   * @param items Call，或 `{ call, overrides }` 以便每条带不同的 value / from
+   * @param overrides 所有条目共享的 overrides，优先级最低
+   */
+  async staticCallAll<T = any>(
+    items: ReadonlyArray<Call | StaticCallItem>,
+    overrides: StaticCallOverrides = {},
+  ): Promise<StaticCallResult<T>[]> {
+    return Promise.all(
+      items.map((item) =>
+        'call' in item && 'contract' in item.call
+          ? this.#staticCall<T>(item.call, item.overrides, overrides)
+          : this.#staticCall<T>(item as Call, undefined, overrides),
+      ),
+    )
+  }
+
+  /** 优先级：explicit > Call 自带的 overrides > shared；值为 undefined 的字段不覆盖 */
+  async #staticCall<T>(
+    call: Call,
+    explicit?: StaticCallOverrides,
+    shared?: StaticCallOverrides,
+  ): Promise<StaticCallResult<T>> {
+    const merged: StaticCallOverrides = merge(merge({ ...shared }, call.overrides), explicit)
+    if (call.kind === 'ethBalance') {
+      try {
+        return { success: true, data: (await this.#ctx.provider.getBalance(call.params[0], merged.blockTag)) as T }
+      } catch (err) {
+        return { success: false, error: err instanceof Error ? err : new Error(String(err)) }
+      }
+    }
+    let returnData: string
+    try {
+      const request = encodeCall(call, false)
+      returnData = await this.#ctx.provider.call({
+        to: request.target,
+        data: request.callData,
+        from: merged.from,
+        value: merged.value,
+        gasLimit: merged.gasLimit,
+        blockTag: merged.blockTag,
+      })
+    } catch (err) {
+      // 只有执行层面的失败才是 CallFailedError；限流、超时等节点错误原样返回
+      if (isExecutionError(err)) {
+        return { success: false, error: new CallFailedError(call, (err as { data?: string | null }).data ?? '0x', err) }
+      }
+      return { success: false, error: err instanceof Error ? err : new Error(String(err)) }
+    }
+    try {
+      return { success: true, data: decodeCall<T>(call, returnData) }
+    } catch (err) {
+      // 目标地址没有合约时返回 0x，解码失败
+      return { success: false, error: new CallFailedError(call, returnData, err) }
+    }
+  }
+
+  /** 底层连接（多节点时是 FallbackRpc） */
+  get rpc(): EthersLikeProvider {
+    return this.#ctx.provider
+  }
+
+  /** 当前使用的 multicall 合约（null 表示 deployless） */
+  get multicall(): Multicall | null {
+    return this.#ctx.multicall
+  }
+
+  #aggregate(requests: CallRequest[], overrides?: CallOverrides): Promise<RawResult[]> {
+    return aggregate(this.#ctx, requests, overrides)
+  }
+}
+
+function resolveMulticall(chainId: number, custom?: Partial<Multicall>): Multicall | null {
+  if (custom?.address) {
+    return { address: custom.address, block: custom.block ?? 0 }
+  }
+  return Number.isFinite(chainId) ? getMulticall3(chainId) : null
+}
+
+/** 浅合并，source 里值为 undefined 的字段不覆盖 target */
+function merge<T extends object>(target: T, source?: object): T {
+  const out = { ...target } as Record<string, unknown>
+  for (const [key, value] of Object.entries(source ?? {})) {
+    if (value !== undefined) {
+      out[key] = value
+    }
+  }
+  return out as T
+}
+
+/** 把数组 / 对象输入展开成 Call 列表，并返回把结果还原成同样形状的函数 */
+function unpack(calls: CallInput): [readonly Call[], (results: unknown[]) => unknown] {
+  if (Array.isArray(calls)) {
+    return [calls, (results) => results]
+  }
+  const keys = Object.keys(calls)
+  const record = calls as Readonly<Record<string, Call>>
+  return [keys.map((key) => record[key] as Call), (results) => Object.fromEntries(keys.map((key, i) => [key, results[i]]))]
+}
+
+function decodeTry<T>(calls: ReadonlyArray<Call | FailableCall>, results: RawResult[]): (T | null)[] {
+  return calls.map((call, i) => {
+    const result = results[i] as RawResult
+    if (!result.success) {
+      return null
+    }
+    try {
+      return decodeCall<T>(call, result.returnData)
+    } catch {
+      // 解码失败：多半是目标地址没有合约
+      return null
+    }
+  })
+}
+
+export default Provider
+
+export type { BlockTag, CallOverrides }