@w3lib/solana-batch-call 0.3.0 → 0.5.0

package/src/rpc.ts

@@ -62,6 +62,31 @@ const TRANSIENT = /\bbusy\b|overload|temporar(il)?y|unavailable|try again|timed?
 
 /** 节点限制单次 getMultipleAccounts 的账户数（如 “Too many accounts requested”）：缩小每次的账户数后重试，不是节点故障 */
 const TOO_MANY_ACCOUNTS = /too many accounts/i
+/**
+ * publicnode 对单次超过 10 个账户的 getMultipleAccounts 返回 HTTP 403 +“Request blocked”（2026-10，而且要等 3 秒多才返回）：
+ * 账户数超过 BLOCKED_LIMIT 时直接按它拆分（逐次减半要多等好几轮），还被拒绝再减半；
+ * 账户数已经很少（≤ BLOCKED_FLOOR）还被拒绝时，是节点真的拒绝访问，交给上层换节点
+ */
+const REQUEST_BLOCKED = /request blocked/i
+const BLOCKED_LIMIT = 10
+const BLOCKED_FLOOR = 8
+
+/** 从报错里学到的节点限制，按节点地址共享（同一个节点的多个客户端不用各自再试一遍） */
+const learnedLimits = new Map<string, { methods: Map<string, number>; maxAccounts?: number }>()
+
+function learnedFor(url: string): { methods: Map<string, number>; maxAccounts?: number } {
+  let entry = learnedLimits.get(url)
+  if (!entry) {
+    entry = { methods: new Map() }
+    learnedLimits.set(url, entry)
+  }
+  return entry
+}
+
+/** 测试用：清空学到的节点限制 */
+export function resetLearnedLimits(): void {
+  learnedLimits.clear()
+}
 
 /** HTTP 层错误（非 2xx、网络错误、超时） */
 export class HttpError extends Error {
@@ -178,20 +203,19 @@ export class HttpRpc implements RpcTransport {
   readonly #retries: number
   readonly #fetch: typeof fetch
   #maxBatchSize: number
-  /** 节点对单个方法在一个批量里的数量限制（如 publicnode：getMultipleAccounts 最多 1 个），从报错里学到 */
-  readonly #methodLimits = new Map<string, number>()
+  /** 从报错里学到的限制（按节点地址共享）：单个方法在一个批量里的数量（如 publicnode：getMultipleAccounts 最多 1 个）、单次的账户数 */
+  readonly #learned: { methods: Map<string, number>; maxAccounts?: number }
   /** options.batch：调用方是否允许批量 */
   readonly #batchOption: boolean
   /** 节点明确表示不支持批量时，在这之前逐条请求（之后重新尝试批量） */
   #batchDisabledUntil = 0
-  /** 节点限制单次 getMultipleAccounts 的账户数时学到的上限 */
-  #maxAccounts: number | undefined
   #queue: Pending[] = []
   #timer: ReturnType<typeof setTimeout> | null = null
 
   constructor(url: string, options: HttpRpcOptions = {}) {
     this.url = url
     this.#safeUrl = safeOrigin(url)
+    this.#learned = learnedFor(url)
     this.#timeout = options.timeout ?? 10_000
     this.#headers = { 'content-type': 'application/json', ...options.headers }
     this.#maxBatchSize = Math.max(1, options.maxBatchSize ?? 20)
@@ -214,7 +238,7 @@ export class HttpRpc implements RpcTransport {
    */
   async #getMultipleAccounts(params: readonly unknown[]): Promise<unknown> {
     const [addresses, ...rest] = params as [unknown[], ...unknown[]]
-    const max = this.#maxAccounts
+    const max = this.#learned.maxAccounts
     if (max !== undefined && addresses.length > max) {
       const parts: unknown[][] = []
       for (let i = 0; i < addresses.length; i += max) {
@@ -234,8 +258,11 @@ export class HttpRpc implements RpcTransport {
     try {
       return await this.#enqueue('getMultipleAccounts', params)
     } catch (err) {
-      if (err instanceof RpcError && TOO_MANY_ACCOUNTS.test(err.message) && addresses.length > 1) {
-        this.#maxAccounts = Math.max(1, Math.min(this.#maxAccounts ?? Number.POSITIVE_INFINITY, Math.floor(addresses.length / 2)))
+      const tooMany = err instanceof RpcError && TOO_MANY_ACCOUNTS.test(err.message) && addresses.length > 1
+      const blocked = err instanceof RpcError && REQUEST_BLOCKED.test(err.message) && addresses.length > BLOCKED_FLOOR
+      if (tooMany || blocked) {
+        const next = blocked && addresses.length > BLOCKED_LIMIT ? BLOCKED_LIMIT : Math.floor(addresses.length / 2)
+        this.#learned.maxAccounts = Math.max(1, Math.min(this.#learned.maxAccounts ?? Number.POSITIVE_INFINITY, next))
         return this.#getMultipleAccounts(params)
       }
       throw err
@@ -276,7 +303,7 @@ export class HttpRpc implements RpcTransport {
     let current: Pending[] = []
     let counts = new Map<string, number>()
     for (const item of items) {
-      const limit = this.#methodLimits.get(item.method)
+      const limit = this.#learned.methods.get(item.method)
       const count = counts.get(item.method) ?? 0
       if (current.length >= this.#maxBatchSize || (limit !== undefined && count >= limit)) {
         chunks.push(current)
@@ -303,7 +330,7 @@ export class HttpRpc implements RpcTransport {
     if (!method || !Number.isFinite(limit) || limit < 1 || items.filter((item) => item.method === method).length <= limit) {
       return false
     }
-    this.#methodLimits.set(method, limit)
+    this.#learned.methods.set(method, limit)
     await Promise.all(this.#split(items).map((chunk) => this.#dispatch(chunk)))
     return true
   }

package/src/subpaths/approvals.ts

@@ -0,0 +1,47 @@
+/**
+ * 授权管理（子路径 `@w3lib/solana-batch-call/approvals`）：批量查地址的代币账户给出的授权（delegate）、可以关闭回收租金的空账户，
+ * 批量撤销 / 关闭。不放在主入口，不用时打包不会带上这部分代码；发送的代码按需加载。
+ *
+ * ```ts
+ * import { closeTokenAccounts, getApprovals, revokeApprovals } from '@w3lib/solana-batch-call/approvals'
+ *
+ * const list = await getApprovals(owner, { mints: [USDC, BONK] })
+ * await revokeApprovals(client, key, list)
+ * await closeTokenAccounts(client, key, list.filter((a) => a.amount === '0'))
+ * ```
+ */
+import { approvals, type ApprovalsQuery, type TokenAccountApproval } from '../approvals.js'
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+
+export {
+  approvals,
+  buildCloses,
+  buildRevokes,
+  closeTokenAccounts,
+  parseTokenAccountState,
+  revokeApprovals,
+  type ApprovalCall,
+  type ApprovalResult,
+  type ApprovalsQuery,
+  type BuildClosesOptions,
+  type CloseAccountsOptions,
+  type CloseBlocker,
+  type TokenAccountApproval,
+} from '../approvals.js'
+export { closeAccount, harvestWithheldTokensToMint, revoke } from '../write/instructions.js'
+
+export interface GetApprovalsOptions extends ApprovalsQuery, ShortcutOptions {}
+
+/**
+ * 查地址的代币账户给出的授权和可以关闭的空账户，节点参数与 getBalances 相同。
+ *
+ * ```ts
+ * await getApprovals(owner, { mints: [USDC, BONK] })                  // 指定代币：读 ATA，免费公共节点也能用
+ * await getApprovals(owner, { provider: 'https://my-rpc…' })         // 全部代币账户：需要支持 getTokenAccountsByOwner 的节点
+ * // [{ account, mint: USDC, symbol: 'USDC', delegate: 'GYFk…', delegatedAmount: '6993125', revocable: true, closable: false, closeBlocker: 'balance', … }]
+ * ```
+ */
+export function getApprovals(owner: string, options: GetApprovalsOptions = {}): Promise<TokenAccountApproval[]> {
+  const { client, own } = resolve(options, ['mints', 'all', 'signal'])
+  return approvals(client, owner, own)
+}

package/src/subpaths/fees.ts

@@ -0,0 +1,41 @@
+/**
+ * 手续费估算（子路径 `@w3lib/solana-batch-call/fees`）：三档优先费建议，一笔交易的花费（基础费 + 优先费 + 新建账户的押金）。
+ * 不放在主入口，不用时打包不会带上这部分代码；模拟交易的代码按需加载。
+ *
+ * ```ts
+ * import { getCostEstimate, getFeeEstimate } from '@w3lib/solana-batch-call/fees'
+ *
+ * await getFeeEstimate({ accounts: [pool] })
+ * await getCostEstimate({ feePayer: owner, instructions })
+ * ```
+ */
+import { estimateCost, estimateFees, type CostEstimate, type CostInput, type EstimateCostOptions, type EstimateFeesOptions, type PriorityFeeEstimate } from '../fees.js'
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+
+export {
+  estimateCost,
+  estimateFees,
+  type CostEstimate,
+  type CostInput,
+  type CreatedAccount,
+  type EstimateCostOptions,
+  type EstimateFeesOptions,
+  type FeeLevel,
+  type PriorityFeeEstimate,
+} from '../fees.js'
+
+export interface GetFeeEstimateOptions extends EstimateFeesOptions, ShortcutOptions {}
+
+/** 当前的三档优先费建议（micro-lamports / 计算单元），节点参数与 getBalances 相同 */
+export function getFeeEstimate(options: GetFeeEstimateOptions = {}): Promise<PriorityFeeEstimate> {
+  const { client, own } = resolve(options, ['accounts', 'percentiles', 'signal'])
+  return estimateFees(client, own)
+}
+
+export interface GetCostEstimateOptions extends EstimateCostOptions, ShortcutOptions {}
+
+/** 一笔交易的花费（基础费 + 优先费 + 新建账户的押金），模拟一次、不发送 */
+export function getCostEstimate(input: CostInput, options: GetCostEstimateOptions = {}): Promise<CostEstimate> {
+  const { client, own } = resolve(options, ['percentiles', 'level', 'priorityFee', 'fees', 'signal'])
+  return estimateCost(client, input, own)
+}

package/src/subpaths/liquidity.ts

@@ -0,0 +1,45 @@
+/**
+ * 添加 / 移除流动性（子路径 `@w3lib/solana-batch-call/liquidity`）：Raydium CLMM、Orca Whirlpool（仓位 NFT），
+ * Raydium AMM v4、CPMM（LP 代币）。不放在主入口，不用时打包不会带上这部分代码。不依赖各 DEX 的 SDK。
+ *
+ * - build*：只读取、不签名，返回预计的数量和按顺序执行的指令，可以当作报价，也可以自己组交易发送
+ * - addLiquidity / removeLiquidity / collectFees：构建后签名发送（同 /write 的 batchCall），SOL 自动包装 / 解包
+ *
+ * ```ts
+ * import { getLpPositions } from '@w3lib/solana-batch-call/lp'
+ * import { addLiquidity, removeLiquidity } from '@w3lib/solana-batch-call/liquidity'
+ *
+ * await addLiquidity(client, secretKey, { protocol: 'raydium-clmm', pool, priceLower: 120, priceUpper: 180, amount0Formatted: '1' })
+ * const [position] = await getLpPositions(owner, { provider: rpc })
+ * await removeLiquidity(client, secretKey, { position, percent: 50 })
+ * ```
+ */
+export { addLiquidity, buildAddLiquidity, buildCollectFees, buildRemoveLiquidity, collectFees, removeLiquidity } from '../liquidity/index.js'
+export type {
+  SolanaAddLiquidityParams,
+  SolanaCollectFeesParams,
+  SolanaIncreaseLiquidityParams,
+  SolanaLiquidityOptions,
+  SolanaLiquidityPlan,
+  SolanaLiquidityResult,
+  SolanaLiquiditySendOptions,
+  SolanaLiquidityStep,
+  SolanaLiquidityStepResult,
+  SolanaNewPositionParams,
+  SolanaPositionRef,
+  SolanaRemoveLiquidityParams,
+} from '../liquidity/types.js'
+export {
+  getLiquidityForAmounts,
+  getMaxAmounts,
+  getMinAmounts,
+  getMintAmounts,
+  nearestUsableTick,
+  priceToTick,
+  sqrtPriceAtTick,
+  tickAtSqrtPrice,
+  type ClmmProgram,
+} from '../lpMath.js'
+export type { SolanaLpPosition, SolanaLpProtocol, SolanaLpToken } from '../lp.js'
+export type { Instruction } from '../write/transaction.js'
+export type { SignerInput, WriteResult, WriteStatus } from '../subpaths/write.js'

package/src/subpaths/lp.ts

@@ -34,10 +34,19 @@ export {
   getAmountsForLiquidity,
   getFeeGrowthInside,
   getFeesOwed,
+  getLiquidityForAmounts,
+  getMaxAmounts,
+  getMinAmounts,
+  getMintAmounts,
+  nearestUsableTick,
   orcaSqrtPriceAtTick,
+  priceToTick,
   raydiumSqrtPriceAtTick,
+  sqrtPriceAtTick,
   sqrtPriceToPrice,
+  tickAtSqrtPrice,
   tickToPrice,
+  type ClmmProgram,
   type TickFeeData,
 } from '../lpMath.js'
 

package/src/subpaths/names.ts

@@ -0,0 +1,45 @@
+/**
+ * 域名解析（子路径 `@w3lib/solana-batch-call/names`）：SNS（Bonfida，`.sns`），名字 → 地址、地址 → 主域名。
+ * 不放在主入口，不用时打包不会带上这部分代码。
+ *
+ * ```ts
+ * import { getAddressNames, getNameAddresses } from '@w3lib/solana-batch-call/names'
+ *
+ * await getNameAddresses(['bonfida.sns', 'toly.sns'])
+ * await getAddressNames([wallet])
+ * ```
+ */
+import type { RequestOptions } from '../client.js'
+import { lookupAddresses, resolveNames, type AddressName, type NamesOptions, type ResolvedName } from '../names.js'
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+
+export { NAME_PROGRAM_ID, SNS_ROOT_DOMAIN, lookupAddresses, resolveNames, snsDomainKey, type AddressName, type NameSource, type NamesOptions, type ResolvedName } from '../names.js'
+
+export interface GetNamesOptions extends NamesOptions, ShortcutOptions {}
+
+/**
+ * 名字 → 地址，节点参数与 getBalances 相同。
+ *
+ * ```ts
+ * await getNameAddresses(['bonfida.sns', 'toly.sns'])
+ * // [{ name: 'bonfida.sns', normalized: 'bonfida.sns', address: 'Fw1E…Lb1v', owner: 'Fw1E…Lb1v', source: 'owner', service: 'sns' }, …]
+ * ```
+ */
+export function getNameAddresses(names: readonly string[], options: GetNamesOptions = {}): Promise<ResolvedName[]> {
+  const { client, own } = resolve(options, ['legacySol', 'allowPda', 'signal'])
+  return resolveNames(client, names, own)
+}
+
+export interface GetAddressNamesOptions extends RequestOptions, ShortcutOptions {}
+
+/**
+ * 地址 → 主域名（核对过属于这个地址）。
+ *
+ * ```ts
+ * await getAddressNames([wallet])   // [{ address: wallet, name: 'bonfida.sns', service: 'sns' }]
+ * ```
+ */
+export function getAddressNames(addresses: readonly string[], options: GetAddressNamesOptions = {}): Promise<AddressName[]> {
+  const { client, own } = resolve(options, ['signal'])
+  return lookupAddresses(client, addresses, own)
+}

package/src/subpaths/price.ts

@@ -0,0 +1,62 @@
+/**
+ * 价格（子路径 `@w3lib/solana-batch-call/price`）：代币的美元价格（DefiLlama 当前 / 历史价格，没有收录的从链上 Raydium / Orca 池子算）、
+ * 组合价格源、地址的资产总值。不放在主入口，不用时打包不会带上这部分代码。
+ *
+ * ```ts
+ * import { NATIVE_MINT } from '@w3lib/solana-batch-call'
+ * import { getPortfolio, getTokenPrices } from '@w3lib/solana-batch-call/price'
+ *
+ * await getTokenPrices([NATIVE_MINT, USDC, newToken])
+ * await getPortfolio(owner, { tokens: [NATIVE_MINT, USDC, JUP] })
+ * ```
+ */
+import { portfolio, type Portfolio, type PortfolioOptions } from '../portfolio.js'
+import { tokenPrices, type TokenPrice, type TokenPricesOptions } from '../price.js'
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+
+export { portfolio, type Portfolio, type PortfolioOptions, type PortfolioToken } from '../portfolio.js'
+export {
+  STABLECOINS,
+  combinePrices,
+  defillamaPrices,
+  onchainPrices,
+  tokenPrices,
+  type DefillamaPriceOptions,
+  type OnchainPriceOptions,
+  type OnchainPriceProtocol,
+  type SolanaPriceSource,
+  type SolanaPriceSourceContext,
+  type TokenPrice,
+  type TokenPricesOptions,
+} from '../price.js'
+
+export interface GetTokenPricesOptions extends TokenPricesOptions, ShortcutOptions {}
+
+/**
+ * 查代币的美元价格（SOL 用 NATIVE_MINT），节点参数与 getBalances 相同。
+ *
+ * ```ts
+ * await getTokenPrices([NATIVE_MINT, USDC])
+ * // [{ token: 'So111…112', native: true, price: 187.4, source: 'defillama' }, { token: USDC, native: false, price: 1, source: 'defillama' }]
+ * ```
+ */
+export function getTokenPrices(mints: readonly string[], options: GetTokenPricesOptions = {}): Promise<TokenPrice[]> {
+  // fetch 同时给节点请求（客户端配置）和查价用，与 getLpPositions 一致
+  const { client, own } = resolve(options, ['sources', 'onError', 'signal'])
+  return tokenPrices(client, mints, { ...own, ...(options.fetch ? { fetch: options.fetch } : {}) })
+}
+
+export interface GetPortfolioOptions extends PortfolioOptions, ShortcutOptions {}
+
+/**
+ * 地址的资产总值：代币余额 × 价格，可选加上 LP 仓位（lp: true）。
+ *
+ * ```ts
+ * await getPortfolio(owner, { tokens: [NATIVE_MINT, USDC, JUP] })              // 指定代币：免费公共节点也能用
+ * await getPortfolio(owner, { provider: 'https://my-rpc…', lp: true })         // 全部持仓 + LP：需要支持 getTokenAccountsByOwner 的节点
+ * ```
+ */
+export function getPortfolio(owner: string, options: GetPortfolioOptions = {}): Promise<Portfolio> {
+  const { client, own } = resolve(options, ['tokens', 'sources', 'lp', 'minUsd', 'onPriceError', 'signal'])
+  return portfolio(client, owner, { ...own, ...(options.fetch ? { fetch: options.fetch } : {}) })
+}

package/src/subpaths/risk.ts

@@ -0,0 +1,36 @@
+/**
+ * 代币风险检查（子路径 `@w3lib/solana-batch-call/risk`）：mint 的增发 / 冻结权限，Token-2022 扩展里影响持有人的设置
+ * （转账手续费、永久授权、转账 hook、不可转让、默认冻结、可暂停、保密转账、mint 可关闭等），可选持币集中度；
+ * tradeChecks 在主网模拟“买入 → 卖出”判断能不能卖（用 /swap，不用时打包不会带上）。不放在主入口，不用时打包不会带上这部分代码。
+ *
+ * ```ts
+ * import { getTokenRisks, getTradeChecks } from '@w3lib/solana-batch-call/risk'
+ *
+ * const [risk] = await getTokenRisks([mint])
+ * if (risk.flags.includes('permanent-delegate')) alert('发行方可以转走你的代币')
+ * const [trade] = await getTradeChecks([mint], { owner: myAddress })
+ * if (trade.honeypot) alert('卖不出')
+ * ```
+ */
+import { tokenRisks, type SolanaTokenRisk, type TokenRisksOptions } from '../risk.js'
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+import { tradeChecks, type SolanaTradeCheck, type TradeCheckOptions } from '../tradeCheck.js'
+
+export { parseRisk, tokenRisks, type SolanaTokenRisk, type TokenRisksOptions } from '../risk.js'
+export { tradeChecks, type SolanaTradeCheck, type TradeCheckOptions, type TradeStage } from '../tradeCheck.js'
+
+export interface GetTokenRisksOptions extends TokenRisksOptions, ShortcutOptions {}
+
+/** 检查代币的风险（一次 getMultipleAccounts），节点参数与 getBalances 相同 */
+export function getTokenRisks(mints: readonly string[], options: GetTokenRisksOptions = {}): Promise<SolanaTokenRisk[]> {
+  const { client, own } = resolve(options, ['concentration', 'signal'])
+  return tokenRisks(client, mints, own)
+}
+
+export interface GetTradeChecksOptions extends TradeCheckOptions, ShortcutOptions {}
+
+/** 模拟买入再卖出，判断能不能交易，节点参数与 getBalances 相同 */
+export function getTradeChecks(mints: readonly string[], options: GetTradeChecksOptions): Promise<SolanaTradeCheck[]> {
+  const { client, own } = resolve(options, ['owner', 'amount', 'amountFormatted', 'protocols', 'intermediates', 'pools', 'discover', 'signal'])
+  return tradeChecks(client, mints, own as TradeCheckOptions)
+}

package/src/subpaths/swap.ts

@@ -0,0 +1,41 @@
+/**
+ * 兑换（子路径 `@w3lib/solana-batch-call/swap`）：在 Raydium CLMM、Orca Whirlpool、Raydium CPMM、Raydium AMM v4 的池子里找最好的路线
+ * （直接或经过 SOL / USDC / USDT 的两跳），本地报价并构建 / 发送兑换交易。不放在主入口，不用时打包不会带上这部分代码。不依赖各 DEX 的 SDK。
+ *
+ * ```ts
+ * import { NATIVE_MINT } from '@w3lib/solana-batch-call'
+ * import { getSwapQuote, swap } from '@w3lib/solana-batch-call/swap'
+ *
+ * const plan = await getSwapQuote(owner, { tokenIn: NATIVE_MINT, tokenOut: USDC, amountInFormatted: '0.5' })
+ * await swap(client, secretKey, { tokenIn: NATIVE_MINT, tokenOut: USDC, amountInFormatted: '0.5' }, { slippage: 0.01 })
+ * ```
+ */
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+import { buildSwap, type SolanaSwapOptions, type SolanaSwapParams, type SolanaSwapPlan } from '../swap/index.js'
+
+export {
+  SWAP_INTERMEDIATES,
+  SWAP_PROTOCOLS,
+  buildSwap,
+  swap,
+  type SolanaSwapHop,
+  type SolanaSwapOptions,
+  type SolanaSwapParams,
+  type SolanaSwapPlan,
+  type SolanaSwapProtocol,
+  type SolanaSwapResult,
+  type SolanaSwapRoute,
+  type SolanaSwapSendOptions,
+  type SolanaSwapStep,
+  type SolanaSwapStepResult,
+} from '../swap/index.js'
+export type { Instruction } from '../write/transaction.js'
+export type { SignerInput, WriteResult, WriteStatus } from '../subpaths/write.js'
+
+export interface GetSwapQuoteOptions extends SolanaSwapOptions, ShortcutOptions {}
+
+/** 报价并构建兑换的指令（同 buildSwap），节点参数与 getBalances 相同 */
+export function getSwapQuote(owner: string, params: SolanaSwapParams, options: GetSwapQuoteOptions = {}): Promise<SolanaSwapPlan> {
+  const { client, own } = resolve(options, ['slippage', 'native', 'protocols', 'intermediates', 'pools', 'discover', 'signal'])
+  return buildSwap(client, owner, params, own)
+}

package/src/subpaths/write.ts

@@ -19,6 +19,8 @@ export {
   COMPUTE_BUDGET_PROGRAM_ID,
   closeAccount,
   createAssociatedTokenAccountIdempotent,
+  harvestWithheldTokensToMint,
+  revoke,
   setComputeUnitLimit,
   setComputeUnitPrice,
   systemTransfer,

package/src/swap/amm.ts

@@ -0,0 +1,88 @@
+/**
+ * Raydium AMM v4 的兑换：swap_base_in_v2（指令 16，不需要 OpenBook 账户）。报价照搬程序（raydium-amm processor.rs）：
+ * 手续费 = ceil(输入 × swap_fee_numerator / swap_fee_denominator)，储备 = 金库余额 − need_take_pnl，恒定乘积向下取整。只支持 SPL Token
+ */
+import { TOKEN_PROGRAM_ID } from '../constants.js'
+import { parseTokenAccount, type AccountInfo } from '../layout.js'
+import { RAYDIUM_AMM_AUTHORITY, RAYDIUM_AMM_PROGRAM_ID } from '../lp.js'
+import { Writer, r, w } from '../liquidity/common.js'
+import type { Instruction } from '../write/transaction.js'
+import { Bytes, UnsupportedPool, mulDivCeil, mulDivFloor, need, swapMint, type AccountGetter, type HopQuote, type SwapMint, type SwapPool } from './common.js'
+
+const POOL_SIZE = 752
+/**
+ * 只支持 SwapOnly（6，不再用 OpenBook 挂单，现在的池子基本都是）：swap_base_in_v2 不带 OpenBook 账户，
+ * 还连着 OpenBook 的池子（Initialized 1、WaitingTrade 7）没有对照程序源码验证过能不能用，不报价，免得排第一后在链上失败
+ */
+const SWAP_STATUSES = new Set([6n])
+
+interface AmmState {
+  address: string
+  status: bigint
+  swapFeeNumerator: bigint
+  swapFeeDenominator: bigint
+  needTakePnl0: bigint
+  needTakePnl1: bigint
+  openTime: bigint
+  vault0: string
+  vault1: string
+  mint0: string
+  mint1: string
+}
+
+/** AmmInfo（无判别符）：status 0、fees.swap_fee 176 / 184、need_take_pnl_coin 192、need_take_pnl_pc 200、pool_open_time 224、vault 336 / 368、mint 400 / 432 */
+export function parseAmmV4Pool(account: AccountInfo): AmmState | null {
+  if (account.owner !== RAYDIUM_AMM_PROGRAM_ID || account.data.length !== POOL_SIZE) return null
+  const b = new Bytes(account.data)
+  return {
+    address: account.address,
+    status: b.u64(0),
+    swapFeeNumerator: b.u64(176),
+    swapFeeDenominator: b.u64(184),
+    needTakePnl0: b.u64(192),
+    needTakePnl1: b.u64(200),
+    openTime: b.u64(224),
+    vault0: b.key(336),
+    vault1: b.key(368),
+    mint0: b.key(400),
+    mint1: b.key(432),
+  }
+}
+
+export function ammV4Pool(state: AmmState): SwapPool {
+  const mints = (get: AccountGetter): [SwapMint, SwapMint] => [
+    swapMint(state.mint0, need(get, state.mint0, 'Token mint')),
+    swapMint(state.mint1, need(get, state.mint1, 'Token mint')),
+  ]
+  return {
+    protocol: 'raydium-amm',
+    address: state.address,
+    mint0: state.mint0,
+    mint1: state.mint1,
+    mints,
+    accounts: () => [state.vault0, state.vault1, state.mint0, state.mint1],
+    quote(get, amountIn, zeroForOne, env): HopQuote {
+      if (!SWAP_STATUSES.has(state.status)) throw new UnsupportedPool(`Swap is not allowed in pool status ${state.status}`)
+      if (env.timestamp < state.openTime) throw new UnsupportedPool('Pool is not open yet')
+      if (state.swapFeeDenominator === 0n) throw new UnsupportedPool('Invalid pool fees')
+      const [m0, m1] = mints(get)
+      if (m0.program !== TOKEN_PROGRAM_ID || m1.program !== TOKEN_PROGRAM_ID) throw new UnsupportedPool('AMM v4 supports only SPL Token mints')
+      const v0 = parseTokenAccount(need(get, state.vault0, 'Pool vault').data).amount
+      const v1 = parseTokenAccount(need(get, state.vault1, 'Pool vault').data).amount
+      if (v0 < state.needTakePnl0 || v1 < state.needTakePnl1) throw new UnsupportedPool('Pool vault is below the pending PnL')
+      const [reserveIn, reserveOut] = zeroForOne ? [v0 - state.needTakePnl0, v1 - state.needTakePnl1] : [v1 - state.needTakePnl1, v0 - state.needTakePnl0]
+      const fee = mulDivCeil(amountIn, state.swapFeeNumerator, state.swapFeeDenominator)
+      const afterFee = amountIn - fee
+      const out = afterFee > 0n ? mulDivFloor(reserveOut, afterFee, reserveIn + afterFee) : 0n
+      // 程序要求输出小于储备
+      return { amountIn, amountOut: out < reserveOut ? out : 0n, accounts: [] }
+    },
+    instruction(_get, owner, input, output, _zeroForOne, quote, minOut): Instruction {
+      return {
+        programId: RAYDIUM_AMM_PROGRAM_ID,
+        keys: [r(TOKEN_PROGRAM_ID), w(state.address), r(RAYDIUM_AMM_AUTHORITY), w(state.vault0), w(state.vault1), w(input), w(output), r(owner, true)],
+        data: new Writer().u8(16).u64(quote.amountIn).u64(minOut).build(),
+      }
+    },
+  }
+}

package/src/swap/clmmMath.ts

@@ -0,0 +1,96 @@
+/**
+ * 集中流动性兑换一步的计算（只做按输入数量兑换），照搬 Raydium CLMM（libraries/swap_math.rs、sqrt_price_math.rs、liquidity_math.rs）
+ * 和 Orca Whirlpool（math/swap_math.rs、token_math.rs）。两个程序“手续费从输入扣”时的公式和取整完全相同；Raydium 另有“手续费从输出扣”的池子
+ */
+import { U64_MAX, mulDivCeil } from './common.js'
+
+const Q64 = 1n << 64n
+export const FEE_RATE_DENOMINATOR = 1_000_000n
+
+export class SwapMathError extends Error {}
+
+/** 价格从 a 到 b（任意顺序）对应的 token0 数量：L · 2^64 · (hi − lo) / (lo · hi) */
+export function amount0Delta(a: bigint, b: bigint, liquidity: bigint, roundUp: boolean): bigint {
+  const [lo, hi] = a < b ? [a, b] : [b, a]
+  if (lo === 0n) throw new SwapMathError('zero sqrt price')
+  const num = (liquidity * (hi - lo)) << 64n
+  const den = lo * hi
+  return roundUp ? (num + den - 1n) / den : num / den
+}
+
+/** 价格从 a 到 b 对应的 token1 数量：L · (hi − lo) / 2^64 */
+export function amount1Delta(a: bigint, b: bigint, liquidity: bigint, roundUp: boolean): bigint {
+  const [lo, hi] = a < b ? [a, b] : [b, a]
+  const p = liquidity * (hi - lo)
+  return roundUp ? (p + Q64 - 1n) >> 64n : p >> 64n
+}
+
+/** 卖出 amount 后的 sqrt 价格（向不越过目标价格的方向取整）：卖 token0 时价格下降，卖 token1 时上升 */
+export function nextSqrtPriceFromInput(sqrtPrice: bigint, liquidity: bigint, amount: bigint, zeroForOne: boolean): bigint {
+  if (liquidity === 0n) throw new SwapMathError('zero liquidity')
+  if (amount === 0n) return sqrtPrice
+  if (zeroForOne) {
+    const num = liquidity << 64n
+    const den = num + amount * sqrtPrice
+    return mulDivCeil(num, sqrtPrice, den)
+  }
+  return sqrtPrice + (amount << 64n) / liquidity
+}
+
+export interface SwapStep {
+  /** 走到的 sqrt 价格 */
+  sqrtPrice: bigint
+  /** 计入价格变动的输入（不含手续费） */
+  amountIn: bigint
+  /** 给用户的输出（手续费从输出扣时已扣除） */
+  amountOut: bigint
+  feeAmount: bigint
+}
+
+/**
+ * 一步兑换：从当前价格向目标价格，最多用 remaining 个输入。
+ * feeOnInput（Orca 和 Raydium 的默认）：输入先按费率扣手续费；否则（Raydium fee_on）：输出按费率扣
+ */
+export function computeSwapStep(
+  sqrtCurrent: bigint,
+  sqrtTarget: bigint,
+  liquidity: bigint,
+  remaining: bigint,
+  feeRate: bigint,
+  zeroForOne: boolean,
+  feeOnInput: boolean,
+  program: 'raydium' | 'orca',
+): SwapStep {
+  const amountForPrice = feeOnInput ? (remaining * (FEE_RATE_DENOMINATOR - feeRate)) / FEE_RATE_DENOMINATOR : remaining
+  // 走到目标价格需要的输入（向上取整）和得到的输出（向下取整）；超过 u64 视为走不到
+  const inAtTarget = zeroForOne ? amount0Delta(sqrtTarget, sqrtCurrent, liquidity, true) : amount1Delta(sqrtCurrent, sqrtTarget, liquidity, true)
+  let sqrtNext: bigint
+  let amountIn: bigint
+  let amountOut: bigint
+  const outAtTarget = () => (zeroForOne ? amount1Delta(sqrtTarget, sqrtCurrent, liquidity, false) : amount0Delta(sqrtCurrent, sqrtTarget, liquidity, false))
+  let reached = inAtTarget <= U64_MAX && amountForPrice >= inAtTarget
+  // Raydium：目标价格处的输出超过 u64 也算走不到；Orca 照常走到目标（之后报错）
+  const out = reached ? outAtTarget() : 0n
+  if (reached && program === 'raydium' && out > U64_MAX) reached = false
+  if (reached) {
+    sqrtNext = sqrtTarget
+    amountIn = inAtTarget
+    amountOut = out
+  } else {
+    sqrtNext = nextSqrtPriceFromInput(sqrtCurrent, liquidity, amountForPrice, zeroForOne)
+    amountIn = zeroForOne ? amount0Delta(sqrtNext, sqrtCurrent, liquidity, true) : amount1Delta(sqrtCurrent, sqrtNext, liquidity, true)
+    amountOut = zeroForOne ? amount1Delta(sqrtNext, sqrtCurrent, liquidity, false) : amount0Delta(sqrtCurrent, sqrtNext, liquidity, false)
+  }
+  if (amountIn > U64_MAX || amountOut > U64_MAX) throw new SwapMathError('token amount exceeds u64')
+  if (zeroForOne ? sqrtNext < sqrtTarget : sqrtNext > sqrtTarget) throw new SwapMathError('price moved past the target')
+  let feeAmount: bigint
+  if (feeOnInput) {
+    feeAmount = sqrtNext !== sqrtTarget ? remaining - amountIn : mulDivCeil(amountIn, feeRate, FEE_RATE_DENOMINATOR - feeRate)
+  } else {
+    feeAmount = mulDivCeil(amountOut, feeRate, FEE_RATE_DENOMINATOR)
+    amountOut -= feeAmount
+    // 没走到目标价格：输入全部用掉（不足一个单位的零头归池子）
+    if (sqrtNext !== sqrtTarget) amountIn = remaining
+  }
+  return { sqrtPrice: sqrtNext, amountIn, amountOut, feeAmount }
+}