@oobe-protocol-labs/synapse-sap-sdk 0.13.0 → 0.15.0

package/src/parser/client.ts

@@ -1,211 +0,0 @@
-/**
- * @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

@@ -1,232 +0,0 @@
-/**
- * @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/inner.ts

@@ -1,255 +0,0 @@
-/**
- * @module parser/inner
- * @description Decode inner (CPI) instructions from transaction metadata.
- *
- * When a SAP instruction triggers cross-program invocations, the
- * resulting inner instructions appear in `tx.meta.innerInstructions`.
- * These are stored in a "compiled" format that references account
- * indices rather than full public keys.
- *
- * This module reconstructs the full account keys from the transaction
- * message's account list and decodes any inner calls that target the
- * SAP program.
- *
- * @category Parser
- * @since v0.5.0
- *
- * @example
- * ```ts
- * import { decodeInnerInstructions } from "@synapse-sap/sdk/parser";
- *
- * const inner = decodeInnerInstructions(
- *   tx.meta?.innerInstructions ?? [],
- *   accountKeys,
- *   program.coder.instruction,
- *   SAP_PROGRAM_ID,
- * );
- * for (const cpi of inner) {
- *   if (cpi.name) console.log("SAP CPI:", cpi.name);
- * }
- * ```
- */
-
-import { PublicKey } from "@solana/web3.js";
-import { utils } from "@coral-xyz/anchor";
-import type { DecodedInnerInstruction, SapInstructionCoder } from "./types";
-
-// ================================================================
-//  Types matching Solana RPC response shapes
-// ================================================================
-
-/**
- * Shape of a single compiled inner instruction from `tx.meta.innerInstructions`.
- * Mirrors the Solana RPC `CompiledInnerInstruction` format.
- *
- * @interface CompiledInner
- * @category Parser
- * @since v0.5.0
- */
-export interface CompiledInner {
-  readonly programIdIndex: number;
-  readonly accounts: number[];
-  readonly data: string;
-}
-
-/**
- * Top-level inner instruction group from the transaction metadata.
- * Each group corresponds to one outer instruction by `index`.
- *
- * @interface InnerInstructionGroup
- * @category Parser
- * @since v0.5.0
- */
-export interface InnerInstructionGroup {
-  readonly index: number;
-  readonly instructions: CompiledInner[];
-}
-
-// ================================================================
-//  Public API
-// ================================================================
-
-/**
- * Decode inner (CPI) instructions from transaction metadata.
- *
- * Reconstructs full public keys from the compiled account indices
- * and attempts to decode each inner instruction that targets the
- * SAP program. Non-SAP inner instructions are included in the
- * result with `name: null` and `args: null`.
- *
- * @param innerInstructionGroups - The `tx.meta.innerInstructions` array.
- * @param accountKeys - Ordered list of all account public keys from the
- *   transaction message (`staticAccountKeys` for versioned, or
- *   `accountKeys` for legacy).
- * @param coder - An Anchor instruction coder built from the SAP IDL.
- * @param sapProgramId - The SAP program public key.
- * @returns An array of decoded inner instructions.
- *
- * @category Parser
- * @since v0.5.0
- */
-export function decodeInnerInstructions(
-  innerInstructionGroups: InnerInstructionGroup[],
-  accountKeys: PublicKey[],
-  coder: SapInstructionCoder,
-  sapProgramId: PublicKey,
-): DecodedInnerInstruction[] {
-  const results: DecodedInnerInstruction[] = [];
-
-  for (const group of innerInstructionGroups) {
-    for (let innerIdx = 0; innerIdx < group.instructions.length; innerIdx++) {
-      const compiled = group.instructions[innerIdx];
-      if (!compiled) continue;
-
-      const programId = resolveAccountKey(
-        accountKeys,
-        compiled.programIdIndex,
-      );
-      const accounts = compiled.accounts.map((idx) =>
-        resolveAccountKey(accountKeys, idx),
-      );
-
-      let name: string | null = null;
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      let args: Record<string, any> | null = null;
-
-      if (programId.equals(sapProgramId)) {
-        const decoded = safeDecodeInstruction(coder, compiled.data);
-        if (decoded) {
-          name = decoded.name;
-          args = decoded.data;
-        }
-      }
-
-      results.push({
-        outerIndex: group.index,
-        innerIndex: innerIdx,
-        name,
-        args,
-        accounts,
-        programId,
-      });
-    }
-  }
-
-  return results;
-}
-
-/**
- * Filter decoded inner instructions to only those targeting the SAP program.
- *
- * @param inner - The full inner instruction list from {@link decodeInnerInstructions}.
- * @returns Only inner instructions where `name` is not `null`.
- *
- * @category Parser
- * @since v0.5.0
- */
-export function filterSapInnerInstructions(
-  inner: DecodedInnerInstruction[],
-): DecodedInnerInstruction[] {
-  return inner.filter((i) => i.name !== null);
-}
-
-// ================================================================
-//  Helpers: extract account keys from various tx formats
-// ================================================================
-
-/**
- * Extract the full ordered list of account keys from a transaction
- * response, handling both legacy and versioned formats.
- *
- * For versioned transactions that include loaded addresses (from
- * address lookup tables), these are appended after the static keys
- * in the order: static, writable loaded, readonly loaded.
- *
- * @param tx - The raw transaction response from RPC.
- * @returns An ordered array of all account public keys.
- *
- * @category Parser
- * @since v0.5.0
- */
-export function extractAccountKeys(
-  tx: {
-    transaction: {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      message: any;
-    };
-    meta?: {
-      loadedAddresses?: {
-        writable: PublicKey[];
-        readonly: PublicKey[];
-      } | null;
-    } | null;
-  },
-): PublicKey[] {
-  const message = tx.transaction.message;
-
-  // Versioned messages expose `staticAccountKeys`
-  if ("staticAccountKeys" in message && Array.isArray(message.staticAccountKeys)) {
-    const staticKeys: PublicKey[] = message.staticAccountKeys.map(toPubkey);
-    const loaded = tx.meta?.loadedAddresses;
-    if (loaded) {
-      return [
-        ...staticKeys,
-        ...loaded.writable.map(toPubkey),
-        ...loaded.readonly.map(toPubkey),
-      ];
-    }
-    return staticKeys;
-  }
-
-  // Legacy messages expose `accountKeys`
-  if ("accountKeys" in message && Array.isArray(message.accountKeys)) {
-    return message.accountKeys.map(toPubkey);
-  }
-
-  return [];
-}
-
-// ================================================================
-//  Internal
-// ================================================================
-
-/**
- * Safely resolve an account index to a public key, returning
- * `PublicKey.default` for out-of-bounds indices instead of throwing.
- *
- * @internal
- */
-function resolveAccountKey(keys: PublicKey[], index: number): PublicKey {
-  const key = keys[index];
-  return key ?? PublicKey.default;
-}
-
-/**
- * Coerce a value to PublicKey. Handles both string base58 and
- * PublicKey instances returned by different RPC client versions.
- *
- * @internal
- */
-function toPubkey(value: string | PublicKey): PublicKey {
-  if (typeof value === "string") return new PublicKey(value);
-  return value;
-}
-
-/**
- * @internal
- */
-function safeDecodeInstruction(
-  coder: SapInstructionCoder,
-  data: string,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-): { name: string; data: Record<string, any> } | null {
-  try {
-    // Inner instruction data from RPC is base58-encoded
-    const buffer = Buffer.from(utils.bytes.bs58.decode(data));
-    return coder.decode(buffer);
-  } catch {
-    // Fallback: try base64 encoding (some RPC responses use base64)
-    try {
-      return coder.decode(Buffer.from(data, "base64"));
-    } catch {
-      return null;
-    }
-  }
-}