xytara 3.1.13 → 3.1.15

package/lib/x402_facilitator.js

@@ -1,191 +1,198 @@
-"use strict";
-
-const { buildCdpBearerToken } = require("./cdp_jwt");
-
-// Self-contained x402 v2 facilitator client for the main runtime.
-//
-// This mirrors the proven logic in services/mcp-execution-target/server.js but takes
-// all configuration as explicit arguments so it has no dependency on any global state
-// and can be reused by any paid route. It is intentionally duplicated rather than shared
-// with the standalone MCP executor, which deploys from its own subdirectory.
-//
-// The trust model is the same one proven live: this process never verifies balances or
-// broadcasts transfers itself. It asks an x402 facilitator to verify the buyer's signed
-// EIP-3009 authorization and to settle it on-chain, and refuses to serve work unless the
-// facilitator confirms both. If the facilitator is unreachable, access fails closed.
-
-function normalizeString(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
-
-function normalizeAddress(value) {
-  return normalizeString(value).toLowerCase();
-}
-
-// Decode a PAYMENT-SIGNATURE header into an x402 v2 payment payload.
-function decodePaymentSignatureHeader(value) {
-  const raw = normalizeString(value);
-  if (!raw) return null;
-  for (const encoding of ["base64url", "base64"]) {
-    try {
-      const decoded = Buffer.from(raw, encoding).toString("utf8");
-      const parsed = JSON.parse(decoded);
-      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
-      if (Number(parsed.x402Version) !== 2) continue;
-      if (!parsed.accepted || typeof parsed.accepted !== "object") continue;
-      if (!parsed.payload || typeof parsed.payload !== "object") continue;
-      return parsed;
-    } catch (_) {
-      // try the next encoding
-    }
-  }
-  return null;
-}
-
-// Find the advertised requirements entry the buyer claims to be paying.
-function matchAcceptedRequirements(paymentPayload, accepts) {
-  const accepted = paymentPayload && paymentPayload.accepted ? paymentPayload.accepted : null;
-  if (!accepted || !Array.isArray(accepts)) return null;
-  return (
-    accepts.find(
-      (entry) =>
-        entry.scheme === normalizeString(accepted.scheme) &&
-        entry.network === normalizeString(accepted.network) &&
-        normalizeAddress(entry.asset) === normalizeAddress(accepted.asset) &&
-        normalizeAddress(entry.payTo) === normalizeAddress(accepted.payTo) &&
-        String(entry.amount) === String(accepted.amount)
-    ) || null
-  );
-}
-
-function createFacilitatorClient(config) {
-  const url = normalizeString(config && config.url).replace(/\/$/, "");
-  const headers = config && config.headers && typeof config.headers === "object" ? config.headers : {};
-  const timeoutMs = Math.max(1000, Number(config && config.timeoutMs) || 15000);
-  // Optional Coinbase CDP auth: when a CDP Secret API Key is configured, a fresh short-lived
-  // EdDSA Bearer JWT is minted per request (CDP rejects static tokens). This is what unlocks
-  // the CDP-hosted facilitator and Base mainnet settlement.
-  const cdp = config && config.cdp && typeof config.cdp === "object" ? config.cdp : null;
-  const cdpKeyId = cdp ? normalizeString(cdp.key_id || cdp.keyId) : "";
-  const cdpKeySecret = cdp ? String((cdp.key_secret || cdp.keySecret) || "").trim() : "";
-  const cdpEnabled = Boolean(cdpKeyId && cdpKeySecret);
-
-  async function post(path, body) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    let authHeaders = {};
-    if (cdpEnabled) {
-      try {
-        const target = new URL(`${url}${path}`);
-        const token = buildCdpBearerToken({ keyId: cdpKeyId, keySecret: cdpKeySecret, method: "POST", host: target.host, path: target.pathname });
-        authHeaders = { Authorization: `Bearer ${token}` };
-      } catch (error) {
-        clearTimeout(timer);
-        return { ok: false, status: 0, json: null, error: error && error.message ? error.message : "cdp_jwt_failed" };
-      }
-    }
-    try {
-      const response = await fetch(`${url}${path}`, {
-        method: "POST",
-        headers: { "content-type": "application/json", accept: "application/json", ...headers, ...authHeaders },
-        body: JSON.stringify(body),
-        signal: controller.signal
-      });
-      const text = await response.text();
-      let json = null;
-      try {
-        json = text ? JSON.parse(text) : null;
-      } catch (_) {
-        json = null;
-      }
-      return { ok: response.ok, status: response.status, json, bodyExcerpt: text ? text.slice(0, 400) : "" };
-    } catch (error) {
-      return { ok: false, status: 0, json: null, error: error && error.message ? error.message : "facilitator_request_failed" };
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-
-  return {
-    verify: (payload, requirements) => post("/verify", { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements }),
-    settle: (payload, requirements) => post("/settle", { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements })
-  };
-}
-
-// Verify a buyer's x402 payment against the advertised requirements via the facilitator.
-// Returns { ok:true, authorization } or { ok:false, status:402, reason, detail }.
-async function verifyX402Payment({ paymentHeader, accepts, resourceUrl, facilitator }) {
-  const header = normalizeString(paymentHeader);
-  if (!header) {
-    return { ok: false, status: 402, reason: "payment_required" };
-  }
-  const paymentPayload = decodePaymentSignatureHeader(header);
-  if (!paymentPayload) {
-    return { ok: false, status: 402, reason: "payment_signature_invalid", detail: "PAYMENT-SIGNATURE must be a base64 JSON x402 v2 payment payload" };
-  }
-  const paymentRequirements = matchAcceptedRequirements(paymentPayload, accepts);
-  if (!paymentRequirements) {
-    return { ok: false, status: 402, reason: "payment_requirements_mismatch", detail: "accepted requirements do not match any advertised payment option" };
-  }
-  // The x402 v2 PaymentRequirements shape is exactly {scheme, network, asset, amount, payTo,
-  // maxTimeoutSeconds, extra} with no `resource` field (resource lives on the payload in v2).
-  // Adding one makes strict facilitators (e.g. Coinbase CDP) reject the request with HTTP 400
-  // and makes paymentRequirements diverge from paymentPayload.accepted, so send it clean.
-  // resourceUrl is accepted for API compatibility but intentionally not sent to the facilitator.
-  void resourceUrl;
-  const requirementsForFacilitator = { ...paymentRequirements };
-  const verification = await facilitator.verify(paymentPayload, requirementsForFacilitator);
-  // A facilitator signals an invalid payment either with a 200 and isValid:false (x402.org) or
-  // with a non-2xx status and the same body (Coinbase CDP returns HTTP 400). Treat any response
-  // that carries an isValid flag as a verification result; only a missing/garbled body is a
-  // genuine transport failure.
-  if (!verification.json || typeof verification.json.isValid === "undefined") {
-    const body = verification.bodyExcerpt ? ` body=${verification.bodyExcerpt}` : "";
-    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: verification.error || `facilitator verify returned HTTP ${verification.status}${body}` };
-  }
-  if (verification.json.isValid !== true) {
-    const detail = normalizeString(verification.json.invalidReason) || normalizeString(verification.json.invalidMessage) || "facilitator rejected the payment";
-    return { ok: false, status: 402, reason: "payment_verification_failed", detail };
-  }
-  return {
-    ok: true,
-    authorization: {
-      paymentPayload,
-      paymentRequirements: requirementsForFacilitator,
-      payer: normalizeString(verification.json.payer) || null
-    }
-  };
-}
-
-// Settle a verified payment on-chain via the facilitator (unless settlement is disabled).
-// Returns { ok:true, settlement } or { ok:false, status:402, reason, detail }.
-async function settleX402Payment({ authorization, facilitator, settle }) {
-  if (settle === false) {
-    return { ok: true, settlement: { success: true, skipped: true, reason: "settlement_disabled_by_operator", payer: authorization.payer } };
-  }
-  const settlement = await facilitator.settle(authorization.paymentPayload, authorization.paymentRequirements);
-  // As with verify, a facilitator may report a failed settlement with a non-2xx status and a
-  // body carrying success:false; only a missing/garbled body is a genuine transport failure.
-  if (!settlement.json || typeof settlement.json.success === "undefined") {
-    const body = settlement.bodyExcerpt ? ` body=${settlement.bodyExcerpt}` : "";
-    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: settlement.error || `facilitator settle returned HTTP ${settlement.status}${body}` };
-  }
-  if (settlement.json.success !== true) {
-    const detail = normalizeString(settlement.json.errorReason) || normalizeString(settlement.json.errorMessage) || "facilitator could not settle the payment";
-    return { ok: false, status: 402, reason: "payment_settlement_failed", detail };
-  }
-  return { ok: true, settlement: settlement.json };
-}
-
-function encodePaymentResponse(settlement) {
-  return Buffer.from(JSON.stringify(settlement), "utf8").toString("base64");
-}
-
-module.exports = {
-  decodePaymentSignatureHeader,
-  matchAcceptedRequirements,
-  createFacilitatorClient,
-  verifyX402Payment,
-  settleX402Payment,
-  encodePaymentResponse
-};
+"use strict";
+
+const { buildCdpBearerToken } = require("./cdp_jwt");
+
+// Self-contained x402 v2 facilitator client for the main runtime.
+//
+// This mirrors the proven logic in services/mcp-execution-target/server.js but takes
+// all configuration as explicit arguments so it has no dependency on any global state
+// and can be reused by any paid route. It is intentionally duplicated rather than shared
+// with the standalone MCP executor, which deploys from its own subdirectory.
+//
+// The trust model is the same one proven live: this process never verifies balances or
+// broadcasts transfers itself. It asks an x402 facilitator to verify the buyer's signed
+// EIP-3009 authorization and to settle it on-chain, and refuses to serve work unless the
+// facilitator confirms both. If the facilitator is unreachable, access fails closed.
+
+function normalizeString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function normalizeAddress(value) {
+  return normalizeString(value).toLowerCase();
+}
+
+// Decode a PAYMENT-SIGNATURE header into an x402 v2 payment payload.
+function decodePaymentSignatureHeader(value) {
+  const raw = normalizeString(value);
+  if (!raw) return null;
+  for (const encoding of ["base64url", "base64"]) {
+    try {
+      const decoded = Buffer.from(raw, encoding).toString("utf8");
+      const parsed = JSON.parse(decoded);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      if (Number(parsed.x402Version) !== 2) continue;
+      if (!parsed.accepted || typeof parsed.accepted !== "object") continue;
+      if (!parsed.payload || typeof parsed.payload !== "object") continue;
+      return parsed;
+    } catch (_) {
+      // try the next encoding
+    }
+  }
+  return null;
+}
+
+// Find the advertised requirements entry the buyer claims to be paying.
+function matchAcceptedRequirements(paymentPayload, accepts) {
+  const accepted = paymentPayload && paymentPayload.accepted ? paymentPayload.accepted : null;
+  if (!accepted || !Array.isArray(accepts)) return null;
+  return (
+    accepts.find(
+      (entry) =>
+        entry.scheme === normalizeString(accepted.scheme) &&
+        entry.network === normalizeString(accepted.network) &&
+        normalizeAddress(entry.asset) === normalizeAddress(accepted.asset) &&
+        normalizeAddress(entry.payTo) === normalizeAddress(accepted.payTo) &&
+        String(entry.amount) === String(accepted.amount)
+    ) || null
+  );
+}
+
+function createFacilitatorClient(config) {
+  const url = normalizeString(config && config.url).replace(/\/$/, "");
+  const headers = config && config.headers && typeof config.headers === "object" ? config.headers : {};
+  const timeoutMs = Math.max(1000, Number(config && config.timeoutMs) || 15000);
+  // Optional Coinbase CDP auth: when a CDP Secret API Key is configured, a fresh short-lived
+  // EdDSA Bearer JWT is minted per request (CDP rejects static tokens). This is what unlocks
+  // the CDP-hosted facilitator and Base mainnet settlement.
+  const cdp = config && config.cdp && typeof config.cdp === "object" ? config.cdp : null;
+  const cdpKeyId = cdp ? normalizeString(cdp.key_id || cdp.keyId) : "";
+  const cdpKeySecret = cdp ? String((cdp.key_secret || cdp.keySecret) || "").trim() : "";
+  const cdpEnabled = Boolean(cdpKeyId && cdpKeySecret);
+
+  async function post(path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let authHeaders = {};
+    if (cdpEnabled) {
+      try {
+        const target = new URL(`${url}${path}`);
+        const token = buildCdpBearerToken({ keyId: cdpKeyId, keySecret: cdpKeySecret, method: "POST", host: target.host, path: target.pathname });
+        authHeaders = { Authorization: `Bearer ${token}` };
+      } catch (error) {
+        clearTimeout(timer);
+        return { ok: false, status: 0, json: null, error: error && error.message ? error.message : "cdp_jwt_failed" };
+      }
+    }
+    try {
+      const response = await fetch(`${url}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json", ...headers, ...authHeaders },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      const text = await response.text();
+      let json = null;
+      try {
+        json = text ? JSON.parse(text) : null;
+      } catch (_) {
+        json = null;
+      }
+      return { ok: response.ok, status: response.status, json, bodyExcerpt: text ? text.slice(0, 400) : "" };
+    } catch (error) {
+      return { ok: false, status: 0, json: null, error: error && error.message ? error.message : "facilitator_request_failed" };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return {
+    verify: (payload, requirements) => post("/verify", { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements }),
+    settle: (payload, requirements) => post("/settle", { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements })
+  };
+}
+
+// Verify a buyer's x402 payment against the advertised requirements via the facilitator.
+// Returns { ok:true, authorization } or { ok:false, status:402, reason, detail }.
+async function verifyX402Payment({ paymentHeader, accepts, resourceUrl, facilitator }) {
+  const header = normalizeString(paymentHeader);
+  if (!header) {
+    return { ok: false, status: 402, reason: "payment_required" };
+  }
+  const paymentPayload = decodePaymentSignatureHeader(header);
+  if (!paymentPayload) {
+    return { ok: false, status: 402, reason: "payment_signature_invalid", detail: "PAYMENT-SIGNATURE must be a base64 JSON x402 v2 payment payload" };
+  }
+  const paymentRequirements = matchAcceptedRequirements(paymentPayload, accepts);
+  if (!paymentRequirements) {
+    return { ok: false, status: 402, reason: "payment_requirements_mismatch", detail: "accepted requirements do not match any advertised payment option" };
+  }
+  // The x402 v2 PaymentRequirements shape is exactly {scheme, network, asset, amount, payTo,
+  // maxTimeoutSeconds, extra} with no `resource` field (resource lives on the payload in v2).
+  // Adding one makes strict facilitators (e.g. Coinbase CDP) reject the request with HTTP 400
+  // and makes paymentRequirements diverge from paymentPayload.accepted, so send it clean.
+  // resourceUrl is accepted for API compatibility but intentionally not sent to the facilitator.
+  void resourceUrl;
+  // maxTimeoutSeconds is not part of the match (validBefore inside the signed authorization is what
+  // binds time), so echo the buyer's value: requirements must equal paymentPayload.accepted even if
+  // the buyer signed against an older challenge with a different window.
+  const acceptedTimeout = Number(paymentPayload.accepted && paymentPayload.accepted.maxTimeoutSeconds);
+  const requirementsForFacilitator = {
+    ...paymentRequirements,
+    ...(Number.isFinite(acceptedTimeout) && acceptedTimeout > 0 ? { maxTimeoutSeconds: acceptedTimeout } : {})
+  };
+  const verification = await facilitator.verify(paymentPayload, requirementsForFacilitator);
+  // A facilitator signals an invalid payment either with a 200 and isValid:false (x402.org) or
+  // with a non-2xx status and the same body (Coinbase CDP returns HTTP 400). Treat any response
+  // that carries an isValid flag as a verification result; only a missing/garbled body is a
+  // genuine transport failure.
+  if (!verification.json || typeof verification.json.isValid === "undefined") {
+    const body = verification.bodyExcerpt ? ` body=${verification.bodyExcerpt}` : "";
+    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: verification.error || `facilitator verify returned HTTP ${verification.status}${body}` };
+  }
+  if (verification.json.isValid !== true) {
+    const detail = normalizeString(verification.json.invalidReason) || normalizeString(verification.json.invalidMessage) || "facilitator rejected the payment";
+    return { ok: false, status: 402, reason: "payment_verification_failed", detail };
+  }
+  return {
+    ok: true,
+    authorization: {
+      paymentPayload,
+      paymentRequirements: requirementsForFacilitator,
+      payer: normalizeString(verification.json.payer) || null
+    }
+  };
+}
+
+// Settle a verified payment on-chain via the facilitator (unless settlement is disabled).
+// Returns { ok:true, settlement } or { ok:false, status:402, reason, detail }.
+async function settleX402Payment({ authorization, facilitator, settle }) {
+  if (settle === false) {
+    return { ok: true, settlement: { success: true, skipped: true, reason: "settlement_disabled_by_operator", payer: authorization.payer } };
+  }
+  const settlement = await facilitator.settle(authorization.paymentPayload, authorization.paymentRequirements);
+  // As with verify, a facilitator may report a failed settlement with a non-2xx status and a
+  // body carrying success:false; only a missing/garbled body is a genuine transport failure.
+  if (!settlement.json || typeof settlement.json.success === "undefined") {
+    const body = settlement.bodyExcerpt ? ` body=${settlement.bodyExcerpt}` : "";
+    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: settlement.error || `facilitator settle returned HTTP ${settlement.status}${body}` };
+  }
+  if (settlement.json.success !== true) {
+    const detail = normalizeString(settlement.json.errorReason) || normalizeString(settlement.json.errorMessage) || "facilitator could not settle the payment";
+    return { ok: false, status: 402, reason: "payment_settlement_failed", detail };
+  }
+  return { ok: true, settlement: settlement.json };
+}
+
+function encodePaymentResponse(settlement) {
+  return Buffer.from(JSON.stringify(settlement), "utf8").toString("base64");
+}
+
+module.exports = {
+  decodePaymentSignatureHeader,
+  matchAcceptedRequirements,
+  createFacilitatorClient,
+  verifyX402Payment,
+  settleX402Payment,
+  encodePaymentResponse
+};

package/lib/x402_lane_contract.js

@@ -26,7 +26,8 @@ function buildX402LanePack() {
     lane_state: "first_party_x402_present",
     default_protocol: centerSummary.default_protocol,
     default_payment_protocol: "x402",
-    default_settlement_mode: centerSummary.default_settlement_mode,
+    // The x402 lane settles USDC on Base through an x402 facilitator (EIP-3009 exact scheme).
+    default_settlement_mode: "x402_evm_exact",
     default_transaction_center: center,
     default_path: defaultX402Path,
     release_default_path: releasePack.default_path,
@@ -93,8 +94,9 @@ function buildX402LanePack() {
       }
     ],
     settlement_posture: {
-      default_mode: centerSummary.default_settlement_mode,
-      current_native_lane: "bsv_teranode",
+      default_mode: "x402_evm_exact",
+      current_native_lane: "x402_evm_exact",
+      runtime_default_settlement_mode: centerSummary.default_settlement_mode,
       native_readiness_surface: "/v1/settlement/bsv-teranode/readiness",
       challenge_quote_hints: [
         "payment quotes carry settlement-aware runtime linkage",

package/lib/x402_settlement_recovery.js

@@ -0,0 +1,175 @@
+"use strict";
+
+const { decodePaymentSignatureHeader } = require("./x402_facilitator");
+
+// Settlement-outcome recovery for the deferred x402 lane.
+//
+// A facilitator /settle that times out or drops the connection does NOT mean the transfer failed:
+// the facilitator may already have broadcast it. Telling the buyer "you were not charged" and
+// withholding the result could leave them charged with nothing. Instead we ask the chain: an
+// EIP-3009 authorization that was used is a settled payment (USDC authorizationState(authorizer,
+// nonce) == true). And every settled (or not-yet-confirmed) result is kept briefly under its
+// payment nonce, so a buyer who lost the response — or was told to wait — can resend the SAME
+// payment signature and receive the result instead of paying again.
+
+const AUTHORIZATION_STATE_SELECTOR = "0xe94a0102"; // authorizationState(address,bytes32)
+const DEFAULT_RPC_URLS = {
+  "eip155:8453": "https://mainnet.base.org",
+  "eip155:84532": "https://sepolia.base.org"
+};
+const REPLAY_TTL_MS = 15 * 60 * 1000;
+const REPLAY_MAX = 1000;
+
+function rpcUrlFor(network) {
+  const key = `XYTARA_RPC_URL_${String(network || "").replace(/[^0-9A-Za-z]/g, "_").toUpperCase()}`;
+  const fromEnv = String(process.env[key] || "").trim();
+  return fromEnv || DEFAULT_RPC_URLS[String(network || "").toLowerCase()] || null;
+}
+
+function hex32(value, bytes) {
+  const clean = String(value || "").toLowerCase().replace(/^0x/, "");
+  if (!/^[0-9a-f]*$/.test(clean) || clean.length > bytes * 2) return null;
+  return clean.padStart(64, "0");
+}
+
+// true = authorization used (payment settled), false = not used, null = could not tell.
+async function authorizationUsed({ network, asset, authorizer, nonce }, options = {}) {
+  const url = rpcUrlFor(network);
+  const from = hex32(authorizer, 20);
+  const n = hex32(nonce, 32);
+  if (!url || !from || !n || !/^0x[0-9a-fA-F]{40}$/.test(String(asset || ""))) return null;
+  const fetchImpl = options.fetch || fetch;
+  try {
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_call", params: [{ to: asset, data: `${AUTHORIZATION_STATE_SELECTOR}${from}${n}` }, "latest"] }),
+      signal: AbortSignal.timeout(options.timeoutMs || 5000)
+    });
+    const json = await response.json();
+    if (!json || typeof json.result !== "string" || !/^0x[0-9a-fA-F]+$/.test(json.result)) return null;
+    return BigInt(json.result) !== 0n;
+  } catch (_) {
+    return null;
+  }
+}
+
+// A just-broadcast transfer may not be mined yet: poll a few times before concluding.
+async function confirmAuthorizationUsed(ref, options = {}) {
+  const attempts = options.attempts || 3;
+  const delayMs = options.delayMs === undefined ? 2000 : options.delayMs;
+  let sawAnswer = false;
+  for (let i = 0; i < attempts; i += 1) {
+    const used = await authorizationUsed(ref, options);
+    if (used === true) return true;
+    if (used === false) sawAnswer = true;
+    if (i < attempts - 1 && delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+  return sawAnswer ? false : null;
+}
+
+// The on-chain reference of a deferred x402 verification (or of a raw payment header).
+function authorizationRefFromVerification(verification) {
+  const deferred = verification && verification.deferred_settlement;
+  const auth = deferred && deferred.authorization;
+  const paymentPayload = auth && auth.paymentPayload;
+  const signed = paymentPayload && paymentPayload.payload && paymentPayload.payload.authorization;
+  const requirements = (auth && auth.paymentRequirements) || (paymentPayload && paymentPayload.accepted) || {};
+  if (!signed || !signed.nonce || !signed.from) return null;
+  return { network: requirements.network, asset: requirements.asset, authorizer: signed.from, nonce: signed.nonce };
+}
+
+function authorizationRefFromHeaders(headers) {
+  const decoded = decodePaymentSignatureHeader((headers || {})["payment-signature"]);
+  const signed = decoded && decoded.payload && decoded.payload.authorization;
+  if (!signed || !signed.nonce || !signed.from) return null;
+  return { network: decoded.accepted.network, asset: decoded.accepted.asset, authorizer: signed.from, nonce: signed.nonce };
+}
+
+function replayKey(ref) {
+  return ref ? `${String(ref.network || "").toLowerCase()}:${String(ref.nonce || "").toLowerCase()}` : null;
+}
+
+function ensureReplayStore(state) {
+  if (!(state.x402SettledReplays instanceof Map)) {
+    // In-memory only: non-enumerable, so it is never written to the state snapshot.
+    Object.defineProperty(state, "x402SettledReplays", { value: new Map(), enumerable: false, writable: true });
+  }
+  return state.x402SettledReplays;
+}
+
+function pruneReplays(store) {
+  const now = Date.now();
+  for (const [key, entry] of store) {
+    if (entry.expires_at_ms <= now) store.delete(key);
+  }
+  while (store.size > REPLAY_MAX) store.delete(store.keys().next().value);
+}
+
+// entry: { status: "settled" | "unconfirmed", ref, response?, finalize?: async (settlement) => response }
+function rememberReplay(state, ref, entry) {
+  const key = replayKey(ref);
+  if (!key) return;
+  const store = ensureReplayStore(state);
+  pruneReplays(store);
+  store.set(key, { ...entry, ref, expires_at_ms: Date.now() + REPLAY_TTL_MS });
+}
+
+// A resent payment that we already settled (or were confirming) gets its result, not a re-run.
+// The payment authorization becomes public on-chain once settled, so it is not enough on its own:
+// the resent REQUEST must match the original too (request_digest), or nothing is returned.
+async function resolveReplay(state, headers, options = {}) {
+  const ref = authorizationRefFromHeaders(headers);
+  const key = replayKey(ref);
+  if (!key) return null;
+  const store = ensureReplayStore(state);
+  pruneReplays(store);
+  const entry = store.get(key);
+  if (!entry) return null;
+  if (String(entry.ref.authorizer || "").toLowerCase() !== String(ref.authorizer || "").toLowerCase()) return null;
+  if (!entry.request_digest || entry.request_digest !== options.request_digest) {
+    return {
+      status: 409,
+      payload: {
+        ok: false,
+        reason: "payment_already_used",
+        detail: "This payment authorization was already used for a different request. Sign a new payment for this request."
+      }
+    };
+  }
+  if (entry.status === "settled" && entry.response) {
+    return { ...entry.response, payload: { ...entry.response.payload, replayed: true } };
+  }
+  const used = await confirmAuthorizationUsed(entry.ref, { attempts: 1, ...(options.rpc || {}) });
+  if (used === true && typeof entry.finalize === "function") {
+    const response = await entry.finalize({ success: true, transaction: null, network: entry.ref.network, payer: entry.ref.authorizer, recovered_from: "authorization_state" });
+    store.set(key, { ...entry, status: "settled", response, finalize: undefined });
+    return { ...response, payload: { ...response.payload, replayed: true } };
+  }
+  if (used === false) {
+    // Never settled: forget it so the payment is verified and executed normally.
+    store.delete(key);
+    return null;
+  }
+  return {
+    status: 409,
+    payload: {
+      ok: false,
+      reason: "settlement_outcome_unknown",
+      detail: "We are still confirming whether this payment settled on-chain. Resend the same payment signature in a minute to receive the result; do not sign a new payment.",
+      payment_settled: null
+    },
+    headers: { "Retry-After": "30" }
+  };
+}
+
+module.exports = {
+  AUTHORIZATION_STATE_SELECTOR,
+  authorizationRefFromHeaders,
+  authorizationRefFromVerification,
+  authorizationUsed,
+  confirmAuthorizationUsed,
+  rememberReplay,
+  resolveReplay,
+  rpcUrlFor
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xytara",
-  "version": "3.1.13",
+  "version": "3.1.15",
   "description": "x402 pay-per-call agent-commerce runtime: gasless USDC on Base, an open settling provider network with a ledger-reconciled revenue split and automated on-chain payouts (key-less runtime, delegated signer), and bounded cryptographic delegated spend. Proven live on Base mainnet.",
   "main": "index.js",
   "bin": {
@@ -106,7 +106,7 @@
     "verify:production-readiness": "node scripts/verify_production_readiness.js",
     "verify:final-activation": "node scripts/verify_final_activation.js",
     "verify:x402-facilitator": "node scripts/verify_x402_facilitator.js",
-    "verify:all": "node scripts/verify_all.js && node scripts/verify_integrations.js && node scripts/verify_adapters.js && node scripts/verify_control_plane_contracts.js && node scripts/verify_control_plane_routes.js && node scripts/verify_framework_provider_promotion.js && node scripts/verify_operator_observability_boundary.js && node scripts/verify_pricing_experiment_plan.js && node scripts/verify_treasury_public_boundary.js && node scripts/verify_market_lanes.js && node scripts/verify_market_lane_depth.js && node scripts/verify_market_lane_traces.js && node scripts/verify_market_lane_promotion.js && node scripts/verify_provider_runtime_breadth.js && node scripts/verify_provider_runtime_journeys.js && node scripts/verify_lifecycle_continuity.js && node scripts/verify_first_run_conversions.js && node scripts/verify_delivery_summary.js && node scripts/verify_runtime_durability.js && node scripts/verify_revenue_launch_paths.js && node scripts/verify_full_catalog.js && node scripts/verify_tooling.js && node scripts/verify_examples.js && node scripts/verify_service.js && node scripts/verify_x402_facilitator.js && node scripts/verify_cdp_facilitator.js && node scripts/verify_a2a_rpc.js && node scripts/verify_checkout_processor.js && node scripts/verify_l402_adapter.js && node scripts/verify_bolt_adapter.js && node scripts/verify_mpp_adapter.js && node scripts/verify_rate_limiter.js && node scripts/verify_execution_surfacing.js && node scripts/verify_agent_identity.js && node scripts/verify_verify_execute_settle.js && node scripts/verify_execution_dedupe.js && node scripts/verify_refund_credit.js && node scripts/verify_commerce_bridge.js && node scripts/verify_settlement.js && node scripts/verify_provider_network.js && node scripts/verify_external_execution_retry.js",
+    "verify:all": "node scripts/verify_all.js && node scripts/verify_integrations.js && node scripts/verify_adapters.js && node scripts/verify_control_plane_contracts.js && node scripts/verify_control_plane_routes.js && node scripts/verify_framework_provider_promotion.js && node scripts/verify_operator_observability_boundary.js && node scripts/verify_pricing_experiment_plan.js && node scripts/verify_treasury_public_boundary.js && node scripts/verify_market_lanes.js && node scripts/verify_market_lane_depth.js && node scripts/verify_market_lane_traces.js && node scripts/verify_market_lane_promotion.js && node scripts/verify_provider_runtime_breadth.js && node scripts/verify_provider_runtime_journeys.js && node scripts/verify_lifecycle_continuity.js && node scripts/verify_first_run_conversions.js && node scripts/verify_delivery_summary.js && node scripts/verify_runtime_durability.js && node scripts/verify_revenue_launch_paths.js && node scripts/verify_full_catalog.js && node scripts/verify_tooling.js && node scripts/verify_examples.js && node scripts/verify_service.js && node scripts/verify_x402_facilitator.js && node scripts/verify_cdp_facilitator.js && node scripts/verify_a2a_rpc.js && node scripts/verify_checkout_processor.js && node scripts/verify_l402_adapter.js && node scripts/verify_bolt_adapter.js && node scripts/verify_mpp_adapter.js && node scripts/verify_rate_limiter.js && node scripts/verify_execution_surfacing.js && node scripts/verify_agent_identity.js && node scripts/verify_verify_execute_settle.js && node scripts/verify_execution_dedupe.js && node scripts/verify_refund_credit.js && node scripts/verify_commerce_bridge.js && node scripts/verify_settlement.js && node scripts/verify_provider_network.js && node scripts/verify_external_execution_retry.js && node scripts/verify_runtime_state_guard.js && node scripts/state_backup_offsite.js selftest && node scripts/verify_lifecycle_spend_binding.js && node scripts/verify_buyer_safety.js && node scripts/verify_buyer_event_log.js && node scripts/verify_x402_settlement_recovery.js",
     "prepublishOnly": "npm run verify:release-candidate",
     "verify:cdp-facilitator": "node scripts/verify_cdp_facilitator.js",
     "verify:a2a-rpc": "node scripts/verify_a2a_rpc.js",
@@ -123,6 +123,12 @@
     "verify:commerce-bridge": "node scripts/verify_commerce_bridge.js",
     "verify:settlement": "node scripts/verify_settlement.js",
     "verify:provider-network": "node scripts/verify_provider_network.js",
-    "verify:external-execution-retry": "node scripts/verify_external_execution_retry.js"
+    "verify:external-execution-retry": "node scripts/verify_external_execution_retry.js",
+    "verify:runtime-state-guard": "node scripts/verify_runtime_state_guard.js",
+    "verify:state-backup": "node scripts/state_backup_offsite.js selftest",
+    "verify:lifecycle-spend-binding": "node scripts/verify_lifecycle_spend_binding.js",
+    "verify:buyer-safety": "node scripts/verify_buyer_safety.js",
+    "verify:buyer-event-log": "node scripts/verify_buyer_event_log.js",
+    "verify:x402-settlement-recovery": "node scripts/verify_x402_settlement_recovery.js"
   }
 }