@w3lib/solana-batch-call 0.4.0 → 0.6.0

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/history.ts

@@ -0,0 +1,38 @@
+/**
+ * 交易历史（子路径 `@w3lib/solana-batch-call/history`）：地址的交易整理成统一的 Activity（兑换、转账、授权、流动性、铸造、失败……），
+ * 数据源可换（默认节点：getSignaturesForAddress + getTransaction；可选 Helius 增强历史）。不放在主入口，不用时打包不会带上这部分代码。
+ *
+ * ```ts
+ * import { getHistory, heliusHistory } from '@w3lib/solana-batch-call/history'
+ *
+ * const page = await getHistory(address, { limit: 20 })
+ * const next = await getHistory(address, { cursor: page.nextCursor, types: ['swap'] })
+ * await getHistory(address, { source: [heliusHistory({ apiKey }), rpcHistory()] })   // 依次尝试
+ * ```
+ */
+import { history, type HistoryOptions, type HistoryPage } from '../history.js'
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+
+export {
+  MAX_HISTORY_LIMIT,
+  activityFromTransaction,
+  history,
+  rpcHistory,
+  type Activity,
+  type ActivityChange,
+  type ActivityType,
+  type HistoryContext,
+  type HistoryOptions,
+  type HistoryPage,
+  type HistorySource,
+  type RpcHistoryOptions,
+} from '../history.js'
+export { activityFromHelius, heliusHistory, type HeliusHistoryOptions } from '../historyHelius.js'
+
+export interface GetHistoryOptions extends HistoryOptions, ShortcutOptions {}
+
+/** 查地址的交易历史，节点参数与 getBalances 相同 */
+export function getHistory(address: string, options: GetHistoryOptions = {}): Promise<HistoryPage> {
+  const { client, own } = resolve(options, ['limit', 'cursor', 'before', 'after', 'types', 'source', 'symbols', 'fetch', 'signal'])
+  return history(client, address, own)
+}

package/src/subpaths/lp.ts

@@ -25,6 +25,7 @@ export {
   type SolanaLpClmmPosition,
   type SolanaLpPosition,
   type SolanaLpProtocol,
+  type SolanaLpReward,
   type SolanaLpToken,
   type SolanaPriceSource,
 } from '../lp.js'
@@ -38,15 +39,18 @@ export {
   getMaxAmounts,
   getMinAmounts,
   getMintAmounts,
+  getRewardGrowthInside,
   nearestUsableTick,
   orcaSqrtPriceAtTick,
   priceToTick,
   raydiumSqrtPriceAtTick,
+  rewardGrowthGlobal,
   sqrtPriceAtTick,
   sqrtPriceToPrice,
   tickAtSqrtPrice,
   tickToPrice,
   type ClmmProgram,
+  type RewardEmission,
   type TickFeeData,
 } from '../lpMath.js'
 
@@ -66,6 +70,6 @@ export interface GetLpPositionsOptions extends LpPositionsOptions, ShortcutOptio
  */
 export function getLpPositions(owner: string, options: GetLpPositionsOptions = {}): Promise<SolanaLpPosition[]> {
   // fetch 同时给节点请求（客户端配置）和查价用，与其他快捷函数一致
-  const { client, own } = resolve(options, ['protocols', 'mints', 'pools', 'includeClosed', 'prices', 'onPriceError', 'signal'])
+  const { client, own } = resolve(options, ['protocols', 'mints', 'pools', 'includeClosed', 'rewards', 'now', 'prices', 'onPriceError', 'signal'])
   return lpPositions(client, owner, { ...own, ...(options.fetch ? { fetch: options.fetch } : {}) })
 }

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/reclaim.ts

@@ -0,0 +1,57 @@
+/**
+ * 账户回收（子路径 `@w3lib/solana-batch-call/reclaim`）：扫描钱包里关闭后能退回租金（SOL）的账户并批量关闭：空的代币账户、垃圾币（销毁后关闭）、
+ * Wrapped SOL（解包）、已清空的 Orca Whirlpool / Raydium CLMM 仓位。给出每项和合计能拿回多少 lamports，发送前用 /simulate 模拟。
+ * 不放在主入口，不用时打包不会带上这部分代码；发送的代码按需加载。
+ *
+ * ```ts
+ * import { getReclaimable, reclaim } from '@w3lib/solana-batch-call/reclaim'
+ *
+ * const r = await getReclaimable(owner, { provider: 'https://my-rpc…' })
+ * r.totalLamports                                          // 全部能拿回的 lamports
+ * const { simulation, results } = await reclaim(client, key, r.items.filter((i) => i.selected))
+ * ```
+ */
+import { reclaimable, type Reclaimable, type ReclaimQuery } from '../reclaim.js'
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+
+export {
+  buildReclaim,
+  reclaim,
+  reclaimable,
+  simulateReclaim,
+  type BuildReclaimOptions,
+  type JunkContext,
+  type ReclaimBlocker,
+  type ReclaimCall,
+  type ReclaimCallResult,
+  type ReclaimItem,
+  type ReclaimKind,
+  type ReclaimOptions,
+  type ReclaimPlan,
+  type ReclaimQuery,
+  type ReclaimResult,
+  type ReclaimSimulation,
+  type ReclaimSimulationOptions,
+  type Reclaimable,
+} from '../reclaim.js'
+export type { PlanSimulation } from '../batchPlan.js'
+export { burnChecked, closeAccount, harvestWithheldTokensToMint } from '../write/instructions.js'
+
+export interface GetReclaimableOptions extends ReclaimQuery, ShortcutOptions {}
+
+/**
+ * 扫描钱包里能回收租金的账户，节点参数与 getBalances 相同。默认列出全部代币账户（需要支持 getTokenAccountsByOwner 的节点），
+ * 免费公共节点传 `mints` 只看指定代币的 ATA。
+ *
+ * ```ts
+ * const r = await getReclaimable(owner, { provider: 'https://my-rpc…' })
+ * // { totalLamports: '45862080', selectedLamports: '41302080',
+ * //   items: [{ kind: 'empty-token', account, mint, lamports: '2039280', selected: true, reasons: ['empty'] },
+ * //           { kind: 'junk-token', symbol: 'claim-rewards.xyz', lamports: '2039280', selected: true, reasons: ['no-price', 'spam-name'] }, …],
+ * //   blocked: [{ kind: 'empty-token', blocker: 'frozen', … }] }
+ * ```
+ */
+export function getReclaimable(owner: string, options: GetReclaimableOptions = {}): Promise<Reclaimable> {
+  const { client, own } = resolve(options, ['mints', 'junk', 'positions', 'prices', 'maxJunkUsd', 'risk', 'isJunk', 'signal'])
+  return reclaimable(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/simulate.ts

@@ -0,0 +1,37 @@
+/**
+ * 交易模拟（子路径 `@w3lib/solana-batch-call/simulate`）：不签名、不发送，在主网模拟一笔交易，给出余额变化、授权变化（delegate / SetAuthority / 关闭账户）、
+ * 指令说明、程序错误、手续费和警告。输入可以是 base64 的交易，也可以直接是本库构建器的输出。不放在主入口，不用时打包不会带上这部分代码；价格、风险检查按需加载。
+ *
+ * ```ts
+ * import { buildSwap } from '@w3lib/solana-batch-call/swap'
+ * import { getSimulation } from '@w3lib/solana-batch-call/simulate'
+ *
+ * const plan = await getSwapQuote(owner, { tokenIn: NATIVE_MINT, tokenOut: USDC, amountInFormatted: '0.5' })
+ * const sim = await getSimulation(plan)            // 或 getSimulation(base64Tx, { owner })
+ * if (!sim.success || sim.warnings.some((w) => w.severity === 'danger')) throw new Error(sim.error ?? sim.warnings[0].message)
+ * ```
+ */
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+import { simulate, type SimulateInput, type SimulateOptions, type SimulationResult } from '../simulate.js'
+
+export {
+  failureText,
+  simulate,
+  type ApprovalChange,
+  type ApprovalChangeKind,
+  type SimulateInput,
+  type SimulateOptions,
+  type SimulatedBalanceChange,
+  type SimulationResult,
+  type SimulationWarning,
+  type WarningSeverity,
+} from '../simulate.js'
+export { decodeInstruction, type DecodedInstruction } from '../decode.js'
+
+export interface GetSimulationOptions extends SimulateOptions, ShortcutOptions {}
+
+/** 模拟一笔交易，节点参数与 getBalances 相同 */
+export function getSimulation(input: SimulateInput, options: GetSimulationOptions = {}): Promise<SimulationResult> {
+  const { client, own } = resolve(options, ['owner', 'signers', 'watch', 'step', 'prices', 'risk', 'fetch', 'signal'])
+  return simulate(client, input, own)
+}

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 }
+}