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

package/src/shortcuts.ts

@@ -0,0 +1,173 @@
+import { SolanaClient, type BalancesOptions, type ClientConfig, type OwnerTokensOptions, 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 的参数忽略 */
+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 : 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, { provider: 'https://my-rpc…' })  // 全部持仓：需要支持 getTokenAccountsByOwner 的节点
+ * ```
+ */
+export function getBalances(owner: string, mints?: readonly string[], options: GetBalancesOptions = {}): Promise<TokenBalance[]> {
+  const { client, own } = resolve(options, ['symbol', 'scan'])
+  return client.balances(owner, mints, own)
+}
+
+/** 批量查多个地址的 SOL 余额（一次 getMultipleAccounts） */
+export function getSolBalances(addresses: readonly string[], options: ShortcutOptions = {}): Promise<SolBalance[]> {
+  return resolve(options).client.solBalances(addresses)
+}
+
+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'])
+  return client.tokens<F>(mints, { fields: own.fields })
+}
+
+/** 批量查 NFT 元数据（名称、uri、所属集合、版税、创作者等） */
+export function getNfts(mints: readonly string[], options: ShortcutOptions = {}): Promise<NftDetails[]> {
+  return resolve(options).client.nfts(mints)
+}
+
+/** 批量查 NFT 持有人 */
+export function getNftOwners(mints: readonly string[], options: ShortcutOptions = {}): Promise<NftOwner[]> {
+  return resolve(options).client.nftOwners(mints)
+}
+
+/** 查某地址持有的全部 NFT（需要支持 getTokenAccountsByOwner 的节点） */
+export function getOwnerNfts(owner: string, options: ShortcutOptions = {}): Promise<NftDetails[]> {
+  return resolve(options).client.ownerNfts(owner)
+}
+
+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'])
+  return client.ownerTokens(owner, own)
+}
+
+/** 测试用：按参数取（或创建）客户端，用于验证缓存复用（不在包的公开导出里） */
+export function resolveClientForTest(options: ShortcutOptions): SolanaClient {
+  return resolve(options).client
+}
+
+/** 测试用：清空客户端缓存 */
+export function resetClientCache(): void {
+  clientCache.clear()
+}

package/src/source.ts

@@ -0,0 +1,151 @@
+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
+  return {
+    transport: multiple ? new FallbackRpc(nodes, options) : (nodes[0] as RpcTransport),
+    genesis,
+  }
+}

package/src/types.ts

@@ -0,0 +1,108 @@
+export type Commitment = 'processed' | 'confirmed' | 'finalized'
+
+/** 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
+}
+
+/** ownerTokens() / getOwnerTokens() 的单项结果 */
+export interface OwnedToken extends Omit<TokenBalance, 'symbol'> {
+  /** 该代币的代币账户数量；大于 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
+}
+
+/** tokens() / getTokens() 可选的字段 */
+export type TokenField = 'name' | 'symbol' | 'uri' | 'decimals' | 'supply' | 'tokenProgram' | 'mintAuthority' | 'freezeAuthority'
+
+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
+}
+
+/**
+ * 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
+} & { [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
+}
+
+export interface NftOwner {
+  mint: string
+  /** 持有人钱包地址 */
+  owner: string | null
+  /** 持有该 NFT 的代币账户 */
+  tokenAccount: string | null
+  success: boolean
+}