@w3lib/evm-batch-call 0.3.0 → 0.4.0

package/src/index.ts

@@ -1,80 +1,33 @@
 export { Contract, bindCall, type BoundMethod, type ContractAbi, type ContractRunner } from './contract.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,
+  getMultiBalances,
   getTokens,
+  type GetAllowancesOptions,
   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 { NATIVE_BALANCE_MODES, NATIVE_CURRENCIES, getNativeBalanceMode, getNativeCurrency, type NativeCurrency } from './chains.js'
 export { clearChainIdCache, detectChainId } from './detect.js'
 export {
   DEFAULT_NATIVE_TOKENS,
   ERC20_ABI,
   NATIVE_TOKEN,
+  exportTokenMetaCache,
   formatAmount,
+  formatUnits,
+  importTokenMetaCache,
+  persistTokenMetaCache,
+  type TokenMetaSnapshot,
+  type TokenMetaStore,
   type BalanceToken,
   type Erc20Contract,
+  type RawTokenAllowance,
+  type RawTokenBalance,
   type TokenBalance,
   type TokenAllowance,
   MAX_UINT256,
@@ -86,7 +39,10 @@ export {
 } from './erc20.js'
 export {
   Provider,
+  type AllowancesOptions,
   type BalancesOptions,
+  type BalancesQuery,
+  type BlockOptions,
   type CallInput,
   type CallResults,
   type ProviderConfig,
@@ -108,10 +64,12 @@ export {
   type TronWebLike,
 } from './tron.js'
 export { CallFailedError, decodeRevertReason, isExecutionError } from './errors.js'
-export { FallbackRpc, type FallbackOptions } from './fallback.js'
+export { AllNodesFailedError, FallbackRpc, type FallbackNodeInfo, type FallbackOptions } from './fallback.js'
+export { onRequest, type RequestEvent, type RequestListener } from './events.js'
+export { watchBalances, type WatchBalancesOptions } from './watch.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'
+export type { BlockTag, CallOverrides, EthersLikeProvider, NativeBalanceMode } from './aggregate.js'
 export type { BatchOptions } from './batcher.js'
-export type { BoundCall, Call, FailableCall, Params, RawResult } from './call.js'
+export type { BoundCall, Call, FailableCall, FailureReason, Params, RawResult, Settled } from './call.js'

package/src/multicall.ts

@@ -47,12 +47,44 @@ const MULTICALL3: Record<number, Multicall> = {
   43114: { address: CANONICAL, block: 11907934 },
   80001: { address: CANONICAL, block: 25444704 },
   421611: { address: CANONICAL, block: 10228837 },
-  5000: { address: '0xd77b59d4cb13bea71f3cc093e401720867355d6e', block: 18877383 },
+  // Mantle：标准地址上的合约字节码与其他链不同，但 aggregate3 / getBlockNumber / getEthBalance 行为一致（2026-10 实测）；
+  // ethcall 表里的 0xd77b…5d6e 调 aggregate3 会 revert
+  5000: { address: CANONICAL, block: 304717 },
   1666600000: { address: CANONICAL, block: 24185753 },
   73927: { address: '0x138A85647768815078DF1dD85C6121e611381A0b', block: 14080843 },
   // Tron 主网 TEazPvZwDjDtFeJupyo7QunvnrnUjPH8ED（链上合约名 Multicall3，2026-10 实测）
   728126428: { address: '0x32a4f47a74a6810bd0bf861cabab99656a75de9e', block: 0 },
-  81457: { address: '0x23928c6f823e0d78eadc9d2f69ace652ff3cdcb1', block: 368182 },
+  // Blast：ethcall 表里的 0x2392…cdcb1 调 aggregate3 会 revert，标准地址可用（2026-10 实测）
+  81457: { address: CANONICAL, block: 88189 },
+
+  // ---- 2026-10 实测补充：标准地址上 aggregate3 可用、区块号与节点一致 ----
+  // 部署区块查到的按实际填写；节点不提供历史状态（或忽略区块参数）查不到的，保守地填核实时的区块：
+  // 更早的历史查询走 deployless，最新状态照常用合约
+  25: { address: CANONICAL, block: 98990812 }, // Cronos，部署区块未查到
+  106: { address: CANONICAL, block: 70377223 }, // Velas，部署区块未查到
+  130: { address: CANONICAL, block: 60854543 }, // Unichain，部署区块未查到
+  143: { address: CANONICAL, block: 9248132 }, // Monad
+  204: { address: CANONICAL, block: 193943883 }, // opBNB，部署区块未查到
+  288: { address: CANONICAL, block: 40299030 }, // Boba，部署区块未查到
+  321: { address: CANONICAL, block: 56352410 }, // KCC，部署区块未查到
+  592: { address: CANONICAL, block: 761794 }, // Astar
+  988: { address: CANONICAL, block: 42479473 }, // Stable，部署区块未查到
+  999: { address: CANONICAL, block: 48135400 }, // HyperEVM，部署区块未查到
+  1116: { address: CANONICAL, block: 6988931 }, // Core
+  2818: { address: CANONICAL, block: 3654913 }, // Morph
+  4663: { address: CANONICAL, block: 84683398 }, // Robinhood Chain，部署区块未查到
+  4689: { address: CANONICAL, block: 53225909 }, // IoTeX，部署区块未查到
+  9745: { address: CANONICAL, block: 0 }, // Plasma，创世预置
+  34443: { address: CANONICAL, block: 2465882 }, // Mode
+  57073: { address: CANONICAL, block: 58104502 }, // Ink，部署区块未查到
+  59144: { address: CANONICAL, block: 42 }, // Linea
+  80094: { address: CANONICAL, block: 0 }, // Berachain，创世预置
+  534352: { address: CANONICAL, block: 14 }, // Scroll
+  86233268: { address: CANONICAL, block: 10854614 }, // Winchain，部署区块未查到
+  // 以下两条链不支持 deployless（合约创建式 eth_call 返回空 / 格式不对），只能用 Multicall3；
+  // 早于部署区块的历史查询会失败
+  42262: { address: CANONICAL, block: 22380155 }, // Oasis Emerald，部署区块未查到
+  1313161554: { address: CANONICAL, block: 62907816 }, // Aurora
 }
 
 export function getMulticall3(chainId: number): Multicall | null {

package/src/nft.ts

@@ -118,6 +118,7 @@ function expandUri(uri: string, tokenId: bigint, gateway?: string): string {
   return expanded
 }
 
+/** 批量查 ERC721 持有人（ownerOf），可混合多个集合：`await nftOwners(multi, [{ contract: BAYC, tokenId: 1 }])` */
 export async function nftOwners(provider: Provider, items: readonly NftItem[], overrides?: CallOverrides): Promise<NftOwner[]> {
   // Tron 上返回 T 开头的地址，方便与 tronWeb.defaultAddress.base58 等直接比较
   const tron = isTronChain(await provider.getChainId())
@@ -132,6 +133,7 @@ export async function nftOwners(provider: Provider, items: readonly NftItem[], o
   })
 }
 
+/** 批量查 ERC721 持有数量（balanceOf）：`await nftBalances(multi, user, [BAYC, MAYC])` */
 export async function nftBalances(
   provider: Provider,
   owner: string,
@@ -146,6 +148,7 @@ export async function nftBalances(
   })
 }
 
+/** 批量查 ERC1155 余额：`await erc1155Balances(multi, user, [{ contract, tokenId: 1 }])` */
 export async function erc1155Balances(
   provider: Provider,
   owner: string,
@@ -169,6 +172,7 @@ export async function erc1155Balances(
   })
 }
 
+/** 批量查 NFT 元数据地址：兼容 ERC721 tokenURI 与 ERC1155 uri（{id} 按规范替换），可转换 ipfs:// */
 export async function nftTokenUris(provider: Provider, items: readonly NftItem[], options: NftTokenUriOptions = {}): Promise<NftTokenUri[]> {
   const { ipfsGateway, ...overrides } = options
   const chainId = await provider.getChainId()
@@ -227,6 +231,7 @@ export async function nftTokenUris(provider: Provider, items: readonly NftItem[]
   })
 }
 
+/** 批量查 NFT 集合信息（标准 / name / symbol / totalSupply），字段可选 */
 export async function nftCollections<F extends NftCollectionField = DefaultNftCollectionField>(
   provider: Provider,
   collections: readonly string[],

package/src/owner.ts

@@ -1,5 +1,5 @@
 import type { CallOverrides } from './aggregate.js'
-import { NATIVE_TOKEN, formatAmount, type BalanceToken } from './erc20.js'
+import { NATIVE_TOKEN, formatUnits, type BalanceToken } from './erc20.js'
 import type { Provider } from './provider.js'
 import { transferScan, type TransferScanOptions } from './scan.js'
 import { isTronAddress } from './tron.js'
@@ -555,6 +555,15 @@ export interface OwnedToken {
   source: string
 }
 
+/**
+ * 列出持有人拥有的代币（资产列表）：从代币来源拿候选代币，再用 multicall 在链上核对余额。
+ * 默认来源是公开代币列表，**只能发现列表里的代币**，局限性见 README「资产列表」一节。
+ *
+ * @deprecated 不推荐使用：EVM 链上无法只靠节点可靠地列出地址持有的全部代币，这个方法只是尽力而为——
+ * 默认来源只能发现公开列表里的代币，依赖第三方免费服务（可能限流、改格式或停止服务），要查几千个代币的余额、耗时数秒，
+ * 价格也不一定可信；传 `alchemy` / `nodereal` 来源能查全，但同样受第三方服务的额度和可用性约束。
+ * 已知要查哪些代币时请用 `getBalances`；需要可靠的完整持仓请直接接入索引服务的接口或自己的索引。局限性详见 README「资产列表」。
+ */
 export async function ownerTokens(provider: Provider, owner: string, options: OwnerTokensOptions = {}): Promise<OwnedToken[]> {
   const { source: baseSource = defaultTokenSource(), prices, minUsd, includeNative = true, fetch: fetchOption, scanTransfers, ...overrides } = options
   const source = scanTransfers ? combine(baseSource, transferScan(scanTransfers === true ? {} : scanTransfers)) : baseSource
@@ -606,7 +615,7 @@ export async function ownerTokens(provider: Provider, owner: string, options: Ow
       return []
     }
     const decimals = chain.decimals
-    const formatted = decimals === balance.decimals ? balance.formatted : formatAmount(BigInt(balance.balance), decimals)
+    const formatted = decimals === balance.decimals ? balance.formatted : formatUnits(BigInt(balance.balance), decimals)
     const price = priceMap.get(addressKey(meta.address))
     return [
       {