@w3lib/evm-batch-call 0.2.0 → 0.4.0

package/dist/deployless.js.map

@@ -1 +1 @@
-{"version":3,"file":"deployless.js","sourceRoot":"","sources":["../src/deployless.ts"],"names":[],"mappings":"AAAA,4HAA4H;AAE5H,wGAAwG;AACxG,MAAM,CAAC,MAAM,8BAA8B,GACzC,kiGAAkiG,CAAA"}
+{"version":3,"file":"deployless.js","sourceRoot":"","sources":["../src/deployless.ts"],"names":[],"mappings":"AAAA,4HAA4H;AAE5H,wGAAwG;AACxG,MAAM,CAAC,MAAM,8BAA8B,GACzC,s4GAAs4G,CAAA"}

package/dist/erc20.d.ts

@@ -1,4 +1,4 @@
-import type { BoundCall } from './call.js';
+import type { BoundCall, FailureReason } from './call.js';
 import type { BoundMethod, Contract } from './contract.js';
 export declare const ERC20_ABI: readonly ["function name() view returns (string)", "function symbol() view returns (string)", "function decimals() view returns (uint8)", "function totalSupply() view returns (uint256)", "function balanceOf(address owner) view returns (uint256)", "function allowance(address owner, address spender) view returns (uint256)", "function approve(address spender, uint256 amount) returns (bool)", "function transfer(address to, uint256 amount) returns (bool)", "function transferFrom(address from, address to, uint256 amount) returns (bool)"];
 type Method<Args extends unknown[], T> = ((...params: Args) => BoundCall<T>) & Pick<BoundMethod<T>, 'staticCall'>;
@@ -27,8 +27,16 @@ export interface TokenAllowance {
     formatted: string;
     /** 额度 ≥ uint96 最大值时为 true（覆盖 MaxUint256，以及 UNI / COMP 等把额度截断为 uint96 的代币） */
     unlimited: boolean;
+    /** 仅在 withBlock / minBlock 时返回：读取时的区块号（读取失败为 null） */
+    blockNumber?: number | null;
     success: boolean;
+    /** 仅在 success 为 false 时返回：失败原因 */
+    error?: FailureReason;
+    /** 仅在 success 为 false 时返回：哪一项没读到 */
+    errorField?: 'allowance' | 'decimals';
 }
+/** allowances(..., { decimals: false }) 的单项结果：不查 decimals，不带 decimals / formatted */
+export type RawTokenAllowance = Omit<TokenAllowance, 'decimals' | 'formatted'>;
 /** unlimited 的判定阈值：uint96 最大值 */
 export declare const UNLIMITED_ALLOWANCE_THRESHOLD: bigint;
 declare const MAX_UINT256: bigint;
@@ -53,8 +61,14 @@ export type TokenDetails<F extends TokenField = DefaultTokenField> = {
     address: string;
     /** 是否是主币占位地址（信息来自内置链信息表 / nativeSymbol 等配置） */
     native: boolean;
+    /** 仅在 withBlock / minBlock 时返回：读取时的区块号（读取失败为 null） */
+    blockNumber?: number | null;
     /** 请求的字段都读到时为 true（主币没有 totalSupply，不计入） */
     success: boolean;
+    /** 仅在 success 为 false 时返回：第一个没读到的字段的失败原因 */
+    error?: FailureReason;
+    /** 仅在 success 为 false 时返回：第一个没读到的字段 */
+    errorField?: TokenField;
 } & {
     [K in F]: TokenFieldTypes[K];
 } & ('totalSupply' extends F ? {
@@ -81,14 +95,29 @@ export interface TokenBalance {
     formatted: string;
     /** 仅在 symbol: true 时返回；读取失败或主币 symbol 未知时为 null */
     symbol?: string | null;
+    /** 仅在 withBlock / minBlock 时返回：读取时的区块号（与余额在同一次 eth_call 里读出；读取失败为 null） */
+    blockNumber?: number | null;
     /** 余额和 decimals 都查到时为 true；失败时 balance、formatted 都为 "0" */
     success: boolean;
+    /**
+     * 仅在 success 为 false 时返回：失败原因（invalid-address 地址非法、no-contract 地址上没有合约、
+     * reverted 执行 revert、decode-failed 返回值无法解码）。symbol 读不到不算失败（symbol 为 null）
+     */
+    error?: FailureReason;
+    /** 仅在 success 为 false 时返回：哪一项没读到（两项都失败时为 balance） */
+    errorField?: 'balance' | 'decimals';
 }
+/** balances(..., { decimals: false }) 的单项结果：不查 decimals，不带 decimals / formatted */
+export type RawTokenBalance = Omit<TokenBalance, 'decimals' | 'formatted' | 'errorField'> & {
+    errorField?: 'balance';
+};
 /**
- * 按精度格式化：formatAmount(1234500000n, 6) === '1234.5'，formatAmount(10n ** 18n, 18) === '1'。
- * 不做四舍五入，保留全部有效小数位。
+ * 按精度格式化（与 ethers 的 formatUnits 同名同义）：formatUnits(1234500000n, 6) === '1234.5'，formatUnits(10n ** 18n, 18) === '1'。
+ * 不做四舍五入，保留全部有效小数位，整数不带小数点（与 ethers 不同：ethers 会返回 '1.0'）。
  */
-export declare function formatAmount(value: bigint, decimals: number): string;
+export declare function formatUnits(value: bigint, decimals: number): string;
+/** @deprecated 改用 formatUnits（同一个函数；formatAmount 容易与项目里的数字展示函数撞名） */
+export declare const formatAmount: typeof formatUnits;
 interface TokenMeta {
     decimals?: number;
     symbol?: string;
@@ -96,8 +125,45 @@ interface TokenMeta {
     /** NFT 集合标准（nftCollections 识别后缓存）；null 表示确认不是 ERC721 / ERC1155 */
     standard?: 'ERC721' | 'ERC1155' | null;
 }
+interface CachedMeta extends TokenMeta {
+    /** name / symbol 各自的写入时间（分开计：只刷新其中一个时，另一个照常过期） */
+    nameAt?: number;
+    symbolAt?: number;
+}
 export declare function getCachedTokenMeta(chainId: number, token: string): TokenMeta;
 export declare function setCachedTokenMeta(chainId: number, token: string, meta: TokenMeta): void;
 /** 测试用：清空 decimals / symbol 缓存 */
 export declare function resetDecimalsCache(): void;
+/** exportTokenMetaCache() 的结果，可以 JSON.stringify */
+export interface TokenMetaSnapshot {
+    version: 1;
+    /** [chainId:小写地址, 信息]，按写入时间先后 */
+    entries: Array<[string, CachedMeta]>;
+}
+/**
+ * 导出代币信息缓存（decimals / symbol / name / NFT 标准），可存到任意地方，下次用 importTokenMetaCache 导入，
+ * 页面刷新后不必重查精度。name / symbol 带写入时间，导入后仍按 1 小时过期。
+ *
+ * @param maxEntries 最多导出多少条（最近写入的优先），默认全部
+ */
+export declare function exportTokenMetaCache(maxEntries?: number): TokenMetaSnapshot;
+/** 导入 exportTokenMetaCache 的结果；格式不对的数据忽略。已有的条目以缓存里的为准（更新） */
+export declare function importTokenMetaCache(snapshot: unknown): void;
+/** persistTokenMetaCache 的存储：localStorage / sessionStorage 可以直接传，也可以自己实现 */
+export interface TokenMetaStore {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/**
+ * 把代币信息缓存持久化到同步的键值存储（如 localStorage）：调用时先读入，之后缓存有更新就防抖（1 秒）整体写回。
+ * 返回停止持久化的函数。存储读写出错（如超出配额）时忽略。
+ *
+ * ```ts
+ * persistTokenMetaCache(localStorage) // 刷新页面后不必重查 decimals
+ * ```
+ */
+export declare function persistTokenMetaCache(store: TokenMetaStore, options?: {
+    key?: string;
+    maxEntries?: number;
+}): () => void;
 //# sourceMappingURL=erc20.d.ts.map

package/dist/erc20.d.ts.map

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

package/dist/erc20.js

@@ -20,29 +20,145 @@ export const NATIVE_TOKEN = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE';
 /** balances() 默认视为主币的地址：0xeeee…eeee 和零地址 */
 export const DEFAULT_NATIVE_TOKENS = [NATIVE_TOKEN, '0x0000000000000000000000000000000000000000'];
 /**
- * 按精度格式化：formatAmount(1234500000n, 6) === '1234.5'，formatAmount(10n ** 18n, 18) === '1'。
- * 不做四舍五入，保留全部有效小数位。
+ * 按精度格式化（与 ethers 的 formatUnits 同名同义）：formatUnits(1234500000n, 6) === '1234.5'，formatUnits(10n ** 18n, 18) === '1'。
+ * 不做四舍五入，保留全部有效小数位，整数不带小数点（与 ethers 不同：ethers 会返回 '1.0'）。
  */
-export function formatAmount(value, decimals) {
+export function formatUnits(value, decimals) {
     const negative = value < 0n;
     const digits = (negative ? -value : value).toString().padStart(decimals + 1, '0');
     const whole = digits.slice(0, digits.length - decimals);
     const fraction = digits.slice(digits.length - decimals).replace(/0+$/, '');
     return `${negative ? '-' : ''}${whole}${fraction ? `.${fraction}` : ''}`;
 }
+/** @deprecated 改用 formatUnits（同一个函数；formatAmount 容易与项目里的数字展示函数撞名） */
+export const formatAmount = formatUnits;
+const NAME_TTL = 60 * 60 * 1000;
+const MAX_CACHED_TOKENS = 50_000;
 const tokenMetaCache = new Map();
+const cacheListeners = new Set();
 export function getCachedTokenMeta(chainId, token) {
-    return tokenMetaCache.get(`${chainId}:${token.toLowerCase()}`) ?? {};
+    const cached = tokenMetaCache.get(`${chainId}:${token.toLowerCase()}`);
+    if (!cached) {
+        return {};
+    }
+    const { nameAt, symbolAt, ...meta } = cached;
+    const now = Date.now();
+    if (nameAt === undefined || now - nameAt > NAME_TTL) {
+        delete meta.name;
+    }
+    if (symbolAt === undefined || now - symbolAt > NAME_TTL) {
+        delete meta.symbol;
+    }
+    return meta;
 }
 export function setCachedTokenMeta(chainId, token, meta) {
     if (Object.keys(meta).length === 0) {
         return; // 没有新数据（如查询失败）时不写入空条目
     }
+    const defined = { ...meta };
+    if ('name' in meta) {
+        defined.nameAt = Date.now();
+    }
+    if ('symbol' in meta) {
+        defined.symbolAt = Date.now();
+    }
     const key = `${chainId}:${token.toLowerCase()}`;
-    tokenMetaCache.set(key, { ...tokenMetaCache.get(key), ...meta });
+    const merged = { ...tokenMetaCache.get(key), ...defined };
+    tokenMetaCache.delete(key); // 重新插入，保持“最近写入在后”的顺序
+    tokenMetaCache.set(key, merged);
+    if (tokenMetaCache.size > MAX_CACHED_TOKENS) {
+        tokenMetaCache.delete(tokenMetaCache.keys().next().value);
+    }
+    cacheListeners.forEach((listener) => listener());
 }
 /** 测试用：清空 decimals / symbol 缓存 */
 export function resetDecimalsCache() {
     tokenMetaCache.clear();
 }
+/**
+ * 导出代币信息缓存（decimals / symbol / name / NFT 标准），可存到任意地方，下次用 importTokenMetaCache 导入，
+ * 页面刷新后不必重查精度。name / symbol 带写入时间，导入后仍按 1 小时过期。
+ *
+ * @param maxEntries 最多导出多少条（最近写入的优先），默认全部
+ */
+export function exportTokenMetaCache(maxEntries = Number.POSITIVE_INFINITY) {
+    const entries = [...tokenMetaCache];
+    return { version: 1, entries: entries.slice(Math.max(0, entries.length - maxEntries)) };
+}
+/** 导入 exportTokenMetaCache 的结果；格式不对的数据忽略。已有的条目以缓存里的为准（更新） */
+export function importTokenMetaCache(snapshot) {
+    const entries = snapshot?.entries;
+    if (snapshot?.version !== 1 || !Array.isArray(entries)) {
+        return;
+    }
+    for (const entry of entries) {
+        if (!Array.isArray(entry) || typeof entry[0] !== 'string' || !/^\d+:\S+$/.test(entry[0]) || !entry[1] || typeof entry[1] !== 'object') {
+            continue;
+        }
+        const [rawKey, value] = entry;
+        // 与 getCachedTokenMeta 的 key 一致：地址部分小写
+        const separator = rawKey.indexOf(':');
+        const key = `${rawKey.slice(0, separator)}:${rawKey.slice(separator + 1).toLowerCase()}`;
+        const meta = {};
+        if (Number.isInteger(value.decimals) && value.decimals >= 0 && value.decimals <= 255)
+            meta.decimals = value.decimals;
+        if (typeof value.name === 'string' && typeof value.nameAt === 'number') {
+            meta.name = value.name;
+            meta.nameAt = value.nameAt;
+        }
+        if (typeof value.symbol === 'string' && typeof value.symbolAt === 'number') {
+            meta.symbol = value.symbol;
+            meta.symbolAt = value.symbolAt;
+        }
+        if (value.standard === 'ERC721' || value.standard === 'ERC1155' || value.standard === null)
+            meta.standard = value.standard;
+        if (Object.keys(meta).length && !tokenMetaCache.has(key)) {
+            tokenMetaCache.set(key, meta);
+        }
+    }
+    while (tokenMetaCache.size > MAX_CACHED_TOKENS) {
+        tokenMetaCache.delete(tokenMetaCache.keys().next().value);
+    }
+}
+/**
+ * 把代币信息缓存持久化到同步的键值存储（如 localStorage）：调用时先读入，之后缓存有更新就防抖（1 秒）整体写回。
+ * 返回停止持久化的函数。存储读写出错（如超出配额）时忽略。
+ *
+ * ```ts
+ * persistTokenMetaCache(localStorage) // 刷新页面后不必重查 decimals
+ * ```
+ */
+export function persistTokenMetaCache(store, options = {}) {
+    const { key = 'w3lib:evm-token-meta', maxEntries = 5000 } = options;
+    try {
+        const raw = store.getItem(key);
+        if (raw) {
+            importTokenMetaCache(JSON.parse(raw));
+        }
+    }
+    catch {
+        // 数据损坏：忽略，之后会被覆盖
+    }
+    let timer;
+    const save = () => {
+        timer = undefined;
+        try {
+            store.setItem(key, JSON.stringify(exportTokenMetaCache(maxEntries)));
+        }
+        catch {
+            // 超出配额等：忽略
+        }
+    };
+    const listener = () => {
+        timer ??= setTimeout(save, 1000);
+    };
+    cacheListeners.add(listener);
+    return () => {
+        cacheListeners.delete(listener);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            save();
+        }
+    };
+}
 //# sourceMappingURL=erc20.js.map

package/dist/erc20.js.map

@@ -1 +1 @@
-{"version":3,"file":"erc20.js","sourceRoot":"","sources":["../src/erc20.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,uCAAuC;IACvC,yCAAyC;IACzC,0CAA0C;IAC1C,+CAA+C;IAC/C,0DAA0D;IAC1D,2EAA2E;IAC3E,kEAAkE;IAClE,8DAA8D;IAC9D,gFAAgF;CACxE,CAAA;AAiCV,iCAAiC;AACjC,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,IAAI,GAAG,GAAG,EAAE,CAAA;AAE3D,MAAM,WAAW,GAAG,EAAE,IAAI,IAAI,GAAG,EAAE,CAAA;AAEnC,OAAO,EAAE,WAAW,EAAE,CAAA;AAKtB,wBAAwB;AACxB,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAA0C,CAAA;AAwB3G,+CAA+C;AAC/C,MAAM,CAAC,MAAM,YAAY,GAAG,4CAA4C,CAAA;AAExE,4CAA4C;AAC5C,MAAM,CAAC,MAAM,qBAAqB,GAAsB,CAAC,YAAY,EAAE,4CAA4C,CAAC,CAAA;AAqBpH;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,QAAgB;IAC1D,MAAM,QAAQ,GAAG,KAAK,GAAG,EAAE,CAAA;IAC3B,MAAM,MAAM,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,QAAQ,GAAG,CAAC,EAAE,GAAG,CAAC,CAAA;IACjF,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAA;IACvD,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IAC1E,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAA;AAC1E,CAAC;AAWD,MAAM,cAAc,GAAG,IAAI,GAAG,EAAqB,CAAA;AAEnD,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,KAAa;IAC/D,OAAO,cAAc,CAAC,GAAG,CAAC,GAAG,OAAO,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,IAAI,EAAE,CAAA;AACtE,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,KAAa,EAAE,IAAe;IAChF,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,OAAM,CAAC,sBAAsB;IAC/B,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,OAAO,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAA;IAC/C,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAA;AAClE,CAAC;AAED,kCAAkC;AAClC,MAAM,UAAU,kBAAkB;IAChC,cAAc,CAAC,KAAK,EAAE,CAAA;AACxB,CAAC"}
+{"version":3,"file":"erc20.js","sourceRoot":"","sources":["../src/erc20.ts"],"names":[],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,25 @@
+/** 一次对某个节点的请求（onRequest 的事件） */
+export interface RequestEvent {
+    /** 节点标识：URL 节点只取 host（不含 path / query，避免泄露 API Key）；钱包为 'wallet'，tronWeb 为 'tronWeb'，其他对象为 'provider' */
+    node: string;
+    /** 'call' | 'getBalance' | 'getChainId' | 'getBlockNumber' | 'getLogs' */
+    method: string;
+    /** 耗时（毫秒） */
+    ms: number;
+    ok: boolean;
+    /** 失败时的错误 */
+    error?: unknown;
+    /** 本次请求按故障切换顺序的第几个节点（0 起）；大于 0 表示换过节点 */
+    attempt: number;
+}
+export type RequestListener = (event: RequestEvent) => void;
+/**
+ * 订阅所有节点请求（全局，对所有 Provider 生效），用于观察哪个节点返回、换过几次节点、每次耗时。返回取消订阅的函数。
+ *
+ * ```ts
+ * const off = onRequest((e) => console.log(e.node, e.method, e.ms, e.ok, e.attempt))
+ * ```
+ */
+export declare function onRequest(listener: RequestListener): () => void;
+export declare function emitRequest(event: RequestEvent): void;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B,yGAAyG;IACzG,IAAI,EAAE,MAAM,CAAA;IACZ,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAA;IACd,aAAa;IACb,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,OAAO,CAAA;IACX,aAAa;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;AAI3D;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,IAAI,CAK/D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAQrD"}

package/dist/events.js

@@ -0,0 +1,25 @@
+const listeners = new Set();
+/**
+ * 订阅所有节点请求（全局，对所有 Provider 生效），用于观察哪个节点返回、换过几次节点、每次耗时。返回取消订阅的函数。
+ *
+ * ```ts
+ * const off = onRequest((e) => console.log(e.node, e.method, e.ms, e.ok, e.attempt))
+ * ```
+ */
+export function onRequest(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+export function emitRequest(event) {
+    for (const listener of listeners) {
+        try {
+            listener(event);
+        }
+        catch {
+            // 监听函数出错不影响请求
+        }
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAiBA,MAAM,SAAS,GAAG,IAAI,GAAG,EAAmB,CAAA;AAE5C;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,QAAyB;IACjD,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IACvB,OAAO,GAAG,EAAE;QACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAC5B,CAAC,CAAA;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAmB;IAC7C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,QAAQ,CAAC,KAAK,CAAC,CAAA;QACjB,CAAC;QAAC,MAAM,CAAC;YACP,cAAc;QAChB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/fallback.d.ts

@@ -3,11 +3,39 @@ import type { EthersLikeProvider } from './aggregate.js';
 export interface FallbackOptions {
     /** 单个节点单次请求超时（毫秒），超时视为该节点故障并换下一个。默认 10000；<= 0 表示不限制 */
     timeout?: number;
-    /** 节点出错后跳过它的时长（毫秒），期间优先用其他节点。默认 30000 */
+    /**
+     * 节点迟迟不返回时，过多久（毫秒）同时请求下一个节点：原来的请求不取消，谁先成功用谁（与 ethers FallbackProvider 的 stallTimeout 相同）。
+     * 适合正常但偶尔较慢的节点：不必把 timeout 设得很短（正常的慢请求会被判成超时）。
+     * 默认 0（不提前请求，只在出错 / 超时后换节点）；只影响 call / getBalance，不影响 getLogs / getBlockNumber
+     */
+    stallTimeout?: number;
+    /** 节点出错后跳过它的时长（毫秒），期间优先用其他节点。默认 30000。超时不算出错，同一节点连续 3 次超时才冷却 */
     cooldown?: number;
 }
+/** FallbackRpc 每个节点的标识（resolveSource 传入；直接 new FallbackRpc 时可省略） */
+export interface FallbackNodeInfo {
+    /** 用于错误信息和 onRequest 事件的节点标识 */
+    label: string;
+    /** 健康状态的 key：URL 字符串或节点对象。相同 key 的节点在所有 FallbackRpc 之间共享冷却状态 */
+    key: string | object;
+}
+/** 测试用：清空全局的节点健康状态 */
+export declare function resetNodeHealth(): void;
+/** 所有节点都失败（多节点时）：errors 是每个节点的标识和失败原因，按尝试顺序 */
+export declare class AllNodesFailedError extends Error {
+    readonly errors: ReadonlyArray<{
+        node: string;
+        error: unknown;
+    }>;
+    constructor(errors: ReadonlyArray<{
+        node: string;
+        error: unknown;
+    }>);
+}
 /**
- * 多节点故障切换：按顺序使用节点，出错或超时换下一个；出错的节点在 cooldown 内排到最后。
+ * 多节点故障切换：按顺序使用节点，出错或超时换下一个；出错的节点在 cooldown 内排到最后（超时只换节点，连续 3 次才冷却）。
+ * 设置了 stallTimeout 时，节点迟迟不返回就同时请求下一个，谁先成功用谁。所有节点都失败时抛 AllNodesFailedError（单节点时抛原始错误）。
+ * 冷却状态按节点全局共享，每次请求都会触发 onRequest 事件。
  *
  * 与 ethers FallbackProvider 相比：
  * - 没有首次请求前对所有节点的 getBlockNumber 同步，一个卡住的节点不会拖住第一次查询
@@ -15,11 +43,34 @@ export interface FallbackOptions {
  */
 export declare class FallbackRpc implements EthersLikeProvider {
     #private;
-    constructor(nodes: EthersLikeProvider[], options?: FallbackOptions);
+    constructor(nodes: EthersLikeProvider[], options?: FallbackOptions, info?: readonly FallbackNodeInfo[]);
     get nodes(): readonly EthersLikeProvider[];
     call(tx: TransactionRequest): Promise<string>;
     getBalance(address: Parameters<EthersLikeProvider['getBalance']>[0], blockTag?: Parameters<EthersLikeProvider['getBalance']>[1]): Promise<bigint>;
     /** 按节点顺序探测 chainId（节点需实现 getChainId，见 detect.ts） */
     getChainId(): Promise<number>;
+    /**
+     * 当前区块号。优先问上次 getLogs 成功的节点（增量扫描时区块号和日志来自同一个节点，不会因节点间的高度差漏扫）；
+     * 不支持 getBlockNumber 的节点跳过，失败也不让节点进入冷却（不影响 call / getBalance）
+     */
+    getBlockNumber(): Promise<number>;
+    /**
+     * 依次尝试支持 getLogs 的节点。与其他请求不同：
+     * - getLogs 失败多半是“区块范围超限 / 节点不开放这个方法”，不代表节点故障，所以不影响 call / getBalance 的节点顺序；
+     *   超时 / 连不上的节点只在 getLogs 里排到后面（冷却期内），上次成功的节点排在最前
+     * - 在用的节点被限频时直接抛出（连续 3 次后才换节点），其他情况全部失败时抛出；GetLogsError 带上每个节点的错误
+     */
+    getLogs(filter: Parameters<NonNullable<EthersLikeProvider['getLogs']>>[0]): Promise<Awaited<ReturnType<NonNullable<EthersLikeProvider['getLogs']>>>>;
+}
+/**
+ * getLogs 失败时抛出（所有节点都失败，或在用的节点被限频），errors 是各节点的错误；
+ * preferred 是上次成功的节点这次返回的错误（它最能说明问题：其他节点可能一直就不能用）
+ */
+export declare class GetLogsError extends Error {
+    readonly errors: readonly unknown[];
+    readonly preferred?: unknown | undefined;
+    constructor(errors: readonly unknown[], preferred?: unknown | undefined);
 }
+/** 取出错误里节点返回的原始信息（ethers 会把它放在 error.message 里，外层是 “could not coalesce error”） */
+export declare function errorText(err: unknown): string;
 //# sourceMappingURL=fallback.d.ts.map

package/dist/fallback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["../src/fallback.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,kBAAkB,EAAE,MAAM,QAAQ,CAAA;AAEzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAKxD,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;GAMG;AACH,qBAAa,WAAY,YAAW,kBAAkB;;gBAMxC,KAAK,EAAE,kBAAkB,EAAE,EAAE,OAAO,GAAE,eAAoB;IAUtE,IAAI,KAAK,IAAI,SAAS,kBAAkB,EAAE,CAEzC;IAED,IAAI,CAAC,EAAE,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7C,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,UAAU,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAIjJ,oDAAoD;IACpD,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;CA+B9B"}
+{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["../src/fallback.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,kBAAkB,EAAE,MAAM,QAAQ,CAAA;AAEzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAMxD,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CACrB;AAmCD,sBAAsB;AACtB,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED,+CAA+C;AAC/C,qBAAa,mBAAoB,SAAQ,KAAK;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;gBAAvD,MAAM,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;CAI7E;AAED;;;;;;;;GAQG;AACH,qBAAa,WAAY,YAAW,kBAAkB;;gBAexC,KAAK,EAAE,kBAAkB,EAAE,EAAE,OAAO,GAAE,eAAoB,EAAE,IAAI,CAAC,EAAE,SAAS,gBAAgB,EAAE;IAa1G,IAAI,KAAK,IAAI,SAAS,kBAAkB,EAAE,CAEzC;IAED,IAAI,CAAC,EAAE,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7C,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,UAAU,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAIjJ,oDAAoD;IACpD,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAsB7B;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAwBvC;;;;;OAKG;IACG,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,WAAW,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;CAkJ3J;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAEnC,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO;gBADnB,MAAM,EAAE,SAAS,OAAO,EAAE,EAC1B,SAAS,CAAC,EAAE,OAAO,YAAA;CAK/B;AAED,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAI9C"}