@w3lib/evm-batch-call 0.2.0 → 0.4.0

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,17 +85,29 @@ 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
+  /** 上次成功的节点连续被限频的次数 */
+  #logsThrottled = 0
+  /** 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)
   }
 
   get nodes(): readonly EthersLikeProvider[] {
@@ -40,45 +115,254 @@ 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))
   }
 
-  async #run<T>(fn: (node: EthersLikeProvider) => Promise<T>): Promise<T> {
-    let lastError: unknown
-    for (const index of this.#order()) {
+  /** 对第 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)
+  }
+
+  /**
+   * 当前区块号。优先问上次 getLogs 成功的节点（增量扫描时区块号和日志来自同一个节点，不会因节点间的高度差漏扫）；
+   * 不支持 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 {
-        const result = await withTimeout(fn(this.#nodes[index] as EthersLikeProvider), this.#timeout)
-        this.#failedAt[index] = 0
-        return result
+        return await this.#attempt('getBlockNumber', index, attempt++, (n) => (n.getBlockNumber as () => Promise<number>)())
       } catch (err) {
-        if (isDeterministic(err)) {
-          throw err
-        }
-        this.#failedAt[index] = Date.now()
         lastError = err
       }
     }
     throw lastError
   }
 
+  /**
+   * 依次尝试支持 getLogs 的节点。与其他请求不同：
+   * - getLogs 失败多半是“区块范围超限 / 节点不开放这个方法”，不代表节点故障，所以不影响 call / getBalance 的节点顺序；
+   *   超时 / 连不上的节点只在 getLogs 里排到后面（冷却期内），上次成功的节点排在最前
+   * - 在用的节点被限频时直接抛出（连续 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 this.#attempt('getLogs', index, attempt++, (n) => (n.getLogs as GetLogs)(filter))
+        this.#logsNode = index
+        this.#logsFailedAt[index] = 0
+        this.#logsThrottled = 0
+        return logs
+      } catch (err) {
+        if (isError(err, 'INVALID_ARGUMENT')) {
+          throw err
+        }
+        if (!isAlive(err)) {
+          // 超时 / 连不上：排到后面；如果是上次成功的节点，不再优先用它
+          this.#logsFailedAt[index] = Date.now()
+          if (index === this.#logsNode) {
+            this.#logsNode = -1
+          }
+        } else if (index === sticky) {
+          preferred = err
+          if (isRateLimited(err)) {
+            // 在用的节点只是限频：直接抛出让调用方退避重试（其他节点多半本来就不能用，逐个试只会更慢）；
+            // 连续 3 次就不再优先用它，试其他节点
+            if (++this.#logsThrottled < 3) {
+              throw new GetLogsError([err], err)
+            }
+            this.#logsThrottled = 0
+            this.#logsNode = -1
+          }
+        }
+        errors.push(err)
+      }
+    }
+    throw new GetLogsError(errors, preferred)
+  }
+
+  /**
+   * 按顺序请求节点：出错（非确定性错误）或超时立即换下一个；设置了 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
+        }
+        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
+      }
+      launch()
+    })
+  }
+
   /** 健康的节点按原顺序在前，冷却中的按出错时间先后排在后面（全挂时也都会再试一次） */
-  #order(): number[] {
+  #order(failedAt: readonly number[] = this.#healthKeys.map((key) => healthOf(key).failedAt)): 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))
+    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]
   }
+
+  /** 上次 getLogs 成功的节点（不在 getLogs 冷却中时）排到最前 */
+  #preferLogsNode(order: number[]): number[] {
+    const index = this.#logsNode
+    const at = this.#logsFailedAt[index]
+    if (index < 0 || (at && Date.now() - at < this.#cooldown)) {
+      return order
+    }
+    return [index, ...order.filter((i) => i !== index)]
+  }
+}
+
+/**
+ * getLogs 失败时抛出（所有节点都失败，或在用的节点被限频），errors 是各节点的错误；
+ * preferred 是上次成功的节点这次返回的错误（它最能说明问题：其他节点可能一直就不能用）
+ */
+export class GetLogsError extends Error {
+  constructor(
+    readonly errors: readonly unknown[],
+    readonly preferred?: unknown,
+  ) {
+    super(errors.length ? `getLogs failed: ${errors.map(errorText).join(' | ')}` : 'No node supports getLogs')
+    this.name = 'GetLogsError'
+  }
+}
+
+/** 取出错误里节点返回的原始信息（ethers 会把它放在 error.message 里，外层是 “could not coalesce error”） */
+export function errorText(err: unknown): string {
+  const e = err as { error?: { message?: unknown }; info?: { error?: { message?: unknown } }; shortMessage?: unknown; message?: unknown } | null
+  const parts = [e?.error?.message, e?.info?.error?.message, e?.shortMessage ?? e?.message].filter((p) => typeof p === 'string')
+  return parts.length ? parts.join('; ') : String(err)
+}
+
+/** 节点正常返回了 JSON-RPC 错误（ethers 把它放在 error / info.error 里）或只是限频，说明节点本身可用 */
+function isAlive(err: unknown): boolean {
+  const e = err as { error?: { message?: unknown }; info?: { error?: { message?: unknown } } } | null
+  return typeof (e?.error?.message ?? e?.info?.error?.message) === 'string' || isRateLimited(err)
+}
+
+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))
 }
 
 /** 换节点也不会变的错误：合约执行结果、参数错误、用户拒绝等 */

package/src/index.ts

@@ -1,45 +1,33 @@
 export { Contract, bindCall, type BoundMethod, type ContractAbi, type ContractRunner } from './contract.js'
+export { GetLogsError } from './fallback.js'
 export {
   getAllowances,
   getBalances,
-  getErc1155Balances,
-  getNftBalances,
-  getNftCollections,
-  getNftOwners,
-  getNftTokenUris,
+  getMultiBalances,
   getTokens,
+  type GetAllowancesOptions,
   type GetBalancesOptions,
-  type GetNftCollectionsOptions,
-  type GetNftTokenUrisOptions,
   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,
@@ -51,7 +39,10 @@ export {
 } from './erc20.js'
 export {
   Provider,
+  type AllowancesOptions,
   type BalancesOptions,
+  type BalancesQuery,
+  type BlockOptions,
   type CallInput,
   type CallResults,
   type ProviderConfig,
@@ -73,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[],