@w3lib/solana-batch-call 0.5.0 → 0.6.0

package/src/lp.ts

@@ -5,7 +5,19 @@ import { decodeAddress, encodeAddress, findProgramAddress, isAddress } from './a
 import type { RequestOptions, SolanaClient } from './client.js'
 import { formatUnits, parseMint, parseTokenAccount, type AccountInfo } from './layout.js'
 import { AllNodesFailedError, HttpError, RpcError } from './rpc.js'
-import { getAmountsForLiquidity, getFeeGrowthInside, getFeesOwed, orcaSqrtPriceAtTick, raydiumSqrtPriceAtTick, sqrtPriceToPrice, tickToPrice, type TickFeeData } from './lpMath.js'
+import {
+  getAmountsForLiquidity,
+  getFeeGrowthInside,
+  getFeesOwed,
+  getRewardGrowthInside,
+  orcaSqrtPriceAtTick,
+  raydiumSqrtPriceAtTick,
+  rewardGrowthGlobal,
+  sqrtPriceToPrice,
+  tickToPrice,
+  type RewardEmission,
+  type TickFeeData,
+} from './lpMath.js'
 import { defillamaPrices, type SolanaPriceSource } from './price.js'
 
 export const RAYDIUM_CLMM_PROGRAM_ID = 'CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK'
@@ -97,6 +109,24 @@ export interface SolanaLpClmmPosition extends SolanaLpPositionBase {
   fees1Formatted: string | null
   /** 开启 prices 时：未领取手续费的美元价值（手续费为 null 或缺价格时为 null） */
   feesUsd?: number | null
+  /** 开启 rewards 时：未领取的挖矿奖励（池子里已初始化的每个奖励一项，数量为 0 的也在） */
+  rewards?: SolanaLpReward[]
+  /** 开启 rewards 和 prices 时：未领取挖矿奖励的美元价值（有数量的奖励缺价格或读不到时为 null） */
+  rewardsUsd?: number | null
+}
+
+/** 集中流动性仓位未领取的挖矿奖励（Raydium CLMM reward_infos / Orca Whirlpool reward_infos） */
+export interface SolanaLpReward {
+  /** 奖励在池子里的位置（0~2） */
+  index: number
+  mint: string
+  symbol: string | null
+  decimals: number | null
+  /** 未领取的数量（最小单位）：已记账的 + 按池子最新状态结算的新增；读不到两端的 tick 数据时为 null */
+  amount: string | null
+  formatted: string | null
+  /** 开启 prices 时：美元价值（没有价格时为 null） */
+  usd?: number | null
 }
 
 export type SolanaLpPosition = SolanaLpAmmPosition | SolanaLpClmmPosition
@@ -116,6 +146,13 @@ export interface LpPositionsOptions extends RequestOptions {
   pools?: readonly string[]
   /** 返回已清空的仓位（流动性为 0、手续费也领完，NFT 还在）。默认 false */
   includeClosed?: boolean
+  /**
+   * 集中流动性仓位同时算未领取的挖矿奖励（Raydium CLMM 农场奖励、Orca 的奖励 slot），放在 rewards 字段，照搬程序的结算：
+   * 池子的奖励增长按时间摊给当前流动性，再按仓位区间内的增长计算。默认 false。有奖励没领的仓位不算“已清空”
+   */
+  rewards?: boolean
+  /** rewards 结算到哪个时刻（unix 秒），默认当前时间；链上用的是区块时间，差几秒影响很小 */
+  now?: number
   /** 查美元价值：true 用 DefiLlama，也可以传自己的 SolanaPriceSource（如 /price 的 combinePrices([defillamaPrices(), onchainPrices()])）。默认不查 */
   prices?: boolean | SolanaPriceSource
   /**
@@ -160,6 +197,7 @@ export class Bytes {
   }
 }
 
+const ZERO_ADDRESS = '11111111111111111111111111111111'
 const RAYDIUM_POSITION_SIZE = 281
 const ORCA_POSITION_SIZE = 216
 /** 池子账户至少要读到的长度（Raydium PoolState 实际 1544 字节，Orca Whirlpool 653 字节） */
@@ -172,7 +210,7 @@ const RAYDIUM_TICK_SIZE = 168
 const ORCA_TICK_ARRAY_SIZE = 88
 const ORCA_TICK_SIZE = 113
 
-interface ClmmPositionState {
+export interface ClmmPositionState {
   protocol: 'raydium-clmm' | 'orca-whirlpool'
   address: string
   mint: string
@@ -184,8 +222,12 @@ interface ClmmPositionState {
   growthLast1: bigint
   owed0: bigint
   owed1: bigint
+  /** 三个挖矿奖励：上次记录的区间内增长、已记账未领取的数量 */
+  rewards: Array<{ growthLast: bigint; owed: bigint }>
 }
 
+const positionRewards = (b: Bytes, offset: number) => [0, 1, 2].map((i) => ({ growthLast: b.u128(offset + i * 24), owed: b.u64(offset + i * 24 + 16) }))
+
 function raydiumPosition(address: string, b: Bytes): ClmmPositionState {
   return {
     protocol: 'raydium-clmm',
@@ -199,6 +241,7 @@ function raydiumPosition(address: string, b: Bytes): ClmmPositionState {
     growthLast1: b.u128(113),
     owed0: b.u64(129),
     owed1: b.u64(137),
+    rewards: positionRewards(b, 145),
   }
 }
 
@@ -215,9 +258,21 @@ function orcaPosition(address: string, b: Bytes): ClmmPositionState {
     owed0: b.u64(112),
     growthLast1: b.u128(120),
     owed1: b.u64(136),
+    rewards: positionRewards(b, 144),
   }
 }
 
+/** 按程序和账户大小解析仓位账户（Raydium PersonalPositionState 281 字节、Orca Position 216 字节）；不是仓位账户时为 null */
+export function parseClmmPosition(protocol: 'raydium-clmm' | 'orca-whirlpool', address: string, account: AccountInfo): ClmmPositionState | null {
+  if (protocol === 'raydium-clmm' && account.owner === RAYDIUM_CLMM_PROGRAM_ID && account.data.length === RAYDIUM_POSITION_SIZE) {
+    return raydiumPosition(address, new Bytes(account.data))
+  }
+  if (protocol === 'orca-whirlpool' && account.owner === ORCA_WHIRLPOOL_PROGRAM_ID && account.data.length === ORCA_POSITION_SIZE) {
+    return orcaPosition(address, new Bytes(account.data))
+  }
+  return null
+}
+
 interface ClmmPoolState {
   mint0: string
   mint1: string
@@ -231,6 +286,41 @@ interface ClmmPoolState {
   /** Orca：池子里的费率；Raydium：在 AmmConfig 里，ammConfig 为它的地址 */
   fee: number | null
   ammConfig: string | null
+  /** 当前区间内的流动性 */
+  liquidity: bigint
+  /** 已初始化的挖矿奖励（index 是在池子里的位置） */
+  rewards: Array<{ index: number; mint: string; emission: RewardEmission }>
+}
+
+const U64_MAX_VALUE = (1n << 64n) - 1n
+
+/** Raydium reward_infos（每个 169 字节，从 397 开始）：open_time +1、end_time +9、last_update_time +17、emissions_per_second_x64 +25、mint +57、growth_global +153 */
+function raydiumRewards(b: Bytes): ClmmPoolState['rewards'] {
+  if (b.data.length < 397 + 3 * 169) {
+    return []
+  }
+  return [0, 1, 2].flatMap((index) => {
+    const o = 397 + index * 169
+    const mint = b.key(o + 57)
+    return mint === ZERO_ADDRESS
+      ? []
+      : [{ index, mint, emission: { initialized: true, openTime: b.u64(o + 1), endTime: b.u64(o + 9), lastUpdated: b.u64(o + 17), emissionsPerSecondX64: b.u128(o + 25), growthGlobalX64: b.u128(o + 153) } }]
+  })
+}
+
+/** Orca reward_last_updated_timestamp（261）和 reward_infos（每个 128 字节，从 269 开始）：mint +0、emissions_per_second_x64 +96、growth_global +112 */
+function orcaRewards(b: Bytes): ClmmPoolState['rewards'] {
+  if (b.data.length < 269 + 3 * 128) {
+    return []
+  }
+  const lastUpdated = b.u64(261)
+  return [0, 1, 2].flatMap((index) => {
+    const o = 269 + index * 128
+    const mint = b.key(o)
+    return mint === ZERO_ADDRESS
+      ? []
+      : [{ index, mint, emission: { initialized: true, openTime: 0n, endTime: U64_MAX_VALUE, lastUpdated, emissionsPerSecondX64: b.u128(o + 96), growthGlobalX64: b.u128(o + 112) } }]
+  })
 }
 
 function raydiumPool(b: Bytes): ClmmPoolState {
@@ -246,6 +336,8 @@ function raydiumPool(b: Bytes): ClmmPoolState {
     global0: b.u128(277),
     global1: b.u128(293),
     fee: null,
+    liquidity: b.u128(237),
+    rewards: raydiumRewards(b),
   }
 }
 
@@ -262,6 +354,8 @@ function orcaPool(b: Bytes): ClmmPoolState {
     global1: b.u128(245),
     decimals0: null,
     decimals1: null,
+    liquidity: b.u128(49),
+    rewards: orcaRewards(b),
   }
 }
 
@@ -346,7 +440,9 @@ export function orcaTickArray(pool: string, tick: number, spacing: number): { ad
   return { address: findProgramAddress([utf8('tick_array'), decodeAddress(pool), utf8(String(start))], ORCA_WHIRLPOOL_PROGRAM_ID), start }
 }
 
-function raydiumTick(account: AccountInfo, start: number, tick: number, spacing: number): TickFeeData | null {
+const rewardOutside = (b: Bytes, offset: number) => [b.u128(offset), b.u128(offset + 16), b.u128(offset + 32)]
+
+export function raydiumTick(account: AccountInfo, start: number, tick: number, spacing: number): TickFeeData | null {
   raydiumDiscriminator ??= discriminator('TickArrayState')
   const offset = 44 + ((tick - start) / spacing) * RAYDIUM_TICK_SIZE
   // 先认判别符、查长度再读字段（PDA 上可能是别的账户，如被转过 SOL 的系统账户）
@@ -358,7 +454,7 @@ function raydiumTick(account: AccountInfo, start: number, tick: number, spacing:
     return null
   }
   // Raydium 不区分是否初始化：没用过的 tick 各项都是 0，按程序的公式算出来就是对的
-  return { initialized: true, feeGrowthOutside0: b.u128(offset + 36), feeGrowthOutside1: b.u128(offset + 52) }
+  return { initialized: true, feeGrowthOutside0: b.u128(offset + 36), feeGrowthOutside1: b.u128(offset + 52), rewardGrowthsOutside: rewardOutside(b, offset + 68) }
 }
 
 /** Anchor 账户判别符：sha256("account:<名称>") 的前 8 字节 */
@@ -367,7 +463,7 @@ let orcaDiscriminators: { fixed: Uint8Array; dynamic: Uint8Array } | undefined
 let raydiumDiscriminator: Uint8Array | undefined
 const startsWith = (data: Uint8Array, prefix: Uint8Array) => data.length >= prefix.length && prefix.every((byte, i) => data[i] === byte)
 
-function orcaTick(account: AccountInfo, start: number, tick: number, spacing: number): TickFeeData | null {
+export function orcaTick(account: AccountInfo, start: number, tick: number, spacing: number): TickFeeData | null {
   orcaDiscriminators ??= { fixed: discriminator('TickArray'), dynamic: discriminator('DynamicTickArray') }
   if (account.data.length < 60) {
     return null // 两种格式的头部（判别符 + start + …）都放不下
@@ -380,7 +476,7 @@ function orcaTick(account: AccountInfo, start: number, tick: number, spacing: nu
     if (b.i32(8) !== start || offset + ORCA_TICK_SIZE > account.data.length) {
       return null
     }
-    return { initialized: b.u8(offset) === 1, feeGrowthOutside0: b.u128(offset + 33), feeGrowthOutside1: b.u128(offset + 49) }
+    return { initialized: b.u8(offset) === 1, feeGrowthOutside0: b.u128(offset + 33), feeGrowthOutside1: b.u128(offset + 49), rewardGrowthsOutside: rewardOutside(b, offset + 65) }
   }
   if (startsWith(account.data, orcaDiscriminators.dynamic)) {
     // 可变大小：start i32 | whirlpool | tick_bitmap u128 | ticks（未初始化 1 字节 0；初始化 1 字节 1 + 112 字节数据）
@@ -403,7 +499,7 @@ function orcaTick(account: AccountInfo, start: number, tick: number, spacing: nu
     if (offset + 113 > account.data.length) {
       return null
     }
-    return { initialized: true, feeGrowthOutside0: b.u128(offset + 33), feeGrowthOutside1: b.u128(offset + 49) }
+    return { initialized: true, feeGrowthOutside0: b.u128(offset + 33), feeGrowthOutside1: b.u128(offset + 49), rewardGrowthsOutside: rewardOutside(b, offset + 65) }
   }
   return null
 }
@@ -426,6 +522,8 @@ interface RawClmm {
   amount1: bigint
   fees0: bigint | null
   fees1: bigint | null
+  /** rewards 选项开启时：每个已初始化的奖励的未领取数量（读不到 tick 时为 null） */
+  rewards?: Array<{ index: number; mint: string; amount: bigint | null }>
 }
 
 interface RawAmm {
@@ -498,11 +596,9 @@ export async function lpPositions(client: SolanaClient, owner: string, options:
     if (!account) {
       return
     }
-    const program = SOLANA_LP_PROTOCOLS[c.protocol].programId
-    if (c.protocol === 'raydium-clmm' && account.owner === program && account.data.length === RAYDIUM_POSITION_SIZE) {
-      positions.push(raydiumPosition(c.address, new Bytes(account.data)))
-    } else if (c.protocol === 'orca-whirlpool' && account.owner === program && account.data.length === ORCA_POSITION_SIZE) {
-      positions.push(orcaPosition(c.address, new Bytes(account.data)))
+    const parsed = parseClmmPosition(c.protocol, c.address, account)
+    if (parsed) {
+      positions.push(parsed)
     }
   })
   // LP mint 的权限是 AMM v4 / CPMM 的固定权限地址时才去找池子
@@ -605,10 +701,32 @@ export async function lpPositions(client: SolanaClient, owner: string, options:
         fees1 = null
       }
     }
-    if (!options.includeClosed && position.liquidity === 0n && fees0 === 0n && fees1 === 0n) {
+    // 未领取的挖矿奖励：没有流动性时只有已记账的；有流动性时先把池子的奖励增长结算到 now，再按区间内的增长算新增
+    let rewards: RawClmm['rewards']
+    if (options.rewards) {
+      const now = BigInt(Math.floor(options.now ?? Date.now() / 1000))
+      const ticks = (() => {
+        if (!arrays) return null
+        const read = position.protocol === 'raydium-clmm' ? raydiumTick : orcaTick
+        const lowerAccount = byAddress.get(arrays.lower.address)
+        const upperAccount = byAddress.get(arrays.upper.address)
+        const lower = lowerAccount ? read(lowerAccount, arrays.lower.start, position.tickLower, pool.tickSpacing) : null
+        const upper = upperAccount ? read(upperAccount, arrays.upper.start, position.tickUpper, pool.tickSpacing) : null
+        return lower && upper ? { lower, upper } : null
+      })()
+      rewards = pool.rewards.map(({ index, mint, emission }) => {
+        const state = position.rewards[index] as { growthLast: bigint; owed: bigint }
+        if (!arrays) return { index, mint, amount: state.owed }
+        if (!ticks) return { index, mint, amount: null }
+        const global = rewardGrowthGlobal(pool.liquidity, emission, now)
+        const inside = getRewardGrowthInside(pool.tick, position.tickLower, ticks.lower, position.tickUpper, ticks.upper, index, global)
+        return { index, mint, amount: getFeesOwed(state.owed, position.liquidity, inside, state.growthLast) }
+      })
+    }
+    if (!options.includeClosed && position.liquidity === 0n && fees0 === 0n && fees1 === 0n && !rewards?.some((x) => x.amount !== 0n)) {
       continue
     }
-    raw.push({ type: 'clmm', position, pool: { ...pool, fee: pool.fee ?? (pool.ammConfig ? (feeRates.get(pool.ammConfig) ?? null) : null) }, amount0, amount1, fees0, fees1 })
+    raw.push({ type: 'clmm', position, pool: { ...pool, fee: pool.fee ?? (pool.ammConfig ? (feeRates.get(pool.ammConfig) ?? null) : null) }, amount0, amount1, fees0, fees1, rewards })
   }
   for (const pool of ammHeld) {
     const balance = held.get(pool.lpMint)?.amount ?? 0n
@@ -706,7 +824,7 @@ async function findAmmPool(client: SolanaClient, protocol: 'raydium-amm' | 'rayd
 
 async function finalize(client: SolanaClient, raw: readonly (RawClmm | RawAmm)[], options: LpPositionsOptions): Promise<SolanaLpPosition[]> {
   const { signal } = options
-  const mints = [...new Set(raw.flatMap((r) => [r.pool.mint0, r.pool.mint1]))]
+  const mints = [...new Set(raw.flatMap((r) => [r.pool.mint0, r.pool.mint1, ...(r.type === 'clmm' ? (r.rewards ?? []).map((x) => x.mint) : [])]))]
   const priceSource = options.prices === true ? defillamaPrices() : options.prices || null
   const fetchFn = options.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args))
   // 价格源出错（服务不可用、被拦截、同步抛错等）时照样返回仓位，只是不带价格；取消查询时照常 reject
@@ -784,6 +902,11 @@ async function finalize(client: SolanaClient, raw: readonly (RawClmm | RawAmm)[]
     const d1 = token1.decimals
     const fees0Formatted = r.fees0 === null ? null : fmt(r.fees0, token0)
     const fees1Formatted = r.fees1 === null ? null : fmt(r.fees1, token1)
+    const rewards = r.rewards?.map((x): SolanaLpReward => {
+      const t = token(x.mint, null)
+      const formatted = x.amount === null ? null : fmt(x.amount, t)
+      return { index: x.index, mint: x.mint, symbol: t.symbol, decimals: t.decimals, amount: x.amount === null ? null : x.amount.toString(), formatted, ...(priceSource ? { usd: x.amount === 0n ? 0 : usd(t, formatted) } : {}) }
+    })
     return {
       ...base,
       type: 'clmm',
@@ -804,6 +927,8 @@ async function finalize(client: SolanaClient, raw: readonly (RawClmm | RawAmm)[]
       fees0Formatted,
       fees1Formatted,
       ...(priceSource ? { feesUsd: r.fees0 === null || r.fees1 === null ? null : sum(usd(token0, fees0Formatted), usd(token1, fees1Formatted), r.fees0, r.fees1) } : {}),
+      ...(rewards ? { rewards } : {}),
+      ...(rewards && priceSource ? { rewardsUsd: rewards.some((x) => x.usd === null || x.usd === undefined) ? null : rewards.reduce((acc, x) => acc + (x.usd ?? 0), 0) } : {}),
     }
   })
   if (priceSource) {

package/src/lpMath.ts

@@ -153,6 +153,8 @@ export interface TickFeeData {
   initialized: boolean
   feeGrowthOutside0: bigint
   feeGrowthOutside1: bigint
+  /** 三个挖矿奖励的 tick 外增长（读 tick 时带上；只算手续费时可以不给） */
+  rewardGrowthsOutside?: readonly bigint[]
 }
 
 const wrap = (x: bigint) => ((x % (1n << 128n)) + (1n << 128n)) % (1n << 128n)
@@ -192,6 +194,42 @@ export function getFeesOwed(owed: bigint, liquidity: bigint, growthInside: bigin
   return owed + (delta > U64_MAX ? 0n : delta)
 }
 
+/** 池子里一个挖矿奖励的状态（两个程序的 reward_infos 里的同名字段） */
+export interface RewardEmission {
+  /** 已初始化：奖励的 mint 不是默认地址 */
+  initialized: boolean
+  emissionsPerSecondX64: bigint
+  growthGlobalX64: bigint
+  /** 上次更新的时间（秒）。Raydium 每个奖励自己记；Orca 是池子的 reward_last_updated_timestamp（三个奖励相同） */
+  lastUpdated: bigint
+  /** 开始 / 结束时间（秒）：Raydium 的 open_time / end_time；Orca 没有，传 0n / 2^64 − 1 */
+  openTime: bigint
+  endTime: bigint
+}
+
+/**
+ * 池子在 now 时刻的奖励全局增长：程序每次操作池子（交易、增减流动性、领取）前先把排放按时间摊给当前的流动性，
+ * Q64.64：growth += Δt · emissions_per_second / liquidity（向下取整，u128 回绕）。
+ * Raydium：now ≤ open_time 不动，Δt 到 end_time 为止；Orca：池子流动性为 0 或 Δt 为 0 不动
+ */
+export function rewardGrowthGlobal(liquidity: bigint, reward: RewardEmission, now: bigint): bigint {
+  if (!reward.initialized || liquidity === 0n || now <= reward.openTime) {
+    return reward.growthGlobalX64
+  }
+  const latest = now < reward.endTime ? now : reward.endTime
+  const delta = latest > reward.lastUpdated ? latest - reward.lastUpdated : 0n
+  return wrap(reward.growthGlobalX64 + (delta * reward.emissionsPerSecondX64) / liquidity)
+}
+
+/** 区间内某个奖励的增长（u128 回绕），tick 未初始化的处理同 getFeeGrowthInside */
+export function getRewardGrowthInside(tick: number, tickLower: number, lower: TickFeeData, tickUpper: number, upper: TickFeeData, index: number, global: bigint): bigint {
+  const lowerOutside = lower.rewardGrowthsOutside?.[index] ?? 0n
+  const upperOutside = upper.rewardGrowthsOutside?.[index] ?? 0n
+  const below = !lower.initialized ? global : tick < tickLower ? wrap(global - lowerOutside) : lowerOutside
+  const above = !upper.initialized ? 0n : tick < tickUpper ? upperOutside : wrap(global - upperOutside)
+  return wrap(global - below - above)
+}
+
 /** Q64.64 sqrt 价格 → token1 / token0 的价格（按精度换算，浮点数，只用于展示） */
 export function sqrtPriceToPrice(sqrtPrice: bigint, decimals0: number, decimals1: number): number {
   // 先取高位再转浮点，避免 2^128 级别的整数转换丢精度后再平方

package/src/programs.ts

@@ -0,0 +1,216 @@
+/**
+ * 常见程序的名字、指令名（Anchor 程序按 sha256("global:<name>") 的前 8 字节识别）和自定义错误码，
+ * 给 /simulate 和 /history 说明交易在做什么。只收录认得准的，其他程序只显示地址
+ */
+import { sha256 } from '@noble/hashes/sha2.js'
+
+import {
+  ASSOCIATED_TOKEN_PROGRAM_ID,
+  SYSTEM_PROGRAM_ID,
+  TOKEN_2022_PROGRAM_ID,
+  TOKEN_PROGRAM_ID,
+} from './constants.js'
+
+// 与 lp.ts 里的同名常量相同；这里不 import 它，避免 /simulate、/history 把整个 LP 模块打进来
+const RAYDIUM_CLMM_PROGRAM_ID = 'CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK'
+const ORCA_WHIRLPOOL_PROGRAM_ID = 'whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc'
+const RAYDIUM_AMM_PROGRAM_ID = '675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8'
+const RAYDIUM_CPMM_PROGRAM_ID = 'CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C'
+
+export const COMPUTE_BUDGET = 'ComputeBudget111111111111111111111111111111'
+export const MEMO_V2 = 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr'
+export const MEMO_V1 = 'Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo'
+export const BPF_LOADER_UPGRADEABLE = 'BPFLoaderUpgradeab1e11111111111111111111111'
+
+/** 指令的大类：交易的类型由它们和余额变化一起决定 */
+export type IxType = 'transfer' | 'swap' | 'approve' | 'liquidity' | 'mint' | 'burn' | 'close' | 'setup' | 'budget' | 'memo' | 'contract' | 'unknown'
+
+export interface ProgramInfo {
+  name: string
+  /** 内置程序（系统、代币、ATA、计算预算、备忘录等）：不算“不认识的程序” */
+  builtin?: boolean
+  /** 协议名（DEX / 借贷等），内置程序没有 */
+  protocol?: string
+}
+
+const p = (name: string, protocol = name): ProgramInfo => ({ name, protocol })
+const b = (name: string): ProgramInfo => ({ name, builtin: true })
+
+export const PROGRAMS: Readonly<Record<string, ProgramInfo>> = {
+  [SYSTEM_PROGRAM_ID]: b('System Program'),
+  [TOKEN_PROGRAM_ID]: b('SPL Token'),
+  [TOKEN_2022_PROGRAM_ID]: b('Token-2022'),
+  [ASSOCIATED_TOKEN_PROGRAM_ID]: b('Associated Token Account'),
+  [COMPUTE_BUDGET]: b('Compute Budget'),
+  [MEMO_V2]: b('Memo'),
+  [MEMO_V1]: b('Memo'),
+  [BPF_LOADER_UPGRADEABLE]: b('BPF Loader Upgradeable'),
+  AddressLookupTab1e1111111111111111111111111: b('Address Lookup Table'),
+  Stake11111111111111111111111111111111111111: b('Stake Program'),
+  Vote111111111111111111111111111111111111111: b('Vote Program'),
+  Ed25519SigVerify111111111111111111111111111: b('Ed25519 Program'),
+  KeccakSecp256k11111111111111111111111111111: b('Secp256k1 Program'),
+  metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s: b('Metaplex Token Metadata'),
+  JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4: p('Jupiter Aggregator v6', 'Jupiter'),
+  JUP4Fb2cqiRUcaTHdrPC8h2gNsA2ETXiPDD33WcGuJB: p('Jupiter Aggregator v4', 'Jupiter'),
+  DCA265Vj8a9CEuX1eb1LWRnDT7uK6q1xMipnNyatn23M: p('Jupiter DCA', 'Jupiter'),
+  j1o2qRpjcyUwEvwtcfhEQefh773ZgjxcVRry7LDqg5X: p('Jupiter Limit Order', 'Jupiter'),
+  jupoNjAxXgZ4rjzxzPMP4oxduvQsQtZzyknqvzYNrNu: p('Jupiter Limit Order v2', 'Jupiter'),
+  PERPHjGBqRHArX4DySjwM6UJHiR3sWAatqfdBS2qQJu: p('Jupiter Perpetuals', 'Jupiter'),
+  [RAYDIUM_AMM_PROGRAM_ID]: p('Raydium AMM v4', 'Raydium'),
+  [RAYDIUM_CLMM_PROGRAM_ID]: p('Raydium CLMM', 'Raydium'),
+  [RAYDIUM_CPMM_PROGRAM_ID]: p('Raydium CPMM', 'Raydium'),
+  routeUGWgWzqBWFcrCfv8tritsqukccJPu3q5GPP3xS: p('Raydium Route', 'Raydium'),
+  [ORCA_WHIRLPOOL_PROGRAM_ID]: p('Orca Whirlpool', 'Orca'),
+  '9W959DqEETiGZocYWCQPaJ6sBmUzgfxXfqGeTEdp3aQP': p('Orca v2', 'Orca'),
+  LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo: p('Meteora DLMM', 'Meteora'),
+  Eo7WjKq67rjJQSZxS6z3YkapzY3eMj6Xy8X5EQVn5UaB: p('Meteora Pools', 'Meteora'),
+  cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG: p('Meteora DAMM v2', 'Meteora'),
+  dbcij3LWUppWqq96dh6gJWwBifmcGfLSB5D4DuSMaqN: p('Meteora Dynamic Bonding Curve', 'Meteora'),
+  '6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P': p('Pump.fun', 'Pump.fun'),
+  pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA: p('PumpSwap', 'Pump.fun'),
+  PhoeNiXZ8ByJGLkxNfZRnkUfjvmuYqLR89jjFHGqdXY: p('Phoenix'),
+  srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX: p('OpenBook v1', 'OpenBook'),
+  opnb2LAfJYbRMAHHvqjCwQxanZn7ReEHp1k81EohpZb: p('OpenBook v2', 'OpenBook'),
+  LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj: p('Lifinity v2', 'Lifinity'),
+  MarBmsSgKXdrN1egZf5sqe1TMai9K1rChYNDJgjq7aD: p('Marinade'),
+  MFv2hWf31Z9kbCa1snEPYctwafyhdvnV7FZnsebVacA: p('marginfi v2', 'marginfi'),
+  KLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjD: p('Kamino Lending', 'Kamino'),
+  dRiftyHA39MWEi3m9aunc5MzRF1JYuBsbn6VPcn33UH: p('Drift v2', 'Drift'),
+  So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo: p('Solend'),
+  SQDS4ep65T869zMMBKyuUq6aD6EgTu8psMjkvj52pCf: p('Squads v4', 'Squads'),
+  wormDTUJ6AWPNvk59vGQbDvGJmqbDTdgWgAqcLBCgUb: p('Wormhole Token Bridge', 'Wormhole'),
+  CndyV3LdqHUfDLmE5naZjVN8rBZz4tqhdefbAnjHG3JR: p('Candy Machine v3', 'Metaplex'),
+  Guard1JwRhJkVH6XZhzoYxeBVQe872VH6QggF4BWmS9g: p('Candy Guard', 'Metaplex'),
+  CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d: p('Metaplex Core', 'Metaplex'),
+  TSWAPaqyCSx2KABk68Shruf4rp7CxcNi8hAsbdwmHbN: p('Tensor Swap', 'Tensor'),
+  M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K: p('Magic Eden v2', 'Magic Eden'),
+}
+
+/** 按指令名（snake_case）识别的 Anchor 程序：指令名 → 大类 */
+const JUPITER_METHODS: Record<string, IxType> = {
+  ...Object.fromEntries(['route', 'route_with_token_ledger', 'shared_accounts_route', 'shared_accounts_route_with_token_ledger', 'exact_out_route', 'shared_accounts_exact_out_route'].map((n) => [n, 'swap'])),
+  set_token_ledger: 'setup',
+}
+
+const ANCHOR: Record<string, Record<string, IxType>> = {
+  JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4: JUPITER_METHODS,
+  JUP4Fb2cqiRUcaTHdrPC8h2gNsA2ETXiPDD33WcGuJB: JUPITER_METHODS,
+  dbcij3LWUppWqq96dh6gJWwBifmcGfLSB5D4DuSMaqN: { swap: 'swap', swap2: 'swap' },
+  CndyV3LdqHUfDLmE5naZjVN8rBZz4tqhdefbAnjHG3JR: { mint: 'mint', mint_v2: 'mint' },
+  Guard1JwRhJkVH6XZhzoYxeBVQe872VH6QggF4BWmS9g: { mint: 'mint', mint_v2: 'mint' },
+  [ORCA_WHIRLPOOL_PROGRAM_ID]: {
+    ...Object.fromEntries(['swap', 'swap_v2', 'two_hop_swap', 'two_hop_swap_v2'].map((n) => [n, 'swap'])),
+    ...Object.fromEntries(
+      [
+        'increase_liquidity', 'increase_liquidity_v2', 'decrease_liquidity', 'decrease_liquidity_v2', 'open_position', 'open_position_with_metadata',
+        'open_position_with_token_extensions', 'close_position', 'close_position_with_token_extensions', 'collect_fees', 'collect_fees_v2', 'collect_reward',
+        'collect_reward_v2', 'open_bundled_position', 'close_bundled_position', 'increase_liquidity_by_token_amounts_v2',
+      ].map((n) => [n, 'liquidity']),
+    ),
+    initialize_tick_array: 'setup',
+    initialize_dynamic_tick_array: 'setup',
+  },
+  [RAYDIUM_CLMM_PROGRAM_ID]: {
+    ...Object.fromEntries(['swap', 'swap_v2', 'swap_router_base_in'].map((n) => [n, 'swap'])),
+    ...Object.fromEntries(
+      ['open_position', 'open_position_v2', 'open_position_with_token22_nft', 'increase_liquidity', 'increase_liquidity_v2', 'decrease_liquidity', 'decrease_liquidity_v2', 'close_position', 'collect_fund_fee'].map((n) => [n, 'liquidity']),
+    ),
+  },
+  [RAYDIUM_CPMM_PROGRAM_ID]: { swap_base_input: 'swap', swap_base_output: 'swap', deposit: 'liquidity', withdraw: 'liquidity' },
+  LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo: {
+    ...Object.fromEntries(['swap', 'swap_exact_out', 'swap_with_price_impact'].map((n) => [n, 'swap'])),
+    ...Object.fromEntries(
+      [
+        'add_liquidity', 'add_liquidity_by_weight', 'add_liquidity_by_strategy', 'add_liquidity_by_strategy_one_side', 'add_liquidity_one_side', 'remove_liquidity',
+        'remove_liquidity_by_range', 'remove_all_liquidity', 'claim_fee', 'claim_reward', 'close_position', 'initialize_position',
+      ].map((n) => [n, 'liquidity']),
+    ),
+  },
+  Eo7WjKq67rjJQSZxS6z3YkapzY3eMj6Xy8X5EQVn5UaB: {
+    swap: 'swap',
+    add_balance_liquidity: 'liquidity',
+    add_imbalance_liquidity: 'liquidity',
+    remove_balance_liquidity: 'liquidity',
+    remove_liquidity_single_side: 'liquidity',
+  },
+  cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG: {
+    swap: 'swap',
+    swap2: 'swap',
+    add_liquidity: 'liquidity',
+    remove_liquidity: 'liquidity',
+    remove_all_liquidity: 'liquidity',
+    claim_position_fee: 'liquidity',
+    create_position: 'liquidity',
+    close_position: 'liquidity',
+  },
+  '6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P': { buy: 'swap', sell: 'swap', create: 'mint', create_v2: 'mint' },
+  pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA: { buy: 'swap', sell: 'swap', deposit: 'liquidity', withdraw: 'liquidity', create_pool: 'liquidity' },
+}
+
+/** Raydium AMM v4：第一个字节是指令编号 */
+const AMM_V4: Record<number, [string, IxType]> = {
+  3: ['deposit', 'liquidity'],
+  4: ['withdraw', 'liquidity'],
+  9: ['swapBaseIn', 'swap'],
+  11: ['swapBaseOut', 'swap'],
+  16: ['swapBaseInV2', 'swap'],
+  17: ['swapBaseOutV2', 'swap'],
+}
+
+let discriminators: Map<string, Map<string, [string, IxType]>> | undefined
+
+const hex = (bytes: Uint8Array) => Array.from(bytes, (x) => x.toString(16).padStart(2, '0')).join('')
+
+/** 认得的程序指令：返回指令名和大类；不认识的指令（程序认得）返回 null */
+export function knownMethod(programId: string, data: Uint8Array): [method: string, type: IxType] | null {
+  if (programId === RAYDIUM_AMM_PROGRAM_ID) return AMM_V4[data[0] as number] ?? null
+  const methods = ANCHOR[programId]
+  if (!methods || data.length < 8) return null
+  if (!discriminators) {
+    discriminators = new Map(
+      Object.entries(ANCHOR).map(([program, list]) => [
+        program,
+        new Map(Object.entries(list).map(([name, type]) => [hex(sha256(new TextEncoder().encode(`global:${name}`)).slice(0, 8)), [name, type] as [string, IxType]])),
+      ]),
+    )
+  }
+  return discriminators.get(programId)?.get(hex(data.slice(0, 8))) ?? null
+}
+
+// ---------------------------------------------------------------------------
+// 自定义错误码
+// ---------------------------------------------------------------------------
+
+const list = (names: string): Record<number, string> => Object.fromEntries(names.split(',').map((n, i) => [i, n]))
+
+const SYSTEM_ERRORS = list('AccountAlreadyInUse,ResultWithNegativeLamports,InvalidProgramId,InvalidAccountDataLength,MaxSeedLengthExceeded,AddressWithSeedMismatch,NonceNoRecentBlockhashes,NonceBlockhashNotExpired,NonceUnexpectedBlockhashValue')
+const TOKEN_ERRORS = list(
+  'NotRentExempt,InsufficientFunds,InvalidMint,MintMismatch,OwnerMismatch,FixedSupply,AlreadyInUse,InvalidNumberOfProvidedSigners,InvalidNumberOfRequiredSigners,UninitializedState,NativeNotSupported,NonNativeHasBalance,InvalidInstruction,InvalidState,Overflow,AuthorityTypeNotSupported,MintCannotFreeze,AccountFrozen,MintDecimalsMismatch,NonNativeNotSupported',
+)
+const JUPITER_ERRORS: Record<number, string> = Object.fromEntries(
+  'EmptyRoute,SlippageToleranceExceeded,InvalidCalculation,MissingPlatformFeeAccount,InvalidSlippage,NotEnoughPercent,InvalidInputIndex,InvalidOutputIndex,NotEnoughAccountKeys,NonZeroMinimumOutAmountNotSupported,InvalidRoutePlan,InvalidReferralAuthority,LedgerTokenAccountDoesNotMatch,InvalidTokenLedger,IncorrectTokenProgramID,TokenProgramNotProvided,SwapNotSupported,ExactOutAmountNotMatched,SourceAndDestinationMintCannotBeTheSame'
+    .split(',')
+    .map((n, i) => [6000 + i, n]),
+)
+const RAYDIUM_AMM_ERRORS: Record<number, string> = { 22: 'InvalidStatus', 23: 'InvalidInstruction', 30: 'ExceededSlippage', 40: 'InsufficientFunds' }
+/** Anchor 框架自带的错误码（2000 起是账户约束） */
+const ANCHOR_ERRORS: Record<number, string> = {
+  100: 'InstructionMissing', 101: 'InstructionFallbackNotFound', 102: 'InstructionDidNotDeserialize', 2000: 'ConstraintMut', 2001: 'ConstraintHasOne',
+  2002: 'ConstraintSigner', 2003: 'ConstraintRaw', 2004: 'ConstraintOwner', 2006: 'ConstraintSeeds', 2012: 'ConstraintAddress', 2014: 'ConstraintTokenMint',
+  2015: 'ConstraintTokenOwner', 3001: 'AccountDiscriminatorNotFound', 3002: 'AccountDiscriminatorMismatch', 3003: 'AccountDidNotDeserialize',
+  3007: 'AccountOwnedByWrongProgram', 3010: 'AccountNotSigner', 3012: 'AccountNotInitialized',
+}
+
+const PROGRAM_ERRORS: Record<string, Record<number, string>> = {
+  [SYSTEM_PROGRAM_ID]: SYSTEM_ERRORS,
+  [TOKEN_PROGRAM_ID]: TOKEN_ERRORS,
+  [TOKEN_2022_PROGRAM_ID]: TOKEN_ERRORS,
+  JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4: JUPITER_ERRORS,
+  [RAYDIUM_AMM_PROGRAM_ID]: RAYDIUM_AMM_ERRORS,
+}
+
+/** 自定义错误码的名字：先看这个程序自己的表，再看 Anchor 框架的；认不出时返回 undefined */
+export function programErrorName(programId: string | undefined, code: number): string | undefined {
+  return (programId ? PROGRAM_ERRORS[programId]?.[code] : undefined) ?? ANCHOR_ERRORS[code]
+}