@w3lib/solana-batch-call 0.6.0 → 0.7.0

package/src/clientConfig.ts

@@ -0,0 +1,12 @@
+import type { Cluster } from './constants.js'
+import type { SourceOptions } from './source.js'
+
+/** SolanaClient 的节点配置（网络、节点选项、期望的创世哈希），按客户端登记：写操作的 sendRpc 按同样的配置解析、校验网络 */
+export interface ClientSourceConfig {
+  cluster: Cluster | undefined
+  options: SourceOptions
+  genesis: () => Promise<string>
+}
+
+/** 单独成模块：/write 只需查表，不用静态带上 source.ts（sendRpc 解析时才按需加载） */
+export const clientSourceConfigs = new WeakMap<object, ClientSourceConfig>()

package/src/decode.ts

@@ -2,7 +2,7 @@
  * 指令解码（/simulate 和 /history 共用）：System、SPL Token / Token-2022、关联代币账户、计算预算、Memo、升级程序加载器，
  * 以及 programs.ts 里认得的 DEX / 聚合器（协议 + 指令名 + 大类）。其他程序只给程序名（认得时）和大类 contract / unknown
  */
-import { encodeAddress } from './address.js'
+import { Bytes } from './bytes.js'
 import { ASSOCIATED_TOKEN_PROGRAM_ID, SYSTEM_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID } from './constants.js'
 import { BPF_LOADER_UPGRADEABLE, COMPUTE_BUDGET, MEMO_V1, MEMO_V2, PROGRAMS, knownMethod, type IxType } from './programs.js'
 
@@ -28,32 +28,6 @@ export const AUTHORITY_TYPES = [
 
 const short = (a: string | undefined) => (a ? `${a.slice(0, 4)}…${a.slice(-4)}` : '?')
 
-class Data {
-  readonly view: DataView
-  offset = 0
-  constructor(readonly bytes: Uint8Array) {
-    this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
-  }
-  u8() {
-    return this.view.getUint8(this.offset++)
-  }
-  u32() {
-    const v = this.view.getUint32(this.offset, true)
-    this.offset += 4
-    return v
-  }
-  u64() {
-    const v = this.view.getBigUint64(this.offset, true)
-    this.offset += 8
-    return v
-  }
-  key() {
-    const v = encodeAddress(this.bytes.slice(this.offset, this.offset + 32))
-    this.offset += 32
-    return v
-  }
-}
-
 /**
  * 解码一条指令。accounts 是指令用到的账户地址（已按指令里的下标解析，包含地址查找表里的），data 是指令数据。
  * 数据格式不对时不抛错，按“不认识的指令”返回
@@ -78,7 +52,7 @@ export function decodeInstruction(index: number, programId: string, accounts: re
 type Partial_ = Pick<DecodedInstruction, 'type' | 'summary'> & Partial<Pick<DecodedInstruction, 'method' | 'args' | 'protocol'>>
 
 function decodeKnown(programId: string, a: readonly string[], data: Uint8Array): Partial_ | null {
-  const d = new Data(data)
+  const d = new Bytes(data)
   switch (programId) {
     case SYSTEM_PROGRAM_ID:
       return decodeSystem(d, a)
@@ -108,7 +82,7 @@ function decodeKnown(programId: string, a: readonly string[], data: Uint8Array):
   }
 }
 
-function decodeSystem(d: Data, a: readonly string[]): Partial_ {
+function decodeSystem(d: Bytes, a: readonly string[]): Partial_ {
   const tag = d.u32()
   switch (tag) {
     case 0: {
@@ -139,7 +113,7 @@ function decodeSystem(d: Data, a: readonly string[]): Partial_ {
   }
 }
 
-function decodeToken(d: Data, a: readonly string[]): Partial_ {
+function decodeToken(d: Bytes, a: readonly string[]): Partial_ {
   const tag = d.u8()
   const amountArgs = (extra: Record<string, unknown>, amount: bigint) => ({ ...extra, amount: amount.toString() })
   switch (tag) {

package/src/fees.ts

@@ -7,7 +7,7 @@ import { base64 } from '@scure/base'
 import { encodeAddress } from './address.js'
 import type { RequestOptions, SolanaClient } from './client.js'
 import { SOL_DECIMALS, SYSTEM_PROGRAM_ID } from './constants.js'
-import { formatUnits } from './layout.js'
+import { computeBudgetOf, formatUnits } from './layout.js'
 import type { InstructionInput } from './write/transaction.js'
 
 export type FeeLevel = 'slow' | 'normal' | 'fast'
@@ -156,14 +156,7 @@ export async function estimateCost(client: SolanaClient, input: CostInput, optio
     raw = base64.encode(bytes)
     signatures = message.signatures
     writable = [...message.writable, ...(await lookupWritable(client, message.lookups, signal))]
-    let limit: number | null = null
-    let price = 0n
-    for (const ix of message.instructions) {
-      if (ix.programId !== COMPUTE_BUDGET_PROGRAM_ID) continue
-      const view = new DataView(ix.data.buffer, ix.data.byteOffset, ix.data.byteLength)
-      if (ix.data[0] === 2 && ix.data.length >= 5) limit = view.getUint32(1, true)
-      if (ix.data[0] === 3 && ix.data.length >= 9) price = view.getBigUint64(1, true)
-    }
+    const { limit, price } = computeBudgetOf(message.instructions)
     const others = message.instructions.filter((ix) => ix.programId !== COMPUTE_BUDGET_PROGRAM_ID).length
     budget = { limit: Math.min(MAX_COMPUTE_UNITS, limit ?? DEFAULT_UNITS_PER_INSTRUCTION * others), price }
   } else {

package/src/history.ts

@@ -5,12 +5,13 @@
  */
 import { base58 } from '@scure/base'
 
-import { isAddress } from './address.js'
+import { InvalidAddressError, isAddress } from './address.js'
 import type { RequestOptions, SolanaClient } from './client.js'
 import { NATIVE_MINT, SOL_DECIMALS, SYSTEM_PROGRAM_ID } from './constants.js'
 import { decodeInstruction, type DecodedInstruction } from './decode.js'
 import { classify, describe, type AssetDelta, type Classified } from './describe.js'
 import { formatUnits } from './layout.js'
+import { mapPool } from './util.js'
 
 export type ActivityType = 'transfer' | 'swap' | 'approve' | 'liquidity' | 'mint' | 'contract' | 'other'
 
@@ -95,7 +96,7 @@ const short = (a: string) => `${a.slice(0, 4)}…${a.slice(-4)}`
  * ```
  */
 export async function history(client: SolanaClient, address: string, options: HistoryOptions = {}): Promise<HistoryPage> {
-  if (!isAddress(address)) throw new Error(`Invalid address: ${address}`)
+  if (!isAddress(address)) throw new InvalidAddressError(`Invalid address: ${address}`, address)
   const limit = options.limit ?? 20
   if (!Number.isInteger(limit) || limit < 1 || limit > MAX_HISTORY_LIMIT) throw new RangeError(`limit must be an integer between 1 and ${MAX_HISTORY_LIMIT}`)
   const sources = options.source === undefined ? [rpcHistory()] : Array.isArray(options.source) ? options.source : [options.source as HistorySource]
@@ -185,18 +186,6 @@ interface SignatureInfo {
   blockTime: number | null
 }
 
-async function pool<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
-  const results = new Array<R>(items.length)
-  let next = 0
-  const worker = async () => {
-    while (next < items.length) {
-      const i = next++
-      results[i] = await fn(items[i] as T)
-    }
-  }
-  await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker))
-  return results
-}
 
 /**
  * 默认数据源：getSignaturesForAddress（用 before 翻页）+ getTransaction（逐笔，json 编码、支持 v0）。
@@ -228,7 +217,7 @@ export function rpcHistory(options: RpcHistoryOptions = {}): HistorySource {
         let i = 0
         while (i < rows.length && items.length < limit && scanned < maxScan) {
           const chunk = rows.slice(i, i + Math.max(1, Math.min(limit - items.length, maxScan - scanned)))
-          const txs = await pool(chunk, concurrency, (row) => client.request<RawTransaction | null>('getTransaction', [row.signature, { encoding: 'json', maxSupportedTransactionVersion: MAX_TX_VERSION, commitment }], { signal }))
+          const txs = await mapPool(chunk, concurrency, (row) => client.request<RawTransaction | null>('getTransaction', [row.signature, { encoding: 'json', maxSupportedTransactionVersion: MAX_TX_VERSION, commitment }], { signal }))
           for (const [j, tx] of txs.entries()) {
             i++
             scanned++

package/src/index.ts

@@ -6,6 +6,7 @@ export {
   type AccountsOptions,
   type BalanceQuery,
   type BalancesOptions,
+  type BalancesQueryOptions,
   type ClientConfig,
   type OwnerTokensOptions,
   type PersistTokenMetaOptions,
@@ -64,7 +65,17 @@ export {
   clusterOfGenesis,
   type Cluster,
 } from './constants.js'
-export { createProgramAddress, decodeAddress, encodeAddress, findProgramAddress, getAssociatedTokenAddress, getMetadataAddress, isAddress, isOnCurve } from './address.js'
+export {
+  InvalidAddressError,
+  createProgramAddress,
+  decodeAddress,
+  encodeAddress,
+  findProgramAddress,
+  getAssociatedTokenAddress,
+  getMetadataAddress,
+  isAddress,
+  isOnCurve,
+} from './address.js'
 export {
   formatAmount,
   formatUnits,
@@ -94,6 +105,7 @@ export {
   type FallbackOptions,
   type HttpRpcOptions,
   type RequestEvent,
+  type RpcRequestOptions,
   type RpcTransport,
 } from './rpc.js'
 export { NetworkCheckedRpc, NetworkMismatchError, type RpcSource, type SourceOptions } from './source.js'

package/src/layout.ts

@@ -1,4 +1,4 @@
-import { encodeAddress } from './address.js'
+import { Bytes } from './bytes.js'
 
 /** getMultipleAccounts 解析后的账户 */
 export interface AccountInfo {
@@ -10,80 +10,6 @@ export interface AccountInfo {
   executable: boolean
 }
 
-class Reader {
-  #offset: number
-  readonly #view: DataView
-
-  constructor(
-    readonly bytes: Uint8Array,
-    offset = 0,
-  ) {
-    this.#offset = offset
-    this.#view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
-  }
-
-  get offset(): number {
-    return this.#offset
-  }
-
-  #need(n: number): void {
-    if (this.#offset + n > this.bytes.length) {
-      throw new RangeError('Account data is shorter than expected')
-    }
-  }
-
-  skip(n: number): void {
-    this.#need(n)
-    this.#offset += n
-  }
-
-  u8(): number {
-    this.#need(1)
-    return this.bytes[this.#offset++] as number
-  }
-
-  u16(): number {
-    this.#need(2)
-    const v = this.#view.getUint16(this.#offset, true)
-    this.#offset += 2
-    return v
-  }
-
-  u32(): number {
-    this.#need(4)
-    const v = this.#view.getUint32(this.#offset, true)
-    this.#offset += 4
-    return v
-  }
-
-  u64(): bigint {
-    this.#need(8)
-    const v = this.#view.getBigUint64(this.#offset, true)
-    this.#offset += 8
-    return v
-  }
-
-  pubkey(): string {
-    this.#need(32)
-    const v = encodeAddress(this.bytes.slice(this.#offset, this.#offset + 32))
-    this.#offset += 32
-    return v
-  }
-
-  /** borsh string：u32 长度 + UTF-8；去掉 Metaplex 用来补齐长度的 \0 */
-  string(): string {
-    const len = this.u32()
-    this.#need(len)
-    const v = new TextDecoder().decode(this.bytes.slice(this.#offset, this.#offset + len))
-    this.#offset += len
-    return v.replace(/\0+$/, '').trim()
-  }
-
-  option<T>(read: () => T): T | null {
-    return this.u8() === 1 ? read() : null
-  }
-}
-
 export interface MintInfo {
   mintAuthority: string | null
   supply: bigint
@@ -116,7 +42,7 @@ export function parseMint(data: Uint8Array): MintInfo {
   if (data.length !== MINT_SIZE && !(data.length > ACCOUNT_TYPE_OFFSET && data[ACCOUNT_TYPE_OFFSET] === ACCOUNT_TYPE_MINT)) {
     throw new RangeError('Not a mint account')
   }
-  const r = new Reader(data)
+  const r = new Bytes(data)
   const hasMintAuthority = r.u32() === 1
   const mintAuthority = r.pubkey()
   const supply = r.u64()
@@ -140,7 +66,7 @@ export function findExtension(data: Uint8Array, extensionType: number): Uint8Arr
     return null
   }
   try {
-    const r = new Reader(data, EXTENSIONS_OFFSET)
+    const r = new Bytes(data, EXTENSIONS_OFFSET)
     while (r.offset + 4 <= data.length) {
       const type = r.u16()
       const length = r.u16()
@@ -167,7 +93,7 @@ function parseTokenMetadataExtension(data: Uint8Array): TokenMetadata | null {
     return null
   }
   try {
-    const m = new Reader(ext)
+    const m = new Bytes(ext)
     m.pubkey() // updateAuthority
     m.pubkey() // mint
     return { name: m.string(), symbol: m.string(), uri: m.string() }
@@ -212,7 +138,7 @@ export function parseTransferFeeConfig(data: Uint8Array): TransferFeeConfigInfo
     return null
   }
   try {
-    const r = new Reader(ext)
+    const r = new Bytes(ext)
     // OptionalNonZeroPubkey：全 0 表示没有
     const configAuthority = r.pubkey()
     const withdrawAuthority = r.pubkey()
@@ -238,15 +164,70 @@ export interface TokenAccountInfo {
   amount: bigint
 }
 
+function isTokenAccountData(data: Uint8Array): boolean {
+  return data.length === ACCOUNT_SIZE || (data.length > ACCOUNT_TYPE_OFFSET && data[ACCOUNT_TYPE_OFFSET] === ACCOUNT_TYPE_ACCOUNT)
+}
+
 /** 解析代币账户（SPL Token / Token-2022 前 72 字节相同） */
 export function parseTokenAccount(data: Uint8Array): TokenAccountInfo {
-  if (data.length !== ACCOUNT_SIZE && !(data.length > ACCOUNT_TYPE_OFFSET && data[ACCOUNT_TYPE_OFFSET] === ACCOUNT_TYPE_ACCOUNT)) {
+  if (!isTokenAccountData(data)) {
     throw new RangeError('Not a token account')
   }
-  const r = new Reader(data)
+  const r = new Bytes(data)
   return { mint: r.pubkey(), owner: r.pubkey(), amount: r.u64() }
 }
 
+/** 代币账户的完整基础布局（前 165 字节，SPL Token / Token-2022 相同） */
+export interface TokenAccountState extends TokenAccountInfo {
+  delegate: string | null
+  /** 0 未初始化、1 正常、2 冻结 */
+  state: number
+  frozen: boolean
+  /** Wrapped SOL 账户（is_native 有值） */
+  native: boolean
+  delegatedAmount: bigint
+  closeAuthority: string | null
+}
+
+/** 解析代币账户的完整基础布局；不是代币账户或未初始化时为 null（包内使用：/approvals、/simulate） */
+export function parseTokenAccountState(data: Uint8Array): TokenAccountState | null {
+  if (!isTokenAccountData(data)) {
+    return null
+  }
+  const b = new Bytes(data)
+  const state = b.u8(108)
+  if (state === 0) {
+    return null
+  }
+  // COption：u32 标记（1 有、0 没有）+ 值
+  return {
+    mint: b.key(0),
+    owner: b.key(32),
+    amount: b.u64(64),
+    delegate: b.u32(72) === 1 ? b.key(76) : null,
+    state,
+    frozen: state === 2,
+    native: b.u32(109) === 1,
+    delegatedAmount: b.u64(121),
+    closeAuthority: b.u32(129) === 1 ? b.key(133) : null,
+  }
+}
+
+/** 计算预算指令里的计算单元上限（SetComputeUnitLimit）和单价（SetComputeUnitPrice，micro-lamports）；没有时 limit 为 null、price 为 0 */
+export function computeBudgetOf(instructions: Iterable<{ programId: string; data: Uint8Array }>): { limit: number | null; price: bigint } {
+  let limit: number | null = null
+  let price = 0n
+  for (const ix of instructions) {
+    if (ix.programId !== COMPUTE_BUDGET_PROGRAM) continue
+    const b = new Bytes(ix.data)
+    if (ix.data[0] === 2 && ix.data.length >= 5) limit = b.u32(1)
+    if (ix.data[0] === 3 && ix.data.length >= 9) price = b.u64(1)
+  }
+  return { limit, price }
+}
+
+const COMPUTE_BUDGET_PROGRAM = 'ComputeBudget111111111111111111111111111111'
+
 export interface MetaplexMetadata extends TokenMetadata {
   updateAuthority: string
   mint: string
@@ -261,7 +242,7 @@ export interface MetaplexMetadata extends TokenMetadata {
 
 /** 解析 Metaplex Token Metadata 账户；老版本账户缺少后面的字段时，缺的部分为默认值 */
 export function parseMetaplexMetadata(data: Uint8Array): MetaplexMetadata {
-  const r = new Reader(data)
+  const r = new Bytes(data)
   if (r.u8() !== 4) {
     throw new RangeError('Not a Metaplex metadata account') // Key::MetadataV1 = 4
   }

package/src/liquidity/common.ts

@@ -1,6 +1,6 @@
 import { sha256 } from '@noble/hashes/sha2.js'
 
-import { encodeAddress, getAssociatedTokenAddress, isAddress } from '../address.js'
+import { encodeAddress, getAssociatedTokenAddress, InvalidAddressError, isAddress } from '../address.js'
 import type { SolanaClient } from '../client.js'
 import { NATIVE_MINT, SYSTEM_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID } from '../constants.js'
 import { formatUnits, parseMint, parseTokenAccount, parseTransferFeeConfig, parseUnits, type AccountInfo } from '../layout.js'
@@ -25,7 +25,7 @@ export interface Ctx {
 export function createCtx(client: SolanaClient, owner: string, options: SolanaLiquidityOptions): Ctx {
   for (const address of [owner, options.recipient ?? owner]) {
     if (!isAddress(address)) {
-      throw new Error(`Invalid address: ${address}`)
+      throw new InvalidAddressError(`Invalid address: ${address}`, address)
     }
   }
   const slippage = options.slippage ?? 0.005

package/src/lp.ts

@@ -1,10 +1,12 @@
 import { sha256 } from '@noble/hashes/sha2.js'
 import { base64 } from '@scure/base'
 
-import { decodeAddress, encodeAddress, findProgramAddress, isAddress } from './address.js'
+import { decodeAddress, findProgramAddress, InvalidAddressError, isAddress } from './address.js'
 import type { RequestOptions, SolanaClient } from './client.js'
 import { formatUnits, parseMint, parseTokenAccount, type AccountInfo } from './layout.js'
 import { AllNodesFailedError, HttpError, RpcError } from './rpc.js'
+import { boundedSet, mapPool } from './util.js'
+import { Bytes } from './bytes.js'
 import {
   getAmountsForLiquidity,
   getFeeGrowthInside,
@@ -168,34 +170,8 @@ export interface LpPositionsOptions extends RequestOptions {
 // 账户布局（各程序的 Anchor / 原生账户，偏移量含 8 字节判别符）
 // ---------------------------------------------------------------------------
 
-/** 小端读取账户数据（添加 / 移除流动性也用） */
-export class Bytes {
-  readonly #view: DataView
-  constructor(readonly data: Uint8Array) {
-    this.#view = new DataView(data.buffer, data.byteOffset, data.byteLength)
-  }
-  u8(o: number): number {
-    return this.#view.getUint8(o)
-  }
-  u16(o: number): number {
-    return this.#view.getUint16(o, true)
-  }
-  u32(o: number): number {
-    return this.#view.getUint32(o, true)
-  }
-  i32(o: number): number {
-    return this.#view.getInt32(o, true)
-  }
-  u64(o: number): bigint {
-    return this.#view.getBigUint64(o, true)
-  }
-  u128(o: number): bigint {
-    return (this.#view.getBigUint64(o + 8, true) << 64n) | this.#view.getBigUint64(o, true)
-  }
-  key(o: number): string {
-    return encodeAddress(this.data.subarray(o, o + 32))
-  }
-}
+// 小端读取账户数据：公共的 Bytes（添加 / 移除流动性也从这里引用）
+export { Bytes }
 
 const ZERO_ADDRESS = '11111111111111111111111111111111'
 const RAYDIUM_POSITION_SIZE = 281
@@ -544,7 +520,7 @@ interface RawAmm {
  */
 export async function lpPositions(client: SolanaClient, owner: string, options: LpPositionsOptions = {}): Promise<SolanaLpPosition[]> {
   if (!isAddress(owner)) {
-    throw new Error(`Invalid owner address: ${owner}`)
+    throw new InvalidAddressError(`Invalid owner address: ${owner}`, owner)
   }
   const protocols = new Set<SolanaLpProtocol>(options.protocols ?? (Object.keys(SOLANA_LP_PROTOCOLS) as SolanaLpProtocol[]))
   for (const p of protocols) {
@@ -554,7 +530,7 @@ export async function lpPositions(client: SolanaClient, owner: string, options:
   }
   for (const address of [...(options.mints ?? []), ...(options.pools ?? [])]) {
     if (!isAddress(address)) {
-      throw new Error(`Invalid address: ${address}`)
+      throw new InvalidAddressError(`Invalid address: ${address}`, address)
     }
   }
   const { signal } = options
@@ -621,13 +597,30 @@ export async function lpPositions(client: SolanaClient, owner: string, options:
     }
   })
 
-  // 3. 池子：集中流动性的池子账户；LP 代币按 LP mint 找池子
+  // 3. 池子：集中流动性的池子账户；LP 代币按 LP mint 找池子（之前找到过的直接读池子账户，和集中流动性的池子一起读）
   const poolAddresses = [...new Set(positions.map((p) => p.pool))]
+  const cached = lookups.flatMap((l) => {
+    const address = ammPoolByLpMint.get(lpPoolKey(l.protocol, l.lpMint))
+    return address ? [{ ...l, address }] : []
+  })
+  const uncached = lookups.filter((l) => !ammPoolByLpMint.has(lpPoolKey(l.protocol, l.lpMint)))
   const [poolAccounts, found] = await Promise.all([
-    client.accounts(poolAddresses, { signal }),
-    Promise.all(lookups.map((l) => findAmmPool(client, l.protocol, l.lpMint, signal))),
+    client.accounts([...poolAddresses, ...cached.map((c) => c.address)], { signal }),
+    findAmmPools(client, uncached, signal),
   ])
-  for (const pool of found) {
+  // 缓存的池子核对一下（地址不对、账户读不到时重新找）
+  const stale: typeof lookups = []
+  cached.forEach((c, i) => {
+    const account = poolAccounts[poolAddresses.length + i]
+    const pool = account ? parseAmmPool(account) : null
+    if (pool && pool.protocol === c.protocol && pool.lpMint === c.lpMint) {
+      poolByLp.set(pool.lpMint, pool)
+    } else {
+      ammPoolByLpMint.delete(lpPoolKey(c.protocol, c.lpMint))
+      stale.push({ protocol: c.protocol, lpMint: c.lpMint })
+    }
+  })
+  for (const pool of [...found, ...(stale.length ? await findAmmPools(client, stale, signal) : [])]) {
     if (pool) {
       poolByLp.set(pool.lpMint, pool)
     }
@@ -751,6 +744,19 @@ export async function lpPositions(client: SolanaClient, owner: string, options:
   return finalize(client, raw, options)
 }
 
+/**
+ * 方法不可用（见 methodUnavailable）时把错误换成说明怎么绕过的 Error（cause 为原错误，hint 拿到原错误的 message）；
+ * 取消、限频、超时等原样抛出（保留错误类型）。/lp、/approvals、资产总值共用
+ */
+export function withMethodHint<T>(promise: Promise<T>, signal: AbortSignal | undefined, hint: (detail: string) => string): Promise<T> {
+  return promise.catch((err: unknown) => {
+    if (signal?.aborted || !methodUnavailable(err)) {
+      throw err
+    }
+    throw new Error(hint(err instanceof Error ? err.message : String(err)), { cause: err })
+  })
+}
+
 /**
  * 节点不提供这个方法（方法不存在、被拦截、需要付费 / Token、403 等）：这时报错里说明怎么绕过。
  * 多节点时所有节点都是这个原因才算；限频、超时、网络不对等原样抛出（资产总值 portfolio 也用）
@@ -779,43 +785,63 @@ async function listHoldings(client: SolanaClient, owner: string, mints: readonly
     const balances = list.length ? await client.balances(owner, list, { signal }) : []
     return balances.filter((b) => b.success && !b.native && b.balance !== '0').map((b) => ({ mint: b.token, amount: BigInt(b.balance), decimals: b.decimals }))
   }
-  const tokens = await client.ownerTokens(owner, { signal, metadata: false, includeNative: false, includeNfts: true }).catch((err: unknown) => {
-    if (signal?.aborted || !methodUnavailable(err)) {
-      throw err // 取消、限频、超时等原样抛出（保留错误类型）
-    }
-    throw new Error(
-      `Scanning the token accounts of ${owner} failed (${err instanceof Error ? err.message : String(err)}). ` +
-        'Scanning needs getTokenAccountsByOwner (most free public nodes do not support it): pass the position NFT / LP mints in `mints`, or use a node that supports it',
-      { cause: err },
-    )
-  })
+  const tokens = await withMethodHint(
+    client.ownerTokens(owner, { signal, metadata: false, includeNative: false, includeNfts: true }),
+    signal,
+    (detail) =>
+      `Scanning the token accounts of ${owner} failed (${detail}). ` +
+      'Scanning needs getTokenAccountsByOwner (most free public nodes do not support it): pass the position NFT / LP mints in `mints`, or use a node that supports it',
+  )
   return tokens.map((t) => ({ mint: t.token, amount: BigInt(t.balance), decimals: t.decimals }))
 }
 
-/** 按 LP mint 找 AMM v4 / CPMM 的池子（getProgramAccounts + memcmp），找不到时为 null */
+/**
+ * LP mint → 池子地址（AMM v4 / CPMM）：池子地址不会变，找到后永久缓存（条目数有上限，超出淘汰最早写入的），
+ * 之后不再 getProgramAccounts，用时读池子账户核对
+ */
+const ammPoolByLpMint = new Map<string, string>()
+const MAX_CACHED_LP_POOLS = 10_000
+/** 同时进行的 getProgramAccounts 数（每个都要节点扫描整个程序的账户，很重） */
+const MAX_PARALLEL_POOL_LOOKUPS = 4
+
+function lpPoolKey(protocol: 'raydium-amm' | 'raydium-cpmm', lpMint: string): string {
+  return `${protocol}:${lpMint}`
+}
+
+/** 测试用：清空 LP mint → 池子地址的缓存 */
+export function resetLpPoolCache(): void {
+  ammPoolByLpMint.clear()
+}
+
+/** 按 LP mint 找池子，限制并发；结果与 lookups 一一对应 */
+function findAmmPools(
+  client: SolanaClient,
+  lookups: ReadonlyArray<{ protocol: 'raydium-amm' | 'raydium-cpmm'; lpMint: string }>,
+  signal: AbortSignal | undefined,
+): Promise<Array<AmmPoolState | null>> {
+  return mapPool(lookups, MAX_PARALLEL_POOL_LOOKUPS, (l) => findAmmPool(client, l.protocol, l.lpMint, signal))
+}
+
+/** 按 LP mint 找 AMM v4 / CPMM 的池子（getProgramAccounts + memcmp），找不到时为 null；找到的池子地址写入缓存 */
 async function findAmmPool(client: SolanaClient, protocol: 'raydium-amm' | 'raydium-cpmm', lpMint: string, signal: AbortSignal | undefined): Promise<AmmPoolState | null> {
   const [programId, size, offset] = protocol === 'raydium-amm' ? [RAYDIUM_AMM_PROGRAM_ID, AMM_POOL_SIZE, 464] : [RAYDIUM_CPMM_PROGRAM_ID, CPMM_POOL_SIZE, 136]
-  const res = await client
-    .request<{ pubkey: string; account: { data: [string, string]; owner: string } }[]>(
+  // 免费公共节点大多不支持 getProgramAccounts：说明怎么绕过
+  const res = await withMethodHint(
+    client.request<{ pubkey: string; account: { data: [string, string]; owner: string } }[]>(
       'getProgramAccounts',
       [programId, { encoding: 'base64', commitment: client.commitment, filters: [{ dataSize: size }, { memcmp: { offset, bytes: lpMint } }] }],
       { signal },
-    )
-    .catch((err: unknown) => {
-      if (signal?.aborted || !methodUnavailable(err)) {
-        throw err
-      }
-      // 免费公共节点大多不支持 getProgramAccounts：说明怎么绕过
-      throw new Error(
-        `Finding the ${SOLANA_LP_PROTOCOLS[protocol].name} pool of LP token ${lpMint} uses getProgramAccounts, which failed (${err instanceof Error ? err.message : String(err)}; most free public nodes do not support it). ` +
-          "Pass the pool address in `pools`, use a node that supports getProgramAccounts, or skip LP tokens with `protocols: ['raydium-clmm', 'orca-whirlpool']`",
-        { cause: err },
-      )
-    })
+    ),
+    signal,
+    (detail) =>
+      `Finding the ${SOLANA_LP_PROTOCOLS[protocol].name} pool of LP token ${lpMint} uses getProgramAccounts, which failed (${detail}; most free public nodes do not support it). ` +
+      "Pass the pool address in `pools`, use a node that supports getProgramAccounts, or skip LP tokens with `protocols: ['raydium-clmm', 'orca-whirlpool']`",
+  )
   for (const item of res ?? []) {
     const data = base64.decode(item.account.data[0])
     const pool = parseAmmPool({ address: item.pubkey, owner: item.account.owner, data, lamports: 0n, executable: false })
     if (pool?.lpMint === lpMint) {
+      boundedSet(ammPoolByLpMint, lpPoolKey(protocol, lpMint), pool.address, MAX_CACHED_LP_POOLS)
       return pool
     }
   }

package/src/portfolio.ts

@@ -2,7 +2,7 @@
  * 资产总值（子路径 `@w3lib/solana-batch-call/price`）：代币余额 × 价格，可选加上 LP 仓位的价值
  */
 import type { RequestOptions, SolanaClient } from './client.js'
-import { lpPositions, methodUnavailable, type LpPositionsOptions, type SolanaLpPosition } from './lp.js'
+import { lpPositions, withMethodHint, type LpPositionsOptions, type SolanaLpPosition } from './lp.js'
 import { combinePrices, defillamaPrices, onchainPrices, tokenPrices, type SolanaPriceSource } from './price.js'
 
 export interface PortfolioOptions extends RequestOptions {
@@ -110,15 +110,12 @@ async function holdings(client: SolanaClient, owner: string, tokens: readonly st
     const balances = tokens.length ? await client.balances(owner, tokens, { symbol: true, signal }) : []
     return balances.filter((b) => b.success).map((b) => ({ token: b.token, native: b.native, symbol: b.symbol ?? null, balance: b.balance, decimals: b.decimals, formatted: b.formatted }))
   }
-  const owned = await client.ownerTokens(owner, { signal }).catch((err: unknown) => {
-    if (signal?.aborted || !methodUnavailable(err)) {
-      throw err // 取消、限频、超时等原样抛出（保留错误类型）
-    }
-    throw new Error(
-      `Listing the tokens 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 `tokens`, or use a node that supports it',
-      { cause: err },
-    )
-  })
+  const owned = await withMethodHint(
+    client.ownerTokens(owner, { signal }),
+    signal,
+    (detail) =>
+      `Listing the tokens of ${owner} failed (${detail}). ` +
+      'Listing needs getTokenAccountsByOwner (most free public nodes do not support it): pass the mints in `tokens`, or use a node that supports it',
+  )
   return owned.map((t) => ({ token: t.token, native: t.native, symbol: t.symbol ?? null, balance: t.balance, decimals: t.decimals, formatted: t.formatted }))
 }