@w3lib/evm-batch-call 0.2.0 → 0.4.0

package/src/scan.ts

@@ -0,0 +1,293 @@
+import { errorText, GetLogsError } from './fallback.js'
+import type { DiscoveredToken, TokenSource } from './owner.js'
+import { isTronChain } from './source.js'
+
+/** ERC20 / ERC721 的 Transfer(address,address,uint256) 事件 */
+const TRANSFER_TOPIC = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
+
+/** 增量扫描的进度，按 chainId + 地址保存 */
+export interface TransferScanState {
+  /** 第一个扫描的区块（之前的历史不扫描） */
+  startBlock: number
+  /** 已扫描到的区块号（含）；第一次调用且 lookbackBlocks 为 0 时等于 startBlock - 1 */
+  cursor: number
+  /** 扫描中发现的代币合约地址（小写） */
+  tokens: string[]
+  /** 当前使用的单次查询区块范围：出错时缩小，连续成功后翻倍，直到 rangeLimit / blockRange 选项 */
+  blockRange: number
+  /** 节点的区块范围上限（报错里给出的，或减半试出来的），记录 1 天后失效，之后会重新试更大的范围 */
+  rangeLimit?: number
+  /** rangeLimit 的记录时间（毫秒时间戳） */
+  rangeLimitAt?: number
+  /** 节点不开放 getLogs 时，在这个时间之前不再尝试（毫秒时间戳） */
+  pausedUntil?: number
+}
+
+/** 进度存储：默认存在内存里；传自定义存储可以跨页面刷新 / 重启接着扫（如 localStorage、数据库） */
+export interface TransferScanStorage {
+  get(key: string): TransferScanState | undefined | Promise<TransferScanState | undefined>
+  set(key: string, state: TransferScanState): void | Promise<void>
+}
+
+/** 内存存储（默认）：最多保存 1000 个地址，超出时淘汰最早的 */
+export function memoryScanStorage(limit = 1000): TransferScanStorage {
+  const map = new Map<string, TransferScanState>()
+  return {
+    get: (key) => map.get(key),
+    set: (key, state) => {
+      map.delete(key)
+      map.set(key, state)
+      if (map.size > limit) {
+        map.delete(map.keys().next().value as string)
+      }
+    },
+  }
+}
+
+/**
+ * 基于 getItem / setItem 的存储（如浏览器的 localStorage）：
+ * `transferScan({ storage: keyValueScanStorage(localStorage) })`
+ */
+export function keyValueScanStorage(store: { getItem(key: string): string | null; setItem(key: string, value: string): void }, prefix = 'w3lib:transfer-scan:'): TransferScanStorage {
+  return {
+    get: (key) => {
+      try {
+        const raw = store.getItem(prefix + key)
+        return raw ? (JSON.parse(raw) as TransferScanState) : undefined // 格式在读取后校验
+      } catch {
+        return undefined
+      }
+    },
+    set: (key, state) => {
+      try {
+        store.setItem(prefix + key, JSON.stringify(state))
+      } catch {
+        // 存储满或不可用：只影响下次能否接着扫
+      }
+    },
+  }
+}
+
+export interface TransferScanOptions {
+  /** 进度存储，默认内存（进程 / 页面结束就丢失） */
+  storage?: TransferScanStorage
+  /** 第一次调用时往回扫多少个区块，默认 0（只从现在开始往后扫） */
+  lookbackBlocks?: number
+  /** 单次 getLogs 的最大区块范围，默认 1000；节点有上限时自动缩小 */
+  blockRange?: number
+  /** 每次调用最多发多少个 getLogs 请求，默认 20；落后很多时分多次追上 */
+  maxRequests?: number
+  /** 每次调用的扫描时间预算（毫秒），默认 5000：超过后不再发新请求，留到下次调用 */
+  timeBudget?: number
+  /** 只扫到最新区块往前这么多个区块，默认 5：避开链重组，也避免节点之间高度不一致时漏扫 */
+  confirmations?: number
+}
+
+const defaultStorage = memoryScanStorage()
+
+/** 节点不开放 getLogs 时，暂停多久再试 */
+const PAUSE_ON_UNSUPPORTED = 10 * 60 * 1000
+/** 记下的区块范围上限多久后失效（节点可能换了 / 调整了限制） */
+const RANGE_LIMIT_TTL = 24 * 60 * 60 * 1000
+/** 连续成功多少次后把范围翻倍 */
+const GROW_AFTER = 2
+
+type ErrorKind = 'transient' | 'range' | 'unsupported' | 'other'
+
+/** 按节点返回的错误信息分类 */
+function kindOf(text: string): ErrorKind {
+  if (/too many|rate.?limit|429|temporarily|unavailable|busy|timed? ?out|timeout|network|ECONN|ENOTFOUND|socket|fetch failed|missing response|bad response|50[234]|quota|credits|compute units/i.test(text)) {
+    return 'transient' // 限频 / 超时 / 连不上：换个时间重试即可
+  }
+  if (/range|too (?:large|wide|big)|exceed|query returned more than|more than \d+ (?:results|logs)|response size|block limit/i.test(text)) {
+    return 'range'
+  }
+  if (/method not found|-32601|not supported|unsupported|not available|does not exist|not (?:allowed|enabled|whitelisted)|disabled/i.test(text)) {
+    return 'unsupported'
+  }
+  return 'other'
+}
+
+/** 每个节点的错误；GetLogsError 里没有错误表示没有节点支持 getLogs */
+function errorTexts(err: unknown): string[] {
+  if (err instanceof GetLogsError) {
+    return err.errors.length ? err.errors.map(errorText) : ['getLogs is not supported']
+  }
+  return [errorText(err)]
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/** 从错误信息里找区块范围上限，如 “log query range must not exceed 25 blocks”“maximum block range: 5000” */
+function parseRangeLimit(texts: string[]): number | null {
+  let best: number | null = null
+  for (const raw of texts) {
+    const text = raw.replace(/(\d),(?=\d{3}\b)/g, '$1') // 10,000 → 10000
+    const match =
+      /(?:exceed|maximum|max|limit(?:ed)? (?:of|to)?|up to|range)[^\d]{0,40}?(\d{1,7})\s*blocks?/i.exec(text) ??
+      /(\d{1,7})\s*blocks?[^.]{0,20}(?:range|limit|maximum)/i.exec(text) ??
+      /block range[^\d]{0,20}(\d{1,7})/i.exec(text)
+    const n = match ? Number(match[1]) : NaN
+    if (Number.isInteger(n) && n > 0 && (best === null || n > best)) {
+      best = n // 多个节点给了不同上限时取最大的（能用的节点里最宽松的那个）
+    }
+  }
+  return best
+}
+
+const isInt = (value: unknown, min: number): value is number => Number.isSafeInteger(value) && (value as number) >= min
+const isTime = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value)
+
+/** 校验存储里读出的进度：格式不对（旧版本 / 被改坏）时丢弃，重新开始 */
+function parseState(raw: unknown): TransferScanState | undefined {
+  const s = raw as Partial<Record<keyof TransferScanState, unknown>> | null
+  if (!s || typeof s !== 'object' || !isInt(s.startBlock, 0) || !isInt(s.cursor, -1) || !isInt(s.blockRange, 1) || !Array.isArray(s.tokens)) {
+    return undefined
+  }
+  if (!s.tokens.every((t) => typeof t === 'string' && /^0x[0-9a-fA-F]{40}$/.test(t))) {
+    return undefined
+  }
+  return {
+    startBlock: s.startBlock,
+    cursor: s.cursor,
+    tokens: (s.tokens as string[]).map((t) => t.toLowerCase()),
+    blockRange: s.blockRange,
+    ...(isInt(s.rangeLimit, 1) && isTime(s.rangeLimitAt) ? { rangeLimit: s.rangeLimit, rangeLimitAt: s.rangeLimitAt } : {}),
+    ...(isTime(s.pausedUntil) ? { pausedUntil: s.pausedUntil } : {}),
+  }
+}
+
+async function loadState(storage: TransferScanStorage, key: string): Promise<TransferScanState | undefined> {
+  try {
+    return parseState(await storage.get(key))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 增量扫描地址收到的 ERC20 代币（Transfer 事件，to = 该地址）：第一次调用记下当前区块，之后每次从上次的位置往后扫。
+ * 用来补充代币列表发现不了的新代币。作为代币来源使用：`combine(defaultTokenSource(), transferScan())`，
+ * 或在 getOwnerTokens 里用 `scanTransfers: true`。
+ *
+ * 局限：只能发现开始扫描之后收到的代币（除非设置 lookbackBlocks）；需要节点支持 eth_getLogs，免费公共节点限制较多
+ *（BSC 上只有 blockrazor 可用且每次最多 25 个区块）；Tron 不支持。
+ */
+export function transferScan(options: TransferScanOptions = {}): TokenSource {
+  const storage = options.storage ?? defaultStorage
+  const lookback = Math.max(0, Math.floor(options.lookbackBlocks ?? 0))
+  const maxRange = Math.max(1, Math.floor(options.blockRange ?? 1000))
+  const maxRequests = Math.max(1, options.maxRequests ?? 20)
+  const timeBudget = options.timeBudget ?? 5000
+  const confirmations = Math.max(0, Math.floor(options.confirmations ?? 5))
+  return {
+    name: 'transfers',
+    async discover({ chainId, owner, provider }) {
+      if (!provider || isTronChain(chainId) || !/^0x[0-9a-fA-F]{40}$/.test(owner)) {
+        return null
+      }
+      const key = `${chainId}:${owner.toLowerCase()}`
+      const saved = await loadState(storage, key)
+      const toResult = (state: TransferScanState | undefined): DiscoveredToken[] => (state?.tokens ?? []).map((address) => ({ address }))
+      if (saved?.pausedUntil && Date.now() < saved.pausedUntil) {
+        return toResult(saved)
+      }
+
+      const startedAt = Date.now()
+      let target: number
+      try {
+        target = (await provider.getBlockNumber()) - confirmations
+      } catch {
+        return saved ? toResult(saved) : null // 节点不支持 / 暂时不可用：返回已发现的代币
+      }
+      const now = Date.now()
+      let state: TransferScanState
+      if (saved) {
+        state = { ...saved, tokens: [...saved.tokens] }
+        delete state.pausedUntil
+        if (state.rangeLimitAt !== undefined && now - state.rangeLimitAt > RANGE_LIMIT_TTL) {
+          delete state.rangeLimit
+          delete state.rangeLimitAt
+        }
+      } else {
+        const cursor = Math.max(-1, target - lookback)
+        state = { startBlock: cursor + 1, cursor, tokens: [], blockRange: maxRange }
+      }
+      const tokens = new Set(state.tokens)
+      const ownerTopic = `0x${owner.slice(2).toLowerCase().padStart(64, '0')}`
+      const cap = () => Math.min(maxRange, state.rangeLimit ?? maxRange)
+      const setLimit = (limit: number) => {
+        state.rangeLimit = limit
+        state.rangeLimitAt = Date.now()
+      }
+      let range = Math.min(state.blockRange, cap())
+      let successes = 0
+      let transient = 0
+
+      for (let requests = 0; requests < maxRequests && state.cursor < target; requests++) {
+        if (timeBudget > 0 && Date.now() - startedAt >= timeBudget) {
+          break // 超出时间预算，留到下次调用
+        }
+        const fromBlock = state.cursor + 1
+        const toBlock = Math.min(target, fromBlock + range - 1)
+        try {
+          const logs = await provider.getLogs({ fromBlock, toBlock, topics: [TRANSFER_TOPIC, null, ownerTopic] })
+          for (const log of logs) {
+            // ERC20 的 Transfer 有 3 个 topic；ERC721 的 tokenId 也是 indexed，有 4 个，排除
+            if (log.topics.length === 3) {
+              tokens.add(log.address.toLowerCase())
+            }
+          }
+          state.cursor = toBlock
+          transient = 0
+          if (++successes >= GROW_AFTER && range < cap()) {
+            range = Math.min(cap(), range * 2) // 之前缩小过（偶发错误 / 换了节点）：逐步放大回去
+            successes = 0
+          }
+        } catch (err) {
+          successes = 0
+          const texts = errorTexts(err)
+          const kinds = texts.map(kindOf)
+          // 上次成功的节点这次的错误最能说明问题（其他节点可能一直就不能用，它们的报错不代表当前范围有问题）
+          const preferred = err instanceof GetLogsError && err.preferred !== undefined ? kindOf(errorText(err.preferred)) : undefined
+          const limit = parseRangeLimit(texts)
+          if (limit !== null && limit < range) {
+            range = limit // 节点明确给了范围上限
+            setLimit(limit)
+          } else if (kinds.every((k) => k === 'unsupported')) {
+            // 所有节点都不开放 getLogs：暂停一段时间，避免每次调用都白发请求
+            state.pausedUntil = Date.now() + PAUSE_ON_UNSUPPORTED
+            break
+          } else if (preferred === 'transient' || (preferred === undefined && kinds.every((k) => k === 'transient' || k === 'unsupported'))) {
+            // 在用的节点只是限频 / 超时：不缩小范围，退避后重试；连续 3 次就留到下次调用
+            const remaining = timeBudget > 0 ? timeBudget - (Date.now() - startedAt) : Infinity
+            if (++transient >= 3 || remaining <= 0) {
+              break
+            }
+            await sleep(Math.min(500 * transient, remaining))
+          } else if (range > 1) {
+            range = Math.max(1, Math.floor(range / 2)) // 范围超限但没说上限：减半再试
+            setLimit(range)
+          } else {
+            state.pausedUntil = Date.now() + PAUSE_ON_UNSUPPORTED // 连 1 个区块都查不了
+            break
+          }
+        }
+      }
+      state.blockRange = range
+      state.tokens = [...tokens]
+      try {
+        await storage.set(key, state)
+      } catch {
+        // 存储不可用：只影响下次能否接着扫
+      }
+      return toResult(state)
+    },
+  }
+}
+
+/** 读取某地址的扫描进度（不存在时为 undefined） */
+export async function getTransferScanState(chainId: number, owner: string, storage: TransferScanStorage = defaultStorage): Promise<TransferScanState | undefined> {
+  return loadState(storage, `${chainId}:${owner.toLowerCase()}`)
+}
+

package/src/shortcuts.ts

@@ -1,17 +1,6 @@
 import type { CallOverrides } from './aggregate.js'
-import type { BalanceToken, DefaultTokenField, TokenAllowance, TokenBalance, TokenDetails, TokenField } from './erc20.js'
-import type {
-  DefaultNftCollectionField,
-  Erc1155Balance,
-  NftBalance,
-  NftCollection,
-  NftCollectionField,
-  NftCollectionsOptions,
-  NftItem,
-  NftOwner,
-  NftTokenUri,
-} from './nft.js'
-import { Provider, type BalancesOptions, type ProviderConfig, type TokensOptions } from './provider.js'
+import type { BalanceToken, DefaultTokenField, RawTokenAllowance, RawTokenBalance, TokenAllowance, TokenBalance, TokenDetails, TokenField } from './erc20.js'
+import { Provider, type AllowancesOptions, type BalancesOptions, type BalancesQuery, type ProviderConfig, type TokensOptions } from './provider.js'
 import type { ProviderSource } from './source.js'
 
 /** getBalances / getTokens 共用的节点参数 */
@@ -24,17 +13,21 @@ export interface ShortcutProviderOptions extends ProviderConfig {
    * - ethers Provider
    * - 浏览器插件钱包：`window.ethereum`（EIP-1193）、`window.tronWeb`
    * - 混合数组，如 `[window.ethereum, 'https://…']`：钱包出错或不在这条链上时自动用后面的节点
+   * - 已创建的 Provider 实例：直接使用（chainId 和其他节点配置以实例为准，不能再传）
    */
-  provider?: ProviderSource | readonly ProviderSource[]
+  provider?: ProviderSource | readonly ProviderSource[] | Provider
 }
 
 export interface GetBalancesOptions extends BalancesOptions, ShortcutProviderOptions {}
 
 export interface GetTokensOptions<F extends TokenField = DefaultTokenField> extends TokensOptions<F>, ShortcutProviderOptions {}
 
+export interface GetAllowancesOptions extends AllowancesOptions, ShortcutProviderOptions {}
+
 // 复用 Provider：多次调用共享连接、multicall 地址判定和自动合并队列。
-// 按 “chainId + 配置内容” 分组，组内 URL 按字符串、钱包 / Provider 对象按引用（WeakMap，不阻止回收）。
-// 不缓存的情况：配置里有函数等无法比较内容的值；含对象的节点数组；没传 chainId 且节点是对象
+// 按 “chainId + 配置内容” 分组，组内 URL 按字符串、钱包 / Provider 对象按引用（WeakMap，不阻止回收）；
+// 钱包 + URL 的混合数组按 “对象编号 + URL” 组合成字符串 key（对象编号用 WeakMap 分配，缓存条数有上限）。
+// 不缓存的情况：配置里有函数等无法比较内容的值；没传 chainId 且节点里有对象
 // （钱包可能切链，每次按当前链新建；chainId 识别本身有缓存，切链时自动失效，不会每次都发请求）
 interface ProviderGroup {
   byString: Map<string, Provider>
@@ -66,7 +59,20 @@ function configKey(config: ProviderConfig): string | null {
   }
 }
 
-function sourceKey(chainId: number | undefined, source: ShortcutProviderOptions['provider']): string | object | null {
+/** 对象来源（钱包、ethers Provider）的编号，用于混合数组的缓存 key；WeakMap 不阻止对象被回收 */
+const objectIds = new WeakMap<object, number>()
+let nextObjectId = 0
+
+function objectId(value: object): number {
+  let id = objectIds.get(value)
+  if (id === undefined) {
+    id = ++nextObjectId
+    objectIds.set(value, id)
+  }
+  return id
+}
+
+function sourceKey(chainId: number | undefined, source: ProviderSource | readonly ProviderSource[] | undefined): string | object | null {
   if (source === undefined) {
     return 'default'
   }
@@ -75,12 +81,23 @@ function sourceKey(chainId: number | undefined, source: ShortcutProviderOptions[
   }
   if (Array.isArray(source)) {
     // URL 数组每次调用都是新数组，按内容缓存
-    return source.every((item) => typeof item === 'string') ? `urls:${source.join('\n')}` : null
+    if (source.every((item) => typeof item === 'string')) {
+      return `urls:${source.join('\n')}`
+    }
+    // 钱包 + URL：对象按编号、URL 按内容
+    return chainId === undefined ? null : `mixed:${source.map((item) => (typeof item === 'string' ? `url:${item}` : `obj:${objectId(item as object)}`)).join('\n')}`
   }
   return chainId === undefined ? null : (source as object)
 }
 
-function getProvider(chainId: number | undefined, source: ShortcutProviderOptions['provider'], config: ProviderConfig): Provider {
+function getProvider(chainId: number | undefined, input: ShortcutProviderOptions['provider'], config: ProviderConfig): Provider {
+  if (input instanceof Provider) {
+    if (chainId !== undefined || Object.keys(config).length) {
+      throw new Error('chainId and provider config must be set on the Provider instance itself, not passed alongside it')
+    }
+    return input
+  }
+  const source = input
   if (chainId === undefined && source === undefined) {
     throw new Error('getBalances / getTokens requires chainId or provider')
   }
@@ -112,12 +129,15 @@ function getProvider(chainId: number | undefined, source: ShortcutProviderOption
 
 export interface ShortcutOptions extends CallOverrides, ShortcutProviderOptions {}
 
-/** 拆出节点参数、调用参数和函数自己的参数（ownKeys），其余作为 Provider 配置；值为 undefined 的参数忽略 */
-function resolve<T extends ShortcutOptions, K extends keyof T & string = never>(
+/**
+ * 拆出节点参数、调用参数和函数自己的参数（ownKeys），其余作为 Provider 配置；值为 undefined 的参数忽略。
+ * 子路径（/nft、/owner）的快捷函数也用它，与 getBalances 共享 Provider 缓存
+ */
+export function resolve<T extends ShortcutOptions, K extends keyof T & string = never>(
   options: T,
   ownKeys: readonly K[] = [],
 ): { provider: Provider; overrides: CallOverrides; own: Pick<T, K> } {
-  const { chainId, provider, blockTag, from, ...others } = options
+  const { chainId, provider, blockTag, from, signal, minBlock, ...others } = options
   const own: Record<string, unknown> = {}
   const config: Record<string, unknown> = {}
   for (const [key, value] of Object.entries(others)) {
@@ -128,7 +148,7 @@ function resolve<T extends ShortcutOptions, K extends keyof T & string = never>(
   return {
     // null / 空字符串（如状态里还没有 chainId）按“未传”处理，走自动识别，而不是变成 chainId 0
     provider: getProvider(chainId === undefined || chainId === null || chainId === '' ? undefined : Number(chainId), provider, config as ProviderConfig),
-    overrides: { blockTag, from },
+    overrides: { blockTag, from, signal, minBlock },
     own: own as Pick<T, K>,
   }
 }
@@ -144,12 +164,29 @@ function resolve<T extends ShortcutOptions, K extends keyof T & string = never>(
  * await getBalances(user, tokens, { provider: 'https://bsc-dataseed.bnbchain.org' })
  * await getBalances(user, tokens, { chainId: 56, provider: [window.ethereum, 'https://…'] }) // 钱包优先，失败用公共节点
  * await getBalances(user, tokens, { chainId: 56, symbol: true })                 // 同时返回 symbol
+ * await getBalances(user, tokens, { chainId: 56, decimals: false })             // 只查余额，不带 decimals / formatted
  * // [{ token: NATIVE_TOKEN, native: true, balance: '1500000000000000000', decimals: 18, formatted: '1.5', success: true }, ...]
  * ```
  */
-export function getBalances(owner: string, tokens: readonly BalanceToken[], options: GetBalancesOptions = {}): Promise<TokenBalance[]> {
-  const { provider, overrides, own } = resolve(options, ['symbol'])
-  return provider.balances(owner, tokens, { ...overrides, symbol: own.symbol })
+export function getBalances(owner: string, tokens: readonly BalanceToken[], options: GetBalancesOptions & { decimals: false }): Promise<RawTokenBalance[]>
+export function getBalances(owner: string, tokens: readonly BalanceToken[], options?: GetBalancesOptions): Promise<TokenBalance[]>
+export function getBalances(owner: string, tokens: readonly BalanceToken[], options: GetBalancesOptions = {}): Promise<Array<TokenBalance | RawTokenBalance>> {
+  const { provider, overrides, own } = resolve(options, ['symbol', 'decimals', 'withBlock'])
+  return provider.balances(owner, tokens, { ...overrides, ...own })
+}
+
+/**
+ * 多个钱包一次查（同一条链上合成一次 multicall），结果与 queries 一一对应。节点参数与 getBalances 相同。
+ *
+ * ```ts
+ * const [a, b] = await getMultiBalances([{ owner: walletA, tokens: [NATIVE_TOKEN, USDT] }, { owner: walletB, tokens: [USDT] }], { chainId: 56 })
+ * ```
+ */
+export function getMultiBalances(queries: readonly BalancesQuery[], options: GetBalancesOptions & { decimals: false }): Promise<RawTokenBalance[][]>
+export function getMultiBalances(queries: readonly BalancesQuery[], options?: GetBalancesOptions): Promise<TokenBalance[][]>
+export function getMultiBalances(queries: readonly BalancesQuery[], options: GetBalancesOptions = {}): Promise<Array<Array<TokenBalance | RawTokenBalance>>> {
+  const { provider, overrides, own } = resolve(options, ['symbol', 'decimals', 'withBlock'])
+  return provider.multiBalances(queries, { ...overrides, ...own })
 }
 
 /**
@@ -167,8 +204,8 @@ export function getTokens<const F extends TokenField = DefaultTokenField>(
   tokens: readonly string[],
   options: GetTokensOptions<F> = {},
 ): Promise<TokenDetails<F>[]> {
-  const { provider, overrides, own } = resolve(options, ['fields'])
-  return provider.tokens<F>(tokens, { ...overrides, fields: own.fields })
+  const { provider, overrides, own } = resolve(options, ['fields', 'withBlock'])
+  return provider.tokens<F>(tokens, { ...overrides, ...own })
 }
 
 /**
@@ -183,66 +220,17 @@ export function getAllowances(
   owner: string,
   spender: string,
   tokens: readonly BalanceToken[],
-  options: ShortcutOptions = {},
-): Promise<TokenAllowance[]> {
-  const { provider, overrides } = resolve(options)
-  return provider.allowances(owner, spender, tokens, overrides)
-}
-
-export interface GetNftCollectionsOptions<F extends NftCollectionField = DefaultNftCollectionField>
-  extends NftCollectionsOptions<F>,
-    ShortcutProviderOptions {}
-
-/**
- * 批量查 NFT 集合信息，字段可选（默认 standard / name / symbol）。
- *
- * ```ts
- * await getNftCollections([BAYC, MAYC], { chainId: 1, fields: ['standard', 'name', 'totalSupply'] })
- * // [{ address: BAYC, standard: 'ERC721', name: 'BoredApeYachtClub', totalSupply: '10000', success: true }, ...]
- * ```
- */
-export function getNftCollections<const F extends NftCollectionField = DefaultNftCollectionField>(
-  collections: readonly string[],
-  options: GetNftCollectionsOptions<F> = {},
-): Promise<NftCollection<F>[]> {
-  const { provider, overrides, own } = resolve(options, ['fields'])
-  return provider.nftCollections<F>(collections, { ...overrides, fields: own.fields })
-}
-
-/** 批量查 ERC721 持有数量：`await getNftBalances(user, [BAYC, MAYC], { chainId: 1 })` */
-export function getNftBalances(owner: string, collections: readonly string[], options: ShortcutOptions = {}): Promise<NftBalance[]> {
-  const { provider, overrides } = resolve(options)
-  return provider.nftBalances(owner, collections, overrides)
-}
-
-/** 批量查 ERC721 持有人：`await getNftOwners([{ contract: BAYC, tokenId: 1 }], { chainId: 1 })` */
-export function getNftOwners(items: readonly NftItem[], options: ShortcutOptions = {}): Promise<NftOwner[]> {
-  const { provider, overrides } = resolve(options)
-  return provider.nftOwners(items, overrides)
-}
-
-export interface GetNftTokenUrisOptions extends ShortcutOptions {
-  /** 把 ipfs://xxx 转成 `${ipfsGateway}xxx`，如 'https://ipfs.io/ipfs/' */
-  ipfsGateway?: string
-}
-
-/**
- * 批量查 NFT 元数据地址（ERC721 tokenURI / ERC1155 uri 自动兼容）。
- *
- * ```ts
- * await getNftTokenUris([{ contract: BAYC, tokenId: 1 }], { chainId: 1, ipfsGateway: 'https://ipfs.io/ipfs/' })
- * // [{ contract: BAYC, tokenId: '1', uri: 'https://ipfs.io/ipfs/Qm…/1', success: true }]
- * ```
- */
-export function getNftTokenUris(items: readonly NftItem[], options: GetNftTokenUrisOptions = {}): Promise<NftTokenUri[]> {
-  const { provider, overrides, own } = resolve(options, ['ipfsGateway'])
-  return provider.nftTokenUris(items, { ...overrides, ipfsGateway: own.ipfsGateway })
-}
-
-/** 批量查 ERC1155 余额：`await getErc1155Balances(user, [{ contract, tokenId: 1 }], { chainId: 137 })` */
-export function getErc1155Balances(owner: string, items: readonly NftItem[], options: ShortcutOptions = {}): Promise<Erc1155Balance[]> {
-  const { provider, overrides } = resolve(options)
-  return provider.erc1155Balances(owner, items, overrides)
+  options: GetAllowancesOptions & { decimals: false },
+): Promise<RawTokenAllowance[]>
+export function getAllowances(owner: string, spender: string, tokens: readonly BalanceToken[], options?: GetAllowancesOptions): Promise<TokenAllowance[]>
+export function getAllowances(
+  owner: string,
+  spender: string,
+  tokens: readonly BalanceToken[],
+  options: GetAllowancesOptions = {},
+): Promise<Array<TokenAllowance | RawTokenAllowance>> {
+  const { provider, overrides, own } = resolve(options, ['decimals', 'withBlock'])
+  return provider.allowances(owner, spender, tokens, { ...overrides, ...own })
 }
 
 /** 测试用：按参数取（或创建）Provider，用于验证缓存复用（不在包的公开导出里） */

package/src/source.ts

@@ -2,9 +2,9 @@ import { BrowserProvider, FetchRequest, JsonRpcProvider, makeError, type Eip1193
 
 import type { EthersLikeProvider } from './aggregate.js'
 import { canDetectChainId, detectChainId, detectChainIdCached } from './detect.js'
-import { FallbackRpc, type FallbackOptions } from './fallback.js'
+import { FallbackRpc, type FallbackNodeInfo, type FallbackOptions } from './fallback.js'
 import { DEFAULT_RPC_URLS, DEFAULT_TRON_HOSTS } from './rpcNodes.js'
-import { TRON_CHAIN_ID, TronProvider, type TronProviderOptions, type TronWebLike } from './tron.js'
+import { TRON_CHAIN_ID, TronProvider, isTronChain, type TronProviderOptions, type TronWebLike } from './tron.js'
 
 /**
  * 可传给 Provider 的底层连接（也可以传数组，按顺序作为主节点 + 备用节点）：
@@ -22,11 +22,7 @@ export interface SourceOptions {
   tron?: Omit<TronProviderOptions, 'fullHost' | 'request'>
 }
 
-const TRON_CHAIN_IDS = new Set<number>(Object.values(TRON_CHAIN_ID))
-
-export function isTronChain(chainId: number): boolean {
-  return TRON_CHAIN_IDS.has(chainId)
-}
+export { isTronChain }
 
 /** 链的默认节点：EVM 用内置公共节点表，Tron 主网用内置全节点列表 */
 export function getDefaultRpcUrls(chainId: number): readonly string[] {
@@ -57,7 +53,38 @@ export function resolveSource(
     // 内置公共节点本来就是按 chainId 选出来的，不需要再校验
     return source === undefined ? node : withChainCheck(chainId, item, node, timeout)
   })
-  return multiple ? new FallbackRpc(nodes, options.fallback) : (nodes[0] as EthersLikeProvider)
+  const info: FallbackNodeInfo[] = list.map((item) => ({ label: nodeLabel(item), key: item as string | object }))
+  // 单节点也经过 FallbackRpc（统一触发 onRequest 事件、抛原始错误）。外层超时只对单个 EVM URL 节点加（FetchRequest 本来就有同样的超时）；
+  // 钱包等对象节点、Tron URL（TronProvider 有自己的超时和 429 退避、限流队列，外层超时会把排队 / 退避中的请求截断）不传 timeout 时不加，与原来一致
+  const singleEvmUrl = typeof list[0] === 'string' && !isTronChain(chainId)
+  const fallback = multiple || singleEvmUrl || options.fallback?.timeout !== undefined ? options.fallback : { ...options.fallback, timeout: 0 }
+  return new FallbackRpc(nodes, fallback, info)
+}
+
+/** 节点标识（错误信息、onRequest 事件用）：URL 只取 host，不含 path / query（常带 API Key） */
+export function nodeLabel(source: ProviderSource): string {
+  if (typeof source === 'string') {
+    try {
+      return new URL(source).host || 'url'
+    } catch {
+      return 'url'
+    }
+  }
+  const value = source as Partial<EthersLikeProvider & Eip1193Provider & TronWebLike>
+  if (value instanceof JsonRpcProvider) {
+    try {
+      return new URL(value._getConnection().url).host || 'provider'
+    } catch {
+      return 'provider'
+    }
+  }
+  if (value.fullNode) {
+    return 'tronWeb'
+  }
+  if (typeof value.call !== 'function' && typeof value.request === 'function') {
+    return 'wallet'
+  }
+  return 'provider'
 }
 
 /** 识别失败后多久内不再重试识别（期间请求照常发出，不做校验） */
@@ -120,6 +147,22 @@ export class ChainCheckedProvider implements EthersLikeProvider {
     return this.#run(() => this.inner.getBalance(...args))
   }
 
+  getBlockNumber(): Promise<number> {
+    const inner = this.inner
+    if (!inner.getBlockNumber) {
+      return Promise.reject(new Error('getBlockNumber is not supported by this node'))
+    }
+    return this.#run(() => (inner.getBlockNumber as () => Promise<number>)())
+  }
+
+  getLogs(filter: Parameters<NonNullable<EthersLikeProvider['getLogs']>>[0]): Promise<Awaited<ReturnType<NonNullable<EthersLikeProvider['getLogs']>>>> {
+    const inner = this.inner
+    if (!inner.getLogs) {
+      return Promise.reject(new Error('getLogs is not supported by this node'))
+    }
+    return this.#run(() => (inner.getLogs as NonNullable<EthersLikeProvider['getLogs']>)(filter))
+  }
+
   async getChainId(): Promise<number> {
     return this.chainId
   }