@w3lib/solana-batch-call 0.6.0 → 0.7.0

package/src/tokenMeta.ts

@@ -0,0 +1,270 @@
+// 代币信息缓存（decimals / 所属程序 / name / symbol）和“数据为空的钱包账户”记录：余额、代币详情共用
+
+import { isAddress } from './address.js'
+import { SYSTEM_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID } from './constants.js'
+import { parseMetaplexMetadata, parseMint, type AccountInfo, type MetaplexMetadata, type MintInfo } from './layout.js'
+
+export interface TokenMeta {
+  decimals?: number
+  tokenProgram?: string
+  /** tokenProgram 来自导入的缓存、还没从链上确认过：ATA 模式第一次用时按程序未知处理（推导两个程序的 ATA、读 mint 确认） */
+  programUnverified?: boolean
+  /** null：确认没有元数据 */
+  name?: string | null
+  symbol?: string | null
+}
+
+interface CachedMeta extends TokenMeta {
+  /** name / symbol 的写入时间 */
+  namesAt?: number
+}
+
+// 代币信息缓存（按 网络 + mint）：decimals / 所属程序不会变，永久缓存；
+// name / symbol 来自可修改的元数据，缓存 1 小时。条目数有上限，超出时淘汰最早写入的
+const NAME_TTL = 60 * 60 * 1000
+const MAX_CACHED_TOKENS = 50_000
+const tokenMetaCache = new Map<string, CachedMeta>()
+
+// 已知数据为空的钱包账户（系统账户或不存在）：ATA 模式下和代币账户放在同一个请求里读，不必单独带 dataSlice 多发一个请求。
+// 按 scope + 地址记，最多 1 万个，超出淘汰最早的；读到不是系统账户（如程序账户）时移除
+const MAX_SMALL_OWNERS = 10_000
+const smallOwners = new Set<string>()
+
+export function isSmallOwner(scope: string, owner: string): boolean {
+  return smallOwners.has(`${scope}:${owner}`)
+}
+
+/** 根据只读 lamports 的结果判断钱包账户是否“数据为空”（dataSlice 读不到数据长度，按所属程序判断：系统账户的数据为空） */
+export function learnOwner(scope: string, owner: string, account: AccountInfo | null): void {
+  const key = `${scope}:${owner}`
+  if (account === null || account.owner === SYSTEM_PROGRAM_ID) {
+    smallOwners.delete(key)
+    smallOwners.add(key)
+    if (smallOwners.size > MAX_SMALL_OWNERS) {
+      smallOwners.delete(smallOwners.values().next().value as string)
+    }
+  } else {
+    smallOwners.delete(key)
+  }
+}
+
+/** 缓存写入监听（persistTokenMetaCache 用） */
+const cacheWriteListeners = new Set<() => void>()
+
+/** 测试用：清空代币信息缓存 */
+export function resetTokenMetaCache(): void {
+  smallOwners.clear()
+  tokenMetaCache.clear()
+}
+
+/** exportTokenMetaCache() 的结果，可以 JSON 序列化 */
+export interface TokenMetaSnapshot {
+  version: 1
+  /** [网络:mint, 信息]；namesAt 是 name / symbol 的写入时间（毫秒时间戳），导入后继续按 1 小时过期 */
+  entries: Array<[string, { decimals?: number; tokenProgram?: string; name?: string | null; symbol?: string | null; namesAt?: number }]>
+}
+
+const SHARED_SCOPES = new Set<string>(['mainnet', 'devnet', 'testnet'])
+
+/**
+ * 导出代币信息缓存（decimals / 所属程序 / name / symbol），用于持久化：刷新页面后导入，不必重查 decimals。
+ * 只导出按网络共享的条目（自定义节点且没指定 cluster 的客户端，缓存只在该客户端内，不导出）。
+ * maxEntries：只导出最近写入的这么多条
+ */
+export function exportTokenMetaCache(maxEntries = Number.POSITIVE_INFINITY): TokenMetaSnapshot {
+  const entries: TokenMetaSnapshot['entries'] = []
+  for (const [key, meta] of tokenMetaCache) {
+    if (SHARED_SCOPES.has(key.slice(0, key.indexOf(':')))) {
+      const { programUnverified: _, ...exported } = meta
+      entries.push([key, exported])
+    }
+  }
+  return { version: 1, entries: entries.slice(Math.max(0, entries.length - maxEntries)) }
+}
+
+/** 导入 exportTokenMetaCache() 的结果；格式不对的条目跳过，内存里已有的条目不覆盖 */
+export function importTokenMetaCache(snapshot: unknown): void {
+  const entries = (snapshot as Partial<TokenMetaSnapshot> | null)?.entries
+  if ((snapshot as Partial<TokenMetaSnapshot> | null)?.version !== 1 || !Array.isArray(entries)) {
+    return
+  }
+  for (const entry of entries) {
+    const meta = validMeta(entry)
+    if (meta && !tokenMetaCache.has(entry[0])) {
+      tokenMetaCache.set(entry[0], meta)
+      if (tokenMetaCache.size > MAX_CACHED_TOKENS) {
+        tokenMetaCache.delete(tokenMetaCache.keys().next().value as string)
+      }
+    }
+  }
+}
+
+function validMeta(entry: unknown): CachedMeta | null {
+  if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== 'string') {
+    return null
+  }
+  const [key, raw] = entry as [string, Record<string, unknown>]
+  const colon = key.indexOf(':')
+  if (!SHARED_SCOPES.has(key.slice(0, colon)) || !isAddress(key.slice(colon + 1)) || !raw || typeof raw !== 'object') {
+    return null
+  }
+  const meta: CachedMeta = {}
+  if (typeof raw.decimals === 'number' && Number.isInteger(raw.decimals) && raw.decimals >= 0 && raw.decimals <= 255) meta.decimals = raw.decimals
+  if (raw.tokenProgram === TOKEN_PROGRAM_ID || raw.tokenProgram === TOKEN_2022_PROGRAM_ID) {
+    meta.tokenProgram = raw.tokenProgram
+    meta.programUnverified = true
+  }
+  // 写入时间只接受有限值、且不晚于现在（留 1 分钟时钟误差）：未来的时间会让 name / symbol 永不过期，截到现在
+  if (
+    typeof raw.namesAt === 'number' &&
+    Number.isFinite(raw.namesAt) &&
+    (typeof raw.name === 'string' || raw.name === null) &&
+    (typeof raw.symbol === 'string' || raw.symbol === null)
+  ) {
+    meta.name = raw.name
+    meta.symbol = raw.symbol
+    meta.namesAt = Math.min(raw.namesAt, Date.now())
+  }
+  return Object.keys(meta).length ? meta : null
+}
+
+export interface PersistTokenMetaOptions {
+  /** 存储的键，默认 'w3lib:solana-token-meta' */
+  key?: string
+  /** 最多保存多少条（最近写入的优先），默认 5000 */
+  maxEntries?: number
+}
+
+/**
+ * 把代币信息缓存持久化到同步的键值存储（如 localStorage）：调用时读入，之后缓存有写入就防抖（约 1 秒）整体写回。
+ * 返回停止函数（会立即写回还没写的变化）。读到格式不对的数据会丢弃；写入失败（如存储已满）忽略。
+ *
+ * ```ts
+ * persistTokenMetaCache(localStorage) // 刷新页面后 decimals 不必重查
+ * ```
+ */
+export function persistTokenMetaCache(
+  store: { getItem(key: string): string | null; setItem(key: string, value: string): void },
+  options: PersistTokenMetaOptions = {},
+): () => void {
+  const key = options.key ?? 'w3lib:solana-token-meta'
+  const maxEntries = options.maxEntries ?? 5000
+  try {
+    const raw = store.getItem(key)
+    if (raw) {
+      importTokenMetaCache(JSON.parse(raw))
+    }
+  } catch {
+    // 格式不对：丢弃
+  }
+  let timer: ReturnType<typeof setTimeout> | null = null
+  const write = () => {
+    timer = null
+    try {
+      store.setItem(key, JSON.stringify(exportTokenMetaCache(maxEntries)))
+    } catch {
+      // 存储已满等：忽略
+    }
+  }
+  const onWrite = () => {
+    if (!timer) {
+      timer = setTimeout(write, 1000)
+      ;(timer as { unref?: () => void }).unref?.()
+    }
+  }
+  cacheWriteListeners.add(onWrite)
+  return () => {
+    cacheWriteListeners.delete(onWrite)
+    if (timer) {
+      clearTimeout(timer)
+      write()
+    }
+  }
+}
+
+/**
+ * 从 mint 账户 / 元数据账户里学到的信息写入缓存，返回合并后的结果。
+ * lookedForNames：本次同时读了 mint 和元数据账户，都没有 name / symbol 时记为“确认没有”（null），之后不再重查
+ */
+export function learnMeta(scope: string, mint: string, mintAccount: AccountInfo | null, metadataAccount: AccountInfo | null, lookedForNames = false): TokenMeta {
+  const update: TokenMeta = {}
+  const info = mintAccount ? safeParseMint(mintAccount) : null
+  if (info && mintAccount) {
+    update.decimals = info.decimals
+    update.tokenProgram = mintAccount.owner
+    if (info.metadata) {
+      update.name = info.metadata.name
+      update.symbol = info.metadata.symbol
+    }
+  }
+  if (metadataAccount && update.name === undefined) {
+    const metaplex = safeParseMetaplex(metadataAccount)
+    if (metaplex) {
+      update.name = metaplex.name
+      update.symbol = metaplex.symbol
+    }
+  }
+  if (lookedForNames && info && update.name === undefined) {
+    update.name = null
+    update.symbol = null
+  }
+  setMeta(scope, mint, update)
+  return getMeta(scope, mint)
+}
+
+export function safeParseMint(account: AccountInfo): MintInfo | null {
+  if (account.owner !== TOKEN_PROGRAM_ID && account.owner !== TOKEN_2022_PROGRAM_ID) {
+    return null
+  }
+  try {
+    const mint = parseMint(account.data)
+    // 未初始化的 mint（创建和初始化分在两笔交易里，恰好在中间读到）：decimals 还是 0，不能当真、更不能永久缓存
+    return mint.isInitialized ? mint : null
+  } catch {
+    return null
+  }
+}
+
+export function safeParseMetaplex(account: AccountInfo): MetaplexMetadata | null {
+  try {
+    return parseMetaplexMetadata(account.data)
+  } catch {
+    return null
+  }
+}
+
+export function getMeta(scope: string, mint: string): TokenMeta {
+  const cached = tokenMetaCache.get(`${scope}:${mint}`)
+  if (!cached) {
+    return {}
+  }
+  const { namesAt, ...meta } = cached
+  if (namesAt === undefined || Date.now() - namesAt > NAME_TTL) {
+    delete meta.name
+    delete meta.symbol
+  }
+  return meta
+}
+
+export function setMeta(scope: string, mint: string, meta: TokenMeta): void {
+  const defined: CachedMeta = Object.fromEntries(Object.entries(meta).filter(([, v]) => v !== undefined))
+  if (Object.keys(defined).length === 0) {
+    return
+  }
+  if ('name' in defined || 'symbol' in defined) {
+    defined.namesAt = Date.now()
+  }
+  const key = `${scope}:${mint}`
+  const merged = { ...tokenMetaCache.get(key), ...defined }
+  if ('tokenProgram' in defined && !defined.programUnverified) {
+    delete merged.programUnverified // 从链上学到了所属程序
+  }
+  tokenMetaCache.delete(key) // 重新插入，保持“最近写入在后”的顺序
+  tokenMetaCache.set(key, merged)
+  if (tokenMetaCache.size > MAX_CACHED_TOKENS) {
+    tokenMetaCache.delete(tokenMetaCache.keys().next().value as string)
+  }
+  for (const listener of cacheWriteListeners) {
+    listener()
+  }
+}

package/src/tradeCheck.ts

@@ -4,13 +4,13 @@
  */
 import { base64 } from '@scure/base'
 
-import { getAssociatedTokenAddress, isAddress } from './address.js'
+import { getAssociatedTokenAddress, InvalidAddressError, isAddress } from './address.js'
 import type { RequestOptions, SolanaClient } from './client.js'
 import { NATIVE_MINT, TOKEN_PROGRAM_ID } from './constants.js'
 import { parseTokenAccount, parseUnits } from './layout.js'
 import { buildSwap, type SolanaSwapOptions, type SolanaSwapPlan } from './swap/index.js'
 import { MAX_COMPUTE_UNITS, setComputeUnitLimit } from './write/instructions.js'
-import { transactionErrorText } from './write/send.js'
+import { transactionErrorText } from './write/errors.js'
 import { MAX_ACCOUNT_LOCKS, PACKET_DATA_SIZE, compileMessage, serializeTransaction, transactionSize, type Instruction } from './write/transaction.js'
 
 export type TradeStage = 'ok' | 'no-pool' | 'buy-failed' | 'sell-failed'
@@ -55,7 +55,7 @@ export interface TradeCheckOptions extends RequestOptions, Pick<SolanaSwapOption
  * ```
  */
 export async function tradeChecks(client: SolanaClient, mints: readonly string[], options: TradeCheckOptions): Promise<SolanaTradeCheck[]> {
-  if (!isAddress(options.owner)) throw new Error(`Invalid owner address: ${options.owner}`)
+  if (!isAddress(options.owner)) throw new InvalidAddressError(`Invalid owner address: ${options.owner}`, options.owner)
   if (options.amount !== undefined && options.amountFormatted !== undefined) throw new Error('Pass either amount or amountFormatted, not both')
   const spent = options.amountFormatted !== undefined ? parseUnits(options.amountFormatted, 9) : options.amount !== undefined ? BigInt(options.amount) : 50_000_000n
   if (spent <= 0n) throw new RangeError('amount must be greater than 0')

package/src/util.ts

@@ -0,0 +1,110 @@
+/** 内部公共工具：并发池、可取消的等待、多个调用方共用一次操作时的取消 */
+
+/** 并发数为 limit 的 map，结果按输入顺序。某一项出错时整体 reject，其余 worker 不再取后面的项（已开始的照常结束） */
+export async function mapPool<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]> {
+  const results = new Array<R>(items.length)
+  let next = 0
+  let failed = false
+  const worker = async () => {
+    while (!failed && next < items.length) {
+      const i = next++
+      try {
+        results[i] = await fn(items[i] as T, i)
+      } catch (err) {
+        failed = true
+        throw err
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker))
+  return results
+}
+
+/**
+ * 等待 ms 毫秒。signal 取消时：rejectOnAbort 为 true（默认）时立即 reject（reason 为 signal.reason），
+ * 为 false 时提前 resolve（用于“取消后不再等，由调用方自己检查 signal”的场景）
+ */
+export function sleep(ms: number, signal?: AbortSignal, rejectOnAbort = true): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      if (rejectOnAbort) {
+        reject(signal.reason)
+      } else {
+        resolve()
+      }
+      return
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    const onAbort = () => {
+      clearTimeout(timer)
+      if (rejectOnAbort) {
+        reject(signal?.reason)
+      } else {
+        resolve()
+      }
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/**
+ * 多个调用方共用一次操作（在途去重）时的取消：所有加入的调用方都取消后才中止；
+ * 有一个调用方没传 signal 就永远不会中止。操作结束后调用 done() 移除监听
+ */
+export class SharedAbort {
+  readonly #controller = new AbortController()
+  /** 还没取消的调用方数量（只算传了 signal 的） */
+  #active = 0
+  /** 有调用方没传 signal */
+  #forever = false
+  #cleanups: Array<() => void> = []
+  #done = false
+
+  get signal(): AbortSignal {
+    return this.#controller.signal
+  }
+
+  /** 加入；已经中止或已结束时返回 false（调用方应另起一次操作） */
+  join(signal: AbortSignal | undefined): boolean {
+    if (this.#controller.signal.aborted || this.#done) {
+      return false
+    }
+    if (!signal) {
+      this.#forever = true
+      return true
+    }
+    if (signal.aborted) {
+      // 调用方已经取消（外层会直接 reject）：不计入
+      return true
+    }
+    this.#active++
+    const onAbort = () => {
+      if (--this.#active === 0 && !this.#forever && !this.#done) {
+        this.#controller.abort(signal.reason)
+      }
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    this.#cleanups.push(() => signal.removeEventListener('abort', onAbort))
+    return true
+  }
+
+  done(): void {
+    this.#done = true
+    for (const cleanup of this.#cleanups) {
+      cleanup()
+    }
+    this.#cleanups = []
+  }
+}
+
+/** 往有条目上限的 Map 里写入（先删再插保持“最近写入在后”），超出时淘汰最早写入的 */
+export function boundedSet<K, V>(map: Map<K, V>, key: K, value: V, max: number): void {
+  map.delete(key)
+  map.set(key, value)
+  while (map.size > max) {
+    map.delete(map.keys().next().value as K)
+  }
+}

package/src/write/chain.ts

@@ -0,0 +1,218 @@
+import { sha256 } from '@noble/hashes/sha2.js'
+import { base64 } from '@scure/base'
+
+import type { SolanaClient } from '../client.js'
+import { FallbackRpc, RpcError, isNodeFault, type RpcTransport } from '../rpc.js'
+import { clientSourceConfigs } from '../clientConfig.js'
+import { sleep } from '../util.js'
+import { errorText } from './errors.js'
+import type { SendOptions } from './send.js'
+import { serializeTransaction, type CompiledMessage } from './transaction.js'
+
+/**
+ * 最近发出过的交易消息（sha256）：同样的消息签名也相同，再发一次只会被节点当成同一笔。
+ * 在签名之前检查（钱包签名的交易也适用），重复时调整计算单元上限让消息不同
+ */
+const recentMessages = new Set<string>()
+
+export function messageKey(message: Uint8Array): string {
+  return base64.encode(sha256(message))
+}
+
+export function isRecentMessage(message: Uint8Array): boolean {
+  return recentMessages.has(messageKey(message))
+}
+
+export function remember(message: Uint8Array): void {
+  recentMessages.add(messageKey(message))
+  if (recentMessages.size > 10_000) {
+    recentMessages.delete(recentMessages.values().next().value as string)
+  }
+}
+
+export interface Blockhash {
+  blockhash: string
+  lastValidBlockHeight: number
+}
+
+export interface SimulationValue {
+  err: unknown
+  logs?: string[] | null
+  unitsConsumed?: number
+  /** 请求了 accounts 时：模拟执行后这些账户的状态（已扣手续费）；账户不存在时为 null */
+  accounts?: Array<{ lamports: number | string } | null> | null
+}
+
+/**
+ * 'auto' 优先费用：最近费用里去掉 0 再取 75 分位。
+ * 不活跃的账户大多数 slot 没有相关交易，返回 0（2026-10 主网实测 USDC mint 150 个 slot 里 135 个是 0），
+ * 带上 0 取分位数几乎总是 0，等于不加优先费用
+ */
+export function autoPriorityFee(fees: readonly number[], cap: bigint): bigint {
+  const paid = fees
+    .filter((fee) => fee > 0)
+    .map((fee) => BigInt(fee))
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+  const p75 = paid.length ? (paid[Math.min(paid.length - 1, Math.floor(paid.length * 0.75))] as bigint) : 0n
+  return p75 < cap ? p75 : cap
+}
+
+/** 一批发送共用的节点访问：blockhash（缓存 10 秒）、优先费用（按账户缓存 10 秒）、模拟、广播 */
+export class Chain {
+  #blockhash: { at: number; value: Promise<Blockhash> } | null = null
+  readonly #fees = new Map<string, { at: number; value: Promise<bigint> }>()
+  #broadcastTargets: Promise<RpcTransport[]> | null = null
+
+  constructor(
+    readonly client: SolanaClient,
+    readonly options: SendOptions,
+  ) {}
+
+  get commitment(): 'confirmed' | 'finalized' {
+    return this.options.commitment ?? 'confirmed'
+  }
+
+  #walletChain: Promise<string | undefined> | null = null
+
+  /** Wallet Standard 的链标识（'solana:mainnet' 等）；网络未知时为 undefined */
+  walletChain(): Promise<string | undefined> {
+    this.#walletChain ??= this.client.getCluster().then(
+      (cluster) => (cluster ? `solana:${cluster}` : undefined),
+      () => undefined,
+    )
+    return this.#walletChain
+  }
+
+  blockhash(fresh = false): Promise<Blockhash> {
+    if (fresh || !this.#blockhash || Date.now() - this.#blockhash.at > 10_000) {
+      const value = this.client
+        .request<{ value: Blockhash }>('getLatestBlockhash', [{ commitment: 'confirmed' }])
+        .then((res) => res.value)
+      value.catch(() => {
+        if (this.#blockhash?.value === value) this.#blockhash = null
+      })
+      this.#blockhash = { at: Date.now(), value }
+    }
+    return this.#blockhash.value
+  }
+
+  async priorityFee(writable: readonly string[]): Promise<bigint> {
+    const option = this.options.priorityFee ?? 'auto'
+    if (option !== 'auto') {
+      return BigInt(option)
+    }
+    const accounts = [...writable].sort().slice(0, 128)
+    const key = accounts.join(',')
+    let cached = this.#fees.get(key)
+    if (!cached || Date.now() - cached.at > 10_000) {
+      const cap = BigInt(this.options.maxPriorityFee ?? 1_000_000)
+      const value = this.client
+        .request<Array<{ prioritizationFee: number }>>('getRecentPrioritizationFees', [accounts])
+        .then((list) => autoPriorityFee(list.map((f) => f.prioritizationFee), cap))
+        .catch(() => 0n) // 节点不支持时不加优先费用
+      cached = { at: Date.now(), value }
+      this.#fees.set(key, cached)
+    }
+    return cached.value
+  }
+
+  /** 模拟；watch 是要返回模拟后状态的账户（如手续费支付者，用来判断付不付得起优先费用） */
+  async simulate(message: CompiledMessage, minContextSlot: number | undefined, watch?: readonly string[]): Promise<SimulationValue> {
+    const raw = base64.encode(serializeTransaction(message, message.signers.map(() => null)))
+    const config: Record<string, unknown> = { encoding: 'base64', sigVerify: false, replaceRecentBlockhash: true, commitment: 'confirmed' }
+    if (minContextSlot !== undefined) {
+      config.minContextSlot = minContextSlot
+    }
+    if (watch?.length) {
+      config.accounts = { encoding: 'base64', addresses: watch }
+    }
+    // 节点暂时的问题（限频、高度还没到 minContextSlot 等）重试几次，不当成调用失败
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const res = await this.client.request<{ value: SimulationValue }>('simulateTransaction', [raw, config])
+        return res.value
+      } catch (err) {
+        if (attempt >= 3 || (err instanceof RpcError && !isNodeFault(err))) throw err
+        await sleep(500 * (attempt + 1), this.options.signal, false)
+      }
+    }
+  }
+
+  /** 账户当前的 lamports；读不到时为 null（调用方按“不知道”处理） */
+  async balance(address: string, minContextSlot: number | undefined): Promise<bigint | null> {
+    try {
+      const config: Record<string, unknown> = { commitment: 'confirmed' }
+      if (minContextSlot !== undefined) config.minContextSlot = minContextSlot
+      const res = await this.client.request<{ value: number | string }>('getBalance', [address, config])
+      return BigInt(res.value)
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * 广播目标：sendRpc（不传时用 client 的节点）。sendRpc 按 client 的网络和节点选项（headers / fetch / timeout 等）解析，
+   * 并校验和 client 在同一个网络（不一致时报 NetworkMismatchError）。
+   * broadcast 为 'all' 时拆成各个节点（每个单独包一层 FallbackRpc，照常触发 onRequest、记录健康状态），否则整体按故障切换顺序只发给第一个可用的节点。
+   * 解析出错时抛出、不缓存（下次重试）。source.ts 只在传了 sendRpc 时按需加载（/write 的入口本身不静态依赖它）
+   */
+  #targets(): Promise<RpcTransport[]> {
+    this.#broadcastTargets ??= this.#resolveTargets().catch((err: unknown) => {
+      this.#broadcastTargets = null
+      throw err
+    })
+    return this.#broadcastTargets
+  }
+
+  async #resolveTargets(): Promise<RpcTransport[]> {
+    let sender = this.client.transport
+    if (this.options.sendRpc !== undefined) {
+      const { resolveSource } = await import('../source.js')
+      const config = clientSourceConfigs.get(this.client)
+      sender = resolveSource(this.options.sendRpc, config?.cluster, config?.options, config?.genesis).transport
+    }
+    const nodes = sender instanceof FallbackRpc ? sender.nodes : [sender]
+    return this.options.broadcast === 'all' && nodes.length > 1 ? nodes.map((node) => new FallbackRpc([node])) : [sender]
+  }
+
+  /**
+   * 广播：'accepted'（第一个接受的节点返回就结束，其余节点在后台继续）；没有节点接受时，有节点明确拒绝（或节点不在同一个网络）则抛出，
+   * 否则返回错误说明（节点都连不上，交易可能已经发出）
+   */
+  async broadcast(raw: string): Promise<'accepted' | { uncertain: string }> {
+    const params = [raw, { encoding: 'base64', skipPreflight: true, maxRetries: 0 }]
+    const attempts = (await this.#targets()).map((target) =>
+      target.request('sendTransaction', params).then(
+        () => 'accepted' as const,
+        (err: unknown) => {
+          if (/already (been )?processed/i.test(errorText(err))) {
+            return 'accepted' as const
+          }
+          throw err
+        },
+      ),
+    )
+    // 返回后还没结束的节点照常在后台完成：吞掉它们的拒绝，避免未处理的 rejection
+    attempts.forEach((attempt) => attempt.catch(() => {}))
+    try {
+      return await Promise.any(attempts)
+    } catch (err) {
+      const errors: unknown[] = err instanceof AggregateError ? err.errors : [err]
+      const rejected = errors.find((e) => (e instanceof RpcError && !isNodeFault(e)) || isNetworkMismatch(e))
+      if (rejected) {
+        throw rejected
+      }
+      return { uncertain: `broadcast not acknowledged: ${errors.map(errorText).join(' | ')}` }
+    }
+  }
+}
+
+/** 按 SendOptions 取优先费用单价（micro-lamports / 计算单元）；writable 是交易里的可写账户 */
+export function priorityFeeFor(client: SolanaClient, options: SendOptions, writable: readonly string[]): Promise<bigint> {
+  return new Chain(client, options).priorityFee(writable)
+}
+
+/** 节点不在同一个网络（source.ts 的 NetworkMismatchError）：按 name 判断，免得为 instanceof 静态带上 source.ts */
+function isNetworkMismatch(err: unknown): boolean {
+  return err instanceof Error && err.name === 'NetworkMismatchError'
+}

package/src/write/collect.ts

@@ -1,4 +1,4 @@
-import { getAssociatedTokenAddress, isAddress } from '../address.js'
+import { getAssociatedTokenAddress, InvalidAddressError, isAddress } from '../address.js'
 import type { SolanaClient } from '../client.js'
 import { formatUnits } from '../layout.js'
 import type { TokenBalance } from '../types.js'
@@ -71,7 +71,7 @@ interface Item {
  */
 export async function batchCollect(client: SolanaClient, wallets: readonly SignerInput[], to: string, options: BatchCollectOptions): Promise<CollectResult> {
   if (!isAddress(to)) {
-    throw new Error(`Invalid collect address: ${to}`)
+    throw new InvalidAddressError(`Invalid collect address: ${to}`, to)
   }
   const cache = new Map()
   const signers = await Promise.all(wallets.map((w) => resolveSigner(w, cache)))