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

package/src/parser/inner.ts

@@ -0,0 +1,255 @@
+/**
+ * @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;
+    }
+  }
+}

package/src/parser/instructions.ts

@@ -0,0 +1,135 @@
+/**
+ * @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";
+
+// ================================================================
+//  Public API
+// ================================================================
+
+/**
+ * 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 function parseSapInstructionsFromList(
+  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;
+}
+
+/**
+ * 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 function parseSapInstructionNamesFromList(
+  instructions: TransactionInstruction[],
+  coder: SapInstructionCoder,
+  sapProgramId: PublicKey,
+): string[] {
+  return parseSapInstructionsFromList(instructions, coder, sapProgramId).map(
+    (ix) => ix.name,
+  );
+}
+
+/**
+ * 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 function containsSapInstruction(
+  instructions: TransactionInstruction[],
+  sapProgramId: PublicKey,
+): boolean {
+  return instructions.some((ix) => ix.programId.equals(sapProgramId));
+}
+
+// ================================================================
+//  Internal
+// ================================================================
+
+/**
+ * @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/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;
+  }
+}