@w3lib/evm-batch-call 0.3.0 → 0.4.1

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,166 @@ 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
+    const nameAt = validTimestamp(value.nameAt)
+    if (typeof value.name === 'string' && nameAt !== null) {
+      meta.name = value.name
+      meta.nameAt = nameAt
+    }
+    const symbolAt = validTimestamp(value.symbolAt)
+    if (typeof value.symbol === 'string' && symbolAt !== null) {
+      meta.symbol = value.symbol
+      meta.symbolAt = 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)
+  }
+}
+
+/**
+ * 导入的写入时间：只接受有限的数值；晚于当前时间的（时钟不准、数据被改过）截到当前时间——否则永不过期。
+ * 不合格时为 null（丢弃 name / symbol，之后重新查）
+ */
+function validTimestamp(value: unknown): number | null {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    return null
+  }
+  return Math.min(value, Date.now())
+}
+
+/** 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 {
+      // 监听函数出错不影响请求
+    }
+  }
+}