@w3lib/solana-batch-call 0.1.0 → 0.2.1

package/dist/client.js

@@ -1,18 +1,86 @@
 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 { formatAmount, parseMetaplexMetadata, parseMint, parseTokenAccount } from './layout.js';
-import { HttpError, RpcError } from './rpc.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）照常抛出 */
+/** 可以降级处理的错误：网络 / HTTP 错误、节点限制（限频、需要 Key 等）、节点不在期望的网络上、所有节点都失败；其他（参数错误、程序 bug）照常抛出 */
 function isRecoverable(err) {
-    return err instanceof HttpError || (err instanceof RpcError && err.nodeFault) || err instanceof NetworkMismatchError;
+    return err instanceof HttpError || (err instanceof RpcError && err.nodeFault) || err instanceof NetworkMismatchError || err instanceof AllNodesFailedError;
+}
+/** 查询带上取消：已取消时不执行；中途取消时立即 reject，查询本身继续（结果丢弃） */
+function abortable(signal, run) {
+    if (!signal) {
+        return run();
+    }
+    if (signal.aborted) {
+        return Promise.reject(signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        run()
+            .then(resolve, reject)
+            .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) {
@@ -31,25 +99,160 @@ const TOKEN_STANDARDS = [
 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;
+}
 /**
- * Solana 批量读取客户端。
+ * 把代币信息缓存持久化到同步的键值存储（如 localStorage）：调用时读入，之后缓存有写入就防抖（约 1 秒）整体写回。
+ * 返回停止函数（会立即写回还没写的变化）。读到格式不对的数据会丢弃；写入失败（如存储已满）忽略。
  *
  * ```ts
- * 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'] })
+ * persistTokenMetaCache(localStorage) // 刷新页面后 decimals 不必重查
  * ```
- *
- * 同一 tick 内发起的 RPC 调用会合并成一个 JSON-RPC 批量请求；账户读取按 100 个一组用 getMultipleAccounts。
  */
+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;
@@ -72,171 +275,337 @@ export class SolanaClient {
         return this.#cluster ?? clusterOfGenesis(await this.#genesis());
     }
     /** 直接发 JSON-RPC 调用（同样参与自动合并与故障切换） */
-    request(method, params) {
-        return this.transport.request(method, params);
+    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 }));
     }
     /**
      * 批量读取账户（getMultipleAccounts，按 100 个一组，去重），结果与 addresses 一一对应。
      * 账户不存在或地址非法时为 null。
      */
-    async accounts(addresses) {
-        const fetched = await this.#fetchAccounts(addresses, false);
+    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);
     }
     /**
-     * getMultipleAccounts：去重、按 100 个一组，最多同时 3 组（避免大批量时触发节点限频）。
-     * tolerant 为 true 时，某组因节点问题（网络、限频等）失败不抛错：该组标记为 FAILED，并且不再发后面的组（节点已经在限频了）。
+     * 只读 lamports（主币余额）：getMultipleAccounts 带 dataSlice { offset: 0, length: 0 }，不读回账户数据——
+     * 钱包可能是数据很大的程序账户（上百 KB），整份读回会拖慢甚至超时。结果与 addresses 一一对应，账户不存在或地址非法时为 null
      */
-    async #fetchAccounts(addresses, tolerant) {
-        const unique = [...new Set(addresses.filter((a) => isAddress(a)))];
+    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 = [];
-        for (let i = 0; i < unique.length; i += MAX_ACCOUNTS_PER_REQUEST) {
-            chunks.push(unique.slice(i, i + MAX_ACCOUNTS_PER_REQUEST));
-        }
-        const result = new Map();
+        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.flat().forEach((address) => result.set(address, FAILED));
+                wave.forEach((chunk) => chunk.addresses.forEach((address) => results[chunk.group]?.set(address, FAILED)));
                 continue;
             }
-            await Promise.all(wave.map(async (chunk) => {
+            // 同一批里的请求同时发出（合并成一个 JSON-RPC 批量请求）；一个失败时等这一批都结束再抛，后面的批次不再发
+            const settled = await Promise.allSettled(wave.map(async (chunk) => {
+                const result = results[chunk.group];
                 try {
-                    const res = await this.transport.request('getMultipleAccounts', [
-                        chunk,
-                        { encoding: 'base64', commitment: this.#commitment },
+                    const res = await this.#call(ctx, 'getMultipleAccounts', [
+                        chunk.addresses,
+                        { encoding: 'base64', commitment: this.#commitment, ...(chunk.lamportsOnly ? { dataSlice: { offset: 0, length: 0 } } : {}) },
                     ]);
-                    chunk.forEach((address, j) => result.set(address, toAccountInfo(address, res?.value?.[j] ?? null)));
+                    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.forEach((address) => result.set(address, FAILED));
+                    chunk.addresses.forEach((address) => result.set(address, FAILED));
                 }
             }));
+            const failed = settled.find((r) => r.status === 'rejected');
+            if (failed) {
+                throw failed.reason;
+            }
         }
-        return result;
+        return results;
     }
-    /** 批量查多个地址的 SOL 余额（一次 getMultipleAccounts；账户不存在视为 0） */
-    async solBalances(addresses) {
-        const accounts = await this.accounts(addresses);
-        return addresses.map((address, i) => {
-            if (!isAddress(address)) {
-                return { address, balance: '0', formatted: '0', success: false };
-            }
-            const lamports = accounts[i]?.lamports ?? 0n;
-            return { address, balance: lamports.toString(), formatted: formatAmount(lamports, SOL_DECIMALS), success: true };
+    /** 批量查多个地址的 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);
         });
     }
+    #context(options) {
+        return { signal: options.signal, minContextSlot: options.minContextSlot };
+    }
     /**
      * 批量查余额（主币 SOL + SPL Token + Token-2022），返回原始余额、decimals 和换算后的数值。
      *
-     * - 传 mints：本地推导 ATA，与主币账户、mint 账户一起用 getMultipleAccounts 一次读完，免费节点也能用
+     * - 传 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
      */
-    async balances(owner, mints, options = {}) {
-        if (!isAddress(owner)) {
-            throw new Error(`Invalid owner address: ${owner}`);
-        }
+    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(owner, mints, options.symbol ?? false);
+            return this.#scanBalances(ctx, owner, mints, withSymbol, programs);
+        }
+        if (options.accounts === 'all') {
+            return this.#mintAccountBalances(ctx, owner, mints, withSymbol, programs);
         }
-        return this.#ataBalances(owner, mints, options.symbol ?? false);
+        return this.#ataBalances(ctx, [{ owner, mints }], withSymbol, programs).then((lists) => lists[0]);
+    }
+    /**
+     * 多个钱包一次查（如多钱包的持仓列表），结果与 queries 一一对应。
+     * ATA 模式（默认）下所有钱包的账户合并成一次（按 100 个一组的）getMultipleAccounts；
+     * scan / accounts: 'all' 时每个钱包各自查询（同一 tick 发出，合并成批量请求）。其他选项与 balances() 相同；
+     * withSlot 时所有钱包的结果带同一个 slot（整次查询的最小值）。任一 owner 非法时报错
+     *
+     * ```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));
+        });
     }
-    async #ataBalances(owner, mints, withSymbol) {
+    /** ATA 模式：所有钱包的 主币账户 / mint / 元数据 / ATA 一起读，结果按钱包分组 */
+    async #ataBalances(ctx, queries, withSymbol, allowed) {
         const scope = this.#scope();
+        // 要数据的账户（mint、元数据、ATA）一组；钱包账户只要 lamports：已知是普通钱包（系统账户 / 不存在，数据为空）的
+        // 放进同一组（一个请求、同一个快照），其余（可能是数据很大的程序账户）单独一组带 dataSlice——同时发出，合并在同一个 JSON-RPC 批量请求里
         const addresses = [];
-        const plan = mints.map((mint) => {
-            if (this.#nativeMints.has(mint)) {
-                return { mint, native: true, owner: addresses.push(owner) - 1 };
+        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;
             }
-            if (!isAddress(mint)) {
-                return { mint, native: false, invalid: true };
+            try {
+                amount = parseTokenAccount(account.data).amount;
             }
-            const meta = getMeta(scope, mint);
-            const needMint = meta.decimals === undefined || meta.tokenProgram === undefined || (withSymbol && meta.symbol === undefined);
-            const programs = meta.tokenProgram ? [meta.tokenProgram] : [TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID];
-            return {
-                mint,
-                native: false,
-                meta,
-                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 })),
-            };
-        });
-        const accounts = await this.accounts(addresses);
-        return plan.map((item) => {
-            if (item.native) {
-                const lamports = accounts[item.owner]?.lamports ?? 0n;
-                return withSymbolField({ token: item.mint, native: true, balance: lamports.toString(), decimals: SOL_DECIMALS, formatted: formatAmount(lamports, SOL_DECIMALS), tokenProgram: null, success: true }, withSymbol, 'SOL');
-            }
-            if ('invalid' in item) {
-                return withSymbolField({ token: item.mint, native: false, balance: '0', decimals: 0, formatted: '0', tokenProgram: null, success: false }, 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 也能确定程序
-            let amount = 0n;
-            for (const ata of item.atas) {
-                const account = accounts[ata.index];
-                if (account && account.owner === ata.program) {
-                    try {
-                        amount = parseTokenAccount(account.data).amount;
-                        if (meta.tokenProgram === undefined) {
-                            setMeta(scope, item.mint, { tokenProgram: ata.program });
-                            meta.tokenProgram = ata.program;
-                        }
-                    }
-                    catch {
-                        // 不是代币账户
-                    }
-                }
+            catch {
+                continue; // 不是代币账户
             }
-            if (meta.decimals === undefined) {
-                return withSymbolField({ token: item.mint, native: false, balance: '0', decimals: 0, formatted: '0', tokenProgram: meta.tokenProgram ?? null, success: false }, withSymbol, meta.symbol ?? null);
+            if (meta.tokenProgram === undefined) {
+                setMeta(scope, item.mint, { tokenProgram: ata.program });
+                meta.tokenProgram = ata.program;
             }
-            return withSymbolField({
+            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: formatAmount(amount, meta.decimals),
+                formatted: formatUnits(amount, meta.decimals),
                 tokenProgram: meta.tokenProgram ?? null,
                 success: true,
-            }, withSymbol, meta.symbol ?? null);
-        });
+            }, withSymbol, meta.symbol ?? null),
+        ];
     }
-    /** 扫描持有人的 SOL 余额和全部代币账户（Token + Token-2022），同一代币的多个账户合计 */
-    async #scanHoldings(owner) {
+    /** 扫描持有人的 SOL 余额和全部代币账户（默认 Token + Token-2022，只请求 programs 里的程序），同一代币的多个账户合计 */
+    async #scanHoldings(ctx, owner, programs = TOKEN_PROGRAMS, withSymbol = false) {
         const scope = this.#scope();
-        const [lamports, ...programs] = await Promise.all([
-            this.transport.request('getBalance', [owner, { commitment: this.#commitment }]),
-            ...[TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID].map((programId) => this.transport.request('getTokenAccountsByOwner', [
-                owner,
-                { programId },
-                { encoding: 'jsonParsed', commitment: this.#commitment },
-            ])),
+        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();
-        [TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID].forEach((program, i) => {
-            for (const entry of programs[i]?.value ?? []) {
-                const info = entry.account?.data?.parsed?.info;
-                const mint = info?.mint;
-                const decimals = info?.tokenAmount?.decimals;
-                if (!mint || decimals === undefined) {
-                    continue;
-                }
-                const prev = held.get(mint);
-                const amount = BigInt(info?.tokenAmount?.amount ?? '0');
-                held.set(mint, { amount: (prev?.amount ?? 0n) + amount, decimals, program, accounts: (prev?.accounts ?? 0) + 1 });
-                setMeta(scope, mint, { decimals, tokenProgram: program });
+        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;
             }
-        });
-        return { sol: BigInt(lamports.value), held };
+            const prev = held.get(mint);
+            held.set(mint, { amount: (prev?.amount ?? 0n) + amount, decimals, program, accounts: (prev?.accounts ?? 0) + 1 });
+        }
+        return held;
     }
     /**
      * 列出持有人拥有的全部代币（SOL 在第一位），带 name / symbol，适合做资产列表。
@@ -245,66 +614,136 @@ export class SolanaClient {
      * - 默认不含 NFT（精度 0 且数量 1）和余额为 0 的代币账户（如已清空的 ATA），可用 includeNfts / includeZero 打开
      * - accounts 是该代币的代币账户数量；大于 1 时余额为所有账户的合计
      * - 顺序：SOL，然后 SPL Token 的代币，再然后 Token-2022 的代币（各自按节点返回的顺序；没有价格信息，不按价值排序）
+     * - tokenPrograms: ['spl'] 时不含 Token-2022 代币
+     * - withSlot 的 slot 只算余额扫描（元数据读取不计入）
      */
-    async ownerTokens(owner, options = {}) {
-        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 { sol, held } = await this.#scanHoldings(owner);
-        // Wrapped SOL 是独立的代币账户（需要 unwrap 才是 SOL），资产列表里单独列出（native: false）
-        const tokens = [...held].filter(([, h]) => (includeZero || h.amount > 0n) && (includeNfts || !isNftHolding(h)));
-        const failed = metadata ? await this.#loadMeta(scope, tokens.map(([mint]) => mint), true, true) : new Set();
-        const list = tokens.map(([mint, h]) => {
-            const item = {
-                token: mint,
-                native: false,
-                balance: h.amount.toString(),
-                decimals: h.decimals,
-                formatted: formatAmount(h.amount, h.decimals),
-                tokenProgram: h.program,
-                accounts: h.accounts,
-                success: true,
-            };
-            if (!metadata) {
-                return item;
+    ownerTokens(owner, options = {}) {
+        return abortable(options.signal, async () => {
+            if (!isAddress(owner)) {
+                throw new Error(`Invalid owner address: ${owner}`);
             }
-            const meta = getMeta(scope, mint);
-            const status = failed.has(mint) ? 'failed' : meta.name == null && meta.symbol == null ? 'missing' : 'ok';
-            return { ...item, name: meta.name ?? null, symbol: meta.symbol ?? null, metadataStatus: status };
+            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);
         });
-        if (includeNative) {
-            const sol_ = { token: NATIVE_MINT, native: true, balance: sol.toString(), decimals: SOL_DECIMALS, formatted: formatAmount(sol, SOL_DECIMALS), tokenProgram: null, accounts: 1, success: true };
-            list.unshift(metadata ? { ...sol_, name: 'Solana', symbol: 'SOL', metadataStatus: 'ok' } : sol_);
-        }
-        return list;
     }
-    async #scanBalances(owner, mints, withSymbol) {
+    async #scanBalances(ctx, owner, mints, withSymbol, allowed) {
         const scope = this.#scope();
-        const { sol, held } = await this.#scanHoldings(owner);
+        // held 里只有允许的程序的代币
+        const { sol, held } = await this.#scanHoldings(ctx, owner, allowed, withSymbol);
         // Wrapped SOL（So111…112）默认按原生 SOL 处理：余额列表里只有一项 SOL，不再列出 wSOL 代币账户
-        const targets = mints ?? [NATIVE_MINT, ...[...held].filter(([mint, h]) => h.amount > 0n && !this.#nativeMints.has(mint)).map(([mint]) => mint)];
+        // 第一项是主币：用 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
-        await this.#loadMeta(scope, targets.filter((mint) => !this.#nativeMints.has(mint) && isAddress(mint)), withSymbol);
-        return targets.map((mint) => {
+        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: formatAmount(sol, SOL_DECIMALS), tokenProgram: null, success: true }, withSymbol, 'SOL');
+                return [
+                    withSymbolField({ token: mint, native: true, balance: sol.toString(), decimals: SOL_DECIMALS, formatted: formatUnits(sol, SOL_DECIMALS), tokenProgram: null, success: true }, withSymbol, 'SOL'),
+                ];
             }
-            const h = held.get(mint);
-            if (!h) {
-                // 没持有：余额为 0；decimals 来自 mint 账户（mint 不存在时 success 为 false）
+            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 withSymbolField({ token: mint, native: false, balance: '0', decimals: meta.decimals ?? 0, formatted: '0', tokenProgram: meta.tokenProgram ?? null, success: meta.decimals !== undefined }, withSymbol, meta.symbol ?? null);
+                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 withSymbolField({ token: mint, native: false, balance: h.amount.toString(), decimals: h.decimals, formatted: formatAmount(h.amount, h.decimals), tokenProgram: h.program, success: true }, withSymbol, getMeta(scope, mint).symbol ?? null);
+            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 账户和元数据账户。
-     * tolerant 为 true 时节点问题不抛错，返回没能读到的 mint（这些代币的信息保持未知，不写缓存）。
+     * 返回没能补上 decimals 的 mint 及原因：failed（tolerant 为 true 时的节点问题，信息保持未知、不写缓存）、not-found、not-token
      */
-    async #loadMeta(scope, mints, withSymbol, tolerant = false) {
+    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;
@@ -313,31 +752,38 @@ export class SolanaClient {
             }
             return [{ mint, metadata: needSymbol ? getMetadataAddress(mint) : null }];
         });
-        const failed = new Set();
+        const failures = new Map();
         if (!plan.length) {
-            return failed;
+            return failures;
         }
-        const fetched = await this.#fetchAccounts(plan.flatMap(({ mint, metadata }) => (metadata ? [mint, metadata] : [mint])), tolerant);
+        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) {
-                failed.add(mint);
+                failures.set(mint, 'failed');
                 continue;
             }
-            this.#learn(scope, mint, mintAccount ?? null, metadataAccount ?? null, metadata !== null);
+            if (this.#learn(scope, mint, mintAccount ?? null, metadataAccount ?? null, metadata !== null).decimals === undefined) {
+                failures.set(mint, mintAccount ? 'not-token' : 'not-found');
+            }
         }
-        return failed;
+        return failures;
     }
     /**
      * 批量查代币详情（一次 getMultipleAccounts），可以选择返回哪些字段。
      * name / symbol / uri 优先取 Token-2022 TokenMetadata 扩展，其次 Metaplex 元数据。
+     * transferFee：Token-2022 转账手续费，请求时会顺带发一次 getEpochInfo（同一个批量请求里）选出当前生效的配置
      */
-    async tokens(mints, options = {}) {
+    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) => {
@@ -345,11 +791,12 @@ export class SolanaClient {
                 return { mint, mintIndex: -1, metadataIndex: -1 };
             }
             const meta = getMeta(scope, mint);
-            // uri / supply / 权限不缓存，需要时总要读 mint；name / symbol 命中缓存时可以省掉元数据账户
+            // 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) &&
@@ -364,35 +811,59 @@ export class SolanaClient {
                 metadataIndex: needsNames && !namesCached ? addresses.push(getMetadataAddress(mint)) - 1 : -1,
             };
         });
-        const accounts = addresses.length ? await this.accounts(addresses) : [];
+        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 }
-                : this.#tokenValues(scope, mint, mintIndex === -1 ? null : (accounts[mintIndex] ?? null), metadataIndex === -1 ? null : (accounts[metadataIndex] ?? null), mintIndex !== -1, mintIndex !== -1 && metadataIndex !== -1);
+                ? { 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 success = values.exists;
+            let missing;
             for (const field of fields) {
                 out[field] = values[field] ?? null;
-                // 权限为 null 表示没有权限，是有效值；主币没有 uri / supply / tokenProgram
-                const nullable = field === 'mintAuthority' || field === 'freezeAuthority' || (native && (field === 'uri' || field === 'supply' || field === 'tokenProgram'));
+                // 权限为 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) {
-                    success = false;
+                    missing ??= field;
                 }
             }
             if (wanted.has('supply')) {
                 const supply = values.supply;
                 const decimals = values.decimals;
-                out.supplyFormatted = supply === null || decimals === null ? null : formatAmount(BigInt(supply), 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;
+                }
             }
-            out.success = success;
             return out;
         });
     }
-    #tokenValues(scope, mint, mintAccount, metadataAccount, fetchedMint, lookedForNames = false) {
+    #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,
@@ -404,77 +875,95 @@ export class SolanaClient {
             tokenProgram: meta.tokenProgram ?? null,
             mintAuthority: info?.mintAuthority ?? null,
             freezeAuthority: info?.freezeAuthority ?? null,
+            transferFee: feeConfig ? toTransferFeeConfig(feeConfig.older, feeConfig.newer, epoch) : null,
         };
     }
     /** 批量查 NFT 元数据（Metaplex；Token-2022 NFT 取 TokenMetadata 扩展），一次 getMultipleAccounts */
-    async nfts(mints) {
-        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) : [];
-        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) {
-                return { mint, name: null, symbol: null, uri: null, collection: null, creators: [], sellerFeeBasisPoints: null, tokenStandard: null, isMutable: null, updateAuthority: null, success: false };
-            }
-            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,
-            };
+    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,
+                };
+            });
         });
     }
-    /** 批量查 NFT 持有人：getTokenLargestAccounts（合并成一个批量请求）+ 一次 getMultipleAccounts */
-    async nftOwners(mints) {
-        const largest = await Promise.all(mints.map((mint) => isAddress(mint)
-            ? this.transport
-                .request('getTokenLargestAccounts', [mint, { commitment: this.#commitment }])
-                .then((res) => res.value.find((a) => a.amount !== '0')?.address ?? null)
-                .catch((err) => {
-                // mint 不存在 / 不是代币：该项失败；节点问题照常抛出
-                if (err instanceof RpcError && !err.nodeFault)
-                    return null;
-                throw err;
-            })
-            : Promise.resolve(null)));
-        const tokenAccounts = largest.filter((a) => a !== null);
-        const accounts = tokenAccounts.length ? await this.accounts(tokenAccounts) : [];
-        const byAddress = new Map(tokenAccounts.map((a, i) => [a, accounts[i] ?? null]));
-        return mints.map((mint, i) => {
-            const tokenAccount = largest[i] ?? null;
-            const account = tokenAccount ? byAddress.get(tokenAccount) : null;
-            let owner = null;
-            if (account) {
-                try {
-                    owner = parseTokenAccount(account.data).owner;
+    /**
+     * 批量查 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' };
                 }
-                catch {
-                    owner = null;
+                if (rejected) {
+                    return { mint, owner: null, tokenAccount: null, success: false, error: byAddress.get(mint) ? 'not-token' : 'not-found' };
                 }
-            }
-            return { mint, owner, tokenAccount: owner ? tokenAccount : null, success: owner !== null };
+                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' };
+            });
         });
     }
     /** 查某地址持有的全部 NFT（扫描代币账户：数量 1、精度 0），再批量读元数据。需要支持 getTokenAccountsByOwner 的节点 */
-    async ownerNfts(owner) {
-        if (!isAddress(owner)) {
-            throw new Error(`Invalid owner address: ${owner}`);
-        }
-        const { held } = await this.#scanHoldings(owner);
-        const mints = [...held].filter(([, h]) => isNftHolding(h)).map(([mint]) => mint);
-        return mints.length ? (await this.nfts(mints)).filter((nft) => nft.success) : [];
+    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;
@@ -509,6 +998,14 @@ export class SolanaClient {
         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;
@@ -527,7 +1024,9 @@ function safeParseMint(account) {
         return null;
     }
     try {
-        return parseMint(account.data);
+        const mint = parseMint(account.data);
+        // 未初始化的 mint（创建和初始化分在两笔交易里，恰好在中间读到）：decimals 还是 0，不能当真、更不能永久缓存
+        return mint.isInitialized ? mint : null;
     }
     catch {
         return null;
@@ -563,13 +1062,23 @@ function setMeta(scope, mint, meta) {
     }
     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