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

package/dist/cjs/parser/transaction.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * @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);
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSapInstructionsFromTransaction = parseSapInstructionsFromTransaction;
+exports.parseSapInstructionNamesFromTransaction = parseSapInstructionNamesFromTransaction;
+const web3_js_1 = require("@solana/web3.js");
+// ================================================================
+//  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
+ */
+function parseSapInstructionsFromTransaction(tx, coder, sapProgramId, addressLookupTables) {
+    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
+ */
+function parseSapInstructionNamesFromTransaction(tx, coder, sapProgramId, addressLookupTables) {
+    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, addressLookupTables) {
+    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 = web3_js_1.TransactionMessage.decompile(message, addressLookupTables?.length
+            ? { addressLookupTableAccounts: addressLookupTables }
+            : undefined);
+        return decompiledMessage.instructions;
+    }
+    // Legacy message: decompile directly
+    const decompiledMessage = web3_js_1.TransactionMessage.decompile(message);
+    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, coder, sapProgramId) {
+    const results = [];
+    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, data) {
+    try {
+        return coder.decode(Buffer.from(data));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=transaction.js.map

package/dist/cjs/parser/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../../src/parser/transaction.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;;AAqCH,kFAQC;AAiBD,0FAYC;AAxED,6CAOyB;AAGzB,mEAAmE;AACnE,cAAc;AACd,mEAAmE;AAEnE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,mCAAmC,CACjD,EAAsD,EACtD,KAA0B,EAC1B,YAAuB,EACvB,mBAAiD;IAEjD,MAAM,YAAY,GAAG,oBAAoB,CAAC,EAAE,EAAE,mBAAmB,CAAC,CAAC;IACnE,OAAO,qBAAqB,CAAC,YAAY,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,uCAAuC,CACrD,EAAsD,EACtD,KAA0B,EAC1B,YAAuB,EACvB,mBAAiD;IAEjD,OAAO,mCAAmC,CACxC,EAAE,EACF,KAAK,EACL,YAAY,EACZ,mBAAmB,CACpB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,mEAAmE;AACnE,oBAAoB;AACpB,mEAAmE;AAEnE;;;;;;;GAOG;AACH,SAAS,oBAAoB,CAC3B,EAAsD,EACtD,mBAAiD;IAEjD,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC;IAEvC,kEAAkE;IAClE,2EAA2E;IAC3E,MAAM,WAAW,GACf,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,CAAC,OAAO,KAAK,QAAQ,CAAC;IAEzE,IAAI,WAAW,EAAE,CAAC;QAChB,kEAAkE;QAClE,MAAM,iBAAiB,GAAG,4BAAkB,CAAC,SAAS,CACpD,OAAqD,EACrD,mBAAmB,EAAE,MAAM;YACzB,CAAC,CAAC,EAAE,0BAA0B,EAAE,mBAAmB,EAAE;YACrD,CAAC,CAAC,SAAS,CACd,CAAC;QACF,OAAO,iBAAiB,CAAC,YAAY,CAAC;IACxC,CAAC;IAED,qCAAqC;IACrC,MAAM,iBAAiB,GAAG,4BAAkB,CAAC,SAAS,CACpD,OAAqD,CACtD,CAAC;IACF,OAAO,iBAAiB,CAAC,YAAY,CAAC;AACxC,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,qBAAqB,CAC5B,YAAsC,EACtC,KAA0B,EAC1B,YAAuB;IAEvB,MAAM,OAAO,GAA4B,EAAE,CAAC;IAE5C,KAAK,MAAM,EAAE,IAAI,YAAY,EAAE,CAAC;QAC9B,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC;YAAE,SAAS;QAEjD,MAAM,OAAO,GAAG,qBAAqB,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QACtD,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,SAAS;YAChC,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,IAAI;YAC3B,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;YACtC,GAAG,EAAE,EAAE;SACR,CAAC,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,qBAAqB,CAC5B,KAA0B,EAC1B,IAAyB;IAGzB,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/cjs/parser/types.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/parser/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/parser/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG"}