@w3lib/evm-batch-call 0.3.0 → 0.4.0

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,7 +43,7 @@ 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>;

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;;gBAYxC,KAAK,EAAE,kBAAkB,EAAE,EAAE,OAAO,GAAE,eAAoB;IAWtE,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;IAI7B;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAgBvC;;;;;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;CAgF3J;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"}
+{"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"}

package/dist/fallback.js

@@ -1,9 +1,49 @@
 import { isError } from 'ethers';
 import { detectChainIdOf } from './detect.js';
 import { isExecutionError } from './errors.js';
-import { withTimeout } from './util.js';
+import { emitRequest } from './events.js';
+import { TimeoutError, withTimeout } from './util.js';
+/** 连续超时多少次后才冷却（偶尔慢不算坏节点） */
+const TIMEOUTS_BEFORE_COOLDOWN = 3;
+const MAX_TRACKED_URLS = 1000;
+const healthByUrl = new Map();
+const healthByObject = new WeakMap();
+function healthOf(key) {
+    if (typeof key === 'string') {
+        let health = healthByUrl.get(key);
+        if (!health) {
+            health = { failedAt: 0, timeouts: 0 };
+            healthByUrl.set(key, health);
+            if (healthByUrl.size > MAX_TRACKED_URLS) {
+                healthByUrl.delete(healthByUrl.keys().next().value);
+            }
+        }
+        return health;
+    }
+    let health = healthByObject.get(key);
+    if (!health) {
+        health = { failedAt: 0, timeouts: 0 };
+        healthByObject.set(key, health);
+    }
+    return health;
+}
+/** 测试用：清空全局的节点健康状态 */
+export function resetNodeHealth() {
+    healthByUrl.clear();
+}
+/** 所有节点都失败（多节点时）：errors 是每个节点的标识和失败原因，按尝试顺序 */
+export class AllNodesFailedError extends Error {
+    errors;
+    constructor(errors) {
+        super(`All RPC nodes failed: ${errors.map((e) => `${e.node}: ${errorText(e.error)}`).join(' | ')}`, { cause: errors[errors.length - 1]?.error });
+        this.errors = errors;
+        this.name = 'AllNodesFailedError';
+    }
+}
 /**
- * 多节点故障切换：按顺序使用节点，出错或超时换下一个；出错的节点在 cooldown 内排到最后。
+ * 多节点故障切换：按顺序使用节点，出错或超时换下一个；出错的节点在 cooldown 内排到最后（超时只换节点，连续 3 次才冷却）。
+ * 设置了 stallTimeout 时，节点迟迟不返回就同时请求下一个，谁先成功用谁。所有节点都失败时抛 AllNodesFailedError（单节点时抛原始错误）。
+ * 冷却状态按节点全局共享，每次请求都会触发 onRequest 事件。
  *
  * 与 ethers FallbackProvider 相比：
  * - 没有首次请求前对所有节点的 getBlockNumber 同步，一个卡住的节点不会拖住第一次查询
@@ -12,50 +52,80 @@ import { withTimeout } from './util.js';
 export class FallbackRpc {
     #nodes;
     #timeout;
+    #stallTimeout;
     #cooldown;
-    #failedAt;
+    #labels;
+    /** 健康状态的 key；每次用时再从全局表里取（表淘汰条目后，各实例仍取到同一个对象） */
+    #healthKeys;
     /** 上次 getLogs 成功的节点 */
     #logsNode = -1;
     /** 上次成功的节点连续被限频的次数 */
     #logsThrottled = 0;
     /** getLogs 超时 / 连不上的时间，只影响 getLogs 的节点顺序 */
     #logsFailedAt;
-    constructor(nodes, options = {}) {
+    constructor(nodes, options = {}, info) {
         if (!nodes.length) {
             throw new Error('FallbackRpc requires at least one node');
         }
         this.#nodes = nodes;
         this.#timeout = options.timeout ?? 10_000;
+        this.#stallTimeout = options.stallTimeout ?? 0;
         this.#cooldown = options.cooldown ?? 30_000;
-        this.#failedAt = nodes.map(() => 0);
+        this.#labels = nodes.map((_, i) => info?.[i]?.label ?? `node${i}`);
+        this.#healthKeys = nodes.map((node, i) => info?.[i]?.key ?? node);
         this.#logsFailedAt = nodes.map(() => 0);
     }
     get nodes() {
         return this.#nodes;
     }
     call(tx) {
-        return this.#run((node) => node.call(tx));
+        return this.#run('call', (node) => node.call(tx));
     }
     getBalance(address, blockTag) {
-        return this.#run((node) => node.getBalance(address, blockTag));
+        return this.#run('getBalance', (node) => node.getBalance(address, blockTag));
     }
     /** 按节点顺序探测 chainId（节点需实现 getChainId，见 detect.ts） */
     getChainId() {
-        return this.#run((node) => detectChainIdOf(node));
+        return this.#run('getChainId', (node) => detectChainIdOf(node));
+    }
+    /** 对第 index 个节点发一次请求（带超时），并触发 onRequest 事件 */
+    async #attempt(method, index, attempt, fn, timeout = this.#timeout) {
+        const started = Date.now();
+        try {
+            const result = await withTimeout(Promise.resolve().then(() => fn(this.#nodes[index])), timeout);
+            emitRequest({ node: this.#labels[index], method, ms: Date.now() - started, ok: true, attempt });
+            return result;
+        }
+        catch (err) {
+            emitRequest({ node: this.#labels[index], method, ms: Date.now() - started, ok: false, error: err, attempt });
+            throw err;
+        }
+    }
+    /** 单节点：直接请求（getLogs / getBlockNumber 不走多节点的特殊逻辑），抛原始错误 */
+    #single(method, fn) {
+        return this.#attempt(method, 0, 0, fn);
     }
     /**
      * 当前区块号。优先问上次 getLogs 成功的节点（增量扫描时区块号和日志来自同一个节点，不会因节点间的高度差漏扫）；
      * 不支持 getBlockNumber 的节点跳过，失败也不让节点进入冷却（不影响 call / getBalance）
      */
     async getBlockNumber() {
+        if (this.#nodes.length === 1) {
+            const node = this.#nodes[0];
+            if (!node.getBlockNumber) {
+                throw new Error('getBlockNumber is not supported by this provider');
+            }
+            return this.#single('getBlockNumber', (n) => n.getBlockNumber());
+        }
         let lastError = new Error('No node supports getBlockNumber');
+        let attempt = 0;
         for (const index of this.#preferLogsNode(this.#order())) {
             const node = this.#nodes[index];
             if (!node.getBlockNumber) {
                 continue;
             }
             try {
-                return await withTimeout(node.getBlockNumber(), this.#timeout);
+                return await this.#attempt('getBlockNumber', index, attempt++, (n) => n.getBlockNumber());
             }
             catch (err) {
                 lastError = err;
@@ -70,16 +140,24 @@ export class FallbackRpc {
      * - 在用的节点被限频时直接抛出（连续 3 次后才换节点），其他情况全部失败时抛出；GetLogsError 带上每个节点的错误
      */
     async getLogs(filter) {
+        if (this.#nodes.length === 1) {
+            // 单节点：原样请求、抛原始错误（与不经过 FallbackRpc 时一致）
+            if (!this.#nodes[0]?.getLogs) {
+                throw new Error('getLogs is not supported by this provider');
+            }
+            return this.#single('getLogs', (n) => n.getLogs(filter));
+        }
         const errors = [];
         let preferred;
         const sticky = this.#logsNode;
+        let attempt = 0;
         for (const index of this.#preferLogsNode(this.#order(this.#logsFailedAt))) {
             const node = this.#nodes[index];
             if (!node.getLogs) {
                 continue;
             }
             try {
-                const logs = await withTimeout(node.getLogs(filter), this.#timeout);
+                const logs = await this.#attempt('getLogs', index, attempt++, (n) => n.getLogs(filter));
                 this.#logsNode = index;
                 this.#logsFailedAt[index] = 0;
                 this.#logsThrottled = 0;
@@ -113,26 +191,80 @@ export class FallbackRpc {
         }
         throw new GetLogsError(errors, preferred);
     }
-    async #run(fn) {
-        let lastError;
-        for (const index of this.#order()) {
-            try {
-                const result = await withTimeout(fn(this.#nodes[index]), this.#timeout);
-                this.#failedAt[index] = 0;
-                return result;
-            }
-            catch (err) {
-                if (isDeterministic(err)) {
-                    throw err;
+    /**
+     * 按顺序请求节点：出错（非确定性错误）或超时立即换下一个；设置了 stallTimeout 时，
+     * 当前节点超过 stallTimeout 还没返回也会同时请求下一个（已发出的请求不取消），第一个成功的结果胜出。
+     * 出错的节点进入冷却；超时只换节点，同一节点连续 3 次超时才冷却（冷启动的大批量查询偶尔慢，不应把健康的节点踢到后面）；
+     * 节点还没有请求的区块（minBlock 重查时落后的节点）也只换节点、不冷却。
+     * 确定性错误（revert、参数错误等）直接抛出；所有节点都失败时抛 AllNodesFailedError（单节点时抛原始错误）。
+     */
+    #run(method, fn) {
+        const order = this.#order();
+        return new Promise((resolve, reject) => {
+            let next = 0;
+            let running = 0;
+            let settled = false;
+            const errors = [];
+            let stallTimer;
+            const finish = (done) => {
+                settled = true;
+                clearTimeout(stallTimer);
+                done();
+            };
+            const fail = () => {
+                const only = errors.length === 1 && this.#nodes.length === 1;
+                finish(() => reject(only ? errors[0]?.error : new AllNodesFailedError(errors)));
+            };
+            const launch = () => {
+                if (settled || next >= order.length) {
+                    return false;
                 }
-                this.#failedAt[index] = Date.now();
-                lastError = err;
-            }
-        }
-        throw lastError;
+                const attempt = next++;
+                const index = order[attempt];
+                const health = healthOf(this.#healthKeys[index]);
+                running++;
+                clearTimeout(stallTimer);
+                if (this.#stallTimeout > 0 && next < order.length) {
+                    stallTimer = setTimeout(launch, this.#stallTimeout);
+                }
+                this.#attempt(method, index, attempt, fn).then((result) => {
+                    running--;
+                    health.failedAt = 0;
+                    health.timeouts = 0;
+                    if (!settled) {
+                        finish(() => resolve(result));
+                    }
+                }, (err) => {
+                    running--;
+                    const deterministic = isDeterministic(err);
+                    if (err instanceof TimeoutError) {
+                        if (++health.timeouts >= TIMEOUTS_BEFORE_COOLDOWN) {
+                            health.failedAt = Date.now();
+                            health.timeouts = 0;
+                        }
+                    }
+                    else if (!deterministic && !isBehind(err)) {
+                        health.failedAt = Date.now();
+                    }
+                    if (settled) {
+                        return;
+                    }
+                    if (deterministic) {
+                        finish(() => reject(err));
+                        return;
+                    }
+                    errors.push({ node: this.#labels[index], error: err });
+                    if (!launch() && running === 0) {
+                        fail();
+                    }
+                });
+                return true;
+            };
+            launch();
+        });
     }
     /** 健康的节点按原顺序在前，冷却中的按出错时间先后排在后面（全挂时也都会再试一次） */
-    #order(failedAt = this.#failedAt) {
+    #order(failedAt = this.#healthKeys.map((key) => healthOf(key).failedAt)) {
         const now = Date.now();
         const healthy = [];
         const cooling = [];
@@ -178,6 +310,12 @@ function isAlive(err) {
 function isRateLimited(err) {
     return /too many requests|rate.?limit|\b429\b/i.test(errorText(err));
 }
+/**
+ * 节点还没有请求的区块（minBlock 按指定区块重查时，落后的节点会这样报错）：只换节点、不冷却——节点本身是健康的，只是慢一两个块
+ */
+function isBehind(err) {
+    return /header not found|unknown block|block not found|block .*not (yet )?(available|found)|requested block .*(ahead|future)|after last accepted block/i.test(errorText(err));
+}
 /** 换节点也不会变的错误：合约执行结果、参数错误、用户拒绝等 */
 function isDeterministic(err) {
     return (isExecutionError(err) ||

package/dist/fallback.js.map

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

package/dist/index.d.ts

@@ -1,20 +1,19 @@
 export { Contract, bindCall, type BoundMethod, type ContractAbi, type ContractRunner } from './contract.js';
-export { getTransferScanState, keyValueScanStorage, memoryScanStorage, transferScan, type TransferScanOptions, type TransferScanState, type TransferScanStorage, } from './scan.js';
 export { GetLogsError } from './fallback.js';
-export { ALCHEMY_NETWORKS, COINGECKO_PLATFORMS, DEFILLAMA_CHAINS, alchemy, clearTokenListCache, coingeckoTokenList, combine, defaultTokenSource, defillamaPrices, firstAvailable, metamaskTokenList, nodereal, staticTokens, tokenList, type DiscoveredToken, type OwnedToken, type OwnerTokensOptions, type PriceSource, type PriceSourceContext, type TokenSource, type TokenSourceContext, } from './owner.js';
-export { getAllowances, getBalances, getErc1155Balances, getNftBalances, getNftCollections, getNftOwners, getNftTokenUris, getOwnerTokens, getTokens, type GetBalancesOptions, type GetNftCollectionsOptions, type GetNftTokenUrisOptions, type GetOwnerTokensOptions, type GetTokensOptions, type ShortcutOptions, type ShortcutProviderOptions, } from './shortcuts.js';
-export { DEFAULT_NFT_COLLECTION_FIELDS, ERC1155_ABI, ERC721_ABI, type DefaultNftCollectionField, type Erc1155Balance, type NftBalance, type NftCollection, type NftCollectionField, type NftCollectionsOptions, type NftItem, type NftOwner, type NftStandard, type NftTokenUri, type NftTokenUriOptions, } from './nft.js';
-export { NATIVE_CURRENCIES, getNativeCurrency, type NativeCurrency } from './chains.js';
+export { getAllowances, getBalances, getMultiBalances, getTokens, type GetAllowancesOptions, type GetBalancesOptions, type GetTokensOptions, type ShortcutOptions, type ShortcutProviderOptions, } from './shortcuts.js';
+export { NATIVE_BALANCE_MODES, NATIVE_CURRENCIES, getNativeBalanceMode, getNativeCurrency, type NativeCurrency } from './chains.js';
 export { clearChainIdCache, detectChainId } from './detect.js';
-export { DEFAULT_NATIVE_TOKENS, ERC20_ABI, NATIVE_TOKEN, formatAmount, type BalanceToken, type Erc20Contract, type TokenBalance, type TokenAllowance, MAX_UINT256, UNLIMITED_ALLOWANCE_THRESHOLD, DEFAULT_TOKEN_FIELDS, type DefaultTokenField, type TokenDetails, type TokenField, } from './erc20.js';
-export { Provider, type BalancesOptions, type CallInput, type CallResults, type ProviderConfig, type ProviderSource, type StaticCallItem, type StaticCallOverrides, type StaticCallResult, type TokensOptions, type TryCallResults, } from './provider.js';
+export { DEFAULT_NATIVE_TOKENS, ERC20_ABI, NATIVE_TOKEN, exportTokenMetaCache, formatAmount, formatUnits, importTokenMetaCache, persistTokenMetaCache, type TokenMetaSnapshot, type TokenMetaStore, type BalanceToken, type Erc20Contract, type RawTokenAllowance, type RawTokenBalance, type TokenBalance, type TokenAllowance, MAX_UINT256, UNLIMITED_ALLOWANCE_THRESHOLD, DEFAULT_TOKEN_FIELDS, type DefaultTokenField, type TokenDetails, type TokenField, } from './erc20.js';
+export { Provider, type AllowancesOptions, type BalancesOptions, type BalancesQuery, type BlockOptions, type CallInput, type CallResults, type ProviderConfig, type ProviderSource, type StaticCallItem, type StaticCallOverrides, type StaticCallResult, type TokensOptions, type TryCallResults, } from './provider.js';
 export { TRON_CHAIN_ID, TronProvider, isTronAddress, toEvmAddress, toTronAddress, type TronProviderOptions, type TronRequest, type TronWebLike, } from './tron.js';
 export { CallFailedError, decodeRevertReason, isExecutionError } from './errors.js';
-export { FallbackRpc, type FallbackOptions } from './fallback.js';
+export { AllNodesFailedError, FallbackRpc, type FallbackNodeInfo, type FallbackOptions } from './fallback.js';
+export { onRequest, type RequestEvent, type RequestListener } from './events.js';
+export { watchBalances, type WatchBalancesOptions } from './watch.js';
 export { ChainCheckedProvider, getDefaultRpcUrls, isTronChain, type SourceOptions } from './source.js';
 export { DEFAULT_RPC_URLS, DEFAULT_TRON_HOSTS } from './rpcNodes.js';
 export { MULTICALL3_ADDRESS, getMulticall3, type Multicall } from './multicall.js';
-export type { BlockTag, CallOverrides, EthersLikeProvider } from './aggregate.js';
+export type { BlockTag, CallOverrides, EthersLikeProvider, NativeBalanceMode } from './aggregate.js';
 export type { BatchOptions } from './batcher.js';
-export type { BoundCall, Call, FailableCall, Params, RawResult } from './call.js';
+export type { BoundCall, Call, FailableCall, FailureReason, Params, RawResult, Settled } from './call.js';
 //# sourceMappingURL=index.d.ts.map