@w3lib/solana-batch-call 0.6.0 → 0.7.0

package/dist/write/tracker.js

@@ -0,0 +1,129 @@
+import { sleep } from '../util.js';
+/**
+ * 统一轮询所有待确认的交易：一次 getSignatureStatuses 查全部（每 256 个一组），未确认的每两次轮询重发一次，blockhash 过期后再查一次历史确认没上链。
+ * 区块高度（getEpochInfo）不是每轮都查：记下上次查到的（高度, slot），之后用状态查询返回的 context.slot 估计高度的上限
+ * （高度每个 slot 最多加 1），估计值超过某笔交易的 lastValidBlockHeight 时才查，确认过期
+ */
+export class Tracker {
+    chain;
+    #watched = new Set();
+    #running = false;
+    /** 上次查到的区块高度和对应的 slot */
+    #anchor = null;
+    constructor(chain) {
+        this.chain = chain;
+    }
+    watch(signature, raw, lastValidBlockHeight) {
+        const { timeout = 120_000 } = this.chain.options;
+        return new Promise((resolve) => {
+            this.#watched.add({ signature, raw, lastValidBlockHeight, deadline: Date.now() + timeout, polls: 0, resolve });
+            if (!this.#running) {
+                this.#running = true;
+                void this.#loop();
+            }
+        });
+    }
+    /** 查交易状态；contextSlot 是各次响应里最小的 context.slot（节点的数据新到哪个 slot），响应没带时为 0 */
+    async #statuses(signatures, history) {
+        const found = new Map();
+        let contextSlot = Number.POSITIVE_INFINITY;
+        for (let i = 0; i < signatures.length; i += 256) {
+            const chunk = signatures.slice(i, i + 256);
+            const res = await this.chain.client.request('getSignatureStatuses', [
+                chunk,
+                { searchTransactionHistory: history },
+            ]);
+            contextSlot = Math.min(contextSlot, res.context?.slot ?? 0);
+            res.value.forEach((s, k) => s && found.set(chunk[k], s));
+        }
+        return { found, contextSlot };
+    }
+    #done(status) {
+        const level = status.confirmationStatus;
+        return this.chain.commitment === 'finalized' ? level === 'finalized' : level === 'confirmed' || level === 'finalized';
+    }
+    #settle(item, result) {
+        this.#watched.delete(item);
+        item.resolve(result);
+    }
+    /** 是否可能有交易过期了（需要查区块高度确认）：不知道当前高度、或状态查询没带 slot 时总是查 */
+    #mayHaveExpired(waiting, contextSlot) {
+        const known = waiting.filter((w) => Number.isFinite(w.lastValidBlockHeight));
+        if (!known.length) {
+            return false;
+        }
+        if (!this.#anchor || !(contextSlot > 0) || !Number.isFinite(contextSlot)) {
+            return true;
+        }
+        const highest = this.#anchor.height + Math.max(0, contextSlot - this.#anchor.slot);
+        return known.some((w) => highest > w.lastValidBlockHeight);
+    }
+    async #loop() {
+        const { pollInterval = 2_000, signal } = this.chain.options;
+        try {
+            while (this.#watched.size) {
+                await sleep(pollInterval, signal, false);
+                if (signal?.aborted) {
+                    ;
+                    [...this.#watched].forEach((w) => this.#settle(w, { kind: 'aborted' }));
+                    return;
+                }
+                const items = [...this.#watched];
+                try {
+                    const { found: statuses, contextSlot } = await this.#statuses(items.map((w) => w.signature), false);
+                    for (const item of items) {
+                        const status = statuses.get(item.signature);
+                        if (status && this.#done(status)) {
+                            this.#settle(item, { kind: 'landed', slot: status.slot, err: status.err });
+                        }
+                    }
+                    const waiting = items.filter((w) => this.#watched.has(w));
+                    if (waiting.length && this.#mayHaveExpired(waiting, contextSlot)) {
+                        // 区块高度和对应的 slot 一起取（同一个节点、同一个时刻）
+                        const epoch = await this.chain.client.request('getEpochInfo', [{ commitment: 'confirmed' }]);
+                        this.#anchor = { height: epoch.blockHeight, slot: epoch.absoluteSlot };
+                        const expired = waiting.filter((w) => epoch.blockHeight > w.lastValidBlockHeight);
+                        if (expired.length) {
+                            // 过期了：再查一次历史确认确实没上链。请求可能落到另一个节点（多节点 / 负载均衡），
+                            // 它的数据必须不早于看到过期的那个 slot，否则可能只是它还没看到这笔交易，这一轮先不判断
+                            const history = await this.#statuses(expired.map((w) => w.signature), true);
+                            const caughtUp = history.contextSlot >= epoch.absoluteSlot;
+                            for (const item of expired) {
+                                const status = history.found.get(item.signature);
+                                if (!status) {
+                                    if (!caughtUp)
+                                        continue;
+                                    this.#settle(item, { kind: 'expired' });
+                                }
+                                else if (this.#done(status)) {
+                                    this.#settle(item, { kind: 'landed', slot: status.slot, err: status.err });
+                                }
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // 节点暂时出错：下次再查
+                }
+                const now = Date.now();
+                for (const item of [...this.#watched]) {
+                    if (now >= item.deadline) {
+                        this.#settle(item, { kind: 'timeout' });
+                    }
+                    else if (++item.polls % 2 === 0) {
+                        // 每两次轮询重发一次（每笔都重发会让待确认交易多时很快触发节点限频）
+                        void this.chain.broadcast(item.raw).catch(() => { });
+                    }
+                }
+            }
+        }
+        finally {
+            this.#running = false;
+            if (this.#watched.size) {
+                this.#running = true;
+                void this.#loop();
+            }
+        }
+    }
+}
+//# sourceMappingURL=tracker.js.map

package/dist/write/tracker.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@w3lib/solana-batch-call",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Batched Solana reads: SOL / SPL / Token-2022 balances, token metadata, NFTs; batch transfer, collect and program calls (packed transactions, fee payer). Auto-batching JSON-RPC, getMultipleAccounts chunking, RPC failover. No Solana SDK dependency.",
   "keywords": [
     "solana",

package/src/accountReader.ts

@@ -0,0 +1,187 @@
+// 账户读取管线（getMultipleAccounts 分组 / 并发 / 重试）和查询上下文
+
+import { base64 } from '@scure/base'
+
+import { isAddress } from './address.js'
+import type { RequestOptions, SlotOptions } from './client.js'
+import type { AccountInfo } from './layout.js'
+import { AllNodesFailedError, HttpError, RpcError, isBehind, type RpcTransport } from './rpc.js'
+import { NetworkMismatchError } from './source.js'
+import type { Commitment } from './types.js'
+import { mapPool, sleep } from './util.js'
+
+/** 一次查询的上下文：取消、最低 slot，以及读到的 slot（各请求 context.slot 的最小值） */
+export interface QueryContext {
+  signal?: AbortSignal
+  minContextSlot?: number
+  slot?: number
+}
+
+/** 节点高度不够时的重试间隔与总时长 */
+const BEHIND_RETRY_INTERVAL = 500
+const BEHIND_RETRY_TIMEOUT = 10_000
+
+export const MAX_ACCOUNTS_PER_REQUEST = 100
+/** 同时进行的 getMultipleAccounts 请求数上限 */
+const MAX_PARALLEL_ACCOUNT_REQUESTS = 3
+/** fetchAccounts 里没能读到（节点问题）的账户 */
+export const FAILED = Symbol('failed')
+
+/** 可以降级处理的错误：网络 / HTTP 错误、节点限制（限频、需要 Key 等）、节点不在期望的网络上、所有节点都失败；其他（参数错误、程序 bug）照常抛出 */
+export function isRecoverable(err: unknown): boolean {
+  return err instanceof HttpError || (err instanceof RpcError && err.nodeFault) || err instanceof NetworkMismatchError || err instanceof AllNodesFailedError
+}
+
+interface RawAccount {
+  lamports: number | string
+  owner: string
+  data: [string, string] | string
+  executable: boolean
+}
+
+function toAccountInfo(address: string, raw: RawAccount | null): AccountInfo | null {
+  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,
+  }
+}
+
+/**
+ * 账户读取管线：getMultipleAccounts 按 100 个一组、去重、并发池（最多同时 3 个），节点高度不够时等待重试，
+ * 记录读到的 slot；tolerant 时节点问题只标记失败。SolanaClient 和余额 / 代币详情模块共用
+ */
+export class AccountReader {
+  constructor(
+    readonly transport: RpcTransport,
+    readonly commitment: Commitment,
+  ) {}
+
+  /** 发给传输层：有 signal 时作为第三个参数传下去（没有时只传两个参数，自定义传输不受影响） */
+  send<T>(method: string, params: readonly unknown[] | undefined, signal: AbortSignal | undefined): Promise<T> {
+    return signal ? this.transport.request<T>(method, params, { signal }) : this.transport.request<T>(method, params)
+  }
+
+  /**
+   * 发一个读账户类的请求：params 最后一项是配置对象，传了 minContextSlot 时带上；
+   * 节点高度不够（所有节点都落后）时每 500ms 重试，最多约 10 秒；记录返回的 context.slot（取最小值）
+   */
+  async call<T>(ctx: QueryContext, method: string, params: unknown[]): Promise<T> {
+    const last = params[params.length - 1]
+    const sent =
+      ctx.minContextSlot === undefined ? params : [...params.slice(0, -1), { ...(last as object), minContextSlot: ctx.minContextSlot }]
+    const started = Date.now()
+    for (;;) {
+      try {
+        const res = await this.send<T>(method, sent, ctx.signal)
+        const slot = (res as { context?: { slot?: unknown } } | null)?.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)
+      }
+    }
+  }
+
+  async accounts(addresses: readonly string[], ctx: QueryContext): Promise<(AccountInfo | null)[]> {
+    const fetched = await this.fetchAccounts(addresses, false, ctx)
+    return addresses.map((address) => (fetched.get(address) as AccountInfo | null | undefined) ?? null)
+  }
+
+  /**
+   * 只读 lamports（主币余额）：getMultipleAccounts 带 dataSlice { offset: 0, length: 0 }，不读回账户数据——
+   * 钱包可能是数据很大的程序账户（上百 KB），整份读回会拖慢甚至超时。结果与 addresses 一一对应，账户不存在或地址非法时为 null
+   */
+  async lamports(addresses: readonly string[], ctx: QueryContext): Promise<(bigint | null)[]> {
+    const [fetched] = await this.fetchGroups([{ addresses, lamportsOnly: true }], false, ctx)
+    return addresses.map((address) => (fetched?.get(address) as AccountInfo | null | undefined)?.lamports ?? null)
+  }
+
+  /** getMultipleAccounts（读账户数据）：见 fetchGroups */
+  async fetchAccounts(
+    addresses: readonly string[],
+    tolerant: boolean,
+    ctx: QueryContext,
+    failure?: { error?: unknown },
+  ): Promise<Map<string, AccountInfo | null | typeof FAILED>> {
+    const [fetched] = await this.fetchGroups([{ addresses, lamportsOnly: false }], tolerant, ctx, failure)
+    return fetched as Map<string, AccountInfo | null | typeof FAILED>
+  }
+
+  /**
+   * getMultipleAccounts：每组去重、按 100 个一组拆分，所有组的请求放进并发池，最多同时 3 个（一个结束就发下一个，不必等同一波里最慢的）。
+   * lamportsOnly 的组带 dataSlice（长度 0，对同一请求里的所有账户生效，所以只要 lamports 的账户要单独成组）。
+   * tolerant 为 true 时，某个请求因节点问题（网络、限频等）失败不抛错：该请求的账户标记为 FAILED，并且不再发后面的请求（节点已经在限频了），
+   * 第一个这样的错误记在 failure.error；否则第一个错误抛出，后面的请求也不再发。结果按组返回
+   */
+  async fetchGroups(
+    groups: ReadonlyArray<{ addresses: readonly string[]; lamportsOnly: boolean }>,
+    tolerant: boolean,
+    ctx: QueryContext,
+    failure?: { error?: unknown },
+  ): Promise<Array<Map<string, AccountInfo | null | typeof FAILED>>> {
+    const chunks: Array<{ group: number; addresses: string[]; lamportsOnly: boolean }> = []
+    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<string, AccountInfo | null | typeof FAILED>())
+    // 出错后不再发后面的请求
+    let stopped = false
+    // 并发池最先发出的几个请求在同一 tick（合并成一个 JSON-RPC 批量请求）
+    await mapPool(chunks, MAX_PARALLEL_ACCOUNT_REQUESTS, async (chunk) => {
+      const result = results[chunk.group] as Map<string, AccountInfo | null | typeof FAILED>
+      if (stopped) {
+        chunk.addresses.forEach((address) => result.set(address, FAILED))
+        return
+      }
+      // 已取消的查询不再发后面的请求
+      if (ctx.signal?.aborted) {
+        throw ctx.signal.reason
+      }
+      try {
+        const res = await this.call<{ value: Array<RawAccount | null> }>(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) {
+        stopped = true
+        if (!tolerant || !isRecoverable(err)) {
+          throw err
+        }
+        if (failure && !('error' in failure)) {
+          failure.error = err
+        }
+        chunk.addresses.forEach((address) => result.set(address, FAILED))
+      }
+    })
+    return results
+  }
+}
+
+/** 结果项带上 slot（传了 withSlot / minContextSlot，且这次查询发了请求时） */
+export function attachSlot<T extends object>(items: T[], ctx: QueryContext, options: SlotOptions): T[] {
+  if ((!options.withSlot && options.minContextSlot === undefined) || ctx.slot === undefined) {
+    return items
+  }
+  const slot = ctx.slot
+  return items.map((item) => ({ ...item, slot }))
+}
+
+export function queryContext(options: RequestOptions & SlotOptions): QueryContext {
+  return { signal: options.signal, minContextSlot: options.minContextSlot }
+}

package/src/address.ts

@@ -18,7 +18,7 @@ export function isAddress(value: unknown): value is string {
 export function decodeAddress(address: string): Uint8Array {
   const bytes = base58.decode(address)
   if (bytes.length !== 32) {
-    throw new Error(`Invalid Solana address: ${address}`)
+    throw new InvalidAddressError(`Invalid Solana address: ${address}`, address)
   }
   return bytes
 }
@@ -95,8 +95,28 @@ function concat(parts: Uint8Array[]): Uint8Array {
 const MAX_SEED_LENGTH = 32
 const MAX_SEEDS = 16
 
-// PDA 推导是纯计算但要做多次 sha256 + 曲线判断，结果缓存
+// PDA 推导是纯计算但要做多次 sha256 + 曲线判断，结果缓存（LRU：命中时移到最后，满了删最久没用的）
 const pdaCache = new Map<string, string>()
+const MAX_PDA_CACHE = 10_000
+
+const HEX = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, '0'))
+
+/** 缓存键：程序地址 + 各种子的十六进制（比 base58 编码快得多；用 ',' 分隔，不同的种子划分不会撞键） */
+function pdaKey(seeds: readonly Uint8Array[], programId: string): string {
+  let key = programId
+  for (const seed of seeds) {
+    key += ','
+    for (let i = 0; i < seed.length; i++) {
+      key += HEX[seed[i] as number]
+    }
+  }
+  return key
+}
+
+/** 测试用：这组种子的 PDA 是否在缓存里 */
+export function isPdaCached(seeds: readonly Uint8Array[], programId: string): boolean {
+  return pdaCache.has(pdaKey(seeds, programId))
+}
 
 /**
  * 推导 PDA（与 web3.js PublicKey.findProgramAddressSync 相同），返回地址。
@@ -110,9 +130,11 @@ export function findProgramAddress(seeds: Uint8Array[], programId: string): stri
   if (seeds.length + 1 > MAX_SEEDS) {
     throw new TypeError('Max seeds exceeded')
   }
-  const key = `${programId}:${seeds.map((s) => encodeAddress(s)).join(',')}`
+  const key = pdaKey(seeds, programId)
   const cached = pdaCache.get(key)
   if (cached) {
+    pdaCache.delete(key)
+    pdaCache.set(key, cached)
     return cached
   }
   const program = decodeAddress(programId)
@@ -120,10 +142,10 @@ export function findProgramAddress(seeds: Uint8Array[], programId: string): stri
     const hash = sha256(concat([...seeds, new Uint8Array([bump]), program, PDA_MARKER]))
     if (!isOnCurve(hash)) {
       const address = encodeAddress(hash)
-      if (pdaCache.size > 10_000) {
-        pdaCache.clear()
-      }
       pdaCache.set(key, address)
+      if (pdaCache.size > MAX_PDA_CACHE) {
+        pdaCache.delete(pdaCache.keys().next().value as string)
+      }
       return address
     }
   }
@@ -151,3 +173,16 @@ export function getMetadataAddress(mint: string): string {
     METADATA_PROGRAM_ID,
   )
 }
+
+/** 地址不合法时抛出（继承 Error，message 与之前的普通 Error 相同；用 code / address 判断） */
+export class InvalidAddressError extends Error {
+  readonly code = 'INVALID_ADDRESS'
+  /** 不合法的那个值 */
+  readonly address: string
+
+  constructor(message: string, address: string) {
+    super(message)
+    this.name = 'InvalidAddressError'
+    this.address = address
+  }
+}

package/src/approvals.ts

@@ -4,18 +4,19 @@
  */
 import { base64 } from '@scure/base'
 
-import { encodeAddress, getAssociatedTokenAddress, getMetadataAddress, isAddress } from './address.js'
+import { encodeAddress, getAssociatedTokenAddress, getMetadataAddress, InvalidAddressError, isAddress } from './address.js'
 import type { RequestOptions, SolanaClient } from './client.js'
 import { TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID } from './constants.js'
-import { findExtension, formatUnits, parseMetaplexMetadata, parseMint, type AccountInfo } from './layout.js'
-import { methodUnavailable } from './lp.js'
+import { Bytes } from './bytes.js'
+import { findExtension, formatUnits, parseMetaplexMetadata, parseMint, parseTokenAccountState as parseTokenAccountBase, type AccountInfo } from './layout.js'
+import { withMethodHint } from './lp.js'
 import { closeAccount, harvestWithheldTokensToMint, revoke } from './write/instructions.js'
 import type { BatchCallOptions } from './write/batch.js'
 import type { WriteResult } from './write/send.js'
 import type { SignerInput } from './write/signer.js'
 import type { Instruction } from './write/transaction.js'
 
-export interface ApprovalsQuery extends RequestOptions {
+export interface ApprovalsOptions extends RequestOptions {
   /**
    * 要检查的代币 mint：读这些代币的关联代币账户（ATA，SPL Token 和 Token-2022 都看），免费公共节点也能用；非 ATA 的代币账户查不到。
    * 不传时列出地址的全部代币账户（getTokenAccountsByOwner），需要支持它的节点
@@ -25,6 +26,9 @@ export interface ApprovalsQuery extends RequestOptions {
   all?: boolean
 }
 
+/** @deprecated 改名为 ApprovalsOptions（与其他查询的 options 命名统一），旧名保留 */
+export type ApprovalsQuery = ApprovalsOptions
+
 /** 关不掉的原因：balance 有余额（Wrapped SOL 除外）；close-authority 关闭权限是别的地址；confidential-balance Token-2022 机密余额不为 0 */
 export type CloseBlocker = 'balance' | 'close-authority' | 'confidential-balance'
 
@@ -66,8 +70,6 @@ export interface TokenAccountApproval {
   closeBlocker: CloseBlocker | null
 }
 
-const ACCOUNT_SIZE = 165
-const ACCOUNT_TYPE_ACCOUNT = 2
 const EXT_TRANSFER_FEE_AMOUNT = 2
 const EXT_CONFIDENTIAL_TRANSFER_ACCOUNT = 5
 const EXT_PERMANENT_DELEGATE = 12
@@ -88,34 +90,27 @@ interface ParsedAccount {
   confidentialBalance: boolean
 }
 
-/** 解析代币账户；不是已初始化的代币账户时为 null */
+/** 解析代币账户（基础布局用 layout 的 parseTokenAccountState）及关闭相关的 Token-2022 扩展；不是已初始化的代币账户时为 null */
 export function parseTokenAccountState(data: Uint8Array): ParsedAccount | null {
-  if (data.length !== ACCOUNT_SIZE && !(data.length > ACCOUNT_SIZE && data[ACCOUNT_SIZE] === ACCOUNT_TYPE_ACCOUNT)) {
+  const base = parseTokenAccountBase(data)
+  if (!base) {
     return null
   }
-  const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
-  const pubkey = (offset: number) => encodeAddress(data.slice(offset, offset + 32))
-  // COption：u32 标记（1 有、0 没有）+ 值
-  const option = (offset: number) => view.getUint32(offset, true) === 1
-  const state = data[108] as number
-  if (state === 0) {
-    return null // 未初始化
-  }
   const withheld = findExtension(data, EXT_TRANSFER_FEE_AMOUNT)
   // 机密转账：待入账（lo / hi）和可用余额的密文全为 0 才能关闭；手续费扩展同理（Token-2022 的 closable 检查）
   const confidential = findExtension(data, EXT_CONFIDENTIAL_TRANSFER_ACCOUNT)
   const confidentialFee = findExtension(data, EXT_CONFIDENTIAL_TRANSFER_FEE_AMOUNT)
   const nonZero = (bytes: Uint8Array | null, from: number, to: number) => !!bytes && bytes.slice(from, to).some((b) => b !== 0)
   return {
-    mint: pubkey(0),
-    owner: pubkey(32),
-    amount: view.getBigUint64(64, true),
-    delegate: option(72) ? pubkey(76) : null,
-    frozen: state === 2,
-    native: option(109),
-    delegatedAmount: view.getBigUint64(121, true),
-    closeAuthority: option(129) ? pubkey(133) : null,
-    withheldAmount: withheld && withheld.length >= 8 ? new DataView(withheld.buffer, withheld.byteOffset).getBigUint64(0, true) : 0n,
+    mint: base.mint,
+    owner: base.owner,
+    amount: base.amount,
+    delegate: base.delegate,
+    frozen: base.frozen,
+    native: base.native,
+    delegatedAmount: base.delegatedAmount,
+    closeAuthority: base.closeAuthority,
+    withheldAmount: withheld && withheld.length >= 8 ? new Bytes(withheld).u64(0) : 0n,
     confidentialBalance: nonZero(confidential, 33, 225) || nonZero(confidentialFee, 0, 64),
   }
 }
@@ -142,12 +137,12 @@ interface Found {
  * await approvals(new SolanaClient('https://my-rpc…'), owner)   // 全部代币账户
  * ```
  */
-export async function approvals(client: SolanaClient, owner: string, query: ApprovalsQuery = {}): Promise<TokenAccountApproval[]> {
+export async function approvals(client: SolanaClient, owner: string, options: ApprovalsOptions = {}): Promise<TokenAccountApproval[]> {
   if (!isAddress(owner)) {
-    throw new Error(`Invalid owner address: ${owner}`)
+    throw new InvalidAddressError(`Invalid owner address: ${owner}`, owner)
   }
-  const { signal } = query
-  const found = query.mints ? await ataAccounts(client, owner, query.mints, signal) : await listAccounts(client, owner, signal)
+  const { signal } = options
+  const found = options.mints ? await ataAccounts(client, owner, options.mints, signal) : await listAccounts(client, owner, signal)
   // 只看 owner 自己的账户（ATA 的 owner 可能被改过：SPL Token 的 ATA 能 SetAuthority 换 owner）
   const mine = found.filter((f) => f.parsed.owner === owner)
   const mints = [...new Set(mine.map((f) => f.parsed.mint))]
@@ -185,7 +180,7 @@ export async function approvals(client: SolanaClient, owner: string, query: Appr
       closeBlocker,
     }
   })
-  return query.all ? list : list.filter((a) => a.delegate !== null || a.closeBlocker === 'close-authority' || BigInt(a.amount) === 0n)
+  return options.all ? list : list.filter((a) => a.delegate !== null || a.closeBlocker === 'close-authority' || BigInt(a.amount) === 0n)
 }
 
 /** 指定 mints：两个程序的 ATA 都读（mint 所属程序未知时只有一个存在） */
@@ -203,22 +198,19 @@ async function ataAccounts(client: SolanaClient, owner: string, mints: readonly
 
 /** 不传 mints：用 getTokenAccountsByOwner 列出两个程序的全部代币账户（base64，自己解析扩展） */
 async function listAccounts(client: SolanaClient, owner: string, signal: AbortSignal | undefined): Promise<Found[]> {
-  const lists = await Promise.all(
-    [TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID].map((programId) =>
-      client.request<{ value: RawTokenAccount[] }>('getTokenAccountsByOwner', [owner, { programId }, { encoding: 'base64', commitment: client.commitment }], { signal }).then(
-        (res) => ({ programId, value: res.value ?? [] }),
+  const lists = await withMethodHint(
+    Promise.all(
+      [TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID].map((programId) =>
+        client
+          .request<{ value: RawTokenAccount[] }>('getTokenAccountsByOwner', [owner, { programId }, { encoding: 'base64', commitment: client.commitment }], { signal })
+          .then((res) => ({ programId, value: res.value ?? [] })),
       ),
     ),
-  ).catch((err: unknown) => {
-    if (signal?.aborted || !methodUnavailable(err)) {
-      throw err // 取消、限频、超时等原样抛出（保留错误类型）
-    }
-    throw new Error(
-      `Listing the token accounts of ${owner} failed (${err instanceof Error ? err.message : String(err)}). ` +
-        'Listing needs getTokenAccountsByOwner (most free public nodes do not support it): pass the mints in `mints`, or use a node that supports it',
-      { cause: err },
-    )
-  })
+    signal,
+    (detail) =>
+      `Listing the token accounts of ${owner} failed (${detail}). ` +
+      'Listing needs getTokenAccountsByOwner (most free public nodes do not support it): pass the mints in `mints`, or use a node that supports it',
+  )
   return lists.flatMap(({ programId, value }) =>
     value.flatMap((entry) => {
       const parsed = entry.account.owner === programId ? parseTokenAccountState(base64.decode(entry.account.data[0])) : null