@w3lib/solana-batch-call 0.5.0 → 0.7.0

package/src/write/errors.ts

@@ -0,0 +1,82 @@
+import { SYSTEM_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID } from '../constants.js'
+
+// 交易错误的可读说明（发送、/swap 的交易检查、/fees 共用）
+
+export function errorText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+// ---- 交易错误 ----
+
+const TX_ERRORS: Record<string, string> = {
+  InsufficientFundsForFee: 'insufficient SOL for the transaction fee',
+  AccountNotFound: 'fee payer account not found (it has no SOL)',
+  BlockhashNotFound: 'blockhash not found',
+  AlreadyProcessed: 'transaction already processed',
+}
+
+/**
+ * 日志里最有用的一行：程序打印的 “Program log: Error: …”，其次是系统程序直接打印的说明（如 “Transfer: insufficient lamports …”，
+ * 不以 “Program ” 开头），最后才是运行时的 “Program … failed: custom program error: 0x1”
+ */
+function logDetail(logs: readonly string[]): string | undefined {
+  const reversed = [...logs].reverse()
+  const programError = reversed.find((line) => /^Program log: (Error|error)/.test(line))
+  if (programError) return programError.replace(/^Program log: /, '')
+  const plain = reversed.find((line) => !line.startsWith('Program '))
+  if (plain) return plain
+  return reversed.find((line) => / failed: /.test(line))?.replace(/^Program \w+ failed: /, '')
+}
+
+// 常见程序的自定义错误码（上链失败时没有日志，只有错误码）
+const SYSTEM_ERRORS = ['account already in use', 'insufficient lamports', 'invalid program id', 'invalid account data length']
+const TOKEN_ERRORS: Record<number, string> = {
+  0: 'account not rent-exempt',
+  1: 'insufficient funds',
+  2: 'invalid mint',
+  3: 'account not associated with this mint',
+  4: 'owner does not match',
+  9: 'account is not initialized',
+  11: 'non-native account can only be closed if its balance is zero',
+  17: 'account is frozen',
+  18: 'mint decimals mismatch',
+}
+
+function customErrorText(program: string | undefined, code: number): string | undefined {
+  if (program === SYSTEM_PROGRAM_ID) return SYSTEM_ERRORS[code]
+  if (program === TOKEN_PROGRAM_ID || program === TOKEN_2022_PROGRAM_ID) return TOKEN_ERRORS[code]
+  return undefined
+}
+
+/**
+ * 交易错误的可读说明：优先取日志（见 logDetail），否则按错误类型；
+ * programs 是每条指令的程序（按下标），用来翻译常见程序的自定义错误码
+ */
+export function transactionErrorText(err: unknown, logs?: readonly string[] | null, programs?: readonly string[]): string {
+  const detail = logDetail(logs ?? [])
+  if (typeof err === 'string') {
+    return TX_ERRORS[err] ?? err
+  }
+  const instruction = (err as { InstructionError?: [number, unknown] } | null)?.InstructionError
+  if (instruction) {
+    const [index, reason] = instruction
+    const custom = (reason as { Custom?: number } | null)?.Custom
+    const known = custom === undefined ? undefined : customErrorText(programs?.[index], custom)
+    return detail ?? known ?? (typeof reason === 'string' ? reason : JSON.stringify(reason))
+  }
+  if ((err as { InsufficientFundsForRent?: unknown } | null)?.InsufficientFundsForRent) {
+    return 'account would be left with less SOL than the rent-exempt minimum'
+  }
+  return detail ?? JSON.stringify(err)
+}
+
+export function isBudgetExceeded(err: unknown, logs?: readonly string[] | null): boolean {
+  const reason = (err as { InstructionError?: [number, unknown] } | null)?.InstructionError?.[1]
+  return reason === 'ComputationalBudgetExceeded' || (logs ?? []).some((l) => /exceeded CUs meter|compute units/i.test(l) && /exceed/i.test(l))
+}
+
+/** 用户在钱包里拒绝签名 */
+export function isRejection(err: unknown): boolean {
+  const e = err as { code?: unknown; name?: unknown; message?: unknown } | null
+  return e?.code === 4001 || /reject|denied|cancel|declined/i.test(`${String(e?.name ?? '')} ${String(e?.message ?? '')}`)
+}

package/src/write/instructions.ts

@@ -74,6 +74,23 @@ export function closeAccount(account: string, destination: string, owner: string
   }
 }
 
+/** SPL Token / Token-2022 BurnChecked：销毁代币账户里的代币（校验 mint 和精度），owner 签名 */
+export function burnChecked(account: string, mint: string, owner: string, amount: bigint, decimals: number, tokenProgram: string): Instruction {
+  return {
+    programId: tokenProgram,
+    keys: [
+      { pubkey: account, isSigner: false, isWritable: true },
+      { pubkey: mint, isSigner: false, isWritable: true },
+      { pubkey: owner, isSigner: true, isWritable: false },
+    ],
+    data: bytes(10, (v) => {
+      v.setUint8(0, 15)
+      v.setBigUint64(1, amount, true)
+      v.setUint8(9, decimals)
+    }),
+  }
+}
+
 /** 撤销代币账户的授权（Approve 设置的 delegate），owner 签名 */
 export function revoke(account: string, owner: string, tokenProgram: string): Instruction {
   return {

package/src/write/pack.ts

@@ -0,0 +1,142 @@
+import { MAX_COMPUTE_UNITS, setComputeUnitLimit, setComputeUnitPrice } from './instructions.js'
+import { MAX_ACCOUNT_LOCKS, PACKET_DATA_SIZE, compileMessage, transactionSize, type Instruction } from './transaction.js'
+
+/** 打包用的占位 blockhash（大小与真实值相同） */
+export const PLACEHOLDER_BLOCKHASH = '11111111111111111111111111111111'
+
+/** 计算预算指令（上限 + 单价）：发送时排在最前面 */
+export function budgetInstructions(units: number, price: bigint): Instruction[] {
+  return [setComputeUnitLimit(units), setComputeUnitPrice(price)]
+}
+
+/** 加上计算预算指令后，这些指令能否放进一笔交易（完整编译一次；不超过 1232 字节和 64 个账户） */
+export function fitsInTransaction(payer: string, instructions: readonly Instruction[]): boolean {
+  const message = compileMessage(payer, [...budgetInstructions(MAX_COMPUTE_UNITS, 0n), ...instructions], PLACEHOLDER_BLOCKHASH)
+  return transactionSize(message) <= PACKET_DATA_SIZE && message.accountKeys.length <= MAX_ACCOUNT_LOCKS
+}
+
+function compactLength(n: number): number {
+  return n < 0x80 ? 1 : n < 0x4000 ? 2 : 3
+}
+
+/**
+ * 增量估算 legacy 交易的大小（与 compileMessage + transactionSize 的结果相同）：
+ * 签名数 + 64 × 签名数 + 3 字节头 + 账户数 + 32 × 账户数 + 32 字节 blockhash + 指令数 + 各指令（程序下标 1 + 账户数 + 账户下标 + 数据长度 + 数据）。
+ * 只记累计的账户集合（是否签名者）和指令字节，加一个调用只看它自己的指令
+ */
+class SizeEstimate {
+  /** 账户 → 是否签名者 */
+  readonly #signer = new Map<string, boolean>()
+  #signers = 0
+  #instructions = 0
+  #instructionBytes = 0
+
+  constructor(payer: string) {
+    this.#signer.set(payer, true)
+    this.#signers = 1
+    this.add(budgetInstructions(MAX_COMPUTE_UNITS, 0n))
+  }
+
+  /** 加入这些指令后的大小和账户数（不修改状态） */
+  probe(instructions: readonly Instruction[]): { size: number; accounts: number } {
+    let accounts = this.#signer.size
+    let signers = this.#signers
+    let bytes = this.#instructionBytes
+    const added = new Map<string, boolean>()
+    const touch = (pubkey: string, isSigner: boolean) => {
+      // 本次已经加过 / 升级过的以 added 为准（累计集合里是非签名者 false 时，?? 不会回落，不能先查累计集合）
+      const known = added.has(pubkey) ? added.get(pubkey) : this.#signer.get(pubkey)
+      if (known === undefined) {
+        accounts++
+        if (isSigner) signers++
+        added.set(pubkey, isSigner)
+      } else if (isSigner && !known) {
+        signers++
+        added.set(pubkey, true)
+      }
+    }
+    for (const ix of instructions) {
+      ix.keys.forEach((k) => touch(k.pubkey, k.isSigner))
+      touch(ix.programId, false)
+      bytes += 1 + compactLength(ix.keys.length) + ix.keys.length + compactLength(ix.data.length) + ix.data.length
+    }
+    const count = this.#instructions + instructions.length
+    const size = compactLength(signers) + 64 * signers + 3 + compactLength(accounts) + 32 * accounts + 32 + compactLength(count) + bytes
+    return { size, accounts }
+  }
+
+  fits(instructions: readonly Instruction[]): boolean {
+    const { size, accounts } = this.probe(instructions)
+    return size <= PACKET_DATA_SIZE && accounts <= MAX_ACCOUNT_LOCKS
+  }
+
+  add(instructions: readonly Instruction[]): void {
+    for (const ix of instructions) {
+      for (const k of [...ix.keys.map((key) => [key.pubkey, key.isSigner] as const), [ix.programId, false] as const]) {
+        const [pubkey, isSigner] = k
+        const known = this.#signer.get(pubkey)
+        if (known === undefined) {
+          this.#signer.set(pubkey, isSigner)
+          if (isSigner) this.#signers++
+        } else if (isSigner && !known) {
+          this.#signer.set(pubkey, true)
+          this.#signers++
+        }
+      }
+      this.#instructionBytes += 1 + compactLength(ix.keys.length) + ix.keys.length + compactLength(ix.data.length) + ix.data.length
+      this.#instructions++
+    }
+  }
+}
+
+export interface PackOptions {
+  /** 每笔交易最多几个调用，默认不限（只受交易大小 / 账户数限制） */
+  batchSize?: number
+  /** 只能单独成一笔交易的调用（如计算单元和优先费用固定的扫空转账） */
+  alone?: (index: number) => boolean
+}
+
+/** 打包结果的一笔交易：包含的调用下标；tooLarge 为 true 时是单个调用自己就放不进一笔交易 */
+export interface Pack {
+  indices: number[]
+  tooLarge: boolean
+}
+
+/**
+ * 把调用按顺序打包成交易（batchCall / batchTransfer / batchCollect 的发送和 /reclaim、/claim 的批量计划共用）：
+ * 相邻的调用放进同一笔，直到加上计算预算指令后超过 1232 字节或 64 个账户、或达到 batchSize；alone 的调用单独成一笔；
+ * 单个调用自己就放不进的单独成一笔并标记 tooLarge。
+ * 大小按累计的账户集合和指令字节增量估算（每加一个调用只看它自己的指令），每笔打完再完整编译校验一次
+ */
+export function packUnits(payer: string, units: ReadonlyArray<{ instructions: readonly Instruction[] }>, options: PackOptions = {}): Pack[] {
+  const batchSize = options.batchSize ?? Number.POSITIVE_INFINITY
+  const alone = options.alone ?? (() => false)
+  const packs: Pack[] = []
+  let i = 0
+  while (i < units.length) {
+    const estimate = new SizeEstimate(payer)
+    const first = (units[i] as { instructions: readonly Instruction[] }).instructions
+    if (!estimate.fits(first)) {
+      packs.push({ indices: [i], tooLarge: true })
+      i++
+      continue
+    }
+    estimate.add(first)
+    const indices = [i++]
+    if (!alone(indices[0] as number)) {
+      while (i < units.length && indices.length < batchSize && !alone(i)) {
+        const next = (units[i] as { instructions: readonly Instruction[] }).instructions
+        if (!estimate.fits(next)) break
+        estimate.add(next)
+        indices.push(i++)
+      }
+    }
+    // 完整编译校验一次（估算与编译结果应当一致；万一不一致，去掉末尾的调用直到放得下，去掉的留给下一笔）
+    while (indices.length > 1 && !fitsInTransaction(payer, indices.flatMap((k) => (units[k] as { instructions: readonly Instruction[] }).instructions))) {
+      indices.pop()
+      i--
+    }
+    packs.push({ indices, tooLarge: false })
+  }
+  return packs
+}