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

package/dist/rpc.js

@@ -0,0 +1,295 @@
+/** 节点返回的 JSON-RPC 错误 */
+export class RpcError extends Error {
+    code;
+    data;
+    /** 是否是节点自身的限制（限频、需要 API Key、禁止访问等），换节点可能成功 */
+    nodeFault;
+    constructor(message, code, data) {
+        super(message);
+        this.name = 'RpcError';
+        this.code = code;
+        this.data = data;
+        this.nodeFault =
+            code === 403 ||
+                code === 429 ||
+                code === -32005 ||
+                /forbidden|blocked|personal token|api.?key|rate.?limit|too many|not allowed|unauthori[sz]ed|limit exceeded|disabled|not available|not supported/i.test(message);
+    }
+}
+/** HTTP 层错误（非 2xx、网络错误、超时） */
+export class HttpError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'HttpError';
+        this.status = status;
+    }
+}
+/** 是否是节点问题（应换节点重试）：除了确定性的 JSON-RPC 错误（如参数错误），其余都算 */
+export function isNodeFault(err) {
+    if (err instanceof RpcError) {
+        return err.nodeFault;
+    }
+    return true;
+}
+let nextId = 1;
+/** 批量请求被拒绝、可以降级为逐条请求的 HTTP 状态 */
+const BATCH_REJECTED_STATUS = new Set([400, 404, 405, 415, 422]);
+function isBatchLimitError(message) {
+    return !!message && /batch/i.test(message) && /more than \d+|too (large|many|big)|not (allowed|supported)|exceed/i.test(message);
+}
+/**
+ * 基于 fetch 的 JSON-RPC 传输：同一收集窗口内的调用合并成一个 JSON-RPC 批量请求。
+ * 节点不支持批量（返回非数组）或限制批量大小（如 drpc 免费档最多 3 条）时自动降级。
+ */
+export class HttpRpc {
+    url;
+    #timeout;
+    #headers;
+    #batchWait;
+    #retries;
+    #fetch;
+    #maxBatchSize;
+    #batch;
+    #queue = [];
+    #timer = null;
+    constructor(url, options = {}) {
+        this.url = url;
+        this.#timeout = options.timeout ?? 10_000;
+        this.#headers = { 'content-type': 'application/json', ...options.headers };
+        this.#maxBatchSize = Math.max(1, options.maxBatchSize ?? 20);
+        this.#batch = options.batch ?? true;
+        this.#batchWait = options.batchWait ?? 0;
+        this.#retries = Math.max(0, options.retries ?? 2);
+        this.#fetch = options.fetch ?? ((...args) => fetch(...args));
+    }
+    request(method, params = []) {
+        return new Promise((resolve, reject) => {
+            this.#queue.push({ method, params, resolve: resolve, reject });
+            if (!this.#batch || this.#queue.length >= this.#maxBatchSize) {
+                this.#flush();
+            }
+            else if (!this.#timer) {
+                this.#timer = setTimeout(() => this.#flush(), this.#batchWait);
+            }
+        });
+    }
+    #flush() {
+        if (this.#timer) {
+            clearTimeout(this.#timer);
+            this.#timer = null;
+        }
+        const queue = this.#queue;
+        this.#queue = [];
+        for (let i = 0; i < queue.length; i += this.#maxBatchSize) {
+            void this.#dispatch(queue.slice(i, i + this.#maxBatchSize));
+        }
+    }
+    async #dispatch(items) {
+        if (items.length === 1 || !this.#batch) {
+            await Promise.all(items.map((item) => this.#single(item)));
+            return;
+        }
+        const ids = items.map(() => nextId++);
+        let body;
+        try {
+            body = await this.#post(items.map((item, i) => ({ jsonrpc: '2.0', id: ids[i], method: item.method, params: item.params })));
+        }
+        catch (err) {
+            if (err instanceof HttpError && err.status === 413 && items.length > 1) {
+                // 请求体太大：批量减半后重发
+                this.#maxBatchSize = Math.max(1, Math.floor(items.length / 2));
+                await this.#redispatch(items);
+                return;
+            }
+            // 400 / 404 / 405 / 415 / 422 等：节点多半不接受批量请求，降级为逐条请求
+            // （401 / 403 / 429 / 5xx 是鉴权、限频或节点本身的问题，降级没有用，原样报错）
+            if (err instanceof HttpError && err.status !== undefined && BATCH_REJECTED_STATUS.has(err.status)) {
+                this.#disableBatch();
+                await Promise.all(items.map((item) => this.#single(item)));
+                return;
+            }
+            items.forEach((item) => item.reject(err));
+            return;
+        }
+        if (!Array.isArray(body)) {
+            const error = body?.error;
+            const rpcError = new RpcError(error?.message ?? 'Invalid JSON-RPC batch response', error?.code, error?.data);
+            // 限频 / 鉴权等节点问题：原样报错，不降级（降级成逐条请求只会让限频更严重）
+            if (rpcError.nodeFault) {
+                items.forEach((item) => item.reject(rpcError));
+                return;
+            }
+            // 其他（如 -32600 invalid request）：节点不支持批量，降级为逐条请求
+            this.#disableBatch();
+            await Promise.all(items.map((item) => this.#single(item)));
+            return;
+        }
+        const byId = new Map(body.map((res) => [res.id, res]));
+        const limited = body.find((res) => isBatchLimitError(res.error?.message));
+        if (limited) {
+            // 如 “Batch of more than 3 requests are not allowed”：按限制缩小批量后重发；
+            // 限制不小于当前批量（节点的上限判断有偏差）或解析不出数字时，降级为逐条请求，避免无限重发
+            const max = Number(/more than (\d+)/i.exec(limited.error?.message ?? '')?.[1]);
+            if (Number.isFinite(max) && max > 1 && max < items.length) {
+                this.#maxBatchSize = max;
+                await this.#redispatch(items);
+            }
+            else {
+                this.#disableBatch();
+                await Promise.all(items.map((item) => this.#single(item)));
+            }
+            return;
+        }
+        // 批量里个别调用被限频（JSON-RPC 429）：只把这些调用退避后单独重试
+        const limitedItems = [];
+        items.forEach((item, i) => {
+            const response = byId.get(ids[i]);
+            if (response?.error?.code === 429 && this.#retries > 0) {
+                limitedItems.push(item);
+            }
+            else {
+                settle(item, response);
+            }
+        });
+        if (limitedItems.length) {
+            await new Promise((r) => setTimeout(r, 500));
+            await Promise.all(limitedItems.map((item) => this.#single(item)));
+        }
+    }
+    /** 按当前的 maxBatchSize 重新分批发送（每批都比原来小，不会无限循环） */
+    async #redispatch(items) {
+        const size = this.#maxBatchSize;
+        const chunks = [];
+        for (let i = 0; i < items.length; i += size) {
+            chunks.push(items.slice(i, i + size));
+        }
+        await Promise.all(chunks.map((chunk) => this.#dispatch(chunk)));
+    }
+    async #single(item) {
+        try {
+            const body = (await this.#post({ jsonrpc: '2.0', id: nextId++, method: item.method, params: item.params }));
+            settle(item, body);
+        }
+        catch (err) {
+            item.reject(err);
+        }
+    }
+    #disableBatch() {
+        this.#batch = false;
+    }
+    async #post(payload) {
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                response = await this.#fetch(this.url, {
+                    method: 'POST',
+                    headers: this.#headers,
+                    body: JSON.stringify(payload),
+                    signal: this.#timeout > 0 && Number.isFinite(this.#timeout) ? AbortSignal.timeout(this.#timeout) : undefined,
+                });
+            }
+            catch (err) {
+                throw new HttpError(`Request to ${this.url} failed: ${err?.message ?? err}`);
+            }
+            if (response.status === 429 && attempt < this.#retries) {
+                await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
+                continue;
+            }
+            const text = await response.text();
+            let body;
+            try {
+                body = parseJson(text);
+            }
+            catch {
+                throw new HttpError(`Invalid JSON from ${this.url} (HTTP ${response.status})`, response.status);
+            }
+            // 非 2xx 但返回了 JSON-RPC 结构（如 403 Access forbidden、drpc 的 500 + 批量错误数组）：交给上层解析
+            if (!response.ok && !Array.isArray(body) && !body?.error) {
+                throw new HttpError(`HTTP ${response.status} from ${this.url}`, response.status);
+            }
+            // 有的节点限频时返回 HTTP 200 + JSON-RPC 错误码 429：同样退避重试
+            if (attempt < this.#retries && isRateLimited(body)) {
+                await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
+                continue;
+            }
+            return body;
+        }
+    }
+}
+// lamports 等 u64 以 JSON 数字返回，超过 2^53（约 900 万 SOL）时 JSON.parse 会丢精度：
+// 支持 JSON.parse source text access 的环境（Node 21+、新版浏览器）直接取原文；否则先把超长整数改成字符串再解析
+let sourceAccess;
+function parseJson(text) {
+    sourceAccess ??= (() => {
+        let supported = false;
+        JSON.parse('1', (_key, value, context) => {
+            supported = typeof context?.source === 'string';
+            return value;
+        });
+        return supported;
+    })();
+    if (sourceAccess) {
+        return JSON.parse(text, (_key, value, context) => typeof value === 'number' && !Number.isSafeInteger(value) && Number.isInteger(value) && context?.source ? context.source : value);
+    }
+    return JSON.parse(text.replace(/([:[,]\s*)(-?\d{16,})(?=\s*[,}\]])/g, '$1"$2"'));
+}
+function isRateLimited(body) {
+    const responses = (Array.isArray(body) ? body : [body]);
+    return responses.length > 0 && responses.every((res) => res?.error?.code === 429);
+}
+function settle(item, response) {
+    if (!response) {
+        item.reject(new HttpError('Missing response in JSON-RPC batch'));
+    }
+    else if (response.error) {
+        item.reject(new RpcError(response.error.message ?? 'JSON-RPC error', response.error.code, response.error.data));
+    }
+    else {
+        item.resolve(response.result);
+    }
+}
+/**
+ * 多节点故障切换：按顺序使用，节点问题（网络、超时、限频、需要 Key、403 等）换下一个；
+ * 参数错误等确定性错误直接抛出。出错的节点在冷却期内排到最后。
+ */
+export class FallbackRpc {
+    nodes;
+    #cooldown;
+    #failedAt;
+    constructor(nodes, options = {}) {
+        if (!nodes.length) {
+            throw new Error('FallbackRpc requires at least one node');
+        }
+        this.nodes = nodes;
+        this.#cooldown = options.cooldown ?? 30_000;
+        this.#failedAt = nodes.map(() => 0);
+    }
+    async request(method, params) {
+        let lastError;
+        for (const index of this.#order()) {
+            try {
+                const result = await this.nodes[index].request(method, params);
+                this.#failedAt[index] = 0;
+                return result;
+            }
+            catch (err) {
+                if (!isNodeFault(err)) {
+                    throw err;
+                }
+                this.#failedAt[index] = Date.now();
+                lastError = err;
+            }
+        }
+        throw lastError;
+    }
+    #order() {
+        const now = Date.now();
+        const healthy = [];
+        const cooling = [];
+        this.#failedAt.forEach((at, i) => (at && now - at < this.#cooldown ? cooling : healthy).push(i));
+        cooling.sort((a, b) => this.#failedAt[a] - this.#failedAt[b]);
+        return [...healthy, ...cooling];
+    }
+}
+//# sourceMappingURL=rpc.js.map

package/dist/rpc.js.map

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

package/dist/shortcuts.d.ts

@@ -0,0 +1,60 @@
+import { SolanaClient, type BalancesOptions, type ClientConfig, type OwnerTokensOptions, 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, { provider: 'https://my-rpc…' })  // 全部持仓：需要支持 getTokenAccountsByOwner 的节点
+ * ```
+ */
+export declare function getBalances(owner: string, mints?: readonly string[], options?: GetBalancesOptions): Promise<TokenBalance[]>;
+/** 批量查多个地址的 SOL 余额（一次 getMultipleAccounts） */
+export declare function getSolBalances(addresses: readonly string[], options?: ShortcutOptions): 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>[]>;
+/** 批量查 NFT 元数据（名称、uri、所属集合、版税、创作者等） */
+export declare function getNfts(mints: readonly string[], options?: ShortcutOptions): Promise<NftDetails[]>;
+/** 批量查 NFT 持有人 */
+export declare function getNftOwners(mints: readonly string[], options?: ShortcutOptions): Promise<NftOwner[]>;
+/** 查某地址持有的全部 NFT（需要支持 getTokenAccountsByOwner 的节点） */
+export declare function getOwnerNfts(owner: string, options?: ShortcutOptions): 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 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,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAA;AAChI,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;AAqFD,MAAM,WAAW,kBAAmB,SAAQ,eAAe,EAAE,eAAe;CAAG;AAE/E;;;;;;;;;;GAUG;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;AAED,8CAA8C;AAC9C,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAEjH;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,uCAAuC;AACvC,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAEtG;AAED,kBAAkB;AAClB,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAEzG;AAED,sDAAsD;AACtD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAEhG;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,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,136 @@
+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 的参数忽略 */
+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 : 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, { provider: 'https://my-rpc…' })  // 全部持仓：需要支持 getTokenAccountsByOwner 的节点
+ * ```
+ */
+export function getBalances(owner, mints, options = {}) {
+    const { client, own } = resolve(options, ['symbol', 'scan']);
+    return client.balances(owner, mints, own);
+}
+/** 批量查多个地址的 SOL 余额（一次 getMultipleAccounts） */
+export function getSolBalances(addresses, options = {}) {
+    return resolve(options).client.solBalances(addresses);
+}
+/**
+ * 批量查代币详情，字段可选（默认 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']);
+    return client.tokens(mints, { fields: own.fields });
+}
+/** 批量查 NFT 元数据（名称、uri、所属集合、版税、创作者等） */
+export function getNfts(mints, options = {}) {
+    return resolve(options).client.nfts(mints);
+}
+/** 批量查 NFT 持有人 */
+export function getNftOwners(mints, options = {}) {
+    return resolve(options).client.nftOwners(mints);
+}
+/** 查某地址持有的全部 NFT（需要支持 getTokenAccountsByOwner 的节点） */
+export function getOwnerNfts(owner, options = {}) {
+    return resolve(options).client.ownerNfts(owner);
+}
+/**
+ * 列出持有人拥有的全部代币（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']);
+    return client.ownerTokens(owner, own);
+}
+/** 测试用：按参数取（或创建）客户端，用于验证缓存复用（不在包的公开导出里） */
+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":"AAAA,OAAO,EAAE,YAAY,EAAwF,MAAM,aAAa,CAAA;AAahI,qEAAqE;AACrE,kCAAkC;AAClC,MAAM,UAAU,GAAG,EAAE,CAAA;AAOrB,MAAM,WAAW,GAAG,IAAI,GAAG,EAAuB,CAAA;AAElD,SAAS,UAAU,CAAO,GAAc,EAAE,GAAM,EAAE,KAAQ;IACxD,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IACnB,IAAI,GAAG,CAAC,IAAI,GAAG,UAAU,EAAE,CAAC;QAC1B,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAU,CAAC,CAAA;IAC1C,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,MAAoB;IACrC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,KAAc,EAAE,EAAE;YACrD,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;gBAChC,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAA;YACnC,CAAC;YACD,OAAO,KAAK,CAAA;QACd,CAAC,CAAC,CAAA;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,MAAmC;IACpD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,OAAO,MAAM,EAAE,CAAA;IACxB,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;IAC9F,CAAC;IACD,OAAO,MAAgB,CAAA;AACzB,CAAC;AAED,2DAA2D;AAC3D,SAAS,OAAO,CACd,OAAU,EACV,UAAwB,EAAE;IAE1B,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAA;IACvC,MAAM,GAAG,GAA4B,EAAE,CAAA;IACvC,MAAM,MAAM,GAA4B,EAAE,CAAA;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,CAAC;YAAA,CAAE,OAA6B,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;QAC7E,CAAC;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,QAAQ,EAAE,MAAsB,CAAC,EAAE,GAAG,EAAE,GAAiB,EAAE,CAAA;AACxF,CAAC;AAED,SAAS,SAAS,CAAC,MAAmC,EAAE,MAAoB;IAC1E,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAA;IAC7B,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAA;IAC7B,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjC,OAAO,IAAI,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACzC,CAAC;IACD,IAAI,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAChC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,GAAG,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI,OAAO,EAAE,EAAE,CAAA;QACxD,UAAU,CAAC,WAAW,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;IACrC,CAAC;IACD,IAAI,MAAM,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACxF,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACzC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,UAAU,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,CAAA;QACzC,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;QACjC,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAID;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,KAAyB,EAAE,UAA8B,EAAE;IACpG,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAA;IAC5D,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,CAAA;AAC3C,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,cAAc,CAAC,SAA4B,EAAE,UAA2B,EAAE;IACxF,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAA;AACvD,CAAC;AAID;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAiD,KAAwB,EAAE,UAA+B,EAAE;IACnI,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAA;IACpD,OAAO,MAAM,CAAC,MAAM,CAAI,KAAK,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAA;AACxD,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,OAAO,CAAC,KAAwB,EAAE,UAA2B,EAAE;IAC7E,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AAC5C,CAAC;AAED,kBAAkB;AAClB,MAAM,UAAU,YAAY,CAAC,KAAwB,EAAE,UAA2B,EAAE;IAClF,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;AACjD,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,UAA2B,EAAE;IACvE,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;AACjD,CAAC;AAID;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,UAAiC,EAAE;IAC/E,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC,CAAA;IACrG,OAAO,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;AACvC,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,oBAAoB,CAAC,OAAwB;IAC3D,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAA;AAChC,CAAC;AAED,kBAAkB;AAClB,MAAM,UAAU,gBAAgB;IAC9B,WAAW,CAAC,KAAK,EAAE,CAAA;AACrB,CAAC"}

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,CA0ChB"}