@w3lib/evm-batch-call 0.3.0 → 0.4.0

package/src/erc20.ts

@@ -1,4 +1,4 @@
-import type { BoundCall } from './call.js'
+import type { BoundCall, FailureReason } from './call.js'
 import type { BoundMethod, Contract } from './contract.js'
 
 export const ERC20_ABI = [
@@ -41,9 +41,18 @@ export interface TokenAllowance {
   formatted: string
   /** 额度 ≥ uint96 最大值时为 true（覆盖 MaxUint256，以及 UNI / COMP 等把额度截断为 uint96 的代币） */
   unlimited: boolean
+  /** 仅在 withBlock / minBlock 时返回：读取时的区块号（读取失败为 null） */
+  blockNumber?: number | null
   success: boolean
+  /** 仅在 success 为 false 时返回：失败原因 */
+  error?: FailureReason
+  /** 仅在 success 为 false 时返回：哪一项没读到 */
+  errorField?: 'allowance' | 'decimals'
 }
 
+/** allowances(..., { decimals: false }) 的单项结果：不查 decimals，不带 decimals / formatted */
+export type RawTokenAllowance = Omit<TokenAllowance, 'decimals' | 'formatted'>
+
 /** unlimited 的判定阈值：uint96 最大值 */
 export const UNLIMITED_ALLOWANCE_THRESHOLD = 2n ** 96n - 1n
 
@@ -75,8 +84,14 @@ export type TokenDetails<F extends TokenField = DefaultTokenField> = {
   address: string
   /** 是否是主币占位地址（信息来自内置链信息表 / nativeSymbol 等配置） */
   native: boolean
+  /** 仅在 withBlock / minBlock 时返回：读取时的区块号（读取失败为 null） */
+  blockNumber?: number | null
   /** 请求的字段都读到时为 true（主币没有 totalSupply，不计入） */
   success: boolean
+  /** 仅在 success 为 false 时返回：第一个没读到的字段的失败原因 */
+  error?: FailureReason
+  /** 仅在 success 为 false 时返回：第一个没读到的字段 */
+  errorField?: TokenField
 } & { [K in F]: TokenFieldTypes[K] } & ('totalSupply' extends F ? { totalSupplyFormatted: string | null } : unknown)
 
 /** 主币占位地址（多数聚合器、钱包的约定），传给 balances() 时按主币处理 */
@@ -100,15 +115,27 @@ export interface TokenBalance {
   formatted: string
   /** 仅在 symbol: true 时返回；读取失败或主币 symbol 未知时为 null */
   symbol?: string | null
+  /** 仅在 withBlock / minBlock 时返回：读取时的区块号（与余额在同一次 eth_call 里读出；读取失败为 null） */
+  blockNumber?: number | null
   /** 余额和 decimals 都查到时为 true；失败时 balance、formatted 都为 "0" */
   success: boolean
+  /**
+   * 仅在 success 为 false 时返回：失败原因（invalid-address 地址非法、no-contract 地址上没有合约、
+   * reverted 执行 revert、decode-failed 返回值无法解码）。symbol 读不到不算失败（symbol 为 null）
+   */
+  error?: FailureReason
+  /** 仅在 success 为 false 时返回：哪一项没读到（两项都失败时为 balance） */
+  errorField?: 'balance' | 'decimals'
 }
 
+/** balances(..., { decimals: false }) 的单项结果：不查 decimals，不带 decimals / formatted */
+export type RawTokenBalance = Omit<TokenBalance, 'decimals' | 'formatted' | 'errorField'> & { errorField?: 'balance' }
+
 /**
- * 按精度格式化：formatAmount(1234500000n, 6) === '1234.5'，formatAmount(10n ** 18n, 18) === '1'。
- * 不做四舍五入，保留全部有效小数位。
+ * 按精度格式化（与 ethers 的 formatUnits 同名同义）：formatUnits(1234500000n, 6) === '1234.5'，formatUnits(10n ** 18n, 18) === '1'。
+ * 不做四舍五入，保留全部有效小数位，整数不带小数点（与 ethers 不同：ethers 会返回 '1.0'）。
  */
-export function formatAmount(value: bigint, decimals: number): string {
+export function formatUnits(value: bigint, decimals: number): string {
   const negative = value < 0n
   const digits = (negative ? -value : value).toString().padStart(decimals + 1, '0')
   const whole = digits.slice(0, digits.length - decimals)
@@ -116,7 +143,11 @@ export function formatAmount(value: bigint, decimals: number): string {
   return `${negative ? '-' : ''}${whole}${fraction ? `.${fraction}` : ''}`
 }
 
-// decimals / symbol / name 不会变，按 chainId + 地址缓存，轮询余额时只需要查 balanceOf
+/** @deprecated 改用 formatUnits（同一个函数；formatAmount 容易与项目里的数字展示函数撞名） */
+export const formatAmount = formatUnits
+
+// 代币信息缓存（按 chainId + 地址）：decimals / NFT 标准不会变，永久缓存；name / symbol 在可升级合约上可能改，缓存 1 小时。
+// 条目数有上限，超出时淘汰最早写入的（与 solana-batch-call 一致）。轮询余额时只需要查 balanceOf
 interface TokenMeta {
   decimals?: number
   symbol?: string
@@ -125,21 +156,153 @@ interface TokenMeta {
   standard?: 'ERC721' | 'ERC1155' | null
 }
 
-const tokenMetaCache = new Map<string, TokenMeta>()
+interface CachedMeta extends TokenMeta {
+  /** name / symbol 各自的写入时间（分开计：只刷新其中一个时，另一个照常过期） */
+  nameAt?: number
+  symbolAt?: number
+}
+
+const NAME_TTL = 60 * 60 * 1000
+const MAX_CACHED_TOKENS = 50_000
+const tokenMetaCache = new Map<string, CachedMeta>()
+const cacheListeners = new Set<() => void>()
 
 export function getCachedTokenMeta(chainId: number, token: string): TokenMeta {
-  return tokenMetaCache.get(`${chainId}:${token.toLowerCase()}`) ?? {}
+  const cached = tokenMetaCache.get(`${chainId}:${token.toLowerCase()}`)
+  if (!cached) {
+    return {}
+  }
+  const { nameAt, symbolAt, ...meta } = cached
+  const now = Date.now()
+  if (nameAt === undefined || now - nameAt > NAME_TTL) {
+    delete meta.name
+  }
+  if (symbolAt === undefined || now - symbolAt > NAME_TTL) {
+    delete meta.symbol
+  }
+  return meta
 }
 
 export function setCachedTokenMeta(chainId: number, token: string, meta: TokenMeta): void {
   if (Object.keys(meta).length === 0) {
     return // 没有新数据（如查询失败）时不写入空条目
   }
+  const defined: CachedMeta = { ...meta }
+  if ('name' in meta) {
+    defined.nameAt = Date.now()
+  }
+  if ('symbol' in meta) {
+    defined.symbolAt = Date.now()
+  }
   const key = `${chainId}:${token.toLowerCase()}`
-  tokenMetaCache.set(key, { ...tokenMetaCache.get(key), ...meta })
+  const merged = { ...tokenMetaCache.get(key), ...defined }
+  tokenMetaCache.delete(key) // 重新插入，保持“最近写入在后”的顺序
+  tokenMetaCache.set(key, merged)
+  if (tokenMetaCache.size > MAX_CACHED_TOKENS) {
+    tokenMetaCache.delete(tokenMetaCache.keys().next().value as string)
+  }
+  cacheListeners.forEach((listener) => listener())
 }
 
 /** 测试用：清空 decimals / symbol 缓存 */
 export function resetDecimalsCache(): void {
   tokenMetaCache.clear()
 }
+
+/** exportTokenMetaCache() 的结果，可以 JSON.stringify */
+export interface TokenMetaSnapshot {
+  version: 1
+  /** [chainId:小写地址, 信息]，按写入时间先后 */
+  entries: Array<[string, CachedMeta]>
+}
+
+/**
+ * 导出代币信息缓存（decimals / symbol / name / NFT 标准），可存到任意地方，下次用 importTokenMetaCache 导入，
+ * 页面刷新后不必重查精度。name / symbol 带写入时间，导入后仍按 1 小时过期。
+ *
+ * @param maxEntries 最多导出多少条（最近写入的优先），默认全部
+ */
+export function exportTokenMetaCache(maxEntries = Number.POSITIVE_INFINITY): TokenMetaSnapshot {
+  const entries = [...tokenMetaCache]
+  return { version: 1, entries: entries.slice(Math.max(0, entries.length - maxEntries)) }
+}
+
+/** 导入 exportTokenMetaCache 的结果；格式不对的数据忽略。已有的条目以缓存里的为准（更新） */
+export function importTokenMetaCache(snapshot: unknown): void {
+  const entries = (snapshot as Partial<TokenMetaSnapshot> | null)?.entries
+  if ((snapshot as Partial<TokenMetaSnapshot> | null)?.version !== 1 || !Array.isArray(entries)) {
+    return
+  }
+  for (const entry of entries) {
+    if (!Array.isArray(entry) || typeof entry[0] !== 'string' || !/^\d+:\S+$/.test(entry[0]) || !entry[1] || typeof entry[1] !== 'object') {
+      continue
+    }
+    const [rawKey, value] = entry as [string, CachedMeta]
+    // 与 getCachedTokenMeta 的 key 一致：地址部分小写
+    const separator = rawKey.indexOf(':')
+    const key = `${rawKey.slice(0, separator)}:${rawKey.slice(separator + 1).toLowerCase()}`
+    const meta: CachedMeta = {}
+    if (Number.isInteger(value.decimals) && (value.decimals as number) >= 0 && (value.decimals as number) <= 255) meta.decimals = value.decimals
+    if (typeof value.name === 'string' && typeof value.nameAt === 'number') {
+      meta.name = value.name
+      meta.nameAt = value.nameAt
+    }
+    if (typeof value.symbol === 'string' && typeof value.symbolAt === 'number') {
+      meta.symbol = value.symbol
+      meta.symbolAt = value.symbolAt
+    }
+    if (value.standard === 'ERC721' || value.standard === 'ERC1155' || value.standard === null) meta.standard = value.standard
+    if (Object.keys(meta).length && !tokenMetaCache.has(key)) {
+      tokenMetaCache.set(key, meta)
+    }
+  }
+  while (tokenMetaCache.size > MAX_CACHED_TOKENS) {
+    tokenMetaCache.delete(tokenMetaCache.keys().next().value as string)
+  }
+}
+
+/** persistTokenMetaCache 的存储：localStorage / sessionStorage 可以直接传，也可以自己实现 */
+export interface TokenMetaStore {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+}
+
+/**
+ * 把代币信息缓存持久化到同步的键值存储（如 localStorage）：调用时先读入，之后缓存有更新就防抖（1 秒）整体写回。
+ * 返回停止持久化的函数。存储读写出错（如超出配额）时忽略。
+ *
+ * ```ts
+ * persistTokenMetaCache(localStorage) // 刷新页面后不必重查 decimals
+ * ```
+ */
+export function persistTokenMetaCache(store: TokenMetaStore, options: { key?: string; maxEntries?: number } = {}): () => void {
+  const { key = 'w3lib:evm-token-meta', maxEntries = 5000 } = options
+  try {
+    const raw = store.getItem(key)
+    if (raw) {
+      importTokenMetaCache(JSON.parse(raw))
+    }
+  } catch {
+    // 数据损坏：忽略，之后会被覆盖
+  }
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const save = () => {
+    timer = undefined
+    try {
+      store.setItem(key, JSON.stringify(exportTokenMetaCache(maxEntries)))
+    } catch {
+      // 超出配额等：忽略
+    }
+  }
+  const listener = () => {
+    timer ??= setTimeout(save, 1000)
+  }
+  cacheListeners.add(listener)
+  return () => {
+    cacheListeners.delete(listener)
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      save()
+    }
+  }
+}

package/src/events.ts

@@ -0,0 +1,42 @@
+/** 一次对某个节点的请求（onRequest 的事件） */
+export interface RequestEvent {
+  /** 节点标识：URL 节点只取 host（不含 path / query，避免泄露 API Key）；钱包为 'wallet'，tronWeb 为 'tronWeb'，其他对象为 'provider' */
+  node: string
+  /** 'call' | 'getBalance' | 'getChainId' | 'getBlockNumber' | 'getLogs' */
+  method: string
+  /** 耗时（毫秒） */
+  ms: number
+  ok: boolean
+  /** 失败时的错误 */
+  error?: unknown
+  /** 本次请求按故障切换顺序的第几个节点（0 起）；大于 0 表示换过节点 */
+  attempt: number
+}
+
+export type RequestListener = (event: RequestEvent) => void
+
+const listeners = new Set<RequestListener>()
+
+/**
+ * 订阅所有节点请求（全局，对所有 Provider 生效），用于观察哪个节点返回、换过几次节点、每次耗时。返回取消订阅的函数。
+ *
+ * ```ts
+ * const off = onRequest((e) => console.log(e.node, e.method, e.ms, e.ok, e.attempt))
+ * ```
+ */
+export function onRequest(listener: RequestListener): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+export function emitRequest(event: RequestEvent): void {
+  for (const listener of listeners) {
+    try {
+      listener(event)
+    } catch {
+      // 监听函数出错不影响请求
+    }
+  }
+}

package/src/fallback.ts

@@ -3,17 +3,80 @@ import { isError, type TransactionRequest } from 'ethers'
 import type { EthersLikeProvider } from './aggregate.js'
 import { detectChainIdOf } from './detect.js'
 import { isExecutionError } from './errors.js'
-import { withTimeout } from './util.js'
+import { emitRequest } from './events.js'
+import { TimeoutError, withTimeout } from './util.js'
 
 export interface FallbackOptions {
   /** 单个节点单次请求超时（毫秒），超时视为该节点故障并换下一个。默认 10000；<= 0 表示不限制 */
   timeout?: number
-  /** 节点出错后跳过它的时长（毫秒），期间优先用其他节点。默认 30000 */
+  /**
+   * 节点迟迟不返回时，过多久（毫秒）同时请求下一个节点：原来的请求不取消，谁先成功用谁（与 ethers FallbackProvider 的 stallTimeout 相同）。
+   * 适合正常但偶尔较慢的节点：不必把 timeout 设得很短（正常的慢请求会被判成超时）。
+   * 默认 0（不提前请求，只在出错 / 超时后换节点）；只影响 call / getBalance，不影响 getLogs / getBlockNumber
+   */
+  stallTimeout?: number
+  /** 节点出错后跳过它的时长（毫秒），期间优先用其他节点。默认 30000。超时不算出错，同一节点连续 3 次超时才冷却 */
   cooldown?: number
 }
 
+/** FallbackRpc 每个节点的标识（resolveSource 传入；直接 new FallbackRpc 时可省略） */
+export interface FallbackNodeInfo {
+  /** 用于错误信息和 onRequest 事件的节点标识 */
+  label: string
+  /** 健康状态的 key：URL 字符串或节点对象。相同 key 的节点在所有 FallbackRpc 之间共享冷却状态 */
+  key: string | object
+}
+
+/** 节点健康状态，按节点（URL / 对象）全局共享：Provider 重建后刚失败过的节点仍排在后面 */
+interface Health {
+  failedAt: number
+  /** 连续超时次数 */
+  timeouts: number
+}
+
+/** 连续超时多少次后才冷却（偶尔慢不算坏节点） */
+const TIMEOUTS_BEFORE_COOLDOWN = 3
+const MAX_TRACKED_URLS = 1000
+const healthByUrl = new Map<string, Health>()
+const healthByObject = new WeakMap<object, Health>()
+
+function healthOf(key: string | object): Health {
+  if (typeof key === 'string') {
+    let health = healthByUrl.get(key)
+    if (!health) {
+      health = { failedAt: 0, timeouts: 0 }
+      healthByUrl.set(key, health)
+      if (healthByUrl.size > MAX_TRACKED_URLS) {
+        healthByUrl.delete(healthByUrl.keys().next().value as string)
+      }
+    }
+    return health
+  }
+  let health = healthByObject.get(key)
+  if (!health) {
+    health = { failedAt: 0, timeouts: 0 }
+    healthByObject.set(key, health)
+  }
+  return health
+}
+
+/** 测试用：清空全局的节点健康状态 */
+export function resetNodeHealth(): void {
+  healthByUrl.clear()
+}
+
+/** 所有节点都失败（多节点时）：errors 是每个节点的标识和失败原因，按尝试顺序 */
+export class AllNodesFailedError extends Error {
+  constructor(readonly errors: ReadonlyArray<{ node: string; error: unknown }>) {
+    super(`All RPC nodes failed: ${errors.map((e) => `${e.node}: ${errorText(e.error)}`).join(' | ')}`, { cause: errors[errors.length - 1]?.error })
+    this.name = 'AllNodesFailedError'
+  }
+}
+
 /**
- * 多节点故障切换：按顺序使用节点，出错或超时换下一个；出错的节点在 cooldown 内排到最后。
+ * 多节点故障切换：按顺序使用节点，出错或超时换下一个；出错的节点在 cooldown 内排到最后（超时只换节点，连续 3 次才冷却）。
+ * 设置了 stallTimeout 时，节点迟迟不返回就同时请求下一个，谁先成功用谁。所有节点都失败时抛 AllNodesFailedError（单节点时抛原始错误）。
+ * 冷却状态按节点全局共享，每次请求都会触发 onRequest 事件。
  *
  * 与 ethers FallbackProvider 相比：
  * - 没有首次请求前对所有节点的 getBlockNumber 同步，一个卡住的节点不会拖住第一次查询
@@ -22,8 +85,11 @@ export interface FallbackOptions {
 export class FallbackRpc implements EthersLikeProvider {
   readonly #nodes: EthersLikeProvider[]
   readonly #timeout: number
+  readonly #stallTimeout: number
   readonly #cooldown: number
-  readonly #failedAt: number[]
+  readonly #labels: string[]
+  /** 健康状态的 key；每次用时再从全局表里取（表淘汰条目后，各实例仍取到同一个对象） */
+  readonly #healthKeys: Array<string | object>
   /** 上次 getLogs 成功的节点 */
   #logsNode = -1
   /** 上次成功的节点连续被限频的次数 */
@@ -31,14 +97,16 @@ export class FallbackRpc implements EthersLikeProvider {
   /** getLogs 超时 / 连不上的时间，只影响 getLogs 的节点顺序 */
   readonly #logsFailedAt: number[]
 
-  constructor(nodes: EthersLikeProvider[], options: FallbackOptions = {}) {
+  constructor(nodes: EthersLikeProvider[], options: FallbackOptions = {}, info?: readonly FallbackNodeInfo[]) {
     if (!nodes.length) {
       throw new Error('FallbackRpc requires at least one node')
     }
     this.#nodes = nodes
     this.#timeout = options.timeout ?? 10_000
+    this.#stallTimeout = options.stallTimeout ?? 0
     this.#cooldown = options.cooldown ?? 30_000
-    this.#failedAt = nodes.map(() => 0)
+    this.#labels = nodes.map((_, i) => info?.[i]?.label ?? `node${i}`)
+    this.#healthKeys = nodes.map((node, i) => info?.[i]?.key ?? node)
     this.#logsFailedAt = nodes.map(() => 0)
   }
 
@@ -47,16 +115,34 @@ export class FallbackRpc implements EthersLikeProvider {
   }
 
   call(tx: TransactionRequest): Promise<string> {
-    return this.#run((node) => node.call(tx))
+    return this.#run('call', (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))
+    return this.#run('getBalance', (node) => node.getBalance(address, blockTag))
   }
 
   /** 按节点顺序探测 chainId（节点需实现 getChainId，见 detect.ts） */
   getChainId(): Promise<number> {
-    return this.#run((node) => detectChainIdOf(node))
+    return this.#run('getChainId', (node) => detectChainIdOf(node))
+  }
+
+  /** 对第 index 个节点发一次请求（带超时），并触发 onRequest 事件 */
+  async #attempt<T>(method: string, index: number, attempt: number, fn: (node: EthersLikeProvider) => Promise<T>, timeout = this.#timeout): Promise<T> {
+    const started = Date.now()
+    try {
+      const result = await withTimeout(Promise.resolve().then(() => fn(this.#nodes[index] as EthersLikeProvider)), timeout)
+      emitRequest({ node: this.#labels[index] as string, method, ms: Date.now() - started, ok: true, attempt })
+      return result
+    } catch (err) {
+      emitRequest({ node: this.#labels[index] as string, method, ms: Date.now() - started, ok: false, error: err, attempt })
+      throw err
+    }
+  }
+
+  /** 单节点：直接请求（getLogs / getBlockNumber 不走多节点的特殊逻辑），抛原始错误 */
+  #single<T>(method: string, fn: (node: EthersLikeProvider) => Promise<T>): Promise<T> {
+    return this.#attempt(method, 0, 0, fn)
   }
 
   /**
@@ -64,14 +150,22 @@ export class FallbackRpc implements EthersLikeProvider {
    * 不支持 getBlockNumber 的节点跳过，失败也不让节点进入冷却（不影响 call / getBalance）
    */
   async getBlockNumber(): Promise<number> {
+    if (this.#nodes.length === 1) {
+      const node = this.#nodes[0] as EthersLikeProvider
+      if (!node.getBlockNumber) {
+        throw new Error('getBlockNumber is not supported by this provider')
+      }
+      return this.#single('getBlockNumber', (n) => (n.getBlockNumber as () => Promise<number>)())
+    }
     let lastError: unknown = new Error('No node supports getBlockNumber')
+    let attempt = 0
     for (const index of this.#preferLogsNode(this.#order())) {
       const node = this.#nodes[index] as EthersLikeProvider
       if (!node.getBlockNumber) {
         continue
       }
       try {
-        return await withTimeout(node.getBlockNumber(), this.#timeout)
+        return await this.#attempt('getBlockNumber', index, attempt++, (n) => (n.getBlockNumber as () => Promise<number>)())
       } catch (err) {
         lastError = err
       }
@@ -86,16 +180,25 @@ export class FallbackRpc implements EthersLikeProvider {
    * - 在用的节点被限频时直接抛出（连续 3 次后才换节点），其他情况全部失败时抛出；GetLogsError 带上每个节点的错误
    */
   async getLogs(filter: Parameters<NonNullable<EthersLikeProvider['getLogs']>>[0]): Promise<Awaited<ReturnType<NonNullable<EthersLikeProvider['getLogs']>>>> {
+    type GetLogs = NonNullable<EthersLikeProvider['getLogs']>
+    if (this.#nodes.length === 1) {
+      // 单节点：原样请求、抛原始错误（与不经过 FallbackRpc 时一致）
+      if (!this.#nodes[0]?.getLogs) {
+        throw new Error('getLogs is not supported by this provider')
+      }
+      return this.#single('getLogs', (n) => (n.getLogs as GetLogs)(filter))
+    }
     const errors: unknown[] = []
     let preferred: unknown
     const sticky = this.#logsNode
+    let attempt = 0
     for (const index of this.#preferLogsNode(this.#order(this.#logsFailedAt))) {
       const node = this.#nodes[index] as EthersLikeProvider
       if (!node.getLogs) {
         continue
       }
       try {
-        const logs = await withTimeout(node.getLogs(filter), this.#timeout)
+        const logs = await this.#attempt('getLogs', index, attempt++, (n) => (n.getLogs as GetLogs)(filter))
         this.#logsNode = index
         this.#logsFailedAt[index] = 0
         this.#logsThrottled = 0
@@ -128,26 +231,83 @@ export class FallbackRpc implements EthersLikeProvider {
     throw new GetLogsError(errors, preferred)
   }
 
-  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
+  /**
+   * 按顺序请求节点：出错（非确定性错误）或超时立即换下一个；设置了 stallTimeout 时，
+   * 当前节点超过 stallTimeout 还没返回也会同时请求下一个（已发出的请求不取消），第一个成功的结果胜出。
+   * 出错的节点进入冷却；超时只换节点，同一节点连续 3 次超时才冷却（冷启动的大批量查询偶尔慢，不应把健康的节点踢到后面）；
+   * 节点还没有请求的区块（minBlock 重查时落后的节点）也只换节点、不冷却。
+   * 确定性错误（revert、参数错误等）直接抛出；所有节点都失败时抛 AllNodesFailedError（单节点时抛原始错误）。
+   */
+  #run<T>(method: string, fn: (node: EthersLikeProvider) => Promise<T>): Promise<T> {
+    const order = this.#order()
+    return new Promise<T>((resolve, reject) => {
+      let next = 0
+      let running = 0
+      let settled = false
+      const errors: Array<{ node: string; error: unknown }> = []
+      let stallTimer: ReturnType<typeof setTimeout> | undefined
+      const finish = (done: () => void) => {
+        settled = true
+        clearTimeout(stallTimer)
+        done()
+      }
+      const fail = () => {
+        const only = errors.length === 1 && this.#nodes.length === 1
+        finish(() => reject(only ? errors[0]?.error : new AllNodesFailedError(errors)))
+      }
+      const launch = (): boolean => {
+        if (settled || next >= order.length) {
+          return false
         }
-        this.#failedAt[index] = Date.now()
-        lastError = err
+        const attempt = next++
+        const index = order[attempt] as number
+        const health = healthOf(this.#healthKeys[index] as string | object)
+        running++
+        clearTimeout(stallTimer)
+        if (this.#stallTimeout > 0 && next < order.length) {
+          stallTimer = setTimeout(launch, this.#stallTimeout)
+        }
+        this.#attempt(method, index, attempt, fn).then(
+          (result) => {
+            running--
+            health.failedAt = 0
+            health.timeouts = 0
+            if (!settled) {
+              finish(() => resolve(result))
+            }
+          },
+          (err: unknown) => {
+            running--
+            const deterministic = isDeterministic(err)
+            if (err instanceof TimeoutError) {
+              if (++health.timeouts >= TIMEOUTS_BEFORE_COOLDOWN) {
+                health.failedAt = Date.now()
+                health.timeouts = 0
+              }
+            } else if (!deterministic && !isBehind(err)) {
+              health.failedAt = Date.now()
+            }
+            if (settled) {
+              return
+            }
+            if (deterministic) {
+              finish(() => reject(err))
+              return
+            }
+            errors.push({ node: this.#labels[index] as string, error: err })
+            if (!launch() && running === 0) {
+              fail()
+            }
+          },
+        )
+        return true
       }
-    }
-    throw lastError
+      launch()
+    })
   }
 
   /** 健康的节点按原顺序在前，冷却中的按出错时间先后排在后面（全挂时也都会再试一次） */
-  #order(failedAt: readonly number[] = this.#failedAt): number[] {
+  #order(failedAt: readonly number[] = this.#healthKeys.map((key) => healthOf(key).failedAt)): number[] {
     const now = Date.now()
     const healthy: number[] = []
     const cooling: number[] = []
@@ -198,6 +358,13 @@ function isRateLimited(err: unknown): boolean {
   return /too many requests|rate.?limit|\b429\b/i.test(errorText(err))
 }
 
+/**
+ * 节点还没有请求的区块（minBlock 按指定区块重查时，落后的节点会这样报错）：只换节点、不冷却——节点本身是健康的，只是慢一两个块
+ */
+function isBehind(err: unknown): boolean {
+  return /header not found|unknown block|block not found|block .*not (yet )?(available|found)|requested block .*(ahead|future)|after last accepted block/i.test(errorText(err))
+}
+
 /** 换节点也不会变的错误：合约执行结果、参数错误、用户拒绝等 */
 function isDeterministic(err: unknown): boolean {
   return (