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

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;
-    }
-  }
-}

package/src/parser/instructions.ts

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

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