@oobe-protocol-labs/synapse-sap-sdk 0.9.3 → 0.10.0

package/src/idl/synapse_agent_sap.json

@@ -2,7 +2,7 @@
   "address": "SAPpUhsWLJG1FfkGRcXagEDMrMsWGjbky7AyhGpFETZ",
   "metadata": {
     "name": "synapse_agent_sap",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "spec": "0.1.0",
     "description": "Created with Anchor"
   },
@@ -2693,6 +2693,37 @@
             "Agent to prepay for — anyone can create escrow"
           ]
         },
+        {
+          "name": "agent_stake",
+          "docs": [
+            "v0.10 hardening: agent MUST hold at least `AgentStake::MIN_STAKE`",
+            "in collateral before any new escrow can be opened.  This guarantees",
+            "every accepted client has a slashable bond to claim against in case",
+            "of dispute."
+          ],
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  115,
+                  97,
+                  112,
+                  95,
+                  115,
+                  116,
+                  97,
+                  107,
+                  101
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "agent"
+              }
+            ]
+          }
+        },
         {
           "name": "escrow",
           "writable": true,
@@ -2792,6 +2823,35 @@
         {
           "name": "agent"
         },
+        {
+          "name": "agent_stake",
+          "docs": [
+            "v0.10 hardening: agent MUST have an active stake ≥ MIN_STAKE",
+            "before any new escrow can be opened."
+          ],
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  115,
+                  97,
+                  112,
+                  95,
+                  115,
+                  116,
+                  97,
+                  107,
+                  101
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "agent"
+              }
+            ]
+          }
+        },
         {
           "name": "escrow",
           "writable": true,
@@ -6956,7 +7016,9 @@
     {
       "name": "settle_batch",
       "docs": [
-        "Batch settle up to 10 settlements in one TX. Volume curve spans batch."
+        "Batch settle up to 10 settlements in one TX. Volume curve spans batch.",
+        "v0.10: requires `batch_root = sha256(s_0 || s_1 || ... || s_{N-1})`",
+        "to seed the anti-replay receipt PDA."
       ],
       "discriminator": [
         22,
@@ -7056,6 +7118,44 @@
               }
             ]
           }
+        },
+        {
+          "name": "settlement_receipt",
+          "docs": [
+            "v0.10 anti-replay: PDA bound to the batch_root (sha256 of all",
+            "service_hashes in order).  Replaying the same batch fails the",
+            "`init` constraint."
+          ],
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  115,
+                  97,
+                  112,
+                  95,
+                  114,
+                  101,
+                  99,
+                  118
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "escrow"
+              },
+              {
+                "kind": "arg",
+                "path": "batch_root"
+              }
+            ]
+          }
+        },
+        {
+          "name": "system_program",
+          "address": "11111111111111111111111111111111"
         }
       ],
       "args": [
@@ -7068,6 +7168,15 @@
               }
             }
           }
+        },
+        {
+          "name": "batch_root",
+          "type": {
+            "array": [
+              "u8",
+              32
+            ]
+          }
         }
       ]
     },
@@ -7180,6 +7289,45 @@
               }
             ]
           }
+        },
+        {
+          "name": "settlement_receipt",
+          "docs": [
+            "v0.10 anti-replay: an `init` of this PDA fails if the same",
+            "`service_hash` was already used to settle this escrow.",
+            "Receipt PDAs are intentionally NOT closeable to preserve the",
+            "uniqueness invariant for the lifetime of the escrow."
+          ],
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  115,
+                  97,
+                  112,
+                  95,
+                  114,
+                  101,
+                  99,
+                  118
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "escrow"
+              },
+              {
+                "kind": "arg",
+                "path": "service_hash"
+              }
+            ]
+          }
+        },
+        {
+          "name": "system_program",
+          "address": "11111111111111111111111111111111"
         }
       ],
       "args": [
@@ -7312,6 +7460,41 @@
             ]
           }
         },
+        {
+          "name": "settlement_receipt",
+          "docs": [
+            "v0.10 anti-replay: PDA bound to (escrow, service_hash).",
+            "In CoSigned mode this gates the immediate transfer; in",
+            "DisputeWindow mode this gates the pending-amount bump so the",
+            "same `service_hash` cannot be re-applied to inflate pending."
+          ],
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  115,
+                  97,
+                  112,
+                  95,
+                  114,
+                  101,
+                  99,
+                  118
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "escrow"
+              },
+              {
+                "kind": "arg",
+                "path": "service_hash"
+              }
+            ]
+          }
+        },
         {
           "name": "system_program",
           "address": "11111111111111111111111111111111"
@@ -8486,6 +8669,19 @@
         179
       ]
     },
+    {
+      "name": "SettlementReceipt",
+      "discriminator": [
+        52,
+        249,
+        252,
+        121,
+        4,
+        232,
+        187,
+        4
+      ]
+    },
     {
       "name": "Subscription",
       "discriminator": [
@@ -9980,6 +10176,41 @@
       "code": 6136,
       "name": "InvalidReceiptProof",
       "msg": "bad receipt proof"
+    },
+    {
+      "code": 6137,
+      "name": "SettlementReplay",
+      "msg": "settlement replay"
+    },
+    {
+      "code": 6138,
+      "name": "PaymentTokenNotAllowed",
+      "msg": "token not allowed"
+    },
+    {
+      "code": 6139,
+      "name": "AgentStakeRequired",
+      "msg": "agent stake required"
+    },
+    {
+      "code": 6140,
+      "name": "DelegateExpiryInvalid",
+      "msg": "delegate expiry invalid"
+    },
+    {
+      "code": 6141,
+      "name": "EscrowNotClosed",
+      "msg": "escrow not closed"
+    },
+    {
+      "code": 6142,
+      "name": "VolumeCurveNotDescending",
+      "msg": "curve not descending"
+    },
+    {
+      "code": 6143,
+      "name": "DuplicateServiceHash",
+      "msg": "dup service hash"
     }
   ],
   "types": [
@@ -13125,6 +13356,43 @@
         ]
       }
     },
+    {
+      "name": "SettlementReceipt",
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "bump",
+            "type": "u8"
+          },
+          {
+            "name": "escrow",
+            "type": "pubkey"
+          },
+          {
+            "name": "service_hash",
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            "name": "calls_settled",
+            "type": "u64"
+          },
+          {
+            "name": "amount",
+            "type": "u64"
+          },
+          {
+            "name": "settled_at",
+            "type": "i64"
+          }
+        ]
+      }
+    },
     {
       "name": "SettlementSecurity",
       "docs": [

package/src/modules/escrow-v2.ts

@@ -23,6 +23,8 @@ import {
   deriveEscrowV2,
   derivePendingSettlement as derivePendingPda,
   deriveDispute as deriveDisputePda,
+  deriveStake,
+  deriveSettlementReceipt,
 } from "../pda";
 import type {
   EscrowAccountV2Data,
@@ -35,6 +37,7 @@ import {
   buildRpcOptions,
 } from "../utils/priority-fee";
 import type { SettleOptions } from "../utils/priority-fee";
+import { isAcceptedPaymentToken } from "../constants/payments";
 
 /**
  * @name EscrowV2Module
@@ -83,8 +86,17 @@ export class EscrowV2Module extends BaseModule {
     args: CreateEscrowV2Args,
     splAccounts: AccountMeta[] = [],
   ): Promise<TransactionSignature> {
+    // v0.10.0: payment-token allowlist (SOL or USDC only).
+    if (!isAcceptedPaymentToken(args.tokenMint ?? null)) {
+      throw new Error(
+        "createEscrowV2: tokenMint must be null (SOL) or USDC (mainnet/devnet). " +
+        "On-chain will reject with PaymentTokenNotAllowed.",
+      );
+    }
+
     const [agentPda] = deriveAgent(agentWallet);
     const [escrowPda] = this.deriveEscrow(agentPda, undefined, args.escrowNonce);
+    const [stakePda] = deriveStake(agentPda);
 
     return this.methods
       .createEscrowV2(
@@ -104,6 +116,7 @@ export class EscrowV2Module extends BaseModule {
       .accounts({
         depositor: this.walletPubkey,
         agent: agentPda,
+        agentStake: stakePda,
         escrow: escrowPda,
         systemProgram: SystemProgram.programId,
       })
@@ -142,6 +155,7 @@ export class EscrowV2Module extends BaseModule {
     const [agentPda] = deriveAgent(this.walletPubkey);
     const [escrowPda] = this.deriveEscrow(agentPda, depositorWallet, nonce);
     const [statsPda] = deriveAgentStats(agentPda);
+    const [receiptPda] = deriveSettlementReceipt(escrowPda, serviceHash);
 
     const preIxs = buildPriorityFeeIxs(opts);
     const rpcOpts = buildRpcOptions(opts);
@@ -153,6 +167,7 @@ export class EscrowV2Module extends BaseModule {
         agent: agentPda,
         agentStats: statsPda,
         escrow: escrowPda,
+        settlementReceipt: receiptPda,
         systemProgram: SystemProgram.programId,
       })
       .remainingAccounts(splAccounts);

package/src/modules/escrow.ts

@@ -23,6 +23,8 @@ import {
   deriveAgent,
   deriveAgentStats,
   deriveEscrow,
+  deriveStake,
+  deriveSettlementReceipt,
 } from "../pda";
 import type {
   EscrowAccountData,
@@ -34,6 +36,8 @@ import {
   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
@@ -105,9 +109,17 @@ export class EscrowModule extends BaseModule {
     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 [statsPda] = deriveAgentStats(agentPda);
+    const [stakePda] = deriveStake(agentPda);
 
     return this.methods
       .createEscrow(
@@ -122,7 +134,7 @@ export class EscrowModule extends BaseModule {
       .accounts({
         depositor: this.walletPubkey,
         agent: agentPda,
-        agentStats: statsPda,
+        agentStake: stakePda,
         escrow: escrowPda,
         systemProgram: SystemProgram.programId,
       })
@@ -181,6 +193,7 @@ export class EscrowModule extends BaseModule {
     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);
@@ -192,6 +205,7 @@ export class EscrowModule extends BaseModule {
         agent: agentPda,
         agentStats: statsPda,
         escrow: escrowPda,
+        settlementReceipt: receiptPda,
         systemProgram: SystemProgram.programId,
       })
       .remainingAccounts(splAccounts);
@@ -255,17 +269,26 @@ export class EscrowModule extends BaseModule {
    * @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> {
@@ -273,16 +296,26 @@ export class EscrowModule extends BaseModule {
     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);
+
     const preIxs = buildPriorityFeeIxs(opts);
     const rpcOpts = buildRpcOptions(opts);
 
     let builder = this.methods
-      .settleBatch(settlements)
+      .settleBatch(settlements, rootArr)
       .accounts({
         wallet: this.walletPubkey,
         agent: agentPda,
         agentStats: statsPda,
         escrow: escrowPda,
+        settlementReceipt: receiptPda,
         systemProgram: SystemProgram.programId,
       })
       .remainingAccounts(splAccounts);

package/src/pda/index.ts

@@ -878,3 +878,42 @@ export const deriveReceiptBatch = (
     ],
     programId,
   );
+
+/**
+ * Derive the **SettlementReceipt** PDA (v0.10.0 anti-replay).
+ *
+ * Seeds: `["sap_recv", escrow_pda, service_hash_or_batch_root]`
+ *
+ * Created via `init` on every `settle_calls`, `settle_batch`, and
+ * `settle_calls_v2`. The PDA's existence after the first call blocks
+ * any future replay of the same `service_hash` (or `batch_root`)
+ * against the same escrow.
+ *
+ * @name deriveSettlementReceipt
+ * @description Compute the receipt PDA that gates settlement replay.
+ * @param escrowPda     - Parent escrow PDA (V1 `EscrowAccount` or V2 `EscrowAccountV2`).
+ * @param receiptKey    - 32-byte `service_hash` (single settle / V2 settle)
+ *                        or `batch_root = sha256(s_0 || ... || s_{N-1})` (settle_batch).
+ * @param programId     - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.10.0
+ */
+export const deriveSettlementReceipt = (
+  escrowPda: PublicKey,
+  receiptKey: Uint8Array | number[] | Buffer,
+  programId = SAP_PROGRAM_ID,
+): PdaResult => {
+  const buf = Buffer.isBuffer(receiptKey)
+    ? receiptKey
+    : Buffer.from(receiptKey as Uint8Array);
+  if (buf.length !== 32) {
+    throw new Error(
+      `deriveSettlementReceipt: receiptKey must be 32 bytes, got ${buf.length}`,
+    );
+  }
+  return findPda(
+    [toSeedBuf(SEEDS.SETTLEMENT_RECEIPT), escrowPda.toBuffer(), buf],
+    programId,
+  );
+};

package/src/plugin/index.ts

@@ -782,6 +782,8 @@ async function executeEscrow(client: SapClient, name: string, input: any) {
       const tx = await client.escrow.settleBatch(
         new PublicKey(input.depositorWallet),
         settlements,
+        // batchRoot omitted \u2192 SDK auto-derives sha256(s_0 || ... || s_N)
+        undefined,
         [],
         batchOpts,
       );

package/src/utils/hash.ts

@@ -55,3 +55,59 @@ export const sha256 = (input: string | Buffer | Uint8Array): Uint8Array => {
  * ```
  */
 export const hashToArray = (hash: Uint8Array): number[] => Array.from(hash);
+
+/**
+ * Compute the deterministic batch root used by `settle_batch` (v0.10.0).
+ *
+ * The on-chain program enforces:
+ *   `batch_root == sha256(s_0 || s_1 || ... || s_{N-1})`
+ * where each `s_i` is a 32-byte service hash, in the same order as the
+ * `settlements: Settlement[]` array passed to the instruction.
+ *
+ * Use this helper to derive the seed for the {@link deriveSettlementReceipt}
+ * PDA when batching settlements.
+ *
+ * @name computeBatchRoot
+ * @param serviceHashes - Array of 32-byte service hashes (Buffer/Uint8Array/number[]).
+ * @returns {Uint8Array} 32-byte batch root.
+ * @throws If any `serviceHashes[i]` is not exactly 32 bytes long.
+ * @category Utils
+ * @since v0.10.0
+ *
+ * @example
+ * ```ts
+ * import { computeBatchRoot, hashToArray } from "@synapse-sap/sdk/utils";
+ *
+ * const root = computeBatchRoot([h1, h2, h3]);
+ * await client.escrow.settleBatch(depositor, settlements, root);
+ * ```
+ */
+export const computeBatchRoot = (
+  serviceHashes: ReadonlyArray<Uint8Array | Buffer | number[]>,
+): Uint8Array => {
+  if (serviceHashes.length === 0) {
+    throw new Error("computeBatchRoot: serviceHashes must not be empty");
+  }
+  const hash = createHash("sha256");
+  for (let i = 0; i < serviceHashes.length; i++) {
+    const h = serviceHashes[i];
+    let buf: Buffer;
+    if (h instanceof Uint8Array) {
+      buf = Buffer.from(h);
+    } else if (Array.isArray(h)) {
+      buf = Buffer.from(h);
+    } else {
+      throw new Error(
+        `computeBatchRoot: serviceHashes[${i}] is undefined or unsupported type`,
+      );
+    }
+    if (buf.length !== 32) {
+      throw new Error(
+        `computeBatchRoot: serviceHashes[${i}] must be 32 bytes, got ${buf.length}`,
+      );
+    }
+    hash.update(buf);
+  }
+  return new Uint8Array(hash.digest());
+};
+