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

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

@@ -0,0 +1,154 @@
+/**
+ * @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/esm/parser/types.d.ts.map

@@ -0,0 +1 @@
+{"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"}

package/dist/esm/parser/types.js

@@ -0,0 +1,13 @@
+/**
+ * @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
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/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/pda/index.d.ts

@@ -0,0 +1,510 @@
+/**
+ * @module pda
+ * @description Deterministic PDA derivation for every SAP v2 account.
+ *
+ * Each function returns `[PublicKey, bump]` and is pure — no network
+ * calls. All results are memoizable by the caller.
+ *
+ * Seeds mirror the Rust `#[account(seeds = [...])]` definitions exactly.
+ *
+ * @category PDA
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { deriveAgent, deriveEscrow } from "@synapse-sap/sdk/pda";
+ *
+ * const [agentPda, bump] = deriveAgent(walletPublicKey);
+ * const [escrowPda] = deriveEscrow(agentPda, depositor);
+ * ```
+ */
+import { PublicKey } from "@solana/web3.js";
+/**
+ * Tuple returned by all PDA derivation functions.
+ *
+ * @name PdaResult
+ * @description A readonly tuple of `[pda, bump]` where `pda` is the derived
+ *   `PublicKey` and `bump` is the canonical bump seed (`u8`).
+ * @category PDA
+ * @since v0.1.0
+ */
+type PdaResult = readonly [pda: PublicKey, bump: number];
+/**
+ * Derive the **GlobalRegistry** PDA.
+ *
+ * Seeds: `["sap_global"]`
+ *
+ * @name deriveGlobalRegistry
+ * @description Returns the singleton global registry address used by the SAP program.
+ * @param programId - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see GlobalRegistry account type
+ */
+export declare const deriveGlobalRegistry: (programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **AgentAccount** PDA for a given wallet.
+ *
+ * Seeds: `["sap_agent", wallet]`
+ *
+ * @name deriveAgent
+ * @description Computes the unique agent PDA owned by `wallet`.
+ * @param wallet    - The agent owner’s wallet `PublicKey`.
+ * @param programId - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see AgentAccount
+ */
+export declare const deriveAgent: (wallet: PublicKey, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **AgentStats** PDA for a given agent.
+ *
+ * Seeds: `["sap_stats", agent_pda]`
+ *
+ * @name deriveAgentStats
+ * @description Computes the stats account PDA associated with an agent.
+ * @param agentPda  - The agent’s on-chain PDA.
+ * @param programId - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see AgentStats
+ */
+export declare const deriveAgentStats: (agentPda: PublicKey, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **Feedback** PDA for a reviewer on a specific agent.
+ *
+ * Seeds: `["sap_feedback", agent_pda, reviewer_wallet]`
+ *
+ * @name deriveFeedback
+ * @description Computes the feedback account PDA scoped to a reviewer–agent pair.
+ * @param agentPda  - The target agent’s PDA.
+ * @param reviewer  - The reviewer’s wallet `PublicKey`.
+ * @param programId - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see FeedbackAccount
+ */
+export declare const deriveFeedback: (agentPda: PublicKey, reviewer: PublicKey, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **CapabilityIndex** PDA for a hashed capability string.
+ *
+ * Seeds: `["sap_cap_idx", capability_hash]`
+ *
+ * @name deriveCapabilityIndex
+ * @description Computes the capability index PDA used to look up agents by capability.
+ * @param capabilityHash - SHA-256 hash of the capability string (32 bytes).
+ * @param programId      - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see CapabilityIndex
+ */
+export declare const deriveCapabilityIndex: (capabilityHash: Uint8Array, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **ProtocolIndex** PDA for a hashed protocol string.
+ *
+ * Seeds: `["sap_proto_idx", protocol_hash]`
+ *
+ * @name deriveProtocolIndex
+ * @description Computes the protocol index PDA used to look up agents by protocol.
+ * @param protocolHash - SHA-256 hash of the protocol string (32 bytes).
+ * @param programId    - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see ProtocolIndex
+ */
+export declare const deriveProtocolIndex: (protocolHash: Uint8Array, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **ToolCategoryIndex** PDA for a tool category discriminant.
+ *
+ * Seeds: `["sap_tool_cat", category_u8]`
+ *
+ * @name deriveToolCategoryIndex
+ * @description Computes the tool category index PDA used to look up tools by category.
+ * @param category  - The `u8` category discriminant (see {@link TOOL_CATEGORY_VALUES}).
+ * @param programId - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see ToolCategoryIndex
+ */
+export declare const deriveToolCategoryIndex: (category: number, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **MemoryVault** PDA for a given agent.
+ *
+ * Seeds: `["sap_vault", agent_pda]`
+ *
+ * @name deriveVault
+ * @description Computes the memory vault PDA owned by the specified agent.
+ * @param agentPda  - The agent’s on-chain PDA.
+ * @param programId - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see MemoryVault
+ */
+export declare const deriveVault: (agentPda: PublicKey, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **Session** PDA for a vault and session hash.
+ *
+ * Seeds: `["sap_session", vault_pda, session_hash]`
+ *
+ * @name deriveSession
+ * @description Computes the session PDA scoped to a vault and unique session identifier.
+ * @param vaultPda    - The parent vault’s PDA.
+ * @param sessionHash - SHA-256 hash identifying the session (32 bytes).
+ * @param programId   - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see SessionAccount
+ */
+export declare const deriveSession: (vaultPda: PublicKey, sessionHash: Uint8Array, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **EpochPage** PDA for a session at a given epoch index.
+ *
+ * Seeds: `["sap_epoch", session_pda, epoch_index_u32_le]`
+ *
+ * @name deriveEpochPage
+ * @description Computes the epoch page PDA for paginated memory inscriptions.
+ * @param sessionPda - The parent session’s PDA.
+ * @param epochIndex - Zero-based epoch page index.
+ * @param programId  - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see EpochPage
+ */
+export declare const deriveEpochPage: (sessionPda: PublicKey, epochIndex: number, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **VaultDelegate** PDA for a delegate on a vault.
+ *
+ * Seeds: `["sap_delegate", vault_pda, delegate_pubkey]`
+ *
+ * @name deriveVaultDelegate
+ * @description Computes the delegate authorization PDA granting a wallet write access to a vault.
+ * @param vaultPda  - The parent vault’s PDA.
+ * @param delegate  - The delegate’s wallet `PublicKey`.
+ * @param programId - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see VaultDelegate
+ */
+export declare const deriveVaultDelegate: (vaultPda: PublicKey, delegate: PublicKey, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **Checkpoint** PDA for a session at a given checkpoint index.
+ *
+ * Seeds: `["sap_checkpoint", session_pda, checkpoint_index_u32_le]`
+ *
+ * @name deriveCheckpoint
+ * @description Computes the checkpoint PDA storing a Merkle snapshot of session state.
+ * @param sessionPda      - The parent session’s PDA.
+ * @param checkpointIndex - Zero-based checkpoint index.
+ * @param programId       - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see Checkpoint
+ */
+export declare const deriveCheckpoint: (sessionPda: PublicKey, checkpointIndex: number, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **Tool** PDA for an agent and tool name hash.
+ *
+ * Seeds: `["sap_tool", agent_pda, tool_name_hash]`
+ *
+ * @name deriveTool
+ * @description Computes the tool registration PDA scoped to an agent and tool identifier.
+ * @param agentPda     - The owning agent’s PDA.
+ * @param toolNameHash - SHA-256 hash of the tool name (32 bytes).
+ * @param programId    - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see ToolAccount
+ */
+export declare const deriveTool: (agentPda: PublicKey, toolNameHash: Uint8Array, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **Escrow** PDA for an agent–depositor pair.
+ *
+ * Seeds: `["sap_escrow", agent_pda, depositor_wallet]`
+ *
+ * @name deriveEscrow
+ * @description Computes the escrow PDA holding deposited funds for service payments.
+ * @param agentPda  - The service-providing agent’s PDA.
+ * @param depositor - The depositor’s wallet `PublicKey`.
+ * @param programId - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @deprecated Since v0.7.0 — Use {@link deriveEscrowV2} for V2 escrows with nonce support.
+ * @see EscrowAccount
+ */
+export declare const deriveEscrow: (agentPda: PublicKey, depositor: PublicKey, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **Attestation** PDA for an attester on a specific agent.
+ *
+ * Seeds: `["sap_attest", agent_pda, attester_wallet]`
+ *
+ * @name deriveAttestation
+ * @description Computes the attestation PDA recording a third-party’s trust assertion.
+ * @param agentPda  - The attested agent’s PDA.
+ * @param attester  - The attester’s wallet `PublicKey`.
+ * @param programId - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see AttestationAccount
+ */
+export declare const deriveAttestation: (agentPda: PublicKey, attester: PublicKey, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **MemoryLedger** PDA for a session.
+ *
+ * Seeds: `["sap_ledger", session_pda]`
+ *
+ * @name deriveLedger
+ * @description Computes the ledger PDA that tracks append-only entries for a session.
+ * @param sessionPda - The parent session’s PDA.
+ * @param programId  - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see MemoryLedger
+ */
+export declare const deriveLedger: (sessionPda: PublicKey, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **LedgerPage** PDA for a ledger at a given page index.
+ *
+ * Seeds: `["sap_page", ledger_pda, page_index_u32_le]`
+ *
+ * @name deriveLedgerPage
+ * @description Computes the ledger page PDA for paginated ledger data storage.
+ * @param ledgerPda - The parent ledger’s PDA.
+ * @param pageIndex - Zero-based page index.
+ * @param programId - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ * @see LedgerPage
+ */
+export declare const deriveLedgerPage: (ledgerPda: PublicKey, pageIndex: number, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **MemoryBuffer** PDA for a session at a given page index.
+ *
+ * Seeds: `["sap_buffer", session_pda, page_index_u32_le]`
+ *
+ * @name deriveBuffer
+ * @description Computes the buffer page PDA for chunked memory writes within a session.
+ * @param sessionPda - The parent session's PDA.
+ * @param pageIndex  - Zero-based page index.
+ * @param programId  - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.3.1
+ * @see MemoryBuffer
+ */
+export declare const deriveBuffer: (sessionPda: PublicKey, pageIndex: number, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **SessionDigest** PDA for a session.
+ *
+ * Seeds: `["sap_digest", session_pda]`
+ *
+ * @name deriveDigest
+ * @description Computes the digest PDA that stores a compact hash summary of a session.
+ * @param sessionPda - The parent session's PDA.
+ * @param programId  - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.3.1
+ * @see SessionDigest
+ */
+export declare const deriveDigest: (sessionPda: PublicKey, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **PluginConfig** PDA for an agent and plugin type.
+ *
+ * Seeds: `["sap_plugin", agent_pda, plugin_type_u8]`
+ *
+ * @name derivePlugin
+ * @description Computes the plugin configuration PDA scoped to an agent and plugin type.
+ * @param agentPda   - The owning agent's PDA.
+ * @param pluginType - The `u8` plugin type discriminant.
+ * @param programId  - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.3.1
+ * @see PluginConfig
+ */
+export declare const derivePlugin: (agentPda: PublicKey, pluginType: number, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **MemoryEntry** PDA for an agent and entry hash.
+ *
+ * Seeds: `["sap_memory", agent_pda, entry_hash]`
+ *
+ * @name deriveMemoryEntry
+ * @description Computes the memory entry PDA for legacy key-value memory storage.
+ * @param agentPda  - The owning agent's PDA.
+ * @param entryHash - SHA-256 hash of the entry key (32 bytes).
+ * @param programId - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.3.1
+ * @see MemoryEntry
+ */
+export declare const deriveMemoryEntry: (agentPda: PublicKey, entryHash: Uint8Array, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **MemoryChunk** PDA for a memory entry at a given chunk index.
+ *
+ * Seeds: `["sap_mem_chunk", memory_entry_pda, chunk_index_u8]`
+ *
+ * @name deriveMemoryChunk
+ * @description Computes the chunk PDA for fragmented memory entry data.
+ * @param memoryEntryPda - The parent memory entry's PDA.
+ * @param chunkIndex     - Zero-based chunk index (0–255).
+ * @param programId      - Override program ID (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.3.1
+ * @see MemoryChunk
+ */
+export declare const deriveMemoryChunk: (memoryEntryPda: PublicKey, chunkIndex: number, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **EscrowAccountV2** PDA.
+ *
+ * Seeds: `["sap_escrow_v2", agent_pda, depositor_wallet, nonce_u64_le]`
+ *
+ * @name deriveEscrowV2
+ * @description Computes the V2 escrow PDA supporting nonce-based multi-escrow.
+ * @param agentPda  - The agent's PDA.
+ * @param depositor - The depositor's wallet.
+ * @param nonce     - Escrow nonce (u64) allowing multiple escrows per pair.
+ * @param programId - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export declare const deriveEscrowV2: (agentPda: PublicKey, depositor: PublicKey, nonce?: number | bigint, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **PendingSettlement** PDA.
+ *
+ * Seeds: `["sap_pending", escrow_v2_pda, settlement_index_u64_le]`
+ *
+ * @name derivePendingSettlement
+ * @param escrowV2Pda     - The parent V2 escrow PDA.
+ * @param settlementIndex - The monotonic settlement index (u64).
+ * @param programId       - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export declare const derivePendingSettlement: (escrowV2Pda: PublicKey, settlementIndex: number | bigint, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **DisputeRecord** PDA.
+ *
+ * Seeds: `["sap_dispute", pending_settlement_pda]`
+ *
+ * @name deriveDispute
+ * @param pendingSettlementPda - The parent pending settlement PDA.
+ * @param programId            - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export declare const deriveDispute: (pendingSettlementPda: PublicKey, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **AgentStake** PDA.
+ *
+ * Seeds: `["sap_stake", agent_pda]`
+ *
+ * @name deriveStake
+ * @param agentPda  - The agent's PDA.
+ * @param programId - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export declare const deriveStake: (agentPda: PublicKey, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **Subscription** PDA.
+ *
+ * Seeds: `["sap_sub", agent_pda, subscriber_wallet, sub_id_u64_le]`
+ *
+ * @name deriveSubscription
+ * @param agentPda   - The agent's PDA.
+ * @param subscriber - The subscriber's wallet.
+ * @param subId      - Subscription ID (u64).
+ * @param programId  - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export declare const deriveSubscription: (agentPda: PublicKey, subscriber: PublicKey, subId?: number | bigint, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **CounterShard** PDA.
+ *
+ * Seeds: `["sap_shard", shard_index_u8]`
+ *
+ * @name deriveShard
+ * @param shardIndex - The shard index (0–7).
+ * @param programId  - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export declare const deriveShard: (shardIndex: number, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **IndexPage** PDA.
+ *
+ * Seeds: `["sap_idx_page", parent_index_pda, page_index_u8]`
+ *
+ * @name deriveIndexPage
+ * @param parentIndexPda - The parent index PDA (CapabilityIndex, ProtocolIndex, etc.).
+ * @param pageIndex      - The page index (0–255).
+ * @param programId      - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export declare const deriveIndexPage: (parentIndexPda: PublicKey, pageIndex: number, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **ReceiptBatch** PDA.
+ *
+ * Seeds: `["sap_receipt", escrow_v2_pda, batch_index_u32_le]`
+ *
+ * @name deriveReceiptBatch
+ * @description Computes the receipt batch PDA storing a merkle root of call receipts.
+ * @param escrowV2Pda - The parent V2 escrow PDA.
+ * @param batchIndex  - Zero-based batch index (u32).
+ * @param programId   - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.7.0
+ */
+export declare const deriveReceiptBatch: (escrowV2Pda: PublicKey, batchIndex: number, programId?: PublicKey) => PdaResult;
+/**
+ * Derive the **SettlementReceipt** PDA (v0.10.0 anti-replay).
+ *
+ * Seeds: `["sap_recv", escrow_pda, service_hash_or_batch_root]`
+ *
+ * Created via `init` on every `settle_calls`, `settle_batch`, and
+ * `settle_calls_v2`. The PDA's existence after the first call blocks
+ * any future replay of the same `service_hash` (or `batch_root`)
+ * against the same escrow.
+ *
+ * @name deriveSettlementReceipt
+ * @description Compute the receipt PDA that gates settlement replay.
+ * @param escrowPda     - Parent escrow PDA (V1 `EscrowAccount` or V2 `EscrowAccountV2`).
+ * @param receiptKey    - 32-byte `service_hash` (single settle / V2 settle)
+ *                        or `batch_root = sha256(s_0 || ... || s_{N-1})` (settle_batch).
+ * @param programId     - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.10.0
+ */
+export declare const deriveSettlementReceipt: (escrowPda: PublicKey, receiptKey: Uint8Array | number[] | Buffer, programId?: PublicKey) => PdaResult;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/pda/index.d.ts.map

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