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

package/src/modules/escrow.ts

@@ -1,383 +0,0 @@
-/**
- * @module escrow
- * @description x402 escrow settlement layer — create, deposit,
- * settle, withdraw, batch settle, and close escrow accounts.
- *
- * Supports both SOL and SPL token escrows. SPL operations require
- * passing additional `AccountMeta[]` via the `splAccounts` parameter.
- *
- * @category Modules
- * @since v0.1.0
- * @packageDocumentation
- */
-
-import {
-  SystemProgram,
-  type PublicKey,
-  type TransactionSignature,
-  type AccountMeta,
-} from "@solana/web3.js";
-import { BN } from "@coral-xyz/anchor";
-import { BaseModule } from "./base";
-import {
-  deriveAgent,
-  deriveAgentStats,
-  deriveEscrow,
-  deriveStake,
-  deriveSettlementReceipt,
-} from "../pda";
-import type {
-  EscrowAccountData,
-  CreateEscrowArgs,
-  Settlement,
-} from "../types";
-import {
-  buildPriorityFeeIxs,
-  computeBatchSettleCu,
-  buildRpcOptions,
-} from "../utils/priority-fee";
-import type { SettleOptions } from "../utils/priority-fee";
-import { computeBatchRoot, hashToArray } from "../utils/hash";
-import { isAcceptedPaymentToken } from "../constants/payments";
-
-/**
- * @name EscrowModule
- * @description Manages x402-compatible escrow accounts for agent micropayments.
- *   Provides methods to create, fund, settle, withdraw, batch-settle, close,
- *   and fetch escrow PDAs on the Synapse Agent Protocol.
- *
- * @category Modules
- * @since v0.1.0
- * @extends BaseModule
- *
- * @example
- * ```ts
- * const sap = new SapClient(provider);
- * // Create a SOL escrow for an agent
- * const sig = await sap.escrow.create(agentWallet, {
- *   pricePerCall: new BN(1_000_000),
- *   maxCalls: new BN(100),
- *   initialDeposit: new BN(100_000_000),
- *   expiresAt: null,
- *   volumeCurve: null,
- *   tokenMint: null,
- *   tokenDecimals: null,
- * });
- * ```
- *
- * @deprecated Since v0.7.0 — Use {@link EscrowV2Module} (`client.escrowV2`) instead.
- * V1 escrows lack settlement security, dispute resolution, and staking integration.
- * Existing V1 escrows can be migrated via `client.escrowV2.migrateFromV1()`.
- */
-export class EscrowModule extends BaseModule {
-  // ── PDA helpers ──────────────────────────────────────
-
-  /**
-   * @name deriveEscrow
-   * @description Derive the `EscrowAccount` PDA for a given agent and depositor.
-   * @param agentPda - The agent account PDA.
-   * @param depositor - The depositor wallet. Defaults to the connected wallet.
-   * @returns A tuple of `[PublicKey, bump]` for the escrow PDA.
-   * @see {@link deriveEscrow} from `pda/` module for the underlying derivation.
-   * @since v0.1.0
-   */
-  deriveEscrow(
-    agentPda: PublicKey,
-    depositor?: PublicKey,
-  ): readonly [PublicKey, number] {
-    return deriveEscrow(agentPda, depositor ?? this.walletPubkey);
-  }
-
-  // ── Instructions ─────────────────────────────────────
-
-  /**
-   * @name create
-   * @description Create a new escrow for agent micropayments.
-   *
-   *   For **SOL escrow**: pass `tokenMint: null` and leave `splAccounts` empty.
-   *   For **SPL escrow**: pass `tokenMint`, `tokenDecimals`, and provide
-   *   `splAccounts` with `[depositorAta, escrowAta, tokenMint, tokenProgram]`.
-   *
-   * @param agentWallet - The wallet of the agent to pay.
-   * @param args - Escrow creation parameters (price, max calls, deposit, expiry, volume curve, token info).
-   * @param splAccounts - Remaining accounts for SPL token transfers:
-   *   `[depositorAta, escrowAta, tokenMint, tokenProgram]`. Defaults to `[]`.
-   * @returns {Promise<TransactionSignature>} The transaction signature.
-   * @since v0.1.0
-   */
-  async create(
-    agentWallet: PublicKey,
-    args: CreateEscrowArgs,
-    splAccounts: AccountMeta[] = [],
-  ): Promise<TransactionSignature> {
-    // v0.10.0 client-side guard — surface the on-chain rejection earlier.
-    if (!isAcceptedPaymentToken(args.tokenMint ?? null)) {
-      throw new Error(
-        "createEscrow: tokenMint must be null (SOL) or USDC (mainnet/devnet). " +
-        "On-chain will reject with PaymentTokenNotAllowed.",
-      );
-    }
-
-    const [agentPda] = deriveAgent(agentWallet);
-    const [escrowPda] = this.deriveEscrow(agentPda);
-    const [stakePda] = deriveStake(agentPda);
-
-    return this.methods
-      .createEscrow(
-        args.pricePerCall,
-        args.maxCalls,
-        args.initialDeposit,
-        args.expiresAt,
-        args.volumeCurve,
-        args.tokenMint,
-        args.tokenDecimals,
-      )
-      .accounts({
-        depositor: this.walletPubkey,
-        agent: agentPda,
-        agentStake: stakePda,
-        escrow: escrowPda,
-        systemProgram: SystemProgram.programId,
-      })
-      .remainingAccounts(splAccounts)
-      .rpc();
-  }
-
-  /**
-   * @name deposit
-   * @description Deposit additional funds into an existing escrow.
-   * @param agentWallet - The wallet of the agent associated with the escrow.
-   * @param amount - The amount to deposit (lamports for SOL, smallest unit for SPL).
-   * @param splAccounts - Remaining accounts for SPL token transfers. Defaults to `[]`.
-   * @returns {Promise<TransactionSignature>} The transaction signature.
-   * @since v0.1.0
-   */
-  async deposit(
-    agentWallet: PublicKey,
-    amount: BN | number | bigint,
-    splAccounts: AccountMeta[] = [],
-  ): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(agentWallet);
-    const [escrowPda] = this.deriveEscrow(agentPda);
-
-    return this.methods
-      .depositEscrow(this.bn(amount))
-      .accounts({
-        depositor: this.walletPubkey,
-        escrow: escrowPda,
-        systemProgram: SystemProgram.programId,
-      })
-      .remainingAccounts(splAccounts)
-      .rpc();
-  }
-
-  /**
-   * @name settle
-   * @description Agent settles calls — claims earned funds from the escrow.
-   *   Must be called by the agent owner wallet.
-   * @param depositorWallet - The wallet of the client who funded the escrow.
-   * @param callsToSettle - Number of calls to settle payment for.
-   * @param serviceHash - A 32-byte SHA-256 hash identifying the service rendered.
-   * @param splAccounts - Remaining accounts for SPL token transfers. Defaults to `[]`.
-   * @param opts - Optional {@link SettleOptions} for priority fees and RPC tuning.
-   * @returns {Promise<TransactionSignature>} The transaction signature.
-   * @since v0.1.0
-   * @updated v0.6.2 — Added optional `opts` parameter for priority fees.
-   */
-  async settle(
-    depositorWallet: PublicKey,
-    callsToSettle: BN | number | bigint,
-    serviceHash: number[],
-    splAccounts: AccountMeta[] = [],
-    opts?: SettleOptions,
-  ): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(this.walletPubkey);
-    const [escrowPda] = deriveEscrow(agentPda, depositorWallet);
-    const [statsPda] = deriveAgentStats(agentPda);
-    const [receiptPda] = deriveSettlementReceipt(escrowPda, serviceHash);
-
-    const preIxs = buildPriorityFeeIxs(opts);
-    const rpcOpts = buildRpcOptions(opts);
-
-    let builder = this.methods
-      .settleCalls(this.bn(callsToSettle), serviceHash)
-      .accounts({
-        wallet: this.walletPubkey,
-        agent: agentPda,
-        agentStats: statsPda,
-        escrow: escrowPda,
-        settlementReceipt: receiptPda,
-        systemProgram: SystemProgram.programId,
-      })
-      .remainingAccounts(splAccounts);
-
-    if (preIxs.length > 0) {
-      builder = builder.preInstructions(preIxs);
-    }
-
-    return builder.rpc(rpcOpts);
-  }
-
-  /**
-   * @name withdraw
-   * @description Client withdraws un-settled funds from their escrow.
-   * @param agentWallet - The wallet of the agent associated with the escrow.
-   * @param amount - The amount to withdraw (lamports for SOL, smallest unit for SPL).
-   * @param splAccounts - Remaining accounts for SPL token transfers. Defaults to `[]`.
-   * @returns {Promise<TransactionSignature>} The transaction signature.
-   * @since v0.1.0
-   */
-  async withdraw(
-    agentWallet: PublicKey,
-    amount: BN | number | bigint,
-    splAccounts: AccountMeta[] = [],
-  ): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(agentWallet);
-    const [escrowPda] = this.deriveEscrow(agentPda);
-
-    return this.methods
-      .withdrawEscrow(this.bn(amount))
-      .accounts({
-        depositor: this.walletPubkey,
-        escrow: escrowPda,
-        systemProgram: SystemProgram.programId,
-      })
-      .remainingAccounts(splAccounts)
-      .rpc();
-  }
-
-  /**
-   * @name close
-   * @description Close an empty escrow PDA (balance must be 0) and reclaim rent.
-   * @param agentWallet - The wallet of the agent associated with the escrow.
-   * @returns {Promise<TransactionSignature>} The transaction signature.
-   * @since v0.1.0
-   */
-  async close(agentWallet: PublicKey): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(agentWallet);
-    const [escrowPda] = this.deriveEscrow(agentPda);
-
-    return this.methods
-      .closeEscrow()
-      .accounts({
-        depositor: this.walletPubkey,
-        escrow: escrowPda,
-      })
-      .rpc();
-  }
-
-  /**
-   * @name settleBatch
-   * @description Batch settlement — process up to 10 settlements in a single
-   *   transaction. Must be called by the agent owner wallet.
-   *
-   * @param depositorWallet - The wallet of the client who funded the escrow.
-   * @param settlements - Array of settlement entries (up to 10).
-   * @param batchRoot - Optional pre-computed batch root
-   *   (`sha256(s_0 || s_1 || ... || s_{N-1})`). When omitted the SDK
-   *   computes it from `settlements[*].serviceHash`. **Required on-chain
-   *   since v0.10.0** to seed the anti-replay receipt PDA.
-   * @param splAccounts - Remaining accounts for SPL token transfers. Defaults to `[]`.
-   * @param opts - Optional {@link SettleOptions} for priority fees and RPC tuning.
-   * @returns {Promise<TransactionSignature>} The transaction signature.
-   *
-   * @since v0.1.0
-   * @updated v0.6.2 — Added optional `opts` parameter for priority fees.
-   * @updated v0.10.0 — Added `batchRoot` argument and required
-   *   `settlementReceipt` PDA on-chain (anti-replay).
-   */
-  async settleBatch(
-    depositorWallet: PublicKey,
-    settlements: Settlement[],
-    batchRoot?: Uint8Array | number[] | null,
-    splAccounts: AccountMeta[] = [],
-    opts?: SettleOptions,
-  ): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(this.walletPubkey);
-    const [escrowPda] = deriveEscrow(agentPda, depositorWallet);
-    const [statsPda] = deriveAgentStats(agentPda);
-
-    const rootBytes =
-      batchRoot && batchRoot !== null
-        ? batchRoot instanceof Uint8Array
-          ? batchRoot
-          : Uint8Array.from(batchRoot)
-        : computeBatchRoot(settlements.map((s) => s.serviceHash));
-    const rootArr = hashToArray(rootBytes);
-    const [receiptPda] = deriveSettlementReceipt(escrowPda, rootBytes);
-
-    // Auto-size CU to the batch length so callers don't have to think
-    // about it. The default Solana cap (200k) overflows past ~8
-    // settlements; we compute a tight ceiling and let the caller
-    // override via `opts.computeUnits` if they want.
-    // Setting the CU limit is FREE — it doesn't add lamports, only
-    // caps the maximum the runtime is allowed to charge.
-    const effectiveOpts: SettleOptions = {
-      ...opts,
-      computeUnits: opts?.computeUnits ?? computeBatchSettleCu(settlements.length),
-    };
-    const preIxs = buildPriorityFeeIxs(effectiveOpts);
-    const rpcOpts = buildRpcOptions(effectiveOpts);
-
-    let builder = this.methods
-      .settleBatch(settlements, rootArr)
-      .accountsPartial({
-        wallet: this.walletPubkey,
-        agent: agentPda,
-        agentStats: statsPda,
-        escrow: escrowPda,
-        settlementReceipt: receiptPda,
-        systemProgram: SystemProgram.programId,
-      })
-      .remainingAccounts(splAccounts);
-
-    if (preIxs.length > 0) {
-      builder = builder.preInstructions(preIxs);
-    }
-
-    return builder.rpc(rpcOpts);
-  }
-
-  // ── Fetchers ─────────────────────────────────────────
-
-  /**
-   * @name fetch
-   * @description Fetch a deserialized `EscrowAccount`.
-   * @param agentPda - The agent account PDA.
-   * @param depositor - The depositor wallet. Defaults to the connected wallet.
-   * @returns {Promise<EscrowAccountData>} The escrow account data.
-   * @throws Will throw if the escrow account does not exist.
-   * @since v0.1.0
-   */
-  async fetch(agentPda: PublicKey, depositor?: PublicKey): Promise<EscrowAccountData> {
-    const [pda] = this.deriveEscrow(agentPda, depositor);
-    return this.fetchAccount<EscrowAccountData>("escrowAccount", pda);
-  }
-
-  /**
-   * @name fetchNullable
-   * @description Fetch a deserialized `EscrowAccount`, or `null` if it
-   *   does not exist on-chain.
-   * @param agentPda - The agent account PDA.
-   * @param depositor - The depositor wallet. Defaults to the connected wallet.
-   * @returns {Promise<EscrowAccountData | null>} The escrow data or `null`.
-   * @since v0.1.0
-   */
-  async fetchNullable(agentPda: PublicKey, depositor?: PublicKey): Promise<EscrowAccountData | null> {
-    const [pda] = this.deriveEscrow(agentPda, depositor);
-    return this.fetchAccountNullable<EscrowAccountData>("escrowAccount", pda);
-  }
-
-  /**
-   * @name fetchByPda
-   * @description Fetch an escrow account by its PDA address directly,
-   *   bypassing PDA derivation.
-   * @param escrowPda - The escrow PDA public key.
-   * @returns {Promise<EscrowAccountData>} The escrow account data.
-   * @throws Will throw if the escrow account does not exist.
-   * @since v0.1.0
-   */
-  async fetchByPda(escrowPda: PublicKey): Promise<EscrowAccountData> {
-    return this.fetchAccount<EscrowAccountData>("escrowAccount", escrowPda);
-  }
-}

package/src/modules/feedback.ts

@@ -1,186 +0,0 @@
-/**
- * @module feedback
- * @description Trustless reputation system — give, update, revoke, and close
- *   on-chain feedback entries for agents.
- *
- * Feedback entries are PDA-based reviews tied to an agent and a reviewer wallet,
- * enabling permissionless, verifiable reputation on Solana.
- *
- * @category Modules
- * @since v0.1.0
- * @packageDocumentation
- */
-
-import { SystemProgram, type PublicKey, type TransactionSignature } from "@solana/web3.js";
-import { BaseModule } from "./base";
-import { deriveAgent, deriveFeedback, deriveGlobalRegistry } from "../pda";
-import type { FeedbackAccountData, GiveFeedbackArgs, UpdateFeedbackArgs } from "../types";
-
-/**
- * @name FeedbackModule
- * @description Manages on-chain feedback entries for the Synapse Agent Protocol.
- *   Provides methods to give, update, revoke, close, and fetch feedback PDAs
- *   that form the trustless reputation layer.
- *
- * @category Modules
- * @since v0.1.0
- * @extends BaseModule
- *
- * @example
- * ```ts
- * const sap = new SapClient(provider);
- * const sig = await sap.feedback.give(agentWallet, {
- *   score: 5,
- *   tag: { quality: {} },
- *   commentHash: null,
- * });
- * ```
- */
-export class FeedbackModule extends BaseModule {
-  // ── PDA helpers ──────────────────────────────────────
-
-  /**
-   * @name deriveFeedback
-   * @description Derive the `FeedbackAccount` PDA for a given agent and reviewer.
-   * @param agentPda - The agent account PDA to review.
-   * @param reviewer - The reviewer wallet. Defaults to the connected wallet.
-   * @returns A tuple of `[PublicKey, bump]` for the feedback PDA.
-   * @see {@link deriveFeedback} from `pda/` module for the underlying derivation.
-   * @since v0.1.0
-   */
-  deriveFeedback(
-    agentPda: PublicKey,
-    reviewer?: PublicKey,
-  ): readonly [PublicKey, number] {
-    return deriveFeedback(agentPda, reviewer ?? this.walletPubkey);
-  }
-
-  // ── Instructions ─────────────────────────────────────
-
-  /**
-   * @name give
-   * @description Leave on-chain feedback for an agent. Creates a new
-   *   `FeedbackAccount` PDA owned by the reviewer.
-   * @param agentWallet - The wallet that owns the target agent.
-   * @param args - Feedback parameters (score, tag, optional comment hash).
-   * @returns {Promise<TransactionSignature>} The transaction signature.
-   * @since v0.1.0
-   */
-  async give(
-    agentWallet: PublicKey,
-    args: GiveFeedbackArgs,
-  ): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(agentWallet);
-    const [feedbackPda] = this.deriveFeedback(agentPda);
-    const [globalPda] = deriveGlobalRegistry();
-
-    return this.methods
-      .giveFeedback(args.score, args.tag, args.commentHash ?? null)
-      .accounts({
-        reviewer: this.walletPubkey,
-        agent: agentPda,
-        feedback: feedbackPda,
-        globalRegistry: globalPda,
-        systemProgram: SystemProgram.programId,
-      })
-      .rpc();
-  }
-
-  /**
-   * @name update
-   * @description Update an existing feedback entry. Only the original reviewer
-   *   may update their feedback.
-   * @param agentWallet - The wallet that owns the target agent.
-   * @param args - Updated feedback parameters (new score, optional new tag, optional comment hash).
-   * @returns {Promise<TransactionSignature>} The transaction signature.
-   * @since v0.1.0
-   */
-  async update(
-    agentWallet: PublicKey,
-    args: UpdateFeedbackArgs,
-  ): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(agentWallet);
-    const [feedbackPda] = this.deriveFeedback(agentPda);
-
-    return this.methods
-      .updateFeedback(args.newScore, args.newTag ?? null, args.commentHash ?? null)
-      .accounts({
-        reviewer: this.walletPubkey,
-        agent: agentPda,
-        feedback: feedbackPda,
-      })
-      .rpc();
-  }
-
-  /**
-   * @name revoke
-   * @description Revoke a feedback entry, marking it as revoked and excluding
-   *   it from reputation calculations.
-   * @param agentWallet - The wallet that owns the target agent.
-   * @returns {Promise<TransactionSignature>} The transaction signature.
-   * @since v0.1.0
-   */
-  async revoke(agentWallet: PublicKey): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(agentWallet);
-    const [feedbackPda] = this.deriveFeedback(agentPda);
-
-    return this.methods
-      .revokeFeedback()
-      .accounts({
-        reviewer: this.walletPubkey,
-        agent: agentPda,
-        feedback: feedbackPda,
-      })
-      .rpc();
-  }
-
-  /**
-   * @name close
-   * @description Close a revoked feedback PDA and reclaim rent to the reviewer.
-   * @param agentWallet - The wallet that owns the target agent.
-   * @returns {Promise<TransactionSignature>} The transaction signature.
-   * @since v0.1.0
-   */
-  async close(agentWallet: PublicKey): Promise<TransactionSignature> {
-    const [agentPda] = deriveAgent(agentWallet);
-    const [feedbackPda] = this.deriveFeedback(agentPda);
-
-    return this.methods
-      .closeFeedback()
-      .accounts({
-        reviewer: this.walletPubkey,
-        feedback: feedbackPda,
-      })
-      .rpc();
-  }
-
-  // ── Fetchers ─────────────────────────────────────────
-
-  /**
-   * @name fetch
-   * @description Fetch a deserialized `FeedbackAccount`.
-   * @param agentPda - The agent account PDA.
-   * @param reviewer - The reviewer wallet. Defaults to the connected wallet.
-   * @returns {Promise<FeedbackAccountData>} The feedback account data.
-   * @throws Will throw if the feedback account does not exist.
-   * @since v0.1.0
-   */
-  async fetch(agentPda: PublicKey, reviewer?: PublicKey): Promise<FeedbackAccountData> {
-    const [pda] = this.deriveFeedback(agentPda, reviewer);
-    return this.fetchAccount<FeedbackAccountData>("feedbackAccount", pda);
-  }
-
-  /**
-   * @name fetchNullable
-   * @description Fetch a deserialized `FeedbackAccount`, or `null` if it
-   *   does not exist on-chain.
-   * @param agentPda - The agent account PDA.
-   * @param reviewer - The reviewer wallet. Defaults to the connected wallet.
-   * @returns {Promise<FeedbackAccountData | null>} The feedback data or `null`.
-   * @since v0.1.0
-   */
-  async fetchNullable(agentPda: PublicKey, reviewer?: PublicKey): Promise<FeedbackAccountData | null> {
-    const [pda] = this.deriveFeedback(agentPda, reviewer);
-    return this.fetchAccountNullable<FeedbackAccountData>("feedbackAccount", pda);
-  }
-}

package/src/modules/index.ts

@@ -1,28 +0,0 @@
-/**
- * @module modules
- * @description Barrel export for all domain modules of the `@synapse-sap/sdk`.
- *
- * Re-exports every module class so consumers can import from a single entry point:
- * ```ts
- * import { AgentModule, VaultModule } from "@synapse-sap/sdk/modules";
- * ```
- *
- * @category Modules
- * @since v0.1.0
- * @packageDocumentation
- */
-
-export { AgentModule } from "./agent";
-export { FeedbackModule } from "./feedback";
-export { IndexingModule } from "./indexing";
-export { ToolsModule } from "./tools";
-export { VaultModule } from "./vault";
-export { EscrowModule } from "./escrow";
-export { EscrowV2Module } from "./escrow-v2";
-export { ReceiptModule } from "./receipt";
-export { StakingModule } from "./staking";
-export { SubscriptionModule } from "./subscription";
-export { AttestationModule } from "./attestation";
-export { LedgerModule } from "./ledger";
-export { BaseModule } from "./base";
-export type { SapProgram, SapTransactionResult } from "./base";