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

package/src/constants/payments.ts

@@ -0,0 +1,92 @@
+/**
+ * @module constants/payments
+ * @description Payment-token allowlist + agent stake collateral constants
+ *   mirroring the on-chain v0.10.0 hardening.
+ *
+ *   The on-chain program now accepts only:
+ *   - **Native SOL** — signalled by `tokenMint = null` on escrow creation.
+ *   - **USDC mainnet** — `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`.
+ *   - **USDC devnet**  — `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`.
+ *
+ *   Any other SPL mint passed to `createEscrow` / `createEscrowV2` is
+ *   rejected on-chain with `PaymentTokenNotAllowed` (error code 6093).
+ *
+ *   Additionally, the agent owner MUST have an `AgentStake` PDA with
+ *   `staked_amount >= MIN_AGENT_STAKE_LAMPORTS` (0.1 SOL) BEFORE any
+ *   client can create a new escrow against that agent. Use
+ *   {@link StakingModule.initStake} + {@link StakingModule.deposit}
+ *   to satisfy the requirement.
+ *
+ * @category Constants
+ * @since v0.10.0
+ */
+
+import { PublicKey } from "@solana/web3.js";
+
+/**
+ * USDC mint on Solana mainnet-beta (Circle).
+ *
+ * @name USDC_MINT_MAINNET
+ * @category Constants
+ * @since v0.10.0
+ */
+export const USDC_MINT_MAINNET = new PublicKey(
+  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+);
+
+/**
+ * USDC mint on Solana devnet (Circle test mint).
+ *
+ * @name USDC_MINT_DEVNET
+ * @category Constants
+ * @since v0.10.0
+ */
+export const USDC_MINT_DEVNET = new PublicKey(
+  "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
+);
+
+/**
+ * Minimum agent stake required to gate escrow creation, expressed in lamports.
+ * Mirrors `AgentStake::MIN_STAKE` on-chain (`100_000_000` = 0.1 SOL).
+ *
+ * @name MIN_AGENT_STAKE_LAMPORTS
+ * @category Constants
+ * @since v0.10.0
+ */
+export const MIN_AGENT_STAKE_LAMPORTS = BigInt(100_000_000);
+
+/**
+ * Maximum delegate duration (seconds) accepted by `add_vault_delegate`.
+ * Mirrors `VaultDelegate::MAX_DELEGATE_DURATION_SECS` on-chain
+ * (`365 * 86_400` = 1 year).
+ *
+ * @name MAX_DELEGATE_DURATION_SECS
+ * @category Constants
+ * @since v0.10.0
+ */
+export const MAX_DELEGATE_DURATION_SECS = 365 * 86_400;
+
+/**
+ * Returns true when `mint` is an accepted USDC mint (mainnet or devnet).
+ *
+ * @name isAcceptedUsdcMint
+ * @param mint - Candidate SPL token mint.
+ * @category Constants
+ * @since v0.10.0
+ */
+export function isAcceptedUsdcMint(mint: PublicKey): boolean {
+  return mint.equals(USDC_MINT_MAINNET) || mint.equals(USDC_MINT_DEVNET);
+}
+
+/**
+ * Returns true when the (optional) `tokenMint` is acceptable as escrow payment.
+ * `null` represents native SOL and is always accepted.
+ *
+ * @name isAcceptedPaymentToken
+ * @param tokenMint - The mint passed to `createEscrow*`. `null` = SOL.
+ * @category Constants
+ * @since v0.10.0
+ */
+export function isAcceptedPaymentToken(tokenMint: PublicKey | null): boolean {
+  return tokenMint === null || isAcceptedUsdcMint(tokenMint);
+}

package/src/constants/seeds.ts

@@ -61,7 +61,15 @@ export const SEEDS = {
   SUBSCRIPTION: "sap_sub",
   SHARD: "sap_shard",
   INDEX_PAGE: "sap_idx_page",
-  /** @since v0.7.0 — Receipt batch merkle root PDA */
+  /**
+   * @since v0.10.0 — Anti-replay receipt PDA bound to (escrow, service_hash) or (escrow, batch_root).
+   * Created via `init` on every settle_calls / settle_batch / settle_calls_v2; replays fail.
+   */
+  SETTLEMENT_RECEIPT: "sap_recv",
+  /**
+   * @deprecated v0.10.0 — Was reserved for receipt batch merkle root (never used on-chain).
+   * Use {@link SEEDS.SETTLEMENT_RECEIPT} (`sap_recv`) instead. Will be removed in v0.11.0.
+   */
   RECEIPT: "sap_receipt",
 } as const;
 

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

@@ -184,12 +184,23 @@ export {
   deriveLedger,
   deriveLedgerPage,
   deriveReceiptBatch,
+  deriveSettlementReceipt,
 } from "./pda";
 
 // ── Utilities ────────────────────────────────────────
-export { sha256, hashToArray, assert } from "./utils";
+export { sha256, hashToArray, assert, computeBatchRoot } from "./utils";
 export { serializeAccount, serializeValue } from "./utils";
 
+// v0.10 — payment + stake constants
+export {
+  USDC_MINT_MAINNET,
+  USDC_MINT_DEVNET,
+  MIN_AGENT_STAKE_LAMPORTS,
+  MAX_DELEGATE_DURATION_SECS,
+  isAcceptedUsdcMint,
+  isAcceptedPaymentToken,
+} from "./constants";
+
 // v0.6.0 — Network normalizer
 export {
   normalizeNetworkId,

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,
       );