@w3lib/evm-batch-call 0.2.0 → 0.4.0

package/dist/provider.d.ts

@@ -1,11 +1,10 @@
 import { type BigNumberish } from 'ethers';
-import { type BlockTag, type CallOverrides, type EthersLikeProvider } from './aggregate.js';
+import { type BlockTag, type CallOverrides, type EthersLikeProvider, type NativeBalanceMode } from './aggregate.js';
 import { type BatchOptions } from './batcher.js';
 import { type BoundCall, type Call } from './call.js';
 import { Contract, type ContractAbi, type ContractRunner } from './contract.js';
-import { type BalanceToken, type Erc20Contract, type TokenBalance, type TokenAllowance, type DefaultTokenField, type TokenDetails, type TokenField } from './erc20.js';
+import { type BalanceToken, type Erc20Contract, type RawTokenAllowance, type RawTokenBalance, type TokenBalance, type TokenAllowance, type DefaultTokenField, type TokenDetails, type TokenField } from './erc20.js';
 import { type Multicall } from './multicall.js';
-import { type DefaultNftCollectionField, type Erc1155Balance, type NftBalance, type NftCollection, type NftCollectionField, type NftCollectionsOptions, type NftItem, type NftOwner, type NftTokenUri, type NftTokenUriOptions } from './nft.js';
 import { type ProviderSource, type SourceOptions } from './source.js';
 export type { ProviderSource };
 export interface StaticCallOverrides extends CallOverrides {
@@ -26,11 +25,13 @@ export type StaticCallResult<T> = {
 /** all / tryAll 的输入：Call 数组，或 { 名字: Call } 对象 */
 export type CallInput = readonly Call[] | Readonly<Record<string, Call>>;
 type ResultOf<C> = C extends Call<infer R> ? R : any;
+/** C 是 any（如 `all<any>(calls)` 显式写了 any，会落到第一个重载上）时按 ethcall 的写法返回 any[] */
+type IsAny<T> = 0 extends 1 & T ? true : false;
 /** 与输入同构的结果：数组 → 数组（元组保留各项类型），对象 → 同名字段 */
-export type CallResults<C> = {
+export type CallResults<C> = IsAny<C> extends true ? any[] : {
     -readonly [K in keyof C]: ResultOf<C[K]>;
 };
-export type TryCallResults<C> = {
+export type TryCallResults<C> = IsAny<C> extends true ? any[] : {
     -readonly [K in keyof C]: ResultOf<C[K]> | null;
 };
 export interface ProviderConfig extends SourceOptions {
@@ -50,14 +51,43 @@ export interface ProviderConfig extends SourceOptions {
     nativeSymbol?: string;
     /** 主币名称（tokens 用），默认按内置链信息表，表里没有时为 null */
     nativeName?: string;
+    /**
+     * 主币余额的读取方式，默认按内置表 NATIVE_BALANCE_MODES，表里没有时为 'contract'：
+     * - 'contract'：和其他调用放在同一次 eth_call 里（Multicall3.getEthBalance / deployless 里的 BALANCE）
+     * - 'rpc'：单独用 eth_getBalance。有的链在合约里读主币余额恒为 0、不报错，需要用这个
+     * - `{ erc20: '0x…' }`：主币其实是一个 ERC20 合约，改调它的 balanceOf
+     */
+    nativeBalance?: NativeBalanceMode;
 }
-export interface TokensOptions<F extends TokenField = DefaultTokenField> extends CallOverrides {
+/** balances / allowances / tokens 共用：结果带读取时的区块号 */
+export interface BlockOptions {
+    /**
+     * 每项结果带 blockNumber（读取时的区块号，与数据在同一次 eth_call 里读出）。传了 minBlock 时自动带上。
+     * 大批量拆成多次 eth_call 时为其中包含区块号查询的那一次
+     */
+    withBlock?: boolean;
+}
+export interface TokensOptions<F extends TokenField = DefaultTokenField> extends CallOverrides, BlockOptions {
     /** 要返回的字段，默认 ['name', 'symbol', 'decimals'] */
     fields?: readonly F[];
 }
-export interface BalancesOptions extends CallOverrides {
+export interface BalancesOptions extends CallOverrides, BlockOptions {
     /** 同时返回 symbol（代币查一次后缓存；主币取 nativeSymbol / 内置链信息表）。默认 false */
     symbol?: boolean;
+    /**
+     * 是否查 decimals 并返回 decimals / formatted。默认 true。
+     * false：只查余额（没有 decimals 的合约如 ERC721 也能拿到余额，冷启动时子调用数减半），结果里不带 decimals / formatted
+     */
+    decimals?: boolean;
+}
+/** multiBalances / getMultiBalances 的单项查询 */
+export interface BalancesQuery {
+    owner: string;
+    tokens: readonly BalanceToken[];
+}
+export interface AllowancesOptions extends CallOverrides, BlockOptions {
+    /** 是否查 decimals 并返回 decimals / formatted。默认 true；false 时只查额度，结果里不带 decimals / formatted */
+    decimals?: boolean;
 }
 /**
  * Multicall Provider，API 与 ethcall 的 Provider 保持一致：
@@ -126,7 +156,21 @@ export declare class Provider implements ContractRunner {
      * - decimals、symbol 查到一次后缓存，之后只查 balanceOf；也可以直接传 `{ address, decimals }`
      * - 单个代币失败（非合约地址、非法地址等）不影响其他代币，该项 success 为 false
      */
+    balances(owner: string, tokens: readonly BalanceToken[], options: BalancesOptions & {
+        decimals: false;
+    }): Promise<RawTokenBalance[]>;
     balances(owner: string, tokens: readonly BalanceToken[], options?: BalancesOptions): Promise<TokenBalance[]>;
+    /**
+     * 多个钱包一次查：同一条链上所有钱包的余额合成一次 multicall（与 balances 选项相同），结果与 queries 一一对应。
+     *
+     * ```ts
+     * const [a, b] = await multi.multiBalances([{ owner: walletA, tokens: [NATIVE_TOKEN, USDT] }, { owner: walletB, tokens: [USDT] }])
+     * ```
+     */
+    multiBalances(queries: readonly BalancesQuery[], options: BalancesOptions & {
+        decimals: false;
+    }): Promise<RawTokenBalance[][]>;
+    multiBalances(queries: readonly BalancesQuery[], options?: BalancesOptions): Promise<TokenBalance[][]>;
     /**
      * 批量查 ERC20 授权额度（发交易前判断是否需要 approve），一次请求。
      *
@@ -138,17 +182,10 @@ export declare class Provider implements ContractRunner {
      * - 主币不需要授权：native 为 true，额度视为 MaxUint256、unlimited 为 true，不发请求
      * - decimals 与 balances / tokens 共用缓存；也可以直接传 `{ address, decimals }`
      */
-    allowances(owner: string, spender: string, tokens: readonly BalanceToken[], overrides?: CallOverrides): Promise<TokenAllowance[]>;
-    /** 批量查 NFT 集合信息（标准 / name / symbol / totalSupply），字段可选 */
-    nftCollections<const F extends NftCollectionField = DefaultNftCollectionField>(collections: readonly string[], options?: NftCollectionsOptions<F>): Promise<NftCollection<F>[]>;
-    /** 批量查 ERC721 持有数量（balanceOf） */
-    nftBalances(owner: string, collections: readonly string[], overrides?: CallOverrides): Promise<NftBalance[]>;
-    /** 批量查 ERC721 持有人（ownerOf），可混合多个集合 */
-    nftOwners(items: readonly NftItem[], overrides?: CallOverrides): Promise<NftOwner[]>;
-    /** 批量查 NFT 元数据地址：兼容 ERC721 tokenURI 与 ERC1155 uri（{id} 按规范替换），可转换 ipfs:// */
-    nftTokenUris(items: readonly NftItem[], options?: NftTokenUriOptions): Promise<NftTokenUri[]>;
-    /** 批量查 ERC1155 余额 */
-    erc1155Balances(owner: string, items: readonly NftItem[], overrides?: CallOverrides): Promise<Erc1155Balance[]>;
+    allowances(owner: string, spender: string, tokens: readonly BalanceToken[], options: AllowancesOptions & {
+        decimals: false;
+    }): Promise<RawTokenAllowance[]>;
+    allowances(owner: string, spender: string, tokens: readonly BalanceToken[], options?: AllowancesOptions): Promise<TokenAllowance[]>;
     /**
      * 批量查 ERC20 代币详情，一次请求；可以选择返回哪些字段。
      *
@@ -208,6 +245,14 @@ export declare class Provider implements ContractRunner {
      * @param overrides 所有条目共享的 overrides，优先级最低
      */
     staticCallAll<T = any>(items: ReadonlyArray<Call | StaticCallItem>, overrides?: StaticCallOverrides): Promise<StaticCallResult<T>[]>;
+    /** 当前区块号（底层节点需支持 getBlockNumber） */
+    getBlockNumber(): Promise<number>;
+    /** eth_getLogs（底层节点需支持 getLogs）。多节点时依次尝试，全部失败抛 GetLogsError */
+    getLogs(filter: Parameters<NonNullable<EthersLikeProvider['getLogs']>>[0]): Promise<Awaited<ReturnType<NonNullable<EthersLikeProvider['getLogs']>>>>;
+    /** 是否是按主币处理的地址（config.nativeTokens，默认 0xeeee…eeee 和零地址） */
+    isNativeToken(address: string): boolean;
+    /** 按主币处理的地址（小写），顺序同 config.nativeTokens */
+    get nativeTokens(): readonly string[];
     /** 底层连接（多节点时是 FallbackRpc）。只传节点构造时，需在 ready() 之后读取 */
     get rpc(): EthersLikeProvider;
     /** 当前使用的 multicall 合约（null 表示 deployless；只传节点构造时在 ready() 之前也为 null） */

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}

package/dist/provider.js

@@ -1,15 +1,15 @@
 import {} from 'ethers';
 import { aggregate } from './aggregate.js';
 import { Batcher } from './batcher.js';
-import { asStringOrBytes32, decodeCall, encodeCall } from './call.js';
+import { asStringOrBytes32, decodeCall, encodeCall, settleResult, } from './call.js';
 import { Contract, bindCall } from './contract.js';
-import { DEFAULT_NATIVE_TOKENS, ERC20_ABI, formatAmount, getCachedTokenMeta, setCachedTokenMeta, MAX_UINT256, UNLIMITED_ALLOWANCE_THRESHOLD, DEFAULT_TOKEN_FIELDS, } from './erc20.js';
+import { DEFAULT_NATIVE_TOKENS, ERC20_ABI, formatUnits, getCachedTokenMeta, setCachedTokenMeta, MAX_UINT256, UNLIMITED_ALLOWANCE_THRESHOLD, DEFAULT_TOKEN_FIELDS, } from './erc20.js';
 import { CallFailedError, isExecutionError } from './errors.js';
 import { MULTICALL3_ADDRESS, getMulticall3 } from './multicall.js';
-import { getNativeCurrency } from './chains.js';
-import { erc1155Balances, nftBalances, nftCollections, nftOwners, nftTokenUris, } from './nft.js';
+import { getNativeBalanceMode, getNativeCurrency } from './chains.js';
 import { detectChainId } from './detect.js';
 import { isTronChain, resolveSource } from './source.js';
+import { withSignal } from './util.js';
 /** 构造参数第一个是 chainId 还是节点：数字、数字字符串、0x 十六进制视为 chainId，其余（URL、对象、数组）视为节点 */
 function isChainIdArg(value) {
     return (typeof value === 'number' ||
@@ -18,6 +18,7 @@ function isChainIdArg(value) {
 }
 const ETH_BALANCE_INPUTS = [{ name: 'addr', type: 'address' }];
 const ETH_BALANCE_OUTPUTS = [{ name: 'balance', type: 'uint256' }];
+const BLOCK_NUMBER_OUTPUTS = [{ name: 'blockNumber', type: 'uint256' }];
 /**
  * Multicall Provider，API 与 ethcall 的 Provider 保持一致：
  *
@@ -92,6 +93,7 @@ export class Provider {
             chainId,
             multicall: config.deployless ? null : resolveMulticall(chainId, config.multicall),
             chunkSize: config.chunkSize ?? 500,
+            nativeBalance: config.nativeBalance ?? getNativeBalanceMode(chainId),
         };
     }
     /** 链 ID（不传 chainId 构造时，会等待从节点识别完成） */
@@ -127,20 +129,11 @@ export class Provider {
     erc20(address) {
         return new Contract(address, ERC20_ABI, this);
     }
-    /**
-     * 批量查余额（含按 decimals 换算后的数值），主币和代币混在一起、一次请求。
-     *
-     * ```ts
-     * const list = await multi.balances(user, [NATIVE_TOKEN, USDT, { address: USDC, decimals: 6 }], { symbol: true })
-     * list[1] // { token: USDT, native: false, balance: '1234500000000000000000', decimals: 18, formatted: '1234.5', symbol: 'USDT', success: true }
-     * ```
-     *
-     * - 主币地址见 config.nativeTokens（默认 0xeeee…eeee 和零地址）；精度 / symbol 按内置链信息表，可用 nativeDecimals / nativeSymbol 覆盖
-     * - decimals、symbol 查到一次后缓存，之后只查 balanceOf；也可以直接传 `{ address, decimals }`
-     * - 单个代币失败（非合约地址、非法地址等）不影响其他代币，该项 success 为 false
-     */
-    async balances(owner, tokens, options = {}) {
-        const { symbol: withSymbol = false, ...overrides } = options;
+    balances(owner, tokens, options = {}) {
+        return withSignal(options.signal, () => this.#balances(owner, tokens, options));
+    }
+    async #balances(owner, tokens, options) {
+        const { symbol: withSymbol = false, decimals: withDecimals = true, ...overrides } = options;
         const { chainId } = await this.#ensureReady();
         const nativeCurrency = this.#nativeCurrency(chainId);
         const items = tokens.map((token) => {
@@ -151,102 +144,122 @@ export class Provider {
         const calls = [];
         const plan = items.map(({ address, native, decimals, symbol }) => {
             const balanceIndex = calls.push(native ? this.getEthBalance(owner) : this.erc20(address).balanceOf(owner)) - 1;
-            const decimalsIndex = decimals === undefined ? calls.push(this.erc20(address).decimals()) - 1 : -1;
+            const decimalsIndex = withDecimals && decimals === undefined ? calls.push(this.erc20(address).decimals()) - 1 : -1;
             const symbolIndex = withSymbol && !native && symbol === undefined ? calls.push(this.#symbolCall(address)) - 1 : -1;
             return { balanceIndex, decimalsIndex, symbolIndex };
         });
-        const results = await this.tryAll(calls, overrides);
+        const blockIndex = this.#pushBlockNumber(calls, options);
+        const results = await this.#settleAll(calls, overrides);
+        const block = blockField(results, blockIndex);
         return items.map((item, i) => {
             const { balanceIndex, decimalsIndex, symbolIndex } = plan[i];
             const balance = results[balanceIndex];
-            const fetchedDecimals = decimalsIndex === -1 ? null : results[decimalsIndex];
-            const fetchedSymbol = symbolIndex === -1 ? null : results[symbolIndex];
+            const fetchedDecimals = valueOf(results[decimalsIndex]);
+            const fetchedSymbol = valueOf(results[symbolIndex]);
             if (!item.native && (fetchedDecimals !== null || fetchedSymbol !== null)) {
                 setCachedTokenMeta(chainId, item.address, {
                     ...(fetchedDecimals !== null ? { decimals: Number(fetchedDecimals) } : {}),
                     ...(fetchedSymbol !== null ? { symbol: fetchedSymbol } : {}),
                 });
             }
+            const extra = { ...(withSymbol ? { symbol: item.symbol ?? fetchedSymbol ?? null } : {}), ...block };
+            if (!withDecimals) {
+                return balance.ok
+                    ? { token: item.address, native: item.native, balance: balance.value.toString(), ...extra, success: true }
+                    : { token: item.address, native: item.native, balance: '0', ...extra, success: false, error: balance.reason, errorField: 'balance' };
+            }
             const decimals = item.decimals ?? (fetchedDecimals === null ? null : Number(fetchedDecimals));
-            const extra = withSymbol ? { symbol: item.symbol ?? fetchedSymbol ?? null } : {};
-            if (balance === null || decimals === null) {
-                return { token: item.address, native: item.native, balance: '0', decimals: decimals ?? 0, formatted: '0', ...extra, success: false };
+            if (!balance.ok || decimals === null) {
+                const failure = !balance.ok
+                    ? { error: balance.reason, errorField: 'balance' }
+                    : { error: reasonOf(results[decimalsIndex]), errorField: 'decimals' };
+                return { token: item.address, native: item.native, balance: '0', decimals: decimals ?? 0, formatted: '0', ...extra, success: false, ...failure };
             }
             // 结果全是字符串 / 数字 / 布尔 / null，可以直接 JSON.stringify
             return {
                 token: item.address,
                 native: item.native,
-                balance: balance.toString(),
+                balance: balance.value.toString(),
                 decimals,
-                formatted: formatAmount(balance, decimals),
+                formatted: formatUnits(balance.value, decimals),
                 ...extra,
                 success: true,
             };
         });
     }
-    /**
-     * 批量查 ERC20 授权额度（发交易前判断是否需要 approve），一次请求。
-     *
-     * ```ts
-     * const [usdt] = await multi.allowances(user, router, [USDT])
-     * usdt // { token: USDT, spender: router, native: false, allowance: '…', decimals: 18, formatted: '100', unlimited: false, success: true }
-     * ```
-     *
-     * - 主币不需要授权：native 为 true，额度视为 MaxUint256、unlimited 为 true，不发请求
-     * - decimals 与 balances / tokens 共用缓存；也可以直接传 `{ address, decimals }`
-     */
-    async allowances(owner, spender, tokens, overrides) {
+    multiBalances(queries, options = {}) {
+        // 各钱包的子调用在同一 tick 进入合并队列，合成一次 eth_call（相同的 decimals / 区块号查询只发一次）
+        return withSignal(options.signal, () => Promise.all(queries.map((query) => this.#balances(query.owner, query.tokens, options))));
+    }
+    allowances(owner, spender, tokens, options = {}) {
+        return withSignal(options.signal, () => this.#allowances(owner, spender, tokens, options));
+    }
+    async #allowances(owner, spender, tokens, options) {
+        const { decimals: withDecimals = true, ...overrides } = options;
         const { chainId } = await this.#ensureReady();
         const nativeDecimals = this.#nativeCurrency(chainId).decimals;
         const calls = [];
         const plan = tokens.map((token) => {
             const { address, native, decimals } = this.#resolveToken(chainId, token, nativeDecimals);
             const allowanceIndex = native ? -1 : calls.push(this.erc20(address).allowance(owner, spender)) - 1;
-            const decimalsIndex = native || decimals !== undefined ? -1 : calls.push(this.erc20(address).decimals()) - 1;
+            const decimalsIndex = native || !withDecimals || decimals !== undefined ? -1 : calls.push(this.erc20(address).decimals()) - 1;
             return { address, native, decimals, allowanceIndex, decimalsIndex };
         });
-        const results = calls.length ? await this.tryAll(calls, overrides) : [];
+        const blockIndex = this.#pushBlockNumber(calls, options);
+        const results = await this.#settleAll(calls, overrides);
+        const block = blockField(results, blockIndex);
         return plan.map(({ address, native, decimals: known, allowanceIndex, decimalsIndex }) => {
-            const allowance = native ? MAX_UINT256 : (results[allowanceIndex] ?? null);
-            const fetched = decimalsIndex === -1 ? null : (results[decimalsIndex] ?? null);
+            const settled = native ? { ok: true, value: MAX_UINT256 } : results[allowanceIndex];
+            const fetched = valueOf(results[decimalsIndex]);
             if (fetched !== null) {
                 setCachedTokenMeta(chainId, address, { decimals: Number(fetched) });
             }
+            if (!withDecimals) {
+                return settled.ok
+                    ? { token: address, spender, native, allowance: settled.value.toString(), unlimited: settled.value >= UNLIMITED_ALLOWANCE_THRESHOLD, ...block, success: true }
+                    : { token: address, spender, native, allowance: '0', unlimited: false, ...block, success: false, error: settled.reason, errorField: 'allowance' };
+            }
             const decimals = known ?? (fetched === null ? null : Number(fetched));
-            if (allowance === null || decimals === null) {
-                return { token: address, spender, native, allowance: '0', decimals: decimals ?? 0, formatted: '0', unlimited: false, success: false };
+            if (!settled.ok || decimals === null) {
+                const failure = !settled.ok
+                    ? { error: settled.reason, errorField: 'allowance' }
+                    : { error: reasonOf(results[decimalsIndex]), errorField: 'decimals' };
+                return { token: address, spender, native, allowance: '0', decimals: decimals ?? 0, formatted: '0', unlimited: false, ...block, success: false, ...failure };
             }
             return {
                 token: address,
                 spender,
                 native,
-                allowance: allowance.toString(),
+                allowance: settled.value.toString(),
                 decimals,
-                formatted: formatAmount(allowance, decimals),
-                unlimited: allowance >= UNLIMITED_ALLOWANCE_THRESHOLD,
+                formatted: formatUnits(settled.value, decimals),
+                unlimited: settled.value >= UNLIMITED_ALLOWANCE_THRESHOLD,
+                ...block,
                 success: true,
             };
         });
     }
-    /** 批量查 NFT 集合信息（标准 / name / symbol / totalSupply），字段可选 */
-    nftCollections(collections, options) {
-        return nftCollections(this, collections, options);
-    }
-    /** 批量查 ERC721 持有数量（balanceOf） */
-    nftBalances(owner, collections, overrides) {
-        return nftBalances(this, owner, collections, overrides);
-    }
-    /** 批量查 ERC721 持有人（ownerOf），可混合多个集合 */
-    nftOwners(items, overrides) {
-        return nftOwners(this, items, overrides);
-    }
-    /** 批量查 NFT 元数据地址：兼容 ERC721 tokenURI 与 ERC1155 uri（{id} 按规范替换），可转换 ipfs:// */
-    nftTokenUris(items, options) {
-        return nftTokenUris(this, items, options);
+    /**
+     * balances / tokens / allowances 的子调用进自动合并队列：与同一时刻其他组件发起的查询合并成一次 multicall。
+     * 逐条返回值或失败原因；节点错误照常抛出
+     */
+    #settleAll(calls, overrides = {}) {
+        return this.#batcher.loadSettled(calls, { blockTag: overrides.blockTag, from: overrides.from, minBlock: overrides.minBlock, signal: overrides.signal });
     }
-    /** 批量查 ERC1155 余额 */
-    erc1155Balances(owner, items, overrides) {
-        return erc1155Balances(this, owner, items, overrides);
+    /** withBlock / minBlock 时在同一批里加一条区块号查询，返回它的下标（不需要时为 -1） */
+    #pushBlockNumber(calls, options) {
+        if (!options.withBlock && options.minBlock === undefined) {
+            return -1;
+        }
+        return (calls.push({
+            // 地址只用于展示：执行时换成实际的 multicall 地址，deployless 时由合约内部处理
+            contract: { address: MULTICALL3_ADDRESS },
+            name: 'getBlockNumber',
+            inputs: [],
+            outputs: BLOCK_NUMBER_OUTPUTS,
+            params: [],
+            kind: 'blockNumber',
+        }) - 1);
     }
     /** symbol() 调用：string 解码失败时按 bytes32 解析（MKR 等老代币） */
     #symbolCall(address) {
@@ -274,7 +287,10 @@ export class Provider {
      * - symbol / name 兼容返回 bytes32 的老代币（MKR 等）
      * - 读取失败的字段为 null；请求的字段都读到时 success 为 true
      */
-    async tokens(tokens, options = {}) {
+    tokens(tokens, options = {}) {
+        return withSignal(options.signal, () => this.#tokens(tokens, options));
+    }
+    async #tokens(tokens, options) {
         const { fields = DEFAULT_TOKEN_FIELDS, ...overrides } = options;
         const wanted = new Set(fields);
         const needDecimals = wanted.has('decimals') || wanted.has('totalSupply');
@@ -304,8 +320,10 @@ export class Provider {
             }
             return { address, native, meta, index };
         });
-        const results = calls.length ? await this.tryAll(calls, overrides) : [];
-        const read = (i) => (i === undefined ? null : (results[i] ?? null));
+        const blockIndex = this.#pushBlockNumber(calls, options);
+        const results = await this.#settleAll(calls, overrides);
+        const block = blockField(results, blockIndex);
+        const read = (i) => (i === undefined ? null : valueOf(results[i]));
         return plan.map(({ address, native, meta, index }) => {
             const name = meta.name ?? read(index.name);
             const symbol = meta.symbol ?? read(index.symbol);
@@ -326,18 +344,25 @@ export class Provider {
                 totalSupply: totalSupply === null ? null : totalSupply.toString(),
             };
             const out = { address, native };
-            let success = true;
+            let failedField = null;
             for (const field of fields) {
                 out[field] = values[field];
                 // 主币没有 totalSupply，不算失败
                 if (values[field] === null && !(native && field === 'totalSupply')) {
-                    success = false;
+                    failedField ??= field;
                 }
             }
             if (wanted.has('totalSupply')) {
-                out.totalSupplyFormatted = totalSupply === null || decimals === null ? null : formatAmount(totalSupply, decimals);
+                out.totalSupplyFormatted = totalSupply === null || decimals === null ? null : formatUnits(totalSupply, decimals);
+            }
+            Object.assign(out, block);
+            out.success = failedField === null;
+            if (failedField !== null) {
+                // 没发请求的字段（主币信息不在内置表、也没有配置）不是调用失败
+                const callIndex = index[failedField];
+                out.error = callIndex === undefined ? 'not-configured' : reasonOf(results[callIndex]);
+                out.errorField = failedField;
             }
-            out.success = success;
             return out;
         });
     }
@@ -357,10 +382,12 @@ export class Provider {
         };
         return bindCall(call, this);
     }
-    async all(calls, overrides) {
-        const [list, pack] = unpack(calls);
-        const results = await this.#aggregate(list.map((call) => encodeCall(call, false)), overrides);
-        return pack(list.map((call, i) => decodeCall(call, results[i].returnData)));
+    all(calls, overrides) {
+        return withSignal(overrides?.signal, async () => {
+            const [list, pack] = unpack(calls);
+            const results = await this.#aggregate(list.map((call) => encodeCall(call, false)), overrides);
+            return pack(list.map((call, i) => decodeCall(call, results[i].returnData)));
+        });
     }
     async tryAll(calls, overrides) {
         const [list, pack] = unpack(calls);
@@ -369,7 +396,10 @@ export class Provider {
     /**
      * 逐条指定是否允许失败：允许失败的位置返回 null，不允许失败的一旦失败整体抛错。
      */
-    async tryEach(calls, canFail, overrides) {
+    tryEach(calls, canFail, overrides) {
+        return withSignal(overrides?.signal, () => this.#tryEach(calls, canFail, overrides));
+    }
+    async #tryEach(calls, canFail, overrides) {
         // 允许失败的条目编码出错（如后端给的脏地址）只让该条为 null，不拖垮整批
         const requests = calls.map((call, i) => {
             const callCanFail = canFail[i];
@@ -398,7 +428,7 @@ export class Provider {
      */
     call(call, overrides) {
         const own = call.overrides;
-        return this.#batcher.load(call, merge({ blockTag: own?.blockTag, from: own?.from }, overrides));
+        return withSignal(overrides?.signal, () => this.#batcher.load(call, merge({ blockTag: own?.blockTag, from: own?.from }, { blockTag: overrides?.blockTag, from: overrides?.from, minBlock: overrides?.minBlock, signal: overrides?.signal })));
     }
     /**
      * 预执行（模拟交易）：直接对目标合约发 eth_call，可带 from / value / gasLimit，
@@ -409,12 +439,14 @@ export class Provider {
      *
      * overrides 优先级：参数 overrides > Call 上的 overrides（`contract.swap(params, { value })`）。
      */
-    async staticCall(call, overrides = {}) {
-        const result = await this.#staticCall(call, overrides);
-        if (!result.success) {
-            throw result.error;
-        }
-        return result.data;
+    staticCall(call, overrides = {}) {
+        return withSignal(overrides.signal, async () => {
+            const result = await this.#staticCall(call, overrides);
+            if (!result.success) {
+                throw result.error;
+            }
+            return result.data;
+        });
     }
     /**
      * 批量预执行：每条都是独立的 eth_call，同时发出（JsonRpcProvider 会合进一个 JSON-RPC batch 请求；
@@ -423,7 +455,10 @@ export class Provider {
      * @param items Call，或 `{ call, overrides }` 以便每条带不同的 value / from
      * @param overrides 所有条目共享的 overrides，优先级最低
      */
-    async staticCallAll(items, overrides = {}) {
+    staticCallAll(items, overrides = {}) {
+        return withSignal(overrides.signal, () => this.#staticCallAll(items, overrides));
+    }
+    #staticCallAll(items, overrides) {
         return Promise.all(items.map((item) => 'call' in item && 'contract' in item.call
             ? this.#staticCall(item.call, item.overrides, overrides)
             : this.#staticCall(item, undefined, overrides)));
@@ -433,7 +468,10 @@ export class Provider {
         const merged = merge(merge({ ...shared }, call.overrides), explicit);
         if (call.kind === 'ethBalance') {
             try {
-                const { provider } = await this.#ensureReady();
+                const { provider, nativeBalance } = await this.#ensureReady();
+                if (typeof nativeBalance === 'object') {
+                    return await this.#staticCall(this.erc20(nativeBalance.erc20).balanceOf(call.params[0]), explicit, shared);
+                }
                 return { success: true, data: (await provider.getBalance(call.params[0], merged.blockTag)) };
             }
             catch (err) {
@@ -468,6 +506,30 @@ export class Provider {
             return { success: false, error: new CallFailedError(call, returnData, err) };
         }
     }
+    /** 当前区块号（底层节点需支持 getBlockNumber） */
+    async getBlockNumber() {
+        const { provider } = await this.#ensureReady();
+        if (!provider.getBlockNumber) {
+            throw new Error('getBlockNumber is not supported by this provider');
+        }
+        return provider.getBlockNumber();
+    }
+    /** eth_getLogs（底层节点需支持 getLogs）。多节点时依次尝试，全部失败抛 GetLogsError */
+    async getLogs(filter) {
+        const { provider } = await this.#ensureReady();
+        if (!provider.getLogs) {
+            throw new Error('getLogs is not supported by this provider');
+        }
+        return provider.getLogs(filter);
+    }
+    /** 是否是按主币处理的地址（config.nativeTokens，默认 0xeeee…eeee 和零地址） */
+    isNativeToken(address) {
+        return this.#nativeTokens.has(address.toLowerCase());
+    }
+    /** 按主币处理的地址（小写），顺序同 config.nativeTokens */
+    get nativeTokens() {
+        return [...this.#nativeTokens];
+    }
     /** 底层连接（多节点时是 FallbackRpc）。只传节点构造时，需在 ready() 之后读取 */
     get rpc() {
         if (!this.#ctx) {
@@ -509,19 +571,23 @@ function unpack(calls) {
     return [keys.map((key) => record[key]), (results) => Object.fromEntries(keys.map((key, i) => [key, results[i]]))];
 }
 function decodeTry(calls, results) {
-    return calls.map((call, i) => {
-        const result = results[i];
-        if (!result.success) {
-            return null;
-        }
-        try {
-            return decodeCall(call, result.returnData);
-        }
-        catch {
-            // 解码失败：多半是目标地址没有合约
-            return null;
-        }
-    });
+    return calls.map((call, i) => valueOf(settleResult(call, results[i])));
+}
+/** withBlock 时每项结果附带的 { blockNumber }（区块号查询失败时为 null）；不需要时为空对象 */
+function blockField(results, index) {
+    if (index === -1) {
+        return {};
+    }
+    const value = valueOf(results[index]);
+    return { blockNumber: value === null ? null : Number(value) };
+}
+/** 成功的值；失败或没有这一项（下标为 -1）时为 null */
+function valueOf(settled) {
+    return settled?.ok ? settled.value : null;
+}
+/** 失败原因；没有对应的调用时（不应发生）按 decode-failed */
+function reasonOf(settled) {
+    return settled && !settled.ok ? settled.reason : 'decode-failed';
 }
 export default Provider;
 //# sourceMappingURL=provider.js.map