@w3lib/solana-batch-call 0.5.0 → 0.6.0

package/src/claim.ts

@@ -0,0 +1,323 @@
+/**
+ * 批量领取（子路径 `@w3lib/solana-batch-call/claim`）：Orca Whirlpool、Raydium CLMM 仓位的未领取手续费和挖矿奖励（Orca 的奖励 slot、Raydium 的农场奖励）。
+ * 先只读预览（每个仓位能领多少、美元价值），再把全部（或选中的）仓位的领取指令打包成交易，发送前用 /simulate 模拟。
+ * 领取的指令就是 /liquidity 的 collectFees（手续费 + 全部奖励，SOL 自动解包、缺少的代币账户自动创建），这里只做批量和打包
+ */
+import type { RequestOptions, SolanaClient } from './client.js'
+import { isAddress } from './address.js'
+import { buildCollectFees } from './liquidity/index.js'
+import type { SolanaLiquidityPlan } from './liquidity/types.js'
+import { lpPositions, type SolanaLpClmmPosition, type SolanaLpProtocol, type SolanaLpToken } from './lp.js'
+import { defillamaPrices, type SolanaPriceSource } from './price.js'
+import { simulatePlan, sendCalls, type PlanSimulation, type PlanSimulationOptions, type PlannedCall } from './batchPlan.js'
+import { formatUnits } from './layout.js'
+import type { SimulatedBalanceChange } from './simulate.js'
+import type { BatchCallOptions } from './write/batch.js'
+import { mapPool, type WriteResult } from './write/send.js'
+import type { SignerInput } from './write/signer.js'
+
+export type ClaimProtocol = Extract<SolanaLpProtocol, 'orca-whirlpool' | 'raydium-clmm'>
+
+/** 一项能领取的东西：手续费或挖矿奖励 */
+export interface ClaimableAmount {
+  mint: string
+  symbol: string | null
+  decimals: number | null
+  /** 数量（最小单位）；读不到两端的 tick 数据时为 null */
+  amount: string | null
+  formatted: string | null
+  /** 美元价值（查到价格时；没有价格为 null；数量为 0 时为 0） */
+  usd: number | null
+  /** 只在按代币汇总（`Claimable.tokens`）里：true 表示有仓位的数量读不到，`amount` 只是已读到部分的合计（偏低），`usd` 为 null */
+  incomplete?: true
+}
+
+export interface ClaimablePosition {
+  protocol: ClaimProtocol
+  protocolName: string
+  /** 仓位 NFT 的 mint 和仓位账户 */
+  positionMint: string
+  position: string
+  pool: string
+  token0: SolanaLpToken
+  token1: SolanaLpToken
+  liquidity: string
+  inRange: boolean
+  /** token0 / token1 的未领取手续费 */
+  fees: [ClaimableAmount, ClaimableAmount]
+  /** 池子里已初始化的挖矿奖励（Orca 的奖励 slot / Raydium 的 reward_infos），数量按程序的方式结算到当前时间 */
+  rewards: Array<ClaimableAmount & { index: number }>
+  feesUsd: number | null
+  rewardsUsd: number | null
+  /** 手续费 + 奖励的美元价值：有数量的项缺价格或读不到时为 null */
+  totalUsd: number | null
+}
+
+export interface Claimable {
+  owner: string
+  /** 有手续费或奖励可领的仓位（没有流动性也没有可领的不在内），按美元价值从大到小 */
+  positions: ClaimablePosition[]
+  /** 按代币汇总：手续费 + 奖励，所有仓位合计 */
+  tokens: ClaimableAmount[]
+  /** true：有仓位的数量读不到（tick 数据读不到），`tokens` 的数量和各项合计都可能偏低 */
+  incomplete: boolean
+  feesUsd: number | null
+  rewardsUsd: number | null
+  totalUsd: number | null
+  warnings: string[]
+}
+
+export interface ClaimQuery extends RequestOptions {
+  /** 只看这些仓位 NFT 的 mint（读 ATA，免费公共节点也能用）；不传时列出全部代币账户（getTokenAccountsByOwner，需要支持它的节点） */
+  mints?: readonly string[]
+  /** 协议，默认两个都查 */
+  protocols?: readonly ClaimProtocol[]
+  /** 价格：true（默认）用 DefiLlama；false 不查；也可以传自己的价格源（如 combinePrices([defillamaPrices(), onchainPrices()])） */
+  prices?: boolean | SolanaPriceSource
+  /** 奖励结算到哪个时刻（unix 秒），默认当前时间 */
+  now?: number
+  fetch?: typeof fetch
+}
+
+const MAX_ERROR = 200
+
+/**
+ * 预览能领取的手续费和挖矿奖励（只读取，不构建交易）：每个仓位的两种手续费、每个奖励的数量和美元价值，以及按代币汇总。
+ * 奖励照搬程序的结算：池子的奖励增长按时间摊给当前流动性，再按仓位区间内的增长计算
+ *
+ * ```ts
+ * const c = await claimable(client, owner)
+ * c.totalUsd                          // 全部能领的美元价值
+ * c.positions[0].rewards              // [{ index: 0, symbol: 'RAY', formatted: '0.042698', usd: 0.083 }]
+ * ```
+ */
+export async function claimable(client: SolanaClient, owner: string, query: ClaimQuery = {}): Promise<Claimable> {
+  if (!isAddress(owner)) {
+    throw new Error(`Invalid owner address: ${owner}`)
+  }
+  const { signal } = query
+  const protocols: ClaimProtocol[] = query.protocols ? [...query.protocols] : ['orca-whirlpool', 'raydium-clmm']
+  const list = (
+    await lpPositions(client, owner, { protocols, mints: query.mints, rewards: true, now: query.now, signal })
+  ).filter((p): p is SolanaLpClmmPosition => p.type === 'clmm')
+
+  const warnings: string[] = []
+  const mints = [...new Set(list.flatMap((p) => [p.token0.mint, p.token1.mint, ...(p.rewards ?? []).map((r) => r.mint)]))]
+  const source = query.prices === false ? null : query.prices && query.prices !== true ? query.prices : defillamaPrices()
+  let priceMap = new Map<string, number>()
+  if (source && mints.length) {
+    try {
+      priceMap = await source.prices({ mints, fetch: query.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args)), signal, client })
+    } catch (err) {
+      if (signal?.aborted) throw err
+      warnings.push(`Price lookup failed (${(err instanceof Error ? err.message : String(err)).slice(0, MAX_ERROR)}): usd values are null`)
+    }
+  }
+  const amountOf = (token: { mint: string; symbol: string | null; decimals: number | null }, amount: bigint | null): ClaimableAmount => {
+    const formatted = amount === null || token.decimals === null ? null : formatUnits(amount, token.decimals)
+    const price = priceMap.get(token.mint)
+    // 数量为 0 的不需要价格
+    const usd = amount === 0n ? 0 : formatted === null || price === undefined || !source ? null : Number(formatted) * price
+    return { mint: token.mint, symbol: token.symbol, decimals: token.decimals, amount: amount === null ? null : amount.toString(), formatted, usd }
+  }
+  const sum = (items: readonly ClaimableAmount[]) => (items.some((i) => i.usd === null) ? null : items.reduce((acc, i) => acc + (i.usd as number), 0))
+
+  const positions: ClaimablePosition[] = []
+  for (const p of list) {
+    const fees: [ClaimableAmount, ClaimableAmount] = [amountOf(p.token0, p.fees0 === null ? null : BigInt(p.fees0)), amountOf(p.token1, p.fees1 === null ? null : BigInt(p.fees1))]
+    const rewards = (p.rewards ?? []).map((r) => ({ ...amountOf(r, r.amount === null ? null : BigInt(r.amount)), index: r.index }))
+    const unknown = [...fees, ...rewards].some((x) => x.amount === null)
+    if (!unknown && [...fees, ...rewards].every((x) => x.amount === '0')) continue
+    positions.push({
+      protocol: p.protocol as ClaimProtocol,
+      protocolName: p.protocolName,
+      positionMint: p.positionMint,
+      position: p.position,
+      pool: p.pool,
+      token0: p.token0,
+      token1: p.token1,
+      liquidity: p.liquidity,
+      inRange: p.inRange,
+      fees,
+      rewards,
+      feesUsd: sum(fees),
+      rewardsUsd: sum(rewards),
+      totalUsd: sum([...fees, ...rewards]),
+    })
+  }
+  positions.sort((a, b) => (b.totalUsd ?? -1) - (a.totalUsd ?? -1))
+  if (positions.some((p) => [...p.fees, ...p.rewards].some((x) => x.amount === null))) {
+    warnings.push("Some positions' tick arrays could not be read: their amounts are null (they are still included)")
+  }
+
+  // 按代币汇总
+  const byMint = new Map<string, { token: { mint: string; symbol: string | null; decimals: number | null }; amount: bigint; unknown: boolean }>()
+  for (const item of positions.flatMap((p) => [...p.fees, ...p.rewards])) {
+    const entry = byMint.get(item.mint) ?? { token: item, amount: 0n, unknown: false }
+    entry.amount += BigInt(item.amount ?? 0)
+    entry.unknown ||= item.amount === null
+    byMint.set(item.mint, entry)
+  }
+  // 有读不到的数量时保留该代币（即使已读到的部分为 0），标记 incomplete，美元价值为 null
+  const tokens = [...byMint.values()]
+    .filter((e) => e.unknown || e.amount !== 0n)
+    .map((e): ClaimableAmount => (e.unknown ? { ...amountOf(e.token, e.amount), usd: null, incomplete: true } : amountOf(e.token, e.amount)))
+  const sumKnown = (items: ReadonlyArray<number | null>) => (items.some((x) => x === null) ? null : items.reduce<number>((acc, x) => acc + (x as number), 0))
+  return {
+    owner,
+    positions,
+    tokens,
+    incomplete: tokens.some((t) => t.incomplete),
+    feesUsd: sumKnown(positions.map((p) => p.feesUsd)),
+    rewardsUsd: sumKnown(positions.map((p) => p.rewardsUsd)),
+    totalUsd: sumKnown(positions.map((p) => p.totalUsd)),
+    warnings,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 构建、模拟、发送
+// ---------------------------------------------------------------------------
+
+/** 要领取的仓位：claimable 的结果，或只给协议 + 仓位 NFT 的 mint（getLpPositions 的结果也可以） */
+export type ClaimTarget = Pick<ClaimablePosition, 'protocol' | 'positionMint'> & { pool?: string }
+
+export interface BuildClaimOptions extends RequestOptions {
+  /** wSOL（池子的一边或奖励）原来没有账户时用完关闭、换回 SOL，默认 true（同 /liquidity） */
+  native?: boolean
+  /** 同时构建几个仓位（每个要读几次账户），默认 4 */
+  concurrency?: number
+}
+
+export interface ClaimCall extends PlannedCall {
+  protocol: ClaimProtocol
+  positionMint: string
+  /** /liquidity 的领取计划（预计的手续费、奖励的代币、步骤） */
+  plan: SolanaLiquidityPlan
+}
+
+export interface ClaimPlan {
+  owner: string
+  /** 每个仓位一个调用（创建缺少的代币账户 + 领取手续费 + 领取每个奖励，原子执行） */
+  calls: ClaimCall[]
+  /** 构建失败的仓位：仓位不在 owner 名下、不支持的代币（带转账手续费的 Token-2022 池子）等 */
+  failed: Array<{ position: ClaimTarget; error: string }>
+}
+
+/**
+ * 构建批量领取（只读取、不签名）：每个仓位一个调用，指令来自 /liquidity 的 buildCollectFees，构建时重新读取仓位。
+ * 打包成交易由 simulateClaim / claimAll（batchCall）完成
+ *
+ * ```ts
+ * const c = await claimable(client, owner)
+ * const plan = await buildClaimAll(client, owner, c.positions)
+ * ```
+ */
+export async function buildClaimAll(client: SolanaClient, owner: string, positions: readonly ClaimTarget[], options: BuildClaimOptions = {}): Promise<ClaimPlan> {
+  if (!isAddress(owner)) {
+    throw new Error(`Invalid owner address: ${owner}`)
+  }
+  const unique = [...new Map(positions.map((p) => [p.positionMint, p])).values()]
+  const calls: ClaimCall[] = []
+  const failed: ClaimPlan['failed'] = []
+  const built = await mapPool(unique, options.concurrency ?? 4, async (position) => {
+    try {
+      const plan = await buildCollectFees(client, owner, { position: { protocol: position.protocol, positionMint: position.positionMint, pool: position.pool } }, { native: options.native, signal: options.signal })
+      return { position, plan, error: null }
+    } catch (err) {
+      if (options.signal?.aborted) throw err
+      return { position, plan: null, error: (err instanceof Error ? err.message : String(err)).slice(0, MAX_ERROR) }
+    }
+  })
+  for (const item of built) {
+    if (item.plan === null) {
+      failed.push({ position: item.position, error: item.error })
+    } else {
+      calls.push({ owner, protocol: item.position.protocol as ClaimProtocol, positionMint: item.position.positionMint, plan: item.plan, instructions: item.plan.steps.flatMap((s) => s.instructions) })
+    }
+  }
+  return { owner, calls, failed }
+}
+
+export interface ClaimSimulation extends PlanSimulation {
+  /** 模拟里收到的代币合计（手续费支付者 / owner 的余额变化，按资产汇总；SOL 为 'native'） */
+  received: Array<{ asset: string; symbol: string; decimals: number; delta: string; formatted: string; usd?: number | null }>
+}
+
+/** 用 /simulate 模拟构建好的批量领取（不签名、不发送）：逐笔交易的结果、哪些仓位会失败、收到的代币合计 */
+export async function simulateClaim(client: SolanaClient, plan: ClaimPlan, options: Omit<PlanSimulationOptions, 'watch'> = {}): Promise<ClaimSimulation> {
+  const sim = await simulatePlan(client, plan.calls, options)
+  const totals = new Map<string, { change: SimulatedBalanceChange; delta: bigint; usd: number | null | undefined }>()
+  const payer = options.feePayer ?? plan.owner
+  for (const { simulation } of sim.transactions) {
+    for (const change of simulation.balanceChanges) {
+      if (change.address !== payer && change.address !== plan.owner) continue
+      const entry = totals.get(change.asset) ?? { change, delta: 0n, usd: undefined }
+      entry.delta += BigInt(change.delta)
+      // 美元价值是所有变化的合计（任何一笔没有价格就是 null）；都没有 usd 字段时不给
+      if (change.usd !== undefined) entry.usd = entry.usd === null || change.usd === null ? null : (entry.usd ?? 0) + change.usd
+      totals.set(change.asset, entry)
+    }
+  }
+  const received = [...totals.values()]
+    .filter((e) => e.delta !== 0n)
+    .map((e) => ({
+      asset: e.change.asset,
+      symbol: e.change.symbol,
+      decimals: e.change.decimals,
+      delta: e.delta.toString(),
+      formatted: `${e.delta < 0n ? '-' : ''}${formatUnits(e.delta < 0n ? -e.delta : e.delta, e.change.decimals)}`,
+      ...(e.usd !== undefined ? { usd: e.usd } : {}),
+    }))
+  return { ...sim, received }
+}
+
+export interface ClaimOptions extends BatchCallOptions, BuildClaimOptions {
+  /** 发送前先用 /simulate 模拟，模拟失败的仓位不发送，默认 true */
+  simulate?: boolean
+  /** 只领取预计价值不低于它的仓位（美元）；没有价格的仓位照常领取。默认 0 */
+  minUsd?: number
+}
+
+export interface ClaimCallResult extends WriteResult {
+  protocol: ClaimProtocol
+  positionMint: string
+}
+
+export interface ClaimResult {
+  plan: ClaimPlan
+  /** 发送前的模拟（simulate: false 时为 null） */
+  simulation: ClaimSimulation | null
+  /** 与 plan.calls 一一对应；dryRun 时 status 为 'simulated' / 'failed'，没有签名 */
+  results: ClaimCallResult[]
+}
+
+/**
+ * 批量领取：构建 → 模拟 → 用 from 签名发送（钱包同 /write 的 batchCall，多个仓位打包进同一笔交易，feePayer 可以替 owner 付手续费）。
+ * positions 不传时先预览、领取全部有东西可领的仓位；一个仓位失败不影响其他的。dryRun: true 只构建和模拟（不签名，from 只用来取地址）
+ *
+ * ```ts
+ * await claimAll(client, key)                                          // 全部
+ * await claimAll(client, key, c.positions.slice(0, 5), { dryRun: true })
+ * ```
+ */
+export async function claimAll(client: SolanaClient, from: SignerInput, positions?: readonly (ClaimTarget & Partial<Pick<ClaimablePosition, 'totalUsd'>>)[], options: ClaimOptions = {}): Promise<ClaimResult> {
+  const { resolveSigner } = await import('./write/signer.js')
+  const owner = (await resolveSigner(from)).address
+  const minUsd = options.minUsd ?? 0
+  const targets = (positions ?? (await claimable(client, owner, { signal: options.signal })).positions).filter((p) => p.totalUsd === undefined || p.totalUsd === null || p.totalUsd >= minUsd)
+  const plan = await buildClaimAll(client, owner, targets, options)
+  const feePayer = options.feePayer === undefined ? undefined : (await resolveSigner(options.feePayer)).address
+  const simulation = options.simulate === false && !options.dryRun ? null : await simulateClaim(client, plan, { feePayer, signal: options.signal, batchSize: (options.mode ?? 'pack') === 'tx' ? 1 : options.batchSize })
+  const failed = new Map(simulation?.failed.map((f) => [f.index, f.error]))
+  const sent = options.dryRun ? [] : await sendCalls(client, from, plan.calls.filter((_, i) => !failed.has(i)), options)
+  let next = 0
+  const results = plan.calls.map((call, index): ClaimCallResult => {
+    const base = { protocol: call.protocol, positionMint: call.positionMint }
+    const error = failed.get(index)
+    if (error !== undefined) return { index, from: owner, status: 'failed', signature: null, slot: null, fee: null, computeUnits: null, error, ...base }
+    if (options.dryRun) return { index, from: owner, status: 'simulated', signature: null, slot: null, fee: null, computeUnits: null, error: null, ...base }
+    return { ...(sent[next++] as WriteResult), index, ...base }
+  })
+  return { plan, simulation, results }
+}

package/src/decode.ts

@@ -0,0 +1,202 @@
+/**
+ * 指令解码（/simulate 和 /history 共用）：System、SPL Token / Token-2022、关联代币账户、计算预算、Memo、升级程序加载器，
+ * 以及 programs.ts 里认得的 DEX / 聚合器（协议 + 指令名 + 大类）。其他程序只给程序名（认得时）和大类 contract / unknown
+ */
+import { encodeAddress } from './address.js'
+import { ASSOCIATED_TOKEN_PROGRAM_ID, SYSTEM_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID } from './constants.js'
+import { BPF_LOADER_UPGRADEABLE, COMPUTE_BUDGET, MEMO_V1, MEMO_V2, PROGRAMS, knownMethod, type IxType } from './programs.js'
+
+export interface DecodedInstruction {
+  /** 在交易里的下标（顶层指令） */
+  index: number
+  programId: string
+  /** 程序名；不认识时为 null */
+  program: string | null
+  type: IxType
+  protocol?: string
+  method?: string
+  summary: string
+  /** 金额都是最小单位的十进制字符串 */
+  args?: Record<string, unknown>
+}
+
+/** Token 的 SetAuthority 的权限类型 */
+export const AUTHORITY_TYPES = [
+  'MintTokens', 'FreezeAccount', 'AccountOwner', 'CloseAccount', 'TransferFeeConfig', 'WithheldWithdraw', 'CloseMint', 'InterestRate',
+  'PermanentDelegate', 'ConfidentialTransferMint', 'TransferHookProgramId', 'ConfidentialTransferFeeConfig', 'MetadataPointer', 'GroupPointer', 'GroupMemberPointer',
+] as const
+
+const short = (a: string | undefined) => (a ? `${a.slice(0, 4)}…${a.slice(-4)}` : '?')
+
+class Data {
+  readonly view: DataView
+  offset = 0
+  constructor(readonly bytes: Uint8Array) {
+    this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  }
+  u8() {
+    return this.view.getUint8(this.offset++)
+  }
+  u32() {
+    const v = this.view.getUint32(this.offset, true)
+    this.offset += 4
+    return v
+  }
+  u64() {
+    const v = this.view.getBigUint64(this.offset, true)
+    this.offset += 8
+    return v
+  }
+  key() {
+    const v = encodeAddress(this.bytes.slice(this.offset, this.offset + 32))
+    this.offset += 32
+    return v
+  }
+}
+
+/**
+ * 解码一条指令。accounts 是指令用到的账户地址（已按指令里的下标解析，包含地址查找表里的），data 是指令数据。
+ * 数据格式不对时不抛错，按“不认识的指令”返回
+ */
+export function decodeInstruction(index: number, programId: string, accounts: readonly string[], data: Uint8Array): DecodedInstruction {
+  const info = PROGRAMS[programId]
+  const base = { index, programId, program: info?.name ?? null }
+  try {
+    const decoded = decodeKnown(programId, accounts, data)
+    if (decoded) return { ...base, ...decoded }
+    const known = knownMethod(programId, data)
+    if (known) {
+      return { ...base, type: known[1], protocol: info?.protocol, method: known[0], summary: `${info?.protocol ?? info?.name} ${known[0]}` }
+    }
+  } catch {
+    // 数据不符合格式：当作不认识
+  }
+  if (info) return { ...base, type: 'contract', protocol: info.protocol, summary: `Call ${info.name}` }
+  return { ...base, type: 'unknown', summary: `Call unknown program ${short(programId)}` }
+}
+
+type Partial_ = Pick<DecodedInstruction, 'type' | 'summary'> & Partial<Pick<DecodedInstruction, 'method' | 'args' | 'protocol'>>
+
+function decodeKnown(programId: string, a: readonly string[], data: Uint8Array): Partial_ | null {
+  const d = new Data(data)
+  switch (programId) {
+    case SYSTEM_PROGRAM_ID:
+      return decodeSystem(d, a)
+    case TOKEN_PROGRAM_ID:
+    case TOKEN_2022_PROGRAM_ID:
+      return decodeToken(d, a)
+    case ASSOCIATED_TOKEN_PROGRAM_ID: {
+      const method = data.length === 0 || data[0] === 0 ? 'create' : data[0] === 1 ? 'createIdempotent' : 'recoverNested'
+      return { type: 'setup', method, summary: `Create token account for ${short(a[2])}`, args: { payer: a[0], account: a[1], owner: a[2], mint: a[3] } }
+    }
+    case COMPUTE_BUDGET: {
+      const tag = d.u8()
+      if (tag === 2) return { type: 'budget', method: 'setComputeUnitLimit', summary: 'Set compute unit limit', args: { units: d.u32() } }
+      if (tag === 3) return { type: 'budget', method: 'setComputeUnitPrice', summary: 'Set priority fee', args: { microLamports: d.u64().toString() } }
+      return { type: 'budget', summary: 'Compute budget' }
+    }
+    case MEMO_V1:
+    case MEMO_V2:
+      return { type: 'memo', method: 'memo', summary: 'Memo', args: { text: new TextDecoder().decode(data) } }
+    case BPF_LOADER_UPGRADEABLE: {
+      const tag = d.u32()
+      const method = ['initializeBuffer', 'write', 'deploy', 'upgrade', 'setAuthority', 'close', 'extendProgram', 'setAuthorityChecked'][tag]
+      return { type: 'contract', method, summary: `Program loader: ${method ?? `instruction ${tag}`}`, args: { program: a[tag === 3 ? 1 : 0] } }
+    }
+    default:
+      return null
+  }
+}
+
+function decodeSystem(d: Data, a: readonly string[]): Partial_ {
+  const tag = d.u32()
+  switch (tag) {
+    case 0: {
+      const lamports = d.u64()
+      const space = d.u64()
+      return { type: 'setup', method: 'createAccount', summary: `Create account ${short(a[1])}`, args: { from: a[0], account: a[1], lamports: lamports.toString(), space: space.toString(), owner: d.key() } }
+    }
+    case 1: {
+      const owner = d.key()
+      return { type: 'approve', method: 'assign', summary: `Assign ${short(a[0])} to program ${short(owner)}`, args: { account: a[0], owner } }
+    }
+    case 2: {
+      const lamports = d.u64()
+      return { type: 'transfer', method: 'transfer', summary: `Transfer SOL to ${short(a[1])}`, args: { from: a[0], to: a[1], lamports: lamports.toString() } }
+    }
+    case 11: {
+      const lamports = d.u64()
+      return { type: 'transfer', method: 'transferWithSeed', summary: `Transfer SOL to ${short(a[2])}`, args: { from: a[0], to: a[2], lamports: lamports.toString() } }
+    }
+    case 5: {
+      const lamports = d.u64()
+      return { type: 'transfer', method: 'withdrawNonce', summary: `Withdraw nonce account to ${short(a[1])}`, args: { from: a[0], to: a[1], lamports: lamports.toString() } }
+    }
+    case 10:
+      return { type: 'approve', method: 'assignWithSeed', summary: `Assign ${short(a[0])} to another program`, args: { account: a[0] } }
+    default:
+      return { type: 'setup', summary: 'System instruction', method: ['createAccount', 'assign', 'transfer', 'createAccountWithSeed', 'advanceNonce', 'withdrawNonce', 'initializeNonce', 'authorizeNonce', 'allocate', 'allocateWithSeed'][tag] }
+  }
+}
+
+function decodeToken(d: Data, a: readonly string[]): Partial_ {
+  const tag = d.u8()
+  const amountArgs = (extra: Record<string, unknown>, amount: bigint) => ({ ...extra, amount: amount.toString() })
+  switch (tag) {
+    case 3: {
+      const amount = d.u64()
+      return { type: 'transfer', method: 'transfer', summary: `Transfer tokens to ${short(a[1])}`, args: amountArgs({ source: a[0], destination: a[1], authority: a[2] }, amount) }
+    }
+    case 12: {
+      const amount = d.u64()
+      return { type: 'transfer', method: 'transferChecked', summary: `Transfer tokens to ${short(a[2])}`, args: amountArgs({ source: a[0], mint: a[1], destination: a[2], authority: a[3] }, amount) }
+    }
+    case 26: {
+      const sub = d.u8()
+      if (sub === 1) {
+        const amount = d.u64()
+        return { type: 'transfer', method: 'transferCheckedWithFee', summary: `Transfer tokens to ${short(a[2])}`, args: amountArgs({ source: a[0], mint: a[1], destination: a[2], authority: a[3] }, amount) }
+      }
+      return { type: 'setup', method: 'transferFeeExtension', summary: 'Token-2022 transfer fee instruction' }
+    }
+    case 4: {
+      const amount = d.u64()
+      return { type: 'approve', method: 'approve', summary: `Approve ${short(a[1])} to spend tokens`, args: amountArgs({ account: a[0], delegate: a[1], owner: a[2] }, amount) }
+    }
+    case 13: {
+      const amount = d.u64()
+      return { type: 'approve', method: 'approveChecked', summary: `Approve ${short(a[2])} to spend tokens`, args: amountArgs({ account: a[0], mint: a[1], delegate: a[2], owner: a[3] }, amount) }
+    }
+    case 5:
+      return { type: 'approve', method: 'revoke', summary: 'Revoke token delegate', args: { account: a[0], owner: a[1] } }
+    case 6: {
+      const authorityType = AUTHORITY_TYPES[d.u8()] ?? 'Unknown'
+      const newAuthority = d.u8() === 1 ? d.key() : null
+      return {
+        type: 'approve',
+        method: 'setAuthority',
+        summary: newAuthority ? `Set ${authorityType} authority to ${short(newAuthority)}` : `Remove ${authorityType} authority`,
+        args: { account: a[0], authorityType, newAuthority },
+      }
+    }
+    case 7:
+    case 14: {
+      const amount = d.u64()
+      return { type: 'mint', method: tag === 7 ? 'mintTo' : 'mintToChecked', summary: `Mint tokens to ${short(a[1])}`, args: amountArgs({ mint: a[0], destination: a[1] }, amount) }
+    }
+    case 8:
+    case 15: {
+      const amount = d.u64()
+      return { type: 'burn', method: tag === 8 ? 'burn' : 'burnChecked', summary: 'Burn tokens', args: amountArgs({ account: a[0], mint: a[1] }, amount) }
+    }
+    case 9:
+      return { type: 'close', method: 'closeAccount', summary: `Close token account ${short(a[0])}`, args: { account: a[0], destination: a[1], owner: a[2] } }
+    case 17:
+      return { type: 'setup', method: 'syncNative', summary: 'Sync wrapped SOL', args: { account: a[0] } }
+    case 10:
+    case 11:
+      return { type: 'contract', method: tag === 10 ? 'freezeAccount' : 'thawAccount', summary: tag === 10 ? 'Freeze token account' : 'Thaw token account', args: { account: a[0] } }
+    default:
+      return { type: 'setup', summary: tag <= 25 ? 'Initialize token account / mint' : 'Token-2022 extension instruction' }
+  }
+}

package/src/describe.ts

@@ -0,0 +1,77 @@
+/** 交易的类型和一句话说明（/simulate 和 /history 共用）：指令的大类 + 钱包的余额变化 */
+import type { DecodedInstruction } from './decode.js'
+import { PROGRAMS } from './programs.js'
+
+export interface AssetDelta {
+  asset: string
+  symbol: string
+  decimals: number
+  /** 带符号的最小单位十进制字符串 */
+  delta: string
+  formatted: string
+}
+
+export type TxKind = 'transfer' | 'swap' | 'approve' | 'liquidity' | 'mint' | 'contract' | 'unknown'
+
+export interface Classified {
+  type: TxKind
+  protocol?: string
+  method?: string
+  /** 没有认得的指令、按余额变化（一个资产减少、另一个增加）推断为 swap */
+  inferred?: boolean
+}
+
+const short = (a: string) => `${a.slice(0, 4)}…${a.slice(-4)}`
+
+/**
+ * 判断类型：先看认得的指令（流动性 > 兑换 > 授权 > 铸造），再看是不是只有转账；有不认得的程序时，
+ * 钱包一个资产减少、另一个增加就推断为兑换，否则是合约调用（程序认得）或未知。没有任何有意义的指令（只有建账户、关闭等）时为 null
+ */
+export function classify(ixs: readonly DecodedInstruction[], changes: readonly Pick<AssetDelta, 'asset' | 'delta'>[]): Classified | null {
+  const pick = (type: DecodedInstruction['type']) => ixs.find((ix) => ix.type === type)
+  const result = (ix: DecodedInstruction, type: TxKind): Classified => ({ type, protocol: ix.protocol, method: ix.method })
+  for (const type of ['liquidity', 'swap', 'approve', 'mint'] as const) {
+    const ix = pick(type)
+    if (ix) return result(ix, type)
+  }
+  const others = ixs.filter((ix) => ix.type === 'contract' || ix.type === 'unknown')
+  const out = changes.filter((c) => c.delta.startsWith('-'))
+  const received = changes.filter((c) => !c.delta.startsWith('-') && c.delta !== '0')
+  if (others.length) {
+    const first = others.find((ix) => ix.protocol) ?? others[0]!
+    if (out.length && received.some((r) => out.some((o) => o.asset !== r.asset))) return { type: 'swap', protocol: first.protocol, inferred: true }
+    return { type: others.some((ix) => PROGRAMS[ix.programId]) ? 'contract' : 'unknown', protocol: first.protocol, method: first.method }
+  }
+  const transfer = pick('transfer')
+  if (transfer) return result(transfer, 'transfer')
+  return null
+}
+
+const amount = (c: AssetDelta) => `${c.formatted.replace(/^-/, '')} ${c.symbol}`
+const join = (list: readonly AssetDelta[]) => list.map(amount).join(' + ')
+
+/** 一句话说明，如 “Swap 1 SOL for 150.2 USDC on Jupiter” */
+export function describe(kind: Classified | null, ixs: readonly DecodedInstruction[], changes: readonly AssetDelta[], counterparty?: string): string {
+  const out = changes.filter((c) => c.delta.startsWith('-'))
+  const received = changes.filter((c) => !c.delta.startsWith('-') && c.delta !== '0')
+  const via = kind?.protocol ? ` on ${kind.protocol}` : ''
+  switch (kind?.type) {
+    case 'swap':
+      return out.length && received.length ? `Swap ${join(out)} for ${join(received)}${via}` : `Swap${via}`
+    case 'transfer':
+      if (out.length && !received.length) return `Send ${join(out)}${counterparty ? ` to ${short(counterparty)}` : ''}`
+      if (received.length && !out.length) return `Receive ${join(received)}${counterparty ? ` from ${short(counterparty)}` : ''}`
+      return ixs.find((ix) => ix.type === 'transfer')?.summary ?? 'Transfer'
+    case 'liquidity':
+      return `${kind.method ? kind.method.replace(/_/g, ' ') : 'Liquidity'}${via}${out.length ? `: pay ${join(out)}` : ''}${received.length ? `${out.length ? ',' : ':'} receive ${join(received)}` : ''}`
+    case 'approve':
+      return ixs.find((ix) => ix.type === 'approve')?.summary ?? 'Approve'
+    case 'mint':
+      return `Mint${received.length ? `: receive ${join(received)}` : ''}${via}`
+    case 'contract':
+    case 'unknown':
+      return `${ixs.find((ix) => ix.type === kind.type)?.summary ?? 'Call program'}${out.length ? `, pay ${join(out)}` : ''}${received.length ? `, receive ${join(received)}` : ''}`
+    default:
+      return ixs.find((ix) => ix.type === 'close')?.summary ?? (changes.length ? `Balance change: ${join(changes)}` : 'No balance change')
+  }
+}