xytara 3.1.5 → 3.1.7

package/RELEASE_NOTES.md

@@ -1,11 +1,11 @@
-`xytara` 3.1.5 adds native Coinbase CDP facilitator support, unlocking Base mainnet settlement.
+`xytara` 3.1.7 completes the Coinbase CDP facilitator path, proven with a real Base mainnet settlement.
 
-The x402_facilitator mode now authenticates to facilitators that require a short-lived CDP Bearer token, so the runtime can settle real USDC on Base mainnet through the CDP-hosted facilitator, not just test USDC on Base Sepolia via the default facilitator.
+A facilitator can signal a verification or settlement result either with a 200 and the result in the body, or with a non-2xx status and the same body. Coinbase CDP returns HTTP 400 for an invalid payment (with `{isValid:false, invalidReason, invalidMessage}`). The client previously treated any non-2xx as an unreachable transport error and never read the body, so a CDP verdict was misclassified. This release reads the result from the body regardless of HTTP status, which was the last blocker for Base mainnet settlement through CDP.
 
 Highlights:
 
-- the facilitator client mints a fresh EdDSA (Ed25519) CDP Bearer JWT per `/verify` and `/settle` request, with the `uri` claim bound to each request and a 120-second expiry, because CDP rejects static tokens
-- enable it by setting `CDP_API_KEY_ID` and `CDP_API_KEY_SECRET` (or `XYTARA_X402_CDP_KEY_ID` / `XYTARA_X402_CDP_KEY_SECRET`) and pointing `XYTARA_X402_FACILITATOR_URL` at the CDP facilitator; the Ed25519 secret is the base64 64-byte key CDP issues
-- zero new dependencies: the JWT is signed with Node's built-in Ed25519
-- when no CDP key is configured, behavior is unchanged: static-header facilitators and the default Base Sepolia path work exactly as before
-- adds `npm run verify:cdp-facilitator`, which checks the per-request token minting, claim shape, and signature against a mock facilitator, and documents the Base mainnet setup in `REAL_PAYMENT_SETUP.md`
+- the facilitator client treats any `/verify` or `/settle` response that carries an `isValid` or `success` flag as the facilitator's result, regardless of HTTP status; only a missing or unparseable body is a transport failure
+- failure details now surface the facilitator's `invalidReason` / `invalidMessage` / `errorReason` and a truncated response-body excerpt, so operators can see exactly why a facilitator rejected a payment
+- adds regression checks for facilitators that return a non-2xx status with a result body
+- no change for facilitators that return 200 with the result; the default Base Sepolia path is unaffected
+- verified end to end: a real Base mainnet USDC payment settled on-chain through the CDP facilitator and minted self-serve credits

package/examples/generated.carried-handoff.json

@@ -6,9 +6,9 @@
     "source_ref": "spine.job.commitment",
     "committed_ref": "transaction.job.commitment",
     "precommit_pack_ref": "precommit.job.commitment.readiness",
-    "transaction_id": "txn_18742578ec28",
-    "receipt_id": "rcpt_fa3b4219d3c4",
-    "proof_ref": "proof_rcpt_fa3b4219d3c4",
+    "transaction_id": "txn_2b8e48010d89",
+    "receipt_id": "rcpt_5b59fa10c38d",
+    "proof_ref": "proof_rcpt_5b59fa10c38d",
     "payment_protocol": "x402",
     "settlement_mode": "evm_payment",
     "treasury_destination_id": "treasury_acct_demo",

package/lib/x402_facilitator.js

@@ -98,7 +98,7 @@ function createFacilitatorClient(config) {
       } catch (_) {
         json = null;
       }
-      return { ok: response.ok, status: response.status, json };
+      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 {
@@ -127,13 +127,25 @@ async function verifyX402Payment({ paymentHeader, accepts, resourceUrl, facilita
   if (!paymentRequirements) {
     return { ok: false, status: 402, reason: "payment_requirements_mismatch", detail: "accepted requirements do not match any advertised payment option" };
   }
-  const requirementsForFacilitator = { ...paymentRequirements, resource: resourceUrl };
+  // 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);
-  if (!verification.ok || !verification.json) {
-    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: verification.error || `facilitator verify returned HTTP ${verification.status}` };
+  // 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) {
-    return { ok: false, status: 402, reason: "payment_verification_failed", detail: normalizeString(verification.json.invalidReason) || "facilitator rejected the payment" };
+    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,
@@ -152,11 +164,15 @@ async function settleX402Payment({ authorization, facilitator, settle }) {
     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);
-  if (!settlement.ok || !settlement.json) {
-    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: settlement.error || `facilitator settle returned HTTP ${settlement.status}` };
+  // 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) {
-    return { ok: false, status: 402, reason: "payment_settlement_failed", detail: normalizeString(settlement.json.errorReason) || "facilitator could not settle the payment" };
+    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 };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xytara",
-  "version": "3.1.5",
+  "version": "3.1.7",
   "description": "Agent-commerce runtime for quote, pay, execute, deliver, meter, and integrate.",
   "main": "index.js",
   "bin": {

package/scripts/verify_x402_facilitator.js

@@ -1,194 +1,216 @@
-"use strict";
-
-// Verifies the x402_facilitator payment mode end to end against a mock facilitator:
-//   - an unpaid x402 execute returns 402 and advertises the configured accepts
-//   - a well-formed payment is verified and settled, the command runs, and the
-//     response carries a PAYMENT-RESPONSE settlement receipt
-//   - malformed, mismatched, facilitator-rejected, and unsettled payments all 402
-//
-// No real network or chain is used; the mock facilitator stands in for x402.org.
-
-const assert = require("assert");
-const http = require("http");
-
-const ACCEPTS = [
-  {
-    scheme: "exact",
-    network: "eip155:84532",
-    asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
-    amount: "1000",
-    payTo: "0x7cd2E0Ed2721319B20FAac4109774d030833F84D",
-    extra: { name: "USDC", version: "2" },
-    maxTimeoutSeconds: 60
-  }
-];
-
-function startMockFacilitator() {
-  const calls = { verify: 0, settle: 0 };
-  const server = http.createServer((req, res) => {
-    const chunks = [];
-    req.on("data", (c) => chunks.push(c));
-    req.on("end", () => {
-      let body = {};
-      try { body = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}"); } catch (_) { body = {}; }
-      const sig = body && body.paymentPayload && body.paymentPayload.payload ? String(body.paymentPayload.payload.signature || "") : "";
-      const reply = (payload) => {
-        const text = JSON.stringify(payload);
-        res.writeHead(200, { "content-type": "application/json", "content-length": Buffer.byteLength(text) });
-        res.end(text);
-      };
-      if (req.method === "POST" && req.url === "/verify") {
-        calls.verify += 1;
-        if (sig === "reject-me") return reply({ isValid: false, invalidReason: "invalid_signature" });
-        return reply({ isValid: true, payer: "0x1111111111111111111111111111111111111111" });
-      }
-      if (req.method === "POST" && req.url === "/settle") {
-        calls.settle += 1;
-        if (sig === "settle-fails") return reply({ success: false, errorReason: "insufficient_funds" });
-        return reply({ success: true, transaction: "0xmocktx", network: "eip155:84532", payer: "0x1111111111111111111111111111111111111111" });
-      }
-      res.writeHead(404); res.end();
-    });
-  });
-  return new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve({ server, calls, port: server.address().port })));
-}
-
-function paymentHeader(signature, overrides = {}) {
-  const accepted = ACCEPTS[0];
-  return Buffer.from(JSON.stringify({
-    x402Version: 2,
-    accepted: { ...accepted, ...overrides.accepted },
-    payload: {
-      signature,
-      authorization: {
-        from: "0x1111111111111111111111111111111111111111",
-        to: accepted.payTo,
-        value: accepted.amount,
-        validAfter: "0",
-        validBefore: String(Math.floor(Date.now() / 1000) + 600),
-        nonce: `0x${"ab".repeat(32)}`
-      }
-    }
-  }), "utf8").toString("base64");
-}
-
-async function post(baseUrl, path, body, headers = {}) {
-  const res = await fetch(`${baseUrl}${path}`, {
-    method: "POST",
-    headers: { "content-type": "application/json", ...headers },
-    body: JSON.stringify(body)
-  });
-  let json = null;
-  try { json = await res.json(); } catch (_) { json = null; }
-  return { status: res.status, json, headers: res.headers };
-}
-
-async function main() {
-  const facilitator = await startMockFacilitator();
-  const previous = {
-    mode: process.env.XYTARA_PAYMENT_VERIFICATION_MODE,
-    accepts: process.env.XYTARA_X402_ACCEPTS_JSON,
-    facUrl: process.env.XYTARA_X402_FACILITATOR_URL
-  };
-  process.env.XYTARA_PAYMENT_VERIFICATION_MODE = "x402_facilitator";
-  process.env.XYTARA_X402_ACCEPTS_JSON = JSON.stringify(ACCEPTS);
-  process.env.XYTARA_X402_FACILITATOR_URL = `http://127.0.0.1:${facilitator.port}`;
-
-  delete require.cache[require.resolve("../server")];
-  const { createServer } = require("../server");
-  const server = createServer();
-  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
-  const baseUrl = `http://127.0.0.1:${server.address().port}`;
-  const execBody = { account_id: "acct_x402", command: "x402 facilitator demo", task_ref: "trust.verify", body: { subject_id: "s-1" } };
-
-  try {
-    // 1. Unpaid -> 402 advertising accepts.
-    const unpaid = await post(baseUrl, "/x402/commands/execute", execBody);
-    assert.strictEqual(unpaid.status, 402, "unpaid x402 execute must return 402");
-    const required = unpaid.json && unpaid.json.payment_required;
-    assert.ok(required, "402 must carry payment_required");
-    assert.strictEqual(required.x402Version, 2, "challenge must be x402 v2");
-    assert.ok(Array.isArray(required.accepts) && required.accepts.length === 1, "challenge must advertise accepts");
-    assert.strictEqual(required.accepts[0].network, "eip155:84532", "advertised network mismatch");
-    assert.strictEqual(typeof unpaid.headers.get("payment-required"), "string", "PAYMENT-REQUIRED header missing");
-
-    // 2. Bogus header -> 402 payment_signature_invalid.
-    const bogus = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": "not-a-payment" });
-    assert.strictEqual(bogus.status, 402, "bogus payment header must 402");
-    assert.strictEqual(bogus.json.reason, "payment_signature_invalid", "bogus reason mismatch");
-
-    // 3. Mismatched requirements -> 402 before the facilitator.
-    const verifyBefore = facilitator.calls.verify;
-    const mismatch = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("ok", { accepted: { amount: "9" } }) });
-    assert.strictEqual(mismatch.status, 402, "mismatched requirements must 402");
-    assert.strictEqual(mismatch.json.reason, "payment_requirements_mismatch", "mismatch reason");
-    assert.strictEqual(facilitator.calls.verify, verifyBefore, "facilitator must not be called on a requirements mismatch");
-
-    // 4. Facilitator rejects -> 402 payment_verification_failed.
-    const rejected = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("reject-me") });
-    assert.strictEqual(rejected.status, 402, "facilitator-rejected payment must 402");
-    assert.strictEqual(rejected.json.reason, "payment_verification_failed", "rejection reason");
-    assert.strictEqual(rejected.json.detail, "invalid_signature", "rejection detail");
-
-    // 5. Settlement fails -> 402, no tool output.
-    const settleFails = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("settle-fails") });
-    assert.strictEqual(settleFails.status, 402, "failed settlement must 402");
-    assert.strictEqual(settleFails.json.reason, "payment_settlement_failed", "settlement failure reason");
-
-    // 6. Verified + settled -> 200 with a result and a PAYMENT-RESPONSE receipt.
-    const settleBefore = facilitator.calls.settle;
-    const paid = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("ok") });
-    assert.strictEqual(paid.status, 200, "verified+settled payment must 200");
-    assert.strictEqual(typeof paid.json.transaction.transaction_id, "string", "paid result missing transaction");
-    assert.strictEqual(paid.json.transaction.status, "completed", "paid transaction must be completed");
-    assert.strictEqual(paid.json.transaction.payment.verification_mode, "x402_facilitator", "verification mode not recorded");
-    assert.strictEqual(facilitator.calls.settle, settleBefore + 1, "facilitator settle must be called once");
-    const receiptHeader = paid.headers.get("payment-response");
-    assert.strictEqual(typeof receiptHeader, "string", "PAYMENT-RESPONSE header missing on a settled 200");
-    const receipt = JSON.parse(Buffer.from(receiptHeader, "base64").toString("utf8"));
-    assert.strictEqual(receipt.success, true, "settlement receipt must report success");
-    assert.strictEqual(receipt.transaction, "0xmocktx", "settlement receipt transaction mismatch");
-
-    // 7. Native routes must not be disabled by x402_facilitator: a native paid attempt
-    //    falls back to local_signed semantics, never payment_verification_mode_unsupported.
-    const nativeAttempt = await post(baseUrl, "/v1/commands/execute", execBody, {
-      "x-wallet-id": "wallet-not-registered",
-      "x-payment": "encoded",
-      "x-payment-signature": "sig"
-    });
-    assert.notStrictEqual(nativeAttempt.json && nativeAttempt.json.reason, "payment_verification_mode_unsupported", "native route must fall back to local_signed under x402_facilitator");
-
-    // 8. Self-serve credits top-up: unpaid -> 402 advertising accepts + credits_per_topup.
-    const topupUnpaid = await post(baseUrl, "/x402/credits/topup", { account_id: "acct_topup" });
-    assert.strictEqual(topupUnpaid.status, 402, "unpaid topup must 402");
-    assert.ok(Array.isArray(topupUnpaid.json.payment_required.accepts), "topup 402 must advertise accepts");
-    assert.strictEqual(typeof topupUnpaid.json.payment_required.credits_per_topup, "number", "topup 402 must state credits_per_topup");
-
-    // 9. Paid top-up -> 200, credits minted to the account, with a settlement receipt.
-    const topupPaid = await post(baseUrl, "/x402/credits/topup", { account_id: "acct_topup" }, { "payment-signature": paymentHeader("ok") });
-    assert.strictEqual(topupPaid.status, 200, "paid topup must 200");
-    assert.strictEqual(topupPaid.json.ok, true, "paid topup must be ok");
-    assert.strictEqual(typeof topupPaid.json.credit_grant, "object", "paid topup must return a credit grant");
-    const grantedUnits = Number(topupPaid.json.balance.available_units);
-    assert.ok(grantedUnits > 0, "paid topup must leave a positive credit balance");
-    assert.strictEqual(typeof topupPaid.headers.get("payment-response"), "string", "paid topup must carry a settlement receipt");
-
-    // 10. Replayed top-up (same payment nonce) is idempotent: no double-mint.
-    const topupReplay = await post(baseUrl, "/x402/credits/topup", { account_id: "acct_topup" }, { "payment-signature": paymentHeader("ok") });
-    assert.strictEqual(topupReplay.status, 200, "replayed topup must still 200");
-    assert.strictEqual(Number(topupReplay.json.balance.available_units), grantedUnits, "replayed topup must not mint credits twice");
-
-    console.log("xytara verify:x402-facilitator passed");
-  } finally {
-    await new Promise((resolve) => server.close(resolve));
-    await new Promise((resolve) => facilitator.server.close(resolve));
-    if (previous.mode === undefined) delete process.env.XYTARA_PAYMENT_VERIFICATION_MODE; else process.env.XYTARA_PAYMENT_VERIFICATION_MODE = previous.mode;
-    if (previous.accepts === undefined) delete process.env.XYTARA_X402_ACCEPTS_JSON; else process.env.XYTARA_X402_ACCEPTS_JSON = previous.accepts;
-    if (previous.facUrl === undefined) delete process.env.XYTARA_X402_FACILITATOR_URL; else process.env.XYTARA_X402_FACILITATOR_URL = previous.facUrl;
-  }
-}
-
-main().catch((error) => {
-  console.error(error && error.message ? error.message : error);
-  process.exitCode = 1;
-});
+"use strict";
+
+// Verifies the x402_facilitator payment mode end to end against a mock facilitator:
+//   - an unpaid x402 execute returns 402 and advertises the configured accepts
+//   - a well-formed payment is verified and settled, the command runs, and the
+//     response carries a PAYMENT-RESPONSE settlement receipt
+//   - malformed, mismatched, facilitator-rejected, and unsettled payments all 402
+//
+// No real network or chain is used; the mock facilitator stands in for x402.org.
+
+const assert = require("assert");
+const http = require("http");
+
+const ACCEPTS = [
+  {
+    scheme: "exact",
+    network: "eip155:84532",
+    asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    amount: "1000",
+    payTo: "0x7cd2E0Ed2721319B20FAac4109774d030833F84D",
+    extra: { name: "USDC", version: "2" },
+    maxTimeoutSeconds: 60
+  }
+];
+
+function startMockFacilitator() {
+  const calls = { verify: 0, settle: 0 };
+  const server = http.createServer((req, res) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => {
+      let body = {};
+      try { body = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}"); } catch (_) { body = {}; }
+      const sig = body && body.paymentPayload && body.paymentPayload.payload ? String(body.paymentPayload.payload.signature || "") : "";
+      const reply = (payload, status) => {
+        const text = JSON.stringify(payload);
+        res.writeHead(status || 200, { "content-type": "application/json", "content-length": Buffer.byteLength(text) });
+        res.end(text);
+      };
+      if (req.method === "POST" && req.url === "/verify") {
+        calls.verify += 1;
+        calls.lastVerifyBody = body;
+        if (sig === "reject-me") return reply({ isValid: false, invalidReason: "invalid_signature" });
+        if (sig === "cdp-invalid") return reply({ isValid: false, invalidReason: "invalid_payload", invalidMessage: "contract call failed: execution reverted", payer: "0x1111111111111111111111111111111111111111" }, 400);
+        return reply({ isValid: true, payer: "0x1111111111111111111111111111111111111111" });
+      }
+      if (req.method === "POST" && req.url === "/settle") {
+        calls.settle += 1;
+        if (sig === "settle-fails") return reply({ success: false, errorReason: "insufficient_funds" });
+        if (sig === "cdp-settle-fail") return reply({ success: false, errorReason: "insufficient_funds" }, 400);
+        return reply({ success: true, transaction: "0xmocktx", network: "eip155:84532", payer: "0x1111111111111111111111111111111111111111" });
+      }
+      res.writeHead(404); res.end();
+    });
+  });
+  return new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve({ server, calls, port: server.address().port })));
+}
+
+function paymentHeader(signature, overrides = {}) {
+  const accepted = ACCEPTS[0];
+  return Buffer.from(JSON.stringify({
+    x402Version: 2,
+    accepted: { ...accepted, ...overrides.accepted },
+    payload: {
+      signature,
+      authorization: {
+        from: "0x1111111111111111111111111111111111111111",
+        to: accepted.payTo,
+        value: accepted.amount,
+        validAfter: "0",
+        validBefore: String(Math.floor(Date.now() / 1000) + 600),
+        nonce: `0x${"ab".repeat(32)}`
+      }
+    }
+  }), "utf8").toString("base64");
+}
+
+async function post(baseUrl, path, body, headers = {}) {
+  const res = await fetch(`${baseUrl}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body: JSON.stringify(body)
+  });
+  let json = null;
+  try { json = await res.json(); } catch (_) { json = null; }
+  return { status: res.status, json, headers: res.headers };
+}
+
+async function main() {
+  const facilitator = await startMockFacilitator();
+  const previous = {
+    mode: process.env.XYTARA_PAYMENT_VERIFICATION_MODE,
+    accepts: process.env.XYTARA_X402_ACCEPTS_JSON,
+    facUrl: process.env.XYTARA_X402_FACILITATOR_URL
+  };
+  process.env.XYTARA_PAYMENT_VERIFICATION_MODE = "x402_facilitator";
+  process.env.XYTARA_X402_ACCEPTS_JSON = JSON.stringify(ACCEPTS);
+  process.env.XYTARA_X402_FACILITATOR_URL = `http://127.0.0.1:${facilitator.port}`;
+
+  delete require.cache[require.resolve("../server")];
+  const { createServer } = require("../server");
+  const server = createServer();
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const baseUrl = `http://127.0.0.1:${server.address().port}`;
+  const execBody = { account_id: "acct_x402", command: "x402 facilitator demo", task_ref: "trust.verify", body: { subject_id: "s-1" } };
+
+  try {
+    // 1. Unpaid -> 402 advertising accepts.
+    const unpaid = await post(baseUrl, "/x402/commands/execute", execBody);
+    assert.strictEqual(unpaid.status, 402, "unpaid x402 execute must return 402");
+    const required = unpaid.json && unpaid.json.payment_required;
+    assert.ok(required, "402 must carry payment_required");
+    assert.strictEqual(required.x402Version, 2, "challenge must be x402 v2");
+    assert.ok(Array.isArray(required.accepts) && required.accepts.length === 1, "challenge must advertise accepts");
+    assert.strictEqual(required.accepts[0].network, "eip155:84532", "advertised network mismatch");
+    assert.strictEqual(typeof unpaid.headers.get("payment-required"), "string", "PAYMENT-REQUIRED header missing");
+
+    // 2. Bogus header -> 402 payment_signature_invalid.
+    const bogus = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": "not-a-payment" });
+    assert.strictEqual(bogus.status, 402, "bogus payment header must 402");
+    assert.strictEqual(bogus.json.reason, "payment_signature_invalid", "bogus reason mismatch");
+
+    // 3. Mismatched requirements -> 402 before the facilitator.
+    const verifyBefore = facilitator.calls.verify;
+    const mismatch = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("ok", { accepted: { amount: "9" } }) });
+    assert.strictEqual(mismatch.status, 402, "mismatched requirements must 402");
+    assert.strictEqual(mismatch.json.reason, "payment_requirements_mismatch", "mismatch reason");
+    assert.strictEqual(facilitator.calls.verify, verifyBefore, "facilitator must not be called on a requirements mismatch");
+
+    // 4. Facilitator rejects -> 402 payment_verification_failed.
+    const rejected = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("reject-me") });
+    assert.strictEqual(rejected.status, 402, "facilitator-rejected payment must 402");
+    assert.strictEqual(rejected.json.reason, "payment_verification_failed", "rejection reason");
+    assert.strictEqual(rejected.json.detail, "invalid_signature", "rejection detail");
+
+    // 5. Settlement fails -> 402, no tool output.
+    const settleFails = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("settle-fails") });
+    assert.strictEqual(settleFails.status, 402, "failed settlement must 402");
+    assert.strictEqual(settleFails.json.reason, "payment_settlement_failed", "settlement failure reason");
+
+    // 6. Verified + settled -> 200 with a result and a PAYMENT-RESPONSE receipt.
+    const settleBefore = facilitator.calls.settle;
+    const paid = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("ok") });
+    assert.strictEqual(paid.status, 200, "verified+settled payment must 200");
+    assert.strictEqual(typeof paid.json.transaction.transaction_id, "string", "paid result missing transaction");
+    assert.strictEqual(paid.json.transaction.status, "completed", "paid transaction must be completed");
+    assert.strictEqual(paid.json.transaction.payment.verification_mode, "x402_facilitator", "verification mode not recorded");
+    assert.strictEqual(facilitator.calls.settle, settleBefore + 1, "facilitator settle must be called once");
+    const receiptHeader = paid.headers.get("payment-response");
+    assert.strictEqual(typeof receiptHeader, "string", "PAYMENT-RESPONSE header missing on a settled 200");
+    const receipt = JSON.parse(Buffer.from(receiptHeader, "base64").toString("utf8"));
+    assert.strictEqual(receipt.success, true, "settlement receipt must report success");
+    assert.strictEqual(receipt.transaction, "0xmocktx", "settlement receipt transaction mismatch");
+
+    // The facilitator must receive a clean v2 PaymentRequirements: no `resource` field (which
+    // strict facilitators like CDP reject), and it must equal the payment payload's `accepted`.
+    const verifyBody = facilitator.calls.lastVerifyBody;
+    assert.ok(verifyBody && verifyBody.paymentRequirements, "facilitator must receive paymentRequirements");
+    assert.strictEqual(verifyBody.paymentRequirements.resource, undefined, "paymentRequirements must not carry a resource field (v2)");
+    assert.deepStrictEqual(verifyBody.paymentRequirements, verifyBody.paymentPayload.accepted, "paymentRequirements must equal paymentPayload.accepted");
+
+    // 7. Native routes must not be disabled by x402_facilitator: a native paid attempt
+    //    falls back to local_signed semantics, never payment_verification_mode_unsupported.
+    const nativeAttempt = await post(baseUrl, "/v1/commands/execute", execBody, {
+      "x-wallet-id": "wallet-not-registered",
+      "x-payment": "encoded",
+      "x-payment-signature": "sig"
+    });
+    assert.notStrictEqual(nativeAttempt.json && nativeAttempt.json.reason, "payment_verification_mode_unsupported", "native route must fall back to local_signed under x402_facilitator");
+
+    // 7b. CDP-style facilitator: a non-2xx verify carrying isValid:false is a verification
+    //     failure, not an unreachable transport error.
+    const cdpInvalid = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("cdp-invalid") });
+    assert.strictEqual(cdpInvalid.status, 402, "cdp-style 400 verify must still 402");
+    assert.strictEqual(cdpInvalid.json.reason, "payment_verification_failed", "cdp-style 400 must map to payment_verification_failed, not facilitator_unreachable");
+    assert.strictEqual(cdpInvalid.json.detail, "invalid_payload", "cdp-style verify detail must surface invalidReason");
+
+    // 7c. CDP-style settle failure: a non-2xx settle carrying success:false is a settlement failure.
+    const cdpSettleFail = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("cdp-settle-fail") });
+    assert.strictEqual(cdpSettleFail.status, 402, "cdp-style 400 settle must still 402");
+    assert.strictEqual(cdpSettleFail.json.reason, "payment_settlement_failed", "cdp-style 400 settle must map to payment_settlement_failed");
+
+    // 8. Self-serve credits top-up: unpaid -> 402 advertising accepts + credits_per_topup.
+    const topupUnpaid = await post(baseUrl, "/x402/credits/topup", { account_id: "acct_topup" });
+    assert.strictEqual(topupUnpaid.status, 402, "unpaid topup must 402");
+    assert.ok(Array.isArray(topupUnpaid.json.payment_required.accepts), "topup 402 must advertise accepts");
+    assert.strictEqual(typeof topupUnpaid.json.payment_required.credits_per_topup, "number", "topup 402 must state credits_per_topup");
+
+    // 9. Paid top-up -> 200, credits minted to the account, with a settlement receipt.
+    const topupPaid = await post(baseUrl, "/x402/credits/topup", { account_id: "acct_topup" }, { "payment-signature": paymentHeader("ok") });
+    assert.strictEqual(topupPaid.status, 200, "paid topup must 200");
+    assert.strictEqual(topupPaid.json.ok, true, "paid topup must be ok");
+    assert.strictEqual(typeof topupPaid.json.credit_grant, "object", "paid topup must return a credit grant");
+    const grantedUnits = Number(topupPaid.json.balance.available_units);
+    assert.ok(grantedUnits > 0, "paid topup must leave a positive credit balance");
+    assert.strictEqual(typeof topupPaid.headers.get("payment-response"), "string", "paid topup must carry a settlement receipt");
+
+    // 10. Replayed top-up (same payment nonce) is idempotent: no double-mint.
+    const topupReplay = await post(baseUrl, "/x402/credits/topup", { account_id: "acct_topup" }, { "payment-signature": paymentHeader("ok") });
+    assert.strictEqual(topupReplay.status, 200, "replayed topup must still 200");
+    assert.strictEqual(Number(topupReplay.json.balance.available_units), grantedUnits, "replayed topup must not mint credits twice");
+
+    console.log("xytara verify:x402-facilitator passed");
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+    await new Promise((resolve) => facilitator.server.close(resolve));
+    if (previous.mode === undefined) delete process.env.XYTARA_PAYMENT_VERIFICATION_MODE; else process.env.XYTARA_PAYMENT_VERIFICATION_MODE = previous.mode;
+    if (previous.accepts === undefined) delete process.env.XYTARA_X402_ACCEPTS_JSON; else process.env.XYTARA_X402_ACCEPTS_JSON = previous.accepts;
+    if (previous.facUrl === undefined) delete process.env.XYTARA_X402_FACILITATOR_URL; else process.env.XYTARA_X402_FACILITATOR_URL = previous.facUrl;
+  }
+}
+
+main().catch((error) => {
+  console.error(error && error.message ? error.message : error);
+  process.exitCode = 1;
+});