@w3lib/evm-batch-call 0.1.0 → 0.2.0

package/dist/provider.d.ts

@@ -3,8 +3,9 @@ import { type BlockTag, type CallOverrides, type EthersLikeProvider } from './ag
 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 Erc20Contract, type TokenInfo } from './erc20.js';
+import { type BalanceToken, type Erc20Contract, 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 {
@@ -41,8 +42,22 @@ export interface ProviderConfig extends SourceOptions {
     chunkSize?: number;
     /** `provider.call()` 自动合并的参数 */
     batch?: BatchOptions;
-    /** `balances()` 里视为主币的地址，默认 0xeeee…eeee 和零地址 */
+    /** `balances()` 里视为主币的地址，默认 0xeeee…eeee（NATIVE_TOKEN）和零地址 */
     nativeTokens?: readonly string[];
+    /** 主币精度，默认按内置链信息表（NATIVE_CURRENCIES），表里没有时 EVM 18、Tron 6 */
+    nativeDecimals?: number;
+    /** 主币 symbol（balances 的 symbol 选项、tokens 用），默认按内置链信息表，表里没有时为 null */
+    nativeSymbol?: string;
+    /** 主币名称（tokens 用），默认按内置链信息表，表里没有时为 null */
+    nativeName?: string;
+}
+export interface TokensOptions<F extends TokenField = DefaultTokenField> extends CallOverrides {
+    /** 要返回的字段，默认 ['name', 'symbol', 'decimals'] */
+    fields?: readonly F[];
+}
+export interface BalancesOptions extends CallOverrides {
+    /** 同时返回 symbol（代币查一次后缓存；主币取 nativeSymbol / 内置链信息表）。默认 false */
+    symbol?: boolean;
 }
 /**
  * Multicall Provider，API 与 ethcall 的 Provider 保持一致：
@@ -54,13 +69,39 @@ export interface ProviderConfig extends SourceOptions {
  */
 export declare class Provider implements ContractRunner {
     #private;
+    /**
+     * 两种写法：
+     *
+     * ```ts
+     * new Provider(window.ethereum)          // 只传节点：chainId 从节点识别
+     * new Provider([url1, url2], config)
+     * new Provider(56)                       // 只传 chainId：使用内置公共节点
+     * new Provider(56, rpc, config)          // 都传（与 ethcall 相同），不需要识别
+     * ```
+     *
+     * @param provider 节点：RPC URL、ethers Provider、钱包（window.ethereum / tronWeb）或它们的数组（主节点 + 备用节点）
+     * @param config 可选配置
+     */
+    constructor(provider: ProviderSource | readonly ProviderSource[], config?: ProviderConfig);
     /**
      * @param chainId 链 ID（接受数字字符串）
-     * @param provider 节点：RPC URL、ethers Provider、钱包（window.ethereum / tronWeb）或它们的数组（主节点 + 备用节点）。
-     *   不传则使用内置的公共节点表
+     * @param provider 节点，不传则使用内置的公共节点表
      * @param config 可选配置
      */
     constructor(chainId: number | string, provider?: ProviderSource | readonly ProviderSource[], config?: ProviderConfig);
+    /**
+     * 只传节点时等 chainId 识别完成后再返回实例，之后 rpc / multicall 等同步属性可以直接用。
+     *
+     * ```ts
+     * const multi = await Provider.create(window.ethereum)
+     * multi.rpc // 已就绪
+     * ```
+     */
+    static create(provider: ProviderSource | readonly ProviderSource[], config?: ProviderConfig): Promise<Provider>;
+    /** 链 ID（不传 chainId 构造时，会等待从节点识别完成） */
+    getChainId(): Promise<number>;
+    /** 等待初始化完成（只传节点时会先识别 chainId；识别失败在这里抛出） */
+    ready(): Promise<this>;
     /**
      * 绑定到本 Provider 的合约：方法返回的 Call 可以直接 await（自动合并成 multicall），
      * 也可以传给 all / tryAll；`method.staticCall(...)` 预执行。
@@ -74,15 +115,55 @@ export declare class Provider implements ContractRunner {
     /** 绑定的 ERC20 合约（内置 ABI，结果带类型） */
     erc20(address: string): Erc20Contract;
     /**
-     * 批量查余额，主币和代币混在一起、一次请求。主币地址见 config.nativeTokens。
-     * 查询失败（非合约地址、非法地址等）的位置为 0n；需要区分失败请用 tryAll。
+     * 批量查余额（含按 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
+     */
+    balances(owner: string, tokens: readonly BalanceToken[], options?: BalancesOptions): Promise<TokenBalance[]>;
+    /**
+     * 批量查 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 }`
      */
-    balances(owner: string, tokens: readonly string[], overrides?: CallOverrides): Promise<bigint[]>;
+    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[]>;
     /**
-     * 批量查代币信息（symbol / name / decimals），一次请求。
-     * decimals 读不到（非代币合约、主币占位地址等）的位置为 null。
+     * 批量查 ERC20 代币详情，一次请求；可以选择返回哪些字段。
+     *
+     * ```ts
+     * await multi.tokens([USDT, NATIVE_TOKEN])                                       // name / symbol / decimals
+     * await multi.tokens([USDT], { fields: ['symbol', 'decimals', 'totalSupply'] })
+     * // [{ address: USDT, native: false, symbol: 'USDT', decimals: 18, totalSupply: '…', totalSupplyFormatted: '…', success: true }]
+     * ```
+     *
+     * - name / symbol / decimals 查到一次后缓存（与 balances 共用），totalSupply 每次都查
+     * - 主币占位地址不发请求，信息取内置链信息表（可用 nativeName / nativeSymbol / nativeDecimals 覆盖），totalSupply 为 null
+     * - symbol / name 兼容返回 bytes32 的老代币（MKR 等）
+     * - 读取失败的字段为 null；请求的字段都读到时 success 为 true
      */
-    tokenInfo(tokens: readonly string[], overrides?: CallOverrides): Promise<(TokenInfo | null)[]>;
+    tokens<const F extends TokenField = DefaultTokenField>(tokens: readonly string[], options?: TokensOptions<F>): Promise<TokenDetails<F>[]>;
     /**
      * 主币余额查询，可以和合约调用放在同一批里（同一次 eth_call）：
      * 有 Multicall3 时调合约的 getEthBalance；deployless 时由 deployless 合约直接用 BALANCE 读取。
@@ -127,9 +208,9 @@ export declare class Provider implements ContractRunner {
      * @param overrides 所有条目共享的 overrides，优先级最低
      */
     staticCallAll<T = any>(items: ReadonlyArray<Call | StaticCallItem>, overrides?: StaticCallOverrides): Promise<StaticCallResult<T>[]>;
-    /** 底层连接（多节点时是 FallbackRpc） */
+    /** 底层连接（多节点时是 FallbackRpc）。只传节点构造时，需在 ready() 之后读取 */
     get rpc(): EthersLikeProvider;
-    /** 当前使用的 multicall 合约（null 表示 deployless） */
+    /** 当前使用的 multicall 合约（null 表示 deployless；只传节点构造时在 ready() 之前也为 null） */
     get multicall(): Multicall | null;
 }
 export default Provider;

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,12 +1,21 @@
 import {} from 'ethers';
 import { aggregate } from './aggregate.js';
 import { Batcher } from './batcher.js';
-import { decodeCall, encodeCall } from './call.js';
+import { asStringOrBytes32, decodeCall, encodeCall } from './call.js';
 import { Contract, bindCall } from './contract.js';
-import { DEFAULT_NATIVE_TOKENS, ERC20_ABI } from './erc20.js';
+import { DEFAULT_NATIVE_TOKENS, ERC20_ABI, formatAmount, 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 { resolveSource } from './source.js';
+import { getNativeCurrency } from './chains.js';
+import { erc1155Balances, nftBalances, nftCollections, nftOwners, nftTokenUris, } from './nft.js';
+import { detectChainId } from './detect.js';
+import { isTronChain, resolveSource } from './source.js';
+/** 构造参数第一个是 chainId 还是节点：数字、数字字符串、0x 十六进制视为 chainId，其余（URL、对象、数组）视为节点 */
+function isChainIdArg(value) {
+    return (typeof value === 'number' ||
+        typeof value === 'bigint' ||
+        (typeof value === 'string' && /^\s*(\d+|0x[0-9a-fA-F]+)\s*$/.test(value)));
+}
 const ETH_BALANCE_INPUTS = [{ name: 'addr', type: 'address' }];
 const ETH_BALANCE_OUTPUTS = [{ name: 'balance', type: 'uint256' }];
 /**
@@ -18,25 +27,89 @@ const ETH_BALANCE_OUTPUTS = [{ name: 'balance', type: 'uint256' }];
  * ```
  */
 export class Provider {
-    #ctx;
+    /** 不传 chainId 时在识别完成前为 null */
+    #ctx = null;
+    /** 识别中的 Promise；识别失败后置空，下次使用时重试 */
+    #detecting = null;
+    #source;
     #batcher;
     #nativeTokens;
+    #config;
+    constructor(first, second, third) {
+        const hasChainId = isChainIdArg(first);
+        const source = (hasChainId ? second : first);
+        const config = ((hasChainId ? third : second) ?? {});
+        this.#config = config;
+        this.#batcher = new Batcher((requests, overrides) => this.#aggregate(requests, overrides), config.batch);
+        this.#nativeTokens = new Set((config.nativeTokens ?? DEFAULT_NATIVE_TOKENS).map((t) => t.toLowerCase()));
+        this.#source = source;
+        if (hasChainId) {
+            this.#ctx = this.#createContext(Number(first), source);
+        }
+        else {
+            if (source === undefined) {
+                throw new Error('Provider requires a chainId or a provider');
+            }
+            // 提前开始识别；失败时由使用方的调用拿到错误（这里避免未处理的 rejection）
+            this.#ensureReady().catch(() => { });
+        }
+    }
     /**
-     * @param chainId 链 ID（接受数字字符串）
-     * @param provider 节点：RPC URL、ethers Provider、钱包（window.ethereum / tronWeb）或它们的数组（主节点 + 备用节点）。
-     *   不传则使用内置的公共节点表
-     * @param config 可选配置
+     * 只传节点时等 chainId 识别完成后再返回实例，之后 rpc / multicall 等同步属性可以直接用。
+     *
+     * ```ts
+     * const multi = await Provider.create(window.ethereum)
+     * multi.rpc // 已就绪
+     * ```
      */
-    constructor(chainId, provider, config = {}) {
-        const id = Number(chainId);
-        this.#ctx = {
-            provider: resolveSource(id, provider, config),
-            chainId: id,
-            multicall: config.deployless ? null : resolveMulticall(id, config.multicall),
+    static async create(provider, config) {
+        return new Provider(provider, config).ready();
+    }
+    /** 取初始化好的上下文；识别失败不会被永久记住，下次调用重新识别（如节点短暂限流） */
+    #ensureReady() {
+        if (this.#ctx) {
+            return Promise.resolve(this.#ctx);
+        }
+        if (!this.#detecting) {
+            const source = this.#source;
+            const detecting = detectChainId(source, this.#config.fallback?.timeout).then((id) => {
+                this.#ctx = this.#createContext(id, source);
+                return this.#ctx;
+            });
+            this.#detecting = detecting;
+            detecting.catch(() => {
+                if (this.#detecting === detecting) {
+                    this.#detecting = null;
+                }
+            });
+        }
+        return this.#detecting;
+    }
+    #createContext(chainId, source) {
+        const config = this.#config;
+        return {
+            provider: resolveSource(chainId, source, config),
+            chainId,
+            multicall: config.deployless ? null : resolveMulticall(chainId, config.multicall),
             chunkSize: config.chunkSize ?? 500,
         };
-        this.#batcher = new Batcher((requests, overrides) => this.#aggregate(requests, overrides), config.batch);
-        this.#nativeTokens = new Set((config.nativeTokens ?? DEFAULT_NATIVE_TOKENS).map((t) => t.toLowerCase()));
+    }
+    /** 链 ID（不传 chainId 构造时，会等待从节点识别完成） */
+    async getChainId() {
+        return (await this.#ensureReady()).chainId;
+    }
+    /** 等待初始化完成（只传节点时会先识别 chainId；识别失败在这里抛出） */
+    async ready() {
+        await this.#ensureReady();
+        return this;
+    }
+    #nativeCurrency(chainId) {
+        const known = getNativeCurrency(chainId);
+        return {
+            decimals: this.#config.nativeDecimals ?? known?.decimals ?? (isTronChain(chainId) ? 6 : 18),
+            symbol: this.#config.nativeSymbol ?? known?.symbol ?? null,
+            name: this.#config.nativeName ?? known?.name ?? null,
+        };
     }
     /**
      * 绑定到本 Provider 的合约：方法返回的 Call 可以直接 await（自动合并成 multicall），
@@ -55,39 +128,218 @@ export class Provider {
         return new Contract(address, ERC20_ABI, this);
     }
     /**
-     * 批量查余额，主币和代币混在一起、一次请求。主币地址见 config.nativeTokens。
-     * 查询失败（非合约地址、非法地址等）的位置为 0n；需要区分失败请用 tryAll。
+     * 批量查余额（含按 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, overrides) {
-        const calls = tokens.map((token) => this.#nativeTokens.has(token.toLowerCase()) ? this.getEthBalance(owner) : this.erc20(token).balanceOf(owner));
+    async balances(owner, tokens, options = {}) {
+        const { symbol: withSymbol = false, ...overrides } = options;
+        const { chainId } = await this.#ensureReady();
+        const nativeCurrency = this.#nativeCurrency(chainId);
+        const items = tokens.map((token) => {
+            const resolved = this.#resolveToken(chainId, token, nativeCurrency.decimals);
+            const symbol = resolved.native ? nativeCurrency.symbol : getCachedTokenMeta(chainId, resolved.address).symbol;
+            return { ...resolved, symbol };
+        });
+        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 symbolIndex = withSymbol && !native && symbol === undefined ? calls.push(this.#symbolCall(address)) - 1 : -1;
+            return { balanceIndex, decimalsIndex, symbolIndex };
+        });
         const results = await this.tryAll(calls, overrides);
-        return results.map((balance) => balance ?? 0n);
+        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];
+            if (!item.native && (fetchedDecimals !== null || fetchedSymbol !== null)) {
+                setCachedTokenMeta(chainId, item.address, {
+                    ...(fetchedDecimals !== null ? { decimals: Number(fetchedDecimals) } : {}),
+                    ...(fetchedSymbol !== null ? { symbol: fetchedSymbol } : {}),
+                });
+            }
+            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 };
+            }
+            // 结果全是字符串 / 数字 / 布尔 / null，可以直接 JSON.stringify
+            return {
+                token: item.address,
+                native: item.native,
+                balance: balance.toString(),
+                decimals,
+                formatted: formatAmount(balance, decimals),
+                ...extra,
+                success: true,
+            };
+        });
     }
     /**
-     * 批量查代币信息（symbol / name / decimals），一次请求。
-     * decimals 读不到（非代币合约、主币占位地址等）的位置为 null。
+     * 批量查 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 tokenInfo(tokens, overrides) {
-        // 主币占位地址不是合约，不发请求
-        const targets = tokens.filter((token) => !this.#nativeTokens.has(token.toLowerCase()));
-        const calls = targets.flatMap((token) => {
-            const erc20 = this.erc20(token);
-            return [erc20.symbol(), erc20.name(), erc20.decimals()];
+    async allowances(owner, spender, tokens, overrides) {
+        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;
+            return { address, native, decimals, allowanceIndex, decimalsIndex };
         });
         const results = calls.length ? await this.tryAll(calls, overrides) : [];
-        const infoByToken = new Map();
-        targets.forEach((address, i) => {
-            const decimals = results[i * 3 + 2];
-            infoByToken.set(address, decimals === null
-                ? null
-                : {
-                    address,
-                    symbol: results[i * 3] ?? null,
-                    name: results[i * 3 + 1] ?? null,
-                    decimals: Number(decimals),
+        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);
+            if (fetched !== null) {
+                setCachedTokenMeta(chainId, address, { decimals: Number(fetched) });
+            }
+            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 };
+            }
+            return {
+                token: address,
+                spender,
+                native,
+                allowance: allowance.toString(),
+                decimals,
+                formatted: formatAmount(allowance, decimals),
+                unlimited: allowance >= UNLIMITED_ALLOWANCE_THRESHOLD,
+                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);
+    }
+    /** 批量查 ERC1155 余额 */
+    erc1155Balances(owner, items, overrides) {
+        return erc1155Balances(this, owner, items, overrides);
+    }
+    /** symbol() 调用：string 解码失败时按 bytes32 解析（MKR 等老代币） */
+    #symbolCall(address) {
+        return asStringOrBytes32(this.erc20(address).symbol());
+    }
+    /** 解析 balances / allowances 的代币参数：是否主币、已知的 decimals（传入的 > 主币配置 / 缓存） */
+    #resolveToken(chainId, token, nativeDecimals) {
+        const address = typeof token === 'string' ? token : token.address;
+        const native = this.#nativeTokens.has(address.toLowerCase());
+        const passed = typeof token === 'string' ? undefined : token.decimals;
+        const decimals = passed ?? (native ? nativeDecimals : getCachedTokenMeta(chainId, address).decimals);
+        return { address, native, decimals };
+    }
+    /**
+     * 批量查 ERC20 代币详情，一次请求；可以选择返回哪些字段。
+     *
+     * ```ts
+     * await multi.tokens([USDT, NATIVE_TOKEN])                                       // name / symbol / decimals
+     * await multi.tokens([USDT], { fields: ['symbol', 'decimals', 'totalSupply'] })
+     * // [{ address: USDT, native: false, symbol: 'USDT', decimals: 18, totalSupply: '…', totalSupplyFormatted: '…', success: true }]
+     * ```
+     *
+     * - name / symbol / decimals 查到一次后缓存（与 balances 共用），totalSupply 每次都查
+     * - 主币占位地址不发请求，信息取内置链信息表（可用 nativeName / nativeSymbol / nativeDecimals 覆盖），totalSupply 为 null
+     * - symbol / name 兼容返回 bytes32 的老代币（MKR 等）
+     * - 读取失败的字段为 null；请求的字段都读到时 success 为 true
+     */
+    async tokens(tokens, options = {}) {
+        const { fields = DEFAULT_TOKEN_FIELDS, ...overrides } = options;
+        const wanted = new Set(fields);
+        const needDecimals = wanted.has('decimals') || wanted.has('totalSupply');
+        const { chainId } = await this.#ensureReady();
+        const nativeCurrency = this.#nativeCurrency(chainId);
+        const calls = [];
+        const plan = tokens.map((address) => {
+            const native = this.#nativeTokens.has(address.toLowerCase());
+            const meta = native
+                ? { name: nativeCurrency.name ?? undefined, symbol: nativeCurrency.symbol ?? undefined, decimals: nativeCurrency.decimals }
+                : getCachedTokenMeta(chainId, address);
+            const index = {};
+            if (!native) {
+                const erc20 = this.erc20(address);
+                if (wanted.has('name') && meta.name === undefined) {
+                    index.name = calls.push(asStringOrBytes32(erc20.name())) - 1;
+                }
+                if (wanted.has('symbol') && meta.symbol === undefined) {
+                    index.symbol = calls.push(this.#symbolCall(address)) - 1;
+                }
+                if (needDecimals && meta.decimals === undefined) {
+                    index.decimals = calls.push(erc20.decimals()) - 1;
+                }
+                if (wanted.has('totalSupply')) {
+                    index.totalSupply = calls.push(erc20.totalSupply()) - 1;
+                }
+            }
+            return { address, native, meta, index };
+        });
+        const results = calls.length ? await this.tryAll(calls, overrides) : [];
+        const read = (i) => (i === undefined ? null : (results[i] ?? null));
+        return plan.map(({ address, native, meta, index }) => {
+            const name = meta.name ?? read(index.name);
+            const symbol = meta.symbol ?? read(index.symbol);
+            const fetchedDecimals = read(index.decimals);
+            const decimals = meta.decimals ?? (fetchedDecimals === null ? null : Number(fetchedDecimals));
+            const totalSupply = read(index.totalSupply);
+            if (!native) {
+                setCachedTokenMeta(chainId, address, {
+                    ...(index.name !== undefined && name !== null ? { name } : {}),
+                    ...(index.symbol !== undefined && symbol !== null ? { symbol } : {}),
+                    ...(fetchedDecimals !== null ? { decimals: Number(fetchedDecimals) } : {}),
                 });
+            }
+            const values = {
+                name,
+                symbol,
+                decimals,
+                totalSupply: totalSupply === null ? null : totalSupply.toString(),
+            };
+            const out = { address, native };
+            let success = true;
+            for (const field of fields) {
+                out[field] = values[field];
+                // 主币没有 totalSupply，不算失败
+                if (values[field] === null && !(native && field === 'totalSupply')) {
+                    success = false;
+                }
+            }
+            if (wanted.has('totalSupply')) {
+                out.totalSupplyFormatted = totalSupply === null || decimals === null ? null : formatAmount(totalSupply, decimals);
+            }
+            out.success = success;
+            return out;
         });
-        return tokens.map((token) => infoByToken.get(token) ?? null);
     }
     /**
      * 主币余额查询，可以和合约调用放在同一批里（同一次 eth_call）：
@@ -95,7 +347,8 @@ export class Provider {
      */
     getEthBalance(address) {
         const call = {
-            contract: { address: this.#ctx.multicall?.address ?? MULTICALL3_ADDRESS },
+            // 地址只用于展示：执行时合约模式会换成实际的 multicall 地址，deployless 时由合约内部处理
+            contract: { address: this.#ctx?.multicall?.address ?? MULTICALL3_ADDRESS },
             name: 'getEthBalance',
             inputs: ETH_BALANCE_INPUTS,
             outputs: ETH_BALANCE_OUTPUTS,
@@ -180,7 +433,8 @@ export class Provider {
         const merged = merge(merge({ ...shared }, call.overrides), explicit);
         if (call.kind === 'ethBalance') {
             try {
-                return { success: true, data: (await this.#ctx.provider.getBalance(call.params[0], merged.blockTag)) };
+                const { provider } = await this.#ensureReady();
+                return { success: true, data: (await provider.getBalance(call.params[0], merged.blockTag)) };
             }
             catch (err) {
                 return { success: false, error: err instanceof Error ? err : new Error(String(err)) };
@@ -189,7 +443,8 @@ export class Provider {
         let returnData;
         try {
             const request = encodeCall(call, false);
-            returnData = await this.#ctx.provider.call({
+            const { provider } = await this.#ensureReady();
+            returnData = await provider.call({
                 to: request.target,
                 data: request.callData,
                 from: merged.from,
@@ -213,16 +468,19 @@ export class Provider {
             return { success: false, error: new CallFailedError(call, returnData, err) };
         }
     }
-    /** 底层连接（多节点时是 FallbackRpc） */
+    /** 底层连接（多节点时是 FallbackRpc）。只传节点构造时，需在 ready() 之后读取 */
     get rpc() {
+        if (!this.#ctx) {
+            throw new Error('Provider is still detecting chainId; await provider.ready() first');
+        }
         return this.#ctx.provider;
     }
-    /** 当前使用的 multicall 合约（null 表示 deployless） */
+    /** 当前使用的 multicall 合约（null 表示 deployless；只传节点构造时在 ready() 之前也为 null） */
     get multicall() {
-        return this.#ctx.multicall;
+        return this.#ctx?.multicall ?? null;
     }
-    #aggregate(requests, overrides) {
-        return aggregate(this.#ctx, requests, overrides);
+    async #aggregate(requests, overrides) {
+        return aggregate(await this.#ensureReady(), requests, overrides);
     }
 }
 function resolveMulticall(chainId, custom) {