xytara 3.1.6 → 3.1.7

package/RELEASE_NOTES.md

@@ -1,10 +1,11 @@
-`xytara` 3.1.6 fixes the x402 facilitator request so strict facilitators like Coinbase CDP accept it.
+`xytara` 3.1.7 completes the Coinbase CDP facilitator path, proven with a real Base mainnet settlement.
 
-The facilitator client was adding a `resource` field to the `paymentRequirements` it sends to `/verify` and `/settle`. The x402 v2 `PaymentRequirements` shape has no `resource` field (resource belongs on the payload), so strict facilitators such as the CDP-hosted facilitator rejected the request with HTTP 400, which blocked Base mainnet settlement through CDP. Lenient facilitators ignored the extra field, so the default Base Sepolia path was unaffected.
+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:
 
-- sends a clean x402 v2 `paymentRequirements` (`scheme`, `network`, `asset`, `amount`, `payTo`, `maxTimeoutSeconds`, `extra`) with no extra `resource` field, so it matches `paymentPayload.accepted` and passes strict facilitator validation
-- this unblocks the CDP facilitator path added in the previous release, including Base mainnet
-- adds a regression check that the facilitator receives `paymentRequirements` without a `resource` field and equal to the payment payload's `accepted`
-- no change to payment semantics, settlement, or any route; lenient-facilitator and Base Sepolia behavior is unchanged
+- 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_2061435e6b7b",
-    "receipt_id": "rcpt_4451d9ab898f",
-    "proof_ref": "proof_rcpt_4451d9ab898f",
+    "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 {
@@ -135,11 +135,17 @@ async function verifyX402Payment({ paymentHeader, accepts, resourceUrl, facilita
   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,
@@ -158,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.6",
+  "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

@@ -32,20 +32,22 @@ function startMockFacilitator() {
       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 reply = (payload, status) => {
         const text = JSON.stringify(payload);
-        res.writeHead(200, { "content-type": "application/json", "content-length": Buffer.byteLength(text) });
+        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();
@@ -166,6 +168,18 @@ async function main() {
     });
     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");