xytara 3.1.12 → 3.1.13

package/.env.example

@@ -98,6 +98,11 @@ XYTARA_PROVIDER_FAILOVER_MAX=3
 # routing reputation recency decay, factor in (0,1): fades older observations so recent performance
 # weighs more. 1 (default) = no decay (lifetime counts). e.g. 0.95 once the network has real history.
 XYTARA_PROVIDER_REPUTATION_DECAY=1
+# Signed delivery receipts (one per paid call; public keys at GET /.well-known/delivery-receipt-keys).
+# base64 PKCS#8 DER (or PEM) private keys. Ed25519 is the base signature; ML-DSA-65 adds the
+# post-quantum leg (needs Node >= 24). Unset -> receipts are still issued but honestly marked unsigned.
+XYTARA_DELIVERY_RECEIPT_ED25519_KEY=
+XYTARA_DELIVERY_RECEIPT_MLDSA65_KEY=
 # Provider payout auto-execution via an EXTERNAL signer (the runtime stays key-less). OFF unless the
 # URL is set; otherwise payouts are recorded and the operator sends + confirms them. See services/payout-signer.
 XYTARA_PAYOUT_SIGNER_URL=

package/README.md

@@ -4,7 +4,8 @@ Listed on [Smithery](https://smithery.ai/server/naxytra/xytara-mcp-executor) ·
 
 **x402 pay-per-call agent-commerce runtime** — the payment and execution layer of the naxytra
 machine stack. An agent discovers a capability, pays once with x402 (gasless USDC on Base), and gets
-a real deliverable, with settlement and revenue reconciled on-chain. The proof-side half is
+a real deliverable, settled on-chain, with the revenue split reconciled in the ledger and paid out
+on-chain, plus a signed delivery receipt. The proof-side half is
 [xoonya](https://naxytra.com/xoonya).
 
 ## Proven live on Base mainnet
@@ -13,8 +14,8 @@ All demonstrated end to end on Base mainnet (provider-payout transactions are pu
 see **Proof** below):
 
 - **Open settling provider network** — a paid x402 call routes to an independently-registered
-  execution provider, returns a real deliverable, and splits revenue on-chain (reconciled ledger,
-  platform keeps the remainder).
+  execution provider, returns a real deliverable, and splits revenue — reconciled in the ledger and
+  paid out on-chain (platform keeps the remainder).
 - **Automated on-chain provider payouts** — a key-less runtime dispatches to an external signer that
   sends USDC on Base; reconciled, idempotent, double-pay-safe.
 - **Cryptographic bounded delegated spend** — a stolen bearer token cannot spend; each spend requires
@@ -30,10 +31,32 @@ endpoint:   https://xytara-mcp-executor.onrender.com/mcp
 tools/list  -> free (17 deterministic tools)
 tools/call  -> 402 Payment Required with a price
             -> sign ONE gasless USDC authorization (x402 / EIP-3009)
-            -> the Coinbase CDP facilitator verifies + settles it on Base
-            -> the tool runs; the response carries the result + an on-chain settlement receipt
+            -> the Coinbase CDP facilitator verifies it; the tool runs
+            -> only if the tool succeeds is the payment settled on Base (a failed call is not charged)
+            -> the response carries the result, the on-chain settlement receipt, and a signed
+               delivery receipt in result._meta["naxytra.com/delivery-receipt"]
 ```
 
+## Signed delivery receipts
+
+Every paid call returns a `naxytra-delivery-receipt/1`: the payment leg (for x402, the network,
+asset, amount, payer, pay_to, and settlement transaction), the provider that delivered, and the
+SHA-256 of the canonical request and of the delivered output — signed over its JCS (RFC 8785)
+canonical form with Ed25519, plus ML-DSA-65 (FIPS-204) where the issuer has a post-quantum key. The
+signed suite is part of the signed bytes, so stripping a signature fails verification.
+
+```
+GET  /.well-known/delivery-receipt-keys   # the issuer's public keys (pin them)
+GET  /v1/delivery-receipts/:receipt_id    # fetch a receipt the runtime issued
+POST /v1/delivery-receipts/verify         # free signature check
+```
+
+Verify independently: recompute `sha256(JCS(output you received))`, check the settlement
+transaction on-chain, and verify each signature over the canonical bytes with `node:crypto` or
+xoonya's `verifyExternalProofSignature` (the receipt's `kid` is the key ref xoonya reports).
+A receipt proves who delivered what for which paid call, unaltered since signing — **not** whether
+the output was correct or good.
+
 Tools: `summarize`, `text.extract`, `html.to-text`, `text.chunk`, `json.validate`, `zones.lookup`,
 `keccak256`, `address.validate`, `abi.encode`, `abi.decode`, `merkle.verify`, `eip712.hash`,
 `x402.decode`, `x402.verify-receipt`, `tx.status`, `reply.draft`, `catalog`.

package/RELEASE_NOTES.md

@@ -1,5 +1,5 @@
-`xytara` 3.1.12 makes the public adapter-depth surface report open-network providers truthfully.
+`xytara` 3.1.13 adds signed delivery receipts and makes the direct MCP path charge only on success.
 
-- `/v1/adapter-depth` and `/v1/adapter-depth/summary` now count ACTIVE open-network providers that declared an adapter task as provider-live paths, alongside operator env targets. Each is labelled `routing: open_provider_registry`, and the pack lists its `depth_sources`. A pending provider never counts, and a provider is shown as shadowed (not counted) when an operator env target pins the whole lane, because env targets are routed first.
-- Previously the surface only looked at env targets, so it reported `provider_wiring_required` even while paid MCP calls were being served by the live registry provider. It now reports `initial_provider_live_path` for the task that provider serves.
-- Internal callers without runtime state keep the env-only view, so no other surface changes.
+- **Signed delivery receipts** (`naxytra-delivery-receipt/1`) on every paid call, from the runtime and from the MCP executor. A receipt binds the payment leg (for x402: network, asset, amount, payer, pay_to, settlement transaction), the provider that delivered, and the SHA-256 of the canonical request and of the delivered output. It is signed over its JCS (RFC 8785) canonical form with Ed25519, plus ML-DSA-65 (FIPS-204) where the issuer has a post-quantum key; the signed suite is inside the signed bytes, so stripping a signature fails verification. Public keys: `GET /.well-known/delivery-receipt-keys`; runtime receipts are retrievable at `GET /v1/delivery-receipts/:id`; free check at `POST /v1/delivery-receipts/verify`. Key ids use the xoonya key-ref format, so xoonya's verifier checks them too. Without a configured key a receipt is still issued and marked unsigned — never a fake signature. Boundary: a receipt proves who delivered what for which paid call, unaltered — not whether the output was correct.
+- **Real x402 settlement records** — for an x402-paid call the runtime's settlement, treasury, and default-path records now carry the x402 rail, network, amount, payer, pay_to, and settlement transaction, instead of the quote's unsubmitted default rail.
+- **MCP executor charges only on success** — `tools/call` now verifies the payment, runs the tool, and settles only if the call succeeded. A tool error, unknown tool, or bad params is never charged; if settlement fails after the work, the output is withheld and the buyer is not charged. A concurrent replay of the same signed authorization is refused (`409 payment_authorization_in_use`).

package/lib/command_flow.js

@@ -11,6 +11,95 @@ const { validateIntegrationSelection } = require("../integrations/dispatch");
 const { markPaymentAccepted, settleDeferredPayment, verifyPaymentAcceptance } = require("./payment_verification");
 const { executeExternalTarget, resolveExecutionTarget } = require("./external_execution_runtime");
 const { externalExecutionBudgetMs } = require("./external_execution_policy");
+const { hashCanonical, issueDeliveryReceipt, loadDeliveryReceiptSigners } = require("./delivery_receipt");
+
+const DELIVERY_RECEIPT_ISSUER = "xytara-runtime";
+const DELIVERY_RECEIPT_RETENTION = 5000;
+
+// The payment leg of a delivery receipt: on-chain facts for x402, the spend record for credits,
+// and the verification mode for any other lane. Never the buyer's signature or secrets.
+function deliveryReceiptPayment(verification, quote) {
+  const v = verification && typeof verification === "object" ? verification : {};
+  const paymentPayload = v.payment_payload && typeof v.payment_payload === "object" ? v.payment_payload : {};
+  if (v.verification_mode === "x402_facilitator") {
+    const settlement = v.settlement && typeof v.settlement === "object" ? v.settlement : null;
+    return {
+      protocol: "x402",
+      scheme: "exact",
+      network: paymentPayload.x402_network || (settlement && settlement.network) || null,
+      asset: paymentPayload.x402_asset || null,
+      amount: paymentPayload.x402_amount !== undefined && paymentPayload.x402_amount !== null ? String(paymentPayload.x402_amount) : null,
+      payer: paymentPayload.x402_payer || (settlement && settlement.payer) || null,
+      pay_to: paymentPayload.x402_pay_to || null,
+      settlement_tx: settlement ? (settlement.transaction || settlement.txid || null) : null,
+      settled: Boolean(settlement && settlement.success !== false && (settlement.transaction || settlement.txid))
+    };
+  }
+  if (v.verification_mode === "account_credits" || paymentPayload.credit_spend_id) {
+    return {
+      protocol: "account_credits",
+      credit_spend_id: paymentPayload.credit_spend_id || null,
+      quoted_amount_minor: quote && Number.isFinite(Number(quote.amount_minor)) ? Number(quote.amount_minor) : null,
+      currency: (quote && quote.currency) || null
+    };
+  }
+  return {
+    protocol: v.verification_mode || "unspecified",
+    quoted_amount_minor: quote && Number.isFinite(Number(quote.amount_minor)) ? Number(quote.amount_minor) : null,
+    currency: (quote && quote.currency) || null
+  };
+}
+
+// Issues the signed delivery receipt for a completed paid call, attaches it to the response, and
+// keeps it retrievable by id (bounded). Fail-safe: a receipt problem never breaks a completed call.
+function attachDeliveryReceipt(state, result, payload, quote, verification, externalExecutionOptions) {
+  try {
+    if (!result || !result.receipt) return;
+    const execution = externalExecutionOptions && externalExecutionOptions.externalExecution
+      ? externalExecutionOptions.externalExecution
+      : null;
+    const deliverables = result.command && Array.isArray(result.command.deliverables) ? result.command.deliverables : [];
+    const outputs = deliverables.map((deliverable) => (deliverable && deliverable.output_payload !== undefined ? deliverable.output_payload : null));
+    const body = payload && payload.body && typeof payload.body === "object" && !Array.isArray(payload.body) ? payload.body : {};
+    const taskRef = (payload && payload.task_ref)
+      || (Array.isArray(payload && payload.tasks) && payload.tasks[0] && payload.tasks[0].task_ref)
+      || null;
+    const { signers } = loadDeliveryReceiptSigners("XYTARA_DELIVERY_RECEIPT");
+    const deliveryReceipt = issueDeliveryReceipt({
+      receipt_id: `drcpt_${result.receipt.receipt_id.replace(/^rcpt_/, "")}`,
+      issuer: DELIVERY_RECEIPT_ISSUER,
+      call: {
+        quote_id: quote && quote.quote_id ? quote.quote_id : null,
+        transaction_id: result.transaction ? result.transaction.transaction_id : null,
+        runtime_receipt_id: result.receipt.receipt_id,
+        task_ref: taskRef,
+        tool_name: typeof body.tool_name === "string" ? body.tool_name : null
+      },
+      payment: deliveryReceiptPayment(verification, quote),
+      delivery: {
+        status: "completed",
+        provider_id: execution && execution.registered_provider_id ? execution.registered_provider_id : null,
+        routing: execution
+          ? (execution.registered_provider_id ? "open_provider_registry" : "operator_env_target")
+          : "runtime_native",
+        execution_target_id: execution && execution.target_id ? execution.target_id : null,
+        request_sha256: hashCanonical(body),
+        request_hash_input: "the request `body` object (e.g. { tool_name, arguments })",
+        output_sha256: hashCanonical(outputs.length === 1 ? outputs[0] : outputs),
+        output_hash_input: outputs.length === 1
+          ? "command.deliverables[0].output_payload (null when the task returns no payload)"
+          : "the array of command.deliverables[*].output_payload",
+        completed_at: (result.receipt.timing && result.receipt.timing.completed_at_iso) || result.receipt.created_at_iso || null
+      }
+    }, signers);
+    result.delivery_receipt = deliveryReceipt;
+    if (!(state.deliveryReceipts instanceof Map)) state.deliveryReceipts = new Map();
+    state.deliveryReceipts.set(deliveryReceipt.receipt_id, deliveryReceipt);
+    while (state.deliveryReceipts.size > DELIVERY_RECEIPT_RETENTION) {
+      state.deliveryReceipts.delete(state.deliveryReceipts.keys().next().value);
+    }
+  } catch (_) { /* non-fatal: never break a completed, possibly settled call */ }
+}
 const { resolveRegisteredTargets, hasActiveMatchingProvider, recordProviderHealth, recordProviderRouting, recordProviderSettlement } = require("./provider_registry");
 const { claimDeferredExecution, releaseDeferredExecution } = require("./execution_dedupe");
 
@@ -364,17 +453,19 @@ async function executeCommandRequest(state, payload, headers, options) {
         attributeProviderSettlement(state, externalExecutionOptions, payload, quote, {
           transaction_id: creditSpend.credit_spend.credit_spend_id
         }, paymentVerification);
+        const creditResult = createCommandResult(state, {
+          ...payload,
+          payment_preference: "credits_first"
+        }, quote, {
+          paymentVerification,
+          creditSpend: creditSpend.credit_spend,
+          skipPaymentLedger: true,
+          externalExecution: externalExecutionOptions.externalExecution || null
+        });
+        attachDeliveryReceipt(state, creditResult, payload, quote, paymentVerification, externalExecutionOptions);
         return {
           status: 200,
-          payload: createCommandResult(state, {
-            ...payload,
-            payment_preference: "credits_first"
-          }, quote, {
-            paymentVerification,
-            creditSpend: creditSpend.credit_spend,
-            skipPaymentLedger: true,
-            externalExecution: externalExecutionOptions.externalExecution || null
-          })
+          payload: creditResult
         };
       }
       if (creditSpend.reason !== "insufficient_credits") {
@@ -551,12 +642,14 @@ async function executeCommandRequest(state, payload, headers, options) {
     attributeProviderSettlement(state, externalExecutionOptions, payload, quote, {
       settlement_ref: (settledVerification.settlement && (settledVerification.settlement.transaction || settledVerification.settlement.txid)) || null
     }, settledVerification);
+    const paidResult = createCommandResult(state, payload, quote, {
+      paymentVerification: settledVerification,
+      externalExecution: externalExecutionOptions.externalExecution || null
+    });
+    attachDeliveryReceipt(state, paidResult, payload, quote, settledVerification, externalExecutionOptions);
     return {
       status: 200,
-      payload: createCommandResult(state, payload, quote, {
-        paymentVerification: settledVerification,
-        externalExecution: externalExecutionOptions.externalExecution || null
-      }),
+      payload: paidResult,
       ...(settledVerification.payment_response_base64
         ? { paymentResponse: settledVerification.payment_response_base64 }
         : {})
@@ -609,12 +702,14 @@ async function executeAuthorizedCommandRequest(state, payload, authorizationCont
   }
 
   attributeProviderSettlement(state, externalExecutionOptions, payload, quote, undefined, paymentVerification);
+  const authorizedResult = createCommandResult(state, payload, quote, {
+    paymentVerification,
+    externalExecution: externalExecutionOptions.externalExecution || null
+  });
+  attachDeliveryReceipt(state, authorizedResult, payload, quote, paymentVerification, externalExecutionOptions);
   return {
     status: 200,
-    payload: createCommandResult(state, payload, quote, {
-      paymentVerification,
-      externalExecution: externalExecutionOptions.externalExecution || null
-    })
+    payload: authorizedResult
   };
 }
 

package/lib/commerce_artifacts.js

@@ -26,6 +26,26 @@ function assessLatency(declaredLatencyClass, observedLatencyClass) {
   return observed <= declared ? "within_posture" : "outside_posture";
 }
 
+// The x402 facts of a payment verified (and, once settled, settled) through the facilitator, or
+// null for any other lane. For an x402-paid call these replace the quote's default settlement
+// rail in the artifacts, so a consumer never reads an unsubmitted placeholder rail as the real one.
+function x402PaymentFacts(paymentVerification) {
+  const verification = paymentVerification && typeof paymentVerification === "object" ? paymentVerification : null;
+  if (!verification || verification.verification_mode !== "x402_facilitator") return null;
+  const paymentPayload = verification.payment_payload && typeof verification.payment_payload === "object" ? verification.payment_payload : {};
+  const settlement = verification.settlement && typeof verification.settlement === "object" ? verification.settlement : null;
+  const txid = settlement && (settlement.transaction || settlement.txid) ? String(settlement.transaction || settlement.txid) : null;
+  return {
+    network: paymentPayload.x402_network || (settlement && settlement.network) || null,
+    asset: paymentPayload.x402_asset || null,
+    amount: paymentPayload.x402_amount !== undefined && paymentPayload.x402_amount !== null ? String(paymentPayload.x402_amount) : null,
+    payer: paymentPayload.x402_payer || (settlement && settlement.payer) || verification.wallet_id || null,
+    pay_to: paymentPayload.x402_pay_to || null,
+    txid,
+    settled: Boolean(settlement && settlement.success !== false && txid)
+  };
+}
+
 function createCommandArtifacts(payload, quote, options) {
   const opts = options || {};
   const transactionId = `txn_${crypto.randomBytes(6).toString("hex")}`;
@@ -241,28 +261,61 @@ function createCommandArtifacts(payload, quote, options) {
       ? opts.paymentVerification.payment_payload
       : null
   );
-  const settlement = {
-    settlement_id: `settlement_${transactionId}`,
-    mode: quote.settlement_mode || null,
-    preference: quote.settlement_preference || null,
-    adapter: quote.settlement_adapter || null,
-    integration_id: quote.settlement_integration_id || null,
-    binding_hash: quote.settlement_binding_hash || null,
-    rail: isBsvTeranodeSettlementMode(quote.settlement_mode) ? "bsv_teranode" : null,
-    network: bsvHints ? bsvHints.network : null,
-    hints: bsvHints,
-    txid: bsvPaymentReference && bsvPaymentReference.txid ? bsvPaymentReference.txid : null,
-    raw_tx: bsvPaymentReference && (bsvPaymentReference.raw_tx || bsvPaymentReference.rawTx)
-      ? (bsvPaymentReference.raw_tx || bsvPaymentReference.rawTx)
-      : null,
-    status: deferredCompletion ? "pending_completion" : "recorded",
-    recorded_at_iso: deferredCompletion ? null : completedAt.toISOString()
-  };
-  const treasuryDestination = buildTreasuryDestination(quote.account_id, quote.settlement_mode);
+  const x402 = x402PaymentFacts(opts.paymentVerification);
+  const settlement = x402
+    ? {
+        settlement_id: `settlement_${transactionId}`,
+        mode: "x402_facilitator",
+        preference: quote.settlement_preference || null,
+        adapter: "x402_facilitator",
+        integration_id: "builtin.payment.x402",
+        binding_hash: quote.settlement_binding_hash || null,
+        rail: "x402",
+        network: x402.network,
+        asset: x402.asset,
+        amount: x402.amount,
+        payer: x402.payer,
+        pay_to: x402.pay_to,
+        hints: null,
+        txid: x402.txid,
+        raw_tx: null,
+        status: x402.settled ? "settled" : deferredCompletion ? "pending_completion" : "verified_not_settled",
+        recorded_at_iso: deferredCompletion ? null : completedAt.toISOString()
+      }
+    : {
+        settlement_id: `settlement_${transactionId}`,
+        mode: quote.settlement_mode || null,
+        preference: quote.settlement_preference || null,
+        adapter: quote.settlement_adapter || null,
+        integration_id: quote.settlement_integration_id || null,
+        binding_hash: quote.settlement_binding_hash || null,
+        rail: isBsvTeranodeSettlementMode(quote.settlement_mode) ? "bsv_teranode" : null,
+        network: bsvHints ? bsvHints.network : null,
+        hints: bsvHints,
+        txid: bsvPaymentReference && bsvPaymentReference.txid ? bsvPaymentReference.txid : null,
+        raw_tx: bsvPaymentReference && (bsvPaymentReference.raw_tx || bsvPaymentReference.rawTx)
+          ? (bsvPaymentReference.raw_tx || bsvPaymentReference.rawTx)
+          : null,
+        status: deferredCompletion ? "pending_completion" : "recorded",
+        recorded_at_iso: deferredCompletion ? null : completedAt.toISOString()
+      };
+  const treasuryDestination = x402
+    ? {
+        destination_id: `x402_${x402.network || "network"}_${x402.pay_to || "pay_to"}`,
+        destination_kind: "x402_pay_to_address",
+        account_id: quote.account_id,
+        settlement_mode: "x402_facilitator",
+        external_ref: x402.pay_to,
+        network: x402.network,
+        rail: "x402"
+      }
+    : buildTreasuryDestination(quote.account_id, quote.settlement_mode);
   const treasury = {
     ...treasuryDestination,
     treasury_receipt_id: `treasury_${receiptId}`,
-    status: deferredCompletion ? "pending_settlement" : "recorded",
+    status: x402
+      ? (x402.settled ? "settled" : deferredCompletion ? "pending_settlement" : "recorded")
+      : deferredCompletion ? "pending_settlement" : "recorded",
     amount_minor: quote.amount_minor,
     currency: quote.currency,
     payment_id: payment.payment_id,
@@ -271,7 +324,7 @@ function createCommandArtifacts(payload, quote, options) {
     rail: treasuryDestination.rail || settlement.rail || null,
     recorded_at_iso: deferredCompletion ? null : completedAt.toISOString()
   };
-  const defaultPath = quote.default_path || buildDefaultEconomicPath(
+  const quotedDefaultPath = quote.default_path || buildDefaultEconomicPath(
     Array.isArray(quote.integration_ids)
       ? quote.integration_ids.find((integrationId) => typeof integrationId === "string" && integrationId.startsWith("builtin.payment."))
       : null,
@@ -283,6 +336,14 @@ function createCommandArtifacts(payload, quote, options) {
       status: deferredCompletion ? "pending_completion" : "recorded"
     }
   );
+  const defaultPath = x402
+    ? {
+        ...quotedDefaultPath,
+        payment_protocol: "x402",
+        settlement_mode: "x402_facilitator",
+        treasury_destination_id: treasuryDestination.destination_id
+      }
+    : quotedDefaultPath;
   const transaction = {
     transaction_id: transactionId,
     account_id: quote.account_id,

package/lib/delivery_receipt.js

@@ -0,0 +1,225 @@
+"use strict";
+
+// Signed delivery receipts ("naxytra-delivery-receipt/1"). One per paid call, binding WHAT was
+// paid (the x402 settlement or other payment fact), WHO delivered (provider), and WHAT was
+// delivered (sha256 of the canonical request and of the canonical output) — signed so anyone can
+// re-verify it offline against the issuer's published keys.
+//
+// Boundary: a valid receipt proves this issuer attests that this provider returned this exact
+// output for this paid call, unaltered since signing. It does NOT judge whether the output was
+// correct or good — that is the consumer's (e.g. an arbitrator's) decision.
+//
+// Signed bytes  = JCS (RFC 8785) canonical JSON of the receipt WITHOUT its `sig` member.
+// Signatures    = one per algorithm in `signing.suite` (Ed25519 always; ML-DSA-65 when configured
+//                 and the runtime supports it). The suite and key ids are INSIDE the signed bytes,
+//                 so stripping a signature (downgrade) fails verification.
+// Key ids       = "<key type>-spki-sha256:<hex>", the same key-ref format the xoonya verifier
+//                 reports, so a receipt verifies with xoonya's verifyExternalProofSignature too.
+//
+// Dependency-free (node:crypto). This file is shared verbatim by the xytara runtime
+// (lib/delivery_receipt.js) and the MCP executor (services/mcp-execution-target/delivery_receipt.js);
+// a verifier asserts the two copies stay byte-identical.
+
+const crypto = require("crypto");
+
+const RECEIPT_VERSION = "naxytra-delivery-receipt/1";
+const CANONICALIZATION = "JCS (RFC 8785) of the receipt without `sig`";
+const SUPPORTED_ALGS = { ed25519: "EdDSA", "ml-dsa-65": "ML-DSA-65" };
+
+// JCS for the JSON values a receipt carries (strings, finite numbers, booleans, null, arrays,
+// objects). Object keys sorted by UTF-16 code units; `undefined` members dropped like JSON.
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") {
+    if (typeof value === "number" && !Number.isFinite(value)) return "null";
+    return value === undefined ? "null" : JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return "[" + value.map((item) => canonicalize(item === undefined ? null : item)).join(",") + "]";
+  return "{" + Object.keys(value)
+    .filter((key) => value[key] !== undefined)
+    .sort()
+    .map((key) => JSON.stringify(key) + ":" + canonicalize(value[key]))
+    .join(",") + "}";
+}
+
+function sha256Hex(input) {
+  return crypto.createHash("sha256").update(Buffer.isBuffer(input) ? input : Buffer.from(String(input), "utf8")).digest("hex");
+}
+
+// The hash a consumer recomputes from the JSON value they hold (request body or delivered output).
+function hashCanonical(value) {
+  return sha256Hex(canonicalize(value === undefined ? null : value));
+}
+
+function keyRef(publicKey) {
+  const spki = publicKey.export({ type: "spki", format: "der" });
+  return `${publicKey.asymmetricKeyType}-spki-sha256:${sha256Hex(spki)}`;
+}
+
+function parsePrivateKey(raw) {
+  const text = String(raw || "").trim();
+  if (!text) return null;
+  if (text.includes("BEGIN ")) return crypto.createPrivateKey({ key: text, format: "pem" });
+  return crypto.createPrivateKey({ key: Buffer.from(text, "base64"), format: "der", type: "pkcs8" });
+}
+
+// Loads the issuer's signing keys from environment variables `${prefix}_ED25519_KEY` and
+// `${prefix}_MLDSA65_KEY` (base64 PKCS#8 DER, or PEM). Never throws: a missing or unusable key is
+// reported in `problems` and simply not used, so receipts degrade to fewer signatures (or to
+// unsigned) and say so — they never claim a signature that was not made.
+const signerCache = new Map();
+function loadDeliveryReceiptSigners(prefix, env = process.env) {
+  const sources = [
+    { variable: `${prefix}_ED25519_KEY`, expected: "ed25519" },
+    { variable: `${prefix}_MLDSA65_KEY`, expected: "ml-dsa-65" }
+  ];
+  const cacheKey = sources.map((source) => `${source.variable}=${env[source.variable] || ""}`).join("\n");
+  if (signerCache.has(cacheKey)) return signerCache.get(cacheKey);
+  const signers = [];
+  const problems = [];
+  for (const source of sources) {
+    const raw = env[source.variable];
+    if (!raw || !String(raw).trim()) continue;
+    try {
+      const privateKey = parsePrivateKey(raw);
+      if (privateKey.asymmetricKeyType !== source.expected) {
+        problems.push({ variable: source.variable, reason: "key_type_mismatch", detail: `expected ${source.expected}, got ${privateKey.asymmetricKeyType}` });
+        continue;
+      }
+      const publicKey = crypto.createPublicKey(privateKey);
+      signers.push({ alg: SUPPORTED_ALGS[source.expected], kid: keyRef(publicKey), privateKey, publicKey });
+    } catch (error) {
+      problems.push({
+        variable: source.variable,
+        reason: source.expected === "ml-dsa-65" ? "ml_dsa_key_unusable_or_unsupported_on_this_runtime" : "key_unparseable",
+        detail: error && error.message ? error.message.slice(0, 160) : "unparseable"
+      });
+    }
+  }
+  // Deterministic suite order: EdDSA first, then ML-DSA-65.
+  signers.sort((a, b) => (a.alg === "EdDSA" ? -1 : 1) - (b.alg === "EdDSA" ? -1 : 1));
+  const loaded = { signers, problems };
+  signerCache.set(cacheKey, loaded);
+  return loaded;
+}
+
+let mlDsaSupport = null;
+function runtimeSupportsMlDsa() {
+  if (mlDsaSupport === null) {
+    try {
+      mlDsaSupport = Boolean(crypto.generateKeyPairSync("ml-dsa-44").publicKey);
+    } catch (_) {
+      mlDsaSupport = false;
+    }
+  }
+  return mlDsaSupport;
+}
+
+// Builds and signs a receipt. `fields` = { receipt_id, issuer, call, payment, delivery }.
+function issueDeliveryReceipt(fields, signers, now = new Date()) {
+  const f = fields && typeof fields === "object" ? fields : {};
+  const activeSigners = Array.isArray(signers) ? signers : [];
+  const body = {
+    v: RECEIPT_VERSION,
+    receipt_id: f.receipt_id || `drcpt_${crypto.randomBytes(8).toString("hex")}`,
+    issuer: f.issuer || null,
+    issued_at: now.toISOString(),
+    call: f.call || null,
+    payment: f.payment || null,
+    delivery: f.delivery || null,
+    hashing: { algorithm: "sha256", canonicalization: "JCS (RFC 8785)" },
+    signing: {
+      canonicalization: CANONICALIZATION,
+      suite: activeSigners.map((signer) => signer.alg),
+      kids: activeSigners.map((signer) => signer.kid),
+      policy: "every_listed_signature_must_verify"
+    }
+  };
+  if (activeSigners.length === 0) {
+    return { ...body, sig: { state: "unsigned_signing_key_not_configured", signatures: [] } };
+  }
+  const signedBytes = Buffer.from(canonicalize(body), "utf8");
+  return {
+    ...body,
+    sig: {
+      state: "signed",
+      signatures: activeSigners.map((signer) => ({
+        alg: signer.alg,
+        kid: signer.kid,
+        value: crypto.sign(null, signedBytes, signer.privateKey).toString("base64")
+      }))
+    }
+  };
+}
+
+// The issuer's public key set (safe to publish).
+function publicKeySet(signers) {
+  return (Array.isArray(signers) ? signers : []).map((signer) => ({
+    kid: signer.kid,
+    alg: signer.alg,
+    public_key_spki_der_base64: signer.publicKey.export({ type: "spki", format: "der" }).toString("base64"),
+    ...(signer.alg === "EdDSA" ? { jwk: signer.publicKey.export({ format: "jwk" }) } : {})
+  }));
+}
+
+// Verifies a receipt against a set of trusted public keys ([{ kid, alg, public_key_spki_der_base64 }]).
+// Valid only if the receipt is signed, every algorithm in the SIGNED suite has a signature from the
+// SIGNED kid, every such kid is in the trusted set, and every signature verifies.
+function verifyDeliveryReceipt(receipt, trustedKeys) {
+  const r = receipt && typeof receipt === "object" && !Array.isArray(receipt) ? receipt : null;
+  if (!r) return { valid: false, reason: "receipt_required" };
+  if (r.v !== RECEIPT_VERSION) return { valid: false, reason: "unsupported_receipt_version", version: r.v || null };
+  const signing = r.signing && typeof r.signing === "object" ? r.signing : null;
+  const sig = r.sig && typeof r.sig === "object" ? r.sig : null;
+  if (!signing || !Array.isArray(signing.suite) || !Array.isArray(signing.kids) || signing.suite.length === 0) {
+    return { valid: false, reason: "receipt_unsigned" };
+  }
+  if (!sig || sig.state !== "signed" || !Array.isArray(sig.signatures)) return { valid: false, reason: "receipt_unsigned" };
+  const { sig: _omit, ...unsigned } = r;
+  const signedBytes = Buffer.from(canonicalize(unsigned), "utf8");
+  const trusted = new Map((Array.isArray(trustedKeys) ? trustedKeys : []).map((key) => [key.kid, key]));
+  const results = signing.suite.map((alg, index) => {
+    const kid = signing.kids[index];
+    const entry = sig.signatures.find((item) => item && item.alg === alg && item.kid === kid);
+    if (!entry) return { alg, kid, valid: false, reason: "signature_missing_for_signed_suite" };
+    const key = trusted.get(kid);
+    if (!key || key.alg !== alg) return { alg, kid, valid: false, reason: "kid_not_in_trusted_key_set" };
+    try {
+      const publicKey = crypto.createPublicKey({ key: Buffer.from(key.public_key_spki_der_base64, "base64"), format: "der", type: "spki" });
+      if (keyRef(publicKey) !== kid) return { alg, kid, valid: false, reason: "kid_does_not_match_key" };
+      const ok = crypto.verify(null, signedBytes, publicKey, Buffer.from(String(entry.value || ""), "base64"));
+      return { alg, kid, valid: ok, reason: ok ? null : "signature_invalid" };
+    } catch (error) {
+      return { alg, kid, valid: false, reason: "verification_error", detail: error && error.message ? error.message.slice(0, 120) : null };
+    }
+  });
+  const valid = results.length > 0 && results.every((item) => item.valid);
+  return { valid, reason: valid ? null : "signature_check_failed", signatures: results, signed_bytes_sha256: sha256Hex(signedBytes) };
+}
+
+// A short, self-contained recipe for verifying a receipt without trusting the issuer's server.
+function verificationRecipe(keysUrl) {
+  return {
+    signed_bytes: "JCS (RFC 8785) canonical JSON of the receipt with its `sig` member removed (UTF-8).",
+    keys: keysUrl || null,
+    steps: [
+      "1. Fetch the issuer's public keys; check each kid in receipt.signing.kids is listed (and pin them).",
+      "2. For every alg in receipt.signing.suite, take the signature with the matching kid from receipt.sig.signatures.",
+      "3. Verify it over the signed bytes with node:crypto (crypto.verify(null, bytes, spkiPublicKey, signature)) or xoonya's verifyExternalProofSignature({ material, signature, algorithm, public_key, expected_key_ref: kid }).",
+      "4. Recompute sha256(JCS(output you received)) and compare with delivery.output_sha256; for x402 calls check payment.settlement_tx on-chain (amount, payer, pay_to)."
+    ],
+    boundary: "Proves who delivered what for which paid call, unaltered since signing — not whether the output was correct or good."
+  };
+}
+
+module.exports = {
+  RECEIPT_VERSION,
+  canonicalize,
+  hashCanonical,
+  keyRef,
+  loadDeliveryReceiptSigners,
+  runtimeSupportsMlDsa,
+  issueDeliveryReceipt,
+  publicKeySet,
+  verifyDeliveryReceipt,
+  verificationRecipe
+};

package/lib/payment_verification.js

@@ -196,7 +196,8 @@ async function verifyPaymentAcceptance(state, headers, requiredHeaders, quote, o
         x402_payer: auth.authorization.payer,
         x402_network: auth.authorization.paymentRequirements.network,
         x402_asset: auth.authorization.paymentRequirements.asset,
-        x402_amount: auth.authorization.paymentRequirements.amount
+        x402_amount: auth.authorization.paymentRequirements.amount,
+        x402_pay_to: auth.authorization.paymentRequirements.payTo || null
       }
     };
     // Deferred settlement: verify now, settle only AFTER execution succeeds, so a

package/lib/provider_network_contract.js

@@ -121,6 +121,7 @@ function buildProviderNetworkContract() {
     economics: {
       settlement: "Buyers pay via x402 (gasless USDC on Base). The runtime settles on-chain only AFTER your execution succeeds — a failed call does not charge the buyer.",
       revenue_share: "Your provider_share = floor(settled_amount * revenue_share_bps / 10000); the platform keeps the remainder (incl. rounding). settled_amount = min(quote, the amount actually settled on-chain for the call) — never money that was not collected; each ledger row records its settlement_basis.",
+      delivery_receipts: "Every paid call routed to you returns the buyer a signed delivery receipt (naxytra-delivery-receipt/1) naming your provider_id and the sha256 of the request and of the output you returned, bound to the payment (for x402, the settlement tx). Keys: GET /.well-known/delivery-receipt-keys. It attests what you delivered — never whether it was correct.",
       payouts: "Your accrued share is paid to your payout_address by the operator (reconciled ledger: create -> on-chain send -> confirm). Amounts are tracked in the quote's minor unit (USD_CENTS). Ledger rows and payouts are scoped to your registration: a removed-and-re-registered provider_id starts a fresh ledger and never inherits another owner's rows."
     },
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xytara",
-  "version": "3.1.12",
+  "version": "3.1.13",
   "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": {

package/scripts/verify_x402_facilitator.js

@@ -139,6 +139,12 @@ async function main() {
     assert.strictEqual(settleFails.json.reason, "payment_settlement_failed", "settlement failure reason");
 
     // 6. Verified + settled -> 200 with a result and a PAYMENT-RESPONSE receipt.
+    // (Delivery-receipt signing keys for this run only: Ed25519 + ML-DSA-65 hybrid.)
+    const crypto = require("crypto");
+    const receiptEd = crypto.generateKeyPairSync("ed25519");
+    const receiptMl = crypto.generateKeyPairSync("ml-dsa-65");
+    process.env.XYTARA_DELIVERY_RECEIPT_ED25519_KEY = receiptEd.privateKey.export({ type: "pkcs8", format: "der" }).toString("base64");
+    process.env.XYTARA_DELIVERY_RECEIPT_MLDSA65_KEY = receiptMl.privateKey.export({ type: "pkcs8", format: "der" }).toString("base64");
     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");
@@ -152,6 +158,70 @@ async function main() {
     assert.strictEqual(receipt.success, true, "settlement receipt must report success");
     assert.strictEqual(receipt.transaction, "0xmocktx", "settlement receipt transaction mismatch");
 
+    // 6a. The runtime records the REAL x402 settlement (not the quote's default placeholder rail).
+    const recorded = paid.json.receipt.settlement;
+    assert.strictEqual(recorded.rail, "x402", "x402-paid call records the x402 rail");
+    assert.strictEqual(recorded.mode, "x402_facilitator", "x402 settlement mode recorded");
+    assert.strictEqual(recorded.txid, "0xmocktx", "settlement record carries the settled tx");
+    assert.strictEqual(recorded.network, "eip155:84532", "settlement record carries the network");
+    assert.strictEqual(recorded.pay_to, ACCEPTS[0].payTo, "settlement record carries pay_to");
+    assert.strictEqual(recorded.status, "settled", "settlement record status");
+    assert.strictEqual(recorded.live, undefined, "no placeholder BSV settlement record for an x402 call");
+    assert.strictEqual(paid.json.receipt.treasury.rail, "x402", "treasury record on the x402 rail");
+    assert.strictEqual(paid.json.receipt.default_path.settlement_mode, "x402_facilitator", "default path reflects x402");
+
+    // 6b. Signed delivery receipt: binds the settlement, verifies against the published keys,
+    //     is retrievable by id, and rejects tampering and signature stripping.
+    const delivery = paid.json.delivery_receipt;
+    assert.ok(delivery, "paid result carries a delivery receipt");
+    assert.strictEqual(delivery.v, "naxytra-delivery-receipt/1", "delivery receipt version");
+    assert.deepStrictEqual(delivery.signing.suite, ["EdDSA", "ML-DSA-65"], "hybrid suite");
+    assert.strictEqual(delivery.payment.protocol, "x402", "receipt payment protocol");
+    assert.strictEqual(delivery.payment.settlement_tx, "0xmocktx", "receipt binds the settlement tx");
+    assert.strictEqual(delivery.payment.pay_to, ACCEPTS[0].payTo, "receipt carries pay_to");
+    assert.strictEqual(delivery.payment.amount, ACCEPTS[0].amount, "receipt carries the settled amount");
+    assert.strictEqual(delivery.call.quote_id, paid.json.transaction.quote_id, "receipt binds the quote");
+    assert.strictEqual(delivery.account_id, undefined, "receipt carries no account id");
+    const receiptLib = require("../lib/delivery_receipt");
+    assert.strictEqual(delivery.delivery.request_sha256, receiptLib.hashCanonical(execBody.body), "request hash recomputes from the request body");
+    const keysRes = await fetch(`${baseUrl}/.well-known/delivery-receipt-keys`);
+    const keys = await keysRes.json();
+    assert.strictEqual(keys.signing_state, "signing", "keys endpoint reports signing");
+    assert.strictEqual(receiptLib.verifyDeliveryReceipt(delivery, keys.keys).valid, true, "receipt verifies against the published keys");
+    const verifyRes = await post(baseUrl, "/v1/delivery-receipts/verify", { receipt: delivery });
+    assert.strictEqual(verifyRes.json.valid, true, "verify endpoint accepts the genuine receipt");
+    assert.strictEqual(verifyRes.json.issuer_matches, true, "verify endpoint matches the issuer");
+    const tamperedDelivery = JSON.parse(JSON.stringify(delivery));
+    tamperedDelivery.payment.amount = "1";
+    assert.strictEqual((await post(baseUrl, "/v1/delivery-receipts/verify", { receipt: tamperedDelivery })).json.valid, false, "tampered receipt rejected");
+    const strippedDelivery = JSON.parse(JSON.stringify(delivery));
+    strippedDelivery.sig.signatures = strippedDelivery.sig.signatures.filter((entry) => entry.alg !== "ML-DSA-65");
+    assert.strictEqual(receiptLib.verifyDeliveryReceipt(strippedDelivery, keys.keys).valid, false, "stripping the ML-DSA leg (downgrade) rejected");
+    const fetched = await fetch(`${baseUrl}/v1/delivery-receipts/${encodeURIComponent(delivery.receipt_id)}`);
+    assert.strictEqual(fetched.status, 200, "receipt retrievable by id");
+    assert.deepStrictEqual((await fetched.json()).delivery_receipt, delivery, "retrieved receipt is identical");
+    assert.strictEqual((await fetch(`${baseUrl}/v1/delivery-receipts/drcpt_nope`)).status, 404, "unknown receipt 404");
+    // The xoonya verifier accepts the same signatures (kid == xoonya key ref). Checked when the
+    // sibling xoonya checkout is present (workspace); skipped in a standalone xytara checkout.
+    let verifyExternalProofSignature = null;
+    try { ({ verifyExternalProofSignature } = require("../../xoonya/proof_sdk")); } catch (_) { verifyExternalProofSignature = null; }
+    const { sig: _omit, ...unsignedDelivery } = delivery;
+    for (const entry of verifyExternalProofSignature ? delivery.sig.signatures : []) {
+      const key = keys.keys.find((item) => item.kid === entry.kid);
+      const viaXoonya = verifyExternalProofSignature({ material: receiptLib.canonicalize(unsignedDelivery), signature: entry.value, algorithm: entry.alg, public_key: key.public_key_spki_der_base64, expected_key_ref: entry.kid });
+      assert.strictEqual(viaXoonya.signature_valid && viaXoonya.trust_anchored, true, `xoonya verifies + anchors the ${entry.alg} leg`);
+    }
+    delete process.env.XYTARA_DELIVERY_RECEIPT_ED25519_KEY;
+    delete process.env.XYTARA_DELIVERY_RECEIPT_MLDSA65_KEY;
+    // Without keys the receipt is still issued but honestly unsigned (never a fake signature).
+    const unsignedPaid = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("ok") });
+    assert.strictEqual(unsignedPaid.json.delivery_receipt.sig.state, "unsigned_signing_key_not_configured", "no keys -> honestly unsigned");
+    assert.strictEqual(receiptLib.verifyDeliveryReceipt(unsignedPaid.json.delivery_receipt, keys.keys).valid, false, "unsigned receipt never verifies");
+    // The shared module is byte-identical in the runtime and the MCP executor.
+    const fs = require("fs");
+    const path = require("path");
+    assert.ok(fs.readFileSync(path.join(__dirname, "..", "lib", "delivery_receipt.js")).equals(fs.readFileSync(path.join(__dirname, "..", "services", "mcp-execution-target", "delivery_receipt.js"))), "delivery_receipt.js copies must stay byte-identical");
+
     // 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;

package/server.js

@@ -198,6 +198,14 @@ const {
   buildProviderEarningsView
 } = require("./lib/provider_registry");
 const { loadPayoutSignerConfig, dispatchProviderPayout } = require("./lib/provider_payout_execution");
+const {
+  RECEIPT_VERSION: DELIVERY_RECEIPT_VERSION,
+  loadDeliveryReceiptSigners,
+  publicKeySet: deliveryReceiptPublicKeySet,
+  runtimeSupportsMlDsa,
+  verifyDeliveryReceipt,
+  verificationRecipe: deliveryReceiptVerificationRecipe
+} = require("./lib/delivery_receipt");
 const { buildProviderNetworkContract } = require("./lib/provider_network_contract");
 const {
   createEconomicsBudget,
@@ -7808,6 +7816,51 @@ async function routeRequest(req, res) {
     return;
   }
 
+  // Signed delivery receipts: the issuer's PUBLIC key set (pin these), fetch a receipt by id, and a
+  // free stateless verify. Receipts carry only public payment facts + hashes (no account, no secrets).
+  if (req.method === "GET" && (url.pathname === "/.well-known/delivery-receipt-keys" || url.pathname === "/v1/delivery-receipts/keys")) {
+    const { signers, problems } = loadDeliveryReceiptSigners("XYTARA_DELIVERY_RECEIPT");
+    sendJson(res, 200, {
+      ok: true,
+      issuer: "xytara-runtime",
+      receipt_version: DELIVERY_RECEIPT_VERSION,
+      signing_state: signers.length > 0 ? "signing" : "unsigned_signing_key_not_configured",
+      suite: signers.map((signer) => signer.alg),
+      keys: deliveryReceiptPublicKeySet(signers),
+      runtime_supports_ml_dsa: runtimeSupportsMlDsa(),
+      key_problems: problems.map((problem) => ({ variable: problem.variable, reason: problem.reason })),
+      verification: deliveryReceiptVerificationRecipe("/.well-known/delivery-receipt-keys")
+    });
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/delivery-receipts/verify") {
+    const body = await readJsonBody(req);
+    const receipt = body && typeof body === "object" && body.receipt && typeof body.receipt === "object" ? body.receipt : body;
+    const { signers } = loadDeliveryReceiptSigners("XYTARA_DELIVERY_RECEIPT");
+    const result = verifyDeliveryReceipt(receipt, deliveryReceiptPublicKeySet(signers));
+    sendJson(res, 200, {
+      ok: true,
+      ...result,
+      issuer_expected: "xytara-runtime",
+      issuer_matches: Boolean(receipt && receipt.issuer === "xytara-runtime"),
+      checked_against: "this runtime's current published keys (see /.well-known/delivery-receipt-keys)",
+      boundary: "signature validity only: settle the payment leg on-chain and recompute output_sha256 from the output you hold yourself"
+    });
+    return;
+  }
+
+  if (req.method === "GET" && url.pathname.startsWith("/v1/delivery-receipts/")) {
+    const receiptId = getDecodedSuffixId(url.pathname, "/v1/delivery-receipts/");
+    const stored = state.deliveryReceipts instanceof Map ? state.deliveryReceipts.get(receiptId) : null;
+    if (!stored) {
+      sendJson(res, 404, { ok: false, reason: "delivery_receipt_not_found" });
+      return;
+    }
+    sendJson(res, 200, { ok: true, delivery_receipt: stored });
+    return;
+  }
+
   // Public, machine-readable integration contract — how to become a provider. No auth, no secrets.
   if (req.method === "GET" && url.pathname === "/v1/provider-network/contract") {
     sendJson(res, 200, buildProviderNetworkContract());