@w3lib/solana-batch-call 0.5.0 → 0.7.0

package/src/clientConfig.ts

@@ -0,0 +1,12 @@
+import type { Cluster } from './constants.js'
+import type { SourceOptions } from './source.js'
+
+/** SolanaClient 的节点配置（网络、节点选项、期望的创世哈希），按客户端登记：写操作的 sendRpc 按同样的配置解析、校验网络 */
+export interface ClientSourceConfig {
+  cluster: Cluster | undefined
+  options: SourceOptions
+  genesis: () => Promise<string>
+}
+
+/** 单独成模块：/write 只需查表，不用静态带上 source.ts（sendRpc 解析时才按需加载） */
+export const clientSourceConfigs = new WeakMap<object, ClientSourceConfig>()

package/src/decode.ts

@@ -0,0 +1,176 @@
+/**
+ * 指令解码（/simulate 和 /history 共用）：System、SPL Token / Token-2022、关联代币账户、计算预算、Memo、升级程序加载器，
+ * 以及 programs.ts 里认得的 DEX / 聚合器（协议 + 指令名 + 大类）。其他程序只给程序名（认得时）和大类 contract / unknown
+ */
+import { Bytes } from './bytes.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)}` : '?')
+
+/**
+ * 解码一条指令。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 Bytes(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: Bytes, 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: Bytes, 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')
+  }
+}

package/src/fees.ts

@@ -7,7 +7,7 @@ import { base64 } from '@scure/base'
 import { encodeAddress } from './address.js'
 import type { RequestOptions, SolanaClient } from './client.js'
 import { SOL_DECIMALS, SYSTEM_PROGRAM_ID } from './constants.js'
-import { formatUnits } from './layout.js'
+import { computeBudgetOf, formatUnits } from './layout.js'
 import type { InstructionInput } from './write/transaction.js'
 
 export type FeeLevel = 'slow' | 'normal' | 'fast'
@@ -156,14 +156,7 @@ export async function estimateCost(client: SolanaClient, input: CostInput, optio
     raw = base64.encode(bytes)
     signatures = message.signatures
     writable = [...message.writable, ...(await lookupWritable(client, message.lookups, signal))]
-    let limit: number | null = null
-    let price = 0n
-    for (const ix of message.instructions) {
-      if (ix.programId !== COMPUTE_BUDGET_PROGRAM_ID) continue
-      const view = new DataView(ix.data.buffer, ix.data.byteOffset, ix.data.byteLength)
-      if (ix.data[0] === 2 && ix.data.length >= 5) limit = view.getUint32(1, true)
-      if (ix.data[0] === 3 && ix.data.length >= 9) price = view.getBigUint64(1, true)
-    }
+    const { limit, price } = computeBudgetOf(message.instructions)
     const others = message.instructions.filter((ix) => ix.programId !== COMPUTE_BUDGET_PROGRAM_ID).length
     budget = { limit: Math.min(MAX_COMPUTE_UNITS, limit ?? DEFAULT_UNITS_PER_INSTRUCTION * others), price }
   } else {

package/src/history.ts

@@ -0,0 +1,325 @@
+/**
+ * 交易历史（子路径 `@w3lib/solana-batch-call/history`）：把地址的交易整理成统一的 Activity（类型、方向、对手方、资产变化、手续费）。
+ * 数据源可以换：默认 rpcHistory（getSignaturesForAddress 翻页 + getTransaction，免费节点就能用，节点失败自动切换），
+ * 也可以传 heliusHistory 等；传多个时按顺序尝试。游标就是最后一条签名，换数据源也能接着翻
+ */
+import { base58 } from '@scure/base'
+
+import { InvalidAddressError, isAddress } from './address.js'
+import type { RequestOptions, SolanaClient } from './client.js'
+import { NATIVE_MINT, SOL_DECIMALS, SYSTEM_PROGRAM_ID } from './constants.js'
+import { decodeInstruction, type DecodedInstruction } from './decode.js'
+import { classify, describe, type AssetDelta, type Classified } from './describe.js'
+import { formatUnits } from './layout.js'
+import { mapPool } from './util.js'
+
+export type ActivityType = 'transfer' | 'swap' | 'approve' | 'liquidity' | 'mint' | 'contract' | 'other'
+
+export interface ActivityChange extends AssetDelta {}
+
+export interface Activity {
+  /** 交易签名 */
+  hash: string
+  /** 区块时间（unix 秒）；节点没有给时为 0 */
+  time: number
+  /** slot */
+  block?: number
+  status: 'success' | 'failed'
+  type: ActivityType
+  /** 对这个地址来说：资产只增加 in、只减少 out、转给自己 self；兑换等有增有减时不填 */
+  direction?: 'in' | 'out' | 'self'
+  /** 转账的对手方 */
+  counterparty?: string
+  /** 一句话说明，如 “Swap 1 SOL for 150 USDC on Jupiter” */
+  label?: string
+  /** 这个地址的资产变化（SOL 不含手续费，Wrapped SOL 并入 SOL；asset 原生为 'native'，其他是 mint） */
+  changes: ActivityChange[]
+  /** 这个地址付的手续费（lamports，十进制字符串）；不是手续费支付者时不填 */
+  fee?: string
+  protocol?: string
+}
+
+export interface HistoryPage {
+  items: Activity[]
+  /** 还有更多时：下一页的游标（最后一条处理过的签名）；没有更多时不返回 */
+  nextCursor?: string
+}
+
+export interface HistoryContext {
+  client: SolanaClient
+  address: string
+  limit: number
+  cursor?: string
+  /** 只要这个时间（unix 秒）之前 / 之后的 */
+  before?: number
+  after?: number
+  types?: readonly ActivityType[]
+  fetch: typeof fetch
+  signal?: AbortSignal
+}
+
+/** 历史数据源：返回统一格式的 Activity（代币的 symbol 先用缩写的 mint，getHistory 统一补全）；游标是签名 */
+export interface HistorySource {
+  readonly name: string
+  getHistory(ctx: HistoryContext): Promise<HistoryPage>
+}
+
+export interface HistoryOptions extends RequestOptions {
+  /** 每页条数，默认 20，最多 100 */
+  limit?: number
+  /** 上一页的 nextCursor */
+  cursor?: string
+  /** 区块时间上限（不含）/ 下限（含），unix 秒 */
+  before?: number
+  after?: number
+  /** 只要这些类型（不够 limit 时会往后多找，最多看 limit × 5 笔） */
+  types?: readonly ActivityType[]
+  /** 数据源，默认 rpcHistory()；传数组时按顺序尝试，前一个失败换下一个 */
+  source?: HistorySource | readonly HistorySource[]
+  /** 补全代币符号（读 mint 的元数据），默认 true */
+  symbols?: boolean
+  fetch?: typeof fetch
+}
+
+export const MAX_HISTORY_LIMIT = 100
+/** getTransaction 支持的交易版本：主网已经有 v1 格式的交易（2026-10），只给 0 时遇到它们整个请求报错（-32015）；json 编码下 v1 的账户和指令字段与 v0 相同 */
+const MAX_TX_VERSION = 1
+
+const short = (a: string) => `${a.slice(0, 4)}…${a.slice(-4)}`
+
+/**
+ * 查地址的交易历史。
+ *
+ * ```ts
+ * const page = await history(client, address, { limit: 20 })
+ * const next = await history(client, address, { cursor: page.nextCursor })
+ * ```
+ */
+export async function history(client: SolanaClient, address: string, options: HistoryOptions = {}): Promise<HistoryPage> {
+  if (!isAddress(address)) throw new InvalidAddressError(`Invalid address: ${address}`, address)
+  const limit = options.limit ?? 20
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_HISTORY_LIMIT) throw new RangeError(`limit must be an integer between 1 and ${MAX_HISTORY_LIMIT}`)
+  const sources = options.source === undefined ? [rpcHistory()] : Array.isArray(options.source) ? options.source : [options.source as HistorySource]
+  if (!sources.length) throw new Error('No history source')
+  const ctx: HistoryContext = {
+    client,
+    address,
+    limit,
+    cursor: options.cursor,
+    before: options.before,
+    after: options.after,
+    types: options.types?.length ? options.types : undefined,
+    fetch: options.fetch ?? ((...args) => fetch(...args)),
+    signal: options.signal,
+  }
+  const errors: string[] = []
+  for (const source of sources) {
+    try {
+      const page = await (source as HistorySource).getHistory(ctx)
+      if (options.symbols !== false) await fillSymbols(client, page.items, options.signal)
+      return page
+    } catch (err) {
+      if (options.signal?.aborted) throw err
+      errors.push(`${(source as HistorySource).name}: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+  throw new Error(`All history sources failed (${errors.join('; ')})`)
+}
+
+/** 补全还是缩写 mint 的 symbol（一次 tokens 查询，label 里的同步替换）；读不到的用缩写的 mint */
+async function fillSymbols(client: SolanaClient, items: Activity[], signal: AbortSignal | undefined): Promise<void> {
+  const pending = (c: ActivityChange) => c.symbol === short(c.asset)
+  const missing = [...new Set(items.flatMap((a) => a.changes.filter(pending).map((c) => c.asset)))]
+  if (!missing.length) return
+  const details = await client.tokens(missing, { fields: ['symbol'], signal }).catch(() => null)
+  const symbols = new Map(missing.map((m, i) => [m, details?.[i]?.symbol ?? short(m)]))
+  for (const a of items) {
+    for (const c of a.changes) {
+      if (!pending(c)) continue
+      const symbol = symbols.get(c.asset) as string
+      if (a.label) a.label = a.label.split(c.symbol).join(symbol)
+      c.symbol = symbol
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// RPC 数据源
+// ---------------------------------------------------------------------------
+
+export interface RpcHistoryOptions {
+  /** 同时取多少笔交易的详情，默认 6（公共节点限频很严，节点自己会对 429 退避重试） */
+  concurrency?: number
+  /** 一次翻页最多检查多少笔签名（含被 types / 时间过滤掉的），默认 limit × 5，最多 500 */
+  maxScan?: number
+}
+
+interface RawTransaction {
+  slot: number
+  blockTime: number | null
+  meta: {
+    err: unknown
+    fee: number
+    preBalances: number[]
+    postBalances: number[]
+    preTokenBalances?: RawTokenBalance[]
+    postTokenBalances?: RawTokenBalance[]
+    loadedAddresses?: { writable: string[]; readonly: string[] }
+  } | null
+  transaction: {
+    signatures: string[]
+    message: { accountKeys: string[]; instructions: Array<{ programIdIndex: number; accounts: number[]; data: string }> }
+  }
+}
+
+interface RawTokenBalance {
+  accountIndex: number
+  mint: string
+  owner?: string
+  uiTokenAmount: { amount: string; decimals: number }
+}
+
+interface SignatureInfo {
+  signature: string
+  slot: number
+  err: unknown
+  blockTime: number | null
+}
+
+
+/**
+ * 默认数据源：getSignaturesForAddress（用 before 翻页）+ getTransaction（逐笔，json 编码、支持 v0）。
+ * 先按区块时间过滤签名再取详情，只取需要的笔数；失败的交易也列出（status 为 failed）。每页的请求数 ≈ limit + 1
+ */
+export function rpcHistory(options: RpcHistoryOptions = {}): HistorySource {
+  const concurrency = options.concurrency ?? 6
+  return {
+    name: 'rpc',
+    async getHistory(ctx) {
+      const { client, address, limit, signal } = ctx
+      const maxScan = Math.min(options.maxScan ?? limit * 5, 500)
+      const items: Activity[] = []
+      let cursor = ctx.cursor
+      let scanned = 0
+      let more = true
+      while (items.length < limit && scanned < maxScan && more) {
+        const pageSize = Math.min(1000, Math.max(limit, 20) * (ctx.types ? 3 : 1))
+        const commitment = client.commitment === 'processed' ? 'confirmed' : client.commitment
+        const sigs = await client.request<SignatureInfo[]>('getSignaturesForAddress', [address, { limit: pageSize, ...(cursor ? { before: cursor } : {}), commitment }], { signal })
+        if (!sigs.length) {
+          more = false
+          break
+        }
+        // 按时间过滤：比 before 新的跳过；比 after 旧的之后都不用看了（签名按从新到旧排列）
+        let rows = sigs.filter((s) => ctx.before === undefined || s.blockTime === null || s.blockTime < ctx.before)
+        const old = ctx.after === undefined ? -1 : rows.findIndex((s) => s.blockTime !== null && s.blockTime < (ctx.after as number))
+        if (old >= 0) rows = rows.slice(0, old)
+        let i = 0
+        while (i < rows.length && items.length < limit && scanned < maxScan) {
+          const chunk = rows.slice(i, i + Math.max(1, Math.min(limit - items.length, maxScan - scanned)))
+          const txs = await mapPool(chunk, concurrency, (row) => client.request<RawTransaction | null>('getTransaction', [row.signature, { encoding: 'json', maxSupportedTransactionVersion: MAX_TX_VERSION, commitment }], { signal }))
+          for (const [j, tx] of txs.entries()) {
+            i++
+            scanned++
+            cursor = (chunk[j] as SignatureInfo).signature
+            const activity = tx ? activityFromTransaction(address, tx) : null
+            if (activity && (!ctx.types || ctx.types.includes(activity.type))) items.push(activity)
+            if (items.length >= limit) break
+          }
+        }
+        if (i >= rows.length) {
+          // 这一页看完了：接着从这一页最后一条往后翻；没有更多（不足一页、或已经到 after）时结束
+          cursor = (sigs[sigs.length - 1] as SignatureInfo).signature
+          more = sigs.length >= pageSize && old < 0
+        }
+      }
+      return { items, ...(more && cursor ? { nextCursor: cursor } : {}) }
+    },
+  }
+}
+
+const SOL: Pick<AssetDelta, 'asset' | 'symbol' | 'decimals'> = { asset: 'native', symbol: 'SOL', decimals: SOL_DECIMALS }
+
+/** 合并资产变化：同一资产相加，去掉 0 */
+function toChanges(native: bigint, tokens: Map<string, { delta: bigint; decimals: number }>): ActivityChange[] {
+  const out: ActivityChange[] = []
+  if (native !== 0n) out.push({ ...SOL, delta: native.toString(), formatted: formatUnits(native, SOL_DECIMALS) })
+  for (const [asset, { delta, decimals }] of tokens) {
+    if (delta !== 0n) out.push({ asset, symbol: short(asset), decimals, delta: delta.toString(), formatted: formatUnits(delta, decimals) })
+  }
+  return out
+}
+
+function directionOf(changes: readonly ActivityChange[], counterparty: string | undefined, address: string): Activity['direction'] {
+  if (!changes.length) return counterparty === address ? 'self' : undefined
+  const negative = changes.filter((c) => c.delta.startsWith('-')).length
+  if (negative === 0) return 'in'
+  return negative === changes.length ? 'out' : undefined
+}
+
+const toActivityType = (kind: Classified | null): ActivityType => (kind ? (kind.type === 'unknown' ? 'contract' : kind.type) : 'other')
+
+/** 一笔 getTransaction（json 编码）整理成 Activity，address 的角度；导出供测试和自己取到交易的场景使用 */
+export function activityFromTransaction(address: string, tx: RawTransaction): Activity | null {
+  const meta = tx.meta
+  const hash = tx.transaction.signatures[0]
+  if (!meta || !hash) return null
+  const message = tx.transaction.message
+  const keys = [...message.accountKeys, ...(meta.loadedAddresses?.writable ?? []), ...(meta.loadedAddresses?.readonly ?? [])]
+  const failed = meta.err !== null && meta.err !== undefined
+  const ixs: DecodedInstruction[] = message.instructions.map((ix, i) => {
+    const programId = keys[ix.programIdIndex] as string
+    return decodeInstruction(i, programId, ix.accounts.map((a) => keys[a] as string), base58.decode(ix.data))
+  })
+
+  const index = keys.indexOf(address)
+  const isPayer = index === 0
+  const fee = BigInt(meta.fee)
+  let native = index >= 0 ? BigInt(meta.postBalances[index] ?? 0) - BigInt(meta.preBalances[index] ?? 0) + (isPayer ? fee : 0n) : 0n
+  const tokens = new Map<string, { delta: bigint; decimals: number }>()
+  const ownerOf = new Map<number, string>()
+  for (const [list, sign] of [[meta.preTokenBalances ?? [], -1n], [meta.postTokenBalances ?? [], 1n]] as const) {
+    for (const b of list) {
+      if (b.owner) ownerOf.set(b.accountIndex, b.owner)
+      if (b.owner !== address) continue
+      const prev = tokens.get(b.mint)
+      tokens.set(b.mint, { delta: (prev?.delta ?? 0n) + sign * BigInt(b.uiTokenAmount.amount), decimals: b.uiTokenAmount.decimals })
+    }
+  }
+  // Wrapped SOL 并入 SOL
+  const wsol = tokens.get(NATIVE_MINT)
+  if (wsol) {
+    native += wsol.delta
+    tokens.delete(NATIVE_MINT)
+  }
+  const changes = failed ? [] : toChanges(native, tokens)
+
+  // 对手方：第一笔转账的另一头（代币转账取代币账户的 owner）
+  let counterparty: string | undefined
+  for (const ix of ixs) {
+    if (ix.type !== 'transfer') continue
+    const args = ix.args as Record<string, string> | undefined
+    const owner = (account: string | undefined) => (account ? (ownerOf.get(keys.indexOf(account)) ?? (ix.programId === SYSTEM_PROGRAM_ID ? account : undefined)) : undefined)
+    const from = owner(args?.from ?? args?.source)
+    const to = owner(args?.to ?? args?.destination)
+    counterparty = from === address ? to : from
+    if (counterparty) break
+  }
+
+  const kind = classify(ixs, changes)
+  const type = toActivityType(kind)
+  const label = describe(kind, ixs, changes, counterparty)
+  return {
+    hash,
+    time: tx.blockTime ?? 0,
+    block: tx.slot,
+    status: failed ? 'failed' : 'success',
+    type,
+    direction: type === 'transfer' || type === 'other' ? directionOf(changes, counterparty, address) : undefined,
+    counterparty,
+    label: failed ? `Failed: ${label}` : label,
+    changes,
+    ...(isPayer ? { fee: fee.toString() } : {}),
+    protocol: kind?.protocol,
+  }
+}