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

package/dist/cjs/parser/inner.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * @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);
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeInnerInstructions = decodeInnerInstructions;
+exports.filterSapInnerInstructions = filterSapInnerInstructions;
+exports.extractAccountKeys = extractAccountKeys;
+const web3_js_1 = require("@solana/web3.js");
+const anchor_1 = require("@coral-xyz/anchor");
+// ================================================================
+//  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
+ */
+function decodeInnerInstructions(innerInstructionGroups, accountKeys, coder, sapProgramId) {
+    const results = [];
+    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 = null;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            let args = 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
+ */
+function filterSapInnerInstructions(inner) {
+    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
+ */
+function extractAccountKeys(tx) {
+    const message = tx.transaction.message;
+    // Versioned messages expose `staticAccountKeys`
+    if ("staticAccountKeys" in message && Array.isArray(message.staticAccountKeys)) {
+        const staticKeys = 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, index) {
+    const key = keys[index];
+    return key ?? web3_js_1.PublicKey.default;
+}
+/**
+ * Coerce a value to PublicKey. Handles both string base58 and
+ * PublicKey instances returned by different RPC client versions.
+ *
+ * @internal
+ */
+function toPubkey(value) {
+    if (typeof value === "string")
+        return new web3_js_1.PublicKey(value);
+    return value;
+}
+/**
+ * @internal
+ */
+function safeDecodeInstruction(coder, data) {
+    try {
+        // Inner instruction data from RPC is base58-encoded
+        const buffer = Buffer.from(anchor_1.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;
+        }
+    }
+}
+//# sourceMappingURL=inner.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inner.js","sourceRoot":"","sources":["../../../src/parser/inner.ts"],"names":[],"mappings":"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"}

package/dist/cjs/parser/instructions.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * @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);
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSapInstructionsFromList = parseSapInstructionsFromList;
+exports.parseSapInstructionNamesFromList = parseSapInstructionNamesFromList;
+exports.containsSapInstruction = containsSapInstruction;
+// ================================================================
+//  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
+ */
+function parseSapInstructionsFromList(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;
+}
+/**
+ * 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
+ */
+function parseSapInstructionNamesFromList(instructions, coder, sapProgramId) {
+    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
+ */
+function containsSapInstruction(instructions, sapProgramId) {
+    return instructions.some((ix) => ix.programId.equals(sapProgramId));
+}
+// ================================================================
+//  Internal
+// ================================================================
+/**
+ * @internal
+ */
+function safeDecodeInstruction(coder, data) {
+    try {
+        return coder.decode(Buffer.from(data));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=instructions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/parser/instructions.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;AA2BH,oEAoBC;AAgBD,4EAQC;AAcD,wDAKC;AArFD,mEAAmE;AACnE,cAAc;AACd,mEAAmE;AAEnE;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,4BAA4B,CAC1C,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;;;;;;;;;;;;;GAaG;AACH,SAAgB,gCAAgC,CAC9C,YAAsC,EACtC,KAA0B,EAC1B,YAAuB;IAEvB,OAAO,4BAA4B,CAAC,YAAY,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,GAAG,CACxE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAChB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,sBAAsB,CACpC,YAAsC,EACtC,YAAuB;IAEvB,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,mEAAmE;AACnE,YAAY;AACZ,mEAAmE;AAEnE;;GAEG;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/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"}

package/dist/esm/core/client.js

@@ -34,6 +34,7 @@ import { EscrowModule } from "../modules/escrow";
 import { AttestationModule } from "../modules/attestation";
 import { LedgerModule } from "../modules/ledger";
 import { EventParser } from "../events";
+import { TransactionParser } from "../parser/client";
 import { DiscoveryRegistry } from "../registries/discovery";
 import { X402Registry } from "../registries/x402";
 import { SessionManager } from "../registries/session";
@@ -105,6 +106,8 @@ export class SapClient {
     #attestation;
     #ledger;
     #events;
+    // ── Lazy parser singleton ─────────────────────
+    #parser;
     // ── Lazy registry singletons ──────────────────────
     #discovery;
     #x402;
@@ -289,6 +292,26 @@ export class SapClient {
     get events() {
         return (this.#events ??= new EventParser(this.program));
     }
+    /**
+     * @name parser
+     * @description Transaction parser: decode instruction names, arguments,
+     * accounts, inner CPI calls, and protocol events from raw transaction
+     * responses. Designed for indexers and explorers.
+     * @returns {TransactionParser} The lazily-instantiated `TransactionParser` singleton.
+     * @category Modules
+     * @since v0.5.0
+     * @see {@link TransactionParser}
+     *
+     * @example
+     * ```ts
+     * const tx = await connection.getTransaction(sig, { ... });
+     * const parsed = client.parser.parseTransaction(tx);
+     * console.log(parsed?.instructions.map(i => i.name));
+     * ```
+     */
+    get parser() {
+        return (this.#parser ??= new TransactionParser(this.program));
+    }
     // ═════════════════════════════════════════════
     //  Registry Accessors (high-level abstractions)
     // ═════════════════════════════════════════════

package/dist/esm/core/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/core/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/core/client.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/connection.js

@@ -26,9 +26,39 @@
  * ```
  */
 import { Connection, 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, DEVNET_SAP_PROGRAM_ID, LOCALNET_SAP_PROGRAM_ID, } from "../constants";
 import { SapClient } from "./client";
+/**
+ * @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 {
+    payer;
+    publicKey;
+    constructor(payer) {
+        this.payer = payer;
+        this.publicKey = payer.publicKey;
+    }
+    async signTransaction(tx) {
+        if ("partialSign" in tx) {
+            tx.partialSign(this.payer);
+        }
+        else {
+            tx.sign([this.payer]);
+        }
+        return tx;
+    }
+    async signAllTransactions(txs) {
+        for (const tx of txs) {
+            await this.signTransaction(tx);
+        }
+        return txs;
+    }
+}
 // ═══════════════════════════════════════════════════════════════════
 //  Implementation
 // ═══════════════════════════════════════════════════════════════════
@@ -180,22 +210,22 @@ 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 });
     }
     // ─────────────────────────────────────────────
     //  Client creation
     // ─────────────────────────────────────────────
     /**
-     * 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) {
@@ -217,7 +247,7 @@ export class SapConnection {
      * ```
      */
     fromKeypair(keypair) {
-        return this.createClient(new Wallet(keypair));
+        return this.createClient(new KeypairWallet(keypair));
     }
     // ─────────────────────────────────────────────
     //  Utility methods

package/dist/esm/core/connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../../src/core/connection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../../src/core/connection.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/index.js

@@ -15,5 +15,5 @@
  * ```
  */
 export { SapClient } from "./client";
-export { SapConnection } from "./connection";
+export { SapConnection, KeypairWallet } from "./connection";
 //# sourceMappingURL=index.js.map

package/dist/esm/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}