xytara 3.1.3 → 3.1.5

package/.env.example

@@ -13,6 +13,10 @@ XYTARA_X402_SETTLE=true
 # credit units a single self-serve /x402/credits/topup grants (default 1000);
 # an accepts entry may override per-payment via its extra.credits
 XYTARA_X402_TOPUP_UNITS=1000
+# Coinbase CDP auth for the CDP-hosted facilitator (Base mainnet); Ed25519 Secret API Key.
+# The runtime mints a fresh CDP Bearer JWT per request when both are set.
+CDP_API_KEY_ID=
+CDP_API_KEY_SECRET=
 XYTARA_PAYMENT_MAX_AGE_SECONDS=300
 XYTARA_WALLET_REGISTRY_JSON=[]
 XYTARA_TREASURY_DESTINATION_ID=

package/REAL_PAYMENT_SETUP.md

@@ -65,6 +65,33 @@ mode with `XYTARA_X402_ACCEPTS_JSON` set, and credits persist only when runtime
 persistence (`XYTARA_SUPABASE_*` or `XYTARA_STATE_FILE`) is configured. A runnable buyer is in
 `services/mcp-execution-target/buyer-demo/x402-credits-topup-demo.js`.
 
+### Going to Base mainnet (real USDC)
+
+Base Sepolia uses test USDC. To accept real value, advertise a Base mainnet profile and
+settle it through a mainnet-capable facilitator.
+
+Important: the default `https://x402.org/facilitator` settles **Base Sepolia only** (its
+`/supported` list has no `eip155:8453`). Pointing a mainnet `accepts` entry at it fails
+closed and the route is unpayable. For mainnet use a mainnet-capable facilitator, such as
+Coinbase CDP (`https://api.cdp.coinbase.com/platform/v2/x402`), which is supported natively:
+create a CDP Secret API Key (Ed25519) and set its id and secret, and the runtime mints a
+fresh short-lived CDP Bearer JWT per facilitator call (CDP rejects static tokens).
+
+```env
+# advertise mainnet (real USDC on Base); you can keep a Sepolia entry in the array too
+XYTARA_X402_ACCEPTS_JSON=[{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"10000","payTo":"<your-evm-address>","extra":{"name":"USDC","version":"2"},"maxTimeoutSeconds":60}]
+# point at the CDP-hosted facilitator and supply the CDP Secret API Key:
+XYTARA_X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
+CDP_API_KEY_ID=<your-cdp-key-id>
+CDP_API_KEY_SECRET=<your-cdp-ed25519-secret-base64>
+```
+
+The CDP key must use the **Ed25519** signature algorithm (not ECDSA). `CDP_API_KEY_ID` /
+`CDP_API_KEY_SECRET` are the CDP-standard names; `XYTARA_X402_CDP_KEY_ID` /
+`XYTARA_X402_CDP_KEY_SECRET` are accepted as overrides. `amount` is in the asset's base units
+(USDC has 6 decimals, so `10000` = 0.01 USDC). Verify the CDP auth path locally with
+`npm run verify:cdp-facilitator`. Once mainnet is live, buyers spend real USDC.
+
 ## Minimum Production-Oriented Configuration
 
 Set these environment variables:

package/RELEASE_NOTES.md

@@ -1,16 +1,11 @@
-`xytara` 3.1.3 makes runtime credits self-serve: a buyer can turn a single x402 payment into spendable credit with no operator grant.
+`xytara` 3.1.5 adds native Coinbase CDP facilitator support, unlocking Base mainnet settlement.
 
-This builds on the `x402_facilitator` on-chain settlement mode. Until now, credits could only be minted by an operator; a paying agent still needed someone to grant it a balance. This release closes that gap so the pay-and-use loop is fully autonomous.
+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.
 
 Highlights:
 
-- adds `POST /x402/credits/topup`: pay once with x402 and the facilitator settles the payment on-chain, then the runtime mints the credits to the account and returns the grant, the new balance, and a `PAYMENT-RESPONSE` settlement receipt
-- without a payment the route returns a `402` advertising the same `accepts` plus `credits_per_topup`, so a buyer discovers the price and the credit it buys before paying
-- credits land on `account_id` from the request body, falling back to the paying wallet address
-- idempotent by the payment nonce: re-sending the same settled payment never mints credits twice
-- each top-up grants `XYTARA_X402_TOPUP_UNITS` credit units (default `1000`), unless the matched `accepts` entry sets its own `extra.credits`
-- live only in `x402_facilitator` mode with `accepts` configured; fails closed if the facilitator is unreachable or the payment does not settle
-- extends `npm run verify:x402-facilitator` with the unpaid-challenge, paid-mint, and replay-idempotency cases for the new route
-- adds a runnable buyer, `services/mcp-execution-target/buyer-demo/x402-credits-topup-demo.js`, and documents the route in `REAL_PAYMENT_SETUP.md`
-
-No existing path changes: the per-call x402 routes, native lanes, and operator credit grants all behave exactly as before.
+- 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`

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_c3db568e78ec",
-    "receipt_id": "rcpt_fc14a1bfa4b5",
-    "proof_ref": "proof_rcpt_fc14a1bfa4b5",
+    "transaction_id": "txn_18742578ec28",
+    "receipt_id": "rcpt_fa3b4219d3c4",
+    "proof_ref": "proof_rcpt_fa3b4219d3c4",
     "payment_protocol": "x402",
     "settlement_mode": "evm_payment",
     "treasury_destination_id": "treasury_acct_demo",

package/lib/cdp_jwt.js

@@ -0,0 +1,57 @@
+"use strict";
+
+// Zero-dependency Coinbase CDP Bearer JWT signer, used to authenticate requests to the
+// CDP-hosted x402 facilitator (https://api.cdp.coinbase.com/platform/v2/x402), which
+// settles Base mainnet. CDP authenticates each request with a short-lived (<=120s) EdDSA
+// (Ed25519) JWT generated from a CDP Secret API Key, so a static Authorization header is
+// not usable; a fresh token is minted per request with a `uri` claim bound to that request.
+//
+// Secret format: base64-encoded Ed25519, 64 bytes (first 32 = seed, last 32 = public key).
+// Reference: https://docs.cdp.coinbase.com/get-started/docs/cdp-api-keys
+
+const crypto = require("crypto");
+
+// DER PKCS#8 prefix for an Ed25519 private key carrying a 32-byte seed.
+const ED25519_PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+
+function base64url(input) {
+  const buf = Buffer.isBuffer(input) ? input : Buffer.from(input);
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function privateKeyFromSecret(keySecret) {
+  const decoded = Buffer.from(String(keySecret || "").trim(), "base64");
+  if (decoded.length !== 64) {
+    throw new Error("cdp_key_secret_invalid: expected a base64 Ed25519 key of 64 bytes");
+  }
+  const seed = decoded.subarray(0, 32);
+  const pkcs8 = Buffer.concat([ED25519_PKCS8_PREFIX, seed]);
+  return crypto.createPrivateKey({ key: pkcs8, format: "der", type: "pkcs8" });
+}
+
+// Build a CDP Bearer JWT for a single request.
+//   keyId      CDP API key id (UUID)
+//   keySecret  base64 Ed25519 secret (64 bytes)
+//   method     HTTP method, e.g. "POST"
+//   host       request host, e.g. "api.cdp.coinbase.com"
+//   path       request path, e.g. "/platform/v2/x402/verify"
+function buildCdpBearerToken({ keyId, keySecret, method, host, path }) {
+  const id = String(keyId || "").trim();
+  if (!id) throw new Error("cdp_key_id_missing");
+  const privateKey = privateKeyFromSecret(keySecret);
+  const now = Math.floor(Date.now() / 1000);
+  const header = { alg: "EdDSA", typ: "JWT", kid: id, nonce: crypto.randomBytes(16).toString("hex") };
+  const claims = {
+    sub: id,
+    iss: "cdp",
+    aud: ["cdp_service"],
+    nbf: now,
+    exp: now + 120,
+    uri: `${String(method || "POST").toUpperCase()} ${host}${path}`
+  };
+  const signingInput = `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(claims))}`;
+  const signature = crypto.sign(null, Buffer.from(signingInput), privateKey);
+  return `${signingInput}.${base64url(signature)}`;
+}
+
+module.exports = { buildCdpBearerToken, base64url };