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

package/dist/esm/modules/vault.js

@@ -0,0 +1,423 @@
+/**
+ * @module vault
+ * @description Encrypted memory vault — init, session management, inscribe,
+ * delegate access, nonce rotation, and close operations.
+ *
+ * Vaults provide encrypted, session-scoped memory storage for agents,
+ * with support for epoch-based pagination and hot-wallet delegation.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+import { SystemProgram } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import { deriveAgent, deriveVault, deriveSession, deriveEpochPage, deriveVaultDelegate, deriveGlobalRegistry, } from "../pda";
+import { MAX_DELEGATE_DURATION_SECS } from "../constants/payments";
+import { throwPredicted } from "../utils/anchor-errors";
+/**
+ * @name VaultModule
+ * @description Manages encrypted memory vaults for the Synapse Agent Protocol.
+ *   Provides methods to initialise vaults, open/close sessions, inscribe
+ *   encrypted data, manage delegates (hot wallets), rotate nonces, and
+ *   fetch all related account types.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Initialize a vault
+ * await sap.vault.initVault([...nonce]);
+ * // Open a session and inscribe data
+ * await sap.vault.openSession([...sessionHash]);
+ * ```
+ */
+export class VaultModule extends BaseModule {
+    // ── PDA helpers ──────────────────────────────────────
+    /**
+     * @name deriveVault
+     * @description Derive the `MemoryVault` PDA for a given agent.
+     * @param agentPda - The agent account PDA.
+     * @returns A tuple of `[PublicKey, bump]` for the vault PDA.
+     * @see {@link deriveVault} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveVault(agentPda) {
+        return deriveVault(agentPda);
+    }
+    /**
+     * @name deriveSession
+     * @description Derive the `SessionLedger` PDA for a given vault and session hash.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionHash - A unique session identifier (32 bytes).
+     * @returns A tuple of `[PublicKey, bump]` for the session PDA.
+     * @see {@link deriveSession} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveSession(vaultPda, sessionHash) {
+        return deriveSession(vaultPda, sessionHash);
+    }
+    // ── Vault Lifecycle ──────────────────────────────────
+    /**
+     * @name initVault
+     * @description Initialize an encrypted memory vault for the caller's agent.
+     *   Creates the `MemoryVault` PDA and sets the initial encryption nonce.
+     * @param vaultNonce - The initial encryption nonce (byte array).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async initVault(vaultNonce) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [vaultPda] = deriveVault(agentPda);
+        const [globalPda] = deriveGlobalRegistry();
+        return this.methods
+            .initVault(vaultNonce)
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            vault: vaultPda,
+            globalRegistry: globalPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name openSession
+     * @description Open a new session within a vault. Creates a `SessionLedger`
+     *   PDA identified by the session hash.
+     * @param sessionHash - A unique session identifier (byte array).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async openSession(sessionHash) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [vaultPda] = deriveVault(agentPda);
+        const [sessionPda] = deriveSession(vaultPda, new Uint8Array(sessionHash));
+        return this.methods
+            .openSession(sessionHash)
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            session: sessionPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name inscribe
+     * @description Inscribe encrypted data into the transaction log.
+     *   Account resolution is handled by Anchor via remaining accounts.
+     * @param args - Inscription parameters (sequence, encrypted data, nonce, content hash, fragments, compression, epoch).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async inscribe(args) {
+        // Session PDA is passed via remaining accounts resolution by Anchor
+        // For now, we build accounts manually
+        return this.methods
+            .inscribeMemory(args.sequence, args.encryptedData, args.nonce, args.contentHash, args.totalFragments, args.fragmentIndex, args.compression, args.epochIndex)
+            .rpc();
+    }
+    /**
+     * @name inscribeWithAccounts
+     * @description Full inscribe with explicit session and epoch page PDAs.
+     *   Use this when you need manual control over account resolution.
+     * @param sessionPda - The session ledger PDA.
+     * @param epochPagePda - The epoch page PDA for the target epoch.
+     * @param vaultPda - The memory vault PDA.
+     * @param args - Inscription parameters.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async inscribeWithAccounts(sessionPda, epochPagePda, vaultPda, args) {
+        return this.methods
+            .inscribeMemory(args.sequence, args.encryptedData, args.nonce, args.contentHash, args.totalFragments, args.fragmentIndex, args.compression, args.epochIndex)
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            session: sessionPda,
+            epochPage: epochPagePda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name compactInscribe
+     * @description Simplified inscription (4 args vs 8) for single-fragment writes.
+     * @param sessionPda - The session ledger PDA.
+     * @param vaultPda - The memory vault PDA.
+     * @param args - Compact inscription parameters (sequence, encrypted data, nonce, content hash).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async compactInscribe(sessionPda, vaultPda, args) {
+        return this.methods
+            .compactInscribe(args.sequence, args.encryptedData, args.nonce, args.contentHash)
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            session: sessionPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name closeSession
+     * @description Close a session — no more inscriptions will be allowed.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionPda - The session ledger PDA to close.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async closeSession(vaultPda, sessionPda) {
+        return this.methods
+            .closeSession()
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            session: sessionPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name closeVault
+     * @description Close the `MemoryVault` PDA and reclaim rent to the owner wallet.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async closeVault() {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [vaultPda] = deriveVault(agentPda);
+        return this.methods
+            .closeVault()
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            vault: vaultPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name closeSessionPda
+     * @description Close a `SessionLedger` PDA (session must be closed first).
+     *   Reclaims rent to the owner wallet.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionPda - The session ledger PDA to close.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async closeSessionPda(vaultPda, sessionPda) {
+        return this.methods
+            .closeSessionPda()
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            session: sessionPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name closeEpochPage
+     * @description Close an `EpochPage` PDA and reclaim rent.
+     * @param sessionPda - The session ledger PDA that owns this epoch page.
+     * @param epochIndex - The zero-based epoch index.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async closeEpochPage(sessionPda, epochIndex) {
+        const [epochPda] = deriveEpochPage(sessionPda, epochIndex);
+        return this.methods
+            .closeEpochPage(epochIndex)
+            .accounts({
+            wallet: this.walletPubkey,
+            session: sessionPda,
+            epochPage: epochPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name rotateNonce
+     * @description Rotate the vault encryption nonce. All future inscriptions
+     *   will use the new nonce.
+     * @param newNonce - The replacement nonce (byte array).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async rotateNonce(newNonce) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [vaultPda] = deriveVault(agentPda);
+        return this.methods
+            .rotateVaultNonce(newNonce)
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+        })
+            .rpc();
+    }
+    // ── Delegation ───────────────────────────────────────
+    /**
+     * @name addDelegate
+     * @description Authorize a delegate (hot wallet) for vault operations.
+     *   Creates a `VaultDelegate` PDA with the specified permissions and expiry.
+     * @param delegatePubkey - The public key of the delegate wallet to authorize.
+     * @param permissions - Bitmask of permitted operations.
+     * @param expiresAt - Unix timestamp when delegation expires.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async addDelegate(delegatePubkey, permissions, expiresAt) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [vaultPda] = deriveVault(agentPda);
+        const [delegatePda] = deriveVaultDelegate(vaultPda, delegatePubkey);
+        // v0.13.0 preflight — on-chain rejects expiry > now + MAX_DELEGATE_DURATION_SECS
+        // (365 days). Catch this client-side instead of burning the tx.
+        const exp = typeof expiresAt === "bigint" ? expiresAt : BigInt(expiresAt);
+        const nowSec = BigInt(Math.floor(Date.now() / 1000));
+        if (exp <= nowSec) {
+            throwPredicted("DelegateExpired", `expiresAt ${exp} is in the past (now ${nowSec})`);
+        }
+        const maxExp = nowSec + BigInt(MAX_DELEGATE_DURATION_SECS);
+        if (exp > maxExp) {
+            throwPredicted("DelegateExpiryInvalid", `expiresAt ${exp} > now+MAX (${maxExp}); cap is ${MAX_DELEGATE_DURATION_SECS}s (365 days)`);
+        }
+        if (permissions === 0) {
+            throwPredicted("InvalidDelegate", "permissions bitmask cannot be 0");
+        }
+        await this.requireAccountAbsent("vaultDelegate", delegatePda, "Delegate already exists — revokeDelegate first or use a different delegate wallet");
+        return this.methods
+            .addVaultDelegate(permissions, this.bn(expiresAt))
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            delegate: delegatePda,
+            delegateWallet: delegatePubkey,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name revokeDelegate
+     * @description Revoke a delegate’s authorization, closing their `VaultDelegate` PDA.
+     * @param delegatePubkey - The public key of the delegate wallet to revoke.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async revokeDelegate(delegatePubkey) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [vaultPda] = deriveVault(agentPda);
+        const [delegatePda] = deriveVaultDelegate(vaultPda, delegatePubkey);
+        return this.methods
+            .revokeVaultDelegate()
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            delegate: delegatePda,
+        })
+            .rpc();
+    }
+    /**
+     * @name inscribeDelegated
+     * @description Inscribe data via an authorized delegate (hot wallet).
+     *   The transaction is signed by the delegate instead of the vault owner.
+     * @param delegateWallet - The delegate wallet public key.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionPda - The session ledger PDA.
+     * @param epochPagePda - The epoch page PDA.
+     * @param args - Inscription parameters.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async inscribeDelegated(delegateWallet, vaultPda, sessionPda, epochPagePda, args) {
+        const [delegatePda] = deriveVaultDelegate(vaultPda, delegateWallet);
+        return this.methods
+            .inscribeMemoryDelegated(args.sequence, args.encryptedData, args.nonce, args.contentHash, args.totalFragments, args.fragmentIndex, args.compression, args.epochIndex)
+            .accounts({
+            delegateWallet,
+            vault: vaultPda,
+            delegateAuth: delegatePda,
+            session: sessionPda,
+            epochPage: epochPagePda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    // ── Fetchers ─────────────────────────────────────────
+    /**
+     * @name fetchVault
+     * @description Fetch a deserialized `MemoryVault` account.
+     * @param agentPda - The agent account PDA.
+     * @returns {Promise<MemoryVaultData>} The vault account data.
+     * @throws Will throw if the vault account does not exist.
+     * @since v0.1.0
+     */
+    async fetchVault(agentPda) {
+        const [pda] = deriveVault(agentPda);
+        return this.fetchAccount("memoryVault", pda);
+    }
+    /**
+     * @name fetchVaultNullable
+     * @description Fetch a deserialized `MemoryVault` account, or `null`
+     *   if it does not exist on-chain.
+     * @param agentPda - The agent account PDA.
+     * @returns {Promise<MemoryVaultData | null>} The vault data or `null`.
+     * @since v0.1.0
+     */
+    async fetchVaultNullable(agentPda) {
+        const [pda] = deriveVault(agentPda);
+        return this.fetchAccountNullable("memoryVault", pda);
+    }
+    /**
+     * @name fetchSession
+     * @description Fetch a deserialized `SessionLedger` account by vault and session hash.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionHash - The session identifier used during creation.
+     * @returns {Promise<SessionLedgerData>} The session ledger data.
+     * @throws Will throw if the session does not exist.
+     * @since v0.1.0
+     */
+    async fetchSession(vaultPda, sessionHash) {
+        const [pda] = deriveSession(vaultPda, sessionHash);
+        return this.fetchAccount("sessionLedger", pda);
+    }
+    /**
+     * @name fetchSessionByPda
+     * @description Fetch a deserialized `SessionLedger` account by its PDA directly,
+     *   bypassing PDA derivation.
+     * @param sessionPda - The session ledger PDA.
+     * @returns {Promise<SessionLedgerData>} The session ledger data.
+     * @throws Will throw if the session does not exist.
+     * @since v0.1.0
+     */
+    async fetchSessionByPda(sessionPda) {
+        return this.fetchAccount("sessionLedger", sessionPda);
+    }
+    /**
+     * @name fetchEpochPage
+     * @description Fetch a deserialized `EpochPage` account.
+     * @param sessionPda - The session ledger PDA.
+     * @param epochIndex - The zero-based epoch index.
+     * @returns {Promise<EpochPageData>} The epoch page data.
+     * @throws Will throw if the epoch page does not exist.
+     * @since v0.1.0
+     */
+    async fetchEpochPage(sessionPda, epochIndex) {
+        const [pda] = deriveEpochPage(sessionPda, epochIndex);
+        return this.fetchAccount("epochPage", pda);
+    }
+    /**
+     * @name fetchDelegate
+     * @description Fetch a deserialized `VaultDelegate` account.
+     * @param vaultPda - The memory vault PDA.
+     * @param delegatePubkey - The delegate wallet public key.
+     * @returns {Promise<VaultDelegateData>} The delegate account data.
+     * @throws Will throw if the delegate does not exist.
+     * @since v0.1.0
+     */
+    async fetchDelegate(vaultPda, delegatePubkey) {
+        const [pda] = deriveVaultDelegate(vaultPda, delegatePubkey);
+        return this.fetchAccount("vaultDelegate", pda);
+    }
+}
+//# sourceMappingURL=vault.js.map

package/dist/esm/modules/vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../../../src/modules/vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAA6C,MAAM,iBAAiB,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EACL,WAAW,EACX,WAAW,EACX,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,QAAQ,CAAC;AAShB,OAAO,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,WAAY,SAAQ,UAAU;IACzC,wDAAwD;IAExD;;;;;;;OAOG;IACH,WAAW,CAAC,QAAmB;QAC7B,OAAO,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;;;OAQG;IACH,aAAa,CACX,QAAmB,EACnB,WAAuB;QAEvB,OAAO,aAAa,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;IAED,wDAAwD;IAExD;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS,CAAC,UAAoB;QAClC,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAClD,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,CAAC,SAAS,CAAC,GAAG,oBAAoB,EAAE,CAAC;QAE3C,OAAO,IAAI,CAAC,OAAO;aAChB,SAAS,CAAC,UAAU,CAAC;aACrB,QAAQ,CAAC;YACR,MAAM,EAAE,IAAI,CAAC,YAAY;YACzB,KAAK,EAAE,QAAQ;YACf,KAAK,EAAE,QAAQ;YACf,cAAc,EAAE,SAAS;YACzB,aAAa,EAAE,aAAa,CAAC,SAAS;SACvC,CAAC;aACD,GAAG,EAAE,CAAC;IACX,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,WAAW,CACf,WAAqB;QAErB,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAClD,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,QAAQ,EAAE,IAAI,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;QAE1E,OAAO,IAAI,CAAC,OAAO;aAChB,WAAW,CAAC,WAAW,CAAC;aACxB,QAAQ,CAAC;YACR,MAAM,EAAE,IAAI,CAAC,YAAY;YACzB,KAAK,EAAE,QAAQ;YACf,OAAO,EAAE,UAAU;YACnB,aAAa,EAAE,aAAa,CAAC,SAAS;SACvC,CAAC;aACD,GAAG,EAAE,CAAC;IACX,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,CAAC,IAAwB;QACrC,oEAAoE;QACpE,sCAAsC;QAEtC,OAAO,IAAI,CAAC,OAAO;aAChB,cAAc,CACb,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,aAAa,EAClB,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,cAAc,EACnB,IAAI,CAAC,aAAa,EAClB,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,UAAU,CAChB;aACA,GAAG,EAAE,CAAC;IACX,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,oBAAoB,CACxB,UAAqB,EACrB,YAAuB,EACvB,QAAmB,EACnB,IAAwB;QAExB,OAAO,IAAI,CAAC,OAAO;aAChB,cAAc,CACb,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,aAAa,EAClB,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,cAAc,EACnB,IAAI,CAAC,aAAa,EAClB,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,UAAU,CAChB;aACA,QAAQ,CAAC;YACR,MAAM,EAAE,IAAI,CAAC,YAAY;YACzB,KAAK,EAAE,QAAQ;YACf,OAAO,EAAE,UAAU;YACnB,SAAS,EAAE,YAAY;YACvB,aAAa,EAAE,aAAa,CAAC,SAAS;SACvC,CAAC;aACD,GAAG,EAAE,CAAC;IACX,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,eAAe,CACnB,UAAqB,EACrB,QAAmB,EACnB,IAAyB;QAEzB,OAAO,IAAI,CAAC,OAAO;aAChB,eAAe,CACd,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,aAAa,EAClB,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,WAAW,CACjB;aACA,QAAQ,CAAC;YACR,MAAM,EAAE,IAAI,CAAC,YAAY;YACzB,KAAK,EAAE,QAAQ;YACf,OAAO,EAAE,UAAU;SACpB,CAAC;aACD,GAAG,EAAE,CAAC;IACX,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,YAAY,CAChB,QAAmB,EACnB,UAAqB;QAErB,OAAO,IAAI,CAAC,OAAO;aAChB,YAAY,EAAE;aACd,QAAQ,CAAC;YACR,MAAM,EAAE,IAAI,CAAC,YAAY;YACzB,KAAK,EAAE,QAAQ;YACf,OAAO,EAAE,UAAU;SACpB,CAAC;aACD,GAAG,EAAE,CAAC;IACX,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU;QACd,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAClD,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QAEzC,OAAO,IAAI,CAAC,OAAO;aAChB,UAAU,EAAE;aACZ,QAAQ,CAAC;YACR,MAAM,EAAE,IAAI,CAAC,YAAY;YACzB,KAAK,EAAE,QAAQ;YACf,KAAK,EAAE,QAAQ;SAChB,CAAC;aACD,GAAG,EAAE,CAAC;IACX,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,eAAe,CACnB,QAAmB,EACnB,UAAqB;QAErB,OAAO,IAAI,CAAC,OAAO;aAChB,eAAe,EAAE;aACjB,QAAQ,CAAC;YACR,MAAM,EAAE,IAAI,CAAC,YAAY;YACzB,KAAK,EAAE,QAAQ;YACf,OAAO,EAAE,UAAU;SACpB,CAAC;aACD,GAAG,EAAE,CAAC;IACX,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,cAAc,CAClB,UAAqB,EACrB,UAAkB;QAElB,MAAM,CAAC,QAAQ,CAAC,GAAG,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAE3D,OAAO,IAAI,CAAC,OAAO;aAChB,cAAc,CAAC,UAAU,CAAC;aAC1B,QAAQ,CAAC;YACR,MAAM,EAAE,IAAI,CAAC,YAAY;YACzB,OAAO,EAAE,UAAU;YACnB,SAAS,EAAE,QAAQ;SACpB,CAAC;aACD,GAAG,EAAE,CAAC;IACX,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,WAAW,CACf,QAAkB;QAElB,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAClD,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QAEzC,OAAO,IAAI,CAAC,OAAO;aAChB,gBAAgB,CAAC,QAAQ,CAAC;aAC1B,QAAQ,CAAC;YACR,MAAM,EAAE,IAAI,CAAC,YAAY;YACzB,KAAK,EAAE,QAAQ;SAChB,CAAC;aACD,GAAG,EAAE,CAAC;IACX,CAAC;IAED,wDAAwD;IAExD;;;;;;;;;OASG;IACH,KAAK,CAAC,WAAW,CACf,cAAyB,EACzB,WAAmB,EACnB,SAA0B;QAE1B,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAClD,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,CAAC,WAAW,CAAC,GAAG,mBAAmB,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;QAEpE,iFAAiF;QACjF,gEAAgE;QAChE,MAAM,GAAG,GAAG,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC1E,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;QACrD,IAAI,GAAG,IAAI,MAAM,EAAE,CAAC;YAClB,cAAc,CAAC,iBAAiB,EAAE,aAAa,GAAG,wBAAwB,MAAM,GAAG,CAAC,CAAC;QACvF,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAC;QAC3D,IAAI,GAAG,GAAG,MAAM,EAAE,CAAC;YACjB,cAAc,CACZ,uBAAuB,EACvB,aAAa,GAAG,eAAe,MAAM,aAAa,0BAA0B,cAAc,CAC3F,CAAC;QACJ,CAAC;QACD,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;YACtB,cAAc,CAAC,iBAAiB,EAAE,iCAAiC,CAAC,CAAC;QACvE,CAAC;QACD,MAAM,IAAI,CAAC,oBAAoB,CAC7B,eAAe,EACf,WAAW,EACX,mFAAmF,CACpF,CAAC;QAEF,OAAO,IAAI,CAAC,OAAO;aAChB,gBAAgB,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;aACjD,QAAQ,CAAC;YACR,MAAM,EAAE,IAAI,CAAC,YAAY;YACzB,KAAK,EAAE,QAAQ;YACf,QAAQ,EAAE,WAAW;YACrB,cAAc,EAAE,cAAc;YAC9B,aAAa,EAAE,aAAa,CAAC,SAAS;SACvC,CAAC;aACD,GAAG,EAAE,CAAC;IACX,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,cAAc,CAClB,cAAyB;QAEzB,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAClD,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,CAAC,WAAW,CAAC,GAAG,mBAAmB,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;QAEpE,OAAO,IAAI,CAAC,OAAO;aAChB,mBAAmB,EAAE;aACrB,QAAQ,CAAC;YACR,MAAM,EAAE,IAAI,CAAC,YAAY;YACzB,KAAK,EAAE,QAAQ;YACf,QAAQ,EAAE,WAAW;SACtB,CAAC;aACD,GAAG,EAAE,CAAC;IACX,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,iBAAiB,CACrB,cAAyB,EACzB,QAAmB,EACnB,UAAqB,EACrB,YAAuB,EACvB,IAAwB;QAExB,MAAM,CAAC,WAAW,CAAC,GAAG,mBAAmB,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;QAEpE,OAAO,IAAI,CAAC,OAAO;aAChB,uBAAuB,CACtB,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,aAAa,EAClB,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,cAAc,EACnB,IAAI,CAAC,aAAa,EAClB,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,UAAU,CAChB;aACA,QAAQ,CAAC;YACR,cAAc;YACd,KAAK,EAAE,QAAQ;YACf,YAAY,EAAE,WAAW;YACzB,OAAO,EAAE,UAAU;YACnB,SAAS,EAAE,YAAY;YACvB,aAAa,EAAE,aAAa,CAAC,SAAS;SACvC,CAAC;aACD,GAAG,EAAE,CAAC;IACX,CAAC;IAED,wDAAwD;IAExD;;;;;;;OAOG;IACH,KAAK,CAAC,UAAU,CAAC,QAAmB;QAClC,MAAM,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,YAAY,CAAkB,aAAa,EAAE,GAAG,CAAC,CAAC;IAChE,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,kBAAkB,CAAC,QAAmB;QAC1C,MAAM,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,oBAAoB,CAAkB,aAAa,EAAE,GAAG,CAAC,CAAC;IACxE,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,YAAY,CAChB,QAAmB,EACnB,WAAuB;QAEvB,MAAM,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,YAAY,CAAoB,eAAe,EAAE,GAAG,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,iBAAiB,CAAC,UAAqB;QAC3C,OAAO,IAAI,CAAC,YAAY,CAAoB,eAAe,EAAE,UAAU,CAAC,CAAC;IAC3E,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,cAAc,CAClB,UAAqB,EACrB,UAAkB;QAElB,MAAM,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC,YAAY,CAAgB,WAAW,EAAE,GAAG,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,aAAa,CACjB,QAAmB,EACnB,cAAyB;QAEzB,MAAM,CAAC,GAAG,CAAC,GAAG,mBAAmB,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;QAC5D,OAAO,IAAI,CAAC,YAAY,CAAoB,eAAe,EAAE,GAAG,CAAC,CAAC;IACpE,CAAC;CACF"}

package/dist/esm/parser/client.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @module parser/client
+ * @description Object-oriented wrapper for transaction parsing.
+ *
+ * Binds the Anchor `Program` reference so callers do not need to
+ * pass it on every call. Designed as a lazy singleton accessible
+ * from {@link SapClient.parser}.
+ *
+ * @category Parser
+ * @since v0.5.0
+ *
+ * @example
+ * ```ts
+ * const client = SapClient.from(provider);
+ *
+ * // Parse a full transaction
+ * const parsed = client.parser.parseTransaction(txResponse);
+ *
+ * // Quick instruction names
+ * const names = client.parser.instructionNames(txResponse);
+ *
+ * // From pre-built instructions
+ * const decoded = client.parser.fromInstructions(ixList);
+ * ```
+ */
+import type { Program } from "@coral-xyz/anchor";
+import type { TransactionInstruction, TransactionResponse, VersionedTransactionResponse } from "@solana/web3.js";
+import { AddressLookupTableAccount } from "@solana/web3.js";
+import type { DecodedSapInstruction, ParsedSapTransaction, ParseFilterOptions } from "./types";
+import { type InnerInstructionGroup } from "./inner";
+/**
+ * Stateful transaction parser bound to a specific Anchor `Program`.
+ *
+ * Stores the program reference, instruction coder, and program ID
+ * internally so that repeated parse calls require only the
+ * transaction data as input.
+ *
+ * @name TransactionParser
+ * @category Parser
+ * @since v0.5.0
+ */
+export declare class TransactionParser {
+    private readonly program;
+    private readonly coder;
+    private readonly programId;
+    /**
+     * Create a new TransactionParser.
+     *
+     * @param program - An Anchor `Program` built from the SAP IDL.
+     */
+    constructor(program: Program<any>);
+    /**
+     * Full parse: instructions + inner calls + events.
+     *
+     * @param tx - Raw transaction response from `connection.getTransaction`.
+     * @param options - Optional filters for instructions, events, and inner calls.
+     * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+     * @returns Complete parsed transaction, or `null` if the input is nullish.
+     *
+     * @since v0.5.0
+     */
+    parseTransaction(tx: TransactionResponse | VersionedTransactionResponse | null | undefined, options?: ParseFilterOptions, addressLookupTables?: AddressLookupTableAccount[]): ParsedSapTransaction | null;
+    /**
+     * Parse a batch of transactions.
+     *
+     * @param txs - Array of transaction responses (may contain `null` entries).
+     * @param options - Optional parse filters.
+     * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+     * @returns Non-null parsed transactions.
+     *
+     * @since v0.5.0
+     */
+    parseBatch(txs: (TransactionResponse | VersionedTransactionResponse | null | undefined)[], options?: ParseFilterOptions, addressLookupTables?: AddressLookupTableAccount[]): ParsedSapTransaction[];
+    /**
+     * Decode top-level SAP instructions from a transaction response.
+     *
+     * @param tx - Raw transaction response.
+     * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+     * @returns Decoded SAP instructions.
+     *
+     * @since v0.5.0
+     */
+    instructionsFromTransaction(tx: TransactionResponse | VersionedTransactionResponse, addressLookupTables?: AddressLookupTableAccount[]): DecodedSapInstruction[];
+    /**
+     * Extract only the instruction names from a transaction response.
+     *
+     * @param tx - Raw transaction response.
+     * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+     * @returns Instruction name strings.
+     *
+     * @since v0.5.0
+     */
+    instructionNames(tx: TransactionResponse | VersionedTransactionResponse, addressLookupTables?: AddressLookupTableAccount[]): string[];
+    /**
+     * Decode SAP instructions from a pre-built instruction array.
+     *
+     * @param instructions - The instruction list to decode.
+     * @returns Decoded SAP instructions.
+     *
+     * @since v0.5.0
+     */
+    fromInstructions(instructions: TransactionInstruction[]): DecodedSapInstruction[];
+    /**
+     * Check if any instruction in the list targets the SAP program.
+     *
+     * @param instructions - The instruction array to inspect.
+     * @returns `true` if at least one instruction targets SAP.
+     *
+     * @since v0.5.0
+     */
+    isSapTransaction(instructions: TransactionInstruction[]): boolean;
+    /**
+     * Decode inner (CPI) instructions from transaction metadata.
+     *
+     * @param innerGroups - The `tx.meta.innerInstructions` array.
+     * @param tx - The transaction response (for account key resolution).
+     * @returns Decoded inner instructions.
+     *
+     * @since v0.5.0
+     */
+    decodeInner(innerGroups: InnerInstructionGroup[], tx: TransactionResponse | VersionedTransactionResponse): import("./types").DecodedInnerInstruction[];
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/esm/parser/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/parser/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAEV,sBAAsB,EACtB,mBAAmB,EACnB,4BAA4B,EAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAEnB,MAAM,SAAS,CAAC;AAIjB,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB;IAUhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IATpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC;;;;OAIG;gBAE0B,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC;IAKlD;;;;;;;;;OASG;IACH,gBAAgB,CACd,EAAE,EAAE,mBAAmB,GAAG,4BAA4B,GAAG,IAAI,GAAG,SAAS,EACzE,OAAO,CAAC,EAAE,kBAAkB,EAC5B,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,oBAAoB,GAAG,IAAI;IAU9B;;;;;;;;;OASG;IACH,UAAU,CACR,GAAG,EAAE,CAAC,mBAAmB,GAAG,4BAA4B,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EAC9E,OAAO,CAAC,EAAE,kBAAkB,EAC5B,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,oBAAoB,EAAE;IAUzB;;;;;;;;OAQG;IACH,2BAA2B,CACzB,EAAE,EAAE,mBAAmB,GAAG,4BAA4B,EACtD,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,qBAAqB,EAAE;IAS1B;;;;;;;;OAQG;IACH,gBAAgB,CACd,EAAE,EAAE,mBAAmB,GAAG,4BAA4B,EACtD,mBAAmB,CAAC,EAAE,yBAAyB,EAAE,GAChD,MAAM,EAAE;IAMX;;;;;;;OAOG;IACH,gBAAgB,CACd,YAAY,EAAE,sBAAsB,EAAE,GACrC,qBAAqB,EAAE;IAI1B;;;;;;;OAOG;IACH,gBAAgB,CAAC,YAAY,EAAE,sBAAsB,EAAE,GAAG,OAAO;IAIjE;;;;;;;;OAQG;IACH,WAAW,CACT,WAAW,EAAE,qBAAqB,EAAE,EACpC,EAAE,EAAE,mBAAmB,GAAG,4BAA4B;CAUzD"}