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

package/dist/cjs/modules/receipt.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReceiptModule = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const anchor_1 = require("@coral-xyz/anchor");
+const base_1 = require("./base");
+const pda_1 = require("../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
+ */
+class ReceiptModule extends base_1.BaseModule {
+    // ── Helpers ──────────────────────────────────────────
+    toNum(v) {
+        return anchor_1.BN.isBN(v) ? v.toNumber() : Number(v);
+    }
+    // ── PDA helpers ──────────────────────────────────────
+    deriveReceiptBatch(escrowV2Pda, batchIndex) {
+        return (0, pda_1.deriveReceiptBatch)(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] = (0, pda_1.deriveAgent)(this.walletPubkey);
+        const [escrowPda] = (0, pda_1.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: web3_js_1.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] = (0, pda_1.deriveAgent)(this.walletPubkey);
+        const [escrowPda] = (0, pda_1.deriveEscrowV2)(agentPda, depositorWallet, this.toNum(nonce));
+        const [pendingPda] = (0, pda_1.derivePendingSettlement)(escrowPda, this.toNum(settlementIndex));
+        const [disputePda] = (0, pda_1.deriveDispute)(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] = (0, pda_1.deriveAgent)(agentWallet);
+        const [escrowPda] = (0, pda_1.deriveEscrowV2)(agentPda, depositorWallet, this.toNum(nonce));
+        const [pendingPda] = (0, pda_1.derivePendingSettlement)(escrowPda, this.toNum(settlementIndex));
+        const [disputePda] = (0, pda_1.deriveDispute)(pendingPda);
+        const [statsPda] = (0, pda_1.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] = (0, pda_1.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);
+    }
+}
+exports.ReceiptModule = ReceiptModule;
+//# sourceMappingURL=receipt.js.map

package/dist/cjs/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/cjs/modules/staking.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * @module staking
+ * @description Agent staking lifecycle — init, deposit, request unstake,
+ * complete unstake, and fetch stake accounts.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StakingModule = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const base_1 = require("./base");
+const pda_1 = require("../pda");
+const payments_1 = require("../constants/payments");
+const anchor_errors_1 = require("../utils/anchor-errors");
+/**
+ * @name StakingModule
+ * @description Manages agent stake accounts — init, deposit, unstake, and fetch.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @extends BaseModule
+ */
+class StakingModule extends base_1.BaseModule {
+    // ── PDA helpers ──────────────────────────────────────
+    deriveStake(agentPda) {
+        return (0, pda_1.deriveStake)(agentPda);
+    }
+    // ── Instructions ─────────────────────────────────────
+    async initStake(agentWallet, initialDeposit) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [stakePda] = this.deriveStake(agentPda);
+        // v0.13.0 preflights
+        const want = BigInt(this.bn(initialDeposit).toString());
+        if (want < payments_1.MIN_AGENT_STAKE_LAMPORTS) {
+            (0, anchor_errors_1.throwPredicted)("StakeBelowMinimum", `initial deposit ${want} < MIN_AGENT_STAKE_LAMPORTS ${payments_1.MIN_AGENT_STAKE_LAMPORTS}`);
+        }
+        await this.requireAccountAbsent("agentStake", stakePda, "Stake already initialized — use depositStake to top up");
+        return this.methods
+            .initStake(this.bn(initialDeposit))
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            stake: stakePda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .rpc();
+    }
+    async deposit(agentWallet, amount) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [stakePda] = this.deriveStake(agentPda);
+        // v0.13.0 preflight — stake must already exist; amount > 0
+        if (BigInt(this.bn(amount).toString()) <= 0n) {
+            (0, anchor_errors_1.throwPredicted)("InsufficientStake", "Deposit amount must be > 0");
+        }
+        await this.requireAccountExists("agentStake", stakePda, { predicted: "NoStakeAccount", hint: "Call initStake first" });
+        return this.methods
+            .depositStake(this.bn(amount))
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            stake: stakePda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .rpc();
+    }
+    async requestUnstake(agentWallet, amount) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [stakePda] = this.deriveStake(agentPda);
+        // v0.13.0 preflight — enforce MIN_STAKE floor + no double-pending
+        const stake = await this.requireAccountExists("agentStake", stakePda, { predicted: "NoStakeAccount", hint: "No stake account to unstake from" });
+        const want = BigInt(this.bn(amount).toString());
+        if (want <= 0n)
+            (0, anchor_errors_1.throwPredicted)("InsufficientStake", "Unstake amount must be > 0");
+        const max = this.getMaxUnstakeLamports(stake);
+        if (want > max) {
+            (0, anchor_errors_1.throwPredicted)("StakeBelowMinimum", `requested ${want} would drop stake below MIN_AGENT_STAKE_LAMPORTS (max unstake = ${max})`);
+        }
+        if (BigInt(stake.unstakeAmount.toString()) > 0n) {
+            (0, anchor_errors_1.throwPredicted)("UnstakeAlreadyPending", "A pending unstake already exists — completeUnstake first or wait for cooldown");
+        }
+        return this.methods
+            .requestUnstake(this.bn(amount))
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            stake: stakePda,
+        })
+            .rpc();
+    }
+    async completeUnstake(agentWallet) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [stakePda] = this.deriveStake(agentPda);
+        // v0.13.0 preflight — cooldown must have elapsed and an unstake must be pending
+        const stake = await this.requireAccountExists("agentStake", stakePda, { predicted: "NoStakeAccount", hint: "No stake account" });
+        const pending = BigInt(stake.unstakeAmount.toString());
+        if (pending === 0n) {
+            (0, anchor_errors_1.throwPredicted)("NoUnstakePending", "Call requestUnstake first");
+        }
+        const availableAt = BigInt(stake.unstakeAvailableAt.toString());
+        const nowSec = BigInt(Math.floor(Date.now() / 1000));
+        if (nowSec < availableAt) {
+            (0, anchor_errors_1.throwPredicted)("UnstakeCooldownNotMet", `available at unix ${availableAt}, now ${nowSec} (Δ ${availableAt - nowSec}s)`);
+        }
+        return this.methods
+            .completeUnstake()
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            stake: stakePda,
+        })
+            .rpc();
+    }
+    // ── Fetchers ─────────────────────────────────────────
+    async fetch(agentPda) {
+        const [pda] = this.deriveStake(agentPda);
+        return this.fetchAccount("agentStake", pda);
+    }
+    async fetchNullable(agentPda) {
+        const [pda] = this.deriveStake(agentPda);
+        return this.fetchAccountNullable("agentStake", pda);
+    }
+    async fetchByPda(stakePda) {
+        return this.fetchAccount("agentStake", stakePda);
+    }
+    // ── v0.11 helpers ────────────────────────────────────────────
+    /**
+     * 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) {
+        const staked = BigInt(stake.stakedAmount.toString());
+        if (staked <= payments_1.MIN_AGENT_STAKE_LAMPORTS)
+            return 0n;
+        return staked - payments_1.MIN_AGENT_STAKE_LAMPORTS;
+    }
+    /**
+     * 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, escrowLamports) {
+        const required = (0, payments_1.computeRequiredStakeLamports)(escrowLamports);
+        const have = BigInt(stake.stakedAmount.toString());
+        return have >= required ? 0n : required - have;
+    }
+}
+exports.StakingModule = StakingModule;
+//# sourceMappingURL=staking.js.map

package/dist/cjs/modules/staking.js.map

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

package/dist/cjs/modules/subscription.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * @module subscription
+ * @description Agent subscription lifecycle — create, fund, cancel,
+ * close, and fetch subscription accounts.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubscriptionModule = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const anchor_1 = require("@coral-xyz/anchor");
+const base_1 = require("./base");
+const pda_1 = require("../pda");
+/**
+ * @name SubscriptionModule
+ * @description Manages recurring subscriptions between subscribers and agents.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @extends BaseModule
+ */
+class SubscriptionModule extends base_1.BaseModule {
+    // ── PDA helpers ──────────────────────────────────────
+    toNum(v) {
+        return anchor_1.BN.isBN(v) ? v.toNumber() : Number(v);
+    }
+    deriveSubscription(agentPda, subscriber, subId = 0) {
+        return (0, pda_1.deriveSubscription)(agentPda, subscriber ?? this.walletPubkey, this.toNum(subId));
+    }
+    // ── Instructions ─────────────────────────────────────
+    async create(agentWallet, args) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [subPda] = this.deriveSubscription(agentPda, undefined, args.subId);
+        return this.methods
+            .createSubscription(this.bn(args.subId), this.bn(args.pricePerInterval), args.billingInterval, this.bn(args.initialFund))
+            .accounts({
+            subscriber: this.walletPubkey,
+            agent: agentPda,
+            subscription: subPda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .rpc();
+    }
+    async fund(agentWallet, subId, amount) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [subPda] = this.deriveSubscription(agentPda, undefined, subId);
+        return this.methods
+            .fundSubscription(this.bn(amount))
+            .accounts({
+            subscriber: this.walletPubkey,
+            subscription: subPda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .rpc();
+    }
+    async cancel(agentWallet, subId = 0) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [subPda] = this.deriveSubscription(agentPda, undefined, subId);
+        return this.methods
+            .cancelSubscription()
+            .accounts({
+            subscriber: this.walletPubkey,
+            agentWallet,
+            subscription: subPda,
+        })
+            .rpc();
+    }
+    async close(agentWallet, subId = 0) {
+        const [agentPda] = (0, pda_1.deriveAgent)(agentWallet);
+        const [subPda] = this.deriveSubscription(agentPda, undefined, subId);
+        return this.methods
+            .closeSubscription()
+            .accounts({
+            subscriber: this.walletPubkey,
+            subscription: subPda,
+        })
+            .rpc();
+    }
+    // ── Fetchers ─────────────────────────────────────────
+    async fetch(agentPda, subscriber, subId = 0) {
+        const [pda] = this.deriveSubscription(agentPda, subscriber, subId);
+        return this.fetchAccount("subscriptionAccount", pda);
+    }
+    async fetchNullable(agentPda, subscriber, subId = 0) {
+        const [pda] = this.deriveSubscription(agentPda, subscriber, subId);
+        return this.fetchAccountNullable("subscriptionAccount", pda);
+    }
+    async fetchByPda(subPda) {
+        return this.fetchAccount("subscriptionAccount", subPda);
+    }
+}
+exports.SubscriptionModule = SubscriptionModule;
+//# sourceMappingURL=subscription.js.map

package/dist/cjs/modules/subscription.js.map

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