@w3lib/solana-batch-call 0.0.0-stage → 0.2.0

package/dist/shortcuts.d.ts

@@ -0,0 +1,93 @@
+import { SolanaClient, type BalanceQuery, type BalancesOptions, type ClientConfig, type OwnerTokensOptions, type RequestOptions, type SolBalancesOptions, type TokensOptions } from './client.js';
+import type { RpcSource } from './source.js';
+import type { DefaultTokenField, NftDetails, NftOwner, OwnedToken, SolBalance, TokenBalance, TokenDetails, TokenField } from './types.js';
+/** 各函数共用的节点参数 */
+export interface ShortcutOptions extends ClientConfig {
+    /**
+     * 节点：RPC URL、URL 数组（主节点 + 备用节点）、web3.js Connection、自定义传输（request(method, params)）。
+     * 不传则使用 cluster（默认 mainnet）的内置公共节点
+     */
+    provider?: RpcSource | readonly RpcSource[];
+}
+export interface GetBalancesOptions extends BalancesOptions, ShortcutOptions {
+}
+/**
+ * 批量查余额（SOL + SPL Token + Token-2022），返回原始余额、decimals 和换算后的数值。
+ *
+ * ```ts
+ * import { NATIVE_MINT, getBalances } from '@w3lib/solana-batch-call'
+ *
+ * await getBalances(owner, [NATIVE_MINT, USDC])                        // 指定代币：免费公共节点也能用
+ * await getBalances(owner, [NATIVE_MINT, USDC], { symbol: true })
+ * await getBalances(owner, undefined, { tokenPrograms: ['spl'] })            // 不含 Token-2022 代币
+ * await getBalances(owner, [USDC], { accounts: 'all' })                      // 算上非 ATA 账户：需要支持 getTokenAccountsByOwner 的节点
+ * await getBalances(owner, undefined, { provider: 'https://my-rpc…' })  // 全部持仓：需要支持 getTokenAccountsByOwner 的节点
+ * ```
+ */
+export declare function getBalances(owner: string, mints?: readonly string[], options?: GetBalancesOptions): Promise<TokenBalance[]>;
+/**
+ * 多个钱包一次查，结果与 queries 一一对应；ATA 模式下所有钱包合并成一次 getMultipleAccounts。参数同 getBalances。
+ *
+ * ```ts
+ * await getMultiBalances([{ owner: a, mints: [NATIVE_MINT, USDC] }, { owner: b, mints: [USDC] }])
+ * ```
+ */
+export declare function getMultiBalances(queries: readonly BalanceQuery[], options?: GetBalancesOptions): Promise<TokenBalance[][]>;
+export interface GetSolBalancesOptions extends SolBalancesOptions, ShortcutOptions {
+}
+/** 批量查多个地址的 SOL 余额（一次 getMultipleAccounts） */
+export declare function getSolBalances(addresses: readonly string[], options?: GetSolBalancesOptions): Promise<SolBalance[]>;
+export interface GetTokensOptions<F extends TokenField = DefaultTokenField> extends TokensOptions<F>, ShortcutOptions {
+}
+/**
+ * 批量查代币详情，字段可选（默认 name / symbol / decimals）。
+ *
+ * ```ts
+ * await getTokens([USDC, PYUSD], { fields: ['name', 'symbol', 'decimals', 'supply', 'tokenProgram'] })
+ * ```
+ */
+export declare function getTokens<const F extends TokenField = DefaultTokenField>(mints: readonly string[], options?: GetTokensOptions<F>): Promise<TokenDetails<F>[]>;
+export interface GetNftsOptions extends RequestOptions, ShortcutOptions {
+}
+/** 批量查 NFT 元数据（名称、uri、所属集合、版税、创作者等） */
+export declare function getNfts(mints: readonly string[], options?: GetNftsOptions): Promise<NftDetails[]>;
+/** 批量查 NFT 持有人 */
+export declare function getNftOwners(mints: readonly string[], options?: GetNftsOptions): Promise<NftOwner[]>;
+/** 查某地址持有的全部 NFT（需要支持 getTokenAccountsByOwner 的节点） */
+export declare function getOwnerNfts(owner: string, options?: GetNftsOptions): Promise<NftDetails[]>;
+export interface GetOwnerTokensOptions extends OwnerTokensOptions, ShortcutOptions {
+}
+/**
+ * 列出持有人拥有的全部代币（SOL 在第一位），带 name / symbol，适合做资产列表。
+ * 需要支持 getTokenAccountsByOwner 的节点。
+ *
+ * ```ts
+ * await getOwnerTokens(owner, { provider: 'https://my-rpc…' })
+ * // [{ token: NATIVE_MINT, native: true, name: 'Solana', symbol: 'SOL', formatted: '1.5', … }, { token: USDC, name: 'USD Coin', … }]
+ * ```
+ */
+export declare function getOwnerTokens(owner: string, options?: GetOwnerTokensOptions): Promise<OwnedToken[]>;
+export interface WatchBalancesOptions extends Omit<GetBalancesOptions, 'signal' | 'minContextSlot'> {
+    /** 轮询间隔（毫秒），默认 15000；多处订阅同一份时取最小的 */
+    interval?: number;
+    /** 第一次拿到结果、以及之后余额（balance）变化时调用；previous 是上一次通知的结果（第一次为 null） */
+    onChange: (balances: TokenBalance[], previous: TokenBalance[] | null) => void;
+    /** 某次轮询失败时调用（之后照常继续轮询） */
+    onError?: (err: unknown) => void;
+}
+/**
+ * 轮询余额，多处订阅同一个钱包时合并成一份轮询，只在余额变化时通知。返回取消订阅的函数；最后一个订阅者取消时停止轮询。
+ * 参数同 getBalances（不支持 signal / minContextSlot）；上一次请求没完成时不会发起下一次。
+ * 结果顺序按第一个订阅者传的 mints；新订阅者加入时如果已有结果，立即收到一次（previous 为 null）
+ *
+ * ```ts
+ * const stop = watchBalances(owner, [NATIVE_MINT, USDC], { interval: 10_000, onChange: (list) => render(list) })
+ * stop()
+ * ```
+ */
+export declare function watchBalances(owner: string, mints: readonly string[] | undefined, options: WatchBalancesOptions): () => void;
+/** 测试用：按参数取（或创建）客户端，用于验证缓存复用（不在包的公开导出里） */
+export declare function resolveClientForTest(options: ShortcutOptions): SolanaClient;
+/** 测试用：清空客户端缓存 */
+export declare function resetClientCache(): void;
+//# sourceMappingURL=shortcuts.d.ts.map

package/dist/shortcuts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcuts.d.ts","sourceRoot":"","sources":["../src/shortcuts.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EACnB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAEzI,iBAAiB;AACjB,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,GAAG,SAAS,SAAS,EAAE,CAAA;CAC5C;AAwFD,MAAM,WAAW,kBAAmB,SAAQ,eAAe,EAAE,eAAe;CAAG;AAE/E;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAG/H;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAG9H;AAED,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB,EAAE,eAAe;CAAG;AAErF,8CAA8C;AAC9C,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAGvH;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,UAAU,GAAG,iBAAiB,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC,EAAE,eAAe;CAAG;AAExH;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,CAAC,CAAC,SAAS,UAAU,GAAG,iBAAiB,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,gBAAgB,CAAC,CAAC,CAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAGjK;AAED,MAAM,WAAW,cAAe,SAAQ,cAAc,EAAE,eAAe;CAAG;AAE1E,uCAAuC;AACvC,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAGrG;AAED,kBAAkB;AAClB,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAGxG;AAED,sDAAsD;AACtD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAG/F;AAED,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB,EAAE,eAAe;CAAG;AAErF;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAGxG;AAED,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,kBAAkB,EAAE,QAAQ,GAAG,gBAAgB,CAAC;IACjG,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iEAAiE;IACjE,QAAQ,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI,KAAK,IAAI,CAAA;IAC7E,0BAA0B;IAC1B,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACjC;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,OAAO,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAuD5H;AA8DD,2CAA2C;AAC3C,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,YAAY,CAE3E;AAED,kBAAkB;AAClB,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/dist/shortcuts.js

@@ -0,0 +1,281 @@
+import { SolanaClient, } from './client.js';
+// 复用客户端：多次调用共享连接、批量合并与故障切换状态。按 “配置内容” 分组，组内 URL 按字符串、对象按引用（WeakMap）。
+// 配置里有函数（如自定义 fetch）或节点数组含对象时不缓存。
+const MAX_CACHED = 32;
+const clientCache = new Map();
+function setBounded(map, key, value) {
+    map.set(key, value);
+    if (map.size > MAX_CACHED) {
+        map.delete(map.keys().next().value);
+    }
+}
+function configKey(config) {
+    try {
+        return JSON.stringify(config, (_key, value) => {
+            if (typeof value === 'function') {
+                throw new Error('not comparable');
+            }
+            return value;
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function sourceKey(source) {
+    if (source === undefined) {
+        return 'default';
+    }
+    if (typeof source === 'string') {
+        return `url:${source}`;
+    }
+    if (Array.isArray(source)) {
+        return source.every((item) => typeof item === 'string') ? `urls:${source.join('\n')}` : null;
+    }
+    return source;
+}
+/**
+ * 拆出节点参数和函数自己的参数（ownKeys），其余作为客户端配置；值为 undefined 的参数忽略。
+ * signal 总是作为函数自己的参数（放进客户端配置会让每次调用都新建客户端）
+ */
+function resolve(options, ownKeys = []) {
+    const { provider, ...others } = options;
+    const own = {};
+    const config = {};
+    for (const [key, value] of Object.entries(others)) {
+        if (value !== undefined) {
+            ;
+            (ownKeys.includes(key) ? own : key === 'signal' ? {} : config)[key] = value;
+        }
+    }
+    return { client: getClient(provider, config), own: own };
+}
+function getClient(source, config) {
+    const cfg = configKey(config);
+    const key = sourceKey(source);
+    if (cfg === null || key === null) {
+        return new SolanaClient(source, config);
+    }
+    let group = clientCache.get(cfg);
+    if (!group) {
+        group = { byString: new Map(), byObject: new WeakMap() };
+        setBounded(clientCache, cfg, group);
+    }
+    let client = typeof key === 'string' ? group.byString.get(key) : group.byObject.get(key);
+    if (!client) {
+        client = new SolanaClient(source, config);
+        if (typeof key === 'string') {
+            setBounded(group.byString, key, client);
+        }
+        else {
+            group.byObject.set(key, client);
+        }
+    }
+    return client;
+}
+/**
+ * 批量查余额（SOL + SPL Token + Token-2022），返回原始余额、decimals 和换算后的数值。
+ *
+ * ```ts
+ * import { NATIVE_MINT, getBalances } from '@w3lib/solana-batch-call'
+ *
+ * await getBalances(owner, [NATIVE_MINT, USDC])                        // 指定代币：免费公共节点也能用
+ * await getBalances(owner, [NATIVE_MINT, USDC], { symbol: true })
+ * await getBalances(owner, undefined, { tokenPrograms: ['spl'] })            // 不含 Token-2022 代币
+ * await getBalances(owner, [USDC], { accounts: 'all' })                      // 算上非 ATA 账户：需要支持 getTokenAccountsByOwner 的节点
+ * await getBalances(owner, undefined, { provider: 'https://my-rpc…' })  // 全部持仓：需要支持 getTokenAccountsByOwner 的节点
+ * ```
+ */
+export function getBalances(owner, mints, options = {}) {
+    const { client, own } = resolve(options, BALANCE_KEYS);
+    return client.balances(owner, mints, own);
+}
+const BALANCE_KEYS = ['symbol', 'scan', 'accounts', 'tokenPrograms', 'signal', 'minContextSlot', 'withSlot'];
+/**
+ * 多个钱包一次查，结果与 queries 一一对应；ATA 模式下所有钱包合并成一次 getMultipleAccounts。参数同 getBalances。
+ *
+ * ```ts
+ * await getMultiBalances([{ owner: a, mints: [NATIVE_MINT, USDC] }, { owner: b, mints: [USDC] }])
+ * ```
+ */
+export function getMultiBalances(queries, options = {}) {
+    const { client, own } = resolve(options, BALANCE_KEYS);
+    return client.multiBalances(queries, own);
+}
+/** 批量查多个地址的 SOL 余额（一次 getMultipleAccounts） */
+export function getSolBalances(addresses, options = {}) {
+    const { client, own } = resolve(options, ['signal', 'minContextSlot', 'withSlot']);
+    return client.solBalances(addresses, own);
+}
+/**
+ * 批量查代币详情，字段可选（默认 name / symbol / decimals）。
+ *
+ * ```ts
+ * await getTokens([USDC, PYUSD], { fields: ['name', 'symbol', 'decimals', 'supply', 'tokenProgram'] })
+ * ```
+ */
+export function getTokens(mints, options = {}) {
+    const { client, own } = resolve(options, ['fields', 'signal']);
+    return client.tokens(mints, own);
+}
+/** 批量查 NFT 元数据（名称、uri、所属集合、版税、创作者等） */
+export function getNfts(mints, options = {}) {
+    const { client, own } = resolve(options, ['signal']);
+    return client.nfts(mints, own);
+}
+/** 批量查 NFT 持有人 */
+export function getNftOwners(mints, options = {}) {
+    const { client, own } = resolve(options, ['signal']);
+    return client.nftOwners(mints, own);
+}
+/** 查某地址持有的全部 NFT（需要支持 getTokenAccountsByOwner 的节点） */
+export function getOwnerNfts(owner, options = {}) {
+    const { client, own } = resolve(options, ['signal']);
+    return client.ownerNfts(owner, own);
+}
+/**
+ * 列出持有人拥有的全部代币（SOL 在第一位），带 name / symbol，适合做资产列表。
+ * 需要支持 getTokenAccountsByOwner 的节点。
+ *
+ * ```ts
+ * await getOwnerTokens(owner, { provider: 'https://my-rpc…' })
+ * // [{ token: NATIVE_MINT, native: true, name: 'Solana', symbol: 'SOL', formatted: '1.5', … }, { token: USDC, name: 'USD Coin', … }]
+ * ```
+ */
+export function getOwnerTokens(owner, options = {}) {
+    const { client, own } = resolve(options, ['metadata', 'includeNative', 'includeZero', 'includeNfts', 'tokenPrograms', 'signal', 'minContextSlot', 'withSlot']);
+    return client.ownerTokens(owner, own);
+}
+// 共享轮询：按客户端（同样的节点配置会复用同一个客户端）+ owner + mints（顺序无关）+ 影响结果的选项
+const watches = new WeakMap();
+/**
+ * 轮询余额，多处订阅同一个钱包时合并成一份轮询，只在余额变化时通知。返回取消订阅的函数；最后一个订阅者取消时停止轮询。
+ * 参数同 getBalances（不支持 signal / minContextSlot）；上一次请求没完成时不会发起下一次。
+ * 结果顺序按第一个订阅者传的 mints；新订阅者加入时如果已有结果，立即收到一次（previous 为 null）
+ *
+ * ```ts
+ * const stop = watchBalances(owner, [NATIVE_MINT, USDC], { interval: 10_000, onChange: (list) => render(list) })
+ * stop()
+ * ```
+ */
+export function watchBalances(owner, mints, options) {
+    const { onChange, onError, interval = 15_000, ...rest } = options;
+    if (!(interval > 0)) {
+        throw new Error(`Invalid interval: ${interval}`);
+    }
+    const { client, own } = resolve(rest, ['symbol', 'scan', 'accounts', 'tokenPrograms', 'withSlot']);
+    const key = JSON.stringify([
+        owner,
+        mints === undefined ? null : [...new Set(mints)].sort(),
+        own.symbol ?? false,
+        own.scan ?? false,
+        own.accounts ?? 'ata',
+        own.tokenPrograms === undefined ? null : [...own.tokenPrograms].sort(),
+        own.withSlot ?? false,
+    ]);
+    let group = watches.get(client);
+    if (!group) {
+        group = new Map();
+        watches.set(client, group);
+    }
+    let watch = group.get(key);
+    const watcher = { interval, onChange, onError };
+    if (!watch) {
+        watch = { client, owner, mints, options: own, watchers: new Set([watcher]), timer: null, running: false, stopped: false, last: null, lastKey: null };
+        group.set(key, watch);
+        poll(watch);
+    }
+    else {
+        watch.watchers.add(watcher);
+        const current = watch;
+        if (current.last) {
+            const last = current.last;
+            queueMicrotask(() => current.watchers.has(watcher) && safely(() => watcher.onChange(last, null)));
+        }
+        // 间隔变小：按新的间隔重新安排下一次
+        if (current.timer && interval < nextInterval(current, watcher)) {
+            clearTimeout(current.timer);
+            current.timer = null;
+            schedule(current);
+        }
+    }
+    const owned = watch;
+    const ownedGroup = group;
+    return () => {
+        if (!owned.watchers.delete(watcher) || owned.watchers.size) {
+            return;
+        }
+        owned.stopped = true;
+        if (owned.timer) {
+            clearTimeout(owned.timer);
+            owned.timer = null;
+        }
+        if (ownedGroup.get(key) === owned) {
+            ownedGroup.delete(key);
+        }
+    };
+}
+/** 除了 except 以外订阅者的最小间隔（用于判断新订阅者是否让间隔变小） */
+function nextInterval(watch, except) {
+    let min = Number.POSITIVE_INFINITY;
+    for (const w of watch.watchers) {
+        if (w !== except)
+            min = Math.min(min, w.interval);
+    }
+    return min;
+}
+function schedule(watch) {
+    if (watch.stopped || watch.timer || watch.running) {
+        return;
+    }
+    watch.timer = setTimeout(() => poll(watch), nextInterval(watch));
+}
+function poll(watch) {
+    watch.timer = null;
+    if (watch.running || watch.stopped) {
+        return;
+    }
+    watch.running = true;
+    watch.client
+        .balances(watch.owner, watch.mints, watch.options)
+        .then((balances) => {
+        // 只比较余额（slot 每次都会变）
+        const key = JSON.stringify(balances.map((b) => [b.token, b.balance, b.success]));
+        if (watch.stopped || key === watch.lastKey) {
+            return;
+        }
+        const previous = watch.last;
+        watch.last = balances;
+        watch.lastKey = key;
+        for (const w of [...watch.watchers]) {
+            safely(() => w.onChange(balances, previous));
+        }
+    }, (err) => {
+        if (!watch.stopped) {
+            for (const w of [...watch.watchers]) {
+                safely(() => w.onError?.(err));
+            }
+        }
+    })
+        .finally(() => {
+        watch.running = false;
+        schedule(watch);
+    });
+}
+function safely(fn) {
+    try {
+        fn();
+    }
+    catch {
+        // 订阅者的回调出错不影响轮询
+    }
+}
+/** 测试用：按参数取（或创建）客户端，用于验证缓存复用（不在包的公开导出里） */
+export function resolveClientForTest(options) {
+    return resolve(options).client;
+}
+/** 测试用：清空客户端缓存 */
+export function resetClientCache() {
+    clientCache.clear();
+}
+//# sourceMappingURL=shortcuts.js.map

package/dist/shortcuts.js.map

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

package/dist/source.d.ts

@@ -0,0 +1,35 @@
+import { type Cluster } from './constants.js';
+import { type FallbackOptions, type HttpRpcOptions, type RpcTransport } from './rpc.js';
+/**
+ * 节点来源（也可以传数组：主节点 + 备用节点）：
+ * - RPC URL 字符串
+ * - @solana/web3.js 的 Connection（使用其 rpcEndpoint）
+ * - 自定义传输：实现 `request(method, params)` 的对象（如包一层 @solana/kit 的 rpc）
+ */
+export type RpcSource = string | RpcTransport | {
+    rpcEndpoint: string;
+};
+export interface SourceOptions extends HttpRpcOptions, FallbackOptions {
+}
+export declare function genesisOf(transport: RpcTransport): Promise<string>;
+export declare class NetworkMismatchError extends Error {
+    constructor(expected: string, actual: string);
+}
+/**
+ * 校验节点所在的网络（创世区块哈希），避免把 devnet 的数据当成 mainnet 的返回。
+ * 校验与请求并行发出，不增加延迟；结果缓存，每个节点只多一次请求；识别失败时不拦截，并在一段时间内不再重试。
+ */
+export declare class NetworkCheckedRpc implements RpcTransport {
+    #private;
+    readonly inner: RpcTransport;
+    readonly expected: () => Promise<string>;
+    constructor(inner: RpcTransport, expected: () => Promise<string>);
+    request<T = unknown>(method: string, params?: readonly unknown[]): Promise<T>;
+}
+export interface ResolvedSource {
+    transport: RpcTransport;
+    /** 期望的创世区块哈希：指定了 cluster 时取对应值，否则取第一个响应节点的 */
+    genesis: () => Promise<string>;
+}
+export declare function resolveSource(source: RpcSource | readonly RpcSource[] | undefined, cluster: Cluster | undefined, options?: SourceOptions): ResolvedSource;
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAC/E,OAAO,EAAwB,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAA;AAE7G;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,YAAY,GAAG;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvE,MAAM,WAAW,aAAc,SAAQ,cAAc,EAAE,eAAe;CAAG;AAoBzE,wBAAgB,SAAS,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAalE;AAKD,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAI7C;AAED;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,YAAY;;IAIlD,QAAQ,CAAC,KAAK,EAAE,YAAY;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC;gBAD/B,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC;IAqBpC,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC;CAUpF;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,YAAY,CAAA;IACvB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CAC/B;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,GAAG,SAAS,SAAS,EAAE,GAAG,SAAS,EACpD,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,OAAO,GAAE,aAAkB,GAC1B,cAAc,CAwChB"}

package/dist/source.js

@@ -0,0 +1,124 @@
+import { DEFAULT_RPC_URLS, GENESIS_HASHES } from './constants.js';
+import { FallbackRpc, HttpRpc } from './rpc.js';
+/** @param failFast 多个自定义节点时为 true：不在单节点内重试 429，直接切到下一个节点 */
+function toTransport(source, options, failFast) {
+    if (typeof source === 'string') {
+        return new HttpRpc(source, { ...options, retries: failFast ? 0 : options.retries });
+    }
+    if (typeof source.request === 'function') {
+        return source;
+    }
+    const endpoint = source.rpcEndpoint;
+    if (typeof endpoint === 'string') {
+        return new HttpRpc(endpoint, { ...options, retries: failFast ? 0 : options.retries });
+    }
+    throw new Error('Unsupported RPC source: expected a URL, a web3.js Connection or an object with request(method, params)');
+}
+// 各节点的创世区块哈希缓存：失败（含超时）时删除，下次重试
+const genesisCache = new WeakMap();
+export function genesisOf(transport) {
+    let cached = genesisCache.get(transport);
+    if (!cached) {
+        const promise = transport.request('getGenesisHash');
+        genesisCache.set(transport, promise);
+        promise.catch(() => {
+            if (genesisCache.get(transport) === promise) {
+                genesisCache.delete(transport);
+            }
+        });
+        cached = promise;
+    }
+    return cached;
+}
+/** 识别失败后多久内不再重试（期间请求照常发出，不做校验） */
+const CHECK_RETRY_INTERVAL = 60_000;
+export class NetworkMismatchError extends Error {
+    constructor(expected, actual) {
+        super(`Network mismatch: expected genesis ${expected}, but the node is on ${actual}`);
+        this.name = 'NetworkMismatchError';
+    }
+}
+/**
+ * 校验节点所在的网络（创世区块哈希），避免把 devnet 的数据当成 mainnet 的返回。
+ * 校验与请求并行发出，不增加延迟；结果缓存，每个节点只多一次请求；识别失败时不拦截，并在一段时间内不再重试。
+ */
+export class NetworkCheckedRpc {
+    inner;
+    expected;
+    #checkFailedAt = 0;
+    constructor(inner, expected) {
+        this.inner = inner;
+        this.expected = expected;
+    }
+    async #check() {
+        if (this.#checkFailedAt && Date.now() - this.#checkFailedAt < CHECK_RETRY_INTERVAL) {
+            return;
+        }
+        let expected;
+        let actual;
+        try {
+            ;
+            [expected, actual] = await Promise.all([this.expected(), genesisOf(this.inner)]);
+        }
+        catch {
+            this.#checkFailedAt = Date.now();
+            return;
+        }
+        this.#checkFailedAt = 0;
+        if (expected !== actual) {
+            throw new NetworkMismatchError(expected, actual);
+        }
+    }
+    async request(method, params) {
+        const [checked, result] = await Promise.allSettled([this.#check(), this.inner.request(method, params)]);
+        if (checked.status === 'rejected') {
+            throw checked.reason;
+        }
+        if (result.status === 'rejected') {
+            throw result.reason;
+        }
+        return result.value;
+    }
+}
+export function resolveSource(source, cluster, options = {}) {
+    const isDefault = source === undefined;
+    const list = isDefault ? DEFAULT_RPC_URLS[cluster ?? 'mainnet'] : Array.isArray(source) ? source : [source];
+    if (!list.length) {
+        throw new Error('RPC source list is empty');
+    }
+    const multiple = list.length > 1;
+    // 内置节点保留 429 重试：浏览器里官方节点总是 403，实际只有 publicnode 一个可用节点
+    const raw = list.map((item) => toTransport(item, options, multiple && !isDefault));
+    let detecting = null;
+    const genesis = () => {
+        if (cluster) {
+            return Promise.resolve(GENESIS_HASHES[cluster]);
+        }
+        if (!detecting) {
+            const promise = (async () => {
+                let lastError;
+                for (const node of raw) {
+                    try {
+                        return await genesisOf(node);
+                    }
+                    catch (err) {
+                        lastError = err;
+                    }
+                }
+                throw lastError;
+            })();
+            detecting = promise;
+            promise.catch(() => {
+                if (detecting === promise)
+                    detecting = null;
+            });
+        }
+        return detecting;
+    };
+    // 内置节点本来就是按 cluster 选的，不校验；单个节点且没指定 cluster 时，期望值就是它自己，也不需要校验
+    const check = !isDefault && (multiple || cluster !== undefined);
+    const nodes = check ? raw.map((node) => new NetworkCheckedRpc(node, genesis)) : raw;
+    // 单个节点也包一层 FallbackRpc：统一 onRequest 事件和健康状态（单节点失败时抛原始错误）
+    return { transport: new FallbackRpc(nodes, options), genesis };
+}
+//# sourceMappingURL=source.js.map

package/dist/source.js.map

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