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

package/dist/types/parser/instructions.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @module parser/instructions
+ * @description Decode SAP instruction names from a pre-built `TransactionInstruction[]`.
+ *
+ * This is "Case 2B": you already have the decompiled instruction list
+ * (for example, from a UI that constructs instructions before sending)
+ * and want to identify which ones target the SAP program.
+ *
+ * @category Parser
+ * @since v0.5.0
+ *
+ * @example
+ * ```ts
+ * import { parseSapInstructionsFromList } from "@synapse-sap/sdk/parser";
+ * import { SAP_PROGRAM_ID } from "@synapse-sap/sdk";
+ *
+ * const decoded = parseSapInstructionsFromList(
+ *   instructions,
+ *   program.coder.instruction,
+ *   SAP_PROGRAM_ID,
+ * );
+ * for (const ix of decoded) {
+ *   console.log(ix.name, ix.args);
+ * }
+ * ```
+ */
+import type { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import type { DecodedSapInstruction, SapInstructionCoder } from "./types";
+/**
+ * Decode an array of `TransactionInstruction` and return only the
+ * SAP instructions with their decoded names and arguments.
+ *
+ * Non-SAP instructions (system, token, other programs) are silently
+ * skipped. Instructions whose data cannot be decoded against the IDL
+ * are still included with `name: "unknown"` and `args: null` so that
+ * consumers can detect IDL mismatches or unsupported instruction
+ * variants.
+ *
+ * @param instructions - The instruction array to inspect.
+ * @param coder - An Anchor instruction coder built from the SAP IDL.
+ * @param sapProgramId - The SAP program public key to filter by.
+ * @returns An array of decoded SAP instructions.
+ *
+ * @category Parser
+ * @since v0.5.0
+ */
+export declare function parseSapInstructionsFromList(instructions: TransactionInstruction[], coder: SapInstructionCoder, sapProgramId: PublicKey): DecodedSapInstruction[];
+/**
+ * Return only the instruction names for SAP instructions in the list.
+ *
+ * Convenience wrapper over {@link parseSapInstructionsFromList} for
+ * callers that only need the string names.
+ *
+ * @param instructions - The instruction array to inspect.
+ * @param coder - An Anchor instruction coder for the SAP IDL.
+ * @param sapProgramId - The SAP program public key.
+ * @returns An array of instruction name strings.
+ *
+ * @category Parser
+ * @since v0.5.0
+ */
+export declare function parseSapInstructionNamesFromList(instructions: TransactionInstruction[], coder: SapInstructionCoder, sapProgramId: PublicKey): string[];
+/**
+ * Check whether any instruction in the list targets the SAP program.
+ *
+ * Useful as a fast pre-filter before committing to a full decode pass.
+ *
+ * @param instructions - The instruction array to inspect.
+ * @param sapProgramId - The SAP program public key.
+ * @returns `true` if at least one instruction targets the SAP program.
+ *
+ * @category Parser
+ * @since v0.5.0
+ */
+export declare function containsSapInstruction(instructions: TransactionInstruction[], sapProgramId: PublicKey): boolean;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/types/parser/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../../src/parser/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAM1E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,4BAA4B,CAC1C,YAAY,EAAE,sBAAsB,EAAE,EACtC,KAAK,EAAE,mBAAmB,EAC1B,YAAY,EAAE,SAAS,GACtB,qBAAqB,EAAE,CAgBzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gCAAgC,CAC9C,YAAY,EAAE,sBAAsB,EAAE,EACtC,KAAK,EAAE,mBAAmB,EAC1B,YAAY,EAAE,SAAS,GACtB,MAAM,EAAE,CAIV;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,sBAAsB,EAAE,EACtC,YAAY,EAAE,SAAS,GACtB,OAAO,CAET"}

package/dist/types/parser/transaction.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @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 { AddressLookupTableAccount, type PublicKey, type VersionedTransactionResponse, type TransactionResponse } from "@solana/web3.js";
+import type { DecodedSapInstruction, SapInstructionCoder } from "./types";
+/**
+ * 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 declare function parseSapInstructionsFromTransaction(tx: TransactionResponse | VersionedTransactionResponse, coder: SapInstructionCoder, sapProgramId: PublicKey, addressLookupTables?: AddressLookupTableAccount[]): DecodedSapInstruction[];
+/**
+ * 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 declare function parseSapInstructionNamesFromTransaction(tx: TransactionResponse | VersionedTransactionResponse, coder: SapInstructionCoder, sapProgramId: PublicKey, addressLookupTables?: AddressLookupTableAccount[]): string[];
+//# sourceMappingURL=transaction.d.ts.map

package/dist/types/parser/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../../src/parser/transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAEL,yBAAyB,EACzB,KAAK,SAAS,EAEd,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,EACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAM1E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mCAAmC,CACjD,EAAE,EAAE,mBAAmB,GAAG,4BAA4B,EACtD,KAAK,EAAE,mBAAmB,EAC1B,YAAY,EAAE,SAAS,EACvB,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,qBAAqB,EAAE,CAGzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uCAAuC,CACrD,EAAE,EAAE,mBAAmB,GAAG,4BAA4B,EACtD,KAAK,EAAE,mBAAmB,EAC1B,YAAY,EAAE,SAAS,EACvB,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,MAAM,EAAE,CAOV"}

package/dist/types/parser/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @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";
+/**
+ * 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).
+     */
+    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;
+}
+/**
+ * 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. */
+    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;
+}
+/**
+ * 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[];
+}
+/**
+ * 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[];
+}
+/**
+ * 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): {
+        name: string;
+        data: Record<string, any>;
+    } | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/parser/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/parser/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAM3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IAEH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC;IAC/B,qFAAqF;IACrF,QAAQ,CAAC,GAAG,EAAE,sBAAsB,CAAC;CACtC;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,wEAAwE;IAExE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC1C,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,qBAAqB,EAAE,CAAC;IAC/C,gEAAgE;IAChE,QAAQ,CAAC,iBAAiB,EAAE,uBAAuB,EAAE,CAAC;IACtD,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;CACzB;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,YAAY,EAAE,CAAC;CACvC;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,MAAM,CACJ,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,QAAQ,CAAC,EAAE,MAAM,GAEhB;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;CACvD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/synapse-sap-sdk",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "TypeScript SDK for the Synapse Agent Protocol (SAP v2) on Solana",
   "license": "MIT",
   "main": "dist/cjs/index.js",
@@ -131,6 +131,11 @@
       "import": "./dist/esm/postgres/index.js",
       "require": "./dist/cjs/postgres/index.js",
       "types": "./dist/types/postgres/index.d.ts"
+    },
+    "./parser": {
+      "import": "./dist/esm/parser/index.js",
+      "require": "./dist/cjs/parser/index.js",
+      "types": "./dist/types/parser/index.d.ts"
     }
   },
   "files": [

package/src/core/client.ts

@@ -36,6 +36,7 @@ import { EscrowModule } from "../modules/escrow";
 import { AttestationModule } from "../modules/attestation";
 import { LedgerModule } from "../modules/ledger";
 import { EventParser } from "../events";
+import { TransactionParser } from "../parser/client";
 import { DiscoveryRegistry } from "../registries/discovery";
 import { X402Registry } from "../registries/x402";
 import { SessionManager } from "../registries/session";
@@ -116,6 +117,9 @@ export class SapClient {
   #ledger?: LedgerModule;
   #events?: EventParser;
 
+  // ── Lazy parser singleton ─────────────────────
+  #parser?: TransactionParser;
+
   // ── Lazy registry singletons ──────────────────────
   #discovery?: DiscoveryRegistry;
   #x402?: X402Registry;
@@ -318,6 +322,27 @@ export class SapClient {
     return (this.#events ??= new EventParser(this.program));
   }
 
+  /**
+   * @name parser
+   * @description Transaction parser: decode instruction names, arguments,
+   * accounts, inner CPI calls, and protocol events from raw transaction
+   * responses. Designed for indexers and explorers.
+   * @returns {TransactionParser} The lazily-instantiated `TransactionParser` singleton.
+   * @category Modules
+   * @since v0.5.0
+   * @see {@link TransactionParser}
+   *
+   * @example
+   * ```ts
+   * const tx = await connection.getTransaction(sig, { ... });
+   * const parsed = client.parser.parseTransaction(tx);
+   * console.log(parsed?.instructions.map(i => i.name));
+   * ```
+   */
+  get parser(): TransactionParser {
+    return (this.#parser ??= new TransactionParser(this.program));
+  }
+
   // ═════════════════════════════════════════════
   //  Registry Accessors (high-level abstractions)
   // ═════════════════════════════════════════════

package/src/index.ts

@@ -15,6 +15,7 @@
  * | `modules/`        | Low-level per-domain instruction wrappers     |
  * | `registries/`     | High-level abstractions (discovery, x402, …)  |
  * | `plugin/`         | SynapseAgentKit adapter (52 tools)            |
+ * | `parser/`         | Transaction decode, instruction + event parse |
  * | `idl/`            | Embedded Anchor IDL                           |
  *
  * @example
@@ -220,6 +221,30 @@ export type {
   SyncOptions,
 } from "./postgres";
 
+// ── Parser (transaction decode + instruction + events) ─
+export {
+  parseSapInstructionsFromTransaction,
+  parseSapInstructionNamesFromTransaction,
+  parseSapInstructionsFromList,
+  parseSapInstructionNamesFromList,
+  containsSapInstruction,
+  parseSapTransactionComplete,
+  parseSapTransactionBatch,
+  decodeInnerInstructions,
+  filterSapInnerInstructions,
+  extractAccountKeys,
+  TransactionParser,
+} from "./parser";
+export type {
+  DecodedSapInstruction,
+  DecodedInnerInstruction,
+  ParsedSapTransaction,
+  ParseFilterOptions,
+  SapInstructionCoder,
+  CompiledInner,
+  InnerInstructionGroup,
+} from "./parser";
+
 // ── Registries (high-level developer abstractions) ────
 export {
   DiscoveryRegistry,

package/src/parser/client.ts

@@ -0,0 +1,211 @@
+/**
+ * @module parser/client
+ * @description Object-oriented wrapper for transaction parsing.
+ *
+ * Binds the Anchor `Program` reference so callers do not need to
+ * pass it on every call. Designed as a lazy singleton accessible
+ * from {@link SapClient.parser}.
+ *
+ * @category Parser
+ * @since v0.5.0
+ *
+ * @example
+ * ```ts
+ * const client = SapClient.from(provider);
+ *
+ * // Parse a full transaction
+ * const parsed = client.parser.parseTransaction(txResponse);
+ *
+ * // Quick instruction names
+ * const names = client.parser.instructionNames(txResponse);
+ *
+ * // From pre-built instructions
+ * const decoded = client.parser.fromInstructions(ixList);
+ * ```
+ */
+
+import type { Program } from "@coral-xyz/anchor";
+import type {
+  PublicKey,
+  TransactionInstruction,
+  TransactionResponse,
+  VersionedTransactionResponse,
+} from "@solana/web3.js";
+import { AddressLookupTableAccount } from "@solana/web3.js";
+
+import type {
+  DecodedSapInstruction,
+  ParsedSapTransaction,
+  ParseFilterOptions,
+  SapInstructionCoder,
+} from "./types";
+import { parseSapInstructionsFromTransaction } from "./transaction";
+import { parseSapInstructionsFromList, containsSapInstruction } from "./instructions";
+import { parseSapTransactionComplete, parseSapTransactionBatch } from "./complete";
+import {
+  decodeInnerInstructions,
+  extractAccountKeys,
+  type InnerInstructionGroup,
+} from "./inner";
+
+/**
+ * Stateful transaction parser bound to a specific Anchor `Program`.
+ *
+ * Stores the program reference, instruction coder, and program ID
+ * internally so that repeated parse calls require only the
+ * transaction data as input.
+ *
+ * @name TransactionParser
+ * @category Parser
+ * @since v0.5.0
+ */
+export class TransactionParser {
+  private readonly coder: SapInstructionCoder;
+  private readonly programId: PublicKey;
+
+  /**
+   * Create a new TransactionParser.
+   *
+   * @param program - An Anchor `Program` built from the SAP IDL.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  constructor(private readonly program: Program<any>) {
+    this.coder = program.coder.instruction as unknown as SapInstructionCoder;
+    this.programId = program.programId;
+  }
+
+  /**
+   * Full parse: instructions + inner calls + events.
+   *
+   * @param tx - Raw transaction response from `connection.getTransaction`.
+   * @param options - Optional filters for instructions, events, and inner calls.
+   * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+   * @returns Complete parsed transaction, or `null` if the input is nullish.
+   *
+   * @since v0.5.0
+   */
+  parseTransaction(
+    tx: TransactionResponse | VersionedTransactionResponse | null | undefined,
+    options?: ParseFilterOptions,
+    addressLookupTables?: AddressLookupTableAccount[],
+  ): ParsedSapTransaction | null {
+    return parseSapTransactionComplete(
+      tx,
+      this.program,
+      this.programId,
+      options,
+      addressLookupTables,
+    );
+  }
+
+  /**
+   * Parse a batch of transactions.
+   *
+   * @param txs - Array of transaction responses (may contain `null` entries).
+   * @param options - Optional parse filters.
+   * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+   * @returns Non-null parsed transactions.
+   *
+   * @since v0.5.0
+   */
+  parseBatch(
+    txs: (TransactionResponse | VersionedTransactionResponse | null | undefined)[],
+    options?: ParseFilterOptions,
+    addressLookupTables?: AddressLookupTableAccount[],
+  ): ParsedSapTransaction[] {
+    return parseSapTransactionBatch(
+      txs,
+      this.program,
+      this.programId,
+      options,
+      addressLookupTables,
+    );
+  }
+
+  /**
+   * Decode top-level SAP instructions from a transaction response.
+   *
+   * @param tx - Raw transaction response.
+   * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+   * @returns Decoded SAP instructions.
+   *
+   * @since v0.5.0
+   */
+  instructionsFromTransaction(
+    tx: TransactionResponse | VersionedTransactionResponse,
+    addressLookupTables?: AddressLookupTableAccount[],
+  ): DecodedSapInstruction[] {
+    return parseSapInstructionsFromTransaction(
+      tx,
+      this.coder,
+      this.programId,
+      addressLookupTables,
+    );
+  }
+
+  /**
+   * Extract only the instruction names from a transaction response.
+   *
+   * @param tx - Raw transaction response.
+   * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+   * @returns Instruction name strings.
+   *
+   * @since v0.5.0
+   */
+  instructionNames(
+    tx: TransactionResponse | VersionedTransactionResponse,
+    addressLookupTables?: AddressLookupTableAccount[],
+  ): string[] {
+    return this.instructionsFromTransaction(tx, addressLookupTables).map(
+      (ix) => ix.name,
+    );
+  }
+
+  /**
+   * Decode SAP instructions from a pre-built instruction array.
+   *
+   * @param instructions - The instruction list to decode.
+   * @returns Decoded SAP instructions.
+   *
+   * @since v0.5.0
+   */
+  fromInstructions(
+    instructions: TransactionInstruction[],
+  ): DecodedSapInstruction[] {
+    return parseSapInstructionsFromList(instructions, this.coder, this.programId);
+  }
+
+  /**
+   * Check if any instruction in the list targets the SAP program.
+   *
+   * @param instructions - The instruction array to inspect.
+   * @returns `true` if at least one instruction targets SAP.
+   *
+   * @since v0.5.0
+   */
+  isSapTransaction(instructions: TransactionInstruction[]): boolean {
+    return containsSapInstruction(instructions, this.programId);
+  }
+
+  /**
+   * Decode inner (CPI) instructions from transaction metadata.
+   *
+   * @param innerGroups - The `tx.meta.innerInstructions` array.
+   * @param tx - The transaction response (for account key resolution).
+   * @returns Decoded inner instructions.
+   *
+   * @since v0.5.0
+   */
+  decodeInner(
+    innerGroups: InnerInstructionGroup[],
+    tx: TransactionResponse | VersionedTransactionResponse,
+  ) {
+    const accountKeys = extractAccountKeys(tx);
+    return decodeInnerInstructions(
+      innerGroups,
+      accountKeys,
+      this.coder,
+      this.programId,
+    );
+  }
+}