@piprail/sdk 1.20.0 → 1.20.1

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [1.20.1] — 2026-06-11 — gate replay store: bounded + exception-safe
+
+Patch — internal robustness on the gate's built-in replay protection. No API change, no visible
+behaviour change, defaults identical.
+
+### Fixed
+- **Bounded the default used-proof set.** It's now evicted past the replay window
+  (`maxTimeoutSeconds`) instead of growing for the life of the process — safe because the driver's
+  recency check rejects any proof that old anyway, so a dropped entry still can't be replayed. A
+  long-lived gate no longer slowly leaks memory. Custom `isUsed`/`markUsed` stores are unaffected
+  (give them a TTL = the window).
+- **`onchain-proof` verification is now claim-release exception-safe.** If a driver's `verify()`
+  *throws* (an unexpected RPC exception) rather than returning a rejection, the gate now releases the
+  proof reservation before rethrowing — so a transient blip can't permanently burn an otherwise-valid
+  proof. This matches the `exact` path, which already did it.
+
+### Docs
+- Rewrote **[Replay protection & recovery](https://docs.piprail.com/accepting-payments/replay-protection/)**
+  with the full "paid but didn't receive — what happens to the payment?" model (a recoverability
+  matrix, the at-most-once-by-design rationale, the bounded-memory behaviour, and the client's
+  never-re-pay `.ref` recovery).
+
 ## [1.20.0] — 2026-06-11 — discovery hardening: conformance-locked, accurate timing, PipRail-attributed
 
 A minor release focused on the discovery/registration subsystem — verified live against the real

package/dist/index.cjs

@@ -4215,14 +4215,23 @@ function createPaymentGate(options) {
     };
   }
   const hasCustomStore = Boolean(options.isUsed || options.markUsed);
-  const localUsed = /* @__PURE__ */ new Set();
+  const localUsed = /* @__PURE__ */ new Map();
+  const replayWindowMs = maxTimeoutSeconds * 1e3;
+  function pruneUsed(now) {
+    for (const [key, expiry] of localUsed) {
+      if (expiry > now) break;
+      localUsed.delete(key);
+    }
+  }
   async function claimTx(ref) {
     if (hasCustomStore) {
       return options.isUsed ? Boolean(await options.isUsed(ref)) : false;
     }
     const key = ref.toLowerCase();
+    const now = Date.now();
+    pruneUsed(now);
     if (localUsed.has(key)) return true;
-    localUsed.add(key);
+    localUsed.set(key, now + replayWindowMs);
     return false;
   }
   async function settleTx(ref, ok) {
@@ -4382,7 +4391,13 @@ function createPaymentGate(options) {
     }
     const ref = sig.payload.txHash;
     if (await claimTx(ref)) return rejection("tx_already_used", `Proof ${ref} was already redeemed.`);
-    const result = await spec.net.verify(ref, buildAccept(spec, sig.payload.nonce));
+    let result;
+    try {
+      result = await spec.net.verify(ref, buildAccept(spec, sig.payload.nonce));
+    } catch (err) {
+      await settleTx(ref, false);
+      throw err;
+    }
     if (!result.ok) {
       await settleTx(ref, false);
       return rejection(result.error, result.detail);

package/dist/index.js

@@ -4215,14 +4215,23 @@ function createPaymentGate(options) {
     };
   }
   const hasCustomStore = Boolean(options.isUsed || options.markUsed);
-  const localUsed = /* @__PURE__ */ new Set();
+  const localUsed = /* @__PURE__ */ new Map();
+  const replayWindowMs = maxTimeoutSeconds * 1e3;
+  function pruneUsed(now) {
+    for (const [key, expiry] of localUsed) {
+      if (expiry > now) break;
+      localUsed.delete(key);
+    }
+  }
   async function claimTx(ref) {
     if (hasCustomStore) {
       return options.isUsed ? Boolean(await options.isUsed(ref)) : false;
     }
     const key = ref.toLowerCase();
+    const now = Date.now();
+    pruneUsed(now);
     if (localUsed.has(key)) return true;
-    localUsed.add(key);
+    localUsed.set(key, now + replayWindowMs);
     return false;
   }
   async function settleTx(ref, ok) {
@@ -4382,7 +4391,13 @@ function createPaymentGate(options) {
     }
     const ref = sig.payload.txHash;
     if (await claimTx(ref)) return rejection("tx_already_used", `Proof ${ref} was already redeemed.`);
-    const result = await spec.net.verify(ref, buildAccept(spec, sig.payload.nonce));
+    let result;
+    try {
+      result = await spec.net.verify(ref, buildAccept(spec, sig.payload.nonce));
+    } catch (err) {
+      await settleTx(ref, false);
+      throw err;
+    }
     if (!result.ok) {
       await settleTx(ref, false);
       return rejection(result.error, result.detail);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "1.20.0",
+  "version": "1.20.1",
   "description": "Accept x402 crypto payments across 29 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",