@w3lib/solana-batch-call 0.5.0 → 0.7.0

package/src/historyHelius.ts

@@ -0,0 +1,136 @@
+/** Helius 增强交易历史数据源（需要应用自己的 API key）：把 `/v0/addresses/{address}/transactions` 的结果整理成和 rpcHistory 一样的 Activity */
+import { NATIVE_MINT, SOL_DECIMALS } from './constants.js'
+import { formatUnits } from './layout.js'
+import type { Activity, ActivityChange, ActivityType, HistorySource } from './history.js'
+
+export interface HeliusHistoryOptions {
+  apiKey: string
+  /** 默认 https://api.helius.xyz */
+  baseUrl?: string
+}
+
+interface HeliusItem {
+  signature: string
+  timestamp?: number
+  slot?: number
+  fee?: number
+  feePayer?: string
+  type?: string
+  source?: string
+  description?: string
+  transactionError?: unknown
+  nativeTransfers?: Array<{ fromUserAccount: string; toUserAccount: string; amount: number }>
+  tokenTransfers?: Array<{ fromUserAccount: string | null; toUserAccount: string | null; tokenAmount: number; mint: string }>
+  accountData?: Array<{
+    account: string
+    nativeBalanceChange?: number
+    tokenBalanceChanges?: Array<{ userAccount: string; mint: string; rawTokenAmount: { tokenAmount: string; decimals: number } }>
+  }>
+}
+
+const short = (a: string) => `${a.slice(0, 4)}…${a.slice(-4)}`
+
+/** Helius 的交易类型 → Activity 类型（认不出的按资产变化判断） */
+function typeOf(item: HeliusItem, changes: readonly ActivityChange[]): ActivityType {
+  const t = item.type ?? ''
+  if (/SWAP/.test(t)) return 'swap'
+  if (t === 'TRANSFER') return 'transfer'
+  if (/LIQUIDITY|POSITION|POOL/.test(t)) return 'liquidity'
+  if (/MINT/.test(t)) return 'mint'
+  if (/APPROVE|REVOKE|DELEGATE/.test(t)) return 'approve'
+  const out = changes.filter((c) => c.delta.startsWith('-'))
+  if (out.length && changes.some((c) => !c.delta.startsWith('-') && out.some((o) => o.asset !== c.asset))) return 'swap'
+  return t && t !== 'UNKNOWN' ? 'contract' : 'other'
+}
+
+export function activityFromHelius(address: string, item: HeliusItem): Activity {
+  const me = item.accountData?.find((a) => a.account === address)
+  const isPayer = item.feePayer === address
+  const fee = BigInt(item.fee ?? 0)
+  let native = BigInt(me?.nativeBalanceChange ?? 0) + (isPayer ? fee : 0n)
+  const tokens = new Map<string, { delta: bigint; decimals: number }>()
+  for (const entry of item.accountData ?? []) {
+    for (const t of entry.tokenBalanceChanges ?? []) {
+      if (t.userAccount !== address) continue
+      const prev = tokens.get(t.mint)
+      tokens.set(t.mint, { delta: (prev?.delta ?? 0n) + BigInt(t.rawTokenAmount.tokenAmount), decimals: t.rawTokenAmount.decimals })
+    }
+  }
+  const wsol = tokens.get(NATIVE_MINT)
+  if (wsol) {
+    native += wsol.delta
+    tokens.delete(NATIVE_MINT)
+  }
+  const failed = item.transactionError !== null && item.transactionError !== undefined
+  const changes: ActivityChange[] = []
+  if (!failed) {
+    if (native !== 0n) changes.push({ asset: 'native', symbol: 'SOL', decimals: SOL_DECIMALS, delta: native.toString(), formatted: formatUnits(native, SOL_DECIMALS) })
+    for (const [asset, { delta, decimals }] of tokens) {
+      if (delta !== 0n) changes.push({ asset, symbol: short(asset), decimals, delta: delta.toString(), formatted: formatUnits(delta, decimals) })
+    }
+  }
+  const type = typeOf(item, changes)
+  let counterparty: string | undefined
+  for (const t of [...(item.nativeTransfers ?? []), ...(item.tokenTransfers ?? []).map((x) => ({ fromUserAccount: x.fromUserAccount ?? '', toUserAccount: x.toUserAccount ?? '' }))]) {
+    if (t.fromUserAccount === address && t.toUserAccount) counterparty = t.toUserAccount
+    else if (t.toUserAccount === address && t.fromUserAccount) counterparty = t.fromUserAccount
+    if (counterparty) break
+  }
+  const negative = changes.filter((c) => c.delta.startsWith('-')).length
+  const protocol = item.source && !/^(SYSTEM_PROGRAM|UNKNOWN)$/.test(item.source) ? item.source[0] + item.source.slice(1).toLowerCase().replace(/_/g, ' ') : undefined
+  return {
+    hash: item.signature,
+    time: item.timestamp ?? 0,
+    block: item.slot,
+    status: failed ? 'failed' : 'success',
+    type,
+    direction: (type === 'transfer' || type === 'other') && changes.length ? (negative === 0 ? 'in' : negative === changes.length ? 'out' : undefined) : undefined,
+    counterparty,
+    label: item.description || undefined,
+    changes,
+    ...(isPayer ? { fee: fee.toString() } : {}),
+    protocol,
+  }
+}
+
+/**
+ * Helius 增强交易历史（`GET /v0/addresses/{address}/transactions`，按 before 签名翻页）。apiKey 由应用传入，库里不带。
+ * 按交易类型过滤时翻页最多再取 3 页
+ *
+ * ```ts
+ * await getHistory(address, { source: [heliusHistory({ apiKey }), rpcHistory()] })   // Helius 失败时用节点
+ * ```
+ */
+export function heliusHistory(options: HeliusHistoryOptions): HistorySource {
+  if (!options.apiKey) throw new Error('heliusHistory needs an apiKey')
+  const base = (options.baseUrl ?? 'https://api.helius.xyz').replace(/\/+$/, '')
+  return {
+    name: 'helius',
+    async getHistory(ctx) {
+      const items: Activity[] = []
+      let cursor = ctx.cursor
+      let more = true
+      for (let page = 0; page < (ctx.types ? 4 : 1) && items.length < ctx.limit && more; page++) {
+        const url = `${base}/v0/addresses/${ctx.address}/transactions?api-key=${encodeURIComponent(options.apiKey)}&limit=${Math.min(100, ctx.limit)}${cursor ? `&before=${encodeURIComponent(cursor)}` : ''}`
+        const res = await ctx.fetch(url, { signal: ctx.signal })
+        if (!res.ok) throw new Error(`HTTP ${res.status}`)
+        const raw = (await res.json()) as HeliusItem[]
+        if (!Array.isArray(raw)) throw new Error('Unexpected response')
+        more = raw.length >= Math.min(100, ctx.limit)
+        for (const item of raw) {
+          cursor = item.signature
+          const t = item.timestamp ?? 0
+          if (ctx.before !== undefined && t >= ctx.before) continue
+          if (ctx.after !== undefined && t < ctx.after) {
+            more = false
+            break
+          }
+          const activity = activityFromHelius(ctx.address, item)
+          if (!ctx.types || ctx.types.includes(activity.type)) items.push(activity)
+          if (items.length >= ctx.limit) break
+        }
+      }
+      return { items, ...(more && cursor ? { nextCursor: cursor } : {}) }
+    },
+  }
+}

package/src/index.ts

@@ -6,6 +6,7 @@ export {
   type AccountsOptions,
   type BalanceQuery,
   type BalancesOptions,
+  type BalancesQueryOptions,
   type ClientConfig,
   type OwnerTokensOptions,
   type PersistTokenMetaOptions,
@@ -64,7 +65,17 @@ export {
   clusterOfGenesis,
   type Cluster,
 } from './constants.js'
-export { createProgramAddress, decodeAddress, encodeAddress, findProgramAddress, getAssociatedTokenAddress, getMetadataAddress, isAddress, isOnCurve } from './address.js'
+export {
+  InvalidAddressError,
+  createProgramAddress,
+  decodeAddress,
+  encodeAddress,
+  findProgramAddress,
+  getAssociatedTokenAddress,
+  getMetadataAddress,
+  isAddress,
+  isOnCurve,
+} from './address.js'
 export {
   formatAmount,
   formatUnits,
@@ -94,6 +105,7 @@ export {
   type FallbackOptions,
   type HttpRpcOptions,
   type RequestEvent,
+  type RpcRequestOptions,
   type RpcTransport,
 } from './rpc.js'
 export { NetworkCheckedRpc, NetworkMismatchError, type RpcSource, type SourceOptions } from './source.js'

package/src/layout.ts

@@ -1,4 +1,4 @@
-import { encodeAddress } from './address.js'
+import { Bytes } from './bytes.js'
 
 /** getMultipleAccounts 解析后的账户 */
 export interface AccountInfo {
@@ -10,80 +10,6 @@ export interface AccountInfo {
   executable: boolean
 }
 
-class Reader {
-  #offset: number
-  readonly #view: DataView
-
-  constructor(
-    readonly bytes: Uint8Array,
-    offset = 0,
-  ) {
-    this.#offset = offset
-    this.#view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
-  }
-
-  get offset(): number {
-    return this.#offset
-  }
-
-  #need(n: number): void {
-    if (this.#offset + n > this.bytes.length) {
-      throw new RangeError('Account data is shorter than expected')
-    }
-  }
-
-  skip(n: number): void {
-    this.#need(n)
-    this.#offset += n
-  }
-
-  u8(): number {
-    this.#need(1)
-    return this.bytes[this.#offset++] as number
-  }
-
-  u16(): number {
-    this.#need(2)
-    const v = this.#view.getUint16(this.#offset, true)
-    this.#offset += 2
-    return v
-  }
-
-  u32(): number {
-    this.#need(4)
-    const v = this.#view.getUint32(this.#offset, true)
-    this.#offset += 4
-    return v
-  }
-
-  u64(): bigint {
-    this.#need(8)
-    const v = this.#view.getBigUint64(this.#offset, true)
-    this.#offset += 8
-    return v
-  }
-
-  pubkey(): string {
-    this.#need(32)
-    const v = encodeAddress(this.bytes.slice(this.#offset, this.#offset + 32))
-    this.#offset += 32
-    return v
-  }
-
-  /** borsh string：u32 长度 + UTF-8；去掉 Metaplex 用来补齐长度的 \0 */
-  string(): string {
-    const len = this.u32()
-    this.#need(len)
-    const v = new TextDecoder().decode(this.bytes.slice(this.#offset, this.#offset + len))
-    this.#offset += len
-    return v.replace(/\0+$/, '').trim()
-  }
-
-  option<T>(read: () => T): T | null {
-    return this.u8() === 1 ? read() : null
-  }
-}
-
 export interface MintInfo {
   mintAuthority: string | null
   supply: bigint
@@ -116,7 +42,7 @@ export function parseMint(data: Uint8Array): MintInfo {
   if (data.length !== MINT_SIZE && !(data.length > ACCOUNT_TYPE_OFFSET && data[ACCOUNT_TYPE_OFFSET] === ACCOUNT_TYPE_MINT)) {
     throw new RangeError('Not a mint account')
   }
-  const r = new Reader(data)
+  const r = new Bytes(data)
   const hasMintAuthority = r.u32() === 1
   const mintAuthority = r.pubkey()
   const supply = r.u64()
@@ -140,7 +66,7 @@ export function findExtension(data: Uint8Array, extensionType: number): Uint8Arr
     return null
   }
   try {
-    const r = new Reader(data, EXTENSIONS_OFFSET)
+    const r = new Bytes(data, EXTENSIONS_OFFSET)
     while (r.offset + 4 <= data.length) {
       const type = r.u16()
       const length = r.u16()
@@ -167,7 +93,7 @@ function parseTokenMetadataExtension(data: Uint8Array): TokenMetadata | null {
     return null
   }
   try {
-    const m = new Reader(ext)
+    const m = new Bytes(ext)
     m.pubkey() // updateAuthority
     m.pubkey() // mint
     return { name: m.string(), symbol: m.string(), uri: m.string() }
@@ -212,7 +138,7 @@ export function parseTransferFeeConfig(data: Uint8Array): TransferFeeConfigInfo
     return null
   }
   try {
-    const r = new Reader(ext)
+    const r = new Bytes(ext)
     // OptionalNonZeroPubkey：全 0 表示没有
     const configAuthority = r.pubkey()
     const withdrawAuthority = r.pubkey()
@@ -238,15 +164,70 @@ export interface TokenAccountInfo {
   amount: bigint
 }
 
+function isTokenAccountData(data: Uint8Array): boolean {
+  return data.length === ACCOUNT_SIZE || (data.length > ACCOUNT_TYPE_OFFSET && data[ACCOUNT_TYPE_OFFSET] === ACCOUNT_TYPE_ACCOUNT)
+}
+
 /** 解析代币账户（SPL Token / Token-2022 前 72 字节相同） */
 export function parseTokenAccount(data: Uint8Array): TokenAccountInfo {
-  if (data.length !== ACCOUNT_SIZE && !(data.length > ACCOUNT_TYPE_OFFSET && data[ACCOUNT_TYPE_OFFSET] === ACCOUNT_TYPE_ACCOUNT)) {
+  if (!isTokenAccountData(data)) {
     throw new RangeError('Not a token account')
   }
-  const r = new Reader(data)
+  const r = new Bytes(data)
   return { mint: r.pubkey(), owner: r.pubkey(), amount: r.u64() }
 }
 
+/** 代币账户的完整基础布局（前 165 字节，SPL Token / Token-2022 相同） */
+export interface TokenAccountState extends TokenAccountInfo {
+  delegate: string | null
+  /** 0 未初始化、1 正常、2 冻结 */
+  state: number
+  frozen: boolean
+  /** Wrapped SOL 账户（is_native 有值） */
+  native: boolean
+  delegatedAmount: bigint
+  closeAuthority: string | null
+}
+
+/** 解析代币账户的完整基础布局；不是代币账户或未初始化时为 null（包内使用：/approvals、/simulate） */
+export function parseTokenAccountState(data: Uint8Array): TokenAccountState | null {
+  if (!isTokenAccountData(data)) {
+    return null
+  }
+  const b = new Bytes(data)
+  const state = b.u8(108)
+  if (state === 0) {
+    return null
+  }
+  // COption：u32 标记（1 有、0 没有）+ 值
+  return {
+    mint: b.key(0),
+    owner: b.key(32),
+    amount: b.u64(64),
+    delegate: b.u32(72) === 1 ? b.key(76) : null,
+    state,
+    frozen: state === 2,
+    native: b.u32(109) === 1,
+    delegatedAmount: b.u64(121),
+    closeAuthority: b.u32(129) === 1 ? b.key(133) : null,
+  }
+}
+
+/** 计算预算指令里的计算单元上限（SetComputeUnitLimit）和单价（SetComputeUnitPrice，micro-lamports）；没有时 limit 为 null、price 为 0 */
+export function computeBudgetOf(instructions: Iterable<{ programId: string; data: Uint8Array }>): { limit: number | null; price: bigint } {
+  let limit: number | null = null
+  let price = 0n
+  for (const ix of instructions) {
+    if (ix.programId !== COMPUTE_BUDGET_PROGRAM) continue
+    const b = new Bytes(ix.data)
+    if (ix.data[0] === 2 && ix.data.length >= 5) limit = b.u32(1)
+    if (ix.data[0] === 3 && ix.data.length >= 9) price = b.u64(1)
+  }
+  return { limit, price }
+}
+
+const COMPUTE_BUDGET_PROGRAM = 'ComputeBudget111111111111111111111111111111'
+
 export interface MetaplexMetadata extends TokenMetadata {
   updateAuthority: string
   mint: string
@@ -261,7 +242,7 @@ export interface MetaplexMetadata extends TokenMetadata {
 
 /** 解析 Metaplex Token Metadata 账户；老版本账户缺少后面的字段时，缺的部分为默认值 */
 export function parseMetaplexMetadata(data: Uint8Array): MetaplexMetadata {
-  const r = new Reader(data)
+  const r = new Bytes(data)
   if (r.u8() !== 4) {
     throw new RangeError('Not a Metaplex metadata account') // Key::MetadataV1 = 4
   }

package/src/liquidity/common.ts

@@ -1,6 +1,6 @@
 import { sha256 } from '@noble/hashes/sha2.js'
 
-import { encodeAddress, getAssociatedTokenAddress, isAddress } from '../address.js'
+import { encodeAddress, getAssociatedTokenAddress, InvalidAddressError, isAddress } from '../address.js'
 import type { SolanaClient } from '../client.js'
 import { NATIVE_MINT, SYSTEM_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID } from '../constants.js'
 import { formatUnits, parseMint, parseTokenAccount, parseTransferFeeConfig, parseUnits, type AccountInfo } from '../layout.js'
@@ -25,7 +25,7 @@ export interface Ctx {
 export function createCtx(client: SolanaClient, owner: string, options: SolanaLiquidityOptions): Ctx {
   for (const address of [owner, options.recipient ?? owner]) {
     if (!isAddress(address)) {
-      throw new Error(`Invalid address: ${address}`)
+      throw new InvalidAddressError(`Invalid address: ${address}`, address)
     }
   }
   const slippage = options.slippage ?? 0.005

package/src/liquidity/orca.ts

@@ -223,6 +223,20 @@ export async function orcaAdd(ctx: Ctx, params: SolanaIncreaseLiquidityParams |
   })
 }
 
+/**
+ * 关闭已清空的仓位（流动性、手续费、奖励都为 0）：销毁仓位 NFT、关闭仓位账户和 NFT 的代币账户（nftAccount，默认 owner 的 ATA），租金退给 receiver。
+ * NFT 是 Token-2022（带元数据扩展）时连 mint 一起关闭，否则（Metaplex 时代的 SPL Token NFT）mint 留着
+ */
+export function orcaClosePosition(owner: string, receiver: string, positionMint: string, nftProgram: string, nftAccount = getAssociatedTokenAddress(owner, positionMint, nftProgram)): Instruction {
+  const position = positionAddress(positionMint)
+  const token2022 = nftProgram === TOKEN_2022_PROGRAM_ID
+  return {
+    programId: PROGRAM,
+    keys: [r(owner, true), w(receiver), w(position), w(positionMint), w(nftAccount), r(nftProgram)],
+    data: anchorIx(token2022 ? 'close_position_with_token_extensions' : 'close_position'),
+  }
+}
+
 /** 移除（decrease + 领取手续费和奖励）/ 只领取（collectOnly） */
 export async function orcaRemove(ctx: Ctx, params: SolanaRemoveLiquidityParams, collectOnly = false): Promise<SolanaLiquidityPlan> {
   const mint = refMint(params.position)
@@ -304,11 +318,7 @@ export async function orcaRemove(ctx: Ctx, params: SolanaRemoveLiquidityParams,
     })
   })
   if (burn) {
-    main.push(
-      nftProgram === TOKEN_2022_PROGRAM_ID
-        ? { programId: PROGRAM, keys: [r(ctx.owner, true), w(ctx.owner), w(positionAccount), w(mint), w(nftAccount), r(TOKEN_2022_PROGRAM_ID)], data: anchorIx('close_position_with_token_extensions') }
-        : { programId: PROGRAM, keys: [r(ctx.owner, true), w(ctx.owner), w(positionAccount), w(mint), w(nftAccount), r(TOKEN_PROGRAM_ID)], data: anchorIx('close_position') },
-    )
+    main.push(orcaClosePosition(ctx.owner, ctx.owner, mint, nftProgram))
   }
   return makePlan(ctx, {
     action: collectOnly ? 'collect' : 'remove',

package/src/liquidity/raydiumClmm.ts

@@ -249,6 +249,18 @@ export async function raydiumAdd(ctx: Ctx, params: SolanaIncreaseLiquidityParams
   })
 }
 
+/**
+ * 关闭已清空的仓位（流动性、手续费、奖励都为 0）：销毁仓位 NFT、关闭 NFT 的代币账户和仓位账户，租金退给 owner（程序固定，不能指定别人）。
+ * pool 是仓位所在的池子（官方 SDK 也带着它）
+ */
+export function raydiumClosePosition(owner: string, positionMint: string, nftProgram: string, pool: string, nftAccount = getAssociatedTokenAddress(owner, positionMint, nftProgram)): Instruction {
+  return {
+    programId: PROGRAM,
+    keys: [w(owner, true), w(positionMint), w(nftAccount), w(personalPositionAddress(positionMint)), r(SYSTEM_PROGRAM_ID), r(nftProgram), w(pool)],
+    data: anchorIx('close_position'),
+  }
+}
+
 /** 移除（liquidity > 0）/ 只领取手续费和奖励（collectOnly：流动性为 0 的 decrease） */
 export async function raydiumRemove(ctx: Ctx, params: SolanaRemoveLiquidityParams, collectOnly = false): Promise<SolanaLiquidityPlan> {
   const mint = refMint(params.position)
@@ -308,11 +320,7 @@ export async function raydiumRemove(ctx: Ctx, params: SolanaRemoveLiquidityParam
   }
   const main: Instruction[] = [decrease]
   if (burn) {
-    main.push({
-      programId: PROGRAM,
-      keys: [w(ctx.owner, true), w(mint), w(nftAta), w(personal), r(SYSTEM_PROGRAM_ID), r(nftProgram), w(pool.address)],
-      data: anchorIx('close_position'),
-    })
+    main.push(raydiumClosePosition(ctx.owner, mint, nftProgram, pool.address))
   }
   return makePlan(ctx, {
     action: collectOnly ? 'collect' : 'remove',