@w3lib/evm-batch-call 0.3.0 → 0.4.1

package/src/shortcuts.ts

@@ -1,18 +1,6 @@
 import type { CallOverrides } from './aggregate.js'
-import type { OwnedToken, OwnerTokensOptions } from './owner.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 共用的节点参数 */
@@ -25,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>
@@ -67,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'
   }
@@ -76,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')
   }
@@ -113,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)) {
@@ -129,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>,
   }
 }
@@ -145,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 })
 }
 
 /**
@@ -168,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 })
 }
 
 /**
@@ -184,87 +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)
-}
-
-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 provider.ownerTokens(owner, { ...overrides, ...own })
+  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, chainId: Number.isFinite(chainId) ? chainId : undefined }))
+  // 单节点也经过 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'
 }
 
 /** 识别失败后多久内不再重试识别（期间请求照常发出，不做校验） */

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)
+      },
+    )
+  })
+}