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

package/src/index.ts

@@ -62,6 +62,8 @@ export type {
   SettlementSecurityKind,
   DisputeOutcomeKind,
   BillingIntervalKind,
+  DisputeTypeValue,
+  ResolutionLayerKind,
   // Helper structs
   Capability,
   VolumeCurveBreakpoint,
@@ -90,6 +92,7 @@ export type {
   EscrowAccountV2Data,
   PendingSettlementData,
   DisputeRecordData,
+  ReceiptBatchData,
   AgentStakeData,
   SubscriptionData,
   CounterShardData,
@@ -129,6 +132,8 @@ export {
   SettlementSecurity,
   DisputeOutcome,
   BillingInterval,
+  DisputeType,
+  ResolutionLayer,
 } from "./types";
 
 // ── Constants ────────────────────────────────────────
@@ -178,6 +183,7 @@ export {
   deriveAttestation,
   deriveLedger,
   deriveLedgerPage,
+  deriveReceiptBatch,
 } from "./pda";
 
 // ── Utilities ────────────────────────────────────────
@@ -297,6 +303,7 @@ export {
   VaultModule,
   EscrowModule,
   EscrowV2Module,
+  ReceiptModule,
   StakingModule,
   SubscriptionModule,
   AttestationModule,

package/src/modules/escrow-v2.ts

@@ -1,8 +1,8 @@
 /**
  * @module escrow-v2
  * @description V2 escrow settlement layer — supports settlement security
- * modes (SelfReport, CoSigned, DisputeWindow), dispute resolution,
- * pending settlements, and migration from V1.
+ * modes (CoSigned, DisputeWindow), receipt-based dispute resolution,
+ * pending settlements, and automatic resolution via merkle proofs.
  *
  * @category Modules
  * @since v0.7.0
@@ -20,7 +20,6 @@ import { BaseModule } from "./base";
 import {
   deriveAgent,
   deriveAgentStats,
-  deriveEscrow,
   deriveEscrowV2,
   derivePendingSettlement as derivePendingPda,
   deriveDispute as deriveDisputePda,
@@ -173,6 +172,7 @@ export class EscrowV2Module extends BaseModule {
     callsToSettle: BN | number | bigint,
     amount: BN | number | bigint,
     serviceHash: number[],
+    receiptMerkleRoot: number[] = new Array(32).fill(0),
   ): Promise<TransactionSignature> {
     const [agentPda] = deriveAgent(agentWallet);
     const [escrowPda] = this.deriveEscrow(agentPda, depositorWallet, nonce);
@@ -184,6 +184,7 @@ export class EscrowV2Module extends BaseModule {
         this.bn(callsToSettle),
         this.bn(amount),
         serviceHash,
+        receiptMerkleRoot,
       )
       .accounts({
         wallet: this.walletPubkey,
@@ -223,6 +224,7 @@ export class EscrowV2Module extends BaseModule {
     nonce: BN | number | bigint,
     settlementIndex: BN | number | bigint,
     evidenceHash: number[],
+    disputeType: number = 0,
   ): Promise<TransactionSignature> {
     const [agentPda] = deriveAgent(agentWallet);
     const [escrowPda] = this.deriveEscrow(agentPda, undefined, nonce);
@@ -230,7 +232,7 @@ export class EscrowV2Module extends BaseModule {
     const [disputePda] = this.deriveDispute(pendingPda);
 
     return this.methods
-      .fileDispute(evidenceHash)
+      .fileDispute(evidenceHash, disputeType)
       .accounts({
         depositor: this.walletPubkey,
         escrow: escrowPda,
@@ -241,31 +243,18 @@ export class EscrowV2Module extends BaseModule {
       .rpc();
   }
 
+  /**
+   * @deprecated Since v0.7.0 — Arbiter-based resolution removed.
+   * Use {@link ReceiptModule.submitReceiptProof} + {@link ReceiptModule.autoResolveDispute} instead.
+   */
   async resolveDispute(
-    depositorWallet: PublicKey,
-    agentWallet: PublicKey,
-    nonce: BN | number | bigint,
-    settlementIndex: BN | number | bigint,
-    outcome: number,
+    _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();
+    throw new Error("resolveDispute removed in v0.7.0 — use ReceiptModule.autoResolveDispute");
   }
 
   async closeDispute(
@@ -327,23 +316,13 @@ export class EscrowV2Module extends BaseModule {
       .rpc();
   }
 
+  /**
+   * @deprecated Since v0.7.0 — Migration instruction removed from program.
+   */
   async migrateFromV1(
-    agentWallet: PublicKey,
+    _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();
+    throw new Error("migrateFromV1 removed in v0.7.0 — migration instruction was deleted");
   }
 
   // ── Fetchers ─────────────────────────────────────────

package/src/modules/index.ts

@@ -19,6 +19,7 @@ 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";

package/src/modules/receipt.ts

@@ -0,0 +1,207 @@
+/**
+ * @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,
+} 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);
+
+    return this.methods
+      .autoResolveDispute()
+      .accounts({
+        payer: this.walletPubkey,
+        depositor: depositorWallet,
+        agentWallet,
+        escrow: escrowPda,
+        pendingSettlement: pendingPda,
+        dispute: disputePda,
+        agentStats: statsPda,
+      })
+      .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/pda/index.ts

@@ -846,3 +846,35 @@ export const deriveIndexPage = (
     ],
     programId,
   );
+
+// ═════════════════════════════════════════════
+//  Receipt Batch (v0.7)
+// ═════════════════════════════════════════════
+
+/**
+ * Derive the **ReceiptBatch** PDA.
+ *
+ * Seeds: `["sap_receipt", escrow_v2_pda, batch_index_u32_le]`
+ *
+ * @name deriveReceiptBatch
+ * @description Computes the receipt batch PDA storing a merkle root of call receipts.
+ * @param escrowV2Pda - The parent V2 escrow PDA.
+ * @param batchIndex  - Zero-based batch index (u32).
+ * @param programId   - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.7.0
+ */
+export const deriveReceiptBatch = (
+  escrowV2Pda: PublicKey,
+  batchIndex: number,
+  programId = SAP_PROGRAM_ID,
+): PdaResult =>
+  findPda(
+    [
+      toSeedBuf(SEEDS.RECEIPT),
+      escrowV2Pda.toBuffer(),
+      u32le(batchIndex),
+    ],
+    programId,
+  );

package/src/types/accounts.ts

@@ -11,7 +11,7 @@
 
 import type { PublicKey } from "@solana/web3.js";
 import type BN from "bn.js";
-import type { ToolHttpMethodKind, ToolCategoryKind, SettlementSecurityKind, DisputeOutcomeKind, BillingIntervalKind } from "./enums";
+import type { ToolHttpMethodKind, ToolCategoryKind, SettlementSecurityKind, DisputeOutcomeKind, BillingIntervalKind, ResolutionLayerKind } from "./enums";
 import type { Capability, PricingTier, PluginRef, VolumeCurveBreakpoint } from "./common";
 
 // ═══════════════════════════════════════════════════════════════════
@@ -652,9 +652,12 @@ export interface EscrowAccountV2Data {
   readonly disputeWindowSlots: BN;
   readonly settlementIndex: BN;
   readonly coSigner: PublicKey | null;
+  /** @deprecated Since v0.7.0 — arbiter role replaced by automatic receipt verification */
   readonly arbiter: PublicKey | null;
   readonly pendingAmount: BN;
   readonly pendingCalls: BN;
+  /** @since v0.7.0 — Number of receipt batches inscribed against this escrow */
+  readonly receiptBatchCount: number;
 }
 
 // ═══════════════════════════════════════════════════════════════════
@@ -682,6 +685,8 @@ export interface PendingSettlementData {
   readonly isFinalized: boolean;
   readonly isDisputed: boolean;
   readonly outcome: DisputeOutcomeKind;
+  /** @since v0.7.0 — Merkle root of receipts backing this settlement */
+  readonly receiptMerkleRoot: number[]; // [u8; 32]
 }
 
 // ═══════════════════════════════════════════════════════════════════
@@ -690,7 +695,7 @@ export interface PendingSettlementData {
 
 /**
  * @interface DisputeRecordData
- * @description On-chain dispute with arbiter resolution.
+ * @description On-chain dispute with automatic receipt-based resolution (v0.7).
  * @category Types
  * @since v0.5.0
  */
@@ -702,12 +707,56 @@ export interface DisputeRecordData {
   readonly agent: PublicKey;
   readonly evidenceHash: number[]; // [u8; 32]
   readonly agentEvidenceHash: number[]; // [u8; 32]
+  /** @deprecated Since v0.7.0 — arbiter role replaced by automatic resolution */
   readonly arbiter: PublicKey;
   readonly outcome: DisputeOutcomeKind;
   readonly createdAt: BN;
   readonly resolvedAt: BN;
   readonly resolutionHash: number[]; // [u8; 32]
   readonly slashAmount: BN;
+  /** @since v0.7.0 — Category of dispute (NonDelivery=0, PartialDelivery=1, Overcharge=2, Quality=3) */
+  readonly disputeType: number;
+  /** @since v0.7.0 — How the dispute was resolved (Pending/Auto/Governance) */
+  readonly resolutionLayer: ResolutionLayerKind;
+  /** @since v0.7.0 — Bond deposited by the disputer (lamports) */
+  readonly disputeBond: BN;
+  /** @since v0.7.0 — Number of calls the agent proved via merkle proofs */
+  readonly provenCalls: BN;
+  /** @since v0.7.0 — Number of calls the agent originally claimed */
+  readonly claimedCalls: BN;
+  /** @since v0.7.0 — Unix timestamp by which agent must submit proof */
+  readonly proofDeadline: BN;
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Receipt Batch (v0.7)
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface ReceiptBatchData
+ * @description Merkle root of a batch of call receipts inscribed by an agent.
+ *
+ * Seeds: `["sap_receipt", escrow_v2_pda, batch_index_u32_le]`
+ *
+ * @category Types
+ * @since v0.7.0
+ */
+export interface ReceiptBatchData {
+  readonly bump: number;
+  /** Parent escrow V2 PDA */
+  readonly escrow: PublicKey;
+  /** Zero-based batch index */
+  readonly batchIndex: number;
+  /** Merkle root of the receipt batch */
+  readonly merkleRoot: number[]; // [u8; 32]
+  /** Number of calls in the batch */
+  readonly callCount: BN;
+  /** Unix timestamp for the start of the period covered */
+  readonly periodStart: BN;
+  /** Unix timestamp for the end of the period covered */
+  readonly periodEnd: BN;
+  /** Unix timestamp when the batch was inscribed */
+  readonly inscribedAt: BN;
 }
 
 // ═══════════════════════════════════════════════════════════════════

package/src/types/enums.ts

@@ -221,7 +221,7 @@ export type ToolCategoryKind =
  * @name SettlementSecurity
  * @description Anchor-compatible enum variants for V2 escrow settlement security levels.
  *
- * - `SelfReport` — Agent settles unilaterally (v1 compatible).
+ * - `SelfReport` — **DEPRECATED in v0.7** — Agent settles unilaterally (abuse vector).
  * - `CoSigned` — Agent + client must co-sign every settlement.
  * - `DisputeWindow` — Settlement enters pending state, depositor can dispute.
  *
@@ -229,6 +229,7 @@ export type ToolCategoryKind =
  * @since v0.5.0
  */
 export const SettlementSecurity = {
+  /** @deprecated Removed in v0.7 — returns SelfReportDeprecated error */
   SelfReport: { selfReport: {} },
   CoSigned: { coSigned: {} },
   DisputeWindow: { disputeWindow: {} },
@@ -253,11 +254,64 @@ export const DisputeOutcome = {
   AutoReleased: { autoReleased: {} },
   DepositorWins: { depositorWins: {} },
   AgentWins: { agentWins: {} },
+  /** @since v0.7.0 — Proportional refund based on proven vs claimed calls */
+  PartialRefund: { partialRefund: {} },
+  /** @since v0.7.0 — 50/50 split for irresolvable quality disputes */
+  Split: { split: {} },
 } as const;
 
 export type DisputeOutcomeKind =
   (typeof DisputeOutcome)[keyof typeof DisputeOutcome];
 
+// ═══════════════════════════════════════════════════════════════════
+//  Dispute Type (v0.7)
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name DisputeType
+ * @description Categories of disputes that can be filed against a pending settlement.
+ *
+ * - `NonDelivery` — Agent took payment but delivered nothing.
+ * - `PartialDelivery` — Agent delivered fewer calls than claimed.
+ * - `Overcharge` — Agent charged more than the agreed price.
+ * - `Quality` — Agent delivered but output quality is disputed.
+ *
+ * @category Types
+ * @since v0.7.0
+ */
+export const DisputeType = {
+  NonDelivery: 0,
+  PartialDelivery: 1,
+  Overcharge: 2,
+  Quality: 3,
+} as const;
+
+export type DisputeTypeValue = (typeof DisputeType)[keyof typeof DisputeType];
+
+// ═══════════════════════════════════════════════════════════════════
+//  Resolution Layer (v0.7)
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name ResolutionLayer
+ * @description How a dispute was resolved.
+ *
+ * - `Pending` — Not yet resolved.
+ * - `Auto` — Resolved automatically via receipt merkle proofs.
+ * - `Governance` — Resolved via protocol governance (quality disputes).
+ *
+ * @category Types
+ * @since v0.7.0
+ */
+export const ResolutionLayer = {
+  Pending: { pending: {} },
+  Auto: { auto: {} },
+  Governance: { governance: {} },
+} as const;
+
+export type ResolutionLayerKind =
+  (typeof ResolutionLayer)[keyof typeof ResolutionLayer];
+
 // ═══════════════════════════════════════════════════════════════════
 //  Billing Interval (V2.1)
 // ═══════════════════════════════════════════════════════════════════

package/src/types/index.ts

@@ -30,6 +30,8 @@ export {
   SettlementSecurity,
   DisputeOutcome,
   BillingInterval,
+  DisputeType,
+  ResolutionLayer,
 } from "./enums";
 
 export type {
@@ -41,6 +43,8 @@ export type {
   SettlementSecurityKind,
   DisputeOutcomeKind,
   BillingIntervalKind,
+  DisputeTypeValue,
+  ResolutionLayerKind,
 } from "./enums";
 
 // ── Common Structs ───────────────────────────────────
@@ -74,6 +78,7 @@ export type {
   EscrowAccountV2Data,
   PendingSettlementData,
   DisputeRecordData,
+  ReceiptBatchData,
   AgentStakeData,
   SubscriptionData,
   CounterShardData,