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

package/dist/esm/modules/tools.js

@@ -0,0 +1,341 @@
+/**
+ * @module tools
+ * @description Tool schema registry and session checkpoints for the
+ * Synapse Agent Protocol.
+ *
+ * Covers: publish, inscribe schema, update, deactivate/reactivate,
+ * close, report invocations, and session checkpoint management.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+import { SystemProgram } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import { deriveAgent, deriveTool, deriveCheckpoint, deriveGlobalRegistry, } from "../pda";
+import { sha256, hashToArray } from "../utils";
+import { throwPredicted } from "../utils/anchor-errors";
+/**
+ * @name ToolsModule
+ * @description Manages tool descriptors and session checkpoints for the
+ *   Synapse Agent Protocol. Provides methods to publish, update, deactivate,
+ *   reactivate, close, and fetch tool descriptors, as well as inscribe
+ *   JSON schemas into TX logs and manage session checkpoints.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Publish a tool by name (auto-hashes)
+ * const sig = await sap.tools.publishByName(
+ *   "getWeather", "mcp-v1", "Fetch weather",
+ *   '{"type":"object"}', '{"type":"object"}',
+ *   0, 1, 2, 1, false,
+ * );
+ * ```
+ */
+export class ToolsModule extends BaseModule {
+    // ── PDA helpers ──────────────────────────────────────
+    /**
+     * @name deriveTool
+     * @description Derive the `ToolDescriptor` PDA for a given agent and tool name.
+     *   The tool name is SHA-256 hashed internally.
+     * @param agentPda - The agent account PDA.
+     * @param toolName - The human-readable tool name.
+     * @returns A tuple of `[PublicKey, bump]` for the tool PDA.
+     * @see {@link deriveTool} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveTool(agentPda, toolName) {
+        return deriveTool(agentPda, sha256(toolName));
+    }
+    // ── Instructions ─────────────────────────────────────
+    /**
+     * @name publish
+     * @description Publish a new tool descriptor for an agent using pre-computed
+     *   hashes. For auto-hashing, prefer {@link publishByName}.
+     * @param args - Tool publication parameters (name, hashes, HTTP method, category, params, etc.).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async publish(args) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [toolPda] = deriveTool(agentPda, new Uint8Array(args.toolNameHash));
+        const [globalPda] = deriveGlobalRegistry();
+        // v0.13.0 preflights — enforce SAP v0.2.0 hardening rules
+        if (!args.toolName || args.toolName.length === 0) {
+            throwPredicted("EmptyToolName");
+        }
+        if (Buffer.byteLength(args.toolName, "utf8") > 32) {
+            throwPredicted("ToolNameTooLong", `${Buffer.byteLength(args.toolName, "utf8")} > 32 bytes`);
+        }
+        // v0.2.0 hardening: every tool MUST publish a non-empty input/output schema
+        // hash. Zero-hash tools are not callable by automated clients (LLMs/routers).
+        const isZeroHash = (h) => h.length === 32 && h.every((b) => b === 0);
+        if (!args.inputSchemaHash || args.inputSchemaHash.length !== 32 || isZeroHash(args.inputSchemaHash)) {
+            throwPredicted("InvalidSchemaHash", "inputSchemaHash is empty/zero — v0.2.0 requires every tool to declare a JSON-Schema. Use publishByName() or precompute sha256(schemaJson).");
+        }
+        if (!args.outputSchemaHash || args.outputSchemaHash.length !== 32 || isZeroHash(args.outputSchemaHash)) {
+            throwPredicted("InvalidSchemaHash", "outputSchemaHash is empty/zero — v0.2.0 requires every tool to declare a JSON-Schema.");
+        }
+        await this.requireAccountAbsent("toolDescriptor", toolPda, "Tool already published with this name; use update() to change schema/version");
+        return this.methods
+            .publishTool(args.toolName, args.toolNameHash, args.protocolHash, args.descriptionHash, args.inputSchemaHash, args.outputSchemaHash, args.httpMethod, args.category, args.paramsCount, args.requiredParams, args.isCompound)
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            tool: toolPda,
+            globalRegistry: globalPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name publishByName
+     * @description Convenience method to publish a tool using string names.
+     *   All string arguments are automatically SHA-256 hashed.
+     * @param toolName - Human-readable tool name.
+     * @param protocolId - Protocol identifier (e.g. `"mcp-v1"`).
+     * @param description - Tool description text.
+     * @param inputSchema - JSON schema string for input validation.
+     * @param outputSchema - JSON schema string for output validation.
+     * @param httpMethod - Numeric HTTP method enum value.
+     * @param category - Numeric tool category enum value.
+     * @param paramsCount - Total number of parameters.
+     * @param requiredParams - Number of required parameters.
+     * @param isCompound - Whether the tool is a compound (multi-step) tool.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async publishByName(toolName, protocolId, description, inputSchema, outputSchema, httpMethod, category, paramsCount, requiredParams, isCompound) {
+        // v0.13.0 preflight — reject empty schemas BEFORE hashing (otherwise the
+        // hash of an empty string slips past the publish() schema-hash check).
+        if (!inputSchema || inputSchema.trim().length === 0) {
+            throwPredicted("InvalidSchemaHash", "inputSchema string is empty — pass a valid JSON-Schema (v0.2.0 requirement)");
+        }
+        if (!outputSchema || outputSchema.trim().length === 0) {
+            throwPredicted("InvalidSchemaHash", "outputSchema string is empty — pass a valid JSON-Schema (v0.2.0 requirement)");
+        }
+        return this.publish({
+            toolName,
+            toolNameHash: hashToArray(sha256(toolName)),
+            protocolHash: hashToArray(sha256(protocolId)),
+            descriptionHash: hashToArray(sha256(description)),
+            inputSchemaHash: hashToArray(sha256(inputSchema)),
+            outputSchemaHash: hashToArray(sha256(outputSchema)),
+            httpMethod,
+            category,
+            paramsCount,
+            requiredParams,
+            isCompound,
+        });
+    }
+    /**
+     * @name inscribeSchema
+     * @description Inscribe a full JSON schema into the transaction log (zero rent).
+     *   The schema is stored as TX log data, not as PDA account data.
+     * @param toolName - The human-readable tool name.
+     * @param args - Schema inscription parameters (type, data, hash, compression).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async inscribeSchema(toolName, args) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [toolPda] = this.deriveTool(agentPda, toolName);
+        return this.methods
+            .inscribeToolSchema(args.schemaType, args.schemaData, args.schemaHash, args.compression)
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            tool: toolPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name update
+     * @description Update a tool’s schema hashes and bump its version.
+     *   All fields are optional — only non-null values are written.
+     * @param toolName - The human-readable tool name.
+     * @param args - Partial update parameters (hashes, method, category, params).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async update(toolName, args) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [toolPda] = this.deriveTool(agentPda, toolName);
+        return this.methods
+            .updateTool(args.descriptionHash ?? null, args.inputSchemaHash ?? null, args.outputSchemaHash ?? null, args.httpMethod ?? null, args.category ?? null, args.paramsCount ?? null, args.requiredParams ?? null)
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            tool: toolPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name deactivate
+     * @description Deactivate a tool. The tool remains discoverable but is
+     *   marked as unavailable.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async deactivate(toolName) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [toolPda] = this.deriveTool(agentPda, toolName);
+        return this.methods
+            .deactivateTool()
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            tool: toolPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name reactivate
+     * @description Reactivate a previously deactivated tool.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async reactivate(toolName) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [toolPda] = this.deriveTool(agentPda, toolName);
+        return this.methods
+            .reactivateTool()
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            tool: toolPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name close
+     * @description Close a tool PDA and reclaim rent to the owner wallet.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async close(toolName) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [toolPda] = this.deriveTool(agentPda, toolName);
+        const [globalPda] = deriveGlobalRegistry();
+        return this.methods
+            .closeTool()
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            tool: toolPda,
+            globalRegistry: globalPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name reportInvocations
+     * @description Report tool invocation count. Updates the on-chain counter
+     *   for analytics and discovery ranking.
+     * @param toolName - The human-readable tool name.
+     * @param invocations - The number of invocations to report.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async reportInvocations(toolName, invocations) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [toolPda] = this.deriveTool(agentPda, toolName);
+        return this.methods
+            .reportToolInvocations(this.bn(invocations))
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            tool: toolPda,
+        })
+            .rpc();
+    }
+    // ── Checkpoints ──────────────────────────────────────
+    /**
+     * @name createCheckpoint
+     * @description Create a checkpoint snapshot of the current session state.
+     *   Checkpoints are indexed by session PDA and checkpoint index.
+     * @param sessionPda - The session ledger PDA.
+     * @param checkpointIndex - The zero-based checkpoint index.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async createCheckpoint(sessionPda, checkpointIndex) {
+        const [checkpointPda] = deriveCheckpoint(sessionPda, checkpointIndex);
+        return this.methods
+            .createSessionCheckpoint(checkpointIndex)
+            .accounts({
+            wallet: this.walletPubkey,
+            session: sessionPda,
+            checkpoint: checkpointPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name closeCheckpoint
+     * @description Close a checkpoint PDA and reclaim rent.
+     * @param sessionPda - The session ledger PDA.
+     * @param checkpointIndex - The zero-based checkpoint index.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async closeCheckpoint(sessionPda, checkpointIndex) {
+        const [checkpointPda] = deriveCheckpoint(sessionPda, checkpointIndex);
+        return this.methods
+            .closeCheckpoint(checkpointIndex)
+            .accounts({
+            wallet: this.walletPubkey,
+            session: sessionPda,
+            checkpoint: checkpointPda,
+        })
+            .rpc();
+    }
+    // ── Fetchers ─────────────────────────────────────────
+    /**
+     * @name fetch
+     * @description Fetch a deserialized `ToolDescriptor` account.
+     * @param agentPda - The agent account PDA.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<ToolDescriptorData>} The tool descriptor data.
+     * @throws Will throw if the tool descriptor does not exist.
+     * @since v0.1.0
+     */
+    async fetch(agentPda, toolName) {
+        const [pda] = this.deriveTool(agentPda, toolName);
+        return this.fetchAccount("toolDescriptor", pda);
+    }
+    /**
+     * @name fetchNullable
+     * @description Fetch a deserialized `ToolDescriptor` account, or `null`
+     *   if it does not exist on-chain.
+     * @param agentPda - The agent account PDA.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<ToolDescriptorData | null>} The tool data or `null`.
+     * @since v0.1.0
+     */
+    async fetchNullable(agentPda, toolName) {
+        const [pda] = this.deriveTool(agentPda, toolName);
+        return this.fetchAccountNullable("toolDescriptor", pda);
+    }
+    /**
+     * @name fetchCheckpoint
+     * @description Fetch a deserialized `SessionCheckpoint` account by session PDA and index.
+     * @param sessionPda - The session ledger PDA.
+     * @param checkpointIndex - The zero-based checkpoint index.
+     * @returns {Promise<SessionCheckpointData>} The checkpoint data.
+     * @throws Will throw if the checkpoint does not exist.
+     * @since v0.1.0
+     */
+    async fetchCheckpoint(sessionPda, checkpointIndex) {
+        const [pda] = deriveCheckpoint(sessionPda, checkpointIndex);
+        return this.fetchAccount("sessionCheckpoint", pda);
+    }
+}
+//# sourceMappingURL=tools.js.map

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

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

package/dist/esm/modules/vault.d.ts

@@ -0,0 +1,240 @@
+/**
+ * @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 { type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import type { MemoryVaultData, SessionLedgerData, EpochPageData, VaultDelegateData, InscribeMemoryArgs, CompactInscribeArgs } from "../types";
+/**
+ * @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 declare class VaultModule extends BaseModule {
+    /**
+     * @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: PublicKey): readonly [PublicKey, number];
+    /**
+     * @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: PublicKey, sessionHash: Uint8Array): readonly [PublicKey, number];
+    /**
+     * @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
+     */
+    initVault(vaultNonce: number[]): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    openSession(sessionHash: number[]): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    inscribe(args: InscribeMemoryArgs): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    inscribeWithAccounts(sessionPda: PublicKey, epochPagePda: PublicKey, vaultPda: PublicKey, args: InscribeMemoryArgs): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    compactInscribe(sessionPda: PublicKey, vaultPda: PublicKey, args: CompactInscribeArgs): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    closeSession(vaultPda: PublicKey, sessionPda: PublicKey): Promise<TransactionSignature>;
+    /**
+     * @name closeVault
+     * @description Close the `MemoryVault` PDA and reclaim rent to the owner wallet.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    closeVault(): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    closeSessionPda(vaultPda: PublicKey, sessionPda: PublicKey): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    closeEpochPage(sessionPda: PublicKey, epochIndex: number): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    rotateNonce(newNonce: number[]): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    addDelegate(delegatePubkey: PublicKey, permissions: number, expiresAt: number | bigint): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    revokeDelegate(delegatePubkey: PublicKey): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    inscribeDelegated(delegateWallet: PublicKey, vaultPda: PublicKey, sessionPda: PublicKey, epochPagePda: PublicKey, args: InscribeMemoryArgs): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    fetchVault(agentPda: PublicKey): Promise<MemoryVaultData>;
+    /**
+     * @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
+     */
+    fetchVaultNullable(agentPda: PublicKey): Promise<MemoryVaultData | null>;
+    /**
+     * @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
+     */
+    fetchSession(vaultPda: PublicKey, sessionHash: Uint8Array): Promise<SessionLedgerData>;
+    /**
+     * @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
+     */
+    fetchSessionByPda(sessionPda: PublicKey): Promise<SessionLedgerData>;
+    /**
+     * @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
+     */
+    fetchEpochPage(sessionPda: PublicKey, epochIndex: number): Promise<EpochPageData>;
+    /**
+     * @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
+     */
+    fetchDelegate(vaultPda: PublicKey, delegatePubkey: PublicKey): Promise<VaultDelegateData>;
+}
+//# sourceMappingURL=vault.d.ts.map

package/dist/esm/modules/vault.d.ts.map

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