@w3lib/solana-batch-call 0.0.0-stage → 0.2.0

package/src/shortcuts.ts

@@ -0,0 +1,367 @@
+import {
+  SolanaClient,
+  type BalanceQuery,
+  type BalancesOptions,
+  type ClientConfig,
+  type OwnerTokensOptions,
+  type RequestOptions,
+  type SolBalancesOptions,
+  type TokensOptions,
+} from './client.js'
+import type { RpcSource } from './source.js'
+import type { DefaultTokenField, NftDetails, NftOwner, OwnedToken, SolBalance, TokenBalance, TokenDetails, TokenField } from './types.js'
+
+/** 各函数共用的节点参数 */
+export interface ShortcutOptions extends ClientConfig {
+  /**
+   * 节点：RPC URL、URL 数组（主节点 + 备用节点）、web3.js Connection、自定义传输（request(method, params)）。
+   * 不传则使用 cluster（默认 mainnet）的内置公共节点
+   */
+  provider?: RpcSource | readonly RpcSource[]
+}
+
+// 复用客户端：多次调用共享连接、批量合并与故障切换状态。按 “配置内容” 分组，组内 URL 按字符串、对象按引用（WeakMap）。
+// 配置里有函数（如自定义 fetch）或节点数组含对象时不缓存。
+const MAX_CACHED = 32
+
+interface ClientGroup {
+  byString: Map<string, SolanaClient>
+  byObject: WeakMap<object, SolanaClient>
+}
+
+const clientCache = new Map<string, ClientGroup>()
+
+function setBounded<K, V>(map: Map<K, V>, key: K, value: V): void {
+  map.set(key, value)
+  if (map.size > MAX_CACHED) {
+    map.delete(map.keys().next().value as K)
+  }
+}
+
+function configKey(config: ClientConfig): string | null {
+  try {
+    return JSON.stringify(config, (_key, value: unknown) => {
+      if (typeof value === 'function') {
+        throw new Error('not comparable')
+      }
+      return value
+    })
+  } catch {
+    return null
+  }
+}
+
+function sourceKey(source: ShortcutOptions['provider']): string | object | null {
+  if (source === undefined) {
+    return 'default'
+  }
+  if (typeof source === 'string') {
+    return `url:${source}`
+  }
+  if (Array.isArray(source)) {
+    return source.every((item) => typeof item === 'string') ? `urls:${source.join('\n')}` : null
+  }
+  return source as object
+}
+
+/**
+ * 拆出节点参数和函数自己的参数（ownKeys），其余作为客户端配置；值为 undefined 的参数忽略。
+ * signal 总是作为函数自己的参数（放进客户端配置会让每次调用都新建客户端）
+ */
+function resolve<T extends ShortcutOptions, K extends keyof T & string = never>(
+  options: T,
+  ownKeys: readonly K[] = [],
+): { client: SolanaClient; own: Pick<T, K> } {
+  const { provider, ...others } = options
+  const own: Record<string, unknown> = {}
+  const config: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(others)) {
+    if (value !== undefined) {
+      ;((ownKeys as readonly string[]).includes(key) ? own : key === 'signal' ? {} : config)[key] = value
+    }
+  }
+  return { client: getClient(provider, config as ClientConfig), own: own as Pick<T, K> }
+}
+
+function getClient(source: ShortcutOptions['provider'], config: ClientConfig): SolanaClient {
+  const cfg = configKey(config)
+  const key = sourceKey(source)
+  if (cfg === null || key === null) {
+    return new SolanaClient(source, config)
+  }
+  let group = clientCache.get(cfg)
+  if (!group) {
+    group = { byString: new Map(), byObject: new WeakMap() }
+    setBounded(clientCache, cfg, group)
+  }
+  let client = typeof key === 'string' ? group.byString.get(key) : group.byObject.get(key)
+  if (!client) {
+    client = new SolanaClient(source, config)
+    if (typeof key === 'string') {
+      setBounded(group.byString, key, client)
+    } else {
+      group.byObject.set(key, client)
+    }
+  }
+  return client
+}
+
+export interface GetBalancesOptions extends BalancesOptions, ShortcutOptions {}
+
+/**
+ * 批量查余额（SOL + SPL Token + Token-2022），返回原始余额、decimals 和换算后的数值。
+ *
+ * ```ts
+ * import { NATIVE_MINT, getBalances } from '@w3lib/solana-batch-call'
+ *
+ * await getBalances(owner, [NATIVE_MINT, USDC])                        // 指定代币：免费公共节点也能用
+ * await getBalances(owner, [NATIVE_MINT, USDC], { symbol: true })
+ * await getBalances(owner, undefined, { tokenPrograms: ['spl'] })            // 不含 Token-2022 代币
+ * await getBalances(owner, [USDC], { accounts: 'all' })                      // 算上非 ATA 账户：需要支持 getTokenAccountsByOwner 的节点
+ * await getBalances(owner, undefined, { provider: 'https://my-rpc…' })  // 全部持仓：需要支持 getTokenAccountsByOwner 的节点
+ * ```
+ */
+export function getBalances(owner: string, mints?: readonly string[], options: GetBalancesOptions = {}): Promise<TokenBalance[]> {
+  const { client, own } = resolve(options, BALANCE_KEYS)
+  return client.balances(owner, mints, own)
+}
+
+const BALANCE_KEYS = ['symbol', 'scan', 'accounts', 'tokenPrograms', 'signal', 'minContextSlot', 'withSlot'] as const
+
+/**
+ * 多个钱包一次查，结果与 queries 一一对应；ATA 模式下所有钱包合并成一次 getMultipleAccounts。参数同 getBalances。
+ *
+ * ```ts
+ * await getMultiBalances([{ owner: a, mints: [NATIVE_MINT, USDC] }, { owner: b, mints: [USDC] }])
+ * ```
+ */
+export function getMultiBalances(queries: readonly BalanceQuery[], options: GetBalancesOptions = {}): Promise<TokenBalance[][]> {
+  const { client, own } = resolve(options, BALANCE_KEYS)
+  return client.multiBalances(queries, own)
+}
+
+export interface GetSolBalancesOptions extends SolBalancesOptions, ShortcutOptions {}
+
+/** 批量查多个地址的 SOL 余额（一次 getMultipleAccounts） */
+export function getSolBalances(addresses: readonly string[], options: GetSolBalancesOptions = {}): Promise<SolBalance[]> {
+  const { client, own } = resolve(options, ['signal', 'minContextSlot', 'withSlot'])
+  return client.solBalances(addresses, own)
+}
+
+export interface GetTokensOptions<F extends TokenField = DefaultTokenField> extends TokensOptions<F>, ShortcutOptions {}
+
+/**
+ * 批量查代币详情，字段可选（默认 name / symbol / decimals）。
+ *
+ * ```ts
+ * await getTokens([USDC, PYUSD], { fields: ['name', 'symbol', 'decimals', 'supply', 'tokenProgram'] })
+ * ```
+ */
+export function getTokens<const F extends TokenField = DefaultTokenField>(mints: readonly string[], options: GetTokensOptions<F> = {}): Promise<TokenDetails<F>[]> {
+  const { client, own } = resolve(options, ['fields', 'signal'])
+  return client.tokens<F>(mints, own)
+}
+
+export interface GetNftsOptions extends RequestOptions, ShortcutOptions {}
+
+/** 批量查 NFT 元数据（名称、uri、所属集合、版税、创作者等） */
+export function getNfts(mints: readonly string[], options: GetNftsOptions = {}): Promise<NftDetails[]> {
+  const { client, own } = resolve(options, ['signal'])
+  return client.nfts(mints, own)
+}
+
+/** 批量查 NFT 持有人 */
+export function getNftOwners(mints: readonly string[], options: GetNftsOptions = {}): Promise<NftOwner[]> {
+  const { client, own } = resolve(options, ['signal'])
+  return client.nftOwners(mints, own)
+}
+
+/** 查某地址持有的全部 NFT（需要支持 getTokenAccountsByOwner 的节点） */
+export function getOwnerNfts(owner: string, options: GetNftsOptions = {}): Promise<NftDetails[]> {
+  const { client, own } = resolve(options, ['signal'])
+  return client.ownerNfts(owner, own)
+}
+
+export interface GetOwnerTokensOptions extends OwnerTokensOptions, ShortcutOptions {}
+
+/**
+ * 列出持有人拥有的全部代币（SOL 在第一位），带 name / symbol，适合做资产列表。
+ * 需要支持 getTokenAccountsByOwner 的节点。
+ *
+ * ```ts
+ * await getOwnerTokens(owner, { provider: 'https://my-rpc…' })
+ * // [{ token: NATIVE_MINT, native: true, name: 'Solana', symbol: 'SOL', formatted: '1.5', … }, { token: USDC, name: 'USD Coin', … }]
+ * ```
+ */
+export function getOwnerTokens(owner: string, options: GetOwnerTokensOptions = {}): Promise<OwnedToken[]> {
+  const { client, own } = resolve(options, ['metadata', 'includeNative', 'includeZero', 'includeNfts', 'tokenPrograms', 'signal', 'minContextSlot', 'withSlot'])
+  return client.ownerTokens(owner, own)
+}
+
+export interface WatchBalancesOptions extends Omit<GetBalancesOptions, 'signal' | 'minContextSlot'> {
+  /** 轮询间隔（毫秒），默认 15000；多处订阅同一份时取最小的 */
+  interval?: number
+  /** 第一次拿到结果、以及之后余额（balance）变化时调用；previous 是上一次通知的结果（第一次为 null） */
+  onChange: (balances: TokenBalance[], previous: TokenBalance[] | null) => void
+  /** 某次轮询失败时调用（之后照常继续轮询） */
+  onError?: (err: unknown) => void
+}
+
+interface Watcher {
+  interval: number
+  onChange: WatchBalancesOptions['onChange']
+  onError?: WatchBalancesOptions['onError']
+}
+
+interface Watch {
+  client: SolanaClient
+  owner: string
+  mints: readonly string[] | undefined
+  options: BalancesOptions
+  watchers: Set<Watcher>
+  timer: ReturnType<typeof setTimeout> | null
+  running: boolean
+  stopped: boolean
+  last: TokenBalance[] | null
+  lastKey: string | null
+}
+
+// 共享轮询：按客户端（同样的节点配置会复用同一个客户端）+ owner + mints（顺序无关）+ 影响结果的选项
+const watches = new WeakMap<SolanaClient, Map<string, Watch>>()
+
+/**
+ * 轮询余额，多处订阅同一个钱包时合并成一份轮询，只在余额变化时通知。返回取消订阅的函数；最后一个订阅者取消时停止轮询。
+ * 参数同 getBalances（不支持 signal / minContextSlot）；上一次请求没完成时不会发起下一次。
+ * 结果顺序按第一个订阅者传的 mints；新订阅者加入时如果已有结果，立即收到一次（previous 为 null）
+ *
+ * ```ts
+ * const stop = watchBalances(owner, [NATIVE_MINT, USDC], { interval: 10_000, onChange: (list) => render(list) })
+ * stop()
+ * ```
+ */
+export function watchBalances(owner: string, mints: readonly string[] | undefined, options: WatchBalancesOptions): () => void {
+  const { onChange, onError, interval = 15_000, ...rest } = options
+  if (!(interval > 0)) {
+    throw new Error(`Invalid interval: ${interval}`)
+  }
+  const { client, own } = resolve(rest, ['symbol', 'scan', 'accounts', 'tokenPrograms', 'withSlot'])
+  const key = JSON.stringify([
+    owner,
+    mints === undefined ? null : [...new Set(mints)].sort(),
+    own.symbol ?? false,
+    own.scan ?? false,
+    own.accounts ?? 'ata',
+    own.tokenPrograms === undefined ? null : [...own.tokenPrograms].sort(),
+    own.withSlot ?? false,
+  ])
+  let group = watches.get(client)
+  if (!group) {
+    group = new Map()
+    watches.set(client, group)
+  }
+  let watch = group.get(key)
+  const watcher: Watcher = { interval, onChange, onError }
+  if (!watch) {
+    watch = { client, owner, mints, options: own, watchers: new Set([watcher]), timer: null, running: false, stopped: false, last: null, lastKey: null }
+    group.set(key, watch)
+    poll(watch)
+  } else {
+    watch.watchers.add(watcher)
+    const current = watch
+    if (current.last) {
+      const last = current.last
+      queueMicrotask(() => current.watchers.has(watcher) && safely(() => watcher.onChange(last, null)))
+    }
+    // 间隔变小：按新的间隔重新安排下一次
+    if (current.timer && interval < nextInterval(current, watcher)) {
+      clearTimeout(current.timer)
+      current.timer = null
+      schedule(current)
+    }
+  }
+  const owned = watch
+  const ownedGroup = group
+  return () => {
+    if (!owned.watchers.delete(watcher) || owned.watchers.size) {
+      return
+    }
+    owned.stopped = true
+    if (owned.timer) {
+      clearTimeout(owned.timer)
+      owned.timer = null
+    }
+    if (ownedGroup.get(key) === owned) {
+      ownedGroup.delete(key)
+    }
+  }
+}
+
+/** 除了 except 以外订阅者的最小间隔（用于判断新订阅者是否让间隔变小） */
+function nextInterval(watch: Watch, except?: Watcher): number {
+  let min = Number.POSITIVE_INFINITY
+  for (const w of watch.watchers) {
+    if (w !== except) min = Math.min(min, w.interval)
+  }
+  return min
+}
+
+function schedule(watch: Watch): void {
+  if (watch.stopped || watch.timer || watch.running) {
+    return
+  }
+  watch.timer = setTimeout(() => poll(watch), nextInterval(watch))
+}
+
+function poll(watch: Watch): void {
+  watch.timer = null
+  if (watch.running || watch.stopped) {
+    return
+  }
+  watch.running = true
+  watch.client
+    .balances(watch.owner, watch.mints, watch.options)
+    .then(
+      (balances) => {
+        // 只比较余额（slot 每次都会变）
+        const key = JSON.stringify(balances.map((b) => [b.token, b.balance, b.success]))
+        if (watch.stopped || key === watch.lastKey) {
+          return
+        }
+        const previous = watch.last
+        watch.last = balances
+        watch.lastKey = key
+        for (const w of [...watch.watchers]) {
+          safely(() => w.onChange(balances, previous))
+        }
+      },
+      (err: unknown) => {
+        if (!watch.stopped) {
+          for (const w of [...watch.watchers]) {
+            safely(() => w.onError?.(err))
+          }
+        }
+      },
+    )
+    .finally(() => {
+      watch.running = false
+      schedule(watch)
+    })
+}
+
+function safely(fn: () => void): void {
+  try {
+    fn()
+  } catch {
+    // 订阅者的回调出错不影响轮询
+  }
+}
+
+/** 测试用：按参数取（或创建）客户端，用于验证缓存复用（不在包的公开导出里） */
+export function resolveClientForTest(options: ShortcutOptions): SolanaClient {
+  return resolve(options).client
+}
+
+/** 测试用：清空客户端缓存 */
+export function resetClientCache(): void {
+  clientCache.clear()
+}

package/src/source.ts

@@ -0,0 +1,149 @@
+import { DEFAULT_RPC_URLS, GENESIS_HASHES, type Cluster } from './constants.js'
+import { FallbackRpc, HttpRpc, type FallbackOptions, type HttpRpcOptions, type RpcTransport } from './rpc.js'
+
+/**
+ * 节点来源（也可以传数组：主节点 + 备用节点）：
+ * - RPC URL 字符串
+ * - @solana/web3.js 的 Connection（使用其 rpcEndpoint）
+ * - 自定义传输：实现 `request(method, params)` 的对象（如包一层 @solana/kit 的 rpc）
+ */
+export type RpcSource = string | RpcTransport | { rpcEndpoint: string }
+
+export interface SourceOptions extends HttpRpcOptions, FallbackOptions {}
+
+/** @param failFast 多个自定义节点时为 true：不在单节点内重试 429，直接切到下一个节点 */
+function toTransport(source: RpcSource, options: SourceOptions, failFast: boolean): RpcTransport {
+  if (typeof source === 'string') {
+    return new HttpRpc(source, { ...options, retries: failFast ? 0 : options.retries })
+  }
+  if (typeof (source as RpcTransport).request === 'function') {
+    return source as RpcTransport
+  }
+  const endpoint = (source as { rpcEndpoint?: unknown }).rpcEndpoint
+  if (typeof endpoint === 'string') {
+    return new HttpRpc(endpoint, { ...options, retries: failFast ? 0 : options.retries })
+  }
+  throw new Error('Unsupported RPC source: expected a URL, a web3.js Connection or an object with request(method, params)')
+}
+
+// 各节点的创世区块哈希缓存：失败（含超时）时删除，下次重试
+const genesisCache = new WeakMap<RpcTransport, Promise<string>>()
+
+export function genesisOf(transport: RpcTransport): Promise<string> {
+  let cached = genesisCache.get(transport)
+  if (!cached) {
+    const promise = transport.request<string>('getGenesisHash')
+    genesisCache.set(transport, promise)
+    promise.catch(() => {
+      if (genesisCache.get(transport) === promise) {
+        genesisCache.delete(transport)
+      }
+    })
+    cached = promise
+  }
+  return cached
+}
+
+/** 识别失败后多久内不再重试（期间请求照常发出，不做校验） */
+const CHECK_RETRY_INTERVAL = 60_000
+
+export class NetworkMismatchError extends Error {
+  constructor(expected: string, actual: string) {
+    super(`Network mismatch: expected genesis ${expected}, but the node is on ${actual}`)
+    this.name = 'NetworkMismatchError'
+  }
+}
+
+/**
+ * 校验节点所在的网络（创世区块哈希），避免把 devnet 的数据当成 mainnet 的返回。
+ * 校验与请求并行发出，不增加延迟；结果缓存，每个节点只多一次请求；识别失败时不拦截，并在一段时间内不再重试。
+ */
+export class NetworkCheckedRpc implements RpcTransport {
+  #checkFailedAt = 0
+
+  constructor(
+    readonly inner: RpcTransport,
+    readonly expected: () => Promise<string>,
+  ) {}
+
+  async #check(): Promise<void> {
+    if (this.#checkFailedAt && Date.now() - this.#checkFailedAt < CHECK_RETRY_INTERVAL) {
+      return
+    }
+    let expected: string
+    let actual: string
+    try {
+      ;[expected, actual] = await Promise.all([this.expected(), genesisOf(this.inner)])
+    } catch {
+      this.#checkFailedAt = Date.now()
+      return
+    }
+    this.#checkFailedAt = 0
+    if (expected !== actual) {
+      throw new NetworkMismatchError(expected, actual)
+    }
+  }
+
+  async request<T = unknown>(method: string, params?: readonly unknown[]): Promise<T> {
+    const [checked, result] = await Promise.allSettled([this.#check(), this.inner.request<T>(method, params)])
+    if (checked.status === 'rejected') {
+      throw checked.reason
+    }
+    if (result.status === 'rejected') {
+      throw result.reason
+    }
+    return result.value
+  }
+}
+
+export interface ResolvedSource {
+  transport: RpcTransport
+  /** 期望的创世区块哈希：指定了 cluster 时取对应值，否则取第一个响应节点的 */
+  genesis: () => Promise<string>
+}
+
+export function resolveSource(
+  source: RpcSource | readonly RpcSource[] | undefined,
+  cluster: Cluster | undefined,
+  options: SourceOptions = {},
+): ResolvedSource {
+  const isDefault = source === undefined
+  const list: readonly RpcSource[] = isDefault ? DEFAULT_RPC_URLS[cluster ?? 'mainnet'] : Array.isArray(source) ? source : [source as RpcSource]
+  if (!list.length) {
+    throw new Error('RPC source list is empty')
+  }
+  const multiple = list.length > 1
+  // 内置节点保留 429 重试：浏览器里官方节点总是 403，实际只有 publicnode 一个可用节点
+  const raw = list.map((item) => toTransport(item, options, multiple && !isDefault))
+
+  let detecting: Promise<string> | null = null
+  const genesis = (): Promise<string> => {
+    if (cluster) {
+      return Promise.resolve(GENESIS_HASHES[cluster])
+    }
+    if (!detecting) {
+      const promise = (async () => {
+        let lastError: unknown
+        for (const node of raw) {
+          try {
+            return await genesisOf(node)
+          } catch (err) {
+            lastError = err
+          }
+        }
+        throw lastError
+      })()
+      detecting = promise
+      promise.catch(() => {
+        if (detecting === promise) detecting = null
+      })
+    }
+    return detecting
+  }
+
+  // 内置节点本来就是按 cluster 选的，不校验；单个节点且没指定 cluster 时，期望值就是它自己，也不需要校验
+  const check = !isDefault && (multiple || cluster !== undefined)
+  const nodes = check ? raw.map((node) => new NetworkCheckedRpc(node, genesis)) : raw
+  // 单个节点也包一层 FallbackRpc：统一 onRequest 事件和健康状态（单节点失败时抛原始错误）
+  return { transport: new FallbackRpc(nodes, options), genesis }
+}

package/src/types.ts

@@ -0,0 +1,164 @@
+export type Commitment = 'processed' | 'confirmed' | 'finalized'
+
+/**
+ * tokenPrograms 参数的取值：简写 'spl'（SPL Token）/ 'token-2022'，也可以直接传程序地址
+ * （TOKEN_PROGRAM_ID / TOKEN_2022_PROGRAM_ID）
+ */
+export type TokenProgramName = 'spl' | 'token-2022'
+// (string & {})：保留 'spl' / 'token-2022' 的自动补全
+export type TokenProgramOption = TokenProgramName | (string & {})
+
+/**
+ * 单项失败（success: false）的原因：
+ * - invalid-address：地址格式非法（不是 base58 的 32 字节）
+ * - not-found：地址合法，但链上没有这个账户（如 mint 不存在）
+ * - not-token：账户存在，但不是代币 mint（或代币账户）
+ * - no-metadata：代币存在，但没有元数据（nfts）
+ * - no-holder：没有持有人（nftOwners：供应量为 0 或已销毁）
+ * - missing-field：代币存在，但请求的字段读不到（tokens），见 errorField
+ */
+export type FailureReason = 'invalid-address' | 'not-found' | 'not-token' | 'no-metadata' | 'no-holder' | 'missing-field'
+
+/** balances() 的单项结果，字段都是字符串 / 数字 / 布尔 / null，可以直接 JSON.stringify */
+export interface TokenBalance {
+  /** 代币的 mint（原样） */
+  token: string
+  /** 是否按原生 SOL 查询 */
+  native: boolean
+  /** 余额（最小单位的十进制字符串）；需要计算时用 BigInt(balance) */
+  balance: string
+  decimals: number
+  /** 按 decimals 换算后的十进制字符串，如 "1234.5"；整数不带小数点 */
+  formatted: string
+  /** 代币所属程序（SPL Token / Token-2022）；主币或未知时为 null */
+  tokenProgram: string | null
+  /** 仅在 symbol: true 时返回；读不到时为 null */
+  symbol?: string | null
+  /** 查询失败（mint 不存在、地址非法等）时为 false，balance / formatted 为 "0" */
+  success: boolean
+  /** 失败原因，仅 success 为 false 时返回 */
+  error?: FailureReason
+  /** 传了 withSlot / minContextSlot 时返回：读取时节点的 slot（一次查询发了多个请求时取最小的） */
+  slot?: number
+}
+
+/** ownerTokens() / getOwnerTokens() 的单项结果（总是 success: true） */
+export interface OwnedToken extends Omit<TokenBalance, 'symbol' | 'error'> {
+  /** 该代币的代币账户数量；大于 1 时 balance 为所有账户的合计 */
+  accounts: number
+  /** metadata 为 true（默认）时返回；没有元数据或读取失败时为 null（见 metadataStatus） */
+  name?: string | null
+  symbol?: string | null
+  /** metadata 为 true 时返回：ok 读到了；missing 确认没有元数据；failed 节点问题没能读到（可以稍后单独用 getTokens 重查） */
+  metadataStatus?: 'ok' | 'missing' | 'failed'
+}
+
+export interface SolBalance {
+  address: string
+  /** lamports（十进制字符串） */
+  balance: string
+  /** 按 9 位精度换算后的 SOL */
+  formatted: string
+  success: boolean
+  /** 失败原因（只有 invalid-address），仅 success 为 false 时返回 */
+  error?: FailureReason
+  /** 传了 withSlot / minContextSlot 时返回：读取时节点的 slot（多个请求时取最小的）；没有发请求（地址全部非法）时不返回 */
+  slot?: number
+}
+
+/** tokens() / getTokens() 可选的字段 */
+export type TokenField = 'name' | 'symbol' | 'uri' | 'decimals' | 'supply' | 'tokenProgram' | 'mintAuthority' | 'freezeAuthority' | 'transferFee'
+
+/** Token-2022 转账手续费的一套配置 */
+export interface TransferFee {
+  /** 费率，万分比（100 = 1%） */
+  basisPoints: number
+  /** 单笔最多收取的手续费（最小单位的十进制字符串） */
+  maximumFee: string
+  /** 从这个 epoch 开始生效 */
+  epoch: string
+}
+
+/**
+ * tokens() 的 transferFee 字段：顶层是**当前 epoch** 生效的配置（按 getEpochInfo 选 newer / older），
+ * older / newer 是扩展里的两套原始配置。收到的数量 = 转账数量 - min(数量 × basisPoints / 10000 向上取整, maximumFee)
+ */
+export interface TransferFeeConfig extends TransferFee {
+  older: TransferFee
+  newer: TransferFee
+}
+
+export const DEFAULT_TOKEN_FIELDS = ['name', 'symbol', 'decimals'] as const satisfies readonly TokenField[]
+
+export type DefaultTokenField = (typeof DEFAULT_TOKEN_FIELDS)[number]
+
+interface TokenFieldTypes {
+  /** 优先取 Token-2022 TokenMetadata 扩展，其次 Metaplex 元数据 */
+  name: string | null
+  symbol: string | null
+  uri: string | null
+  decimals: number | null
+  /** 最小单位的十进制字符串 */
+  supply: string | null
+  tokenProgram: string | null
+  /** 没有 mint 权限（已放弃）时为 null */
+  mintAuthority: string | null
+  freezeAuthority: string | null
+  /** Token-2022 转账手续费；SPL Token、没有这个扩展、主币时为 null（不算失败） */
+  transferFee: TransferFeeConfig | null
+}
+
+/**
+ * tokens() / getTokens() 的单项结果，只包含请求的字段。
+ * 请求 supply 时额外带 supplyFormatted（按 decimals 换算）。
+ */
+export type TokenDetails<F extends TokenField = DefaultTokenField> = {
+  /** mint 地址 */
+  address: string
+  native: boolean
+  /** mint 存在且请求的 name / symbol / uri / decimals / supply 都读到时为 true */
+  success: boolean
+  /** 失败原因，仅 success 为 false 时返回 */
+  error?: FailureReason
+  /** error 为 missing-field 时：第一个读不到的字段 */
+  errorField?: F
+} & { [K in F]: TokenFieldTypes[K] } & ('supply' extends F ? { supplyFormatted: string | null } : unknown)
+
+export type TokenStandard =
+  | 'NonFungible'
+  | 'FungibleAsset'
+  | 'Fungible'
+  | 'NonFungibleEdition'
+  | 'ProgrammableNonFungible'
+  | 'ProgrammableNonFungibleEdition'
+
+/** nfts() / getNfts() 的单项结果（Metaplex 元数据；Token-2022 NFT 只有 name / symbol / uri） */
+export interface NftDetails {
+  mint: string
+  name: string | null
+  symbol: string | null
+  /** 链下元数据 JSON 的地址 */
+  uri: string | null
+  /** 所属集合；verified 为 false 表示未经集合方签名确认 */
+  collection: { address: string; verified: boolean } | null
+  creators: Array<{ address: string; verified: boolean; share: number }>
+  /** 版税，万分比 */
+  sellerFeeBasisPoints: number | null
+  tokenStandard: TokenStandard | null
+  isMutable: boolean | null
+  updateAuthority: string | null
+  success: boolean
+  /** 失败原因，仅 success 为 false 时返回 */
+  error?: FailureReason
+}
+
+export interface NftOwner {
+  mint: string
+  /** 持有人钱包地址 */
+  owner: string | null
+  /** 持有该 NFT 的代币账户 */
+  tokenAccount: string | null
+  success: boolean
+  /** 失败原因，仅 success 为 false 时返回 */
+  error?: FailureReason
+}