@w3lib/evm-batch-call 0.1.0 → 0.2.0

package/src/shortcuts.ts

@@ -0,0 +1,256 @@
+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 { ProviderSource } from './source.js'
+
+/** getBalances / getTokens 共用的节点参数 */
+export interface ShortcutProviderOptions extends ProviderConfig {
+  /** 链 ID。传了 provider 时可省略（从节点识别，结果会缓存）；不传 provider 时必填（用于选择内置公共节点） */
+  chainId?: number | string
+  /**
+   * 节点，与 `new Provider(...)` 相同，不传则使用内置公共节点：
+   * - RPC URL，或 URL 数组（主节点 + 备用节点）
+   * - ethers Provider
+   * - 浏览器插件钱包：`window.ethereum`（EIP-1193）、`window.tronWeb`
+   * - 混合数组，如 `[window.ethereum, 'https://…']`：钱包出错或不在这条链上时自动用后面的节点
+   */
+  provider?: ProviderSource | readonly ProviderSource[]
+}
+
+export interface GetBalancesOptions extends BalancesOptions, ShortcutProviderOptions {}
+
+export interface GetTokensOptions<F extends TokenField = DefaultTokenField> extends TokensOptions<F>, ShortcutProviderOptions {}
+
+// 复用 Provider：多次调用共享连接、multicall 地址判定和自动合并队列。
+// 按 “chainId + 配置内容” 分组，组内 URL 按字符串、钱包 / Provider 对象按引用（WeakMap，不阻止回收）。
+// 不缓存的情况：配置里有函数等无法比较内容的值；含对象的节点数组；没传 chainId 且节点是对象
+// （钱包可能切链，每次按当前链新建；chainId 识别本身有缓存，切链时自动失效，不会每次都发请求）
+interface ProviderGroup {
+  byString: Map<string, Provider>
+  byObject: WeakMap<object, Provider>
+}
+
+const providerCache = new Map<string, ProviderGroup>()
+
+/** 缓存上限（分组数、每组 URL 数），超出时淘汰最早加入的；对象来源用 WeakMap，随对象回收 */
+const MAX_CACHED = 32
+
+function setBounded<K, V>(map: Map<K, V>, key: K, value: V): void {
+  map.set(key, value)
+  if (map.size > MAX_CACHED) {
+    map.delete(map.keys().next().value as K)
+  }
+}
+
+function configKey(config: ProviderConfig): string | null {
+  try {
+    return JSON.stringify(config, (_key, value: unknown) => {
+      if (typeof value === 'function') {
+        throw new Error('not comparable')
+      }
+      return typeof value === 'bigint' ? value.toString() : value
+    })
+  } catch {
+    return null
+  }
+}
+
+function sourceKey(chainId: number | undefined, source: ShortcutProviderOptions['provider']): string | object | null {
+  if (source === undefined) {
+    return 'default'
+  }
+  if (typeof source === 'string') {
+    return `url:${source}`
+  }
+  if (Array.isArray(source)) {
+    // URL 数组每次调用都是新数组，按内容缓存
+    return source.every((item) => typeof item === 'string') ? `urls:${source.join('\n')}` : null
+  }
+  return chainId === undefined ? null : (source as object)
+}
+
+function getProvider(chainId: number | undefined, source: ShortcutProviderOptions['provider'], config: ProviderConfig): Provider {
+  if (chainId === undefined && source === undefined) {
+    throw new Error('getBalances / getTokens requires chainId or provider')
+  }
+  const create = () => (chainId === undefined ? new Provider(source as ProviderSource, config) : new Provider(chainId, source, config))
+  const cfg = configKey(config)
+  const key = sourceKey(chainId, source)
+  if (cfg === null || key === null) {
+    return create()
+  }
+  const groupKey = `${chainId ?? 'auto'}|${cfg}`
+  let group = providerCache.get(groupKey)
+  if (!group) {
+    group = { byString: new Map(), byObject: new WeakMap() }
+    setBounded(providerCache, groupKey, group)
+  }
+  let provider = typeof key === 'string' ? group.byString.get(key) : group.byObject.get(key)
+  if (!provider) {
+    provider = create()
+    if (typeof key === 'string') {
+      setBounded(group.byString, key, provider)
+    } else {
+      group.byObject.set(key, provider)
+    }
+  }
+  return provider
+}
+
+// ---- 各查询函数：节点参数都相同 ----
+
+export interface ShortcutOptions extends CallOverrides, ShortcutProviderOptions {}
+
+/** 拆出节点参数、调用参数和函数自己的参数（ownKeys），其余作为 Provider 配置；值为 undefined 的参数忽略 */
+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 own: Record<string, unknown> = {}
+  const config: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(others)) {
+    if (value !== undefined) {
+      ;((ownKeys as readonly string[]).includes(key) ? own : config)[key] = value
+    }
+  }
+  return {
+    // null / 空字符串（如状态里还没有 chainId）按“未传”处理，走自动识别，而不是变成 chainId 0
+    provider: getProvider(chainId === undefined || chainId === null || chainId === '' ? undefined : Number(chainId), provider, config as ProviderConfig),
+    overrides: { blockTag, from },
+    own: own as Pick<T, K>,
+  }
+}
+
+/**
+ * 批量查余额（主币 + 代币，一次请求），返回原始余额、decimals 和换算后的数值。
+ *
+ * ```ts
+ * import { NATIVE_TOKEN, getBalances } from '@w3lib/evm-batch-call'
+ *
+ * await getBalances(user, [NATIVE_TOKEN, USDT], { chainId: 56 })                 // 内置公共节点
+ * await getBalances(user, tokens, { provider: window.ethereum })                  // 钱包，chainId 自动识别
+ * 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
+ * // [{ 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 })
+}
+
+/**
+ * 批量查 ERC20 代币详情（一次请求），可以选择返回哪些字段。节点参数与 getBalances 相同。
+ *
+ * ```ts
+ * import { NATIVE_TOKEN, getTokens } from '@w3lib/evm-batch-call'
+ *
+ * await getTokens([USDT, NATIVE_TOKEN], { chainId: 56 })            // 默认 name / symbol / decimals
+ * await getTokens([USDT], { provider: window.ethereum, fields: ['symbol', 'decimals', 'totalSupply'] })
+ * // [{ address: USDT, native: false, symbol: 'USDT', decimals: 18, totalSupply: '…', totalSupplyFormatted: '…', success: true }]
+ * ```
+ */
+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 })
+}
+
+/**
+ * 批量查 ERC20 授权额度（一次请求）。
+ *
+ * ```ts
+ * const [usdt] = await getAllowances(user, router, [USDT], { chainId: 56 })
+ * if (!usdt.unlimited && BigInt(usdt.allowance) < amount) { // 需要 approve
+ * ```
+ */
+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)
+}
+
+/** 测试用：按参数取（或创建）Provider，用于验证缓存复用（不在包的公开导出里） */
+export function resolveProviderForTest(options: ShortcutOptions): Provider {
+  return resolve(options).provider
+}
+
+/** 测试用：清空 getBalances / getTokens 的 Provider 缓存 */
+export function resetBalancesProviderCache(): void {
+  providerCache.clear()
+}

package/src/source.ts

@@ -1,6 +1,7 @@
-import { BrowserProvider, FetchRequest, JsonRpcProvider, type Eip1193Provider } from 'ethers'
+import { BrowserProvider, FetchRequest, JsonRpcProvider, makeError, type Eip1193Provider, type TransactionRequest } from 'ethers'
 
 import type { EthersLikeProvider } from './aggregate.js'
+import { canDetectChainId, detectChainId, detectChainIdCached } from './detect.js'
 import { FallbackRpc, 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'
@@ -50,10 +51,102 @@ export function resolveSource(
   }
   // 多节点时 Tron 节点不在单节点内重试 429，直接切到下一个节点
   const multiple = list.length > 1
-  const nodes = list.map((item) => toEthersLike(chainId, item, options, multiple))
+  const timeout = options.fallback?.timeout ?? 10_000
+  const nodes = list.map((item) => {
+    const node = toEthersLike(chainId, item, options, multiple)
+    // 内置公共节点本来就是按 chainId 选出来的，不需要再校验
+    return source === undefined ? node : withChainCheck(chainId, item, node, timeout)
+  })
   return multiple ? new FallbackRpc(nodes, options.fallback) : (nodes[0] as EthersLikeProvider)
 }
 
+/** 识别失败后多久内不再重试识别（期间请求照常发出，不做校验） */
+const CHECK_RETRY_INTERVAL = 60_000
+
+/**
+ * 校验节点所在的链与 Provider 的 chainId 一致，避免把另一条链的数据当成这条链的返回：
+ * 比如 [钱包, 公共节点] 自动识别出钱包的链后，公共节点其实在另一条链上；或者配错了节点 URL。
+ *
+ * - 不一致时抛 NETWORK_ERROR（多节点时 FallbackRpc 会换下一个节点）
+ * - 通过已配置好的节点连接识别（带 Tron apiKey / 限流等），结果按来源缓存，每个节点只多一次请求
+ * - 识别与实际请求并行发出，不增加延迟；不一致时丢弃请求结果
+ * - 识别本身失败时不拦截（交给实际请求去报错），并在一段时间内不再重试，避免每次请求都多一次识别
+ */
+export class ChainCheckedProvider implements EthersLikeProvider {
+  #checkFailedAt = 0
+
+  constructor(
+    readonly inner: EthersLikeProvider,
+    readonly chainId: number,
+    readonly source: ProviderSource,
+    readonly timeout: number,
+  ) {}
+
+  async #check(): Promise<void> {
+    if (this.#checkFailedAt && Date.now() - this.#checkFailedAt < CHECK_RETRY_INTERVAL) {
+      return
+    }
+    let actual: number
+    try {
+      actual = await detectChainIdCached(this.source, () => detectViaNode(this.inner, this.source), this.timeout)
+    } catch {
+      this.#checkFailedAt = Date.now()
+      return
+    }
+    this.#checkFailedAt = 0
+    if (actual !== this.chainId) {
+      throw makeError(`chainId mismatch: expected ${this.chainId}, but the node is on ${actual}`, 'NETWORK_ERROR', {
+        event: 'chainIdMismatch',
+      })
+    }
+  }
+
+  async #run<T>(request: () => Promise<T>): Promise<T> {
+    const [checked, result] = await Promise.allSettled([this.#check(), request()])
+    if (checked.status === 'rejected') {
+      throw checked.reason
+    }
+    if (result.status === 'rejected') {
+      throw result.reason
+    }
+    return result.value
+  }
+
+  call(tx: TransactionRequest): Promise<string> {
+    return this.#run(() => this.inner.call(tx))
+  }
+
+  getBalance(...args: Parameters<EthersLikeProvider['getBalance']>): Promise<bigint> {
+    return this.#run(() => this.inner.getBalance(...args))
+  }
+
+  async getChainId(): Promise<number> {
+    return this.chainId
+  }
+}
+
+/** 通过已创建的节点连接识别它实际所在的链 */
+function detectViaNode(node: EthersLikeProvider, source: ProviderSource): Promise<number> {
+  if (node instanceof TronProvider) {
+    return node.getChainId()
+  }
+  // JsonRpcProvider（staticNetwork）/ BrowserProvider（'any' 网络）的 getNetwork 不反映节点实际的链，直接问节点
+  if (node instanceof JsonRpcProvider) {
+    return node.send('eth_chainId', []).then(Number)
+  }
+  return detectChainId(source, Number.POSITIVE_INFINITY)
+}
+
+function withChainCheck(chainId: number, source: ProviderSource, node: EthersLikeProvider, timeout: number): EthersLikeProvider {
+  if (!Number.isFinite(chainId) || !canDetectChainId(source) || pinnedWallets.has(node)) {
+    return node
+  }
+  return new ChainCheckedProvider(node, chainId, source, timeout)
+}
+
+/** 由 EIP-1193 钱包创建、已固定在 chainId 上的 BrowserProvider（每次请求 ethers 都会校验链），不需要再包一层 */
+const pinnedWallets = new WeakSet<EthersLikeProvider>()
+
 function toEthersLike(chainId: number, source: ProviderSource, options: SourceOptions, multiple: boolean): EthersLikeProvider {
   if (typeof source === 'string') {
     if (isTronChain(chainId)) {
@@ -78,7 +171,13 @@ function toEthersLike(chainId: number, source: ProviderSource, options: SourceOp
     return TronProvider.fromTronWeb(source as TronWebLike, options.tron)
   }
   if (typeof value.request === 'function') {
-    return new BrowserProvider(source as Eip1193Provider)
+    // 传入 chainId：钱包当前所在的链与之不符时请求报 NETWORK_ERROR（network changed），
+    // 而不是静默返回另一条链的数据；在多节点列表里会据此自动切到下一个节点
+    const wallet = new BrowserProvider(source as Eip1193Provider, Number.isFinite(chainId) ? chainId : undefined)
+    if (Number.isFinite(chainId)) {
+      pinnedWallets.add(wallet)
+    }
+    return wallet
   }
   throw new Error('Unsupported provider: expected an RPC URL, an ethers Provider, an EIP-1193 provider or a tronWeb instance')
 }

package/src/tron.ts

@@ -62,7 +62,8 @@ function toTronHex(address: string): string {
 
 /** 只用到 tronWeb 的这几个字段，兼容 tronweb v5/v6 及钱包注入的实例 */
 export interface TronWebLike {
-  fullNode: { request: (url: string, payload: Record<string, unknown>, method: string) => Promise<any> }
+  /** host 是当前连接的全节点地址，TronLink 切换网络时会变，用于区分 chainId 缓存 */
+  fullNode: { request: (url: string, payload: Record<string, unknown>, method: string) => Promise<any>; host?: string }
   defaultAddress?: { base58?: string | false }
 }
 
@@ -85,6 +86,8 @@ export interface TronProviderOptions {
   minInterval?: number
   /** 遇到 HTTP 429 时的重试次数（指数退避，从 1s 开始）。默认 3 */
   retries?: number
+  /** 单次 HTTP 请求超时（毫秒，仅对内置 fetch 生效，自定义 request 自行处理）。默认 10000；<= 0 不限制 */
+  timeout?: number
   /** 不传 from 时使用的调用者地址；传函数则每次调用时取值（钱包切换账号后自动跟随） */
   defaultFrom?: string | (() => string | null | undefined)
 }
@@ -131,8 +134,14 @@ export class TronProvider implements EthersLikeProvider {
       if (options.apiKey) {
         headers['TRON-PRO-API-KEY'] = options.apiKey
       }
+      const timeout = options.timeout ?? 10_000
       this.#request = async (path, body) => {
-        const res = await fetch(`${host}/${path}`, { method: 'POST', headers, body: JSON.stringify(body) })
+        const res = await fetch(`${host}/${path}`, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(body),
+          signal: timeout > 0 && Number.isFinite(timeout) ? AbortSignal.timeout(timeout) : undefined,
+        })
         if (!res.ok) {
           throw new HttpError(`Tron request ${path} failed: HTTP ${res.status}`, res.status)
         }
@@ -202,6 +211,16 @@ export class TronProvider implements EthersLikeProvider {
     return output
   }
 
+  /** chainId = 创世区块哈希的最后 4 字节（与 TronGrid /jsonrpc 的 eth_chainId 一致，主网 728126428） */
+  async getChainId(): Promise<number> {
+    const res = await this.#limit(() => this.#request('wallet/getblockbynum', { num: 0 }))
+    const blockId = String(res?.blockID ?? '')
+    if (!/^[0-9a-f]{64}$/i.test(blockId)) {
+      throw new Error('Unable to detect Tron chainId: unexpected genesis block response')
+    }
+    return Number.parseInt(blockId.slice(-8), 16)
+  }
+
   async getBalance(address: unknown, blockTag?: unknown): Promise<bigint> {
     assertLatest(blockTag)
     const res = await this.#limit(() => this.#request('wallet/getaccount', { address: toTronHex(String(address)) }))

package/src/util.ts

@@ -0,0 +1,20 @@
+export class TimeoutError extends Error {
+  constructor(ms: number) {
+    super(`RPC request timed out after ${ms}ms`)
+    this.name = 'TimeoutError'
+  }
+}
+
+/** ms <= 0 或非有限值表示不限制 */
+export 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))
+}