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

package/src/core/connection.ts

@@ -31,9 +31,11 @@ import {
   type Commitment,
   Keypair,
   type PublicKey,
+  type Transaction,
+  type VersionedTransaction,
   LAMPORTS_PER_SOL,
 } from "@solana/web3.js";
-import { AnchorProvider, Wallet } from "@coral-xyz/anchor";
+import { AnchorProvider } from "@coral-xyz/anchor";
 import {
   SAP_PROGRAM_ID,
   MAINNET_SAP_PROGRAM_ID,
@@ -42,6 +44,56 @@ import {
 } from "../constants";
 import { SapClient } from "./client";
 
+// ═══════════════════════════════════════════════════════════════════
+//  Wallet interface (replaces Anchor's Wallet which is not
+//  exported from the ESM bundle of @coral-xyz/anchor)
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface SapWallet
+ * @description Minimal wallet/signer interface compatible with
+ * Anchor's `AnchorProvider`. Avoids importing `Wallet` from
+ * `@coral-xyz/anchor` which is absent in ESM builds.
+ * @category Core
+ * @since v0.4.1
+ */
+export interface SapWallet {
+  readonly publicKey: PublicKey;
+  signTransaction<T extends Transaction | VersionedTransaction>(tx: T): Promise<T>;
+  signAllTransactions<T extends Transaction | VersionedTransaction>(txs: T[]): Promise<T[]>;
+}
+
+/**
+ * @name KeypairWallet
+ * @description Simple wallet wrapper around a `Keypair`.
+ * Drop-in replacement for Anchor's `NodeWallet` / `Wallet` class.
+ * @category Core
+ * @since v0.4.1
+ */
+export class KeypairWallet implements SapWallet {
+  readonly publicKey: PublicKey;
+
+  constructor(readonly payer: Keypair) {
+    this.publicKey = payer.publicKey;
+  }
+
+  async signTransaction<T extends Transaction | VersionedTransaction>(tx: T): Promise<T> {
+    if ("partialSign" in tx) {
+      (tx as Transaction).partialSign(this.payer);
+    } else {
+      (tx as VersionedTransaction).sign([this.payer]);
+    }
+    return tx;
+  }
+
+  async signAllTransactions<T extends Transaction | VersionedTransaction>(txs: T[]): Promise<T[]> {
+    for (const tx of txs) {
+      await this.signTransaction(tx);
+    }
+    return txs;
+  }
+}
+
 // ═══════════════════════════════════════════════════════════════════
 //  Types
 // ═══════════════════════════════════════════════════════════════════
@@ -261,7 +313,7 @@ export class SapConnection {
       commitment: opts?.commitment,
       cluster: opts?.cluster,
     });
-    const client = conn.createClient(new Wallet(keypair));
+    const client = conn.createClient(new KeypairWallet(keypair));
     return Object.assign(conn, { client });
   }
 
@@ -270,18 +322,18 @@ export class SapConnection {
   // ─────────────────────────────────────────────
 
   /**
-   * Create a {@link SapClient} from an Anchor {@link Wallet} (signer).
+   * Create a {@link SapClient} from a {@link SapWallet} (signer).
    *
-   * @param {Wallet} wallet — An Anchor-compatible wallet/signer.
+   * @param {SapWallet} wallet — A wallet/signer implementing {@link SapWallet}.
    * @returns {SapClient} A fully-configured SAP client.
    * @since v0.1.0
    *
    * @example
    * ```ts
-   * const client = conn.createClient(new Wallet(keypair));
+   * const client = conn.createClient(new KeypairWallet(keypair));
    * ```
    */
-  createClient(wallet: Wallet): SapClient {
+  createClient(wallet: SapWallet): SapClient {
     const provider = new AnchorProvider(this.connection, wallet, {
       commitment: this.commitment,
     });
@@ -301,7 +353,7 @@ export class SapConnection {
    * ```
    */
   fromKeypair(keypair: Keypair): SapClient {
-    return this.createClient(new Wallet(keypair));
+    return this.createClient(new KeypairWallet(keypair));
   }
 
   // ─────────────────────────────────────────────

package/src/core/index.ts

@@ -16,5 +16,5 @@
  */
 
 export { SapClient } from "./client";
-export { SapConnection } from "./connection";
-export type { SapCluster, SapConnectionConfig } from "./connection";
+export { SapConnection, KeypairWallet } from "./connection";
+export type { SapCluster, SapConnectionConfig, SapWallet } from "./connection";

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
@@ -44,8 +45,8 @@
  */
 
 // ── Core ─────────────────────────────────────────────
-export { SapClient, SapConnection } from "./core";
-export type { SapCluster, SapConnectionConfig } from "./core";
+export { SapClient, SapConnection, KeypairWallet } from "./core";
+export type { SapCluster, SapConnectionConfig, SapWallet } from "./core";
 
 // ── Types ────────────────────────────────────────────
 export type {
@@ -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,
+    );
+  }
+}

package/src/parser/complete.ts

@@ -0,0 +1,232 @@
+/**
+ * @module parser/complete
+ * @description Full SAP transaction parser: instructions + args + accounts + events.
+ *
+ * This is "Case 2 Complete": given a raw transaction response, produce a
+ * single {@link ParsedSapTransaction} containing every decoded instruction,
+ * all inner (CPI) calls, and all SAP events extracted from the logs.
+ *
+ * Designed for indexer pipelines where the decode step must be pure,
+ * deterministic, and fully testable without an RPC connection.
+ *
+ * @category Parser
+ * @since v0.5.0
+ *
+ * @example
+ * ```ts
+ * import { parseSapTransactionComplete } from "@synapse-sap/sdk/parser";
+ * import { SAP_PROGRAM_ID, SAP_IDL } from "@synapse-sap/sdk";
+ * import { Program } from "\@coral-xyz/anchor";
+ *
+ * const program = new Program(SAP_IDL, provider);
+ * const tx = await connection.getTransaction(sig, {
+ *   commitment: "confirmed",
+ *   maxSupportedTransactionVersion: 0,
+ * });
+ *
+ * const parsed = parseSapTransactionComplete(tx, program, SAP_PROGRAM_ID);
+ * console.log(parsed.instructions.map(i => i.name));
+ * console.log(parsed.events.map(e => e.name));
+ * ```
+ */
+
+import {
+  AddressLookupTableAccount,
+  type PublicKey,
+  type TransactionResponse,
+  type VersionedTransactionResponse,
+} from "@solana/web3.js";
+import type { Program } from "@coral-xyz/anchor";
+
+import type {
+  ParsedSapTransaction,
+  ParseFilterOptions,
+  DecodedInnerInstruction,
+  SapInstructionCoder,
+} from "./types";
+import type { ParsedEvent } from "../events";
+import { EventParser } from "../events";
+import { parseSapInstructionsFromTransaction } from "./transaction";
+import {
+  decodeInnerInstructions,
+  extractAccountKeys,
+  type InnerInstructionGroup,
+} from "./inner";
+
+// ================================================================
+//  Public API
+// ================================================================
+
+/**
+ * Parse a complete SAP transaction into a unified result.
+ *
+ * Combines three stages:
+ * 1. **Instruction decode** - top-level SAP instructions with args and accounts
+ * 2. **Inner instruction decode** - CPI calls with full account reconstruction
+ * 3. **Event extraction** - SAP events decoded from the transaction logs
+ *
+ * All three stages are safe: malformed data produces `null` fields
+ * rather than exceptions. This makes the function suitable for
+ * batch-processing in indexer workers where a single bad transaction
+ * must not halt the pipeline.
+ *
+ * @param tx - The raw transaction response from `connection.getTransaction`.
+ * @param program - An Anchor `Program` instance built from the SAP IDL.
+ *   The coder and program ID are extracted automatically.
+ * @param sapProgramId - The SAP program public key. Passed explicitly so
+ *   callers can target devnet/localnet deployments independently.
+ * @param options - Optional filters for instructions, events, and inner calls.
+ * @param addressLookupTables - Resolved lookup table accounts for v0 transactions.
+ * @returns A fully parsed transaction, or `null` if the input is `null`/`undefined`.
+ *
+ * @category Parser
+ * @since v0.5.0
+ */
+export function parseSapTransactionComplete(
+  tx: TransactionResponse | VersionedTransactionResponse | null | undefined,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  program: Program<any>,
+  sapProgramId: PublicKey,
+  options?: ParseFilterOptions,
+  addressLookupTables?: AddressLookupTableAccount[],
+): ParsedSapTransaction | null {
+  if (!tx) return null;
+
+  const opts: Required<ParseFilterOptions> = {
+    includeInner: options?.includeInner ?? false,
+    includeEvents: options?.includeEvents ?? true,
+    instructionFilter: options?.instructionFilter ?? [],
+    eventFilter: options?.eventFilter ?? [],
+  };
+
+  // Extract coder from the program
+  const coder = program.coder.instruction as unknown as SapInstructionCoder;
+
+  // 1. Top-level instructions
+  let instructions = parseSapInstructionsFromTransaction(
+    tx,
+    coder,
+    sapProgramId,
+    addressLookupTables,
+  );
+
+  if (opts.instructionFilter.length > 0) {
+    const filterSet = new Set(opts.instructionFilter);
+    instructions = instructions.filter((ix) => filterSet.has(ix.name));
+  }
+
+  // 2. Inner (CPI) instructions
+  let innerInstructions: DecodedInnerInstruction[] = [];
+  if (opts.includeInner && tx.meta?.innerInstructions) {
+    const accountKeys = extractAccountKeys(tx);
+    innerInstructions = decodeInnerInstructions(
+      tx.meta.innerInstructions as unknown as InnerInstructionGroup[],
+      accountKeys,
+      coder,
+      sapProgramId,
+    );
+  }
+
+  // 3. Events from logs
+  let events: ParsedEvent[] = [];
+  const logs = tx.meta?.logMessages ?? [];
+
+  if (opts.includeEvents && logs.length > 0) {
+    const eventParser = new EventParser(program);
+    events = eventParser.parseLogs(logs);
+
+    if (opts.eventFilter.length > 0) {
+      const filterSet = new Set(opts.eventFilter);
+      events = events.filter((e) => filterSet.has(e.name as never));
+    }
+  }
+
+  // 4. Metadata
+  const signature = extractSignature(tx);
+  const slot = tx.slot ?? null;
+  const blockTime = tx.blockTime ?? null;
+  const success = tx.meta?.err === null || tx.meta?.err === undefined;
+
+  return {
+    signature,
+    slot,
+    blockTime,
+    success,
+    instructions,
+    innerInstructions,
+    events,
+    logs,
+  };
+}
+
+/**
+ * Parse multiple transactions in batch.
+ *
+ * Convenience wrapper for indexer pipelines that process pages of
+ * transactions. Skips `null` entries and failed decodes silently.
+ *
+ * @param txs - Array of transaction responses (may contain `null` entries).
+ * @param program - The Anchor SAP program instance.
+ * @param sapProgramId - The SAP program public key.
+ * @param options - Optional parse filters applied to every transaction.
+ * @param addressLookupTables - Lookup tables for v0 transactions.
+ * @returns An array of non-null parsed transactions.
+ *
+ * @category Parser
+ * @since v0.5.0
+ *
+ * @example
+ * ```ts
+ * const signatures = await connection.getSignaturesForAddress(agentPda);
+ * const txs = await Promise.all(
+ *   signatures.map(s => connection.getTransaction(s.signature, { ... }))
+ * );
+ * const parsed = parseSapTransactionBatch(txs, program, SAP_PROGRAM_ID, {
+ *   includeEvents: true,
+ *   includeInner: true,
+ * });
+ * ```
+ */
+export function parseSapTransactionBatch(
+  txs: (TransactionResponse | VersionedTransactionResponse | null | undefined)[],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  program: Program<any>,
+  sapProgramId: PublicKey,
+  options?: ParseFilterOptions,
+  addressLookupTables?: AddressLookupTableAccount[],
+): ParsedSapTransaction[] {
+  const results: ParsedSapTransaction[] = [];
+  for (const tx of txs) {
+    const parsed = parseSapTransactionComplete(
+      tx,
+      program,
+      sapProgramId,
+      options,
+      addressLookupTables,
+    );
+    if (parsed) results.push(parsed);
+  }
+  return results;
+}
+
+// ================================================================
+//  Internal
+// ================================================================
+
+/**
+ * Extract the transaction signature from the response.
+ * Different RPC clients expose it in different locations.
+ *
+ * @internal
+ */
+function extractSignature(
+  tx: TransactionResponse | VersionedTransactionResponse,
+): string | null {
+  // Some clients expose signatures on the transaction object
+  const txObj = tx.transaction;
+  if ("signatures" in txObj && Array.isArray(txObj.signatures) && txObj.signatures.length > 0) {
+    const first = txObj.signatures[0];
+    if (typeof first === "string") return first;
+  }
+  return null;
+}

package/src/parser/index.ts

@@ -0,0 +1,71 @@
+/**
+ * @module parser
+ * @description Transaction parsing utilities for SAP v2.
+ *
+ * Provides modular, composable functions for decoding on-chain SAP
+ * transactions into typed instruction data, argument objects, account
+ * lists, and protocol events.
+ *
+ * Three levels of parsing are available depending on your use case:
+ *
+ * | Function | Input | Output |
+ * |----------|-------|--------|
+ * | `parseSapInstructionsFromTransaction` | `TransactionResponse` (RPC) | Decoded instructions |
+ * | `parseSapInstructionsFromList` | `TransactionInstruction[]` | Decoded instructions |
+ * | `parseSapTransactionComplete` | `TransactionResponse` (RPC) | Instructions + events + inner calls |
+ *
+ * All functions are pure and stateless: they accept the Anchor coder
+ * (or full Program) as a parameter, making them safe for server-side
+ * indexer workers, edge functions (Node.js runtime), and test suites.
+ *
+ * @category Parser
+ * @since v0.5.0
+ *
+ * @example
+ * ```ts
+ * import {
+ *   parseSapTransactionComplete,
+ *   parseSapInstructionsFromList,
+ *   containsSapInstruction,
+ * } from "@synapse-sap/sdk/parser";
+ * ```
+ */
+
+// ── Types ────────────────────────────────────────────
+export type {
+  DecodedSapInstruction,
+  DecodedInnerInstruction,
+  ParsedSapTransaction,
+  ParseFilterOptions,
+  SapInstructionCoder,
+} from "./types";
+
+// ── Case 2A: from TransactionResponse ────────────────
+export {
+  parseSapInstructionsFromTransaction,
+  parseSapInstructionNamesFromTransaction,
+} from "./transaction";
+
+// ── Case 2B: from TransactionInstruction[] ───────────
+export {
+  parseSapInstructionsFromList,
+  parseSapInstructionNamesFromList,
+  containsSapInstruction,
+} from "./instructions";
+
+// ── Case 2 Complete: instructions + events + inner ───
+export {
+  parseSapTransactionComplete,
+  parseSapTransactionBatch,
+} from "./complete";
+
+// ── Inner instruction utilities ──────────────────────
+export {
+  decodeInnerInstructions,
+  filterSapInnerInstructions,
+  extractAccountKeys,
+} from "./inner";
+export type { CompiledInner, InnerInstructionGroup } from "./inner";
+
+// ── OOP wrapper (for SapClient integration) ──────────
+export { TransactionParser } from "./client";