@w3lib/evm-batch-call 0.3.0 → 0.4.1

package/src/fallback.ts

@@ -3,17 +3,108 @@ 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
+  /** 对象节点按链分开记健康状态（钱包可以切链） */
+  chainId?: number
+}
+
+/** call 的结果校验：返回 false 时视为这个节点的结果不可用（如返回空数据），换下一个节点、不冷却 */
+export interface CallValidation {
+  accept?: (result: string) => boolean
+  /**
+   * 最多几个节点的结果没通过校验就不再换节点（默认 2：两个节点结果一致，足以确认是合约本身的问题，
+   * 不必把所有节点挨个试一遍——链上确实没有合约时，每个节点都会这样）
+   */
+  maxInvalid?: number
+}
+
+/** 节点返回的结果没通过校验（如 eth_call 返回 0x / 无法解码）：换节点，不冷却（可能是合约确实不存在，所有节点都会这样） */
+export class InvalidResultError extends Error {
+  constructor(readonly result: string) {
+    super(`Unusable eth_call result: ${result.length > 66 ? `${result.slice(0, 66)}…` : result}`)
+    this.name = 'InvalidResultError'
+  }
+}
+
+/** 节点健康状态，按节点（URL / 对象）全局共享：Provider 重建后刚失败过的节点仍排在后面 */
+interface Health {
+  failedAt: number
+  /** 连续超时次数 */
+  timeouts: number
+  /** 开了 stallTimeout 时，在并发竞争中输给后发节点的时间（慢但没出错）：冷却期内排在健康节点之后 */
+  slowAt: number
+}
+
+/** 连续超时多少次后才冷却（偶尔慢不算坏节点） */
+const TIMEOUTS_BEFORE_COOLDOWN = 3
+const MAX_TRACKED_URLS = 1000
+const healthByUrl = new Map<string, Health>()
+/** 对象节点（钱包、ethers Provider）按链分开记：钱包在一条链上出错不影响它在其他链上的排序 */
+const healthByObject = new WeakMap<object, Map<number | undefined, Health>>()
+
+function healthOf(key: string | object, scope?: number): Health {
+  if (typeof key === 'string') {
+    let health = healthByUrl.get(key)
+    if (!health) {
+      health = { failedAt: 0, timeouts: 0, slowAt: 0 }
+      healthByUrl.set(key, health)
+      if (healthByUrl.size > MAX_TRACKED_URLS) {
+        healthByUrl.delete(healthByUrl.keys().next().value as string)
+      }
+    }
+    return health
+  }
+  let byScope = healthByObject.get(key)
+  if (!byScope) {
+    byScope = new Map()
+    healthByObject.set(key, byScope)
+  }
+  let health = byScope.get(scope)
+  if (!health) {
+    health = { failedAt: 0, timeouts: 0, slowAt: 0 }
+    byScope.set(scope, 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 +113,12 @@ 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>
+  readonly #healthScopes: Array<number | undefined>
   /** 上次 getLogs 成功的节点 */
   #logsNode = -1
   /** 上次成功的节点连续被限频的次数 */
@@ -31,14 +126,17 @@ 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.#healthScopes = nodes.map((_, i) => info?.[i]?.chainId)
     this.#logsFailedAt = nodes.map(() => 0)
   }
 
@@ -46,17 +144,51 @@ export class FallbackRpc implements EthersLikeProvider {
     return this.#nodes
   }
 
-  call(tx: TransactionRequest): Promise<string> {
-    return this.#run((node) => node.call(tx))
+  /** eth_call；validation.accept 返回 false 的结果视为这个节点不可用，换下一个节点（不冷却） */
+  call(tx: TransactionRequest, validation?: CallValidation): Promise<string> {
+    const accept = validation?.accept
+    return this.#run(
+      'call',
+      (node) =>
+        node.call(tx).then((result) => {
+          if (accept && !accept(result)) {
+            throw new InvalidResultError(result)
+          }
+          return result
+        }),
+      accept ? (validation?.maxInvalid ?? 2) : Number.POSITIVE_INFINITY,
+    )
+  }
+
+  #health(index: number): Health {
+    return healthOf(this.#healthKeys[index] as string | object, this.#healthScopes[index])
   }
 
   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 +196,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 +226,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,32 +277,115 @@ 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>, maxInvalid = Number.POSITIVE_INFINITY): Promise<T> {
+    const order = this.#order()
+    let invalid = 0
+    return new Promise<T>((resolve, reject) => {
+      let next = 0
+      let running = 0
+      let settled = false
+      /** 正在进行的请求（按发出顺序）：有节点胜出时，比它先发出、还没返回的节点记一次“慢” */
+      const inFlight: Array<{ index: number; attempt: number }> = []
+      const done = (index: number) => inFlight.splice(inFlight.findIndex((f) => f.index === index), 1)
+      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 = this.#health(index)
+        running++
+        inFlight.push({ index, attempt })
+        clearTimeout(stallTimer)
+        if (this.#stallTimeout > 0 && next < order.length) {
+          stallTimer = setTimeout(launch, this.#stallTimeout)
+        }
+        this.#attempt(method, index, attempt, fn).then(
+          (result) => {
+            running--
+            done(index)
+            health.failedAt = 0
+            health.timeouts = 0
+            if (!settled) {
+              health.slowAt = 0
+              // 先发出却还没返回的节点输掉了竞争：记一次慢，冷却期内排在健康节点之后（之后返回成功也不清除）
+              inFlight.filter((f) => f.attempt < attempt).forEach((f) => (this.#health(f.index).slowAt = Date.now()))
+              finish(() => resolve(result))
+            }
+          },
+          (err: unknown) => {
+            running--
+            done(index)
+            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) && !(err instanceof InvalidResultError) && !isNullResult(err)) {
+              health.failedAt = Date.now()
+            }
+            if (settled) {
+              return
+            }
+            if (deterministic) {
+              finish(() => reject(err))
+              return
+            }
+            errors.push({ node: this.#labels[index] as string, error: err })
+            // 结果没通过校验的节点够数了（已能确认是合约本身的问题）：不再换节点，等进行中的请求结束
+            const enough = err instanceof InvalidResultError && ++invalid >= maxInvalid
+            if ((enough || !launch()) && running === 0) {
+              fail()
+            }
+          },
+        )
+        return true
       }
-    }
-    throw lastError
+      launch()
+    })
   }
 
-  /** 健康的节点按原顺序在前，冷却中的按出错时间先后排在后面（全挂时也都会再试一次） */
-  #order(failedAt: readonly number[] = this.#failedAt): number[] {
+  /**
+   * 健康的节点按原顺序在前；最近在竞争中输过的慢节点其次；冷却中的按出错时间先后排在最后（全挂时也都会再试一次）。
+   * 传入 failedAt 时（getLogs 自己的冷却表）不考虑慢节点
+   */
+  #order(failedAt?: readonly number[]): number[] {
     const now = Date.now()
+    const health = this.#nodes.map((_, i) => this.#health(i))
+    const failed = failedAt ?? health.map((h) => h.failedAt)
     const healthy: number[] = []
+    const slow: number[] = []
     const cooling: number[] = []
-    failedAt.forEach((at, i) => (at && now - at < this.#cooldown ? cooling : healthy).push(i))
-    cooling.sort((a, b) => (failedAt[a] as number) - (failedAt[b] as number))
-    return [...healthy, ...cooling]
+    failed.forEach((at, i) => {
+      if (at && now - at < this.#cooldown) {
+        cooling.push(i)
+      } else if (!failedAt && (health[i] as Health).slowAt && now - (health[i] as Health).slowAt < this.#cooldown) {
+        slow.push(i)
+      } else {
+        healthy.push(i)
+      }
+    })
+    cooling.sort((a, b) => (failed[a] as number) - (failed[b] as number))
+    return [...healthy, ...slow, ...cooling]
   }
 
   /** 上次 getLogs 成功的节点（不在 getLogs 冷却中时）排到最前 */
@@ -198,12 +430,29 @@ function isRateLimited(err: unknown): boolean {
   return /too many requests|rate.?limit|\b429\b/i.test(errorText(err))
 }
 
-/** 换节点也不会变的错误：合约执行结果、参数错误、用户拒绝等 */
+/**
+ * 节点还没有请求的区块（minBlock 按指定区块重查时，落后的节点会这样报错）：只换节点、不冷却——节点本身是健康的，只是慢一两个块
+ */
+function isBehind(err: unknown): boolean {
+  return BEHIND_RE.test(errorText(err))
+}
+
+// 各节点对“还没有这个区块”的报错（2026-10 对内置节点实测）：geth / erigon、Arbitrum 系、X Layer、Mantle、zkSync、Winchain 等
+const BEHIND_RE =
+  /header not found|unknown block|block not found|block .*not (yet )?(available|found)|requested block .*(ahead|future|above)|after last accepted block|unsupported block number|block is out of range|above the latest|height must be less than or equal to the head|doesn't exist yet|block number .*(exceeds|greater than|higher than)|future block/i
+
+/**
+ * 节点返回 result: null（ethers 解析响应时报 INVALID_ARGUMENT，值为 null）：换节点、不冷却。
+ * 只认 null——调用方传入 undefined 等非法参数时值是 undefined，仍是确定性错误，不能拿去每个节点重试
+ */
+function isNullResult(err: unknown): boolean {
+  return isError(err, 'INVALID_ARGUMENT') && (err as { value?: unknown }).value === null
+}
+
+/** 换节点也不会变的错误：合约执行结果、参数错误、用户拒绝等（节点返回 null 除外，见 isNullResult） */
 function isDeterministic(err: unknown): boolean {
-  return (
-    isExecutionError(err) ||
-    isError(err, 'INVALID_ARGUMENT') ||
-    isError(err, 'ACTION_REJECTED') ||
-    isError(err, 'NUMERIC_FAULT')
-  )
+  if (isError(err, 'INVALID_ARGUMENT')) {
+    return !isNullResult(err)
+  }
+  return isExecutionError(err) || isError(err, 'ACTION_REJECTED') || isError(err, 'NUMERIC_FAULT')
 }

package/src/index.ts

@@ -1,80 +1,33 @@
 export { Contract, bindCall, type BoundMethod, type ContractAbi, type ContractRunner } from './contract.js'
-export {
-  getTransferScanState,
-  keyValueScanStorage,
-  memoryScanStorage,
-  transferScan,
-  type TransferScanOptions,
-  type TransferScanState,
-  type TransferScanStorage,
-} from './scan.js'
 export { GetLogsError } from './fallback.js'
-export {
-  ALCHEMY_NETWORKS,
-  COINGECKO_PLATFORMS,
-  DEFILLAMA_CHAINS,
-  alchemy,
-  clearTokenListCache,
-  coingeckoTokenList,
-  combine,
-  defaultTokenSource,
-  defillamaPrices,
-  firstAvailable,
-  metamaskTokenList,
-  nodereal,
-  staticTokens,
-  tokenList,
-  type DiscoveredToken,
-  type OwnedToken,
-  type OwnerTokensOptions,
-  type PriceSource,
-  type PriceSourceContext,
-  type TokenSource,
-  type TokenSourceContext,
-} from './owner.js'
 export {
   getAllowances,
   getBalances,
-  getErc1155Balances,
-  getNftBalances,
-  getNftCollections,
-  getNftOwners,
-  getNftTokenUris,
-  getOwnerTokens,
+  getMultiBalances,
   getTokens,
+  type GetAllowancesOptions,
   type GetBalancesOptions,
-  type GetNftCollectionsOptions,
-  type GetNftTokenUrisOptions,
-  type GetOwnerTokensOptions,
   type GetTokensOptions,
   type ShortcutOptions,
   type ShortcutProviderOptions,
 } from './shortcuts.js'
-export {
-  DEFAULT_NFT_COLLECTION_FIELDS,
-  ERC1155_ABI,
-  ERC721_ABI,
-  type DefaultNftCollectionField,
-  type Erc1155Balance,
-  type NftBalance,
-  type NftCollection,
-  type NftCollectionField,
-  type NftCollectionsOptions,
-  type NftItem,
-  type NftOwner,
-  type NftStandard,
-  type NftTokenUri,
-  type NftTokenUriOptions,
-} from './nft.js'
-export { NATIVE_CURRENCIES, getNativeCurrency, type NativeCurrency } from './chains.js'
+export { NATIVE_BALANCE_MODES, NATIVE_CURRENCIES, getNativeBalanceMode, getNativeCurrency, type NativeCurrency } from './chains.js'
 export { clearChainIdCache, detectChainId } from './detect.js'
 export {
   DEFAULT_NATIVE_TOKENS,
   ERC20_ABI,
   NATIVE_TOKEN,
+  exportTokenMetaCache,
   formatAmount,
+  formatUnits,
+  importTokenMetaCache,
+  persistTokenMetaCache,
+  type TokenMetaSnapshot,
+  type TokenMetaStore,
   type BalanceToken,
   type Erc20Contract,
+  type RawTokenAllowance,
+  type RawTokenBalance,
   type TokenBalance,
   type TokenAllowance,
   MAX_UINT256,
@@ -86,7 +39,10 @@ export {
 } from './erc20.js'
 export {
   Provider,
+  type AllowancesOptions,
   type BalancesOptions,
+  type BalancesQuery,
+  type BlockOptions,
   type CallInput,
   type CallResults,
   type ProviderConfig,
@@ -108,10 +64,12 @@ export {
   type TronWebLike,
 } from './tron.js'
 export { CallFailedError, decodeRevertReason, isExecutionError } from './errors.js'
-export { FallbackRpc, type FallbackOptions } from './fallback.js'
+export { AllNodesFailedError, FallbackRpc, type FallbackNodeInfo, type FallbackOptions } from './fallback.js'
+export { onRequest, type RequestEvent, type RequestListener } from './events.js'
+export { watchBalances, type WatchBalancesOptions } from './watch.js'
 export { ChainCheckedProvider, 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 { BlockTag, CallOverrides, EthersLikeProvider, NativeBalanceMode } from './aggregate.js'
 export type { BatchOptions } from './batcher.js'
-export type { BoundCall, Call, FailableCall, Params, RawResult } from './call.js'
+export type { BoundCall, Call, FailableCall, FailureReason, Params, RawResult, Settled } from './call.js'

package/src/multicall.ts

@@ -47,12 +47,44 @@ const MULTICALL3: Record<number, Multicall> = {
   43114: { address: CANONICAL, block: 11907934 },
   80001: { address: CANONICAL, block: 25444704 },
   421611: { address: CANONICAL, block: 10228837 },
-  5000: { address: '0xd77b59d4cb13bea71f3cc093e401720867355d6e', block: 18877383 },
+  // Mantle：标准地址上的合约字节码与其他链不同，但 aggregate3 / getBlockNumber / getEthBalance 行为一致（2026-10 实测）；
+  // ethcall 表里的 0xd77b…5d6e 调 aggregate3 会 revert
+  5000: { address: CANONICAL, block: 304717 },
   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 },
+  // Blast：ethcall 表里的 0x2392…cdcb1 调 aggregate3 会 revert，标准地址可用（2026-10 实测）
+  81457: { address: CANONICAL, block: 88189 },
+
+  // ---- 2026-10 实测补充：标准地址上 aggregate3 可用、区块号与节点一致 ----
+  // 部署区块查到的按实际填写；节点不提供历史状态（或忽略区块参数）查不到的，保守地填核实时的区块：
+  // 更早的历史查询走 deployless，最新状态照常用合约
+  25: { address: CANONICAL, block: 98990812 }, // Cronos，部署区块未查到
+  106: { address: CANONICAL, block: 70377223 }, // Velas，部署区块未查到
+  130: { address: CANONICAL, block: 60854543 }, // Unichain，部署区块未查到
+  143: { address: CANONICAL, block: 9248132 }, // Monad
+  204: { address: CANONICAL, block: 193943883 }, // opBNB，部署区块未查到
+  288: { address: CANONICAL, block: 40299030 }, // Boba，部署区块未查到
+  321: { address: CANONICAL, block: 56352410 }, // KCC，部署区块未查到
+  592: { address: CANONICAL, block: 761794 }, // Astar
+  988: { address: CANONICAL, block: 42479473 }, // Stable，部署区块未查到
+  999: { address: CANONICAL, block: 48135400 }, // HyperEVM，部署区块未查到
+  1116: { address: CANONICAL, block: 6988931 }, // Core
+  2818: { address: CANONICAL, block: 3654913 }, // Morph
+  4663: { address: CANONICAL, block: 84683398 }, // Robinhood Chain，部署区块未查到
+  4689: { address: CANONICAL, block: 53225909 }, // IoTeX，部署区块未查到
+  9745: { address: CANONICAL, block: 0 }, // Plasma，创世预置
+  34443: { address: CANONICAL, block: 2465882 }, // Mode
+  57073: { address: CANONICAL, block: 58104502 }, // Ink，部署区块未查到
+  59144: { address: CANONICAL, block: 42 }, // Linea
+  80094: { address: CANONICAL, block: 0 }, // Berachain，创世预置
+  534352: { address: CANONICAL, block: 14 }, // Scroll
+  86233268: { address: CANONICAL, block: 10854614 }, // Winchain，部署区块未查到
+  // 以下两条链不支持 deployless（合约创建式 eth_call 返回空 / 格式不对），只能用 Multicall3；
+  // 早于部署区块的历史查询会失败
+  42262: { address: CANONICAL, block: 22380155 }, // Oasis Emerald，部署区块未查到
+  1313161554: { address: CANONICAL, block: 62907816 }, // Aurora
 }
 
 export function getMulticall3(chainId: number): Multicall | null {

package/src/nft.ts

@@ -118,6 +118,7 @@ function expandUri(uri: string, tokenId: bigint, gateway?: string): string {
   return expanded
 }
 
+/** 批量查 ERC721 持有人（ownerOf），可混合多个集合：`await nftOwners(multi, [{ contract: BAYC, tokenId: 1 }])` */
 export async function nftOwners(provider: Provider, items: readonly NftItem[], overrides?: CallOverrides): Promise<NftOwner[]> {
   // Tron 上返回 T 开头的地址，方便与 tronWeb.defaultAddress.base58 等直接比较
   const tron = isTronChain(await provider.getChainId())
@@ -132,6 +133,7 @@ export async function nftOwners(provider: Provider, items: readonly NftItem[], o
   })
 }
 
+/** 批量查 ERC721 持有数量（balanceOf）：`await nftBalances(multi, user, [BAYC, MAYC])` */
 export async function nftBalances(
   provider: Provider,
   owner: string,
@@ -146,6 +148,7 @@ export async function nftBalances(
   })
 }
 
+/** 批量查 ERC1155 余额：`await erc1155Balances(multi, user, [{ contract, tokenId: 1 }])` */
 export async function erc1155Balances(
   provider: Provider,
   owner: string,
@@ -169,6 +172,7 @@ export async function erc1155Balances(
   })
 }
 
+/** 批量查 NFT 元数据地址：兼容 ERC721 tokenURI 与 ERC1155 uri（{id} 按规范替换），可转换 ipfs:// */
 export async function nftTokenUris(provider: Provider, items: readonly NftItem[], options: NftTokenUriOptions = {}): Promise<NftTokenUri[]> {
   const { ipfsGateway, ...overrides } = options
   const chainId = await provider.getChainId()
@@ -227,6 +231,7 @@ export async function nftTokenUris(provider: Provider, items: readonly NftItem[]
   })
 }
 
+/** 批量查 NFT 集合信息（标准 / name / symbol / totalSupply），字段可选 */
 export async function nftCollections<F extends NftCollectionField = DefaultNftCollectionField>(
   provider: Provider,
   collections: readonly string[],

package/src/owner.ts

@@ -1,5 +1,5 @@
 import type { CallOverrides } from './aggregate.js'
-import { NATIVE_TOKEN, formatAmount, type BalanceToken } from './erc20.js'
+import { NATIVE_TOKEN, formatUnits, type BalanceToken } from './erc20.js'
 import type { Provider } from './provider.js'
 import { transferScan, type TransferScanOptions } from './scan.js'
 import { isTronAddress } from './tron.js'
@@ -555,6 +555,15 @@ export interface OwnedToken {
   source: string
 }
 
+/**
+ * 列出持有人拥有的代币（资产列表）：从代币来源拿候选代币，再用 multicall 在链上核对余额。
+ * 默认来源是公开代币列表，**只能发现列表里的代币**，局限性见 README「资产列表」一节。
+ *
+ * @deprecated 不推荐使用：EVM 链上无法只靠节点可靠地列出地址持有的全部代币，这个方法只是尽力而为——
+ * 默认来源只能发现公开列表里的代币，依赖第三方免费服务（可能限流、改格式或停止服务），要查几千个代币的余额、耗时数秒，
+ * 价格也不一定可信；传 `alchemy` / `nodereal` 来源能查全，但同样受第三方服务的额度和可用性约束。
+ * 已知要查哪些代币时请用 `getBalances`；需要可靠的完整持仓请直接接入索引服务的接口或自己的索引。局限性详见 README「资产列表」。
+ */
 export async function ownerTokens(provider: Provider, owner: string, options: OwnerTokensOptions = {}): Promise<OwnedToken[]> {
   const { source: baseSource = defaultTokenSource(), prices, minUsd, includeNative = true, fetch: fetchOption, scanTransfers, ...overrides } = options
   const source = scanTransfers ? combine(baseSource, transferScan(scanTransfers === true ? {} : scanTransfers)) : baseSource
@@ -606,7 +615,7 @@ export async function ownerTokens(provider: Provider, owner: string, options: Ow
       return []
     }
     const decimals = chain.decimals
-    const formatted = decimals === balance.decimals ? balance.formatted : formatAmount(BigInt(balance.balance), decimals)
+    const formatted = decimals === balance.decimals ? balance.formatted : formatUnits(BigInt(balance.balance), decimals)
     const price = priceMap.get(addressKey(meta.address))
     return [
       {