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

package/src/constants.ts

@@ -0,0 +1,41 @@
+export const SYSTEM_PROGRAM_ID = '11111111111111111111111111111111'
+export const TOKEN_PROGRAM_ID = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'
+export const TOKEN_2022_PROGRAM_ID = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb'
+export const ASSOCIATED_TOKEN_PROGRAM_ID = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL'
+export const METADATA_PROGRAM_ID = 'metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s'
+
+/** Wrapped SOL 的 mint，按惯例也用来表示原生 SOL */
+export const NATIVE_MINT = 'So11111111111111111111111111111111111111112'
+
+/** 原生 SOL 的精度（lamports） */
+export const SOL_DECIMALS = 9
+
+export type Cluster = 'mainnet' | 'devnet' | 'testnet'
+
+/** 各网络的创世区块哈希（getGenesisHash），用于识别节点所在网络 */
+export const GENESIS_HASHES: Readonly<Record<Cluster, string>> = {
+  mainnet: '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d',
+  devnet: 'EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG',
+  testnet: '4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY',
+}
+
+export function clusterOfGenesis(hash: string): Cluster | null {
+  for (const [cluster, genesis] of Object.entries(GENESIS_HASHES)) {
+    if (genesis === hash) {
+      return cluster as Cluster
+    }
+  }
+  return null
+}
+
+/**
+ * 内置公共节点（按优先级排序，2026-10 实测）：
+ * - publicnode：放行跨域、支持批量请求，但不支持 getTokenAccountsByOwner 等需要索引的方法
+ * - 官方节点：对带浏览器 Origin 的请求返回 403，只能在服务端使用
+ * 公共节点限频严，生产环境建议传入自己的节点（Helius / QuickNode / Triton 等）。
+ */
+export const DEFAULT_RPC_URLS: Readonly<Record<Cluster, readonly string[]>> = {
+  mainnet: ['https://solana-rpc.publicnode.com', 'https://api.mainnet-beta.solana.com'],
+  devnet: ['https://api.devnet.solana.com'],
+  testnet: ['https://api.testnet.solana.com'],
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+export { SolanaClient, type BalancesOptions, type ClientConfig, type OwnerTokensOptions, type TokensOptions } from './client.js'
+export {
+  getBalances,
+  getNftOwners,
+  getNfts,
+  getOwnerNfts,
+  getOwnerTokens,
+  getSolBalances,
+  getTokens,
+  type GetBalancesOptions,
+  type GetOwnerTokensOptions,
+  type GetTokensOptions,
+  type ShortcutOptions,
+} from './shortcuts.js'
+export {
+  DEFAULT_TOKEN_FIELDS,
+  type Commitment,
+  type DefaultTokenField,
+  type NftDetails,
+  type NftOwner,
+  type OwnedToken,
+  type SolBalance,
+  type TokenBalance,
+  type TokenDetails,
+  type TokenField,
+  type TokenStandard,
+} from './types.js'
+export {
+  ASSOCIATED_TOKEN_PROGRAM_ID,
+  DEFAULT_RPC_URLS,
+  GENESIS_HASHES,
+  METADATA_PROGRAM_ID,
+  NATIVE_MINT,
+  SOL_DECIMALS,
+  SYSTEM_PROGRAM_ID,
+  TOKEN_2022_PROGRAM_ID,
+  TOKEN_PROGRAM_ID,
+  clusterOfGenesis,
+  type Cluster,
+} from './constants.js'
+export { decodeAddress, encodeAddress, findProgramAddress, getAssociatedTokenAddress, getMetadataAddress, isAddress } from './address.js'
+export {
+  formatAmount,
+  parseMetaplexMetadata,
+  parseMint,
+  parseTokenAccount,
+  type AccountInfo,
+  type MetaplexMetadata,
+  type MintInfo,
+  type TokenAccountInfo,
+  type TokenMetadata,
+} from './layout.js'
+export { FallbackRpc, HttpError, HttpRpc, RpcError, isNodeFault, type FallbackOptions, type HttpRpcOptions, type RpcTransport } from './rpc.js'
+export { NetworkCheckedRpc, NetworkMismatchError, type RpcSource, type SourceOptions } from './source.js'

package/src/layout.ts

@@ -0,0 +1,238 @@
+import { encodeAddress } from './address.js'
+
+/** getMultipleAccounts 解析后的账户 */
+export interface AccountInfo {
+  address: string
+  lamports: bigint
+  /** 所属程序 */
+  owner: string
+  data: Uint8Array
+  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
+  decimals: number
+  isInitialized: boolean
+  freezeAuthority: string | null
+  /** Token-2022 TokenMetadata 扩展（如有） */
+  metadata: TokenMetadata | null
+}
+
+export interface TokenMetadata {
+  name: string
+  symbol: string
+  uri: string
+}
+
+const MINT_SIZE = 82
+const ACCOUNT_SIZE = 165
+/** Token-2022 带扩展的账户：基础布局补齐到 165（Account 的大小），第 165 字节是账户类型，之后是扩展 */
+const ACCOUNT_TYPE_OFFSET = 165
+const EXTENSIONS_OFFSET = 166
+const ACCOUNT_TYPE_MINT = 1
+const ACCOUNT_TYPE_ACCOUNT = 2
+const EXTENSION_TOKEN_METADATA = 19
+
+/** 解析 Mint 账户（SPL Token / Token-2022 通用，Token-2022 额外解析 TokenMetadata 扩展） */
+export function parseMint(data: Uint8Array): MintInfo {
+  // 只接受真正的 mint：SPL Token 恰好 82 字节；Token-2022 带扩展时账户类型必须是 Mint（避免把代币账户 / 多签账户当成 mint）
+  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 hasMintAuthority = r.u32() === 1
+  const mintAuthority = r.pubkey()
+  const supply = r.u64()
+  const decimals = r.u8()
+  const isInitialized = r.u8() === 1
+  const hasFreezeAuthority = r.u32() === 1
+  const freezeAuthority = r.pubkey()
+  return {
+    mintAuthority: hasMintAuthority ? mintAuthority : null,
+    supply,
+    decimals,
+    isInitialized,
+    freezeAuthority: hasFreezeAuthority ? freezeAuthority : null,
+    metadata: data.length > EXTENSIONS_OFFSET ? parseTokenMetadataExtension(data) : null,
+  }
+}
+
+function parseTokenMetadataExtension(data: Uint8Array): TokenMetadata | null {
+  try {
+    const r = new Reader(data, EXTENSIONS_OFFSET)
+    while (r.offset + 4 <= data.length) {
+      const type = r.u16()
+      const length = r.u16()
+      if (type === 0 && length === 0) {
+        return null // 未初始化的填充
+      }
+      if (type === EXTENSION_TOKEN_METADATA) {
+        const m = new Reader(data.slice(r.offset, r.offset + length))
+        m.pubkey() // updateAuthority
+        m.pubkey() // mint
+        return { name: m.string(), symbol: m.string(), uri: m.string() }
+      }
+      r.skip(length)
+    }
+  } catch {
+    // 扩展数据不完整：当作没有
+  }
+  return null
+}
+
+export interface TokenAccountInfo {
+  mint: string
+  owner: string
+  amount: bigint
+}
+
+/** 解析代币账户（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)) {
+    throw new RangeError('Not a token account')
+  }
+  const r = new Reader(data)
+  return { mint: r.pubkey(), owner: r.pubkey(), amount: r.u64() }
+}
+
+export interface MetaplexMetadata extends TokenMetadata {
+  updateAuthority: string
+  mint: string
+  sellerFeeBasisPoints: number
+  creators: Array<{ address: string; verified: boolean; share: number }>
+  primarySaleHappened: boolean
+  isMutable: boolean
+  /** 0 NonFungible，1 FungibleAsset，2 Fungible，3 NonFungibleEdition，4 ProgrammableNonFungible，5 ProgrammableNonFungibleEdition */
+  tokenStandard: number | null
+  collection: { address: string; verified: boolean } | null
+}
+
+/** 解析 Metaplex Token Metadata 账户；老版本账户缺少后面的字段时，缺的部分为默认值 */
+export function parseMetaplexMetadata(data: Uint8Array): MetaplexMetadata {
+  const r = new Reader(data)
+  if (r.u8() !== 4) {
+    throw new RangeError('Not a Metaplex metadata account') // Key::MetadataV1 = 4
+  }
+  const updateAuthority = r.pubkey()
+  const mint = r.pubkey()
+  const name = r.string()
+  const symbol = r.string()
+  const uri = r.string()
+  const sellerFeeBasisPoints = r.u16()
+  const creators =
+    r.option(() => {
+      const count = r.u32()
+      return Array.from({ length: count }, () => ({ address: r.pubkey(), verified: r.u8() === 1, share: r.u8() }))
+    }) ?? []
+  const result: MetaplexMetadata = {
+    updateAuthority,
+    mint,
+    name,
+    symbol,
+    uri,
+    sellerFeeBasisPoints,
+    creators,
+    primarySaleHappened: false,
+    isMutable: false,
+    tokenStandard: null,
+    collection: null,
+  }
+  try {
+    result.primarySaleHappened = r.u8() === 1
+    result.isMutable = r.u8() === 1
+    r.option(() => r.u8()) // editionNonce
+    result.tokenStandard = r.option(() => r.u8())
+    result.collection = r.option(() => {
+      const verified = r.u8() === 1
+      return { address: r.pubkey(), verified }
+    })
+  } catch {
+    // 老版本账户没有这些字段
+  }
+  return result
+}
+
+/** 按精度格式化：formatAmount(1_500_000_000n, 9) === '1.5' */
+export function formatAmount(value: bigint, decimals: number): string {
+  const negative = value < 0n
+  const digits = (negative ? -value : value).toString().padStart(decimals + 1, '0')
+  const whole = digits.slice(0, digits.length - decimals)
+  const fraction = digits.slice(digits.length - decimals).replace(/0+$/, '')
+  return `${negative ? '-' : ''}${whole}${fraction ? `.${fraction}` : ''}`
+}

package/src/rpc.ts

@@ -0,0 +1,349 @@
+/** 最小的 JSON-RPC 传输接口：可以传入自己的实现（如包一层 @solana/kit 的 rpc） */
+export interface RpcTransport {
+  request<T = unknown>(method: string, params?: readonly unknown[]): Promise<T>
+}
+
+/** 节点返回的 JSON-RPC 错误 */
+export class RpcError extends Error {
+  readonly code: number | undefined
+  readonly data: unknown
+  /** 是否是节点自身的限制（限频、需要 API Key、禁止访问等），换节点可能成功 */
+  readonly nodeFault: boolean
+
+  constructor(message: string, code?: number, data?: unknown) {
+    super(message)
+    this.name = 'RpcError'
+    this.code = code
+    this.data = data
+    this.nodeFault =
+      code === 403 ||
+      code === 429 ||
+      code === -32005 ||
+      /forbidden|blocked|personal token|api.?key|rate.?limit|too many|not allowed|unauthori[sz]ed|limit exceeded|disabled|not available|not supported/i.test(message)
+  }
+}
+
+/** HTTP 层错误（非 2xx、网络错误、超时） */
+export class HttpError extends Error {
+  readonly status: number | undefined
+
+  constructor(message: string, status?: number) {
+    super(message)
+    this.name = 'HttpError'
+    this.status = status
+  }
+}
+
+/** 是否是节点问题（应换节点重试）：除了确定性的 JSON-RPC 错误（如参数错误），其余都算 */
+export function isNodeFault(err: unknown): boolean {
+  if (err instanceof RpcError) {
+    return err.nodeFault
+  }
+  return true
+}
+
+export interface HttpRpcOptions {
+  /** 单次 HTTP 请求超时（毫秒），<= 0 不限制。默认 10000 */
+  timeout?: number
+  headers?: Record<string, string>
+  /** 一个 HTTP 批量请求最多包含的调用数。默认 20 */
+  maxBatchSize?: number
+  /** 是否合并成 JSON-RPC 批量请求。默认 true；节点不支持时会自动关闭 */
+  batch?: boolean
+  /** 收集窗口（毫秒），窗口内的调用合并成一个 HTTP 请求。默认 0（同一 tick） */
+  batchWait?: number
+  /** 遇到 HTTP 429 时的重试次数（指数退避，从 500ms 开始）。默认 2 */
+  retries?: number
+  /** 自定义 fetch（如需要代理时） */
+  fetch?: typeof fetch
+}
+
+interface Pending {
+  method: string
+  params: readonly unknown[]
+  resolve: (value: unknown) => void
+  reject: (reason: unknown) => void
+}
+
+interface RpcResponse {
+  id?: number | string | null
+  result?: unknown
+  error?: { code?: number; message?: string; data?: unknown }
+}
+
+let nextId = 1
+
+/** 批量请求被拒绝、可以降级为逐条请求的 HTTP 状态 */
+const BATCH_REJECTED_STATUS = new Set([400, 404, 405, 415, 422])
+
+function isBatchLimitError(message: string | undefined): boolean {
+  return !!message && /batch/i.test(message) && /more than \d+|too (large|many|big)|not (allowed|supported)|exceed/i.test(message)
+}
+
+/**
+ * 基于 fetch 的 JSON-RPC 传输：同一收集窗口内的调用合并成一个 JSON-RPC 批量请求。
+ * 节点不支持批量（返回非数组）或限制批量大小（如 drpc 免费档最多 3 条）时自动降级。
+ */
+export class HttpRpc implements RpcTransport {
+  readonly url: string
+  readonly #timeout: number
+  readonly #headers: Record<string, string>
+  readonly #batchWait: number
+  readonly #retries: number
+  readonly #fetch: typeof fetch
+  #maxBatchSize: number
+  #batch: boolean
+  #queue: Pending[] = []
+  #timer: ReturnType<typeof setTimeout> | null = null
+
+  constructor(url: string, options: HttpRpcOptions = {}) {
+    this.url = url
+    this.#timeout = options.timeout ?? 10_000
+    this.#headers = { 'content-type': 'application/json', ...options.headers }
+    this.#maxBatchSize = Math.max(1, options.maxBatchSize ?? 20)
+    this.#batch = options.batch ?? true
+    this.#batchWait = options.batchWait ?? 0
+    this.#retries = Math.max(0, options.retries ?? 2)
+    this.#fetch = options.fetch ?? ((...args) => fetch(...args))
+  }
+
+  request<T = unknown>(method: string, params: readonly unknown[] = []): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      this.#queue.push({ method, params, resolve: resolve as (value: unknown) => void, reject })
+      if (!this.#batch || this.#queue.length >= this.#maxBatchSize) {
+        this.#flush()
+      } else if (!this.#timer) {
+        this.#timer = setTimeout(() => this.#flush(), this.#batchWait)
+      }
+    })
+  }
+
+  #flush(): void {
+    if (this.#timer) {
+      clearTimeout(this.#timer)
+      this.#timer = null
+    }
+    const queue = this.#queue
+    this.#queue = []
+    for (let i = 0; i < queue.length; i += this.#maxBatchSize) {
+      void this.#dispatch(queue.slice(i, i + this.#maxBatchSize))
+    }
+  }
+
+  async #dispatch(items: Pending[]): Promise<void> {
+    if (items.length === 1 || !this.#batch) {
+      await Promise.all(items.map((item) => this.#single(item)))
+      return
+    }
+    const ids = items.map(() => nextId++)
+    let body: unknown
+    try {
+      body = await this.#post(items.map((item, i) => ({ jsonrpc: '2.0', id: ids[i], method: item.method, params: item.params })))
+    } catch (err) {
+      if (err instanceof HttpError && err.status === 413 && items.length > 1) {
+        // 请求体太大：批量减半后重发
+        this.#maxBatchSize = Math.max(1, Math.floor(items.length / 2))
+        await this.#redispatch(items)
+        return
+      }
+      // 400 / 404 / 405 / 415 / 422 等：节点多半不接受批量请求，降级为逐条请求
+      // （401 / 403 / 429 / 5xx 是鉴权、限频或节点本身的问题，降级没有用，原样报错）
+      if (err instanceof HttpError && err.status !== undefined && BATCH_REJECTED_STATUS.has(err.status)) {
+        this.#disableBatch()
+        await Promise.all(items.map((item) => this.#single(item)))
+        return
+      }
+      items.forEach((item) => item.reject(err))
+      return
+    }
+    if (!Array.isArray(body)) {
+      const error = (body as RpcResponse)?.error
+      const rpcError = new RpcError(error?.message ?? 'Invalid JSON-RPC batch response', error?.code, error?.data)
+      // 限频 / 鉴权等节点问题：原样报错，不降级（降级成逐条请求只会让限频更严重）
+      if (rpcError.nodeFault) {
+        items.forEach((item) => item.reject(rpcError))
+        return
+      }
+      // 其他（如 -32600 invalid request）：节点不支持批量，降级为逐条请求
+      this.#disableBatch()
+      await Promise.all(items.map((item) => this.#single(item)))
+      return
+    }
+    const byId = new Map((body as RpcResponse[]).map((res) => [res.id, res]))
+    const limited = (body as RpcResponse[]).find((res) => isBatchLimitError(res.error?.message))
+    if (limited) {
+      // 如 “Batch of more than 3 requests are not allowed”：按限制缩小批量后重发；
+      // 限制不小于当前批量（节点的上限判断有偏差）或解析不出数字时，降级为逐条请求，避免无限重发
+      const max = Number(/more than (\d+)/i.exec(limited.error?.message ?? '')?.[1])
+      if (Number.isFinite(max) && max > 1 && max < items.length) {
+        this.#maxBatchSize = max
+        await this.#redispatch(items)
+      } else {
+        this.#disableBatch()
+        await Promise.all(items.map((item) => this.#single(item)))
+      }
+      return
+    }
+    // 批量里个别调用被限频（JSON-RPC 429）：只把这些调用退避后单独重试
+    const limitedItems: Pending[] = []
+    items.forEach((item, i) => {
+      const response = byId.get(ids[i])
+      if (response?.error?.code === 429 && this.#retries > 0) {
+        limitedItems.push(item)
+      } else {
+        settle(item, response)
+      }
+    })
+    if (limitedItems.length) {
+      await new Promise((r) => setTimeout(r, 500))
+      await Promise.all(limitedItems.map((item) => this.#single(item)))
+    }
+  }
+
+  /** 按当前的 maxBatchSize 重新分批发送（每批都比原来小，不会无限循环） */
+  async #redispatch(items: Pending[]): Promise<void> {
+    const size = this.#maxBatchSize
+    const chunks: Pending[][] = []
+    for (let i = 0; i < items.length; i += size) {
+      chunks.push(items.slice(i, i + size))
+    }
+    await Promise.all(chunks.map((chunk) => this.#dispatch(chunk)))
+  }
+
+  async #single(item: Pending): Promise<void> {
+    try {
+      const body = (await this.#post({ jsonrpc: '2.0', id: nextId++, method: item.method, params: item.params })) as RpcResponse
+      settle(item, body)
+    } catch (err) {
+      item.reject(err)
+    }
+  }
+
+  #disableBatch(): void {
+    this.#batch = false
+  }
+
+  async #post(payload: unknown): Promise<unknown> {
+    for (let attempt = 0; ; attempt++) {
+      let response: Response
+      try {
+        response = await this.#fetch(this.url, {
+          method: 'POST',
+          headers: this.#headers,
+          body: JSON.stringify(payload),
+          signal: this.#timeout > 0 && Number.isFinite(this.#timeout) ? AbortSignal.timeout(this.#timeout) : undefined,
+        })
+      } catch (err) {
+        throw new HttpError(`Request to ${this.url} failed: ${(err as Error)?.message ?? err}`)
+      }
+      if (response.status === 429 && attempt < this.#retries) {
+        await new Promise((r) => setTimeout(r, 500 * 2 ** attempt))
+        continue
+      }
+      const text = await response.text()
+      let body: unknown
+      try {
+        body = parseJson(text)
+      } catch {
+        throw new HttpError(`Invalid JSON from ${this.url} (HTTP ${response.status})`, response.status)
+      }
+      // 非 2xx 但返回了 JSON-RPC 结构（如 403 Access forbidden、drpc 的 500 + 批量错误数组）：交给上层解析
+      if (!response.ok && !Array.isArray(body) && !(body as RpcResponse)?.error) {
+        throw new HttpError(`HTTP ${response.status} from ${this.url}`, response.status)
+      }
+      // 有的节点限频时返回 HTTP 200 + JSON-RPC 错误码 429：同样退避重试
+      if (attempt < this.#retries && isRateLimited(body)) {
+        await new Promise((r) => setTimeout(r, 500 * 2 ** attempt))
+        continue
+      }
+      return body
+    }
+  }
+}
+
+// lamports 等 u64 以 JSON 数字返回，超过 2^53（约 900 万 SOL）时 JSON.parse 会丢精度：
+// 支持 JSON.parse source text access 的环境（Node 21+、新版浏览器）直接取原文；否则先把超长整数改成字符串再解析
+let sourceAccess: boolean | undefined
+
+function parseJson(text: string): unknown {
+  sourceAccess ??= (() => {
+    let supported = false
+    JSON.parse('1', (_key, value, context?: { source?: string }) => {
+      supported = typeof context?.source === 'string'
+      return value
+    })
+    return supported
+  })()
+  if (sourceAccess) {
+    return JSON.parse(text, (_key, value: unknown, context?: { source?: string }) =>
+      typeof value === 'number' && !Number.isSafeInteger(value) && Number.isInteger(value) && context?.source ? context.source : value,
+    )
+  }
+  return JSON.parse(text.replace(/([:[,]\s*)(-?\d{16,})(?=\s*[,}\]])/g, '$1"$2"'))
+}
+
+function isRateLimited(body: unknown): boolean {
+  const responses = (Array.isArray(body) ? body : [body]) as RpcResponse[]
+  return responses.length > 0 && responses.every((res) => res?.error?.code === 429)
+}
+
+function settle(item: Pending, response: RpcResponse | undefined): void {
+  if (!response) {
+    item.reject(new HttpError('Missing response in JSON-RPC batch'))
+  } else if (response.error) {
+    item.reject(new RpcError(response.error.message ?? 'JSON-RPC error', response.error.code, response.error.data))
+  } else {
+    item.resolve(response.result)
+  }
+}
+
+export interface FallbackOptions {
+  /** 出错节点的冷却时间（毫秒），期间排到最后。默认 30000 */
+  cooldown?: number
+}
+
+/**
+ * 多节点故障切换：按顺序使用，节点问题（网络、超时、限频、需要 Key、403 等）换下一个；
+ * 参数错误等确定性错误直接抛出。出错的节点在冷却期内排到最后。
+ */
+export class FallbackRpc implements RpcTransport {
+  readonly nodes: readonly RpcTransport[]
+  readonly #cooldown: number
+  readonly #failedAt: number[]
+
+  constructor(nodes: readonly RpcTransport[], options: FallbackOptions = {}) {
+    if (!nodes.length) {
+      throw new Error('FallbackRpc requires at least one node')
+    }
+    this.nodes = nodes
+    this.#cooldown = options.cooldown ?? 30_000
+    this.#failedAt = nodes.map(() => 0)
+  }
+
+  async request<T = unknown>(method: string, params?: readonly unknown[]): Promise<T> {
+    let lastError: unknown
+    for (const index of this.#order()) {
+      try {
+        const result = await (this.nodes[index] as RpcTransport).request<T>(method, params)
+        this.#failedAt[index] = 0
+        return result
+      } catch (err) {
+        if (!isNodeFault(err)) {
+          throw err
+        }
+        this.#failedAt[index] = Date.now()
+        lastError = err
+      }
+    }
+    throw lastError
+  }
+
+  #order(): number[] {
+    const now = Date.now()
+    const healthy: number[] = []
+    const cooling: number[] = []
+    this.#failedAt.forEach((at, i) => (at && now - at < this.#cooldown ? cooling : healthy).push(i))
+    cooling.sort((a, b) => (this.#failedAt[a] as number) - (this.#failedAt[b] as number))
+    return [...healthy, ...cooling]
+  }
+}