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

package/dist/esm/modules/ledger.js

@@ -0,0 +1,230 @@
+/**
+ * @module ledger
+ * @description Unified on-chain memory — init, write, seal, and close ledger.
+ *
+ * The recommended memory system: fixed-cost PDA with 4 KB ring buffer,
+ * automatic TX log persistence, and rolling merkle proof.
+ * Write cost is TX fee only (~0.000005 SOL). ZERO additional rent.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+import { SystemProgram } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import { deriveLedger, deriveLedgerPage } from "../pda";
+/**
+ * @name LedgerModule
+ * @description Manage on-chain memory ledgers for sessions.
+ * Each session can have one MemoryLedger PDA with a 4KB ring buffer for recent entries.
+ * When the ring buffer fills, it can be sealed into a permanent LedgerPage.
+ * Ledgers are designed for high-frequency writes with minimal cost (~0.000005 SOL per write).
+ * Sealed pages are immutable and stored on-chain (~0.031 SOL per page).
+ */
+/**
+ * @name LedgerModule
+ * @description Manages the unified on-chain memory ledger for the Solana Agent
+ *   Protocol. Provides methods to initialise a ledger with a 4 KB ring buffer,
+ *   write data (TX fee only), seal pages permanently, close ledgers, and
+ *   decode ring buffer contents.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Init ledger, write data, seal
+ * await sap.ledger.init(sessionPda);
+ * await sap.ledger.write(sessionPda, data, contentHash);
+ * await sap.ledger.seal(sessionPda);
+ * ```
+ */
+export class LedgerModule extends BaseModule {
+    // ── PDA helpers ──────────────────────────────────────
+    /**
+     * @name deriveLedger
+     * @description Derive the `MemoryLedger` PDA for a given session.
+     * @param sessionPda - The session ledger PDA.
+     * @returns A tuple of `[PublicKey, bump]` for the ledger PDA.
+     * @see {@link deriveLedger} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveLedger(sessionPda) {
+        return deriveLedger(sessionPda);
+    }
+    /**
+     * @name deriveLedgerPage
+     * @description Derive a `LedgerPage` PDA for a given ledger and page index.
+     * @param ledgerPda - The memory ledger PDA.
+     * @param pageIndex - The zero-based page index.
+     * @returns A tuple of `[PublicKey, bump]` for the page PDA.
+     * @see {@link deriveLedgerPage} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveLedgerPage(ledgerPda, pageIndex) {
+        return deriveLedgerPage(ledgerPda, pageIndex);
+    }
+    // ── Instructions ─────────────────────────────────────
+    /**
+     * @name init
+     * @description Create a `MemoryLedger` with a 4 KB ring buffer (~0.032 SOL rent).
+     * @param sessionPda - The session ledger PDA to attach the ledger to.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async init(sessionPda) {
+        const [ledgerPda] = deriveLedger(sessionPda);
+        return this.methods
+            .initLedger()
+            .accounts({
+            wallet: this.walletPubkey,
+            session: sessionPda,
+            ledger: ledgerPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name write
+     * @description Write data to the ledger (ring buffer + TX log simultaneously).
+     *   Cost: TX fee only (~0.000005 SOL). ZERO additional rent.
+     * @param sessionPda - The session ledger PDA.
+     * @param data - The data payload to write (Buffer or Uint8Array).
+     * @param contentHash - A 32-byte SHA-256 content hash for verification.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async write(sessionPda, data, contentHash) {
+        const [ledgerPda] = deriveLedger(sessionPda);
+        return this.methods
+            .writeLedger(Buffer.from(data), contentHash)
+            .accounts({
+            wallet: this.walletPubkey,
+            session: sessionPda,
+            ledger: ledgerPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name seal
+     * @description Seal the ring buffer into a permanent `LedgerPage`.
+     *   Pages are WRITE-ONCE, NEVER-DELETE: ~0.031 SOL per page.
+     *   Automatically fetches the current page index from the ledger.
+     * @param sessionPda - The session ledger PDA.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async seal(sessionPda) {
+        const [ledgerPda] = deriveLedger(sessionPda);
+        // Fetch ledger to get current page index
+        const ledger = await this.fetchLedger(sessionPda);
+        const [pagePda] = deriveLedgerPage(ledgerPda, ledger.numPages);
+        return this.methods
+            .sealLedger()
+            .accounts({
+            wallet: this.walletPubkey,
+            session: sessionPda,
+            ledger: ledgerPda,
+            page: pagePda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name close
+     * @description Close a ledger PDA and reclaim ~0.032 SOL rent.
+     * @param sessionPda - The session ledger PDA.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async close(sessionPda) {
+        const [ledgerPda] = deriveLedger(sessionPda);
+        return this.methods
+            .closeLedger()
+            .accounts({
+            wallet: this.walletPubkey,
+            session: sessionPda,
+            ledger: ledgerPda,
+        })
+            .rpc();
+    }
+    // ── Fetchers ─────────────────────────────────────────
+    /**
+     * @name fetchLedger
+     * @description Fetch a deserialized `MemoryLedger` account.
+     * @param sessionPda - The session ledger PDA.
+     * @returns {Promise<MemoryLedgerData>} The memory ledger data.
+     * @throws Will throw if the ledger does not exist.
+     * @since v0.1.0
+     */
+    async fetchLedger(sessionPda) {
+        const [pda] = deriveLedger(sessionPda);
+        return this.fetchAccount("memoryLedger", pda);
+    }
+    /**
+     * @name fetchLedgerNullable
+     * @description Fetch a deserialized `MemoryLedger` account, or `null`
+     *   if it does not exist on-chain.
+     * @param sessionPda - The session ledger PDA.
+     * @returns {Promise<MemoryLedgerData | null>} The ledger data or `null`.
+     * @since v0.1.0
+     */
+    async fetchLedgerNullable(sessionPda) {
+        const [pda] = deriveLedger(sessionPda);
+        return this.fetchAccountNullable("memoryLedger", pda);
+    }
+    /**
+     * @name fetchPage
+     * @description Fetch a deserialized sealed `LedgerPage` account.
+     * @param ledgerPda - The memory ledger PDA.
+     * @param pageIndex - The zero-based page index.
+     * @returns {Promise<LedgerPageData>} The ledger page data.
+     * @throws Will throw if the page does not exist.
+     * @since v0.1.0
+     */
+    async fetchPage(ledgerPda, pageIndex) {
+        const [pda] = deriveLedgerPage(ledgerPda, pageIndex);
+        return this.fetchAccount("ledgerPage", pda);
+    }
+    /**
+     * @name fetchPageNullable
+     * @description Fetch a deserialized sealed `LedgerPage` account, or `null`
+     *   if it does not exist on-chain.
+     * @param ledgerPda - The memory ledger PDA.
+     * @param pageIndex - The zero-based page index.
+     * @returns {Promise<LedgerPageData | null>} The page data or `null`.
+     * @since v0.1.0
+     */
+    async fetchPageNullable(ledgerPda, pageIndex) {
+        const [pda] = deriveLedgerPage(ledgerPda, pageIndex);
+        return this.fetchAccountNullable("ledgerPage", pda);
+    }
+    /**
+     * @name decodeRingBuffer
+     * @description Decode the ring buffer into individual entries.
+     *   Each entry is stored as `[u16 LE data_len][data bytes]`.
+     *   An entry with `data_len === 0` acts as the empty sentinel.
+     * @param ring - Raw ring buffer data (byte array or Uint8Array).
+     * @returns {Uint8Array[]} Array of decoded data entries.
+     * @since v0.1.0
+     */
+    decodeRingBuffer(ring) {
+        const buf = Buffer.from(ring);
+        const entries = [];
+        let offset = 0;
+        while (offset + 2 <= buf.length) {
+            const len = buf.readUInt16LE(offset);
+            if (len === 0)
+                break; // empty sentinel
+            offset += 2;
+            if (offset + len > buf.length)
+                break;
+            entries.push(new Uint8Array(buf.subarray(offset, offset + len)));
+            offset += len;
+        }
+        return entries;
+    }
+}
+//# sourceMappingURL=ledger.js.map

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

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

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

@@ -0,0 +1,77 @@
+/**
+ * @module receipt
+ * @description Receipt-based trustless dispute resolution (v0.7).
+ *
+ * Agents inscribe merkle roots of call receipt batches on-chain.
+ * During disputes, agents submit merkle inclusion proofs to prove delivery.
+ * After the proof deadline, anyone can trigger automatic proportional resolution.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @packageDocumentation
+ */
+import { type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { BaseModule } from "./base";
+import type { ReceiptBatchData } from "../types";
+/**
+ * @name ReceiptModule
+ * @description Manages receipt batch inscriptions, merkle proof submissions,
+ * and automatic dispute resolution for the v0.7 trustless settlement layer.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @extends BaseModule
+ */
+export declare class ReceiptModule extends BaseModule {
+    private toNum;
+    deriveReceiptBatch(escrowV2Pda: PublicKey, batchIndex: number): readonly [PublicKey, number];
+    /**
+     * Inscribe a receipt batch merkle root on-chain.
+     *
+     * Called by the **agent** to commit a cryptographic proof of calls delivered.
+     * The `merkleRoot` is the root of a merkle tree whose leaves are individual
+     * call receipt hashes.
+     *
+     * @param depositorWallet - The depositor's wallet (needed for escrow PDA derivation).
+     * @param nonce           - Escrow nonce.
+     * @param batchIndex      - Zero-based batch index (must equal escrow.receipt_batch_count).
+     * @param merkleRoot      - 32-byte merkle root of the receipt batch.
+     * @param callCount       - Number of calls in the batch.
+     * @param periodStart     - Unix timestamp for the start of the covered period.
+     * @param periodEnd       - Unix timestamp for the end of the covered period.
+     */
+    inscribeReceiptBatch(depositorWallet: PublicKey, nonce: BN | number | bigint, batchIndex: number, merkleRoot: number[], callCount: BN | number | bigint, periodStart: BN | number | bigint, periodEnd: BN | number | bigint): Promise<TransactionSignature>;
+    /**
+     * Submit a merkle inclusion proof during a dispute.
+     *
+     * Called by the **agent** to prove delivery of specific calls.
+     * Each proof verifies that a set of receipt hashes are included
+     * in the previously inscribed merkle root.
+     *
+     * @param depositorWallet - The depositor's wallet.
+     * @param nonce           - Escrow nonce.
+     * @param settlementIndex - Index of the disputed pending settlement.
+     * @param batchIndex      - Receipt batch index containing the proof.
+     * @param provenCount     - Number of calls proven in this proof submission.
+     * @param proof           - Array of 32-byte merkle proof hashes.
+     * @param leaf            - The 32-byte leaf hash being proven.
+     */
+    submitReceiptProof(depositorWallet: PublicKey, nonce: BN | number | bigint, settlementIndex: BN | number | bigint, batchIndex: number, provenCount: BN | number | bigint, proof: number[][], leaf: number[]): Promise<TransactionSignature>;
+    /**
+     * Trigger automatic dispute resolution after the proof deadline.
+     *
+     * Permissionless crank — anyone can call this once the deadline has passed.
+     * Resolution is proportional: if the agent proved N of M claimed calls,
+     * N/M of the settlement amount goes to the agent, the rest is refunded.
+     *
+     * @param agentWallet     - The agent's wallet.
+     * @param depositorWallet - The depositor's wallet.
+     * @param nonce           - Escrow nonce.
+     * @param settlementIndex - Index of the disputed pending settlement.
+     */
+    autoResolveDispute(agentWallet: PublicKey, depositorWallet: PublicKey, nonce: BN | number | bigint, settlementIndex: BN | number | bigint): Promise<TransactionSignature>;
+    fetchReceiptBatch(escrowV2Pda: PublicKey, batchIndex: number): Promise<ReceiptBatchData>;
+    fetchReceiptBatchNullable(escrowV2Pda: PublicKey, batchIndex: number): Promise<ReceiptBatchData | null>;
+}
+//# sourceMappingURL=receipt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../../../src/modules/receipt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAUpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;;;;;;;GAQG;AACH,qBAAa,aAAc,SAAQ,UAAU;IAG3C,OAAO,CAAC,KAAK;IAMb,kBAAkB,CAChB,WAAW,EAAE,SAAS,EACtB,UAAU,EAAE,MAAM,GACjB,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC;IAM/B;;;;;;;;;;;;;;OAcG;IACG,oBAAoB,CACxB,eAAe,EAAE,SAAS,EAC1B,KAAK,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,EAC3B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAAE,EACpB,SAAS,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,EAC/B,WAAW,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,EACjC,SAAS,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IAuBhC;;;;;;;;;;;;;;OAcG;IACG,kBAAkB,CACtB,eAAe,EAAE,SAAS,EAC1B,KAAK,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,EAC3B,eAAe,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,EACrC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,EACjC,KAAK,EAAE,MAAM,EAAE,EAAE,EACjB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,oBAAoB,CAAC;IAyBhC;;;;;;;;;;;OAWG;IACG,kBAAkB,CACtB,WAAW,EAAE,SAAS,EACtB,eAAe,EAAE,SAAS,EAC1B,KAAK,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,EAC3B,eAAe,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,GACpC,OAAO,CAAC,oBAAoB,CAAC;IA2B1B,iBAAiB,CACrB,WAAW,EAAE,SAAS,EACtB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,CAAC;IAKtB,yBAAyB,CAC7B,WAAW,EAAE,SAAS,EACtB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;CAIpC"}

package/dist/esm/modules/receipt.js

@@ -0,0 +1,144 @@
+/**
+ * @module receipt
+ * @description Receipt-based trustless dispute resolution (v0.7).
+ *
+ * Agents inscribe merkle roots of call receipt batches on-chain.
+ * During disputes, agents submit merkle inclusion proofs to prove delivery.
+ * After the proof deadline, anyone can trigger automatic proportional resolution.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @packageDocumentation
+ */
+import { SystemProgram, } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { BaseModule } from "./base";
+import { deriveAgent, deriveAgentStats, deriveEscrowV2, derivePendingSettlement as derivePendingPda, deriveDispute as deriveDisputePda, deriveReceiptBatch as deriveReceiptPda, deriveStake, } from "../pda";
+/**
+ * @name ReceiptModule
+ * @description Manages receipt batch inscriptions, merkle proof submissions,
+ * and automatic dispute resolution for the v0.7 trustless settlement layer.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @extends BaseModule
+ */
+export class ReceiptModule extends BaseModule {
+    // ── Helpers ──────────────────────────────────────────
+    toNum(v) {
+        return BN.isBN(v) ? v.toNumber() : Number(v);
+    }
+    // ── PDA helpers ──────────────────────────────────────
+    deriveReceiptBatch(escrowV2Pda, batchIndex) {
+        return deriveReceiptPda(escrowV2Pda, batchIndex);
+    }
+    // ── Instructions ─────────────────────────────────────
+    /**
+     * Inscribe a receipt batch merkle root on-chain.
+     *
+     * Called by the **agent** to commit a cryptographic proof of calls delivered.
+     * The `merkleRoot` is the root of a merkle tree whose leaves are individual
+     * call receipt hashes.
+     *
+     * @param depositorWallet - The depositor's wallet (needed for escrow PDA derivation).
+     * @param nonce           - Escrow nonce.
+     * @param batchIndex      - Zero-based batch index (must equal escrow.receipt_batch_count).
+     * @param merkleRoot      - 32-byte merkle root of the receipt batch.
+     * @param callCount       - Number of calls in the batch.
+     * @param periodStart     - Unix timestamp for the start of the covered period.
+     * @param periodEnd       - Unix timestamp for the end of the covered period.
+     */
+    async inscribeReceiptBatch(depositorWallet, nonce, batchIndex, merkleRoot, callCount, periodStart, periodEnd) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [escrowPda] = deriveEscrowV2(agentPda, depositorWallet, this.toNum(nonce));
+        const [receiptPda] = this.deriveReceiptBatch(escrowPda, batchIndex);
+        return this.methods
+            .inscribeReceiptBatch(batchIndex, merkleRoot, this.bn(callCount), this.bn(periodStart), this.bn(periodEnd))
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            escrow: escrowPda,
+            receiptBatch: receiptPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * Submit a merkle inclusion proof during a dispute.
+     *
+     * Called by the **agent** to prove delivery of specific calls.
+     * Each proof verifies that a set of receipt hashes are included
+     * in the previously inscribed merkle root.
+     *
+     * @param depositorWallet - The depositor's wallet.
+     * @param nonce           - Escrow nonce.
+     * @param settlementIndex - Index of the disputed pending settlement.
+     * @param batchIndex      - Receipt batch index containing the proof.
+     * @param provenCount     - Number of calls proven in this proof submission.
+     * @param proof           - Array of 32-byte merkle proof hashes.
+     * @param leaf            - The 32-byte leaf hash being proven.
+     */
+    async submitReceiptProof(depositorWallet, nonce, settlementIndex, batchIndex, provenCount, proof, leaf) {
+        const [agentPda] = deriveAgent(this.walletPubkey);
+        const [escrowPda] = deriveEscrowV2(agentPda, depositorWallet, this.toNum(nonce));
+        const [pendingPda] = derivePendingPda(escrowPda, this.toNum(settlementIndex));
+        const [disputePda] = deriveDisputePda(pendingPda);
+        const [receiptPda] = this.deriveReceiptBatch(escrowPda, batchIndex);
+        return this.methods
+            .submitReceiptProof(batchIndex, this.bn(provenCount), proof, leaf)
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            escrow: escrowPda,
+            pendingSettlement: pendingPda,
+            dispute: disputePda,
+            receiptBatch: receiptPda,
+        })
+            .rpc();
+    }
+    /**
+     * Trigger automatic dispute resolution after the proof deadline.
+     *
+     * Permissionless crank — anyone can call this once the deadline has passed.
+     * Resolution is proportional: if the agent proved N of M claimed calls,
+     * N/M of the settlement amount goes to the agent, the rest is refunded.
+     *
+     * @param agentWallet     - The agent's wallet.
+     * @param depositorWallet - The depositor's wallet.
+     * @param nonce           - Escrow nonce.
+     * @param settlementIndex - Index of the disputed pending settlement.
+     */
+    async autoResolveDispute(agentWallet, depositorWallet, nonce, settlementIndex) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [escrowPda] = deriveEscrowV2(agentPda, depositorWallet, this.toNum(nonce));
+        const [pendingPda] = derivePendingPda(escrowPda, this.toNum(settlementIndex));
+        const [disputePda] = deriveDisputePda(pendingPda);
+        const [statsPda] = deriveAgentStats(agentPda);
+        // v0.11 H-3: AgentStake is now a typed required account so the slash on
+        // DepositorWins is guaranteed instead of silently skipped.
+        const [stakePda] = deriveStake(agentPda);
+        return this.methods
+            .autoResolveDispute()
+            .accounts({
+            payer: this.walletPubkey,
+            depositor: depositorWallet,
+            agentWallet,
+            escrow: escrowPda,
+            pendingSettlement: pendingPda,
+            dispute: disputePda,
+            agentStats: statsPda,
+            agentStake: stakePda,
+        })
+            .rpc();
+    }
+    // ── Fetchers ─────────────────────────────────────────
+    async fetchReceiptBatch(escrowV2Pda, batchIndex) {
+        const [pda] = this.deriveReceiptBatch(escrowV2Pda, batchIndex);
+        return this.fetchAccount("receiptBatch", pda);
+    }
+    async fetchReceiptBatchNullable(escrowV2Pda, batchIndex) {
+        const [pda] = this.deriveReceiptBatch(escrowV2Pda, batchIndex);
+        return this.fetchAccountNullable("receiptBatch", pda);
+    }
+}
+//# sourceMappingURL=receipt.js.map

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

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

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

@@ -0,0 +1,51 @@
+/**
+ * @module staking
+ * @description Agent staking lifecycle — init, deposit, request unstake,
+ * complete unstake, and fetch stake accounts.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @packageDocumentation
+ */
+import { type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { BaseModule } from "./base";
+import type { AgentStakeData } from "../types";
+/**
+ * @name StakingModule
+ * @description Manages agent stake accounts — init, deposit, unstake, and fetch.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @extends BaseModule
+ */
+export declare class StakingModule extends BaseModule {
+    deriveStake(agentPda: PublicKey): readonly [PublicKey, number];
+    initStake(agentWallet: PublicKey, initialDeposit: BN | number | bigint): Promise<TransactionSignature>;
+    deposit(agentWallet: PublicKey, amount: BN | number | bigint): Promise<TransactionSignature>;
+    requestUnstake(agentWallet: PublicKey, amount: BN | number | bigint): Promise<TransactionSignature>;
+    completeUnstake(agentWallet: PublicKey): Promise<TransactionSignature>;
+    fetch(agentPda: PublicKey): Promise<AgentStakeData>;
+    fetchNullable(agentPda: PublicKey): Promise<AgentStakeData | null>;
+    fetchByPda(stakePda: PublicKey): Promise<AgentStakeData>;
+    /**
+     * Compute the maximum amount that can be requested via `requestUnstake`
+     * without breaching the on-chain {@link MIN_AGENT_STAKE_LAMPORTS} floor.
+     *
+     * Returns 0 if the agent is already at (or below) the floor.
+     *
+     * @since v0.11.0
+     */
+    getMaxUnstakeLamports(stake: AgentStakeData): bigint;
+    /**
+     * Returns the lamport delta the agent must `deposit` to satisfy the
+     * per-escrow stake-coverage requirement for `escrowLamports`. 0 if already
+     * sufficient. Useful for a UI "top up to open this escrow" button.
+     *
+     * Mirrors the on-chain check in `create_escrow_v2` (v0.11 H-1).
+     *
+     * @since v0.11.0
+     */
+    getRequiredTopUp(stake: AgentStakeData, escrowLamports: bigint): bigint;
+}
+//# sourceMappingURL=staking.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"staking.d.ts","sourceRoot":"","sources":["../../../src/modules/staking.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAO/C;;;;;;;GAOG;AACH,qBAAa,aAAc,SAAQ,UAAU;IAG3C,WAAW,CAAC,QAAQ,EAAE,SAAS,GAAG,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC;IAMxD,SAAS,CACb,WAAW,EAAE,SAAS,EACtB,cAAc,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,GACnC,OAAO,CAAC,oBAAoB,CAAC;IA6B1B,OAAO,CACX,WAAW,EAAE,SAAS,EACtB,MAAM,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,GAC3B,OAAO,CAAC,oBAAoB,CAAC;IAyB1B,cAAc,CAClB,WAAW,EAAE,SAAS,EACtB,MAAM,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,GAC3B,OAAO,CAAC,oBAAoB,CAAC;IAoC1B,eAAe,CACnB,WAAW,EAAE,SAAS,GACrB,OAAO,CAAC,oBAAoB,CAAC;IAmC1B,KAAK,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC;IAKnD,aAAa,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAKlE,UAAU,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC;IAM9D;;;;;;;OAOG;IACH,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM;IAMpD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM;CAKxE"}