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

package/dist/types/parser/instructions.d.ts

@@ -1,76 +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";
-/**
- * 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 declare function parseSapInstructionsFromList(instructions: TransactionInstruction[], coder: SapInstructionCoder, sapProgramId: PublicKey): DecodedSapInstruction[];
-/**
- * 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 declare function parseSapInstructionNamesFromList(instructions: TransactionInstruction[], coder: SapInstructionCoder, sapProgramId: PublicKey): string[];
-/**
- * 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 declare function containsSapInstruction(instructions: TransactionInstruction[], sapProgramId: PublicKey): boolean;
-//# sourceMappingURL=instructions.d.ts.map

package/dist/types/parser/instructions.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../../src/parser/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAM1E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,4BAA4B,CAC1C,YAAY,EAAE,sBAAsB,EAAE,EACtC,KAAK,EAAE,mBAAmB,EAC1B,YAAY,EAAE,SAAS,GACtB,qBAAqB,EAAE,CAgBzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gCAAgC,CAC9C,YAAY,EAAE,sBAAsB,EAAE,EACtC,KAAK,EAAE,mBAAmB,EAC1B,YAAY,EAAE,SAAS,GACtB,MAAM,EAAE,CAIV;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,sBAAsB,EAAE,EACtC,YAAY,EAAE,SAAS,GACtB,OAAO,CAET"}

package/dist/types/parser/transaction.d.ts

@@ -1,77 +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 { AddressLookupTableAccount, type PublicKey, type VersionedTransactionResponse, type TransactionResponse } from "@solana/web3.js";
-import type { DecodedSapInstruction, SapInstructionCoder } from "./types";
-/**
- * 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 declare function parseSapInstructionsFromTransaction(tx: TransactionResponse | VersionedTransactionResponse, coder: SapInstructionCoder, sapProgramId: PublicKey, addressLookupTables?: AddressLookupTableAccount[]): DecodedSapInstruction[];
-/**
- * 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 declare function parseSapInstructionNamesFromTransaction(tx: TransactionResponse | VersionedTransactionResponse, coder: SapInstructionCoder, sapProgramId: PublicKey, addressLookupTables?: AddressLookupTableAccount[]): string[];
-//# sourceMappingURL=transaction.d.ts.map

package/dist/types/parser/transaction.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../../src/parser/transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAEL,yBAAyB,EACzB,KAAK,SAAS,EAEd,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,EACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAM1E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mCAAmC,CACjD,EAAE,EAAE,mBAAmB,GAAG,4BAA4B,EACtD,KAAK,EAAE,mBAAmB,EAC1B,YAAY,EAAE,SAAS,EACvB,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,qBAAqB,EAAE,CAGzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uCAAuC,CACrD,EAAE,EAAE,mBAAmB,GAAG,4BAA4B,EACtD,KAAK,EAAE,mBAAmB,EAC1B,YAAY,EAAE,SAAS,EACvB,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,MAAM,EAAE,CAOV"}

package/dist/types/parser/types.d.ts

@@ -1,154 +0,0 @@
-/**
- * @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
- */
-import type { PublicKey, TransactionInstruction } from "@solana/web3.js";
-import type { ParsedEvent, SapEventName } from "../events";
-/**
- * A single SAP instruction decoded from on-chain transaction data.
- *
- * Contains the human-readable instruction name (as declared in the
- * Anchor IDL), the decoded argument object, the ordered list of
- * account keys, and the raw instruction for advanced consumers.
- *
- * @interface DecodedSapInstruction
- * @category Parser
- * @since v0.5.0
- */
-export interface DecodedSapInstruction {
-    /** Instruction name matching the Anchor IDL method (e.g. `"registerAgent"`). */
-    readonly name: string;
-    /**
-     * Decoded arguments object. Keys match the Anchor IDL argument names.
-     * Returns `null` when decoding fails (e.g. IDL mismatch).
-     */
-    readonly args: Record<string, any> | null;
-    /** Ordered list of account public keys passed to the instruction. */
-    readonly accounts: PublicKey[];
-    /** The original `TransactionInstruction`, useful for re-simulation or forwarding. */
-    readonly raw: TransactionInstruction;
-}
-/**
- * An inner instruction produced by cross-program invocation (CPI)
- * within a SAP transaction.
- *
- * Inner instructions are indexed by the outer instruction position
- * that triggered them. Each entry includes the decoded SAP name
- * when the inner call targets the SAP program, or `null` otherwise.
- *
- * @interface DecodedInnerInstruction
- * @category Parser
- * @since v0.5.0
- */
-export interface DecodedInnerInstruction {
-    /** Zero-based index of the outer instruction that triggered this CPI call. */
-    readonly outerIndex: number;
-    /** Zero-based position within the inner instruction set of the parent. */
-    readonly innerIndex: number;
-    /** SAP instruction name if the CPI targets the SAP program, `null` otherwise. */
-    readonly name: string | null;
-    /** Decoded arguments when the CPI targets SAP and decoding succeeds. */
-    readonly args: Record<string, any> | null;
-    /** Ordered account keys for this inner instruction. */
-    readonly accounts: PublicKey[];
-    /** The program that was invoked by this inner call. */
-    readonly programId: PublicKey;
-}
-/**
- * Full parse result for a single SAP transaction.
- *
- * Combines top-level instruction decoding, inner instruction
- * analysis, and event extraction into one unified structure
- * suitable for indexing, analytics dashboards, and protocol
- * explorers.
- *
- * @interface ParsedSapTransaction
- * @category Parser
- * @since v0.5.0
- *
- * @example
- * ```ts
- * const result = parseSapTransactionComplete(tx, program, SAP_PROGRAM_ID);
- * for (const ix of result.instructions) {
- *   console.log(ix.name, ix.args);
- * }
- * for (const event of result.events) {
- *   console.log(event.name, event.data);
- * }
- * ```
- */
-export interface ParsedSapTransaction {
-    /** Transaction signature (base-58), extracted from the response when available. */
-    readonly signature: string | null;
-    /** Slot at which the transaction was confirmed. */
-    readonly slot: number | null;
-    /** Block timestamp (unix seconds) or `null` if unavailable. */
-    readonly blockTime: number | null;
-    /** Whether the transaction succeeded (`true`) or failed. */
-    readonly success: boolean;
-    /** Top-level SAP instructions found in the transaction. */
-    readonly instructions: DecodedSapInstruction[];
-    /** All inner (CPI) instructions, including non-SAP programs. */
-    readonly innerInstructions: DecodedInnerInstruction[];
-    /** Decoded SAP events extracted from the transaction logs. */
-    readonly events: ParsedEvent[];
-    /** Raw log lines from the transaction, for additional debugging. */
-    readonly logs: string[];
-}
-/**
- * Options for filtering parsed instruction results.
- *
- * @interface ParseFilterOptions
- * @category Parser
- * @since v0.5.0
- */
-export interface ParseFilterOptions {
-    /**
-     * When `true`, include inner (CPI) instructions in the parse
-     * result. Defaults to `false` because inner instruction
-     * reconstruction requires additional account-table lookups.
-     */
-    readonly includeInner?: boolean;
-    /**
-     * When `true`, decode and attach SAP events from the
-     * transaction logs. Defaults to `true`.
-     */
-    readonly includeEvents?: boolean;
-    /**
-     * Restrict the result to instructions matching one of these
-     * names. When `undefined` or empty, all SAP instructions are
-     * returned.
-     */
-    readonly instructionFilter?: string[];
-    /**
-     * Restrict events to those matching one of these names.
-     * When `undefined` or empty, all events are returned.
-     */
-    readonly eventFilter?: SapEventName[];
-}
-/**
- * Minimal interface for the Anchor instruction coder.
- *
- * Extracted so that parser functions can accept either a full
- * `Program` instance or a standalone coder/IDL pair without
- * requiring a live RPC connection.
- *
- * @interface SapInstructionCoder
- * @category Parser
- * @since v0.5.0
- */
-export interface SapInstructionCoder {
-    /** Decode raw instruction data into a name and typed argument object. */
-    decode(data: Buffer | Uint8Array, encoding?: string): {
-        name: string;
-        data: Record<string, any>;
-    } | null;
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/types/parser/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/parser/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAM3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IAEH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC;IAC/B,qFAAqF;IACrF,QAAQ,CAAC,GAAG,EAAE,sBAAsB,CAAC;CACtC;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,wEAAwE;IAExE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC1C,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,qBAAqB,EAAE,CAAC;IAC/C,gEAAgE;IAChE,QAAQ,CAAC,iBAAiB,EAAE,uBAAuB,EAAE,CAAC;IACtD,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;CACzB;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,YAAY,EAAE,CAAC;CACvC;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,MAAM,CACJ,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,QAAQ,CAAC,EAAE,MAAM,GAEhB;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;CACvD"}