@w3lib/evm-batch-call 0.1.0 → 0.3.0

package/src/erc20.ts

@@ -28,16 +28,118 @@ export interface Erc20Contract extends Contract {
   transferFrom: Method<[from: string, to: string, amount: bigint | string | number], boolean>
 }
 
-export interface TokenInfo {
-  address: string
-  /** 读取失败（如 symbol 是 bytes32 的老代币）时为 null */
-  symbol: string | null
+/** allowances() / getAllowances() 的单项结果 */
+export interface TokenAllowance {
+  token: string
+  spender: string
+  /** 主币不需要授权，视为无限额度 */
+  native: boolean
+  /** 授权额度（最小单位的十进制字符串） */
+  allowance: string
+  decimals: number
+  /** 按 decimals 换算后的额度 */
+  formatted: string
+  /** 额度 ≥ uint96 最大值时为 true（覆盖 MaxUint256，以及 UNI / COMP 等把额度截断为 uint96 的代币） */
+  unlimited: boolean
+  success: boolean
+}
+
+/** unlimited 的判定阈值：uint96 最大值 */
+export const UNLIMITED_ALLOWANCE_THRESHOLD = 2n ** 96n - 1n
+
+const MAX_UINT256 = 2n ** 256n - 1n
+
+export { MAX_UINT256 }
+
+/** tokens() / getTokens() 可选的字段 */
+export type TokenField = 'name' | 'symbol' | 'decimals' | 'totalSupply'
+
+/** 不指定 fields 时返回的字段 */
+export const DEFAULT_TOKEN_FIELDS = ['name', 'symbol', 'decimals'] as const satisfies readonly TokenField[]
+
+export type DefaultTokenField = (typeof DEFAULT_TOKEN_FIELDS)[number]
+
+interface TokenFieldTypes {
   name: string | null
+  symbol: string | null
+  decimals: number | null
+  /** 最小单位的十进制字符串 */
+  totalSupply: string | null
+}
+
+/**
+ * tokens() / getTokens() 的单项结果，只包含请求的字段（读取失败的字段为 null）。
+ * 请求 totalSupply 时额外带 totalSupplyFormatted（按 decimals 换算）。
+ */
+export type TokenDetails<F extends TokenField = DefaultTokenField> = {
+  address: string
+  /** 是否是主币占位地址（信息来自内置链信息表 / nativeSymbol 等配置） */
+  native: boolean
+  /** 请求的字段都读到时为 true（主币没有 totalSupply，不计入） */
+  success: boolean
+} & { [K in F]: TokenFieldTypes[K] } & ('totalSupply' extends F ? { totalSupplyFormatted: string | null } : unknown)
+
+/** 主币占位地址（多数聚合器、钱包的约定），传给 balances() 时按主币处理 */
+export const NATIVE_TOKEN = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
+
+/** balances() 默认视为主币的地址：0xeeee…eeee 和零地址 */
+export const DEFAULT_NATIVE_TOKENS: readonly string[] = [NATIVE_TOKEN, '0x0000000000000000000000000000000000000000']
+
+/** balances() 的代币参数：地址，或带已知 decimals 的对象（跳过 decimals 查询） */
+export type BalanceToken = string | { address: string; decimals?: number }
+
+export interface TokenBalance {
+  /** 传入的代币地址（原样） */
+  token: string
+  /** 是否按主币查询 */
+  native: boolean
+  /** 原始余额（最小单位）的十进制字符串，如 "1234500000"；需要计算时用 BigInt(balance) */
+  balance: string
   decimals: number
+  /** 按 decimals 换算后的十进制字符串，如 "1234.5"；整数不带小数点 */
+  formatted: string
+  /** 仅在 symbol: true 时返回；读取失败或主币 symbol 未知时为 null */
+  symbol?: string | null
+  /** 余额和 decimals 都查到时为 true；失败时 balance、formatted 都为 "0" */
+  success: boolean
+}
+
+/**
+ * 按精度格式化：formatAmount(1234500000n, 6) === '1234.5'，formatAmount(10n ** 18n, 18) === '1'。
+ * 不做四舍五入，保留全部有效小数位。
+ */
+export function formatAmount(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)
+  const fraction = digits.slice(digits.length - decimals).replace(/0+$/, '')
+  return `${negative ? '-' : ''}${whole}${fraction ? `.${fraction}` : ''}`
+}
+
+// decimals / symbol / name 不会变，按 chainId + 地址缓存，轮询余额时只需要查 balanceOf
+interface TokenMeta {
+  decimals?: number
+  symbol?: string
+  name?: string
+  /** NFT 集合标准（nftCollections 识别后缓存）；null 表示确认不是 ERC721 / ERC1155 */
+  standard?: 'ERC721' | 'ERC1155' | null
+}
+
+const tokenMetaCache = new Map<string, TokenMeta>()
+
+export function getCachedTokenMeta(chainId: number, token: string): TokenMeta {
+  return tokenMetaCache.get(`${chainId}:${token.toLowerCase()}`) ?? {}
 }
 
-/** 常见的主币占位地址：多数聚合器用 0xeeee…eeee，部分协议用零地址 */
-export const DEFAULT_NATIVE_TOKENS: readonly string[] = [
-  '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
-  '0x0000000000000000000000000000000000000000',
-]
+export function setCachedTokenMeta(chainId: number, token: string, meta: TokenMeta): void {
+  if (Object.keys(meta).length === 0) {
+    return // 没有新数据（如查询失败）时不写入空条目
+  }
+  const key = `${chainId}:${token.toLowerCase()}`
+  tokenMetaCache.set(key, { ...tokenMetaCache.get(key), ...meta })
+}
+
+/** 测试用：清空 decimals / symbol 缓存 */
+export function resetDecimalsCache(): void {
+  tokenMetaCache.clear()
+}

package/src/fallback.ts

@@ -1,7 +1,9 @@
 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'
 
 export interface FallbackOptions {
   /** 单个节点单次请求超时（毫秒），超时视为该节点故障并换下一个。默认 10000；<= 0 表示不限制 */
@@ -22,6 +24,12 @@ export class FallbackRpc implements EthersLikeProvider {
   readonly #timeout: number
   readonly #cooldown: number
   readonly #failedAt: number[]
+  /** 上次 getLogs 成功的节点 */
+  #logsNode = -1
+  /** 上次成功的节点连续被限频的次数 */
+  #logsThrottled = 0
+  /** getLogs 超时 / 连不上的时间，只影响 getLogs 的节点顺序 */
+  readonly #logsFailedAt: number[]
 
   constructor(nodes: EthersLikeProvider[], options: FallbackOptions = {}) {
     if (!nodes.length) {
@@ -31,6 +39,7 @@ export class FallbackRpc implements EthersLikeProvider {
     this.#timeout = options.timeout ?? 10_000
     this.#cooldown = options.cooldown ?? 30_000
     this.#failedAt = nodes.map(() => 0)
+    this.#logsFailedAt = nodes.map(() => 0)
   }
 
   get nodes(): readonly EthersLikeProvider[] {
@@ -45,6 +54,80 @@ export class FallbackRpc implements EthersLikeProvider {
     return this.#run((node) => node.getBalance(address, blockTag))
   }
 
+  /** 按节点顺序探测 chainId（节点需实现 getChainId，见 detect.ts） */
+  getChainId(): Promise<number> {
+    return this.#run((node) => detectChainIdOf(node))
+  }
+
+  /**
+   * 当前区块号。优先问上次 getLogs 成功的节点（增量扫描时区块号和日志来自同一个节点，不会因节点间的高度差漏扫）；
+   * 不支持 getBlockNumber 的节点跳过，失败也不让节点进入冷却（不影响 call / getBalance）
+   */
+  async getBlockNumber(): Promise<number> {
+    let lastError: unknown = new Error('No node supports getBlockNumber')
+    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)
+      } catch (err) {
+        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']>>>> {
+    const errors: unknown[] = []
+    let preferred: unknown
+    const sticky = this.#logsNode
+    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)
+        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)
+  }
+
   async #run<T>(fn: (node: EthersLikeProvider) => Promise<T>): Promise<T> {
     let lastError: unknown
     for (const index of this.#order()) {
@@ -64,14 +147,55 @@ export class FallbackRpc implements EthersLikeProvider {
   }
 
   /** 健康的节点按原顺序在前，冷却中的按出错时间先后排在后面（全挂时也都会再试一次） */
-  #order(): number[] {
+  #order(failedAt: readonly number[] = this.#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))
 }
 
 /** 换节点也不会变的错误：合约执行结果、参数错误、用户拒绝等 */
@@ -83,23 +207,3 @@ function isDeterministic(err: unknown): boolean {
     isError(err, 'NUMERIC_FAULT')
   )
 }
-
-class TimeoutError extends Error {
-  constructor(ms: number) {
-    super(`RPC request timed out after ${ms}ms`)
-    this.name = 'TimeoutError'
-  }
-}
-
-function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
-  if (!Number.isFinite(ms) || ms <= 0) {
-    return promise
-  }
-  let timer: ReturnType<typeof setTimeout>
-  return Promise.race([
-    promise,
-    new Promise<never>((_, reject) => {
-      timer = setTimeout(() => reject(new TimeoutError(ms)), ms)
-    }),
-  ]).finally(() => clearTimeout(timer))
-}

package/src/index.ts

@@ -1,15 +1,101 @@
 export { Contract, bindCall, type BoundMethod, type ContractAbi, type ContractRunner } from './contract.js'
-export { DEFAULT_NATIVE_TOKENS, ERC20_ABI, type Erc20Contract, type TokenInfo } from './erc20.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,
+  getTokens,
+  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 { clearChainIdCache, detectChainId } from './detect.js'
+export {
+  DEFAULT_NATIVE_TOKENS,
+  ERC20_ABI,
+  NATIVE_TOKEN,
+  formatAmount,
+  type BalanceToken,
+  type Erc20Contract,
+  type TokenBalance,
+  type TokenAllowance,
+  MAX_UINT256,
+  UNLIMITED_ALLOWANCE_THRESHOLD,
+  DEFAULT_TOKEN_FIELDS,
+  type DefaultTokenField,
+  type TokenDetails,
+  type TokenField,
+} from './erc20.js'
 export {
   Provider,
-  type ProviderConfig,
+  type BalancesOptions,
   type CallInput,
   type CallResults,
+  type ProviderConfig,
   type ProviderSource,
-  type TryCallResults,
   type StaticCallItem,
   type StaticCallOverrides,
   type StaticCallResult,
+  type TokensOptions,
+  type TryCallResults,
 } from './provider.js'
 export {
   TRON_CHAIN_ID,
@@ -23,7 +109,7 @@ export {
 } from './tron.js'
 export { CallFailedError, decodeRevertReason, isExecutionError } from './errors.js'
 export { FallbackRpc, type FallbackOptions } from './fallback.js'
-export { getDefaultRpcUrls, isTronChain, type SourceOptions } from './source.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'