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

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,
@@ -366,6 +373,7 @@ export {
   X402Registry,
   SessionManager,
   AgentBuilder,
+  MetaplexBridge,
 } from "./registries/index";
 export type {
   DiscoveredAgent,
@@ -391,4 +399,10 @@ export type {
   ToolInput,
   RegisterResult,
   RegisterWithToolsResult,
+  UnifiedProfile,
+  MplAgentSnapshot,
+  Eip8004Registration,
+  Eip8004Service,
+  AttachAgentIdentityOpts,
+  UpdateAgentIdentityUriOpts,
 } from "./registries/index";

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/registries/index.ts

@@ -76,3 +76,13 @@ export type {
   RegisterResult,
   RegisterWithToolsResult,
 } from "./builder";
+
+export { MetaplexBridge } from "./metaplex-bridge";
+export type {
+  UnifiedProfile,
+  MplAgentSnapshot,
+  Eip8004Registration,
+  Eip8004Service,
+  AttachAgentIdentityOpts,
+  UpdateAgentIdentityUriOpts,
+} from "./metaplex-bridge";