@w3lib/evm-batch-call 0.3.0 → 0.4.1

package/src/aggregate.ts

@@ -1,9 +1,11 @@
 import { AbiCoder, Interface, concat, dataSlice, id, isError, type Provider as EthersProvider } from 'ethers'
 
-import type { CallRequest, RawResult } from './call.js'
+import { encodeUint256, type CallRequest, type RawResult } from './call.js'
 import { DEPLOYLESS_MULTICALL3_BYTECODE } from './deployless.js'
 import { isExecutionError } from './errors.js'
+import { AllNodesFailedError, FallbackRpc, InvalidResultError } from './fallback.js'
 import { MULTICALL3_ADDRESS, type Multicall } from './multicall.js'
+import { isTronChain } from './tron.js'
 
 /**
  * 只用到 ethers Provider 的这几个方法：必需 call / getBalance；getLogs / getBlockNumber 可选（只有增量扫描 Transfer 事件时用到）。
@@ -16,13 +18,55 @@ export type BlockTag = number | bigint | string
 export interface CallOverrides {
   blockTag?: BlockTag
   from?: string
+  /**
+   * 最低区块：节点落后于这个区块时（如交易刚确认、公共节点还没跟上）不用它的结果——
+   * 改为按这个区块重查（落后的节点会报错、自动换节点），所有节点都落后时稍等重试，最多约 10 秒。
+   * 只对最新状态的查询生效（指定了 blockTag 时忽略）
+   */
+  minBlock?: number
+  /** 取消查询：已取消时不发请求；执行中取消时立即 reject（合并在一起的底层请求继续完成，结果丢弃） */
+  signal?: AbortSignal
 }
 
+/**
+ * 主币余额的读取方式：
+ * - 'contract'：和其他调用放在同一次 eth_call 里（Multicall3.getEthBalance / deployless 合约里的 BALANCE）
+ * - 'rpc'：单独用 eth_getBalance（与 eth_call 同时发出）。用于合约里读主币余额不可靠的链（如 BALANCE 恒为 0）
+ * - { erc20 }：主币其实是一个 ERC20 合约，改调它的 balanceOf
+ */
+export type NativeBalanceMode = 'contract' | 'rpc' | { erc20: string }
+
+const balanceOfInterface = new Interface(['function balanceOf(address owner) view returns (uint256)'])
+
 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)',
+  'function getBlockNumber() view returns (uint256 blockNumber)',
 ])
 
+/** 区块号查询（minBlock 检查用）：目标在执行时换成 multicall 地址 */
+const BLOCK_NUMBER_REQUEST: CallRequest = {
+  target: MULTICALL3_ADDRESS,
+  allowFailure: true,
+  callData: multicall3Interface.encodeFunctionData('getBlockNumber'),
+  blockNumber: true,
+}
+
+/**
+ * Arbitrum 系的链（Arbitrum One / Nova、Orbit 链如 Robinhood Chain）在合约里 block.number 是 L1 区块号，
+ * L2 区块号要从 ArbSys 预编译合约（0x64）的 arbBlockNumber() 读。区块号查询时顺带读它：有返回值就用它，
+ * 其他链上 0x64 没有代码、返回空数据，忽略
+ */
+const ARB_BLOCK_NUMBER_REQUEST: CallRequest = {
+  target: '0x0000000000000000000000000000000000000064',
+  allowFailure: true,
+  callData: '0xa3b1b31d', // arbBlockNumber()
+}
+
+/** minBlock：所有节点都落后时的重试间隔和总时长 */
+const MIN_BLOCK_RETRY_INTERVAL = 1000
+const MIN_BLOCK_DEADLINE = 10_000
+
 const CALL3_TUPLE = 'tuple(address target, bool allowFailure, bytes callData)[]'
 const RESULT_TUPLE = 'tuple(bool success, bytes returnData)[]'
 /** error Aggregate3Result((bool,bytes)[]) */
@@ -32,7 +76,45 @@ const AGGREGATE3_RESULT_SELECTOR = id('Aggregate3Result((bool,bytes)[])').slice(
  * 判定为无效的 multicall 地址（无代码 / 不是 Multicall3），按 chainId+address 记在模块级，
  * 这样业务里每次 new Provider 也只会多试一次。
  */
-const unusableMulticalls = new Set<string>()
+const unusableMulticalls = new Map<string, number>()
+
+/** 判定不可用后多久重新尝试合约（节点偶发返回空数据时不至于整个会话都不用 Multicall3） */
+const UNUSABLE_TTL = 10 * 60 * 1000
+/** 单节点时连续返回空数据 / 无法解码的次数（多节点时由多个节点一致的结果确认，见 aggregateRawChunk） */
+const invalidStrikes = new Map<string, number>()
+
+/**
+ * eth_call 并解码 aggregate3 的结果：通过 FallbackRpc 时空数据 / 无法解码的结果换下一个节点（解码只做一次，结果复用）；
+ * 其他 Provider 不支持校验参数，取到结果后自己校验
+ */
+async function callAggregate3(provider: EthersLikeProvider, tx: Parameters<EthersLikeProvider['call']>[0]): Promise<RawResult[]> {
+  const decoded = new Map<string, RawResult[]>()
+  const accept = (data: string) => {
+    const results = decodeAggregate3Data(data)
+    if (results) {
+      decoded.set(data, results)
+    }
+    return results !== null
+  }
+  const data = provider instanceof FallbackRpc ? await provider.call(tx, { accept }) : await provider.call(tx)
+  const results = decoded.get(data) ?? decodeAggregate3Data(data)
+  if (!results) {
+    throw new InvalidResultError(data)
+  }
+  return results
+}
+
+/** aggregate3 返回数据的解码结果；空数据或无法解码时为 null */
+function decodeAggregate3Data(data: string): RawResult[] | null {
+  if (!data || data === '0x') {
+    return null
+  }
+  try {
+    return decodeAggregate3(multicall3Interface.decodeFunctionResult('aggregate3', data)[0])
+  } catch {
+    return null
+  }
+}
 
 export interface AggregateContext {
   provider: EthersLikeProvider
@@ -40,6 +122,8 @@ export interface AggregateContext {
   /** null 表示直接走 deployless */
   multicall: Multicall | null
   chunkSize: number
+  /** 主币余额的读取方式，默认 'contract' */
+  nativeBalance?: NativeBalanceMode
 }
 
 /**
@@ -55,64 +139,207 @@ export async function aggregate(
   if (requests.length === 0) {
     return []
   }
+  const mode = ctx.nativeBalance ?? 'contract'
+  if (mode !== 'contract' && requests.some((req) => req.ethBalanceOf !== undefined)) {
+    return typeof mode === 'object' ? aggregate(ctx, requests.map((req) => toErc20Balance(req, mode.erc20)), overrides) : aggregateWithRpcBalances(ctx, requests, overrides)
+  }
   const size = Math.max(1, ctx.chunkSize)
+  const run = overrides.minBlock !== undefined && isLatest(overrides.blockTag) ? aggregateChunkAtLeast : aggregateChunk
   if (requests.length <= size) {
-    return aggregateChunk(ctx, requests, overrides)
+    return run(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)))
+  const results = await Promise.all(chunks.map((chunk) => run(ctx, chunk, overrides)))
   return results.flat()
 }
 
-async function aggregateChunk(
+/**
+ * minBlock：先按最新状态查，同一次 eth_call 里顺带读区块号；节点落后时按 minBlock 指定区块重查——
+ * 落后的节点对未来区块报 “header not found” 等错误，FallbackRpc 换节点（不冷却）；所有节点都落后时稍等重试。
+ * 重查得到的是 minBlock 那个区块的状态（已包含刚确认的交易）。Tron 只能查最新状态，落后时等节点跟上再查。
+ * overrides.signal 取消后不再重试
+ */
+async function aggregateChunkAtLeast(ctx: AggregateContext, requests: CallRequest[], overrides: CallOverrides): Promise<RawResult[]> {
+  const minBlock = overrides.minBlock as number
+  // Tron 节点只能查最新状态（不支持按区块号查询）
+  const canPinBlock = !isTronChain(ctx.chainId)
+  return retryUntilCaughtUp(overrides, async () => {
+    const results = await aggregateChunk(ctx, [...requests, BLOCK_NUMBER_REQUEST], overrides)
+    if ((blockOf(results[results.length - 1]) ?? -1n) >= BigInt(minBlock)) {
+      return results.slice(0, -1)
+    }
+    if (canPinBlock) {
+      // 按区块号重查时同样带上区块号并校验：有的节点对未来区块不报错、直接返回最新状态（如 HyperEVM），不能当成 minBlock 的结果
+      const pinned = await aggregateChunk(ctx, [...requests, BLOCK_NUMBER_REQUEST], { ...overrides, blockTag: minBlock })
+      if ((blockOf(pinned[pinned.length - 1]) ?? -1n) >= BigInt(minBlock)) {
+        return pinned.slice(0, -1)
+      }
+    }
+    throw new Error(`Node is behind minBlock ${minBlock}`)
+  })
+}
+
+/** 节点落后时的重试：确定性错误（合约执行结果）直接抛；其余错误每秒重试，最多约 10 秒；signal 取消后停止 */
+async function retryUntilCaughtUp<T>(overrides: CallOverrides, run: () => Promise<T>): Promise<T> {
+  const deadline = Date.now() + MIN_BLOCK_DEADLINE
+  for (;;) {
+    overrides.signal?.throwIfAborted()
+    try {
+      return await run()
+    } catch (err) {
+      if (isExecutionError(err) || Date.now() + MIN_BLOCK_RETRY_INTERVAL > deadline) {
+        throw err
+      }
+    }
+    await sleep(MIN_BLOCK_RETRY_INTERVAL, overrides.signal)
+  }
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    const onAbort = () => {
+      clearTimeout(timer)
+      reject(signal?.reason)
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/** 区块号查询的结果；失败时为 null */
+function blockOf(result: RawResult | undefined): bigint | null {
+  return result?.success && result.returnData !== '0x' ? BigInt(result.returnData) : null
+}
+
+/** 主币余额请求改成主币 ERC20 合约的 balanceOf（返回值同样是 uint256，解码方式不变） */
+function toErc20Balance(req: CallRequest, erc20: string): CallRequest {
+  if (req.ethBalanceOf === undefined) {
+    return req
+  }
+  return { target: erc20, allowFailure: req.allowFailure, callData: balanceOfInterface.encodeFunctionData('balanceOf', [req.ethBalanceOf]) }
+}
+
+/**
+ * 主币余额单独走 eth_getBalance，结果按原顺序合并；节点错误照常抛出。
+ * 需要区块号（withBlock / minBlock）时，先执行其余请求并读出实际区块号，再在这个区块上读主币余额——
+ * 主币和代币余额、blockNumber 一致，minBlock 的等待 / 换节点也由其余请求负责；否则两者同时发出
+ */
+async function aggregateWithRpcBalances(ctx: AggregateContext, requests: CallRequest[], overrides: CallOverrides): Promise<RawResult[]> {
+  const others = requests.filter((req) => req.ethBalanceOf === undefined)
+  const owners = requests.filter((req) => req.ethBalanceOf !== undefined).map((req) => req.ethBalanceOf as string)
+  const contractCtx: AggregateContext = { ...ctx, nativeBalance: 'contract' }
+  let otherResults: RawResult[]
+  let balances: bigint[]
+  // Tron 节点只能查最新状态，不能按区块号读余额
+  if (isLatest(overrides.blockTag) && !isTronChain(ctx.chainId) && (overrides.minBlock !== undefined || others.some((req) => req.blockNumber))) {
+    const results = await aggregate(contractCtx, [...others, BLOCK_NUMBER_REQUEST], overrides)
+    const block = blockOf(results.pop())
+    otherResults = results
+    const blockTag = block === null ? overrides.blockTag : Number(block)
+    const read = () => Promise.all(owners.map((owner) => ctx.provider.getBalance(owner, blockTag)))
+    // 只有 minBlock 才等待重试（读的区块可能来自比当前节点更新的节点）；只要 withBlock 时出错照常抛出
+    balances = await (overrides.minBlock !== undefined ? retryUntilCaughtUp(overrides, read) : read())
+  } else {
+    ;[otherResults, balances] = await Promise.all([
+      aggregate(contractCtx, others, overrides),
+      Promise.all(owners.map((owner) => ctx.provider.getBalance(owner, overrides.blockTag))),
+    ])
+  }
+  let i = 0
+  let j = 0
+  return requests.map((req) =>
+    req.ethBalanceOf === undefined ? (otherResults[i++] as RawResult) : { success: true, returnData: encodeUint256(balances[j++] as bigint) },
+  )
+}
+
+/** 执行一批请求；其中有区块号查询时顺带读 Arbitrum 的 L2 区块号，并用它替换（见 ARB_BLOCK_NUMBER_REQUEST） */
+async function aggregateChunk(ctx: AggregateContext, requests: CallRequest[], overrides: CallOverrides): Promise<RawResult[]> {
+  if (!requests.some((req) => req.blockNumber)) {
+    return aggregateRawChunk(ctx, requests, overrides)
+  }
+  const results = await aggregateRawChunk(ctx, [...requests, ARB_BLOCK_NUMBER_REQUEST], overrides)
+  const arb = results.pop() as RawResult
+  if (arb.success && arb.returnData.length === 66) {
+    requests.forEach((req, i) => {
+      if (req.blockNumber) {
+        results[i] = arb
+      }
+    })
+  }
+  return results
+}
+
+async function aggregateRawChunk(
   ctx: AggregateContext,
   requests: CallRequest[],
   overrides: CallOverrides,
 ): Promise<RawResult[]> {
   const multicall = ctx.multicall
   if (multicall && isUsable(ctx.chainId, multicall, overrides.blockTag)) {
+    const key = cacheKey(ctx.chainId, multicall.address)
     const results = await callContract(ctx, multicall, requests, overrides)
     if (Array.isArray(results)) {
+      invalidStrikes.delete(key)
       return results
     }
-    // 只有“最新状态下地址上没有可用合约”才记缓存。
+    // 只有“最新状态下地址上没有可用合约”才记缓存（10 分钟后重新尝试）：
+    // - 'invalid'（返回空数据 / 无法解码）要确认过才记：多个节点结果一致，或单节点连续 2 次——节点偶发返回一次 0x 不算
     // - revert 无数据（'reverted'）有歧义：可能是 out of gas / 节点 gas 上限、子调用失败而钱包丢了 revert 数据，
     //   这些情况地址本身是好的，只对这一次退回 deployless，不记缓存
     // - 历史区块查到无代码可能只是那时还没部署，不能推及 latest
-    if (results === 'invalid' && isLatest(overrides.blockTag)) {
-      unusableMulticalls.add(cacheKey(ctx.chainId, multicall.address))
+    if (results !== 'reverted' && isLatest(overrides.blockTag)) {
+      const strikes = (invalidStrikes.get(key) ?? 0) + 1
+      if (results === 'invalid-confirmed' || strikes >= 2) {
+        unusableMulticalls.set(key, Date.now() + UNUSABLE_TTL)
+        invalidStrikes.delete(key)
+      } else {
+        invalidStrikes.set(key, strikes)
+      }
     }
   }
   return callDeployless(ctx, requests, overrides)
 }
 
 /**
- * 'invalid'：地址上没有代码或返回无法解码；'reverted'：执行 revert 且没有 revert 数据。
- * 两种情况都退回 deployless。
+ * 'invalid'：返回空数据（地址上没有代码）或无法解码——经 FallbackRpc 时会先换节点重试；
+ * 所有节点（2 个以上）都这样时为 'invalid-confirmed'。'reverted'：执行 revert 且没有 revert 数据。
+ * 这几种情况都退回 deployless。
  */
 async function callContract(
   ctx: AggregateContext,
   multicall: Multicall,
   requests: CallRequest[],
   overrides: CallOverrides,
-): Promise<RawResult[] | 'invalid' | 'reverted'> {
+): Promise<RawResult[] | 'invalid' | 'invalid-confirmed' | 'reverted'> {
   const calls = requests.map((req) => ({
-    target: req.ethBalanceOf ? multicall.address : req.target,
+    target: req.ethBalanceOf || req.blockNumber ? multicall.address : req.target,
     allowFailure: req.allowFailure,
     callData: req.callData,
   }))
-  let data: string
   try {
-    data = await ctx.provider.call({
+    // 地址上没有代码时 eth_call 返回 0x；空数据 / 无法解码的结果换下一个节点（节点偶发出错时别的节点能给出正确结果）
+    return await callAggregate3(ctx.provider, {
       to: multicall.address,
       data: multicall3Interface.encodeFunctionData('aggregate3', [calls]),
       blockTag: overrides.blockTag,
       from: overrides.from,
     })
   } catch (err) {
+    if (err instanceof InvalidResultError) {
+      return 'invalid'
+    }
+    // 有节点返回空数据、其余节点出错（超时、限频等）：合约可能不存在，退回 deployless；
+    // 只有 2 个以上节点都返回空数据才算确认，记缓存
+    if (err instanceof AllNodesFailedError && err.errors.some((e) => e.error instanceof InvalidResultError)) {
+      const invalid = err.errors.filter((e) => e.error instanceof InvalidResultError).length
+      return invalid >= 2 && invalid === err.errors.length ? 'invalid-confirmed' : 'invalid'
+    }
     // aggregate3 自己的失败（allowFailure=false 的子调用失败）会带 "Multicall3: call failed" 的 revert 数据；
     // 执行层面 revert 且没有数据，基本就是这个地址上不是 Multicall3。
     // 限流、节点缺状态等错误 ethers 也会包装成 CALL_EXCEPTION，那些要原样抛出，不能把地址判成无效
@@ -121,15 +348,6 @@ async function callContract(
     }
     throw err
   }
-  // 地址上没有代码时 eth_call 返回 0x
-  if (!data || data === '0x') {
-    return 'invalid'
-  }
-  try {
-    return decodeAggregate3(multicall3Interface.decodeFunctionResult('aggregate3', data)[0])
-  } catch {
-    return 'invalid'
-  }
 }
 
 /**
@@ -157,20 +375,16 @@ async function callDeploylessChunk(
   const args = AbiCoder.defaultAbiCoder().encode(
     [CALL3_TUPLE],
     [
-      requests.map(({ target, allowFailure, callData, ethBalanceOf }) => ({
-        target: ethBalanceOf ? MULTICALL3_ADDRESS : target,
+      requests.map(({ target, allowFailure, callData, ethBalanceOf, blockNumber }) => ({
+        target: ethBalanceOf || blockNumber ? 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,
-    })
+    // 返回空数据 / 无法解码（节点不支持合约创建式 eth_call，或偶发出错）时换下一个节点
+    return await callAggregate3(ctx.provider, { 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)) {
@@ -188,7 +402,6 @@ async function callDeploylessChunk(
     }
     throw err
   }
-  return decodeAggregate3(multicall3Interface.decodeFunctionResult('aggregate3', data)[0])
 }
 
 /** EIP-3860 initcode 上限 49152 字节，留出余量 */
@@ -228,8 +441,13 @@ function decodeAggregate3(raw: ReadonlyArray<readonly [boolean, string]>): RawRe
 }
 
 function isUsable(chainId: number, multicall: Multicall, blockTag?: BlockTag): boolean {
-  if (unusableMulticalls.has(cacheKey(chainId, multicall.address))) {
-    return false
+  const key = cacheKey(chainId, multicall.address)
+  const until = unusableMulticalls.get(key)
+  if (until !== undefined) {
+    if (Date.now() < until) {
+      return false
+    }
+    unusableMulticalls.delete(key)
   }
   if (blockTag === 'earliest') {
     return false
@@ -254,4 +472,5 @@ function cacheKey(chainId: number, address: string): string {
 /** 测试用：清掉“地址不可用”的缓存 */
 export function resetMulticallCache(): void {
   unusableMulticalls.clear()
+  invalidStrikes.clear()
 }

package/src/batcher.ts

@@ -1,4 +1,4 @@
-import { decodeCall, encodeCall, type Call, type CallRequest, type RawResult } from './call.js'
+import { decodeCall, encodeCall, encodeFailureReason, settleResult, type Call, type CallRequest, type RawResult, type Settled } from './call.js'
 import type { CallOverrides } from './aggregate.js'
 import { CallFailedError } from './errors.js'
 
@@ -13,6 +13,10 @@ type Runner = (requests: CallRequest[], overrides: CallOverrides) => Promise<Raw
 
 interface Pending {
   call: Call
+  /** 调用方的 signal（没有时这个调用方不会取消，整批请求不能中断） */
+  signal?: AbortSignal
+  /** true：失败时 resolve 失败原因（Settled），不 reject；节点错误照常 reject */
+  settle: boolean
   resolve: (value: unknown) => void
   reject: (reason: unknown) => void
 }
@@ -23,6 +27,27 @@ interface Queue {
   timer: ReturnType<typeof setTimeout> | null
 }
 
+/**
+ * 整批请求的 signal：所有调用方都传了 signal、并且都取消后才取消（如 minBlock 的等待重试随之停止）；
+ * 有调用方没传 signal 时为 undefined（整批照常完成）。请求结束后调用 dispose，移除挂在调用方 signal 上的监听
+ * （调用方可能用一个长期存在的 signal 发起很多次查询）
+ */
+function combinedSignal(entries: readonly Pending[]): { signal: AbortSignal | undefined; dispose: () => void } {
+  const signals = [...new Set(entries.map((entry) => entry.signal))]
+  if (!signals.length || signals.some((signal) => signal === undefined)) {
+    return { signal: undefined, dispose: () => {} }
+  }
+  const controller = new AbortController()
+  const check = () => {
+    if (signals.every((signal) => signal?.aborted)) {
+      controller.abort(signals[0]?.reason)
+    }
+  }
+  signals.forEach((signal) => signal?.addEventListener('abort', check, { once: true }))
+  check()
+  return { signal: controller.signal, dispose: () => signals.forEach((signal) => signal?.removeEventListener('abort', check)) }
+}
+
 /**
  * DataLoader 式的自动合并：各处独立调用 `provider.call(x)`，
  * 落在同一个收集窗口、且 blockTag/from 相同的调用会合成一次 aggregate3。
@@ -41,21 +66,49 @@ export class Batcher {
   }
 
   load<T>(call: Call, overrides: CallOverrides = {}): Promise<T> {
-    const key = `${String(overrides.blockTag ?? 'latest')}|${overrides.from ?? ''}`
+    const [key, queue] = this.#queue(overrides)
+    const promise = new Promise<T>((resolve, reject) => {
+      queue.entries.push({ call, signal: overrides.signal, settle: false, resolve: resolve as (value: unknown) => void, reject })
+    })
+    this.#schedule(key, queue)
+    return promise
+  }
+
+  /**
+   * 一组调用一起入队（不会被 maxSize 拆到不同批次），逐条返回成功的值或失败原因；
+   * 只有节点错误（整批失败）时 reject。balances / tokens / allowances 用它参与自动合并。
+   */
+  loadSettled(calls: readonly Call[], overrides: CallOverrides = {}): Promise<Settled[]> {
+    if (!calls.length) {
+      return Promise.resolve([])
+    }
+    const [key, queue] = this.#queue(overrides)
+    const promises = calls.map(
+      (call) =>
+        new Promise<Settled>((resolve, reject) => {
+          queue.entries.push({ call, signal: overrides.signal, settle: true, resolve: resolve as (value: unknown) => void, reject })
+        }),
+    )
+    this.#schedule(key, queue)
+    return Promise.all(promises)
+  }
+
+  #queue(overrides: CallOverrides): [string, Queue] {
+    const key = `${String(overrides.blockTag ?? 'latest')}|${overrides.from ?? ''}|${overrides.minBlock ?? ''}`
     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 })
-    })
+    return [key, queue]
+  }
+
+  #schedule(key: string, queue: Queue): void {
     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 {
@@ -80,11 +133,15 @@ export class Batcher {
       try {
         request = encodeCall(entry.call, true)
       } catch (err) {
-        entry.reject(err)
+        if (entry.settle) {
+          entry.resolve({ ok: false, reason: encodeFailureReason(err) } satisfies Settled)
+        } else {
+          entry.reject(err)
+        }
         requestIndex.push(-1)
         continue
       }
-      const dedupeKey = `${request.ethBalanceOf ? 'eth' : request.target.toLowerCase()}|${request.callData}`
+      const dedupeKey = `${request.ethBalanceOf ? 'eth' : request.blockNumber ? 'block' : request.target.toLowerCase()}|${request.callData}`
       let index = indexByKey.get(dedupeKey)
       if (index === undefined) {
         index = requests.push(request) - 1
@@ -98,11 +155,14 @@ export class Batcher {
     }
 
     let results: RawResult[]
+    const combined = combinedSignal(entries)
     try {
-      results = await this.#run(requests, overrides)
+      results = await this.#run(requests, { ...overrides, signal: combined.signal })
     } catch (err) {
       entries.forEach((entry, i) => requestIndex[i] !== -1 && entry.reject(err))
       return
+    } finally {
+      combined.dispose()
     }
 
     entries.forEach((entry, i) => {
@@ -111,6 +171,10 @@ export class Batcher {
         return
       }
       const result = results[index] as RawResult
+      if (entry.settle) {
+        entry.resolve(settleResult(entry.call, result))
+        return
+      }
       if (!result.success) {
         entry.reject(new CallFailedError(entry.call, result.returnData))
         return

package/src/call.ts

@@ -32,9 +32,10 @@ export interface Call<T = any> {
   /**
    * 内部标记：
    * - ethBalance：原生币余额查询（见 Provider.getEthBalance）
+   * - blockNumber：当前区块号（Multicall3.getBlockNumber；deployless 合约里直接返回 block.number）
    * - stringOrBytes32：string 返回值，解码失败时按 bytes32 解析（MKR 等老代币的 symbol / name）
    */
-  kind?: 'ethBalance' | 'stringOrBytes32'
+  kind?: 'ethBalance' | 'blockNumber' | 'stringOrBytes32'
   /** 仅用于类型推断 */
   readonly __result?: T
 }
@@ -52,13 +53,51 @@ export interface RawResult {
   returnData: string
 }
 
+/**
+ * 单条调用的失败原因：
+ * - invalid-address：合约地址或参数里的地址非法
+ * - invalid-argument：其他参数编码失败（个数不对、数值超出范围等）
+ * - no-contract：调用成功但返回空数据，多半是目标地址上没有合约
+ * - reverted：执行 revert
+ * - decode-failed：有返回数据但无法按 ABI 解码（如合约不是预期的标准）
+ * - not-configured：没有发请求的信息缺失，如主币不在内置链信息表里、也没有配置 nativeName / nativeSymbol
+ */
+export type FailureReason = 'invalid-address' | 'invalid-argument' | 'no-contract' | 'reverted' | 'decode-failed' | 'not-configured'
+
+/** 单条调用的结果：成功的值，或失败原因 */
+export type Settled<T = any> = { ok: true; value: T } | { ok: false; reason: FailureReason }
+
+/** 按 multicall 的原始结果判断成功 / 失败原因 */
+export function settleResult<T>(call: Call, result: RawResult): Settled<T> {
+  if (!result.success) {
+    return { ok: false, reason: 'reverted' }
+  }
+  // 没有返回值的函数成功时本来就返回空数据，照常解码；有返回值却拿到空数据，多半是地址上没有合约
+  if ((!result.returnData || result.returnData === '0x') && call.outputs.length > 0) {
+    return { ok: false, reason: 'no-contract' }
+  }
+  try {
+    return { ok: true, value: decodeCall<T>(call, result.returnData) }
+  } catch {
+    return { ok: false, reason: 'decode-failed' }
+  }
+}
+
+/** 参数编码失败的原因：地址非法，还是其他参数问题 */
+export function encodeFailureReason(err: unknown): FailureReason {
+  const e = err as { code?: unknown; argument?: unknown; message?: unknown } | null
+  return /address/i.test(String(e?.argument ?? '')) || /address/i.test(String(e?.message ?? '')) ? 'invalid-address' : 'invalid-argument'
+}
+
 /** 发给 aggregate3 前的单条请求 */
 export interface CallRequest {
   target: string
   allowFailure: boolean
   callData: string
-  /** 原生币余额查询：有 multicall 合约时走 getEthBalance，deployless 时改走 eth_getBalance */
+  /** 原生币余额查询：默认有 multicall 合约时走 getEthBalance、deployless 时用 BALANCE；其他读取方式见 NativeBalanceMode */
   ethBalanceOf?: string
+  /** 区块号查询：目标换成实际的 multicall 地址（deployless 时由合约内部处理） */
+  blockNumber?: boolean
 }
 
 // inputs → name → outputs → Interface。同一份 ABI 生成的 Call 共享 inputs/outputs 数组（见 contract.ts 的 ABI 缓存），
@@ -100,6 +139,7 @@ export function encodeCall(call: Call, allowFailure: boolean): CallRequest {
     allowFailure,
     callData: iface.encodeFunctionData(fragment, params),
     ethBalanceOf: call.kind === 'ethBalance' ? toEvmAddress(params[0] as string) : undefined,
+    blockNumber: call.kind === 'blockNumber' ? true : undefined,
   }
 }
 

package/src/chains.ts

@@ -1,3 +1,5 @@
+import type { NativeBalanceMode } from './aggregate.js'
+
 /**
  * 内置链的主币信息（balances() / tokens() 里主币的 name / symbol / 精度）。
  * 来源：https://chainid.network/chains.json 的 nativeCurrency；999 在该表里与 Wanchain 测试网撞号，
@@ -44,3 +46,16 @@ export const NATIVE_CURRENCIES: Readonly<Record<number, NativeCurrency>> = {
 export function getNativeCurrency(chainId: number): NativeCurrency | undefined {
   return NATIVE_CURRENCIES[chainId]
 }
+
+/**
+ * 合约里读主币余额不可靠的链，以及应改用的读取方式（ProviderConfig.nativeBalance 的默认值）。
+ * 新链可用 `pnpm check:rpc` 比对“合约里读到的主币余额”和 eth_getBalance 来发现。
+ */
+export const NATIVE_BALANCE_MODES: Readonly<Record<number, NativeBalanceMode>> = {
+  // Anubis：Multicall3.getEthBalance 和 deployless 里的 BALANCE 对任何地址都返回 0，eth_getBalance 正常
+  6714: 'rpc',
+}
+
+export function getNativeBalanceMode(chainId: number): NativeBalanceMode {
+  return NATIVE_BALANCE_MODES[chainId] ?? 'contract'
+}

package/src/deployless.ts

@@ -2,4 +2,4 @@
 
 /** constructor((address target, bool allowFailure, bytes callData)[] calls) — 以 aggregate3 的返回格式带回结果 */
 export const DEPLOYLESS_MULTICALL3_BYTECODE =
-  '0x608060405260405161060f38038061060f8339810160408190526100229161036c565b80516000816001600160401b0381111561003e5761003e6102da565b60405190808252806020026020018201604052801561008457816020015b60408051808201909152600081526060602082015281526020019060019003908161005c5790505b50905060005b828110156102875760008482815181106100a6576100a6610507565b602090810291909101015160408101518151919250906001600160a01b031673ca11bde05977b3631167028862be2a173976ca111480156100e8575080516024145b801561010c5750631348c07360e21b6101008261051d565b6001600160e01b031916145b1561017e5760248101516040805180820182526001815290516001600160a01b039290921691602080830191610149918531910190815260200190565b60405160208183030381529060405281525085858151811061016d5761016d610507565b60200260200101819052505061027d565b60008083600001516001600160a01b03168360405161019d919061055b565b6000604051808303816000865af19150503d80600081146101da576040519150601f19603f3d011682016040523d82523d6000602084013e6101df565b606091505b5091509150811580156101f457508360200151155b156102465760405162461bcd60e51b815260206004820152601760248201527f4d756c746963616c6c333a2063616c6c206661696c656400000000000000000060448201526064015b60405180910390fd5b604051806040016040528083151581526020018281525086868151811061026f5761026f610507565b602002602001018190525050505b505060010161008a565b5060008160405160200161029b9190610577565b6040516020818303038152906040529050616000815111156102d25781604051633649f05160e01b815260040161023d9190610577565b805160208201f35b634e487b7160e01b600052604160045260246000fd5b604051606081016001600160401b0381118282101715610312576103126102da565b60405290565b604051601f8201601f191681016001600160401b0381118282101715610340576103406102da565b604052919050565b60005b8381101561036357818101518382015260200161034b565b50506000910152565b60006020828403121561037e57600080fd5b81516001600160401b0381111561039457600080fd5b8201601f810184136103a557600080fd5b80516001600160401b038111156103be576103be6102da565b8060051b6103ce60208201610318565b918252602081840181019290810190878411156103ea57600080fd5b6020850192505b838310156104fc5782516001600160401b0381111561040f57600080fd5b85016060818a03601f1901121561042557600080fd5b61042d6102f0565b60208201516001600160a01b038116811461044757600080fd5b81526040820151801515811461045c57600080fd5b602082015260608201516001600160401b0381111561047a57600080fd5b60208184010192505089601f83011261049257600080fd5b81516001600160401b038111156104ab576104ab6102da565b6104be601f8201601f1916602001610318565b8181528b60208386010111156104d357600080fd5b6104e4826020830160208701610348565b604083015250835250602092830192909101906103f1565b979650505050505050565b634e487b7160e01b600052603260045260246000fd5b805160208201516001600160e01b0319811691906004821015610554576001600160e01b0319600483900360031b81901b82161692505b5050919050565b6000825161056d818460208701610348565b9190910192915050565b6000602082016020835280845180835260408501915060408160051b86010192506020860160005b8281101561060257603f198786030184528151805115158652602081015190506040602087015280518060408801526105df816060890160208501610348565b601f01601f1916959095016060019450602093840193919091019060010161059f565b5092969550505050505056fe'
+  '0x60806040526040516106c13803806106c18339810160408190526100229161041e565b80516000816001600160401b0381111561003e5761003e61038c565b60405190808252806020026020018201604052801561008457816020015b60408051808201909152600081526060602082015281526020019060019003908161005c5790505b50905060005b828110156103395760008482815181106100a6576100a66105b9565b602090810291909101015160408101518151919250906001600160a01b031673ca11bde05977b3631167028862be2a173976ca111480156100e8575080516024145b801561010c5750631348c07360e21b610100826105cf565b6001600160e01b031916145b1561017e5760248101516040805180820182526001815290516001600160a01b039290921691602080830191610149918531910190815260200190565b60405160208183030381529060405281525085858151811061016d5761016d6105b9565b60200260200101819052505061032f565b81516001600160a01b031673ca11bde05977b3631167028862be2a173976ca111480156101ac575080516004145b80156101d057506310b2ec5760e21b6101c4826105cf565b6001600160e01b031916145b15610230576040518060400160405280600115158152602001436040516020016101fc91815260200190565b604051602081830303815290604052815250848481518110610220576102206105b9565b602002602001018190525061032f565b60008083600001516001600160a01b03168360405161024f919061060d565b6000604051808303816000865af19150503d806000811461028c576040519150601f19603f3d011682016040523d82523d6000602084013e610291565b606091505b5091509150811580156102a657508360200151155b156102f85760405162461bcd60e51b815260206004820152601760248201527f4d756c746963616c6c333a2063616c6c206661696c656400000000000000000060448201526064015b60405180910390fd5b6040518060400160405280831515815260200182815250868681518110610321576103216105b9565b602002602001018190525050505b505060010161008a565b5060008160405160200161034d9190610629565b6040516020818303038152906040529050616000815111156103845781604051633649f05160e01b81526004016102ef9190610629565b805160208201f35b634e487b7160e01b600052604160045260246000fd5b604051606081016001600160401b03811182821017156103c4576103c461038c565b60405290565b604051601f8201601f191681016001600160401b03811182821017156103f2576103f261038c565b604052919050565b60005b838110156104155781810151838201526020016103fd565b50506000910152565b60006020828403121561043057600080fd5b81516001600160401b0381111561044657600080fd5b8201601f8101841361045757600080fd5b80516001600160401b038111156104705761047061038c565b8060051b610480602082016103ca565b9182526020818401810192908101908784111561049c57600080fd5b6020850192505b838310156105ae5782516001600160401b038111156104c157600080fd5b85016060818a03601f190112156104d757600080fd5b6104df6103a2565b60208201516001600160a01b03811681146104f957600080fd5b81526040820151801515811461050e57600080fd5b602082015260608201516001600160401b0381111561052c57600080fd5b60208184010192505089601f83011261054457600080fd5b81516001600160401b0381111561055d5761055d61038c565b610570601f8201601f19166020016103ca565b8181528b602083860101111561058557600080fd5b6105968260208301602087016103fa565b604083015250835250602092830192909101906104a3565b979650505050505050565b634e487b7160e01b600052603260045260246000fd5b805160208201516001600160e01b0319811691906004821015610606576001600160e01b0319600483900360031b81901b82161692505b5050919050565b6000825161061f8184602087016103fa565b9190910192915050565b6000602082016020835280845180835260408501915060408160051b86010192506020860160005b828110156106b457603f198786030184528151805115158652602081015190506040602087015280518060408801526106918160608901602085016103fa565b601f01601f19169590950160600194506020938401939190910190600101610651565b5092969550505050505056fe'