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

package/dist/cjs/pda/index.js

@@ -0,0 +1,672 @@
+"use strict";
+/**
+ * @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);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveSettlementReceipt = exports.deriveReceiptBatch = exports.deriveIndexPage = exports.deriveShard = exports.deriveSubscription = exports.deriveStake = exports.deriveDispute = exports.derivePendingSettlement = exports.deriveEscrowV2 = exports.deriveMemoryChunk = exports.deriveMemoryEntry = exports.derivePlugin = exports.deriveDigest = exports.deriveBuffer = exports.deriveLedgerPage = exports.deriveLedger = exports.deriveAttestation = exports.deriveEscrow = exports.deriveTool = exports.deriveCheckpoint = exports.deriveVaultDelegate = exports.deriveEpochPage = exports.deriveSession = exports.deriveVault = exports.deriveToolCategoryIndex = exports.deriveProtocolIndex = exports.deriveCapabilityIndex = exports.deriveFeedback = exports.deriveAgentStats = exports.deriveAgent = exports.deriveGlobalRegistry = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const constants_1 = require("../constants");
+// ── Helpers ──────────────────────────────────────────────────────
+/**
+ * Thin wrapper around `PublicKey.findProgramAddressSync`.
+ *
+ * @name findPda
+ * @description Derives a PDA from the given seed buffers and program ID.
+ * @param seeds  - Array of seed `Buffer`s / `Uint8Array`s.
+ * @param programId - The program to derive against (defaults to {@link SAP_PROGRAM_ID}).
+ * @returns {PdaResult} The derived `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.1.0
+ */
+const findPda = (seeds, programId = constants_1.SAP_PROGRAM_ID) => web3_js_1.PublicKey.findProgramAddressSync(seeds, programId);
+/**
+ * Encode a seed string as a UTF-8 `Buffer`.
+ *
+ * @name toSeedBuf
+ * @description Converts a string seed prefix to a `Buffer` suitable for PDA derivation.
+ * @param s - The seed string to encode.
+ * @returns {Buffer} UTF-8 encoded buffer.
+ * @category PDA
+ * @since v0.1.0
+ */
+const toSeedBuf = (s) => Buffer.from(s);
+/**
+ * Encode an unsigned 32-bit integer as a little-endian `Buffer`.
+ *
+ * @name u32le
+ * @description Produces a 4-byte LE buffer for numeric PDA seed segments (e.g., epoch index, page index).
+ * @param n - The number to encode.
+ * @returns {Buffer} 4-byte little-endian buffer.
+ * @category PDA
+ * @since v0.1.0
+ */
+const u32le = (n) => {
+    const buf = Buffer.alloc(4);
+    buf.writeUInt32LE(n, 0);
+    return buf;
+};
+/**
+ * Encode an unsigned 64-bit integer as a little-endian `Buffer`.
+ *
+ * @name u64le
+ * @description Produces an 8-byte LE buffer for u64 PDA seed segments (e.g., escrow nonce, sub_id).
+ * @param n - The number or bigint to encode.
+ * @returns {Buffer} 8-byte little-endian buffer.
+ * @category PDA
+ * @since v0.5.0
+ */
+const u64le = (n) => {
+    const buf = Buffer.alloc(8);
+    buf.writeBigUInt64LE(BigInt(n), 0);
+    return buf;
+};
+// ═════════════════════════════════════════════
+//  Core PDAs
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const deriveGlobalRegistry = (programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.GLOBAL)], programId);
+exports.deriveGlobalRegistry = deriveGlobalRegistry;
+/**
+ * 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
+ */
+const deriveAgent = (wallet, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.AGENT), wallet.toBuffer()], programId);
+exports.deriveAgent = deriveAgent;
+/**
+ * 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
+ */
+const deriveAgentStats = (agentPda, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.STATS), agentPda.toBuffer()], programId);
+exports.deriveAgentStats = deriveAgentStats;
+// ═════════════════════════════════════════════
+//  Feedback
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const deriveFeedback = (agentPda, reviewer, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.FEEDBACK), agentPda.toBuffer(), reviewer.toBuffer()], programId);
+exports.deriveFeedback = deriveFeedback;
+// ═════════════════════════════════════════════
+//  Indexing
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const deriveCapabilityIndex = (capabilityHash, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.CAPABILITY_INDEX), Buffer.from(capabilityHash)], programId);
+exports.deriveCapabilityIndex = deriveCapabilityIndex;
+/**
+ * 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
+ */
+const deriveProtocolIndex = (protocolHash, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.PROTOCOL_INDEX), Buffer.from(protocolHash)], programId);
+exports.deriveProtocolIndex = deriveProtocolIndex;
+/**
+ * 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
+ */
+const deriveToolCategoryIndex = (category, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.TOOL_CATEGORY), Buffer.from([category])], programId);
+exports.deriveToolCategoryIndex = deriveToolCategoryIndex;
+// ═════════════════════════════════════════════
+//  Memory Vault
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const deriveVault = (agentPda, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.VAULT), agentPda.toBuffer()], programId);
+exports.deriveVault = deriveVault;
+/**
+ * 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
+ */
+const deriveSession = (vaultPda, sessionHash, programId = constants_1.SAP_PROGRAM_ID) => findPda([
+    toSeedBuf(constants_1.SEEDS.SESSION),
+    vaultPda.toBuffer(),
+    Buffer.from(sessionHash),
+], programId);
+exports.deriveSession = deriveSession;
+/**
+ * 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
+ */
+const deriveEpochPage = (sessionPda, epochIndex, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.EPOCH), sessionPda.toBuffer(), u32le(epochIndex)], programId);
+exports.deriveEpochPage = deriveEpochPage;
+/**
+ * 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
+ */
+const deriveVaultDelegate = (vaultPda, delegate, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.DELEGATE), vaultPda.toBuffer(), delegate.toBuffer()], programId);
+exports.deriveVaultDelegate = deriveVaultDelegate;
+/**
+ * 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
+ */
+const deriveCheckpoint = (sessionPda, checkpointIndex, programId = constants_1.SAP_PROGRAM_ID) => findPda([
+    toSeedBuf(constants_1.SEEDS.CHECKPOINT),
+    sessionPda.toBuffer(),
+    u32le(checkpointIndex),
+], programId);
+exports.deriveCheckpoint = deriveCheckpoint;
+// ═════════════════════════════════════════════
+//  Tools
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const deriveTool = (agentPda, toolNameHash, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.TOOL), agentPda.toBuffer(), Buffer.from(toolNameHash)], programId);
+exports.deriveTool = deriveTool;
+// ═════════════════════════════════════════════
+//  Escrow
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const deriveEscrow = (agentPda, depositor, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.ESCROW), agentPda.toBuffer(), depositor.toBuffer()], programId);
+exports.deriveEscrow = deriveEscrow;
+// ═════════════════════════════════════════════
+//  Attestation
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const deriveAttestation = (agentPda, attester, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.ATTESTATION), agentPda.toBuffer(), attester.toBuffer()], programId);
+exports.deriveAttestation = deriveAttestation;
+// ═════════════════════════════════════════════
+//  Memory Ledger
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const deriveLedger = (sessionPda, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.LEDGER), sessionPda.toBuffer()], programId);
+exports.deriveLedger = deriveLedger;
+/**
+ * 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
+ */
+const deriveLedgerPage = (ledgerPda, pageIndex, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.LEDGER_PAGE), ledgerPda.toBuffer(), u32le(pageIndex)], programId);
+exports.deriveLedgerPage = deriveLedgerPage;
+// ═════════════════════════════════════════════
+//  Memory Buffer (legacy)
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const deriveBuffer = (sessionPda, pageIndex, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.BUFFER), sessionPda.toBuffer(), u32le(pageIndex)], programId);
+exports.deriveBuffer = deriveBuffer;
+// ═════════════════════════════════════════════
+//  Session Digest
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const deriveDigest = (sessionPda, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.DIGEST), sessionPda.toBuffer()], programId);
+exports.deriveDigest = deriveDigest;
+// ═════════════════════════════════════════════
+//  Plugin
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const derivePlugin = (agentPda, pluginType, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.PLUGIN), agentPda.toBuffer(), Buffer.from([pluginType])], programId);
+exports.derivePlugin = derivePlugin;
+// ═════════════════════════════════════════════
+//  Legacy Memory (entry + chunk)
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const deriveMemoryEntry = (agentPda, entryHash, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.MEMORY), agentPda.toBuffer(), Buffer.from(entryHash)], programId);
+exports.deriveMemoryEntry = deriveMemoryEntry;
+/**
+ * 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
+ */
+const deriveMemoryChunk = (memoryEntryPda, chunkIndex, programId = constants_1.SAP_PROGRAM_ID) => findPda([
+    toSeedBuf(constants_1.SEEDS.MEMORY_CHUNK),
+    memoryEntryPda.toBuffer(),
+    Buffer.from([chunkIndex]),
+], programId);
+exports.deriveMemoryChunk = deriveMemoryChunk;
+// ═════════════════════════════════════════════
+//  Escrow V2
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const deriveEscrowV2 = (agentPda, depositor, nonce = 0, programId = constants_1.SAP_PROGRAM_ID) => findPda([
+    toSeedBuf(constants_1.SEEDS.ESCROW_V2),
+    agentPda.toBuffer(),
+    depositor.toBuffer(),
+    u64le(nonce),
+], programId);
+exports.deriveEscrowV2 = deriveEscrowV2;
+/**
+ * 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
+ */
+const derivePendingSettlement = (escrowV2Pda, settlementIndex, programId = constants_1.SAP_PROGRAM_ID) => findPda([
+    toSeedBuf(constants_1.SEEDS.PENDING),
+    escrowV2Pda.toBuffer(),
+    u64le(settlementIndex),
+], programId);
+exports.derivePendingSettlement = derivePendingSettlement;
+/**
+ * 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
+ */
+const deriveDispute = (pendingSettlementPda, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.DISPUTE), pendingSettlementPda.toBuffer()], programId);
+exports.deriveDispute = deriveDispute;
+/**
+ * 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
+ */
+const deriveStake = (agentPda, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.STAKE), agentPda.toBuffer()], programId);
+exports.deriveStake = deriveStake;
+/**
+ * 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
+ */
+const deriveSubscription = (agentPda, subscriber, subId = 0, programId = constants_1.SAP_PROGRAM_ID) => findPda([
+    toSeedBuf(constants_1.SEEDS.SUBSCRIPTION),
+    agentPda.toBuffer(),
+    subscriber.toBuffer(),
+    u64le(subId),
+], programId);
+exports.deriveSubscription = deriveSubscription;
+/**
+ * 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
+ */
+const deriveShard = (shardIndex, programId = constants_1.SAP_PROGRAM_ID) => findPda([toSeedBuf(constants_1.SEEDS.SHARD), Buffer.from([shardIndex])], programId);
+exports.deriveShard = deriveShard;
+/**
+ * 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
+ */
+const deriveIndexPage = (parentIndexPda, pageIndex, programId = constants_1.SAP_PROGRAM_ID) => findPda([
+    toSeedBuf(constants_1.SEEDS.INDEX_PAGE),
+    parentIndexPda.toBuffer(),
+    Buffer.from([pageIndex]),
+], programId);
+exports.deriveIndexPage = deriveIndexPage;
+// ═════════════════════════════════════════════
+//  Receipt Batch (v0.7)
+// ═════════════════════════════════════════════
+/**
+ * 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
+ */
+const deriveReceiptBatch = (escrowV2Pda, batchIndex, programId = constants_1.SAP_PROGRAM_ID) => findPda([
+    toSeedBuf(constants_1.SEEDS.RECEIPT),
+    escrowV2Pda.toBuffer(),
+    u32le(batchIndex),
+], programId);
+exports.deriveReceiptBatch = deriveReceiptBatch;
+/**
+ * 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
+ */
+const deriveSettlementReceipt = (escrowPda, receiptKey, programId = constants_1.SAP_PROGRAM_ID) => {
+    const buf = Buffer.isBuffer(receiptKey)
+        ? receiptKey
+        : Buffer.from(receiptKey);
+    if (buf.length !== 32) {
+        throw new Error(`deriveSettlementReceipt: receiptKey must be 32 bytes, got ${buf.length}`);
+    }
+    return findPda([toSeedBuf(constants_1.SEEDS.SETTLEMENT_RECEIPT), escrowPda.toBuffer(), buf], programId);
+};
+exports.deriveSettlementReceipt = deriveSettlementReceipt;
+//# sourceMappingURL=index.js.map