@w3lib/evm-batch-call 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 0.4.1
+
+### 修复
+
+- 节点返回 `result: null` 等无法解析的结果时（ethers 报 `INVALID_ARGUMENT`，值为 null），换下一个节点、不冷却（调用方传入 undefined 等非法参数仍直接抛出）；原来被当成确定性错误直接抛出、不换节点（如 Unichain 官方节点对未来区块返回 null）
+- `eth_call` 返回空数据（`0x`）或无法解码时换下一个节点重试，不冷却：deployless 原来直接报 `BAD_DATA`；Multicall3 原来偶发一次就在整个会话里弃用（在不支持 deployless 的 Oasis Emerald、Aurora 上会导致批量查询全部失败）。现在最多试 2 个节点：2 个节点都返回空数据（或单节点连续 2 次）才判定合约不可用，10 分钟后重新尝试；有节点返回空数据、其余节点出错时退回 deployless
+- `minBlock`：按区块号重查的结果同样校验区块号——有的节点对未来区块不报错、直接返回最新状态（如 HyperEVM），原来会把早于 `minBlock` 的旧状态当成结果
+- 识别更多节点的“区块不存在”报错（Arbitrum 系 `unsupported block number`、X Layer、Mantle、zkSync、Winchain 等），只换节点、不冷却
+- `stallTimeout`：在并发竞争中输给后发节点的慢节点，冷却期内排到健康节点之后；原来慢但不超时的首选节点永不降级，每次查询都多等一个 `stallTimeout`
+- 钱包等对象节点的健康状态按链分开记：钱包在一条链上出错，不再影响它在其他链上的排序
+- 合并请求结束后移除挂在调用方 `signal` 上的监听（长期存在的 signal 发起多次查询时不再累积）
+- `watchBalances`：新订阅的间隔更短时按上次轮询时间计算下一次，不再因重新计时而推迟
+- 导入代币信息缓存时，时间戳只接受有限值，晚于现在的截到现在（原来未来时间、`NaN` / `Infinity` 会让 name / symbol 永不过期）
+
+## 0.4.0
+
+### 不兼容的改动
+
+- 代币信息缓存与 solana-batch-call 对齐：最多 5 万个代币（超出淘汰最早的），name / symbol 缓存 1 小时后重查（可升级合约可能改名）；decimals 仍永久缓存
+- 单节点也经过 `FallbackRpc`（统一触发 onRequest 事件），`provider.rpc` 始终是 `FallbackRpc`，底层节点在 `rpc.nodes[0]`；错误仍是节点的原始错误
+- NFT 查询和资产列表移到子路径，不用时打包不再带上（拆出后约少 15KB；只用 `getBalances` 时 minify 后约 44KB，含本版本新增功能，不含 ethers）：
+  - `@w3lib/evm-batch-call/nft`：`getNftCollections` / `getNftBalances` / `getNftOwners` / `getNftTokenUris` / `getErc1155Balances`、`ERC721_ABI` / `ERC1155_ABI` 及相关类型
+  - `@w3lib/evm-batch-call/owner`：`getOwnerTokens`、代币来源（`metamaskTokenList` / `alchemy` / `combine` …）、`defillamaPrices`、`transferScan` / `keyValueScanStorage` 等
+  - 删除 `Provider` 上的 `nftCollections` / `nftBalances` / `nftOwners` / `nftTokenUris` / `erc1155Balances` / `ownerTokens` 方法，改用子路径里接收 Provider 的同名函数：`multi.nftOwners(items)` → `nftOwners(multi, items)`
+- `balances` / `tokens` / `allowances` 的子调用改走自动合并队列（见下），与同一时刻的其他查询合并成一次 `eth_call`；结果不变，但请求会推迟到 `batch.wait` 收集窗口结束（默认同一 tick）
+
+### 新增
+
+- `nativeBalance` 配置：`'contract'`（默认）| `'rpc'`（主币单独走 `eth_getBalance`）| `{ erc20 }`（主币改调 ERC20 的 `balanceOf`），对 `balances`、`getEthBalance`、`all` / `call` / `staticCall` 都生效；内置表 `NATIVE_BALANCE_MODES` 收录合约里读主币余额恒为 0 的链（Anubis 6714 默认 `'rpc'`）
+- `pnpm check:rpc` 比对每条链“合约里读到的主币余额”（Multicall3 / deployless）与 `eth_getBalance`，不一致且没有配置时报错
+- `balances` / `allowances`（及 `getBalances` / `getAllowances`）的 `decimals: false` 选项：只查余额 / 额度，结果不带 `decimals` / `formatted`（返回类型 `RawTokenBalance` / `RawTokenAllowance`）；没有 `decimals` 的合约（ERC721）也能拿到余额
+- `balances` / `tokens` / `allowances` 的失败项带 `error`（`invalid-address` / `invalid-argument` / `no-contract` / `reverted` / `decode-failed` / `not-configured`）和 `errorField`（哪一项没读到）
+- `balances` / `tokens` / `allowances` 参与自动合并：不同组件同时发起的查询、单条 `await` 调用合成一次 `eth_call` 并去重；一次调用的子调用不会被 `batch.maxSize` 拆开
+- `fallback.stallTimeout`：当前节点超过这个时间未返回时同时请求下一个节点，先成功的胜出（与 ethers `FallbackProvider` 的 stallTimeout 相同，没有首次请求前的全节点同步）；默认 0 不启用
+- 快捷函数：`[window.ethereum, ...urls]` 这类钱包 + URL 混合列表也复用 Provider 实例；`provider` 参数可以直接传 `Provider` 实例
+- 所有节点都失败时抛 `AllNodesFailedError`，带每个节点的标识（URL 只取 host）和失败原因；单节点时仍抛原始错误
+- 超时与出错分开计：超时只换节点、不冷却，同一节点连续 3 次超时才冷却；节点冷却状态按节点（URL / 对象）全局共享，Provider 重建后仍有效
+- `onRequest(listener)`：订阅所有节点请求（节点、方法、耗时、成败、第几个节点），用于观察故障切换和耗时
+- 所有查询支持 `signal`（AbortSignal）：已取消时不发请求，查询中取消立即 reject
+- `withBlock`：`balances` / `tokens` / `allowances` 的结果带读取时的区块号（同一次 `eth_call` 里读出；deployless 合约新增对 `getBlockNumber()` 的支持）
+- `minBlock`：节点落后于指定区块时按该区块重查、自动换节点（落后不进入冷却），所有节点都落后时稍等重试（约 10 秒，可用 signal 取消），用于交易刚确认后刷新余额；Tron 上等节点跟上后查最新状态
+- `getMultiBalances` / `multiBalances`：多个钱包一次查，同一条链上合成一次 multicall
+- `watchBalances`：轮询余额，多处订阅同一份数据时合并成一份轮询，只在余额变化时通知
+- 代币信息缓存可持久化：`persistTokenMetaCache(localStorage)`、`exportTokenMetaCache` / `importTokenMetaCache`
+- `formatUnits`（与 ethers 同名）；`formatAmount` 保留为别名并标记 deprecated
+
+- Multicall3 地址表补充 23 条链（2026-10 逐条在链上实测 aggregate3 可用）：Cronos、Velas、Unichain、Monad、opBNB、Boba、KCC、Astar、Stable、HyperEVM、Core、Morph、Robinhood Chain、IoTeX、Plasma、Mode、Ink、Linea、Berachain、Scroll、Winchain、Oasis Emerald、Aurora。其中 Oasis Emerald、Aurora 不支持 deployless，原来在这两条链上批量查询会失败
+- `pnpm check:rpc` 检查每条链的批量调用方式：内置表里的 Multicall3 能否调用 aggregate3、deployless 能否执行，两种都不可用时报错
+
+### 修复
+
+- Mantle、Blast 的 Multicall3 地址（来自 ethcall 的表）调用 aggregate3 会 revert，改为标准地址（原来会自动退回 deployless，结果正确但多一次失败的请求）
+- Arbitrum 系的链（Arbitrum One、Robinhood Chain 等）在合约里 `block.number` 是 L1 区块号：`withBlock` / `minBlock` 改为读 ArbSys 的 `arbBlockNumber()`，得到 L2 区块号
+- `all<any>(calls)` / `tryAll<any>(calls)` 显式写 any 时返回 `any[]`，可以按数组解构（原来命中第一个重载，返回值不能解构）
+
+### 文档
+
+- 零地址默认按主币处理，在 README 中单独醒目说明，并给出只保留 `0xeeee…eeee` 的配置
+
 ## 0.3.0
 
 ### 新增

package/README.md

@@ -13,22 +13,15 @@ pnpm add @w3lib/evm-batch-call ethers
 常用的批量查询都有现成函数，一次请求查完一批，结果都是字符串 / 数字 / 布尔，可以直接 `JSON.stringify`：
 
 ```ts
-import {
-  NATIVE_TOKEN,
-  getAllowances,
-  getBalances,
-  getErc1155Balances,
-  getNftBalances,
-  getNftCollections,
-  getNftOwners,
-  getNftTokenUris,
-  getTokens,
-} from '@w3lib/evm-batch-call'
+import { NATIVE_TOKEN, getAllowances, getBalances, getTokens } from '@w3lib/evm-batch-call'
+import { getErc1155Balances, getNftBalances, getNftCollections, getNftOwners, getNftTokenUris } from '@w3lib/evm-batch-call/nft' // NFT 在子路径
 
 // 余额：主币 + 代币，带 decimals 换算
 await getBalances(user, [NATIVE_TOKEN, USDT], { chainId: 56 })
 // [{ token: NATIVE_TOKEN, native: true, balance: '1500000000000000000', decimals: 18, formatted: '1.5', success: true }, ...]
 await getBalances(user, [NATIVE_TOKEN, USDT], { chainId: 56, symbol: true }) // 额外返回 symbol
+await getBalances(user, [BAYC, USDT], { chainId: 1, decimals: false })       // 只查余额，不查 decimals（没有 decimals 的合约也能查）
+// [{ token: BAYC, native: false, balance: '128', success: true }, ...]
 
 // 代币详情，字段可选：name / symbol / decimals / totalSupply（默认前三个）
 await getTokens([USDT, NATIVE_TOKEN], { chainId: 56, fields: ['symbol', 'decimals', 'totalSupply'] })
@@ -46,26 +39,53 @@ await getNftTokenUris([{ contract: BAYC, tokenId: 1 }], { chainId: 1, ipfsGatewa
 await getErc1155Balances(user, [{ contract: ITEMS, tokenId: 7 }], { chainId: 137 })         // ERC1155 余额
 ```
 
-| 函数 | Provider 方法 | 说明 |
+| 函数 | 传 Provider 实例的写法 | 说明 |
 | --- | --- | --- |
-| `getBalances(owner, tokens, opts)` | `balances` | 主币 + 代币余额；`symbol: true` 额外返回 symbol |
-| `getOwnerTokens(owner, opts)` | `ownerTokens` | 资产列表：地址持有的代币（**不推荐使用**，结果不保证完整，见[资产列表](#资产列表)） |
-| `getTokens(tokens, opts)` | `tokens` | ERC20 详情，`fields` 选择返回字段，结果类型随之收窄 |
-| `getAllowances(owner, spender, tokens, opts)` | `allowances` | 授权额度；`unlimited` 表示额度 ≥ uint96 最大值（覆盖 MaxUint256 及 UNI / COMP 这类截断为 uint96 的代币） |
-| `getNftCollections(contracts, opts)` | `nftCollections` | NFT 集合 standard / name / symbol / totalSupply，`fields` 可选 |
-| `getNftBalances(owner, contracts, opts)` | `nftBalances` | ERC721 持有数量 |
-| `getNftOwners(items, opts)` | `nftOwners` | ERC721 持有人，可混合多个集合；不存在的 tokenId 为 null；Tron 链上返回 T 开头的地址 |
-| `getNftTokenUris(items, opts)` | `nftTokenUris` | 元数据地址：自动兼容 ERC721 `tokenURI` 与 ERC1155 `uri`（`{id}` 按规范替换），`ipfsGateway` 转换 `ipfs://`；首次查询顺带识别集合标准并缓存，之后只发对应的调用 |
-| `getErc1155Balances(owner, items, opts)` | `erc1155Balances` | ERC1155 余额 |
+| `getBalances(owner, tokens, opts)` | `multi.balances(owner, tokens, opts)` | 主币 + 代币余额；`symbol: true` 额外返回 symbol；`decimals: false` 只查余额 |
+| `getTokens(tokens, opts)` | `multi.tokens(tokens, opts)` | ERC20 详情，`fields` 选择返回字段，结果类型随之收窄 |
+| `getAllowances(owner, spender, tokens, opts)` | `multi.allowances(...)` | 授权额度；`unlimited` 表示额度 ≥ uint96 最大值（覆盖 MaxUint256 及 UNI / COMP 这类截断为 uint96 的代币）；`decimals: false` 只查额度 |
+| `getNftCollections(contracts, opts)` | `nftCollections(multi, contracts, opts)` | **子路径 `/nft`**。NFT 集合 standard / name / symbol / totalSupply，`fields` 可选 |
+| `getNftBalances(owner, contracts, opts)` | `nftBalances(multi, owner, contracts)` | **`/nft`**。ERC721 持有数量 |
+| `getNftOwners(items, opts)` | `nftOwners(multi, items)` | **`/nft`**。ERC721 持有人，可混合多个集合；不存在的 tokenId 为 null；Tron 链上返回 T 开头的地址 |
+| `getNftTokenUris(items, opts)` | `nftTokenUris(multi, items, opts)` | **`/nft`**。元数据地址：自动兼容 ERC721 `tokenURI` 与 ERC1155 `uri`（`{id}` 按规范替换），`ipfsGateway` 转换 `ipfs://`；首次查询顺带识别集合标准并缓存，之后只发对应的调用 |
+| `getErc1155Balances(owner, items, opts)` | `erc1155Balances(multi, owner, items)` | **`/nft`**。ERC1155 余额 |
+| `getOwnerTokens(owner, opts)` | `ownerTokens(multi, owner, opts)` | **子路径 `/owner`**。资产列表：地址持有的代币（**不推荐使用**，结果不保证完整，见[资产列表](#资产列表)） |
+
+**子路径**：NFT 查询在 `@w3lib/evm-batch-call/nft`，资产列表（含代币来源、价格源、Transfer 增量扫描）在 `@w3lib/evm-batch-call/owner`。不用这些功能时打包不会带上它们的代码（拆出后约少 15KB：只用 `getBalances` 时 minify 后约 44KB、gzip 约 16KB，均不含 ethers）。
 
 共同的规则：
 
-- **主币**：`0xeeee…eeee`（导出为 `NATIVE_TOKEN`，不区分大小写）和零地址按主币处理，不发合约调用；name / symbol / 精度来自内置链信息表（`NATIVE_CURRENCIES`），可用 `nativeTokens` / `nativeName` / `nativeSymbol` / `nativeDecimals` 配置
-- **缓存**：decimals / symbol / name / NFT 标准不会变，查过一次后按链缓存（各函数共用），之后只查会变的数据；已知精度可以直接传 `{ address, decimals }`（主币也适用，优先于内置配置）
-- **失败**：单项失败（非合约地址、非法地址、不存在的 tokenId 等）不影响其他项，该项 `success: false`；整个请求失败（节点不可用等）才会抛错
-- **数值**：原始数值是最小单位的十进制字符串，需要计算时用 `BigInt(x)`；`formatted` 保留全部有效小数位、不四舍五入，整数不带小数点（单独格式化可用 `formatAmount(value, decimals)`）
+- **主币**：`0xeeee…eeee`（导出为 `NATIVE_TOKEN`，不区分大小写）按主币处理，不发合约调用；name / symbol / 精度来自内置链信息表（`NATIVE_CURRENCIES`），可用 `nativeTokens` / `nativeName` / `nativeSymbol` / `nativeDecimals` 配置
+- **⚠ 零地址 `0x0000…0000` 默认也按主币处理**（返回主币余额，不会去调零地址上的 `balanceOf`）。如果你的数据里零地址代表别的含义，传 `nativeTokens: [NATIVE_TOKEN]` 只保留 `0xeeee…eeee`
+- **主币余额的读取方式**：默认和合约调用放在同一次 `eth_call` 里。有的链在合约里读主币余额恒为 0、不报错（如 Anubis），内置表 `NATIVE_BALANCE_MODES` 已为这类链改用 `eth_getBalance`；其他链可用 `nativeBalance: 'rpc'` 或 `{ erc20: '0x…' }` 配置，见[主币余额与 deployless](#主币余额与-deployless)
+- **缓存**：查过一次后按链缓存（各函数共用），之后只查会变的数据。decimals / NFT 标准永久缓存；name / symbol 在可升级合约上可能改，各自缓存 1 小时；最多 5 万个代币，超出淘汰最早的（与 solana-batch-call 一致）。已知精度可以直接传 `{ address, decimals }`（主币也适用，优先于内置配置）。缓存可以持久化，见[缓存持久化](#缓存持久化)
+- **失败**：单项失败（非合约地址、非法地址、不存在的 tokenId 等）不影响其他项，该项 `success: false`；整个请求失败（节点不可用等）才会抛错。`getBalances` / `getTokens` / `getAllowances` 的失败项还带 `error`（`invalid-address` 地址非法、`invalid-argument` 其他参数编码失败、`no-contract` 地址上没有合约、`reverted` 执行 revert、`decode-failed` 返回值无法解码、`not-configured` 没发请求的信息缺失，如主币不在内置链信息表里）和 `errorField`（哪一项没读到，如 `balance` / `decimals`），可以按原因分别处理（如地址非法报错、没有合约按 0）
+- **取消**：所有查询都可以传 `signal`（`AbortController`）：已取消时不发请求；查询中取消时立即 reject，合并在一起的底层请求继续完成、结果丢弃。切换代币时不必再手动比对、丢弃旧结果
+- **只查余额**：`decimals: false` 时不查 decimals，结果不带 `decimals` / `formatted`（类型随之变化）。适合没有 `decimals` 的合约（ERC721 的 `balanceOf`）、或只需要原始数值的场景，冷启动时子调用数减半
+- **数值**：原始数值是最小单位的十进制字符串，需要计算时用 `BigInt(x)`；`formatted` 保留全部有效小数位、不四舍五入，整数不带小数点（单独格式化可用 `formatUnits(value, decimals)`；旧名 `formatAmount` 仍可用，已标记 deprecated）
 - **老代币**：symbol / name 返回 bytes32 的代币（MKR 等）也能解析
 
+### 多个钱包、轮询、刚成交后刷新
+
+```ts
+import { getMultiBalances, watchBalances } from '@w3lib/evm-batch-call'
+
+// 多个钱包一次查：同一条链上合成一次 multicall
+const [a, b] = await getMultiBalances([{ owner: walletA, tokens: [NATIVE_TOKEN, USDT] }, { owner: walletB, tokens: [USDT] }], { chainId: 56 })
+
+// 轮询：多处订阅同一个钱包的同一组代币时合并成一份轮询（代币顺序无关），只在余额变化时通知；返回取消订阅的函数
+const stop = watchBalances(user, [NATIVE_TOKEN, USDT], { chainId: 56, interval: 10_000, onChange: (list, previous) => render(list) })
+
+// 交易刚确认：要求读到的数据不早于交易所在区块（公共节点可能还落后一两个块）
+const receipt = await tx.wait()
+await getBalances(user, tokens, { chainId: 56, minBlock: receipt.blockNumber })
+await getBalances(user, tokens, { chainId: 56, withBlock: true }) // 每项带 blockNumber：读取时的区块号
+```
+
+- **`withBlock`**：区块号与数据在同一次 `eth_call` 里读出（Multicall3 的 `getBlockNumber`；deployless 合约里直接取 `block.number`），不多发请求。`balances` / `tokens` / `allowances` 及对应函数都支持
+- **`minBlock`**：先按最新状态查并顺带读区块号；节点落后时按 `minBlock` 指定区块重查——落后的节点对未来区块报错，自动换下一个节点（落后不算故障，不进入冷却）；所有节点都落后时每秒重试，最多约 10 秒后抛错，传了 `signal` 时取消后立即停止。重查得到的是 `minBlock` 那个区块的状态（已包含刚确认的交易）。只对最新状态的查询生效（指定了 `blockTag` 时忽略）。Tron 节点只能查最新状态，落后时等节点跟上再查。`nativeBalance: 'rpc'` 时主币余额在批量查询实际读取的区块上用 `eth_getBalance` 读取，与代币余额、`blockNumber` 一致
+- **`watchBalances`**：相同的节点参数 + 钱包 + 代币 + 选项共用一份轮询（多处订阅时取最小的 `interval`），新订阅者立即拿到最近一次的结果；查询失败调用 `onError`，轮询继续；上一次查询没完成时不会重叠发起；最后一个订阅者取消后停止
+
 ### 节点参数
 
 以上函数的节点参数相同，`chainId` 和 `provider` 至少传一个：
@@ -83,7 +103,8 @@ await getBalances(user, tokens, { chainId: 56, blockTag: 'pending' })
 - **chainId 自动识别**：EVM 节点 / 钱包用 `eth_chainId`，ethers Provider 用 `getNetwork()`，Tron 读创世区块哈希的最后 4 字节（与 TronGrid 的 `eth_chainId` 一致）；只传 URL 时先按 EVM 识别，失败再按 Tron 识别，所以 Tron 节点 URL 也不用传 chainId
 - **识别结果缓存**：同时发起的识别共用一个请求，失败或超时不缓存（下次重试）。URL 按地址缓存；tronWeb 按当前连接的节点地址缓存（TronLink 切网络后自动重新识别）；EIP-1193 钱包按对象缓存并监听 `chainChanged`，切链时失效，不支持事件监听的钱包不缓存。`clearChainIdCache()` 可手动清空
 - **链校验**：传入的节点会确认它实际所在的链与 chainId 一致，不一致时报 `NETWORK_ERROR`，多节点时自动换下一个节点。所以 `[钱包, 公共节点]` 这类组合、配错了节点 URL、或用户自己创建的 `BrowserProvider` 在别的链上，都不会把另一条链的数据当成这条链的返回。校验通过已配置好的节点连接进行（带 Tron apiKey 等），与实际请求并行发出、不增加延迟，结果缓存，每个节点只多一次请求；内置公共节点不校验
-- **Provider 复用**：同一个 chainId + 配置 + 节点多次调用会复用同一个 Provider（共享连接和合并队列，最多缓存 32 组，超出淘汰最早的）；只传钱包时每次按钱包当前的链创建，切链后自动按新链查询。`chainId` 为 `null` / `''` 时视为未传
+- **Provider 复用**：同一个 chainId + 配置 + 节点多次调用会复用同一个 Provider（共享连接和合并队列，最多缓存 32 组，超出淘汰最早的）；`[window.ethereum, ...urls]` 这类钱包 + URL 混合列表按“钱包对象 + URL”复用。只传钱包（没传 chainId）时每次按钱包当前的链创建，切链后自动按新链查询。`chainId` 为 `null` / `''` 时视为未传
+- **直接传 Provider 实例**：`{ provider: multi }` 时直接用这个实例（chainId 和配置以实例为准，同时再传会报错），与其他直接调用 `multi` 的代码共享合并队列
 - 其余 Provider 配置（`fallback`、`nativeSymbol` 等，见[配置](#配置)）也可以直接放进这个参数
 
 ### 合约调用
@@ -129,12 +150,12 @@ const amountOut = await router.swap.staticCall(params, { value, from: user })
 
 ## 资产列表
 
-> **不推荐使用**（已标记 `@deprecated`）：`getOwnerTokens` / `provider.ownerTokens` 只能尽力而为，结果不保证完整、准确，局限性见下文。已知要查哪些代币时请用 `getBalances`；传 `alchemy` / `nodereal` 来源能查全，但同样受第三方服务的额度和可用性约束，需要可靠的完整持仓请直接接入索引服务的接口或自己的索引。
+> **不推荐使用**（已标记 `@deprecated`）：`getOwnerTokens` / `ownerTokens` 只能尽力而为，结果不保证完整、准确，局限性见下文。已知要查哪些代币时请用 `getBalances`；传 `alchemy` / `nodereal` 来源能查全，但同样受第三方服务的额度和可用性约束，需要可靠的完整持仓请直接接入索引服务的接口或自己的索引。
 
 EVM 链上**没有办法只靠节点列出一个地址持有的全部代币**（链上没有“某地址持有哪些代币”的索引）。`getOwnerTokens` 的做法是：先从“代币来源”拿到候选代币，再用 multicall 在链上核对这些代币的余额，返回有余额的部分。
 
 ```ts
-import { alchemy, getOwnerTokens, nodereal, tokenList } from '@w3lib/evm-batch-call'
+import { alchemy, getOwnerTokens, nodereal, tokenList } from '@w3lib/evm-batch-call/owner'
 
 await getOwnerTokens(user, { chainId: 56 })                                   // 默认：免费公开代币列表
 await getOwnerTokens(user, { chainId: 1, prices: true, minUsd: 1 })           // 带美元价值，按价值排序，过滤 < $1 的代币
@@ -168,7 +189,7 @@ await getOwnerTokens(user, { chainId: 56, source: alchemy({ apiKey: KEY }) }) //
 代币列表发现不了的新代币（刚发行、未被收录），可以用 `scanTransfers` 开关补充：开启后，从**第一次调用开始**，每次调用都往后扫描新区块里转给该地址的 ERC20 `Transfer` 事件，把发现的代币合并进来（结果的 `source` 为 `'transfers'`）。默认关闭。
 
 ```ts
-import { getOwnerTokens, keyValueScanStorage } from '@w3lib/evm-batch-call'
+import { getOwnerTokens, keyValueScanStorage } from '@w3lib/evm-batch-call/owner'
 
 await getOwnerTokens(user, { chainId: 1, scanTransfers: true })                    // 进度存在内存里
 await getOwnerTokens(user, { chainId: 1, scanTransfers: { storage: keyValueScanStorage(localStorage) } }) // 刷新页面后接着扫
@@ -218,13 +239,13 @@ await getOwnerTokens(user, { chainId: 1, scanTransfers: { lookbackBlocks: 20_000
 
 ## 功能
 
-- **常用查询**：余额、代币详情、授权额度、NFT（集合 / 持有 / 元数据地址 / ERC1155 余额），一个函数一次请求
-- **资产列表**（不推荐使用，尽力而为）：`getOwnerTokens`，免费公开代币列表或带 Key 的索引服务发现代币，multicall 核对余额，可选 DefiLlama 价格
+- **常用查询**：余额、代币详情、授权额度、NFT（集合 / 持有 / 元数据地址 / ERC1155 余额，子路径 `/nft`），一个函数一次请求
+- **资产列表**（不推荐使用，尽力而为，子路径 `/owner`）：`getOwnerTokens`，免费公开代币列表或带 Key 的索引服务发现代币，multicall 核对余额，可选 DefiLlama 价格
 - **批量读取**：`all` / `tryAll` / `tryEach`，N 条读调用合成一次 `eth_call`；支持数组或对象输入
-- **自动合并**：绑定合约直接 `await`，或 `provider.call(x)`，同一收集窗口内的调用合并成一次请求并去重
+- **自动合并**：绑定合约直接 `await`、`provider.call(x)`，以及 `balances` / `tokens` / `allowances`，同一收集窗口内的调用合并成一次请求并去重
 - **预执行**：`staticCall` / `staticCallAll` / `method.staticCall`，带 `from` / `value` 模拟交易，返回解析好的 revert 原因
 - **主币余额合并**：`getEthBalance` 与合约调用在同一次 `eth_call` 里——无论链上有没有 Multicall3
-- **任意链可用**：内置 Multicall3 地址表；表里没有、地址无效、或查询早于部署区块时，自动改用 deployless（链上无需部署任何合约）
+- **任意链可用**：内置 Multicall3 地址表；表里没有、地址无效、或查询早于部署区块时，自动改用 deployless（链上无需部署任何合约）。少数链不支持 deployless（合约创建式 `eth_call`，如 Oasis Emerald、Aurora），这些链已在地址表里，只能查合约部署之后的状态；`pnpm check:rpc` 会检查内置节点表里每条链至少有一种批量方式可用
 - **备用节点**：传多个节点自动故障切换；不传节点使用内置公共节点表（34 条 EVM 链 + Tron）
 - **chainId 可选**：传了节点就能自动识别 chainId，结果缓存，钱包切链自动失效
 - **Tron**：走 Tron HTTP API，T 开头地址可以直接用
@@ -245,10 +266,40 @@ new Provider(56, DEFAULT_RPC_URLS[56], { fallback: { timeout: 8000, cooldown: 60
 
 多节点时按顺序使用：出错或超时（默认 10s）换下一个节点，出错的节点在 `cooldown`（默认 30s）内排到最后。与 ethers 的 `FallbackProvider` 相比，没有首次请求前对所有节点的同步，一个卡住的节点不会拖住第一次查询；合约 revert 等确定性结果不会拿去别的节点重试。
 
+**超时与出错分开计**：出错（连不上、5xx、限频等）的节点进入冷却；超时只换下一个节点、不冷却，同一节点连续 3 次超时才冷却——冷启动的大批量查询偶尔慢，不会把健康的节点踢到后面。冷却状态按节点（URL / 对象）全局共享，Provider 重建后刚失败过的节点仍排在后面。
+
+**所有节点都失败**时抛 `AllNodesFailedError`，`err.errors` 是每个节点的标识和失败原因（`[{ node, error }]`，按尝试顺序），message 里也逐个列出；节点标识只取 URL 的 host，不含 path / query 里的 API Key。单节点时抛原始错误。
+
+**可观测性**：`onRequest(listener)` 订阅所有节点请求（全局，返回取消订阅的函数），每次对节点的请求一条事件：
+
+```ts
+import { onRequest } from '@w3lib/evm-batch-call'
+
+const off = onRequest(({ node, method, ms, ok, error, attempt }) => {
+  // node：节点 host（钱包为 'wallet'）；method：call / getBalance / getLogs …；attempt > 0 表示换过节点
+  console.log(`${node} ${method} ${ms}ms ${ok ? 'ok' : 'failed'}${attempt ? ` (第 ${attempt + 1} 个节点)` : ''}`)
+})
+```
+
+**慢节点**：`fallback.stallTimeout`（毫秒，默认 0 关闭）设置后，当前节点超过这个时间还没返回就同时请求下一个节点，原请求不取消，谁先成功用谁（与 `FallbackProvider` 的 stallTimeout 语义相同）；`timeout` 才是真正放弃。节点正常但偶尔较慢时，用 `{ stallTimeout: 2000, timeout: 10_000 }` 比把 `timeout` 设短更好：大批量查询本来就要几秒，`timeout` 太短会把正常的慢请求判成超时、反复重试。只影响 `eth_call` / `eth_getBalance`。
+
 ethers 会把 `eth_call` 的**任何** JSON-RPC 错误（限流、`header not found` 等）都包装成 `CALL_EXCEPTION`，库内用 `isExecutionError(err)` 区分“合约执行结果”和“节点问题”，只有后者会触发切换。
 
 内置节点表 `DEFAULT_RPC_URLS`（按 chainId）/ `DEFAULT_TRON_HOSTS` 中的节点都能在浏览器里直连：放行跨域、支持 batch 请求、chainId 正确、不需要 API Key。公共节点随时可能下线或限流，生产环境建议传入自己的节点，内置表作为备用。
 
+## 缓存持久化
+
+decimals 永远不会变，但页面刷新后缓存就没了，冷启动的大批量查询要顺带查精度，耗时能差好几倍。可以把缓存持久化：
+
+```ts
+import { exportTokenMetaCache, importTokenMetaCache, persistTokenMetaCache } from '@w3lib/evm-batch-call'
+
+persistTokenMetaCache(localStorage)          // 调用时读入，之后有更新就防抖（1 秒）写回，默认最多 5000 条；返回停止函数
+// 或自己存：IndexedDB、服务端……
+await save(JSON.stringify(exportTokenMetaCache()))
+importTokenMetaCache(JSON.parse(await load())) // 格式不对的数据忽略；name / symbol 仍按写入时间 1 小时过期
+```
+
 ## 批量读取
 
 ```ts
@@ -264,6 +315,7 @@ await multi.all(calls, { blockTag: 40_000_000 })                            //
 ```
 
 - 单返回值的函数直接返回该值；多返回值返回 ethers `Result`（可按下标或名字取）；整数统一是 `bigint`
+- 结果类型按输入推断（元组保留各项类型）；ethcall 风格的 `all<T>(calls)` 返回 `T[]`，`all<any>(calls)` 返回 `any[]`
 - `tryAll` 中出现非法地址（如后端给的脏数据）只让该条为 `null`，不会拖垮整批
 - `Contract` 暴露 ABI 里的**所有**函数（不只 view/pure），重载函数用完整签名访问：`c['getAmount(uint256,address)'](...)`
 
@@ -282,6 +334,7 @@ const b = multi.erc20(tokenB).balanceOf(user)
 - `wait`：收集窗口，默认 `0`（同一事件循环 tick）；`maxSize`：达到即发出，默认 500
 - 单条失败只 reject 自己（`CallFailedError`，`err.reason` 是 revert 原因）
 - blockTag / from 不同的调用分开发
+- `balances` / `tokens` / `allowances` 的子调用也进同一个队列：不同组件同时查余额时合成一次 `eth_call`，相同的 `balanceOf` / `decimals` 只请求一次；一次调用的子调用不会被 `maxSize` 拆开
 - 合并发生在**同一个 Provider 实例**内，应按链缓存 Provider，不要每次 `new`
 - 绑定合约的 Call 只在第一次 `await` 时才发请求，传给 `all` / `tryAll` 不会额外发请求
 - 末位参数可以带 overrides：`await pair.getReserves({ blockTag: 18_000_000 })`。传给 `all` / `tryAll` 时以批次的 overrides 为准（一批只能在同一个区块、同一个 from 下执行）
@@ -309,11 +362,20 @@ for (const r of results) {
 
 ## 主币余额与 deployless
 
-`getEthBalance` 在两种模式下都和合约调用在同一次 `eth_call` 里：
+`getEthBalance`（以及 `balances` 里的主币）默认在两种模式下都和合约调用在同一次 `eth_call` 里：
 
 - 有 Multicall3：调合约自带的 `getEthBalance`
 - deployless：使用本库的 [DeploylessMulticall3](contracts/DeploylessMulticall3.sol)，构造函数里直接用 `BALANCE` 读取
 
+**有的链在合约里读不到正确的主币余额**：比如 Anubis（6714）的主币其实是一个 ERC20，`getEthBalance` 和 `BALANCE` 对任何地址都返回 0、不报错，只有 `eth_getBalance` 正确。这时 `balances()` 会返回 `success: true, balance: '0'`，调用方察觉不到。用 `nativeBalance` 配置读取方式：
+
+```ts
+new Provider(6714, url, { nativeBalance: 'rpc' })              // 主币单独走 eth_getBalance（与 eth_call 同时发出）
+new Provider(chainId, url, { nativeBalance: { erc20: '0x…' } }) // 主币改调这个 ERC20 的 balanceOf，仍在同一次 eth_call 里
+```
+
+内置表 `NATIVE_BALANCE_MODES` 收录了已知的这类链（目前是 Anubis），默认按表处理。`pnpm check:rpc` 会对每条链比对“合约里读到的主币余额”和 `eth_getBalance`，新链有这个问题时会报出来。
+
 deployless 还修正了 ethcall 自带字节码的两个上限问题（在 BSC 上实测，约 150 条 `balanceOf` 起就会失败）：
 
 | 限制 | 现象 | 处理 |
@@ -367,12 +429,13 @@ new Provider(chainId, nodes?, { // 或 new Provider(nodes, { … })
   deployless: false,                       // true：强制走 deployless
   chunkSize: 500,                          // 合约模式单次 eth_call 最多打包的调用数
   batch: { wait: 0, maxSize: 500 },        // 自动合并参数
-  fallback: { timeout: 10_000, cooldown: 30_000 }, // 节点超时 / 出错节点冷却时间
+  fallback: { timeout: 10_000, cooldown: 30_000, stallTimeout: 0 }, // 节点超时 / 出错节点冷却时间（超时连续 3 次才冷却）/ 慢节点提前请求下一个
   tron: { apiKey, minInterval: 200 },      // 用 URL 创建 TronProvider 时的参数
   nativeTokens: [NATIVE_TOKEN, ZeroAddress], // 视为主币的地址（默认值；ZeroAddress 来自 ethers）
   nativeDecimals: 18,                      // 主币精度 / symbol / 名称，默认按内置链信息表（NATIVE_CURRENCIES）
   nativeSymbol: 'BNB',
   nativeName: 'BNB',
+  nativeBalance: 'contract',               // 主币余额读取方式：'contract' | 'rpc' | { erc20 }，默认按内置表 NATIVE_BALANCE_MODES
 })
 ```
 

package/contracts/DeploylessMulticall3.sol

@@ -7,6 +7,7 @@ pragma solidity 0.8.30;
  * 与 ethcall 自带的 deployless 字节码相比：
  * - 对 `MULTICALL3.getEthBalance(addr)` 的调用在构造函数里直接用 BALANCE 读取，
  *   主币余额和合约调用在同一次 eth_call 里完成（链上没有 Multicall3 时也一样）
+ * - 对 `MULTICALL3.getBlockNumber()` 的调用直接返回 block.number（与 Multicall3 相同），用于确认读取时的区块
  * - 结果超过 EIP-170 的 24KB 时，合约创建会因 "max code size exceeded" 失败，
  *   此时改为通过 revert Aggregate3Result(...) 带回（revert 数据没有大小限制）
  *
@@ -28,6 +29,8 @@ contract DeploylessMulticall3 {
     address private constant MULTICALL3 = 0xcA11bde05977b3631167028862bE2a173976CA11;
     /// getEthBalance(address)
     bytes4 private constant GET_ETH_BALANCE = 0x4d2301cc;
+    /// getBlockNumber()
+    bytes4 private constant GET_BLOCK_NUMBER = 0x42cbb15c;
     /// EIP-170
     uint256 private constant MAX_CODE_SIZE = 24576;
 
@@ -46,6 +49,8 @@ contract DeploylessMulticall3 {
                     account := and(mload(add(data, 36)), 0xffffffffffffffffffffffffffffffffffffffff)
                 }
                 results[i] = Result(true, abi.encode(account.balance));
+            } else if (c.target == MULTICALL3 && data.length == 4 && bytes4(data) == GET_BLOCK_NUMBER) {
+                results[i] = Result(true, abi.encode(block.number));
             } else {
                 (bool success, bytes memory ret) = c.target.call(data);
                 if (!success && !c.allowFailure) {

package/dist/aggregate.d.ts

@@ -1,5 +1,5 @@
 import { Interface, type Provider as EthersProvider } from 'ethers';
-import type { CallRequest, RawResult } from './call.js';
+import { type CallRequest, type RawResult } from './call.js';
 import { type Multicall } from './multicall.js';
 /**
  * 只用到 ethers Provider 的这几个方法：必需 call / getBalance；getLogs / getBlockNumber 可选（只有增量扫描 Transfer 事件时用到）。
@@ -10,7 +10,24 @@ export type BlockTag = number | bigint | string;
 export interface CallOverrides {
     blockTag?: BlockTag;
     from?: string;
+    /**
+     * 最低区块：节点落后于这个区块时（如交易刚确认、公共节点还没跟上）不用它的结果——
+     * 改为按这个区块重查（落后的节点会报错、自动换节点），所有节点都落后时稍等重试，最多约 10 秒。
+     * 只对最新状态的查询生效（指定了 blockTag 时忽略）
+     */
+    minBlock?: number;
+    /** 取消查询：已取消时不发请求；执行中取消时立即 reject（合并在一起的底层请求继续完成，结果丢弃） */
+    signal?: AbortSignal;
 }
+/**
+ * 主币余额的读取方式：
+ * - 'contract'：和其他调用放在同一次 eth_call 里（Multicall3.getEthBalance / deployless 合约里的 BALANCE）
+ * - 'rpc'：单独用 eth_getBalance（与 eth_call 同时发出）。用于合约里读主币余额不可靠的链（如 BALANCE 恒为 0）
+ * - { erc20 }：主币其实是一个 ERC20 合约，改调它的 balanceOf
+ */
+export type NativeBalanceMode = 'contract' | 'rpc' | {
+    erc20: string;
+};
 export declare const multicall3Interface: Interface;
 export interface AggregateContext {
     provider: EthersLikeProvider;
@@ -18,6 +35,8 @@ export interface AggregateContext {
     /** null 表示直接走 deployless */
     multicall: Multicall | null;
     chunkSize: number;
+    /** 主币余额的读取方式，默认 'contract' */
+    nativeBalance?: NativeBalanceMode;
 }
 /**
  * 执行一批请求，结果与 requests 一一对应。

package/dist/aggregate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../src/aggregate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,SAAS,EAAkC,KAAK,QAAQ,IAAI,cAAc,EAAE,MAAM,QAAQ,CAAA;AAE7G,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAGvD,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAEnE;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,gBAAgB,CAAC,CAAC,CAAA;AAE1I,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;AAE/C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,eAAO,MAAM,mBAAmB,WAG9B,CAAA;AAaF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,4BAA4B;IAC5B,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;IAC3B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,WAAW,EAAE,EACvB,SAAS,GAAE,aAAkB,GAC5B,OAAO,CAAC,SAAS,EAAE,CAAC,CActB;AA0LD,uBAAuB;AACvB,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../src/aggregate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,SAAS,EAAkC,KAAK,QAAQ,IAAI,cAAc,EAAE,MAAM,QAAQ,CAAA;AAE7G,OAAO,EAAiB,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAA;AAI3E,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAGnE;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,gBAAgB,CAAC,CAAC,CAAA;AAE1I,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;AAE/C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yDAAyD;IACzD,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,KAAK,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAItE,eAAO,MAAM,mBAAmB,WAI9B,CAAA;AA0EF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,4BAA4B;IAC5B,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,8BAA8B;IAC9B,aAAa,CAAC,EAAE,iBAAiB,CAAA;CAClC;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,WAAW,EAAE,EACvB,SAAS,GAAE,aAAkB,GAC5B,OAAO,CAAC,SAAS,EAAE,CAAC,CAmBtB;AA2TD,uBAAuB;AACvB,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C"}