@oobe-protocol-labs/synapse-sap-sdk 0.6.3 → 0.7.0

package/src/index.ts

@@ -59,6 +59,9 @@ export type {
   DelegatePermissionBit,
   SchemaTypeValue,
   CompressionTypeValue,
+  SettlementSecurityKind,
+  DisputeOutcomeKind,
+  BillingIntervalKind,
   // Helper structs
   Capability,
   VolumeCurveBreakpoint,
@@ -83,6 +86,14 @@ export type {
   AgentAttestationData,
   MemoryLedgerData,
   LedgerPageData,
+  // V2.1 account data
+  EscrowAccountV2Data,
+  PendingSettlementData,
+  DisputeRecordData,
+  AgentStakeData,
+  SubscriptionData,
+  CounterShardData,
+  IndexPageData,
   // Instruction args
   RegisterAgentArgs,
   UpdateAgentArgs,
@@ -95,6 +106,9 @@ export type {
   CreateEscrowArgs,
   CreateAttestationArgs,
   InscribeToolSchemaArgs,
+  // V2.1 instruction args
+  CreateEscrowV2Args,
+  CreateSubscriptionArgs,
   // v0.6.0 — Endpoint & Manifest types
   EndpointDescriptor,
   HealthCheckDescriptor,
@@ -112,6 +126,9 @@ export {
   DelegatePermission,
   SchemaType,
   CompressionType,
+  SettlementSecurity,
+  DisputeOutcome,
+  BillingInterval,
 } from "./types";
 
 // ── Constants ────────────────────────────────────────
@@ -151,6 +168,13 @@ export {
   deriveCheckpoint,
   deriveTool,
   deriveEscrow,
+  deriveEscrowV2,
+  derivePendingSettlement,
+  deriveDispute,
+  deriveStake,
+  deriveSubscription,
+  deriveShard,
+  deriveIndexPage,
   deriveAttestation,
   deriveLedger,
   deriveLedgerPage,
@@ -216,6 +240,26 @@ export type {
   PriorityFeeConfig,
 } from "./utils";
 
+// v0.6.4 — Escrow validation, merchant middleware, x402 direct
+export {
+  validateEscrowState,
+  attachSplAccounts,
+  toAccountMetas,
+  MissingEscrowAtaError,
+  SapMerchantValidator,
+  parseX402Headers,
+  getX402DirectPayments,
+} from "./utils";
+export type {
+  SplAccountMeta,
+  EscrowValidationResult,
+  ParsedX402Headers,
+  MerchantValidationResult,
+  X402DirectPayment,
+  SettlementPayload,
+  GetX402DirectOptions,
+} from "./utils";
+
 // ── Errors ───────────────────────────────────────────
 export {
   SapError,
@@ -252,6 +296,9 @@ export {
   ToolsModule,
   VaultModule,
   EscrowModule,
+  EscrowV2Module,
+  StakingModule,
+  SubscriptionModule,
   AttestationModule,
   LedgerModule,
   BaseModule,

package/src/modules/escrow-v2.ts

@@ -0,0 +1,396 @@
+/**
+ * @module escrow-v2
+ * @description V2 escrow settlement layer — supports settlement security
+ * modes (SelfReport, CoSigned, DisputeWindow), dispute resolution,
+ * pending settlements, and migration from V1.
+ *
+ * @category Modules
+ * @since v0.7.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,
+  deriveEscrowV2,
+  derivePendingSettlement as derivePendingPda,
+  deriveDispute as deriveDisputePda,
+} from "../pda";
+import type {
+  EscrowAccountV2Data,
+  PendingSettlementData,
+  DisputeRecordData,
+  CreateEscrowV2Args,
+} from "../types";
+import {
+  buildPriorityFeeIxs,
+  buildRpcOptions,
+} from "../utils/priority-fee";
+import type { SettleOptions } from "../utils/priority-fee";
+
+/**
+ * @name EscrowV2Module
+ * @description Manages V2 escrow accounts with settlement security modes,
+ * dispute windows, and pending settlement flows.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @extends BaseModule
+ */
+export class EscrowV2Module extends BaseModule {
+  // ── Helpers ──────────────────────────────────────────
+
+  /** Convert BN | number | bigint → number for PDA seed functions. */
+  private toNum(v: BN | number | bigint): number {
+    return BN.isBN(v) ? v.toNumber() : Number(v);
+  }
+
+  // ── PDA helpers ──────────────────────────────────────
+
+  deriveEscrow(
+    agentPda: PublicKey,
+    depositor?: PublicKey,
+    nonce: BN | number | bigint = 0,
+  ): readonly [PublicKey, number] {
+    return deriveEscrowV2(agentPda, depositor ?? this.walletPubkey, this.toNum(nonce));
+  }
+
+  derivePendingSettlement(
+    escrowV2Pda: PublicKey,
+    settlementIndex: BN | number | bigint,
+  ): readonly [PublicKey, number] {
+    return derivePendingPda(escrowV2Pda, this.toNum(settlementIndex));
+  }
+
+  deriveDispute(
+    pendingSettlementPda: PublicKey,
+  ): readonly [PublicKey, number] {
+    return deriveDisputePda(pendingSettlementPda);
+  }
+
+  // ── Instructions ─────────────────────────────────────
+
+  async create(
+    agentWallet: PublicKey,
+    args: CreateEscrowV2Args,
+    splAccounts: AccountMeta[] = [],
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = this.deriveEscrow(agentPda, undefined, args.escrowNonce);
+
+    return this.methods
+      .createEscrowV2(
+        this.bn(args.escrowNonce),
+        this.bn(args.pricePerCall),
+        this.bn(args.maxCalls),
+        this.bn(args.initialDeposit),
+        args.expiresAt,
+        args.volumeCurve,
+        args.tokenMint,
+        args.tokenDecimals,
+        args.settlementSecurity,
+        this.bn(args.disputeWindowSlots),
+        args.coSigner,
+        args.arbiter,
+      )
+      .accounts({
+        depositor: this.walletPubkey,
+        agent: agentPda,
+        escrow: escrowPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .remainingAccounts(splAccounts)
+      .rpc();
+  }
+
+  async deposit(
+    agentWallet: PublicKey,
+    nonce: BN | number | bigint,
+    amount: BN | number | bigint,
+    splAccounts: AccountMeta[] = [],
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = this.deriveEscrow(agentPda, undefined, nonce);
+
+    return this.methods
+      .depositEscrowV2(this.bn(nonce), this.bn(amount))
+      .accounts({
+        depositor: this.walletPubkey,
+        escrow: escrowPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .remainingAccounts(splAccounts)
+      .rpc();
+  }
+
+  async settle(
+    depositorWallet: PublicKey,
+    nonce: BN | number | bigint,
+    callsToSettle: BN | number | bigint,
+    serviceHash: number[],
+    splAccounts: AccountMeta[] = [],
+    opts?: SettleOptions,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [escrowPda] = this.deriveEscrow(agentPda, depositorWallet, nonce);
+    const [statsPda] = deriveAgentStats(agentPda);
+
+    const preIxs = buildPriorityFeeIxs(opts);
+    const rpcOpts = buildRpcOptions(opts);
+
+    let builder = this.methods
+      .settleCallsV2(this.bn(nonce), this.bn(callsToSettle), serviceHash)
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        agentStats: statsPda,
+        escrow: escrowPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .remainingAccounts(splAccounts);
+
+    if (preIxs.length > 0) {
+      builder = builder.preInstructions(preIxs);
+    }
+
+    return builder.rpc(rpcOpts);
+  }
+
+  async createPendingSettlement(
+    agentWallet: PublicKey,
+    depositorWallet: PublicKey,
+    nonce: BN | number | bigint,
+    settlementIndex: BN | number | bigint,
+    callsToSettle: BN | number | bigint,
+    amount: BN | number | bigint,
+    serviceHash: number[],
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = this.deriveEscrow(agentPda, depositorWallet, nonce);
+    const [pendingPda] = this.derivePendingSettlement(escrowPda, settlementIndex);
+
+    return this.methods
+      .createPendingSettlement(
+        this.bn(settlementIndex),
+        this.bn(callsToSettle),
+        this.bn(amount),
+        serviceHash,
+      )
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        escrow: escrowPda,
+        pendingSettlement: pendingPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  async finalizeSettlement(
+    agentWallet: PublicKey,
+    depositorWallet: PublicKey,
+    nonce: BN | number | bigint,
+    settlementIndex: BN | number | bigint,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = this.deriveEscrow(agentPda, depositorWallet, nonce);
+    const [pendingPda] = this.derivePendingSettlement(escrowPda, settlementIndex);
+    const [statsPda] = deriveAgentStats(agentPda);
+
+    return this.methods
+      .finalizeSettlement()
+      .accounts({
+        payer: this.walletPubkey,
+        agentWallet,
+        escrow: escrowPda,
+        pendingSettlement: pendingPda,
+        agentStats: statsPda,
+      })
+      .rpc();
+  }
+
+  async fileDispute(
+    agentWallet: PublicKey,
+    nonce: BN | number | bigint,
+    settlementIndex: BN | number | bigint,
+    evidenceHash: number[],
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = this.deriveEscrow(agentPda, undefined, nonce);
+    const [pendingPda] = this.derivePendingSettlement(escrowPda, settlementIndex);
+    const [disputePda] = this.deriveDispute(pendingPda);
+
+    return this.methods
+      .fileDispute(evidenceHash)
+      .accounts({
+        depositor: this.walletPubkey,
+        escrow: escrowPda,
+        pendingSettlement: pendingPda,
+        dispute: disputePda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  async resolveDispute(
+    depositorWallet: PublicKey,
+    agentWallet: PublicKey,
+    nonce: BN | number | bigint,
+    settlementIndex: BN | number | bigint,
+    outcome: number,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = this.deriveEscrow(agentPda, depositorWallet, nonce);
+    const [pendingPda] = this.derivePendingSettlement(escrowPda, settlementIndex);
+    const [disputePda] = this.deriveDispute(pendingPda);
+    const [statsPda] = deriveAgentStats(agentPda);
+
+    return this.methods
+      .resolveDispute(outcome)
+      .accounts({
+        arbiter: this.walletPubkey,
+        depositor: depositorWallet,
+        agentWallet,
+        escrow: escrowPda,
+        pendingSettlement: pendingPda,
+        dispute: disputePda,
+        agentStats: statsPda,
+      })
+      .rpc();
+  }
+
+  async closeDispute(
+    pendingSettlementPda: PublicKey,
+  ): Promise<TransactionSignature> {
+    const [disputePda] = this.deriveDispute(pendingSettlementPda);
+
+    return this.methods
+      .closeDispute()
+      .accounts({
+        depositor: this.walletPubkey,
+        dispute: disputePda,
+      })
+      .rpc();
+  }
+
+  async closePendingSettlement(
+    pendingSettlementPda: PublicKey,
+  ): Promise<TransactionSignature> {
+    return this.methods
+      .closePendingSettlement()
+      .accounts({
+        payer: this.walletPubkey,
+        pendingSettlement: pendingSettlementPda,
+      })
+      .rpc();
+  }
+
+  async withdraw(
+    agentWallet: PublicKey,
+    nonce: BN | number | bigint,
+    amount: BN | number | bigint,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = this.deriveEscrow(agentPda, undefined, nonce);
+
+    return this.methods
+      .withdrawEscrowV2(this.bn(amount))
+      .accounts({
+        depositor: this.walletPubkey,
+        escrow: escrowPda,
+      })
+      .rpc();
+  }
+
+  async close(
+    agentWallet: PublicKey,
+    nonce: BN | number | bigint = 0,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = this.deriveEscrow(agentPda, undefined, nonce);
+
+    return this.methods
+      .closeEscrowV2()
+      .accounts({
+        depositor: this.walletPubkey,
+        escrow: escrowPda,
+      })
+      .rpc();
+  }
+
+  async migrateFromV1(
+    agentWallet: PublicKey,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowV1Pda] = deriveEscrow(agentPda, this.walletPubkey);
+    const [escrowV2Pda] = this.deriveEscrow(agentPda, undefined, 0);
+
+    return this.methods
+      .migrateEscrowV1ToV2()
+      .accounts({
+        depositor: this.walletPubkey,
+        agent: agentPda,
+        escrowV1: escrowV1Pda,
+        escrowV2: escrowV2Pda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  // ── Fetchers ─────────────────────────────────────────
+
+  async fetch(
+    agentPda: PublicKey,
+    depositor?: PublicKey,
+    nonce: BN | number | bigint = 0,
+  ): Promise<EscrowAccountV2Data> {
+    const [pda] = this.deriveEscrow(agentPda, depositor, nonce);
+    return this.fetchAccount<EscrowAccountV2Data>("escrowAccountV2", pda);
+  }
+
+  async fetchNullable(
+    agentPda: PublicKey,
+    depositor?: PublicKey,
+    nonce: BN | number | bigint = 0,
+  ): Promise<EscrowAccountV2Data | null> {
+    const [pda] = this.deriveEscrow(agentPda, depositor, nonce);
+    return this.fetchAccountNullable<EscrowAccountV2Data>("escrowAccountV2", pda);
+  }
+
+  async fetchByPda(escrowPda: PublicKey): Promise<EscrowAccountV2Data> {
+    return this.fetchAccount<EscrowAccountV2Data>("escrowAccountV2", escrowPda);
+  }
+
+  async fetchPendingSettlement(
+    pendingPda: PublicKey,
+  ): Promise<PendingSettlementData> {
+    return this.fetchAccount<PendingSettlementData>("pendingSettlement", pendingPda);
+  }
+
+  async fetchPendingSettlementNullable(
+    pendingPda: PublicKey,
+  ): Promise<PendingSettlementData | null> {
+    return this.fetchAccountNullable<PendingSettlementData>("pendingSettlement", pendingPda);
+  }
+
+  async fetchDispute(
+    disputePda: PublicKey,
+  ): Promise<DisputeRecordData> {
+    return this.fetchAccount<DisputeRecordData>("disputeRecord", disputePda);
+  }
+
+  async fetchDisputeNullable(
+    disputePda: PublicKey,
+  ): Promise<DisputeRecordData | null> {
+    return this.fetchAccountNullable<DisputeRecordData>("disputeRecord", disputePda);
+  }
+}

package/src/modules/escrow.ts

@@ -59,6 +59,10 @@ import type { SettleOptions } from "../utils/priority-fee";
  *   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 ──────────────────────────────────────

package/src/modules/index.ts

@@ -18,6 +18,9 @@ export { IndexingModule } from "./indexing";
 export { ToolsModule } from "./tools";
 export { VaultModule } from "./vault";
 export { EscrowModule } from "./escrow";
+export { EscrowV2Module } from "./escrow-v2";
+export { StakingModule } from "./staking";
+export { SubscriptionModule } from "./subscription";
 export { AttestationModule } from "./attestation";
 export { LedgerModule } from "./ledger";
 export { BaseModule } from "./base";

package/src/modules/staking.ts

@@ -0,0 +1,122 @@
+/**
+ * @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";
+
+/**
+ * @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);
+
+    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);
+
+    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);
+
+    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);
+
+    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);
+  }
+}