@w3lib/solana-batch-call 0.6.0 → 0.7.0

package/dist/client.js

@@ -1,22 +1,10 @@
-import { base64 } from '@scure/base';
-import { getAssociatedTokenAddress, getMetadataAddress, isAddress } from './address.js';
-import { NATIVE_MINT, SOL_DECIMALS, SYSTEM_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID, clusterOfGenesis, } from './constants.js';
-import { formatUnits, parseMetaplexMetadata, parseMint, parseTokenAccount, parseTransferFeeConfig, } from './layout.js';
-import { AllNodesFailedError, HttpError, RpcError, isBehind } from './rpc.js';
-import { NetworkMismatchError, resolveSource } from './source.js';
-import { DEFAULT_TOKEN_FIELDS, } from './types.js';
-/** 节点高度不够时的重试间隔与总时长 */
-const BEHIND_RETRY_INTERVAL = 500;
-const BEHIND_RETRY_TIMEOUT = 10_000;
-const MAX_ACCOUNTS_PER_REQUEST = 100;
-/** 同时进行的 getMultipleAccounts 请求数上限 */
-const MAX_PARALLEL_ACCOUNT_REQUESTS = 3;
-/** #fetchAccounts 里没能读到（节点问题）的账户 */
-const FAILED = Symbol('failed');
-/** 可以降级处理的错误：网络 / HTTP 错误、节点限制（限频、需要 Key 等）、节点不在期望的网络上、所有节点都失败；其他（参数错误、程序 bug）照常抛出 */
-function isRecoverable(err) {
-    return err instanceof HttpError || (err instanceof RpcError && err.nodeFault) || err instanceof NetworkMismatchError || err instanceof AllNodesFailedError;
-}
+import { AccountReader, queryContext } from './accountReader.js';
+import { balancesFor, multiBalancesOf, ownerNftsOf, ownerTokensOf, solBalancesOf } from './balances.js';
+import { GENESIS_HASHES, NATIVE_MINT, SYSTEM_PROGRAM_ID, clusterOfGenesis } from './constants.js';
+import { clientSourceConfigs, resolveSource } from './source.js';
+import { nftOwnersOf, nftsOf, tokensOf } from './tokenDetails.js';
+// 代币信息缓存在 tokenMeta.ts；这里继续导出（公开 API 和测试的引用路径不变）
+export { exportTokenMetaCache, importTokenMetaCache, persistTokenMetaCache, resetTokenMetaCache } from './tokenMeta.js';
 /** 查询带上取消：已取消时不执行；中途取消时立即 reject，查询本身继续（结果丢弃） */
 function abortable(signal, run) {
     if (!signal) {
@@ -33,233 +21,30 @@ function abortable(signal, run) {
             .finally(() => signal.removeEventListener('abort', onAbort));
     });
 }
-function sleep(ms, signal) {
-    return new Promise((resolve, reject) => {
-        if (signal?.aborted) {
-            reject(signal.reason);
-            return;
-        }
-        const timer = setTimeout(() => {
-            signal?.removeEventListener('abort', onAbort);
-            resolve();
-        }, ms);
-        const onAbort = () => {
-            clearTimeout(timer);
-            reject(signal?.reason);
-        };
-        signal?.addEventListener('abort', onAbort, { once: true });
-    });
-}
-const TOKEN_PROGRAMS = [TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID];
-// 用 Map：普通对象会让 'constructor' 等原型上的名字通过校验
-const PROGRAM_ALIASES = new Map([
-    ['spl', TOKEN_PROGRAM_ID],
-    ['token-2022', TOKEN_2022_PROGRAM_ID],
-    [TOKEN_PROGRAM_ID, TOKEN_PROGRAM_ID],
-    [TOKEN_2022_PROGRAM_ID, TOKEN_2022_PROGRAM_ID],
-]);
-/**
- * 简写 / 程序地址转成程序地址（顺序固定为 Token、Token-2022）。
- * 不认识的值和空数组报错，避免拼错或漏选时悄悄过滤掉全部代币
- */
-function resolvePrograms(tokenPrograms) {
-    if (tokenPrograms === undefined) {
-        return TOKEN_PROGRAMS;
-    }
-    if (tokenPrograms.length === 0) {
-        throw new Error(`tokenPrograms is empty (expected 'spl' and / or 'token-2022'; omit it to include both)`);
-    }
-    const wanted = new Set(tokenPrograms.map((value) => {
-        const program = PROGRAM_ALIASES.get(value);
-        if (!program) {
-            throw new Error(`Unknown token program: ${value} (expected 'spl', 'token-2022' or a token program id)`);
-        }
-        return program;
-    }));
-    return TOKEN_PROGRAMS.filter((program) => wanted.has(program));
-}
-/** 所属程序已知且不在允许范围内 */
-function isExcluded(tokenProgram, allowed) {
-    return tokenProgram !== undefined && !allowed.includes(tokenProgram);
-}
-/** 按 mint 汇总后精度 0、数量 1 的持仓视为 NFT（ownerTokens 与 ownerNfts 共用） */
-function isNftHolding(holding) {
-    return holding.decimals === 0 && holding.amount === 1n;
-}
-const TOKEN_STANDARDS = [
-    'NonFungible',
-    'FungibleAsset',
-    'Fungible',
-    'NonFungibleEdition',
-    'ProgrammableNonFungible',
-    'ProgrammableNonFungibleEdition',
-];
-// 代币信息缓存（按 网络 + mint）：decimals / 所属程序不会变，永久缓存；
-// name / symbol 来自可修改的元数据，缓存 1 小时。条目数有上限，超出时淘汰最早写入的
-const NAME_TTL = 60 * 60 * 1000;
-const MAX_CACHED_TOKENS = 50_000;
-const tokenMetaCache = new Map();
-// 已知数据为空的钱包账户（系统账户或不存在）：ATA 模式下和代币账户放在同一个请求里读，不必单独带 dataSlice 多发一个请求。
-// 按 scope + 地址记，最多 1 万个，超出淘汰最早的；读到不是系统账户（如程序账户）时移除
-const MAX_SMALL_OWNERS = 10_000;
-const smallOwners = new Set();
-function isSmallOwner(scope, owner) {
-    return smallOwners.has(`${scope}:${owner}`);
-}
-/** 根据只读 lamports 的结果判断钱包账户是否“数据为空”（dataSlice 读不到数据长度，按所属程序判断：系统账户的数据为空） */
-function learnOwner(scope, owner, account) {
-    const key = `${scope}:${owner}`;
-    if (account === null || account.owner === SYSTEM_PROGRAM_ID) {
-        smallOwners.delete(key);
-        smallOwners.add(key);
-        if (smallOwners.size > MAX_SMALL_OWNERS) {
-            smallOwners.delete(smallOwners.values().next().value);
-        }
-    }
-    else {
-        smallOwners.delete(key);
-    }
-}
 let clientIds = 0;
-/** 缓存写入监听（persistTokenMetaCache 用） */
-const cacheWriteListeners = new Set();
-/** 测试用：清空代币信息缓存 */
-export function resetTokenMetaCache() {
-    smallOwners.clear();
-    tokenMetaCache.clear();
-}
-const SHARED_SCOPES = new Set(['mainnet', 'devnet', 'testnet']);
 /**
- * 导出代币信息缓存（decimals / 所属程序 / name / symbol），用于持久化：刷新页面后导入，不必重查 decimals。
- * 只导出按网络共享的条目（自定义节点且没指定 cluster 的客户端，缓存只在该客户端内，不导出）。
- * maxEntries：只导出最近写入的这么多条
- */
-export function exportTokenMetaCache(maxEntries = Number.POSITIVE_INFINITY) {
-    const entries = [];
-    for (const [key, meta] of tokenMetaCache) {
-        if (SHARED_SCOPES.has(key.slice(0, key.indexOf(':')))) {
-            const { programUnverified: _, ...exported } = meta;
-            entries.push([key, exported]);
-        }
-    }
-    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) {
-        const meta = validMeta(entry);
-        if (meta && !tokenMetaCache.has(entry[0])) {
-            tokenMetaCache.set(entry[0], meta);
-            if (tokenMetaCache.size > MAX_CACHED_TOKENS) {
-                tokenMetaCache.delete(tokenMetaCache.keys().next().value);
-            }
-        }
-    }
-}
-function validMeta(entry) {
-    if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== 'string') {
-        return null;
-    }
-    const [key, raw] = entry;
-    const colon = key.indexOf(':');
-    if (!SHARED_SCOPES.has(key.slice(0, colon)) || !isAddress(key.slice(colon + 1)) || !raw || typeof raw !== 'object') {
-        return null;
-    }
-    const meta = {};
-    if (typeof raw.decimals === 'number' && Number.isInteger(raw.decimals) && raw.decimals >= 0 && raw.decimals <= 255)
-        meta.decimals = raw.decimals;
-    if (raw.tokenProgram === TOKEN_PROGRAM_ID || raw.tokenProgram === TOKEN_2022_PROGRAM_ID) {
-        meta.tokenProgram = raw.tokenProgram;
-        meta.programUnverified = true;
-    }
-    // 写入时间只接受有限值、且不晚于现在（留 1 分钟时钟误差）：未来的时间会让 name / symbol 永不过期，截到现在
-    if (typeof raw.namesAt === 'number' &&
-        Number.isFinite(raw.namesAt) &&
-        (typeof raw.name === 'string' || raw.name === null) &&
-        (typeof raw.symbol === 'string' || raw.symbol === null)) {
-        meta.name = raw.name;
-        meta.symbol = raw.symbol;
-        meta.namesAt = Math.min(raw.namesAt, Date.now());
-    }
-    return Object.keys(meta).length ? meta : null;
-}
-/**
- * 把代币信息缓存持久化到同步的键值存储（如 localStorage）：调用时读入，之后缓存有写入就防抖（约 1 秒）整体写回。
- * 返回停止函数（会立即写回还没写的变化）。读到格式不对的数据会丢弃；写入失败（如存储已满）忽略。
+ * Solana 批量读取客户端。
  *
  * ```ts
- * persistTokenMetaCache(localStorage) // 刷新页面后 decimals 不必重查
+ * const sol = new SolanaClient()                                  // 内置公共节点（mainnet）
+ * const sol = new SolanaClient('https://my-rpc.example')          // 自己的节点
+ * const sol = new SolanaClient([connection, 'https://backup…'])   // web3.js Connection + 备用节点
+ *
+ * await sol.balances(owner, [NATIVE_MINT, USDC])
+ * await sol.tokens([USDC, PYUSD], { fields: ['name', 'symbol', 'decimals', 'supply'] })
  * ```
+ *
+ * 同一 tick 内发起的 RPC 调用会合并成一个 JSON-RPC 批量请求；账户读取按 100 个一组用 getMultipleAccounts。
+ * 这里只有薄的公开方法：账户读取管线在 accountReader.ts，余额在 balances.ts，代币详情 / NFT 在 tokenDetails.ts，代币信息缓存在 tokenMeta.ts
  */
-export function persistTokenMetaCache(store, options = {}) {
-    const key = options.key ?? 'w3lib:solana-token-meta';
-    const maxEntries = options.maxEntries ?? 5000;
-    try {
-        const raw = store.getItem(key);
-        if (raw) {
-            importTokenMetaCache(JSON.parse(raw));
-        }
-    }
-    catch {
-        // 格式不对：丢弃
-    }
-    let timer = null;
-    const write = () => {
-        timer = null;
-        try {
-            store.setItem(key, JSON.stringify(exportTokenMetaCache(maxEntries)));
-        }
-        catch {
-            // 存储已满等：忽略
-        }
-    };
-    const onWrite = () => {
-        if (!timer) {
-            timer = setTimeout(write, 1000);
-            timer.unref?.();
-        }
-    };
-    cacheWriteListeners.add(onWrite);
-    return () => {
-        cacheWriteListeners.delete(onWrite);
-        if (timer) {
-            clearTimeout(timer);
-            write();
-        }
-    };
-}
-/** jsonParsed 结果里的一个代币账户：节点解析好的直接取；退回 base64 的自己解析（这时没有 decimals，要从 mint 账户补） */
-function readTokenEntry(entry) {
-    const data = entry.account?.data;
-    if (data && !Array.isArray(data) && typeof data === 'object') {
-        const info = data.parsed?.info;
-        if (info?.mint && info.tokenAmount?.decimals !== undefined) {
-            return { mint: info.mint, amount: BigInt(info.tokenAmount.amount ?? '0'), decimals: info.tokenAmount.decimals };
-        }
-    }
-    const encoded = Array.isArray(data) ? (data[1] === 'base64' ? data[0] : undefined) : typeof data === 'string' ? data : undefined;
-    if (encoded === undefined) {
-        return null;
-    }
-    try {
-        const parsed = parseTokenAccount(base64.decode(encoded));
-        return { mint: parsed.mint, amount: parsed.amount, decimals: undefined };
-    }
-    catch {
-        return null;
-    }
-}
 export class SolanaClient {
     transport;
     #genesis;
     #cluster;
     #commitment;
     #nativeMints;
-    #scopeId;
+    #reader;
+    #rc;
     constructor(provider, config = {}) {
         const resolved = resolveSource(provider, config.cluster ?? (provider === undefined ? 'mainnet' : undefined), config);
         this.transport = resolved.transport;
@@ -267,8 +52,12 @@ export class SolanaClient {
         this.#cluster = config.cluster ?? (provider === undefined ? 'mainnet' : undefined);
         this.#commitment = config.commitment ?? 'confirmed';
         this.#nativeMints = new Set(config.nativeMints ?? [NATIVE_MINT, SYSTEM_PROGRAM_ID]);
+        this.#reader = new AccountReader(this.transport, this.#commitment);
+        // 登记节点配置：写操作的 sendRpc 按同样的网络和节点选项解析
+        clientSourceConfigs.set(this, { cluster: this.#cluster, options: config, genesis: () => this.#cluster ? Promise.resolve(GENESIS_HASHES[this.#cluster]) : this.#genesis() });
         // 网络已知时按网络共享缓存；未知（自定义节点且没指定 cluster）时缓存只在本客户端内使用，避免不同网络串数据
-        this.#scopeId = this.#cluster ?? `client-${++clientIds}`;
+        const scope = this.#cluster ?? `client-${++clientIds}`;
+        this.#rc = { reader: this.#reader, scope, nativeMints: this.#nativeMints, commitment: this.#commitment };
     }
     /** 节点所在网络（按创世区块哈希识别）；不是 mainnet / devnet / testnet 时为 null */
     async getCluster() {
@@ -284,336 +73,39 @@ export class SolanaClient {
     }
     /** 直接发 JSON-RPC 调用（同样参与自动合并与故障切换） */
     request(method, params, options = {}) {
-        return abortable(options.signal, () => this.transport.request(method, params));
-    }
-    /**
-     * 发一个读账户类的请求：params 最后一项是配置对象，传了 minContextSlot 时带上；
-     * 节点高度不够（所有节点都落后）时每 500ms 重试，最多约 10 秒；记录返回的 context.slot（取最小值）
-     */
-    async #call(ctx, method, params) {
-        const last = params[params.length - 1];
-        const sent = ctx.minContextSlot === undefined ? params : [...params.slice(0, -1), { ...last, minContextSlot: ctx.minContextSlot }];
-        const started = Date.now();
-        for (;;) {
-            try {
-                const res = await this.transport.request(method, sent);
-                const slot = res?.context?.slot;
-                if (typeof slot === 'number') {
-                    ctx.slot = ctx.slot === undefined ? slot : Math.min(ctx.slot, slot);
-                }
-                return res;
-            }
-            catch (err) {
-                if (ctx.minContextSlot === undefined || !isBehind(err) || Date.now() - started + BEHIND_RETRY_INTERVAL > BEHIND_RETRY_TIMEOUT) {
-                    throw err;
-                }
-                await sleep(BEHIND_RETRY_INTERVAL, ctx.signal);
-            }
-        }
-    }
-    /** 结果项带上 slot（传了 withSlot / minContextSlot，且这次查询发了请求时） */
-    #attachSlot(items, ctx, options) {
-        if ((!options.withSlot && options.minContextSlot === undefined) || ctx.slot === undefined) {
-            return items;
-        }
-        const slot = ctx.slot;
-        return items.map((item) => ({ ...item, slot }));
+        const { signal } = options;
+        return abortable(signal, () => this.#reader.send(method, params, signal));
     }
     /**
      * 批量读取账户（getMultipleAccounts，按 100 个一组，去重），结果与 addresses 一一对应。
      * 账户不存在或地址非法时为 null。
      */
     accounts(addresses, options = {}) {
-        return abortable(options.signal, () => this.#accounts(addresses, { signal: options.signal, minContextSlot: options.minContextSlot }));
-    }
-    async #accounts(addresses, ctx) {
-        const fetched = await this.#fetchAccounts(addresses, false, ctx);
-        return addresses.map((address) => fetched.get(address) ?? null);
-    }
-    /**
-     * 只读 lamports（主币余额）：getMultipleAccounts 带 dataSlice { offset: 0, length: 0 }，不读回账户数据——
-     * 钱包可能是数据很大的程序账户（上百 KB），整份读回会拖慢甚至超时。结果与 addresses 一一对应，账户不存在或地址非法时为 null
-     */
-    async #lamports(addresses, ctx) {
-        const [fetched] = await this.#fetchGroups([{ addresses, lamportsOnly: true }], false, ctx);
-        return addresses.map((address) => fetched?.get(address)?.lamports ?? null);
-    }
-    /** getMultipleAccounts（读账户数据）：见 #fetchGroups */
-    async #fetchAccounts(addresses, tolerant, ctx) {
-        const [fetched] = await this.#fetchGroups([{ addresses, lamportsOnly: false }], tolerant, ctx);
-        return fetched;
-    }
-    /**
-     * getMultipleAccounts：每组去重、按 100 个一组拆分，所有组的请求一起排队，最多同时 3 个（避免大批量时触发节点限频）。
-     * lamportsOnly 的组带 dataSlice（长度 0，对同一请求里的所有账户生效，所以只要 lamports 的账户要单独成组）。
-     * tolerant 为 true 时，某个请求因节点问题（网络、限频等）失败不抛错：该请求的账户标记为 FAILED，并且不再发后面的请求（节点已经在限频了）；
-     * 否则第一个错误抛出，后面的请求也不再发。结果按组返回
-     */
-    async #fetchGroups(groups, tolerant, ctx) {
-        const chunks = [];
-        groups.forEach(({ addresses, lamportsOnly }, group) => {
-            const unique = [...new Set(addresses.filter((a) => isAddress(a)))];
-            for (let i = 0; i < unique.length; i += MAX_ACCOUNTS_PER_REQUEST) {
-                chunks.push({ group, addresses: unique.slice(i, i + MAX_ACCOUNTS_PER_REQUEST), lamportsOnly });
-            }
-        });
-        const results = groups.map(() => new Map());
-        let aborted = false;
-        for (let i = 0; i < chunks.length; i += MAX_PARALLEL_ACCOUNT_REQUESTS) {
-            const wave = chunks.slice(i, i + MAX_PARALLEL_ACCOUNT_REQUESTS);
-            // 已取消的查询不再发后面的请求
-            if (ctx.signal?.aborted) {
-                throw ctx.signal.reason;
-            }
-            if (aborted) {
-                wave.forEach((chunk) => chunk.addresses.forEach((address) => results[chunk.group]?.set(address, FAILED)));
-                continue;
-            }
-            // 同一批里的请求同时发出（合并成一个 JSON-RPC 批量请求）；一个失败时等这一批都结束再抛，后面的批次不再发
-            const settled = await Promise.allSettled(wave.map(async (chunk) => {
-                const result = results[chunk.group];
-                try {
-                    const res = await this.#call(ctx, 'getMultipleAccounts', [
-                        chunk.addresses,
-                        { encoding: 'base64', commitment: this.#commitment, ...(chunk.lamportsOnly ? { dataSlice: { offset: 0, length: 0 } } : {}) },
-                    ]);
-                    chunk.addresses.forEach((address, j) => result.set(address, toAccountInfo(address, res?.value?.[j] ?? null)));
-                }
-                catch (err) {
-                    if (!tolerant || !isRecoverable(err)) {
-                        throw err;
-                    }
-                    aborted = true;
-                    chunk.addresses.forEach((address) => result.set(address, FAILED));
-                }
-            }));
-            const failed = settled.find((r) => r.status === 'rejected');
-            if (failed) {
-                throw failed.reason;
-            }
-        }
-        return results;
+        return abortable(options.signal, () => this.#reader.accounts(addresses, queryContext(options)));
     }
     /** 批量查多个地址的 SOL 余额（getMultipleAccounts 只读 lamports、不读回账户数据；账户不存在视为 0） */
     solBalances(addresses, options = {}) {
-        return abortable(options.signal, async () => {
-            const ctx = this.#context(options);
-            const balances = await this.#lamports(addresses, ctx);
-            const list = addresses.map((address, i) => {
-                if (!isAddress(address)) {
-                    return { address, balance: '0', formatted: '0', success: false, error: 'invalid-address' };
-                }
-                const lamports = balances[i] ?? 0n;
-                return { address, balance: lamports.toString(), formatted: formatUnits(lamports, SOL_DECIMALS), success: true };
-            });
-            return this.#attachSlot(list, ctx, options);
-        });
+        return abortable(options.signal, () => solBalancesOf(this.#rc, addresses, options));
     }
-    #context(options) {
-        return { signal: options.signal, minContextSlot: options.minContextSlot };
-    }
-    /**
-     * 批量查余额（主币 SOL + SPL Token + Token-2022），返回原始余额、decimals 和换算后的数值。
-     *
-     * - 传 mints：本地推导 ATA，与 mint 账户一起用 getMultipleAccounts 读完，免费节点也能用；主币只读 lamports（dataSlice），另成一组同时发出
-     * - 传 mints 且 accounts: 'all'：每个代币按 mint 过滤查 getTokenAccountsByOwner，统计全部代币账户（含非 ATA）
-     * - 不传 mints（或 scan: true）：用 getTokenAccountsByOwner 扫描全部代币账户，返回所有余额大于 0 的代币
-     * - 失败项（success: false）带 error：invalid-address（mint 地址非法）/ not-found（mint 不存在）/ not-token（不是代币 mint）
-     * - tokenPrograms：只返回这些类型的代币，如 ['spl'] 不含 Token-2022（传了 mints 时，结果里去掉不符合的代币）
-     * - minContextSlot / withSlot：要求节点高度、返回读取时的 slot，见 SlotOptions
-     */
-    balances(owner, mints, options = {}) {
-        return abortable(options.signal, async () => {
-            if (!isAddress(owner)) {
-                throw new Error(`Invalid owner address: ${owner}`);
-            }
-            const ctx = this.#context(options);
-            const list = await this.#balances(ctx, owner, mints, options, resolvePrograms(options.tokenPrograms));
-            return this.#attachSlot(list, ctx, options);
-        });
-    }
-    #balances(ctx, owner, mints, options, programs) {
-        const withSymbol = options.symbol ?? false;
-        if (mints === undefined || options.scan) {
-            return this.#scanBalances(ctx, owner, mints, withSymbol, programs);
-        }
-        if (options.accounts === 'all') {
-            return this.#mintAccountBalances(ctx, owner, mints, withSymbol, programs);
-        }
-        return this.#ataBalances(ctx, [{ owner, mints }], withSymbol, programs).then((lists) => lists[0]);
+    balances(owner, mintsOrOptions, maybeOptions = {}) {
+        // null / undefined 按旧写法的“不传 mints”（扫描模式）处理
+        const objectForm = mintsOrOptions != null && !Array.isArray(mintsOrOptions);
+        const options = objectForm ? mintsOrOptions : (maybeOptions ?? {});
+        const mints = objectForm ? mintsOrOptions.mints : (mintsOrOptions ?? undefined);
+        return abortable(options.signal, () => balancesFor(this.#rc, owner, mints, options));
     }
     /**
      * 多个钱包一次查（如多钱包的持仓列表），结果与 queries 一一对应。
      * ATA 模式（默认）下所有钱包的账户合并成一次（按 100 个一组的）getMultipleAccounts；
      * scan / accounts: 'all' 时每个钱包各自查询（同一 tick 发出，合并成批量请求）。其他选项与 balances() 相同；
-     * withSlot 时所有钱包的结果带同一个 slot（整次查询的最小值）。任一 owner 非法时报错
+     * withSlot 时所有钱包的结果带同一个 slot（整次查询的最小值）。任一 owner 非法时抛 InvalidAddressError
      *
      * ```ts
      * await sol.multiBalances([{ owner: a, mints: [NATIVE_MINT, USDC] }, { owner: b, mints: [USDC] }])
      * ```
      */
     multiBalances(queries, options = {}) {
-        return abortable(options.signal, async () => {
-            for (const { owner } of queries) {
-                if (!isAddress(owner)) {
-                    throw new Error(`Invalid owner address: ${owner}`);
-                }
-            }
-            const programs = resolvePrograms(options.tokenPrograms);
-            const ctx = this.#context(options);
-            const lists = options.scan || options.accounts === 'all'
-                ? await Promise.all(queries.map(({ owner, mints }) => this.#balances(ctx, owner, mints, options, programs)))
-                : await this.#ataBalances(ctx, queries, options.symbol ?? false, programs);
-            return lists.map((list) => this.#attachSlot(list, ctx, options));
-        });
-    }
-    /** ATA 模式：所有钱包的 主币账户 / mint / 元数据 / ATA 一起读，结果按钱包分组 */
-    async #ataBalances(ctx, queries, withSymbol, allowed) {
-        const scope = this.#scope();
-        // 要数据的账户（mint、元数据、ATA）一组；钱包账户只要 lamports：已知是普通钱包（系统账户 / 不存在，数据为空）的
-        // 放进同一组（一个请求、同一个快照），其余（可能是数据很大的程序账户）单独一组带 dataSlice——同时发出，合并在同一个 JSON-RPC 批量请求里
-        const addresses = [];
-        const owners = [];
-        const plans = queries.map(({ owner, mints }) => mints.map((mint) => this.#ataPlan(scope, owner, mint, withSymbol, allowed, addresses, owners)));
-        const [dataMap, ownerMap] = await this.#fetchGroups([
-            { addresses, lamportsOnly: false },
-            { addresses: owners, lamportsOnly: true },
-        ], false, ctx);
-        // 记下钱包账户是否数据为空：单独读的按结果学习；已放进代币那组的，读到不再是系统账户（如被分配给程序）时移除，下次单独读
-        for (const owner of new Set(queries.map((q) => q.owner))) {
-            // null（账户不存在）也是结果，不能用 ?? 落到另一组
-            const account = ownerMap?.has(owner) ? ownerMap.get(owner) : dataMap?.get(owner);
-            if (account !== undefined && account !== FAILED) {
-                learnOwner(scope, owner, account);
-            }
-        }
-        const accounts = addresses.map((address) => dataMap?.get(address) ?? null);
-        const lamportsOf = (owner) => (ownerMap?.has(owner) ? ownerMap.get(owner) : dataMap?.get(owner))?.lamports ?? 0n;
-        return plans.map((plan) => plan.flatMap((item) => this.#ataResult(scope, item, accounts, lamportsOf, withSymbol, allowed)));
-    }
-    #ataPlan(scope, owner, mint, withSymbol, allowed, addresses, owners) {
-        if (this.#nativeMints.has(mint)) {
-            ;
-            (isSmallOwner(scope, owner) ? addresses : owners).push(owner);
-            return { kind: 'native', mint, owner };
-        }
-        if (!isAddress(mint)) {
-            return { kind: 'invalid', mint };
-        }
-        const meta = getMeta(scope, mint);
-        // 导入的缓存里的所属程序没确认过：按未知处理（记错时不会让余额恒为 0）
-        const program = meta.programUnverified ? undefined : meta.tokenProgram;
-        if (isExcluded(program, allowed)) {
-            return { kind: 'excluded', mint };
-        }
-        const needMint = meta.decimals === undefined || program === undefined || (withSymbol && meta.symbol === undefined);
-        // 所属程序未知时只推导允许的程序的 ATA，读到 mint 账户后再确认
-        const programs = program ? [program] : allowed;
-        return {
-            kind: 'token',
-            mint,
-            mintIndex: needMint ? addresses.push(mint) - 1 : -1,
-            metadataIndex: withSymbol && meta.symbol === undefined ? addresses.push(getMetadataAddress(mint)) - 1 : -1,
-            atas: programs.map((program) => ({ program, index: addresses.push(getAssociatedTokenAddress(owner, mint, program)) - 1 })),
-        };
-    }
-    #ataResult(scope, item, accounts, lamportsOf, withSymbol, allowed) {
-        if (item.kind === 'native') {
-            const lamports = lamportsOf(item.owner);
-            return [
-                withSymbolField({ token: item.mint, native: true, balance: lamports.toString(), decimals: SOL_DECIMALS, formatted: formatUnits(lamports, SOL_DECIMALS), tokenProgram: null, success: true }, withSymbol, 'SOL'),
-            ];
-        }
-        if (item.kind === 'excluded') {
-            return [];
-        }
-        if (item.kind === 'invalid') {
-            return [failedBalance(item.mint, 'invalid-address', null, withSymbol, null)];
-        }
-        const mintAccount = item.mintIndex === -1 ? null : (accounts[item.mintIndex] ?? null);
-        const meta = this.#learn(scope, item.mint, mintAccount, item.metadataIndex === -1 ? null : (accounts[item.metadataIndex] ?? null), item.metadataIndex !== -1 && item.mintIndex !== -1);
-        // 代币账户由哪个程序持有就是哪个；mint 账户的 owner 也能确定程序。
-        // 所属程序未知时推导了两个程序的 ATA，但一个 mint 只属于一个程序，另一个程序下不可能有这个 mint 的代币账户：找到就结束
-        let amount = 0n;
-        for (const ata of item.atas) {
-            const account = accounts[ata.index];
-            if (!account || account.owner !== ata.program) {
-                continue;
-            }
-            try {
-                amount = parseTokenAccount(account.data).amount;
-            }
-            catch {
-                continue; // 不是代币账户
-            }
-            if (meta.tokenProgram === undefined) {
-                setMeta(scope, item.mint, { tokenProgram: ata.program });
-                meta.tokenProgram = ata.program;
-            }
-            break;
-        }
-        // 读到 mint 账户后才知道是不允许的程序
-        if (isExcluded(meta.tokenProgram, allowed)) {
-            return [];
-        }
-        if (meta.decimals === undefined) {
-            // decimals 未知时一定读了 mint 账户：不存在 / 存在但不是 mint
-            return [failedBalance(item.mint, mintAccount ? 'not-token' : 'not-found', meta.tokenProgram ?? null, withSymbol, meta.symbol ?? null)];
-        }
-        return [
-            withSymbolField({
-                token: item.mint,
-                native: false,
-                balance: amount.toString(),
-                decimals: meta.decimals,
-                formatted: formatUnits(amount, meta.decimals),
-                tokenProgram: meta.tokenProgram ?? null,
-                success: true,
-            }, withSymbol, meta.symbol ?? null),
-        ];
-    }
-    /** 扫描持有人的 SOL 余额和全部代币账户（默认 Token + Token-2022，只请求 programs 里的程序），同一代币的多个账户合计 */
-    async #scanHoldings(ctx, owner, programs = TOKEN_PROGRAMS, withSymbol = false) {
-        const scope = this.#scope();
-        const [lamports, ...results] = await Promise.all([
-            this.#call(ctx, 'getBalance', [owner, { commitment: this.#commitment }]),
-            ...programs.map((programId) => this.#call(ctx, 'getTokenAccountsByOwner', [owner, { programId }, { encoding: 'jsonParsed', commitment: this.#commitment }])),
-        ]);
-        const entries = programs.flatMap((program, i) => (results[i]?.value ?? []).map((entry) => ({ program, entry })));
-        const held = await this.#collectHoldings(ctx, scope, entries, withSymbol);
-        return { sol: BigInt(lamports.value), held };
-    }
-    /**
-     * 把 getTokenAccountsByOwner（jsonParsed）的结果按 mint 汇总。节点解析不了、退回 base64 的账户自己解析，
-     * decimals 读 mint 账户补上（不丢弃，也不会把余额算成 0）；mint 读不到 decimals 时才跳过
-     */
-    async #collectHoldings(ctx, scope, entries, withSymbol = false) {
-        const read = entries.flatMap(({ program, entry }) => {
-            const token = readTokenEntry(entry);
-            return token ? [{ ...token, program: entry.account?.owner || program }] : [];
-        });
-        read.forEach(({ mint, decimals, program }) => decimals !== undefined && program !== undefined && setMeta(scope, mint, { decimals, tokenProgram: program }));
-        // 缺 decimals 或所属程序（节点没给账户 owner）的读 mint 账户补上；需要 symbol 时一起读，后面不必再读一遍
-        const unknown = [
-            ...new Set(read.filter((t) => getMeta(scope, t.mint).decimals === undefined || (t.program === undefined && getMeta(scope, t.mint).tokenProgram === undefined)).map((t) => t.mint)),
-        ];
-        if (unknown.length) {
-            // 补读 mint 不受 minContextSlot 约束、不计入扫描的 slot（decimals / 所属程序不会因为刚成交而变化）；
-            // 节点问题时不让整次扫描失败，读不到的代币跳过
-            await this.#loadMeta({ signal: ctx.signal }, scope, unknown, withSymbol, true);
-        }
-        const held = new Map();
-        for (const { mint, amount, program: entryProgram } of read) {
-            const meta = getMeta(scope, mint);
-            const decimals = meta.decimals;
-            const program = entryProgram ?? (meta.programUnverified ? undefined : meta.tokenProgram);
-            if (decimals === undefined || program === undefined) {
-                continue;
-            }
-            const prev = held.get(mint);
-            held.set(mint, { amount: (prev?.amount ?? 0n) + amount, decimals, program, accounts: (prev?.accounts ?? 0) + 1 });
-        }
-        return held;
+        return abortable(options.signal, () => multiBalancesOf(this.#rc, queries, options));
     }
     /**
      * 列出持有人拥有的全部代币（SOL 在第一位），带 name / symbol，适合做资产列表。
@@ -626,158 +118,7 @@ export class SolanaClient {
      * - withSlot 的 slot 只算余额扫描（元数据读取不计入）
      */
     ownerTokens(owner, options = {}) {
-        return abortable(options.signal, async () => {
-            if (!isAddress(owner)) {
-                throw new Error(`Invalid owner address: ${owner}`);
-            }
-            const { metadata = true, includeNative = true, includeZero = false, includeNfts = false } = options;
-            const scope = this.#scope();
-            const ctx = this.#context(options);
-            const { sol, held } = await this.#scanHoldings(ctx, owner, resolvePrograms(options.tokenPrograms), metadata);
-            const scanSlot = ctx.slot;
-            // Wrapped SOL 是独立的代币账户（需要 unwrap 才是 SOL），资产列表里单独列出（native: false）
-            const tokens = [...held].filter(([, h]) => (includeZero || h.amount > 0n) && (includeNfts || !isNftHolding(h)));
-            // 元数据不受 minContextSlot 约束（不会因为刚成交而变化）
-            const failures = metadata ? await this.#loadMeta({ signal: options.signal }, scope, tokens.map(([mint]) => mint), true, true) : new Map();
-            const list = tokens.map(([mint, h]) => {
-                const item = {
-                    token: mint,
-                    native: false,
-                    balance: h.amount.toString(),
-                    decimals: h.decimals,
-                    formatted: formatUnits(h.amount, h.decimals),
-                    tokenProgram: h.program,
-                    accounts: h.accounts,
-                    success: true,
-                };
-                if (!metadata) {
-                    return item;
-                }
-                const meta = getMeta(scope, mint);
-                const status = failures.get(mint) === 'failed' ? 'failed' : meta.name == null && meta.symbol == null ? 'missing' : 'ok';
-                return { ...item, name: meta.name ?? null, symbol: meta.symbol ?? null, metadataStatus: status };
-            });
-            if (includeNative) {
-                const sol_ = { token: NATIVE_MINT, native: true, balance: sol.toString(), decimals: SOL_DECIMALS, formatted: formatUnits(sol, SOL_DECIMALS), tokenProgram: null, accounts: 1, success: true };
-                list.unshift(metadata ? { ...sol_, name: 'Solana', symbol: 'SOL', metadataStatus: 'ok' } : sol_);
-            }
-            return this.#attachSlot(list, { slot: scanSlot }, options);
-        });
-    }
-    async #scanBalances(ctx, owner, mints, withSymbol, allowed) {
-        const scope = this.#scope();
-        // held 里只有允许的程序的代币
-        const { sol, held } = await this.#scanHoldings(ctx, owner, allowed, withSymbol);
-        // Wrapped SOL（So111…112）默认按原生 SOL 处理：余额列表里只有一项 SOL，不再列出 wSOL 代币账户
-        // 第一项是主币：用 nativeMints 里的地址（nativeMints 不含 So111…112 时 wSOL 作为普通代币列出，不能再拿它当 SOL）
-        const nativeLead = this.#nativeMints.has(NATIVE_MINT) ? NATIVE_MINT : this.#nativeMints.values().next().value;
-        const targets = mints ?? [
-            ...(nativeLead === undefined ? [] : [nativeLead]),
-            ...[...held].filter(([mint, h]) => h.amount > 0n && !this.#nativeMints.has(mint)).map(([mint]) => mint),
-        ];
-        // 没持有的代币（拿不到 decimals）和缺 symbol 的代币：只读 mint / 元数据账户补上，不需要 ATA
-        const failures = await this.#loadMeta(ctx, scope, targets.filter((mint) => !this.#nativeMints.has(mint) && isAddress(mint)), withSymbol);
-        return targets.flatMap((mint) => {
-            if (this.#nativeMints.has(mint)) {
-                return [
-                    withSymbolField({ token: mint, native: true, balance: sol.toString(), decimals: SOL_DECIMALS, formatted: formatUnits(sol, SOL_DECIMALS), tokenProgram: null, success: true }, withSymbol, 'SOL'),
-                ];
-            }
-            return this.#heldBalance(scope, mint, held.get(mint), failures, withSymbol, allowed);
-        });
-    }
-    /**
-     * 指定 mints、统计全部代币账户：每个代币一次按 mint 过滤的 getTokenAccountsByOwner（同一 tick 发出，自动合并）。
-     * mint 不存在 / 不是代币时节点返回参数错误，按“没持有”处理，再由 #loadMeta 确认原因
-     */
-    async #mintAccountBalances(ctx, owner, mints, withSymbol, allowed) {
-        const scope = this.#scope();
-        // 导入的、未经链上确认的所属程序不用来排除代币（可能记错）：照常查询，从链上学到后再按程序过滤
-        const queried = [
-            ...new Set(mints.filter((mint) => {
-                const meta = getMeta(scope, mint);
-                return !this.#nativeMints.has(mint) && isAddress(mint) && (meta.programUnverified || !isExcluded(meta.tokenProgram, allowed));
-            })),
-        ];
-        const [lamports, ...results] = await Promise.all([
-            mints.some((mint) => this.#nativeMints.has(mint))
-                ? this.#call(ctx, 'getBalance', [owner, { commitment: this.#commitment }])
-                : Promise.resolve(null),
-            ...queried.map((mint) => this.#call(ctx, 'getTokenAccountsByOwner', [owner, { mint }, { encoding: 'jsonParsed', commitment: this.#commitment }]).catch((err) => {
-                // "Invalid param: could not find mint" 等参数错误：mint 不存在或不是代币；节点问题照常抛出
-                if (err instanceof RpcError && !err.nodeFault && err.code === -32602)
-                    return null;
-                throw err;
-            })),
-        ]);
-        const held = await this.#collectHoldings(ctx, scope, queried.flatMap((_, i) => (results[i]?.value ?? []).map((entry) => ({ program: entry.account?.owner, entry }))), withSymbol);
-        // 没持有的代币补 decimals（同时确认 mint 是否存在），需要时补 symbol
-        const failures = await this.#loadMeta(ctx, scope, queried, withSymbol);
-        const sol = BigInt(lamports?.value ?? 0);
-        return mints.flatMap((mint) => {
-            if (this.#nativeMints.has(mint)) {
-                return [
-                    withSymbolField({ token: mint, native: true, balance: sol.toString(), decimals: SOL_DECIMALS, formatted: formatUnits(sol, SOL_DECIMALS), tokenProgram: null, success: true }, withSymbol, 'SOL'),
-                ];
-            }
-            return this.#heldBalance(scope, mint, held.get(mint), failures, withSymbol, allowed);
-        });
-    }
-    /** 扫描类查询（scan / accounts: 'all'）里单个代币的结果；不允许的程序返回空数组 */
-    #heldBalance(scope, mint, h, failures, withSymbol, allowed) {
-        if (!isAddress(mint)) {
-            return [failedBalance(mint, 'invalid-address', null, withSymbol, null)];
-        }
-        const meta = getMeta(scope, mint);
-        if (!h) {
-            // 没持有（或属于不允许的程序）：余额为 0；decimals 来自 mint 账户
-            if (isExcluded(meta.tokenProgram, allowed)) {
-                return [];
-            }
-            if (meta.decimals === undefined) {
-                const failure = failures.get(mint);
-                return [failedBalance(mint, failure === 'not-token' ? 'not-token' : 'not-found', meta.tokenProgram ?? null, withSymbol, meta.symbol ?? null)];
-            }
-            return [withSymbolField({ token: mint, native: false, balance: '0', decimals: meta.decimals, formatted: '0', tokenProgram: meta.tokenProgram ?? null, success: true }, withSymbol, meta.symbol ?? null)];
-        }
-        if (isExcluded(h.program, allowed)) {
-            return [];
-        }
-        return [
-            withSymbolField({ token: mint, native: false, balance: h.amount.toString(), decimals: h.decimals, formatted: formatUnits(h.amount, h.decimals), tokenProgram: h.program, success: true }, withSymbol, meta.symbol ?? null),
-        ];
-    }
-    /**
-     * 补齐 decimals / 所属程序（以及需要时的 symbol / name）：只读缺的 mint 账户和元数据账户。
-     * 返回没能补上 decimals 的 mint 及原因：failed（tolerant 为 true 时的节点问题，信息保持未知、不写缓存）、not-found、not-token
-     */
-    async #loadMeta(ctx, scope, mints, withSymbol, tolerant = false) {
-        const plan = [...new Set(mints)].flatMap((mint) => {
-            const meta = getMeta(scope, mint);
-            const needSymbol = withSymbol && meta.symbol === undefined;
-            if (meta.decimals !== undefined && meta.tokenProgram !== undefined && !needSymbol) {
-                return [];
-            }
-            return [{ mint, metadata: needSymbol ? getMetadataAddress(mint) : null }];
-        });
-        const failures = new Map();
-        if (!plan.length) {
-            return failures;
-        }
-        const fetched = await this.#fetchAccounts(plan.flatMap(({ mint, metadata }) => (metadata ? [mint, metadata] : [mint])), tolerant, ctx);
-        for (const { mint, metadata } of plan) {
-            const mintAccount = fetched.get(mint);
-            const metadataAccount = metadata ? fetched.get(metadata) : null;
-            // mint 和元数据账户可能落在不同的请求里：任一个没读到都算失败，不能当成“没有元数据”缓存
-            if (mintAccount === FAILED || metadataAccount === FAILED) {
-                failures.set(mint, 'failed');
-                continue;
-            }
-            if (this.#learn(scope, mint, mintAccount ?? null, metadataAccount ?? null, metadata !== null).decimals === undefined) {
-                failures.set(mint, mintAccount ? 'not-token' : 'not-found');
-            }
-        }
-        return failures;
+        return abortable(options.signal, () => ownerTokensOf(this.#rc, owner, options));
     }
     /**
      * 批量查代币详情（一次 getMultipleAccounts），可以选择返回哪些字段。
@@ -785,308 +126,22 @@ export class SolanaClient {
      * transferFee：Token-2022 转账手续费，请求时会顺带发一次 getEpochInfo（同一个批量请求里）选出当前生效的配置
      */
     tokens(mints, options = {}) {
-        return abortable(options.signal, () => this.#tokens(mints, options));
-    }
-    async #tokens(mints, options) {
-        const fields = (options.fields ?? DEFAULT_TOKEN_FIELDS);
-        const wanted = new Set(fields);
-        const scope = this.#scope();
-        const ctx = { signal: options.signal };
-        const needsNames = wanted.has('name') || wanted.has('symbol') || wanted.has('uri');
-        const addresses = [];
-        const plan = mints.map((mint) => {
-            if (this.#nativeMints.has(mint) || !isAddress(mint)) {
-                return { mint, mintIndex: -1, metadataIndex: -1 };
-            }
-            const meta = getMeta(scope, mint);
-            // uri / supply / 权限 / 手续费不缓存，需要时总要读 mint；name / symbol 命中缓存时可以省掉元数据账户
-            const cachedOnly = !wanted.has('uri') &&
-                !wanted.has('supply') &&
-                !wanted.has('mintAuthority') &&
-                !wanted.has('freezeAuthority') &&
-                !wanted.has('transferFee') &&
-                (!wanted.has('decimals') || meta.decimals !== undefined) &&
-                (!wanted.has('tokenProgram') || meta.tokenProgram !== undefined) &&
-                (!wanted.has('name') || meta.name !== undefined) &&
-                (!wanted.has('symbol') || meta.symbol !== undefined);
-            if (cachedOnly) {
-                return { mint, mintIndex: -1, metadataIndex: -1 };
-            }
-            const namesCached = (!wanted.has('name') || meta.name !== undefined) && (!wanted.has('symbol') || meta.symbol !== undefined) && !wanted.has('uri');
-            return {
-                mint,
-                mintIndex: addresses.push(mint) - 1,
-                metadataIndex: needsNames && !namesCached ? addresses.push(getMetadataAddress(mint)) - 1 : -1,
-            };
-        });
-        const [accounts, epoch] = await Promise.all([
-            addresses.length ? this.#accounts(addresses, ctx) : Promise.resolve([]),
-            // 手续费按当前 epoch 选新 / 旧配置；和账户读取在同一个批量请求里
-            wanted.has('transferFee') && addresses.length
-                ? this.#call(ctx, 'getEpochInfo', [{ commitment: this.#commitment }]).then((res) => BigInt(res.epoch))
-                : Promise.resolve(null),
-        ]);
-        return plan.map(({ mint, mintIndex, metadataIndex }) => {
-            const native = this.#nativeMints.has(mint);
-            const values = native
-                ? { exists: true, name: 'Solana', symbol: 'SOL', uri: null, decimals: SOL_DECIMALS, supply: null, tokenProgram: null, mintAuthority: null, freezeAuthority: null, transferFee: null }
-                : this.#tokenValues(scope, mint, mintIndex === -1 ? null : (accounts[mintIndex] ?? null), metadataIndex === -1 ? null : (accounts[metadataIndex] ?? null), mintIndex !== -1, mintIndex !== -1 && metadataIndex !== -1, epoch);
-            const out = { address: mint, native };
-            let missing;
-            for (const field of fields) {
-                out[field] = values[field] ?? null;
-                // 权限为 null 表示没有权限、手续费为 null 表示没有手续费，都是有效值；主币没有 uri / supply / tokenProgram
-                const nullable = field === 'mintAuthority' || field === 'freezeAuthority' || field === 'transferFee' || (native && (field === 'uri' || field === 'supply' || field === 'tokenProgram'));
-                if (out[field] === null && !nullable) {
-                    missing ??= field;
-                }
-            }
-            if (wanted.has('supply')) {
-                const supply = values.supply;
-                const decimals = values.decimals;
-                out.supplyFormatted = supply === null || decimals === null ? null : formatUnits(BigInt(supply), decimals);
-            }
-            const error = native
-                ? undefined
-                : !isAddress(mint)
-                    ? 'invalid-address'
-                    : !values.exists
-                        ? accounts[mintIndex]
-                            ? 'not-token'
-                            : 'not-found'
-                        : missing
-                            ? 'missing-field'
-                            : undefined;
-            out.success = error === undefined;
-            if (error) {
-                out.error = error;
-                if (error === 'missing-field') {
-                    out.errorField = missing;
-                }
-            }
-            return out;
-        });
-    }
-    #tokenValues(scope, mint, mintAccount, metadataAccount, fetchedMint, lookedForNames, epoch) {
-        const meta = this.#learn(scope, mint, mintAccount, metadataAccount, lookedForNames);
-        const info = mintAccount ? safeParseMint(mintAccount) : null;
-        const uri = info?.metadata?.uri ?? (metadataAccount ? (safeParseMetaplex(metadataAccount)?.uri ?? null) : null);
-        const feeConfig = info && mintAccount?.owner === TOKEN_2022_PROGRAM_ID ? parseTransferFeeConfig(mintAccount.data) : null;
-        return {
-            // 读了 mint 账户就以它为准（不存在则 false）；没读说明请求的字段全部命中缓存
-            exists: fetchedMint ? info !== null : true,
-            name: meta.name ?? null,
-            symbol: meta.symbol ?? null,
-            uri,
-            decimals: meta.decimals ?? null,
-            supply: info ? info.supply.toString() : null,
-            tokenProgram: meta.tokenProgram ?? null,
-            mintAuthority: info?.mintAuthority ?? null,
-            freezeAuthority: info?.freezeAuthority ?? null,
-            transferFee: feeConfig ? toTransferFeeConfig(feeConfig.older, feeConfig.newer, epoch) : null,
-        };
+        return abortable(options.signal, () => tokensOf(this.#rc, mints, options));
     }
     /** 批量查 NFT 元数据（Metaplex；Token-2022 NFT 取 TokenMetadata 扩展），一次 getMultipleAccounts */
     nfts(mints, options = {}) {
-        return abortable(options.signal, async () => {
-            const scope = this.#scope();
-            const addresses = [];
-            const plan = mints.map((mint) => isAddress(mint) ? { mint, metadataIndex: addresses.push(getMetadataAddress(mint)) - 1, mintIndex: addresses.push(mint) - 1 } : { mint, metadataIndex: -1, mintIndex: -1 });
-            const accounts = addresses.length ? await this.#accounts(addresses, { signal: options.signal }) : [];
-            return plan.map(({ mint, metadataIndex, mintIndex }) => {
-                const metadataAccount = metadataIndex === -1 ? null : (accounts[metadataIndex] ?? null);
-                const mintAccount = mintIndex === -1 ? null : (accounts[mintIndex] ?? null);
-                this.#learn(scope, mint, mintAccount, metadataAccount, mintIndex !== -1);
-                const metaplex = metadataAccount ? safeParseMetaplex(metadataAccount) : null;
-                const ext = mintAccount ? (safeParseMint(mintAccount)?.metadata ?? null) : null;
-                if (!metaplex && !ext) {
-                    const error = mintIndex === -1 ? 'invalid-address' : !mintAccount ? 'not-found' : !safeParseMint(mintAccount) ? 'not-token' : 'no-metadata';
-                    return { mint, name: null, symbol: null, uri: null, collection: null, creators: [], sellerFeeBasisPoints: null, tokenStandard: null, isMutable: null, updateAuthority: null, success: false, error };
-                }
-                return {
-                    mint,
-                    name: ext?.name ?? metaplex?.name ?? null,
-                    symbol: ext?.symbol ?? metaplex?.symbol ?? null,
-                    uri: ext?.uri ?? metaplex?.uri ?? null,
-                    collection: metaplex?.collection ?? null,
-                    creators: metaplex?.creators ?? [],
-                    sellerFeeBasisPoints: metaplex?.sellerFeeBasisPoints ?? null,
-                    tokenStandard: metaplex?.tokenStandard == null ? null : (TOKEN_STANDARDS[metaplex.tokenStandard] ?? null),
-                    isMutable: metaplex?.isMutable ?? null,
-                    updateAuthority: metaplex?.updateAuthority ?? null,
-                    success: true,
-                };
-            });
-        });
+        return abortable(options.signal, () => nftsOf(this.#rc, mints, options));
     }
     /**
      * 批量查 NFT 持有人：getTokenLargestAccounts（合并成一个批量请求）+ 一次 getMultipleAccounts。
      * 节点拒绝的 mint（不存在 / 不是代币）在同一次 getMultipleAccounts 里读 mint 账户区分原因
      */
     nftOwners(mints, options = {}) {
-        return abortable(options.signal, async () => {
-            const ctx = { signal: options.signal };
-            const largest = await Promise.all(mints.map((mint) => isAddress(mint)
-                ? this.#call(ctx, 'getTokenLargestAccounts', [mint, { commitment: this.#commitment }])
-                    .then((res) => ({ tokenAccount: res.value.find((a) => a.amount !== '0')?.address ?? null, rejected: false }))
-                    .catch((err) => {
-                    // mint 不存在 / 不是代币：该项失败；节点问题照常抛出
-                    if (err instanceof RpcError && !err.nodeFault)
-                        return { tokenAccount: null, rejected: true };
-                    throw err;
-                })
-                : Promise.resolve({ tokenAccount: null, rejected: false })));
-            const toRead = largest.flatMap(({ tokenAccount, rejected }, i) => (tokenAccount ? [tokenAccount] : rejected ? [mints[i]] : []));
-            const accounts = toRead.length ? await this.#accounts(toRead, ctx) : [];
-            const byAddress = new Map(toRead.map((a, i) => [a, accounts[i] ?? null]));
-            return mints.map((mint, i) => {
-                const { tokenAccount, rejected } = largest[i] ?? { tokenAccount: null, rejected: false };
-                if (!isAddress(mint)) {
-                    return { mint, owner: null, tokenAccount: null, success: false, error: 'invalid-address' };
-                }
-                if (rejected) {
-                    return { mint, owner: null, tokenAccount: null, success: false, error: byAddress.get(mint) ? 'not-token' : 'not-found' };
-                }
-                const account = tokenAccount ? byAddress.get(tokenAccount) : null;
-                let owner = null;
-                if (account) {
-                    try {
-                        owner = parseTokenAccount(account.data).owner;
-                    }
-                    catch {
-                        owner = null;
-                    }
-                }
-                // 没有余额大于 0 的代币账户（供应量为 0 / 已销毁），或代币账户刚被关闭
-                return owner ? { mint, owner, tokenAccount, success: true } : { mint, owner: null, tokenAccount: null, success: false, error: 'no-holder' };
-            });
-        });
+        return abortable(options.signal, () => nftOwnersOf(this.#rc, mints, options));
     }
     /** 查某地址持有的全部 NFT（扫描代币账户：数量 1、精度 0），再批量读元数据。需要支持 getTokenAccountsByOwner 的节点 */
     ownerNfts(owner, options = {}) {
-        return abortable(options.signal, async () => {
-            if (!isAddress(owner)) {
-                throw new Error(`Invalid owner address: ${owner}`);
-            }
-            const { held } = await this.#scanHoldings({ signal: options.signal }, owner);
-            const mints = [...held].filter(([, h]) => isNftHolding(h)).map(([mint]) => mint);
-            return mints.length ? (await this.nfts(mints, options)).filter((nft) => nft.success) : [];
-        });
-    }
-    #scope() {
-        return this.#scopeId;
+        return abortable(options.signal, () => ownerNftsOf(this.#rc, owner, options));
     }
-    /**
-     * 从 mint 账户 / 元数据账户里学到的信息写入缓存，返回合并后的结果。
-     * lookedForNames：本次同时读了 mint 和元数据账户，都没有 name / symbol 时记为“确认没有”（null），之后不再重查
-     */
-    #learn(scope, mint, mintAccount, metadataAccount, lookedForNames = false) {
-        const update = {};
-        const info = mintAccount ? safeParseMint(mintAccount) : null;
-        if (info && mintAccount) {
-            update.decimals = info.decimals;
-            update.tokenProgram = mintAccount.owner;
-            if (info.metadata) {
-                update.name = info.metadata.name;
-                update.symbol = info.metadata.symbol;
-            }
-        }
-        if (metadataAccount && update.name === undefined) {
-            const metaplex = safeParseMetaplex(metadataAccount);
-            if (metaplex) {
-                update.name = metaplex.name;
-                update.symbol = metaplex.symbol;
-            }
-        }
-        if (lookedForNames && info && update.name === undefined) {
-            update.name = null;
-            update.symbol = null;
-        }
-        setMeta(scope, mint, update);
-        return getMeta(scope, mint);
-    }
-}
-function toTransferFee(fee) {
-    return { basisPoints: fee.basisPoints, maximumFee: fee.maximumFee.toString(), epoch: fee.epoch.toString() };
-}
-/** 当前生效的配置：epoch >= newer.epoch 用 newer，否则 older；不知道当前 epoch 时按 newer */
-function toTransferFeeConfig(older, newer, epoch) {
-    const current = epoch === null || epoch >= newer.epoch ? newer : older;
-    return { ...toTransferFee(current), older: toTransferFee(older), newer: toTransferFee(newer) };
-}
-function toAccountInfo(address, raw) {
-    if (!raw) {
-        return null;
-    }
-    const encoded = Array.isArray(raw.data) ? raw.data[0] : raw.data;
-    return {
-        address,
-        lamports: BigInt(raw.lamports),
-        owner: raw.owner,
-        data: base64.decode(encoded),
-        executable: raw.executable,
-    };
-}
-function safeParseMint(account) {
-    if (account.owner !== TOKEN_PROGRAM_ID && account.owner !== TOKEN_2022_PROGRAM_ID) {
-        return null;
-    }
-    try {
-        const mint = parseMint(account.data);
-        // 未初始化的 mint（创建和初始化分在两笔交易里，恰好在中间读到）：decimals 还是 0，不能当真、更不能永久缓存
-        return mint.isInitialized ? mint : null;
-    }
-    catch {
-        return null;
-    }
-}
-function safeParseMetaplex(account) {
-    try {
-        return parseMetaplexMetadata(account.data);
-    }
-    catch {
-        return null;
-    }
-}
-function getMeta(scope, mint) {
-    const cached = tokenMetaCache.get(`${scope}:${mint}`);
-    if (!cached) {
-        return {};
-    }
-    const { namesAt, ...meta } = cached;
-    if (namesAt === undefined || Date.now() - namesAt > NAME_TTL) {
-        delete meta.name;
-        delete meta.symbol;
-    }
-    return meta;
-}
-function setMeta(scope, mint, meta) {
-    const defined = Object.fromEntries(Object.entries(meta).filter(([, v]) => v !== undefined));
-    if (Object.keys(defined).length === 0) {
-        return;
-    }
-    if ('name' in defined || 'symbol' in defined) {
-        defined.namesAt = Date.now();
-    }
-    const key = `${scope}:${mint}`;
-    const merged = { ...tokenMetaCache.get(key), ...defined };
-    if ('tokenProgram' in defined && !defined.programUnverified) {
-        delete merged.programUnverified; // 从链上学到了所属程序
-    }
-    tokenMetaCache.delete(key); // 重新插入，保持“最近写入在后”的顺序
-    tokenMetaCache.set(key, merged);
-    if (tokenMetaCache.size > MAX_CACHED_TOKENS) {
-        tokenMetaCache.delete(tokenMetaCache.keys().next().value);
-    }
-    for (const listener of cacheWriteListeners) {
-        listener();
-    }
-}
-function withSymbolField(balance, withSymbol, symbol) {
-    return withSymbol ? { ...balance, symbol } : balance;
-}
-/** 失败项：余额为 0，带原因 */
-function failedBalance(token, error, tokenProgram, withSymbol, symbol) {
-    return { ...withSymbolField({ token, native: false, balance: '0', decimals: 0, formatted: '0', tokenProgram, success: false }, withSymbol, symbol), error };
 }
 //# sourceMappingURL=client.js.map