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

package/src/modules/receipt.ts

@@ -1,212 +0,0 @@
-/**
- * @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,
-  type PublicKey,
-  type TransactionSignature,
-} 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";
-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 class ReceiptModule extends BaseModule {
-  // ── Helpers ──────────────────────────────────────────
-
-  private toNum(v: BN | number | bigint): number {
-    return BN.isBN(v) ? v.toNumber() : Number(v);
-  }
-
-  // ── PDA helpers ──────────────────────────────────────
-
-  deriveReceiptBatch(
-    escrowV2Pda: PublicKey,
-    batchIndex: number,
-  ): readonly [PublicKey, number] {
-    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: PublicKey,
-    nonce: BN | number | bigint,
-    batchIndex: number,
-    merkleRoot: number[],
-    callCount: BN | number | bigint,
-    periodStart: BN | number | bigint,
-    periodEnd: BN | number | bigint,
-  ): Promise<TransactionSignature> {
-    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: PublicKey,
-    nonce: BN | number | bigint,
-    settlementIndex: BN | number | bigint,
-    batchIndex: number,
-    provenCount: BN | number | bigint,
-    proof: number[][],
-    leaf: number[],
-  ): Promise<TransactionSignature> {
-    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: PublicKey,
-    depositorWallet: PublicKey,
-    nonce: BN | number | bigint,
-    settlementIndex: BN | number | bigint,
-  ): Promise<TransactionSignature> {
-    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: PublicKey,
-    batchIndex: number,
-  ): Promise<ReceiptBatchData> {
-    const [pda] = this.deriveReceiptBatch(escrowV2Pda, batchIndex);
-    return this.fetchAccount<ReceiptBatchData>("receiptBatch", pda);
-  }
-
-  async fetchReceiptBatchNullable(
-    escrowV2Pda: PublicKey,
-    batchIndex: number,
-  ): Promise<ReceiptBatchData | null> {
-    const [pda] = this.deriveReceiptBatch(escrowV2Pda, batchIndex);
-    return this.fetchAccountNullable<ReceiptBatchData>("receiptBatch", pda);
-  }
-}

package/src/modules/staking.ts

@@ -1,223 +0,0 @@
-/**
- * @module staking
- * @description Agent staking lifecycle — init, deposit, request unstake,
- * complete unstake, and fetch stake accounts.
- *
- * @category Modules
- * @since v0.7.0
- * @packageDocumentation
- */
-
-import {
-  SystemProgram,
-  type PublicKey,
-  type TransactionSignature,
-} from "@solana/web3.js";
-import { BN } from "@coral-xyz/anchor";
-import { BaseModule } from "./base";
-import { deriveAgent, deriveStake } from "../pda";
-import type { AgentStakeData } from "../types";
-import {
-  MIN_AGENT_STAKE_LAMPORTS,
-  computeRequiredStakeLamports,
-} from "../constants/payments";
-import { throwPredicted } from "../utils/anchor-errors";
-
-/**
- * @name StakingModule
- * @description Manages agent stake accounts — init, deposit, unstake, and fetch.
- *
- * @category Modules
- * @since v0.7.0
- * @extends BaseModule
- */
-export class StakingModule extends BaseModule {
-  // ── PDA helpers ──────────────────────────────────────
-
-  deriveStake(agentPda: PublicKey): readonly [PublicKey, number] {
-    return deriveStake(agentPda);
-  }
-
-  // ── Instructions ─────────────────────────────────────
-
-  async initStake(
-    agentWallet: PublicKey,
-    initialDeposit: BN | number | bigint,
-  ): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(agentWallet);
-    const [stakePda] = this.deriveStake(agentPda);
-
-    // v0.13.0 preflights
-    const want = BigInt(this.bn(initialDeposit).toString());
-    if (want < MIN_AGENT_STAKE_LAMPORTS) {
-      throwPredicted(
-        "StakeBelowMinimum",
-        `initial deposit ${want} < MIN_AGENT_STAKE_LAMPORTS ${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: SystemProgram.programId,
-      })
-      .rpc();
-  }
-
-  async deposit(
-    agentWallet: PublicKey,
-    amount: BN | number | bigint,
-  ): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(agentWallet);
-    const [stakePda] = this.deriveStake(agentPda);
-
-    // v0.13.0 preflight — stake must already exist; amount > 0
-    if (BigInt(this.bn(amount).toString()) <= 0n) {
-      throwPredicted("InsufficientStake", "Deposit amount must be > 0");
-    }
-    await this.requireAccountExists<AgentStakeData>(
-      "agentStake",
-      stakePda,
-      { predicted: "NoStakeAccount", hint: "Call initStake first" },
-    );
-
-    return this.methods
-      .depositStake(this.bn(amount))
-      .accounts({
-        wallet: this.walletPubkey,
-        agent: agentPda,
-        stake: stakePda,
-        systemProgram: SystemProgram.programId,
-      })
-      .rpc();
-  }
-
-  async requestUnstake(
-    agentWallet: PublicKey,
-    amount: BN | number | bigint,
-  ): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(agentWallet);
-    const [stakePda] = this.deriveStake(agentPda);
-
-    // v0.13.0 preflight — enforce MIN_STAKE floor + no double-pending
-    const stake = await this.requireAccountExists<AgentStakeData>(
-      "agentStake",
-      stakePda,
-      { predicted: "NoStakeAccount", hint: "No stake account to unstake from" },
-    );
-    const want = BigInt(this.bn(amount).toString());
-    if (want <= 0n) throwPredicted("InsufficientStake", "Unstake amount must be > 0");
-    const max = this.getMaxUnstakeLamports(stake);
-    if (want > max) {
-      throwPredicted(
-        "StakeBelowMinimum",
-        `requested ${want} would drop stake below MIN_AGENT_STAKE_LAMPORTS (max unstake = ${max})`,
-      );
-    }
-    if (BigInt(stake.unstakeAmount.toString()) > 0n) {
-      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: PublicKey,
-  ): Promise<TransactionSignature> {
-    const [agentPda] = 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<AgentStakeData>(
-      "agentStake",
-      stakePda,
-      { predicted: "NoStakeAccount", hint: "No stake account" },
-    );
-    const pending = BigInt(stake.unstakeAmount.toString());
-    if (pending === 0n) {
-      throwPredicted("NoUnstakePending", "Call requestUnstake first");
-    }
-    const availableAt = BigInt(stake.unstakeAvailableAt.toString());
-    const nowSec = BigInt(Math.floor(Date.now() / 1000));
-    if (nowSec < availableAt) {
-      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: PublicKey): Promise<AgentStakeData> {
-    const [pda] = this.deriveStake(agentPda);
-    return this.fetchAccount<AgentStakeData>("agentStake", pda);
-  }
-
-  async fetchNullable(agentPda: PublicKey): Promise<AgentStakeData | null> {
-    const [pda] = this.deriveStake(agentPda);
-    return this.fetchAccountNullable<AgentStakeData>("agentStake", pda);
-  }
-
-  async fetchByPda(stakePda: PublicKey): Promise<AgentStakeData> {
-    return this.fetchAccount<AgentStakeData>("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: AgentStakeData): bigint {
-    const staked = BigInt(stake.stakedAmount.toString());
-    if (staked <= MIN_AGENT_STAKE_LAMPORTS) return 0n;
-    return staked - 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: AgentStakeData, escrowLamports: bigint): bigint {
-    const required = computeRequiredStakeLamports(escrowLamports);
-    const have = BigInt(stake.stakedAmount.toString());
-    return have >= required ? 0n : required - have;
-  }
-}

package/src/modules/subscription.ts

@@ -1,147 +0,0 @@
-/**
- * @module subscription
- * @description Agent subscription lifecycle — create, fund, cancel,
- * close, and fetch subscription accounts.
- *
- * @category Modules
- * @since v0.7.0
- * @packageDocumentation
- */
-
-import {
-  SystemProgram,
-  type PublicKey,
-  type TransactionSignature,
-} from "@solana/web3.js";
-import { BN } from "@coral-xyz/anchor";
-import { BaseModule } from "./base";
-import { deriveAgent, deriveSubscription } from "../pda";
-import type { SubscriptionData, CreateSubscriptionArgs } from "../types";
-
-/**
- * @name SubscriptionModule
- * @description Manages recurring subscriptions between subscribers and agents.
- *
- * @category Modules
- * @since v0.7.0
- * @extends BaseModule
- */
-export class SubscriptionModule extends BaseModule {
-  // ── PDA helpers ──────────────────────────────────────
-
-  private toNum(v: BN | number | bigint): number {
-    return BN.isBN(v) ? v.toNumber() : Number(v);
-  }
-
-  deriveSubscription(
-    agentPda: PublicKey,
-    subscriber?: PublicKey,
-    subId: BN | number | bigint = 0,
-  ): readonly [PublicKey, number] {
-    return deriveSubscription(
-      agentPda,
-      subscriber ?? this.walletPubkey,
-      this.toNum(subId),
-    );
-  }
-
-  // ── Instructions ─────────────────────────────────────
-
-  async create(
-    agentWallet: PublicKey,
-    args: CreateSubscriptionArgs,
-  ): Promise<TransactionSignature> {
-    const [agentPda] = 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: SystemProgram.programId,
-      })
-      .rpc();
-  }
-
-  async fund(
-    agentWallet: PublicKey,
-    subId: BN | number | bigint,
-    amount: BN | number | bigint,
-  ): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(agentWallet);
-    const [subPda] = this.deriveSubscription(agentPda, undefined, subId);
-
-    return this.methods
-      .fundSubscription(this.bn(amount))
-      .accounts({
-        subscriber: this.walletPubkey,
-        subscription: subPda,
-        systemProgram: SystemProgram.programId,
-      })
-      .rpc();
-  }
-
-  async cancel(
-    agentWallet: PublicKey,
-    subId: BN | number | bigint = 0,
-  ): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(agentWallet);
-    const [subPda] = this.deriveSubscription(agentPda, undefined, subId);
-
-    return this.methods
-      .cancelSubscription()
-      .accounts({
-        subscriber: this.walletPubkey,
-        agentWallet,
-        subscription: subPda,
-      })
-      .rpc();
-  }
-
-  async close(
-    agentWallet: PublicKey,
-    subId: BN | number | bigint = 0,
-  ): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(agentWallet);
-    const [subPda] = this.deriveSubscription(agentPda, undefined, subId);
-
-    return this.methods
-      .closeSubscription()
-      .accounts({
-        subscriber: this.walletPubkey,
-        subscription: subPda,
-      })
-      .rpc();
-  }
-
-  // ── Fetchers ─────────────────────────────────────────
-
-  async fetch(
-    agentPda: PublicKey,
-    subscriber?: PublicKey,
-    subId: BN | number | bigint = 0,
-  ): Promise<SubscriptionData> {
-    const [pda] = this.deriveSubscription(agentPda, subscriber, subId);
-    return this.fetchAccount<SubscriptionData>("subscriptionAccount", pda);
-  }
-
-  async fetchNullable(
-    agentPda: PublicKey,
-    subscriber?: PublicKey,
-    subId: BN | number | bigint = 0,
-  ): Promise<SubscriptionData | null> {
-    const [pda] = this.deriveSubscription(agentPda, subscriber, subId);
-    return this.fetchAccountNullable<SubscriptionData>("subscriptionAccount", pda);
-  }
-
-  async fetchByPda(subPda: PublicKey): Promise<SubscriptionData> {
-    return this.fetchAccount<SubscriptionData>("subscriptionAccount", subPda);
-  }
-}