@oobe-protocol-labs/synapse-sap-sdk 0.4.1 → 0.4.2

package/src/parser/transaction.ts

@@ -0,0 +1,200 @@
+/**
+ * @module parser/transaction
+ * @description Decode SAP instruction names from a raw `TransactionResponse`.
+ *
+ * This is "Case 2A": you have a transaction response object obtained
+ * from `connection.getTransaction(signature, ...)` and need to extract
+ * the SAP instruction names, arguments, and account keys.
+ *
+ * The function handles both legacy and versioned (v0) transactions
+ * by decompiling the message into `TransactionInstruction[]` and then
+ * filtering for instructions whose `programId` matches the SAP program.
+ *
+ * @category Parser
+ * @since v0.5.0
+ *
+ * @example
+ * ```ts
+ * import { parseSapInstructionsFromTransaction } from "@synapse-sap/sdk/parser";
+ * import { SAP_PROGRAM_ID } from "@synapse-sap/sdk";
+ *
+ * const tx = await connection.getTransaction(sig, {
+ *   commitment: "confirmed",
+ *   maxSupportedTransactionVersion: 0,
+ * });
+ * if (!tx) throw new Error("Transaction not found");
+ *
+ * const decoded = parseSapInstructionsFromTransaction(
+ *   tx,
+ *   program.coder.instruction,
+ *   SAP_PROGRAM_ID,
+ * );
+ * for (const ix of decoded) {
+ *   console.log(ix.name, ix.args);
+ * }
+ * ```
+ */
+
+import {
+  TransactionMessage,
+  AddressLookupTableAccount,
+  type PublicKey,
+  type TransactionInstruction,
+  type VersionedTransactionResponse,
+  type TransactionResponse,
+} from "@solana/web3.js";
+import type { DecodedSapInstruction, SapInstructionCoder } from "./types";
+
+// ================================================================
+//  Public API
+// ================================================================
+
+/**
+ * Extract and decode SAP instructions from a transaction response.
+ *
+ * Supports both legacy (`TransactionResponse`) and versioned
+ * (`VersionedTransactionResponse`) formats. For versioned
+ * transactions that use address lookup tables, pass the resolved
+ * lookup table accounts so that `TransactionMessage.decompile`
+ * can reconstruct the full account list.
+ *
+ * @param tx - The transaction response from `connection.getTransaction`.
+ * @param coder - An Anchor instruction coder built from the SAP IDL.
+ * @param sapProgramId - The SAP program public key to filter by.
+ * @param addressLookupTables - Resolved lookup table accounts for v0 transactions.
+ *   Required when the transaction uses address lookup tables; omit for legacy txs.
+ * @returns An array of decoded SAP instructions found in the transaction.
+ *
+ * @throws {Error} When the transaction message cannot be decompiled.
+ *
+ * @category Parser
+ * @since v0.5.0
+ */
+export function parseSapInstructionsFromTransaction(
+  tx: TransactionResponse | VersionedTransactionResponse,
+  coder: SapInstructionCoder,
+  sapProgramId: PublicKey,
+  addressLookupTables?: AddressLookupTableAccount[],
+): DecodedSapInstruction[] {
+  const instructions = decompileTransaction(tx, addressLookupTables);
+  return decodeSapInstructions(instructions, coder, sapProgramId);
+}
+
+/**
+ * Extract only the SAP instruction names from a transaction response.
+ *
+ * Lighter-weight alternative to {@link parseSapInstructionsFromTransaction}
+ * when you only need the instruction names without decoded arguments.
+ *
+ * @param tx - The transaction response.
+ * @param coder - An Anchor instruction coder built from the SAP IDL.
+ * @param sapProgramId - The SAP program public key.
+ * @param addressLookupTables - Resolved lookup table accounts for v0 transactions.
+ * @returns An array of instruction name strings.
+ *
+ * @category Parser
+ * @since v0.5.0
+ */
+export function parseSapInstructionNamesFromTransaction(
+  tx: TransactionResponse | VersionedTransactionResponse,
+  coder: SapInstructionCoder,
+  sapProgramId: PublicKey,
+  addressLookupTables?: AddressLookupTableAccount[],
+): string[] {
+  return parseSapInstructionsFromTransaction(
+    tx,
+    coder,
+    sapProgramId,
+    addressLookupTables,
+  ).map((ix) => ix.name);
+}
+
+// ================================================================
+//  Internal helpers
+// ================================================================
+
+/**
+ * Decompile a transaction response into an array of `TransactionInstruction`.
+ *
+ * Handles both legacy messages (which already contain full account keys)
+ * and versioned v0 messages (which require address lookup table resolution).
+ *
+ * @internal
+ */
+function decompileTransaction(
+  tx: TransactionResponse | VersionedTransactionResponse,
+  addressLookupTables?: AddressLookupTableAccount[],
+): TransactionInstruction[] {
+  const message = tx.transaction.message;
+
+  // Versioned transactions expose `version` on the response object.
+  // Legacy transactions have either `version = "legacy"` or no field at all.
+  const isVersioned =
+    "version" in tx && tx.version !== undefined && tx.version !== "legacy";
+
+  if (isVersioned) {
+    // VersionedMessage requires decompile with optional lookup tables
+    const decompiledMessage = TransactionMessage.decompile(
+      message as import("@solana/web3.js").VersionedMessage,
+      addressLookupTables?.length
+        ? { addressLookupTableAccounts: addressLookupTables }
+        : undefined,
+    );
+    return decompiledMessage.instructions;
+  }
+
+  // Legacy message: decompile directly
+  const decompiledMessage = TransactionMessage.decompile(
+    message as import("@solana/web3.js").VersionedMessage,
+  );
+  return decompiledMessage.instructions;
+}
+
+/**
+ * Decode a list of raw `TransactionInstruction` into typed SAP results.
+ *
+ * Filters for instructions whose `programId` matches the SAP program,
+ * then runs each through the Anchor instruction coder.
+ *
+ * @internal
+ */
+function decodeSapInstructions(
+  instructions: TransactionInstruction[],
+  coder: SapInstructionCoder,
+  sapProgramId: PublicKey,
+): DecodedSapInstruction[] {
+  const results: DecodedSapInstruction[] = [];
+
+  for (const ix of instructions) {
+    if (!ix.programId.equals(sapProgramId)) continue;
+
+    const decoded = safeDecodeInstruction(coder, ix.data);
+    results.push({
+      name: decoded?.name ?? "unknown",
+      args: decoded?.data ?? null,
+      accounts: ix.keys.map((k) => k.pubkey),
+      raw: ix,
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Attempt to decode instruction data, returning `null` on failure
+ * instead of throwing. This prevents a single malformed instruction
+ * from breaking the entire parse pipeline.
+ *
+ * @internal
+ */
+function safeDecodeInstruction(
+  coder: SapInstructionCoder,
+  data: Buffer | Uint8Array,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): { name: string; data: Record<string, any> } | null {
+  try {
+    return coder.decode(Buffer.from(data));
+  } catch {
+    return null;
+  }
+}

package/src/parser/types.ts

@@ -0,0 +1,182 @@
+/**
+ * @module parser/types
+ * @description Type definitions for SAP v2 transaction parsing.
+ *
+ * Provides strongly-typed interfaces for decoded instruction data,
+ * account metadata, inner (CPI) instructions, and the full parsed
+ * transaction result used by indexers and explorers.
+ *
+ * @category Parser
+ * @since v0.5.0
+ */
+
+import type { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import type { ParsedEvent, SapEventName } from "../events";
+
+// ================================================================
+//  Decoded Instruction
+// ================================================================
+
+/**
+ * A single SAP instruction decoded from on-chain transaction data.
+ *
+ * Contains the human-readable instruction name (as declared in the
+ * Anchor IDL), the decoded argument object, the ordered list of
+ * account keys, and the raw instruction for advanced consumers.
+ *
+ * @interface DecodedSapInstruction
+ * @category Parser
+ * @since v0.5.0
+ */
+export interface DecodedSapInstruction {
+  /** Instruction name matching the Anchor IDL method (e.g. `"registerAgent"`). */
+  readonly name: string;
+  /**
+   * Decoded arguments object. Keys match the Anchor IDL argument names.
+   * Returns `null` when decoding fails (e.g. IDL mismatch).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly args: Record<string, any> | null;
+  /** Ordered list of account public keys passed to the instruction. */
+  readonly accounts: PublicKey[];
+  /** The original `TransactionInstruction`, useful for re-simulation or forwarding. */
+  readonly raw: TransactionInstruction;
+}
+
+// ================================================================
+//  Inner (CPI) Instruction
+// ================================================================
+
+/**
+ * An inner instruction produced by cross-program invocation (CPI)
+ * within a SAP transaction.
+ *
+ * Inner instructions are indexed by the outer instruction position
+ * that triggered them. Each entry includes the decoded SAP name
+ * when the inner call targets the SAP program, or `null` otherwise.
+ *
+ * @interface DecodedInnerInstruction
+ * @category Parser
+ * @since v0.5.0
+ */
+export interface DecodedInnerInstruction {
+  /** Zero-based index of the outer instruction that triggered this CPI call. */
+  readonly outerIndex: number;
+  /** Zero-based position within the inner instruction set of the parent. */
+  readonly innerIndex: number;
+  /** SAP instruction name if the CPI targets the SAP program, `null` otherwise. */
+  readonly name: string | null;
+  /** Decoded arguments when the CPI targets SAP and decoding succeeds. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly args: Record<string, any> | null;
+  /** Ordered account keys for this inner instruction. */
+  readonly accounts: PublicKey[];
+  /** The program that was invoked by this inner call. */
+  readonly programId: PublicKey;
+}
+
+// ================================================================
+//  Parsed Transaction (complete result)
+// ================================================================
+
+/**
+ * Full parse result for a single SAP transaction.
+ *
+ * Combines top-level instruction decoding, inner instruction
+ * analysis, and event extraction into one unified structure
+ * suitable for indexing, analytics dashboards, and protocol
+ * explorers.
+ *
+ * @interface ParsedSapTransaction
+ * @category Parser
+ * @since v0.5.0
+ *
+ * @example
+ * ```ts
+ * const result = parseSapTransactionComplete(tx, program, SAP_PROGRAM_ID);
+ * for (const ix of result.instructions) {
+ *   console.log(ix.name, ix.args);
+ * }
+ * for (const event of result.events) {
+ *   console.log(event.name, event.data);
+ * }
+ * ```
+ */
+export interface ParsedSapTransaction {
+  /** Transaction signature (base-58), extracted from the response when available. */
+  readonly signature: string | null;
+  /** Slot at which the transaction was confirmed. */
+  readonly slot: number | null;
+  /** Block timestamp (unix seconds) or `null` if unavailable. */
+  readonly blockTime: number | null;
+  /** Whether the transaction succeeded (`true`) or failed. */
+  readonly success: boolean;
+  /** Top-level SAP instructions found in the transaction. */
+  readonly instructions: DecodedSapInstruction[];
+  /** All inner (CPI) instructions, including non-SAP programs. */
+  readonly innerInstructions: DecodedInnerInstruction[];
+  /** Decoded SAP events extracted from the transaction logs. */
+  readonly events: ParsedEvent[];
+  /** Raw log lines from the transaction, for additional debugging. */
+  readonly logs: string[];
+}
+
+// ================================================================
+//  Filter helpers
+// ================================================================
+
+/**
+ * Options for filtering parsed instruction results.
+ *
+ * @interface ParseFilterOptions
+ * @category Parser
+ * @since v0.5.0
+ */
+export interface ParseFilterOptions {
+  /**
+   * When `true`, include inner (CPI) instructions in the parse
+   * result. Defaults to `false` because inner instruction
+   * reconstruction requires additional account-table lookups.
+   */
+  readonly includeInner?: boolean;
+  /**
+   * When `true`, decode and attach SAP events from the
+   * transaction logs. Defaults to `true`.
+   */
+  readonly includeEvents?: boolean;
+  /**
+   * Restrict the result to instructions matching one of these
+   * names. When `undefined` or empty, all SAP instructions are
+   * returned.
+   */
+  readonly instructionFilter?: string[];
+  /**
+   * Restrict events to those matching one of these names.
+   * When `undefined` or empty, all events are returned.
+   */
+  readonly eventFilter?: SapEventName[];
+}
+
+// ================================================================
+//  Coder interface (minimal contract)
+// ================================================================
+
+/**
+ * Minimal interface for the Anchor instruction coder.
+ *
+ * Extracted so that parser functions can accept either a full
+ * `Program` instance or a standalone coder/IDL pair without
+ * requiring a live RPC connection.
+ *
+ * @interface SapInstructionCoder
+ * @category Parser
+ * @since v0.5.0
+ */
+export interface SapInstructionCoder {
+  /** Decode raw instruction data into a name and typed argument object. */
+  decode(
+    data: Buffer | Uint8Array,
+    encoding?: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): { name: string; data: Record<string, any> } | null;
+}