@w3lib/evm-batch-call 0.2.0 → 0.4.0

package/src/subpaths/nft.ts

@@ -0,0 +1,107 @@
+/**
+ * NFT 查询（子路径 `@w3lib/evm-batch-call/nft`）：ERC721 / ERC1155 的集合信息、持有数量、持有人、元数据地址。
+ * 不放在主入口，不用 NFT 功能时打包不会带上这部分代码。
+ *
+ * ```ts
+ * import { Provider } from '@w3lib/evm-batch-call'
+ * import { getNftOwners, nftOwners } from '@w3lib/evm-batch-call/nft'
+ *
+ * await getNftOwners([{ contract: BAYC, tokenId: 1 }], { chainId: 1 })   // 节点参数与 getBalances 相同
+ * await nftOwners(multi, [{ contract: BAYC, tokenId: 1 }])              // 或传已创建的 Provider
+ * ```
+ */
+import {
+  erc1155Balances,
+  nftBalances,
+  nftCollections,
+  nftOwners,
+  nftTokenUris,
+  type DefaultNftCollectionField,
+  type Erc1155Balance,
+  type NftBalance,
+  type NftCollection,
+  type NftCollectionField,
+  type NftItem,
+  type NftOwner,
+  type NftTokenUri,
+  type NftCollectionsOptions,
+} from '../nft.js'
+import { resolve, type ShortcutOptions, type ShortcutProviderOptions } from '../shortcuts.js'
+
+export {
+  DEFAULT_NFT_COLLECTION_FIELDS,
+  ERC1155_ABI,
+  ERC721_ABI,
+  erc1155Balances,
+  nftBalances,
+  nftCollections,
+  nftOwners,
+  nftTokenUris,
+  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 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 nftCollections<F>(provider, 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 nftBalances(provider, 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 nftOwners(provider, 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 nftTokenUris(provider, 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 erc1155Balances(provider, owner, items, overrides)
+}

package/src/subpaths/owner.ts

@@ -0,0 +1,69 @@
+/**
+ * 资产列表（子路径 `@w3lib/evm-batch-call/owner`）：从代币来源发现候选代币，multicall 核对余额；含代币来源、价格源、
+ * Transfer 事件增量扫描。不放在主入口，不用时打包不会带上这部分代码。
+ *
+ * ```ts
+ * import { getOwnerTokens, ownerTokens, alchemy } from '@w3lib/evm-batch-call/owner'
+ *
+ * await getOwnerTokens(user, { chainId: 56 })
+ * await ownerTokens(multi, user, { source: alchemy({ apiKey }) })   // 或传已创建的 Provider
+ * ```
+ */
+import { ownerTokens, type OwnedToken, type OwnerTokensOptions } from '../owner.js'
+import { resolve, type ShortcutProviderOptions } from '../shortcuts.js'
+
+export {
+  ALCHEMY_NETWORKS,
+  COINGECKO_PLATFORMS,
+  DEFILLAMA_CHAINS,
+  alchemy,
+  clearTokenListCache,
+  coingeckoTokenList,
+  combine,
+  defaultTokenSource,
+  defillamaPrices,
+  firstAvailable,
+  metamaskTokenList,
+  nodereal,
+  ownerTokens,
+  staticTokens,
+  tokenList,
+  type DiscoveredToken,
+  type IndexerSourceOptions,
+  type OwnedToken,
+  type OwnerTokensOptions,
+  type PriceSource,
+  type PriceSourceContext,
+  type TokenSource,
+  type TokenSourceContext,
+} from '../owner.js'
+export {
+  getTransferScanState,
+  keyValueScanStorage,
+  memoryScanStorage,
+  transferScan,
+  type TransferScanOptions,
+  type TransferScanState,
+  type TransferScanStorage,
+} from '../scan.js'
+
+export interface GetOwnerTokensOptions extends OwnerTokensOptions, ShortcutProviderOptions {}
+
+/**
+ * 列出持有人拥有的代币（资产列表）。默认用免费公开代币列表发现代币，余额用 multicall 在链上核对。
+ *
+ * ```ts
+ * await getOwnerTokens(user, { chainId: 56 })                                  // 免费，只能发现公开列表里的代币
+ * await getOwnerTokens(user, { chainId: 1, prices: true, minUsd: 1 })          // 带美元价值，过滤零头和垃圾币
+ * await getOwnerTokens(user, { chainId: 56, source: alchemy({ apiKey }) })     // 用 Alchemy 查全部历史持仓
+ * ```
+ *
+ * @deprecated 不推荐使用：EVM 链上无法只靠节点可靠地列出地址持有的全部代币，这个方法只是尽力而为——
+ * 默认来源只能发现公开列表里的代币，依赖第三方免费服务（可能限流、改格式或停止服务），要查几千个代币的余额、耗时数秒，
+ * 价格也不一定可信；传 `alchemy` / `nodereal` 来源能查全，但同样受第三方服务的额度和可用性约束。
+ * 已知要查哪些代币时请用 `getBalances`；需要可靠的完整持仓请直接接入索引服务的接口或自己的索引。局限性详见 README「资产列表」。
+ */
+export function getOwnerTokens(owner: string, options: GetOwnerTokensOptions = {}): Promise<OwnedToken[]> {
+  const { provider, overrides, own } = resolve(options, ['source', 'prices', 'minUsd', 'includeNative', 'fetch', 'scanTransfers'])
+  return ownerTokens(provider, owner, { ...overrides, ...own })
+}

package/src/tron.ts

@@ -19,6 +19,13 @@ export const TRON_CHAIN_ID = {
   nile: 3448148188,
 } as const
 
+const TRON_CHAIN_IDS = new Set<number>(Object.values(TRON_CHAIN_ID))
+
+/** 是否是 Tron 链（主网 / 测试网）：只能查最新状态，地址区分大小写 */
+export function isTronChain(chainId: number): boolean {
+  return TRON_CHAIN_IDS.has(chainId)
+}
+
 const TRON_ADDRESS_RE = /^T[1-9A-HJ-NP-Za-km-z]{33}$/
 
 export function isTronAddress(value: unknown): boolean {

package/src/util.ts

@@ -18,3 +18,30 @@ export function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
     }),
   ]).finally(() => clearTimeout(timer))
 }
+
+/**
+ * 支持 AbortSignal：已取消时直接 reject（不执行 work，不发请求）；执行中取消时立即 reject（reason 为 signal.reason），
+ * 底层请求不中断（可能与其他调用合并在同一个请求里），结果丢弃
+ */
+export function withSignal<T>(signal: AbortSignal | undefined, work: () => Promise<T>): Promise<T> {
+  if (!signal) {
+    return work()
+  }
+  if (signal.aborted) {
+    return Promise.reject(signal.reason)
+  }
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason)
+    signal.addEventListener('abort', onAbort, { once: true })
+    work().then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort)
+        resolve(value)
+      },
+      (err: unknown) => {
+        signal.removeEventListener('abort', onAbort)
+        reject(err)
+      },
+    )
+  })
+}

package/src/watch.ts

@@ -0,0 +1,149 @@
+import type { BalanceToken, RawTokenBalance, TokenBalance } from './erc20.js'
+import type { Provider } from './provider.js'
+import { resolve, type GetBalancesOptions } from './shortcuts.js'
+
+type AnyBalance = TokenBalance | RawTokenBalance
+
+export interface WatchBalancesOptions<B extends AnyBalance = TokenBalance> extends Omit<GetBalancesOptions, 'signal' | 'minBlock' | 'blockTag'> {
+  /** 轮询间隔（毫秒），默认 15000；多处订阅同一份数据时取最小的间隔 */
+  interval?: number
+  /** 第一次拿到结果、以及之后余额变化时调用；previous 是上一次通知的结果（第一次为 null） */
+  onChange: (balances: B[], previous: B[] | null) => void
+  /** 某次查询失败时调用（轮询继续） */
+  onError?: (err: unknown) => void
+}
+
+interface Subscriber {
+  tokens: readonly BalanceToken[]
+  interval: number
+  onChange: (balances: AnyBalance[], previous: AnyBalance[] | null) => void
+  onError?: (err: unknown) => void
+  last: AnyBalance[] | null
+  signature: string | null
+}
+
+interface Watch {
+  subscribers: Set<Subscriber>
+  timer: ReturnType<typeof setTimeout> | null
+  running: boolean
+  /** 最近一次的结果（按规范化的代币 key），新订阅者可以立即拿到 */
+  latest: Map<string, AnyBalance> | null
+}
+
+// 按 Provider 实例分组（快捷函数对相同节点参数复用同一个实例），组内按 “钱包 + 代币集合 + 选项” 共用一份轮询
+const watches = new WeakMap<Provider, Map<string, Watch>>()
+
+/** 调用订阅者的回调：出错不影响其他订阅者和轮询 */
+function safely(fn: () => void): void {
+  try {
+    fn()
+  } catch {
+    // 订阅者自己的错误（如渲染出错）不归轮询处理
+  }
+}
+
+/** 0x 地址不区分大小写，统一小写；Tron 的 T 开头地址区分大小写，原样保留 */
+const normalize = (address: string) => (/^0x/i.test(address) ? address.toLowerCase() : address)
+
+const tokenKey = (token: BalanceToken) => (typeof token === 'string' ? normalize(token) : `${normalize(token.address)}:${token.decimals ?? ''}`)
+
+/**
+ * 轮询余额，多处订阅同一个钱包的同一组代币时合并成一份轮询（代币顺序无关），只在余额变化时通知。返回取消订阅的函数；
+ * 最后一个订阅者取消后停止轮询。节点参数与 getBalances 相同（相同参数复用同一个 Provider，才能共用轮询）。
+ *
+ * ```ts
+ * const stop = watchBalances(user, [NATIVE_TOKEN, USDT], { chainId: 56, interval: 10_000, onChange: (list) => render(list) })
+ * ```
+ */
+export function watchBalances(owner: string, tokens: readonly BalanceToken[], options: WatchBalancesOptions<RawTokenBalance> & { decimals: false }): () => void
+export function watchBalances(owner: string, tokens: readonly BalanceToken[], options: WatchBalancesOptions): () => void
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- 实现签名需兼容两种 onChange 参数类型
+export function watchBalances(owner: string, tokens: readonly BalanceToken[], options: WatchBalancesOptions<any>): () => void {
+  const { interval = 15_000, onChange, onError, ...rest } = options
+  const { provider, overrides, own } = resolve(rest, ['symbol', 'decimals', 'withBlock'])
+  const balancesOptions = { ...overrides, ...own }
+  const unique = [...new Map(tokens.map((token) => [tokenKey(token), token])).entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+  const key = JSON.stringify([normalize(owner), unique.map(([k]) => k), balancesOptions])
+
+  let group = watches.get(provider)
+  if (!group) {
+    group = new Map()
+    watches.set(provider, group)
+  }
+  let watch = group.get(key)
+  const isNew = !watch
+  if (!watch) {
+    watch = { subscribers: new Set(), timer: null, running: false, latest: null }
+    group.set(key, watch)
+  }
+  const subscriber: Subscriber = { tokens, interval, onChange: onChange as Subscriber['onChange'], onError, last: null, signature: null }
+  watch.subscribers.add(subscriber)
+
+  const current = watch
+  const groupRef = group
+  const notify = (sub: Subscriber) => {
+    if (!current.latest) {
+      return
+    }
+    const list = sub.tokens.map((token) => {
+      const item = current.latest?.get(tokenKey(token)) as AnyBalance
+      return { ...item, token: typeof token === 'string' ? token : token.address }
+    })
+    const signature = JSON.stringify(list.map((b) => [b.balance, b.success]))
+    if (signature === sub.signature) {
+      return
+    }
+    const previous = sub.last
+    sub.last = list
+    sub.signature = signature
+    safely(() => sub.onChange(list, previous))
+  }
+  const schedule = () => {
+    if (!current.subscribers.size) {
+      return
+    }
+    const wait = Math.min(...[...current.subscribers].map((sub) => sub.interval))
+    current.timer = setTimeout(poll, wait)
+  }
+  const poll = async () => {
+    current.timer = null
+    if (current.running || !current.subscribers.size) {
+      return
+    }
+    current.running = true
+    try {
+      const list = (await provider.balances(owner, unique.map(([, token]) => token), balancesOptions)) as AnyBalance[]
+      current.latest = new Map(unique.map(([k], i) => [k, list[i] as AnyBalance]))
+      current.subscribers.forEach(notify)
+    } catch (err) {
+      current.subscribers.forEach((sub) => safely(() => sub.onError?.(err)))
+    } finally {
+      current.running = false
+      schedule()
+    }
+  }
+
+  if (isNew) {
+    void poll()
+  } else {
+    // 已有轮询：有结果就立即给新订阅者；新订阅者的间隔更短时重新计时
+    queueMicrotask(() => current.subscribers.has(subscriber) && notify(subscriber))
+    if (current.timer && interval < Math.min(...[...current.subscribers].filter((s) => s !== subscriber).map((s) => s.interval))) {
+      clearTimeout(current.timer)
+      schedule()
+    }
+  }
+
+  return () => {
+    current.subscribers.delete(subscriber)
+    if (!current.subscribers.size) {
+      if (current.timer) {
+        clearTimeout(current.timer)
+        current.timer = null
+      }
+      if (groupRef.get(key) === current) {
+        groupRef.delete(key)
+      }
+    }
+  }
+}