@w3lib/solana-batch-call 0.4.0 → 0.6.0

package/src/names.ts

@@ -0,0 +1,329 @@
+/**
+ * 域名解析（子路径 `@w3lib/solana-batch-call/names`）：SNS（Solana Name Service，Bonfida），名字 → 地址、地址 → 主域名（反查后核对）。
+ * 账户地址都在本地按 PDA 推导，读取合成 getMultipleAccounts，不需要索引节点（代币化的域名除外）
+ */
+import { sha256 } from '@noble/hashes/sha2.js'
+
+import { decodeAddress, encodeAddress, findProgramAddress, getAssociatedTokenAddress, isAddress, isOnCurve } from './address.js'
+import type { RequestOptions, SolanaClient } from './client.js'
+import { TOKEN_PROGRAM_ID } from './constants.js'
+import type { AccountInfo } from './layout.js'
+
+/** SPL Name Service 程序 */
+export const NAME_PROGRAM_ID = 'namesLPneVptA9Z5rqUDD9tMTWEJwofgaYwp8cawRkX'
+/** SNS 顶级域（`.sns`，2026-10 之前叫 `.sol`，链上是同一批账户）的根账户 */
+export const SNS_ROOT_DOMAIN = '58PwtjSDuFHuUkYjH9BYnnQKHfwo9reZhC2zMJv9JPkx'
+/** 反查记录的 class（同时是 SNS 注册程序的中心状态账户） */
+const REVERSE_LOOKUP_CLASS = '33m47vH6Eav6jr5Ry86XjhRft2jRBLDnDgPSHoquXi2Z'
+/** V2 记录的 class：sns-records 程序（HP3D4D1Z…）的中心状态 PDA */
+const RECORDS_V2_CLASS = '2pMnqHvei2N5oDcVGCRdZx48gqti199wr5CsyTTafsbo'
+/** 主域名（favourite domain）所在的程序 */
+const PRIMARY_DOMAIN_PROGRAM = '85iDfUvr3HJyLM2zcq5BXSiDvUWfw6cSE1FfNBo8Ap29'
+/** 域名代币化（NFT）程序 */
+const NAME_TOKENIZER_ID = 'nftD3vbNkNqfj2Sd3HZwbpw4BxxKWr4AjGb9X38JeZk'
+/** 名字账户的头部：parent（32）+ owner（32）+ class（32），之后是数据 */
+const HEADER_LEN = 96
+
+const encoder = new TextEncoder()
+const ZERO = new Uint8Array(32)
+
+export interface NamesOptions extends RequestOptions {
+  /**
+   * 也按 SNS 解析 `.sol` 名字（当作同名的 `.sns`）。默认 false：`.sol` 正在迁到另一个注册服务（SRS），
+   * SNS 官方 SDK 从 slot 452,825,395（约 2026-10-15）起不再解析 `.sol`，以后同一个 `.sol` 名字可能属于别人
+   */
+  legacySol?: boolean
+  /**
+   * 域名的 owner 是 PDA（程序账户，不是钱包）时也作为地址返回，默认 false（与官方 SDK 一致：转给 PDA 的资产可能取不出来，address 为 null）
+   */
+  allowPda?: boolean
+}
+
+/**
+ * 地址的来源（与 SNS 官方 SDK 的解析顺序相同）：
+ * - nft：域名代币化成了 NFT，地址是 NFT 的持有人（要用 getTokenLargestAccounts 找，节点不支持时 address 为 null）
+ * - record-v2 / record-v1：域名设置的 SOL 记录（V2 要求 owner 验证过、没有过期；V1 要求 owner 的签名）
+ * - owner：域名的 owner
+ */
+export type NameSource = 'nft' | 'record-v2' | 'record-v1' | 'owner'
+
+export interface ResolvedName {
+  /** 传入的名字（原样） */
+  name: string
+  /** 规范化后的名字（小写、去掉空格，后缀为 .sns）；名字不合法时为 null */
+  normalized: string | null
+  /** 解析出的地址（SOL 记录，没有时为 owner）；没有注册、名字不合法、记录不合法时为 null */
+  address: string | null
+  /** 域名的 owner（代币化的域名是 NFT 的持有人） */
+  owner: string | null
+  source: NameSource | null
+  /** 解析这个名字的服务（'sns'）；名字不归 SNS 管时为 null */
+  service: 'sns' | null
+}
+
+export interface AddressName {
+  /** 传入的地址（原样） */
+  address: string
+  /** 主域名（如 'bonfida.sns'），核对过属于这个地址；没有设置或已经转给别人时为 null */
+  name: string | null
+  service: 'sns' | null
+}
+
+const hashName = (name: string) => sha256(encoder.encode(`SPL Name Service${name}`))
+
+/** 名字账户：sha256('SPL Name Service' + name)、class、parent 推导的 PDA（没有 class / parent 时用 32 个 0） */
+function nameAccount(name: string, nameClass?: string, parent?: string): string {
+  return findProgramAddress([hashName(name), nameClass ? decodeAddress(nameClass) : ZERO, parent ? decodeAddress(parent) : ZERO], NAME_PROGRAM_ID)
+}
+
+/** 域名对应的名字账户：'bonfida' 或子域名 'sub.bonfida'（不带后缀）；子域名的种子是 '\0' + 子域名，parent 是父域名 */
+export function snsDomainKey(domain: string): { key: string; parent: string | null } {
+  const labels = domain.split('.')
+  if (labels.length === 2) {
+    const parent = nameAccount(labels[1] as string, undefined, SNS_ROOT_DOMAIN)
+    return { key: nameAccount(`\0${labels[0]}`, undefined, parent), parent }
+  }
+  if (labels.length !== 1) {
+    throw new Error(`Invalid SNS domain: ${domain}`)
+  }
+  return { key: nameAccount(domain, undefined, SNS_ROOT_DOMAIN), parent: null }
+}
+
+/** 反查记录：sha256 的是名字账户地址的 base58，class 是 REVERSE_LOOKUP_CLASS，子域名的 parent 是父域名 */
+function reverseKey(domainKey: string, parent?: string | null): string {
+  return nameAccount(domainKey, REVERSE_LOOKUP_CLASS, parent ?? undefined)
+}
+
+/** 规范化：小写、去掉首尾空格；只认 name.sns / sub.name.sns（legacySol 时也认 .sol），返回不带后缀的部分 */
+function parseName(name: string, legacySol: boolean): { domain: string; normalized: string } | null {
+  const n = name.trim().toLowerCase()
+  const suffix = n.endsWith('.sns') ? '.sns' : legacySol && n.endsWith('.sol') ? '.sol' : null
+  if (!suffix) {
+    return null
+  }
+  const domain = n.slice(0, -suffix.length)
+  const labels = domain.split('.')
+  if (labels.length > 2 || labels.some((l) => !l || l.includes('\0'))) {
+    return null
+  }
+  return { domain, normalized: `${domain}.sns` }
+}
+
+interface Registry {
+  parent: string
+  owner: string
+  data: Uint8Array
+}
+
+function registryOf(account: AccountInfo | null | undefined): Registry | null {
+  if (!account || account.owner !== NAME_PROGRAM_ID || account.data.length < HEADER_LEN) {
+    return null
+  }
+  return { parent: encodeAddress(account.data.slice(0, 32)), owner: encodeAddress(account.data.slice(32, 64)), data: account.data.slice(HEADER_LEN) }
+}
+
+/** NftRecord：tag（1）+ nonce（1）+ 名字账户（32）+ owner（32）+ NFT mint（32）；tag 2 表示域名正在代币化 */
+function tokenized(account: AccountInfo | null | undefined): boolean {
+  return !!account && account.owner === NAME_TOKENIZER_ID && account.data[0] === 2
+}
+
+const nftRecordKey = (domainKey: string) => findProgramAddress([encoder.encode('nft_record'), decodeAddress(domainKey)], NAME_TOKENIZER_ID)
+const nftMint = (domainKey: string) => findProgramAddress([encoder.encode('tokenized_name'), decodeAddress(domainKey)], NAME_TOKENIZER_ID)
+
+/** 记录账户：V1 的种子是 '\x01' + 记录名，parent 是域名；V2 是 '\x02' + 记录名，class 是 RECORDS_V2_CLASS */
+const recordV1Key = (domainKey: string, record: string) => nameAccount(`\x01${record}`, undefined, domainKey)
+const recordV2Key = (domainKey: string, record: string) => nameAccount(`\x02${record}`, RECORDS_V2_CLASS, domainKey)
+
+/** V2 记录的验证方式和对应 id 的长度：0 None，1 Solana（32），2 Ethereum（20），3 UnverifiedSolana（32） */
+const VALIDATION_LENGTH = [0, 32, 20, 32]
+const VALIDATION_SOLANA = 1
+
+/**
+ * V2 的 SOL 记录（与官方 SDK 相同）：数据是 u16 过期验证方式 + u16 关联验证方式 + u32 内容长度，然后是两个验证 id 和内容。
+ * 返回记录的地址；记录过期（过期验证的 id 不是当前 owner）时为 undefined（继续看 V1 / owner）；记录不合法时为 null（不解析）
+ */
+function solRecordV2(registry: Registry | null, owner: string): string | null | undefined {
+  if (!registry || registry.data.length < 8) {
+    return undefined
+  }
+  const view = new DataView(registry.data.buffer, registry.data.byteOffset, registry.data.byteLength)
+  const staleness = view.getUint16(0, true)
+  const roa = view.getUint16(2, true)
+  const stalenessLength = VALIDATION_LENGTH[staleness]
+  const roaLength = VALIDATION_LENGTH[roa]
+  if (stalenessLength === undefined || roaLength === undefined) {
+    return null
+  }
+  const body = registry.data.slice(8)
+  const content = body.slice(stalenessLength + roaLength)
+  if (content.length !== 32 || staleness !== VALIDATION_SOLANA || roa !== VALIDATION_SOLANA) {
+    return null
+  }
+  if (encodeAddress(body.slice(0, 32)) !== owner) {
+    return undefined // owner 换了：记录过期
+  }
+  // 关联验证的 id 必须就是内容本身（内容地址签过名）
+  return encodeAddress(body.slice(32, 64)) === encodeAddress(content) ? encodeAddress(content) : null
+}
+
+/** V1 的 SOL 记录：32 字节地址 + 64 字节 owner 的签名（签的是 hex(地址 ‖ 记录账户地址) 的 UTF-8）；签名不对时为 null */
+async function solRecordV1(registry: Registry | null, recordKey: string, owner: string): Promise<string | null> {
+  if (!registry || registry.data.length < 96) {
+    return null
+  }
+  const target = registry.data.slice(0, 32)
+  const signature = registry.data.slice(32, 96)
+  const hex = [...target, ...decodeAddress(recordKey)].map((b) => b.toString(16).padStart(2, '0')).join('')
+  return (await verifyEd25519(decodeAddress(owner), signature, encoder.encode(hex))) ? encodeAddress(target) : null
+}
+
+/** Ed25519 验签（WebCrypto）；运行环境不支持时当作验签失败 */
+async function verifyEd25519(publicKey: Uint8Array, signature: Uint8Array, message: Uint8Array): Promise<boolean> {
+  const subtle = globalThis.crypto?.subtle
+  if (!subtle) return false
+  try {
+    const key = await subtle.importKey('raw', publicKey as Uint8Array<ArrayBuffer>, { name: 'Ed25519' }, false, ['verify'])
+    return await subtle.verify('Ed25519', key, signature as Uint8Array<ArrayBuffer>, message as Uint8Array<ArrayBuffer>)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 代币化域名的 NFT 持有人：getTokenLargestAccounts 找到唯一的持有账户，再读出它的 owner（与官方 SDK 相同）。
+ * 免费公共节点大多不支持 getTokenLargestAccounts，这时为 null
+ */
+async function nftHolders(client: SolanaClient, domainKeys: readonly string[], signal: AbortSignal | undefined): Promise<Map<string, string | null>> {
+  const largest = await Promise.all(
+    domainKeys.map((key) =>
+      client
+        .request<{ value: Array<{ address: string; amount: string }> }>('getTokenLargestAccounts', [nftMint(key), { commitment: client.commitment }], { signal })
+        .then((res) => res.value.find((a) => a.amount === '1')?.address ?? null)
+        .catch((err: unknown) => {
+          if (signal?.aborted) throw err
+          return null
+        }),
+    ),
+  )
+  const holders = largest.filter((a): a is string => a !== null)
+  const accounts = holders.length ? await client.accounts(holders, { signal }) : []
+  const ownerOf = new Map(holders.map((a, i) => [a, accounts[i]?.owner === TOKEN_PROGRAM_ID ? encodeAddress((accounts[i] as AccountInfo).data.slice(32, 64)) : null]))
+  return new Map(domainKeys.map((key, i) => [key, largest[i] ? (ownerOf.get(largest[i] as string) ?? null) : null]))
+}
+
+/**
+ * 名字 → 地址（一次 getMultipleAccounts 读域名、NFT 记录、两版 SOL 记录；代币化的域名另外找 NFT 持有人）。
+ * 解析顺序同官方 SDK：代币化 → NFT 持有人；V2 SOL 记录（验证过、没过期）；V1 SOL 记录（owner 签过名）；owner（是 PDA 时默认不返回）
+ *
+ * ```ts
+ * await resolveNames(client, ['bonfida.sns', 'toly.sns'])
+ * // [{ name: 'bonfida.sns', normalized: 'bonfida.sns', address: 'Fw1E…Lb1v', owner: 'Fw1E…Lb1v', source: 'owner', service: 'sns' }, …]
+ * ```
+ */
+export async function resolveNames(client: SolanaClient, names: readonly string[], options: NamesOptions = {}): Promise<ResolvedName[]> {
+  const { signal, legacySol = false, allowPda = false } = options
+  const items = names.map((name) => {
+    const parsed = parseName(name, legacySol)
+    if (!parsed) return { name, parsed: null, key: null }
+    const { key } = snsDomainKey(parsed.domain)
+    return { name, parsed, key, nft: nftRecordKey(key), v1: recordV1Key(key, 'SOL'), v2: recordV2Key(key, 'SOL') }
+  })
+  const keys = items.flatMap((x) => (x.key ? [x.key, x.nft, x.v1, x.v2] : [])) as string[]
+  const accounts = keys.length ? await client.accounts(keys, { signal }) : []
+  const byKey = new Map(keys.map((k, i) => [k, accounts[i] ?? null]))
+  const nfts = items.filter((x) => x.key && registryOf(byKey.get(x.key)) && tokenized(byKey.get(x.nft as string))).map((x) => x.key as string)
+  const holders = nfts.length ? await nftHolders(client, nfts, signal) : new Map<string, string | null>()
+
+  return Promise.all(
+    items.map(async (x): Promise<ResolvedName> => {
+      const base = { name: x.name, normalized: x.parsed?.normalized ?? null, service: x.parsed ? ('sns' as const) : null }
+      const registry = x.key ? registryOf(byKey.get(x.key)) : null
+      if (!x.key || !registry) {
+        return { ...base, address: null, owner: null, source: null }
+      }
+      if (holders.has(x.key)) {
+        const holder = holders.get(x.key) ?? null
+        return { ...base, address: holder, owner: holder, source: 'nft' }
+      }
+      const owner = registry.owner
+      const v2 = solRecordV2(registryOf(byKey.get(x.v2 as string)), owner)
+      if (v2 !== undefined) {
+        return { ...base, address: v2, owner, source: 'record-v2' }
+      }
+      const v1 = await solRecordV1(registryOf(byKey.get(x.v1 as string)), x.v1 as string, owner)
+      if (v1) {
+        return { ...base, address: v1, owner, source: 'record-v1' }
+      }
+      return { ...base, address: allowPda || isOnCurve(decodeAddress(owner)) ? owner : null, owner, source: 'owner' }
+    }),
+  )
+}
+
+/** 反查记录的数据：u32 长度 + 名字（子域名的以 \0 开头） */
+function reverseName(account: AccountInfo | null | undefined): string | null {
+  const registry = registryOf(account)
+  if (!registry || registry.data.length < 4) {
+    return null
+  }
+  const length = new DataView(registry.data.buffer, registry.data.byteOffset).getUint32(0, true)
+  if (registry.data.length < 4 + length) {
+    return null
+  }
+  return new TextDecoder().decode(registry.data.slice(4, 4 + length)).replace(/^\0/, '') || null
+}
+
+/**
+ * 地址 → 主域名：读地址设置的主域名（favourite domain），再读域名和反查记录拼出名字，核对名字确实推导出这个域名账户、
+ * 并且域名属于这个地址（owner 是它，或代币化后它持有 NFT）——换了 owner 的旧设置不算。通常两次 getMultipleAccounts（子域名三次）
+ *
+ * ```ts
+ * await lookupAddresses(client, [wallet])   // [{ address: wallet, name: 'bonfida.sns', service: 'sns' }]
+ * ```
+ */
+export async function lookupAddresses(client: SolanaClient, addresses: readonly string[], options: RequestOptions = {}): Promise<AddressName[]> {
+  const { signal } = options
+  const wallets = [...new Set(addresses.filter((a) => isAddress(a)))]
+  const primaryKeys = wallets.map((w) => findProgramAddress([encoder.encode('favourite_domain'), decodeAddress(w)], PRIMARY_DOMAIN_PROGRAM))
+  const primaries = primaryKeys.length ? await client.accounts(primaryKeys, { signal }) : []
+  // 主域名账户：tag（1）+ 名字账户（32）
+  const chosen = wallets.flatMap((wallet, i) => {
+    const a = primaries[i]
+    return a && a.owner === PRIMARY_DOMAIN_PROGRAM && a.data.length >= 33 ? [{ wallet, domain: encodeAddress(a.data.slice(1, 33)) }] : []
+  })
+  // 先按顶级域名读反查记录（大多数情况）；是子域名时再读一次
+  const round2 = chosen.flatMap((c) => [c.domain, reverseKey(c.domain), getAssociatedTokenAddress(c.wallet, nftMint(c.domain), TOKEN_PROGRAM_ID)])
+  const accounts2 = round2.length ? await client.accounts(round2, { signal }) : []
+  const found = chosen.map((c, i) => ({ ...c, registry: registryOf(accounts2[3 * i]), reverse: accounts2[3 * i + 1] ?? null, nft: accounts2[3 * i + 2] ?? null }))
+  const subs = found.filter((f) => f.registry && f.registry.parent !== SNS_ROOT_DOMAIN)
+  const round3 = subs.flatMap((f) => [reverseKey(f.domain, f.registry?.parent), reverseKey(f.registry?.parent as string)])
+  const accounts3 = round3.length ? await client.accounts(round3, { signal }) : []
+  const subNames = new Map(
+    subs.map((f, i) => {
+      const [sub, parent] = [reverseName(accounts3[2 * i]), reverseName(accounts3[2 * i + 1])]
+      return [f, sub && parent ? `${sub}.${parent}` : null]
+    }),
+  )
+
+  const names = new Map<string, string>()
+  for (const f of found) {
+    if (!f.registry) continue
+    const domain = f.registry.parent === SNS_ROOT_DOMAIN ? reverseName(f.reverse) : (subNames.get(f) ?? null)
+    if (!domain) continue
+    // 正查核对：名字推导出的账户就是主域名指向的账户（反查记录的内容格式不对时不会拼出别的名字）
+    let key: string
+    try {
+      key = snsDomainKey(domain).key
+    } catch {
+      continue
+    }
+    // 代币化的域名：钱包的 ATA 里有这个域名的 NFT（数量 1）
+    const holdsNft = !!f.nft && f.nft.owner === TOKEN_PROGRAM_ID && f.nft.data.length >= 72 && new DataView(f.nft.data.buffer, f.nft.data.byteOffset).getBigUint64(64, true) === 1n
+    if (key === f.domain && (f.registry.owner === f.wallet || holdsNft)) {
+      names.set(f.wallet, `${domain}.sns`)
+    }
+  }
+  return addresses.map((address) => {
+    const name = names.get(address) ?? null
+    return { address, name, service: name ? 'sns' : null }
+  })
+}

package/src/pools.ts

@@ -0,0 +1,43 @@
+/**
+ * 按两个 mint 推导池子地址（PDA，不需要 getProgramAccounts）：Raydium CLMM / CPMM 的每个 AmmConfig、Orca 的每个费率档位。
+ * 链上价格（/price）和兑换（/swap）共用；Raydium AMM v4 的池子地址要用 OpenBook 市场推导，不在这里
+ */
+import { decodeAddress, findProgramAddress } from './address.js'
+import { ORCA_WHIRLPOOL_PROGRAM_ID, RAYDIUM_CLMM_PROGRAM_ID, RAYDIUM_CPMM_PROGRAM_ID, utf8 } from './lp.js'
+
+export type PdaPoolProtocol = 'raydium-clmm' | 'orca-whirlpool' | 'raydium-cpmm'
+
+/** Orca 默认的 WhirlpoolsConfig */
+export const ORCA_WHIRLPOOLS_CONFIG = '2LecshUwdy9xi7meFgHtFJQNSKk4KdTrcpvaB56dP2NQ'
+/**
+ * 池子 PDA 用到的配置（2026-10 主网实测存在的全部）：
+ * - Raydium CLMM / CPMM 的 AmmConfig：PDA ["amm_config", index（u16 大端）]，index 0~20
+ * - Orca 的费率档位：普通档位的种子是 tick spacing（1、2、4、8、16、64、96、128、256，32896 为 Splash 池），动态费率档位是 1025~1036
+ * Raydium CLMM 用 seed_index 建的自定义池子不在推导范围内
+ */
+const RAYDIUM_CONFIG_COUNT = 21
+const ORCA_FEE_TIERS = [1, 2, 4, 8, 16, 64, 96, 128, 256, 32896, ...Array.from({ length: 12 }, (_, i) => 1025 + i)]
+
+let configs: { clmm: Uint8Array[]; cpmm: Uint8Array[]; orca: Uint8Array } | undefined
+function poolConfigs() {
+  const derive = (program: string) =>
+    Array.from({ length: RAYDIUM_CONFIG_COUNT }, (_, i) => decodeAddress(findProgramAddress([utf8('amm_config'), new Uint8Array([i >> 8, i & 0xff])], program)))
+  configs ??= { clmm: derive(RAYDIUM_CLMM_PROGRAM_ID), cpmm: derive(RAYDIUM_CPMM_PROGRAM_ID), orca: decodeAddress(ORCA_WHIRLPOOLS_CONFIG) }
+  return configs
+}
+
+/** 两个 mint 在这些协议里可能的池子地址（三个程序都要求 mint0 < mint1，按字节比较）；两个 mint 相同时为空 */
+export function poolAddresses(mintA: string, mintB: string, protocols: ReadonlySet<PdaPoolProtocol>): Array<{ protocol: PdaPoolProtocol; address: string }> {
+  const a = decodeAddress(mintA)
+  const b = decodeAddress(mintB)
+  const i = a.findIndex((byte, k) => byte !== b[k])
+  if (i < 0) return []
+  const [m0, m1] = (a[i] as number) < (b[i] as number) ? [a, b] : [b, a]
+  const { clmm, cpmm, orca } = poolConfigs()
+  const out: Array<{ protocol: PdaPoolProtocol; address: string }> = []
+  const add = (protocol: PdaPoolProtocol, seeds: Uint8Array[], program: string) => out.push({ protocol, address: findProgramAddress(seeds, program) })
+  if (protocols.has('raydium-clmm')) for (const c of clmm) add('raydium-clmm', [utf8('pool'), c, m0, m1], RAYDIUM_CLMM_PROGRAM_ID)
+  if (protocols.has('raydium-cpmm')) for (const c of cpmm) add('raydium-cpmm', [utf8('pool'), c, m0, m1], RAYDIUM_CPMM_PROGRAM_ID)
+  if (protocols.has('orca-whirlpool')) for (const t of ORCA_FEE_TIERS) add('orca-whirlpool', [utf8('whirlpool'), orca, m0, m1, new Uint8Array([t & 0xff, t >> 8])], ORCA_WHIRLPOOL_PROGRAM_ID)
+  return out
+}

package/src/portfolio.ts

@@ -0,0 +1,124 @@
+/**
+ * 资产总值（子路径 `@w3lib/solana-batch-call/price`）：代币余额 × 价格，可选加上 LP 仓位的价值
+ */
+import type { RequestOptions, SolanaClient } from './client.js'
+import { lpPositions, methodUnavailable, type LpPositionsOptions, type SolanaLpPosition } from './lp.js'
+import { combinePrices, defillamaPrices, onchainPrices, tokenPrices, type SolanaPriceSource } from './price.js'
+
+export interface PortfolioOptions extends RequestOptions {
+  /**
+   * 要计入的代币（SOL 用 NATIVE_MINT），按关联代币账户（ATA）读余额，免费公共节点也能用。
+   * 不传时列出地址持有的全部代币（同 getOwnerTokens，含 SOL，不含 NFT），需要支持 getTokenAccountsByOwner 的节点
+   */
+  tokens?: readonly string[]
+  /** 价格源，依次使用，默认 [defillamaPrices(), onchainPrices()] */
+  sources?: readonly SolanaPriceSource[]
+  /**
+   * 同时计入 LP 仓位（参数同 lpPositions，价格源用上面的 sources），默认不计入。
+   * 注意 lpPositions 不传 mints 时也要扫描代币账户：免费公共节点上传 { mints: [仓位 NFT / LP mint], pools: [AMM 池子] }
+   */
+  lp?: boolean | Omit<LpPositionsOptions, 'prices' | 'onPriceError' | 'fetch' | 'signal'>
+  /** 价值低于它的代币不列出（不影响合计），默认 0 */
+  minUsd?: number
+  /** 某个价格源出错时调用；回调本身出错会被忽略 */
+  onPriceError?: (err: unknown) => void
+  /** 查价格用的 fetch，默认全局 fetch */
+  fetch?: typeof fetch
+}
+
+export interface PortfolioToken {
+  /** 代币的 mint；SOL 为 NATIVE_MINT（或传入的 nativeMints 里的地址） */
+  token: string
+  /** 原生 SOL；Wrapped SOL 的代币账户单独列出（native: false），价格同 SOL */
+  native: boolean
+  symbol: string | null
+  balance: string
+  decimals: number
+  formatted: string
+  price: number | null
+  /** 美元价值；没有价格时为 null */
+  value: number | null
+  /** 给出价格的价格源 */
+  priceSource: string | null
+}
+
+export interface Portfolio {
+  /** 合计（代币 + LP；没有价格的不计入） */
+  totalUsd: number
+  tokensUsd: number
+  lpUsd: number
+  /** 有余额的代币，按价值从高到低 */
+  tokens: PortfolioToken[]
+  /** LP 仓位（开启 lp 时） */
+  lp: SolanaLpPosition[]
+  /** 有余额但没有价格的代币数（LP 仓位里缺价格的也算） */
+  unpriced: number
+}
+
+interface Held {
+  token: string
+  native: boolean
+  symbol: string | null
+  balance: string
+  decimals: number
+  formatted: string
+}
+
+/**
+ * 一个地址的资产总值：代币余额 × 价格，可选加上 LP 仓位。
+ *
+ * ```ts
+ * const p = await portfolio(client, owner, { tokens: [NATIVE_MINT, USDC, JUP] })   // 指定代币：免费公共节点也能用
+ * const all = await portfolio(new SolanaClient('https://my-rpc…'), owner, { lp: true })   // 全部持仓 + LP：需要支持 getTokenAccountsByOwner 的节点
+ * p.totalUsd  // 1234.5
+ * ```
+ */
+export async function portfolio(client: SolanaClient, owner: string, options: PortfolioOptions = {}): Promise<Portfolio> {
+  const { tokens, sources = [defillamaPrices(), onchainPrices()], lp, minUsd = 0, onPriceError, fetch: fetchFn, signal } = options
+  // 回调本身出错由 combinePrices / lpPositions 忽略
+  const onError = onPriceError ? (_: SolanaPriceSource, err: unknown) => onPriceError(err) : undefined
+  const [balances, positions] = await Promise.all([
+    holdings(client, owner, tokens, signal),
+    lp
+      ? lpPositions(client, owner, { ...(lp === true ? {} : lp), prices: combinePrices(sources, { onError }), fetch: fetchFn, onPriceError, signal })
+      : Promise.resolve([]),
+  ])
+  // 列出全部持仓时，LP 代币已经按仓位计入，不再作为代币重复计算
+  const lpMints = new Set(positions.flatMap((p) => (p.type === 'amm' ? [p.lpMint] : [])))
+  const held = balances.filter((b) => BigInt(b.balance) > 0n && !(tokens === undefined && lpMints.has(b.token)))
+  const prices = held.length ? await tokenPrices(client, held.map((b) => b.token), { sources, onError, fetch: fetchFn, signal }) : []
+  const list: PortfolioToken[] = held.map((b, i) => {
+    const p = prices[i]
+    const price = p?.price ?? null
+    return { ...b, price, value: price === null ? null : Number(b.formatted) * price, priceSource: p?.source ?? null }
+  })
+  const tokensUsd = list.reduce((sum, t) => sum + (t.value ?? 0), 0)
+  const lpUsd = positions.reduce((sum, p) => sum + (p.valueUsd ?? 0), 0)
+  return {
+    totalUsd: tokensUsd + lpUsd,
+    tokensUsd,
+    lpUsd,
+    tokens: list.filter((t) => (t.value ?? 0) >= minUsd || (minUsd === 0 && t.value === null)).sort((a, b) => (b.value ?? -1) - (a.value ?? -1)),
+    lp: positions,
+    unpriced: list.filter((t) => t.price === null).length + positions.filter((p) => p.valueUsd === null).length,
+  }
+}
+
+/** 余额：传 tokens 时读这些代币的 ATA，否则列出全部持仓 */
+async function holdings(client: SolanaClient, owner: string, tokens: readonly string[] | undefined, signal: AbortSignal | undefined): Promise<Held[]> {
+  if (tokens) {
+    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 },
+    )
+  })
+  return owned.map((t) => ({ token: t.token, native: t.native, symbol: t.symbol ?? null, balance: t.balance, decimals: t.decimals, formatted: t.formatted }))
+}