xytara 3.1.0 → 3.1.2

package/PUBLIC_DEMO_SCRIPT.md

@@ -1,78 +1,78 @@
-# xytara Public Demo Script
-
-Use this script when you need a short external-facing walkthrough of `xytara` that does not depend on private project history.
-
-## Goal
-
-Show the runtime side of the public stack in one compact flow:
-
-1. package is live
-2. runtime path is understandable
-3. partner posture is explicit
-4. proof-side continuation exists
-
-## Recommended order
-
-### 1. Release posture
-
-Run:
-
-```bash
-xytara-release --center --summary
-xytara-release --candidate --summary
-```
-
-Or inspect:
-
-- `/v1/release-center/summary`
-- `/v1/release-candidate/summary`
-
-### 2. Runtime durability posture
-
-Inspect:
-
-- `/v1/runtime/durability`
-
-Key sentence to say out loud:
-
-`xytara` treats durability as visible operational posture, not a hidden implementation detail.
-
-### 3. Public runtime walkthrough
-
-Run:
-
-```bash
-node examples/partner_launch_walkthrough.js
-```
-
-Then, if you want the broader package tour:
-
-```bash
-node examples/quickstart.js
-```
-
-### 4. Partner adoption path
-
-Open:
-
-- `PARTNER_READY_PATH.md`
-- `ADAPTER_PARTNER_PATH.md`
-
-Key sentence to say out loud:
-
-Outside teams can reach a reviewable adapter posture without private exceptions.
-
-### 5. Proof continuation
-
-Open:
-
-- `CARRIED_HANDOFF_DEMO.md`
-- `WHY_XYTARA_XOONYA.md`
-
-Key sentence to say out loud:
-
-`xytara` finishes the transaction-side path and hands cleanly into `xoonya` for proof-native completion.
-
-## Good ending line
-
-`xytara` is the public machine-commerce runtime: discover, fund, execute, inspect, and carry forward into proof.
+# xytara Public Demo Script
+
+Use this script when you need a short external-facing walkthrough of `xytara` that does not depend on private project history.
+
+## Goal
+
+Show the runtime side of the public stack in one compact flow:
+
+1. package is live
+2. runtime path is understandable
+3. partner posture is explicit
+4. proof-side continuation exists
+
+## Recommended order
+
+### 1. Release posture
+
+Run:
+
+```bash
+xytara-release --center --summary
+xytara-release --candidate --summary
+```
+
+Or inspect:
+
+- `/v1/release-center/summary`
+- `/v1/release-candidate/summary`
+
+### 2. Runtime durability posture
+
+Inspect:
+
+- `/v1/runtime/durability`
+
+Key sentence to say out loud:
+
+`xytara` treats durability as visible operational posture, not a hidden implementation detail.
+
+### 3. Public runtime walkthrough
+
+Run:
+
+```bash
+node examples/partner_launch_walkthrough.js
+```
+
+Then, if you want the broader package tour:
+
+```bash
+node examples/quickstart.js
+```
+
+### 4. Partner adoption path
+
+Open:
+
+- `PARTNER_READY_PATH.md`
+- `ADAPTER_PARTNER_PATH.md`
+
+Key sentence to say out loud:
+
+Outside teams can reach a reviewable adapter posture without private exceptions.
+
+### 5. Proof continuation
+
+Open:
+
+- `CARRIED_HANDOFF_DEMO.md`
+- `WHY_XYTARA_XOONYA.md`
+
+Key sentence to say out loud:
+
+`xytara` finishes the transaction-side path and hands cleanly into `xoonya` for proof-native completion.
+
+## Good ending line
+
+`xytara` is the public machine-commerce runtime: discover, fund, execute, inspect, and carry forward into proof.

package/README.md

@@ -2,6 +2,10 @@
 
 `xytara` is the runtime and payment layer for the public two-repo stack.
 
+> New to the code? Read [`ARCHITECTURE.md`](ARCHITECTURE.md) first. It separates
+> the small execution-and-settlement engine (~9,300 lines) from the large
+> machine-readable breadth catalog, so the real runtime is legible in one sitting.
+
 It exists to let agents, developers, and systems:
 
 - discover tasks and workflows
@@ -1009,7 +1013,8 @@ Environment example:
 
 Production payment note:
 
-- set `XYTARA_PAYMENT_VERIFICATION_MODE=local_signed` to enforce verifiable signed payment acceptance instead of plain header presence
+- `XYTARA_PAYMENT_VERIFICATION_MODE` defaults to `local_signed` (verifiable signed payment acceptance); `presence` must be opted into explicitly and only accepts plain header presence for local development
+- operator write surfaces (`/v1/economics/*` ledger mutations, `/v1/agent-accounts`, `/v1/operator-shell/admin-pack`, `/v1/credit-bridge/grants`, business cockpit) fail closed with `operator_auth_not_configured` until `XYTARA_ACCOUNT_AUTH_BEARER_TOKEN` and `XYTARA_CREDIT_BRIDGE_BEARER_TOKEN` are set; send `Authorization: Bearer <token>`; query-string tokens are not accepted
 - provide buyer wallet verification material through `XYTARA_WALLET_REGISTRY_JSON` or `XYTARA_WALLET_REGISTRY_PATH`
 - set `XYTARA_TREASURY_DESTINATION_ID` and related treasury env vars so accepted payments land in your merchant treasury posture instead of the default local account placeholder
 - built-in `x402` is the admission lane; real external payout/custody still depends on the payment rail and treasury destination you configure behind that lane

package/REAL_PAYMENT_SETUP.md

@@ -4,18 +4,47 @@ This guide explains how to move `xytara` from local placeholder payment acceptan
 
 ## What Changed
 
-`xytara` now supports two payment-acceptance modes:
+`xytara` supports three payment-acceptance modes. `local_signed` is the default; `presence` and `x402_facilitator` are opt-in.
 
 - `presence`
-  - development/demo mode
+  - development/demo mode only, enabled with `XYTARA_PAYMENT_VERIFICATION_MODE=presence`
   - payment headers are required, but not cryptographically verified
+  - the server logs a warning at startup when this mode is active
 
 - `local_signed`
-  - production-oriented built-in mode
+  - the default and the production-oriented built-in mode
   - signed payment payloads are cryptographically verified against a configured wallet registry
   - quote replay and nonce replay are blocked
   - accepted payments are routed into your configured merchant treasury destination posture
 
+- `x402_facilitator`
+  - trustless, on-chain, pay-per-call, the same mechanism proven live on the MCP executor
+  - the `/x402/commands/execute` and `/x402/mcp/tools/invoke` routes return a `402` that
+    advertises the configured `accepts` (network, asset, amount, payTo) in the
+    `PAYMENT-REQUIRED` header; a buyer signs a gasless x402 USDC authorization (EIP-3009)
+  - on the paid retry, a facilitator verifies the payment and settles it on-chain before any
+    work runs; the response carries a `PAYMENT-RESPONSE` settlement receipt
+  - fails closed: if the facilitator is unreachable or the payment does not settle, nothing runs
+  - the buyer needs no native gas token; the facilitator broadcasts the transfer
+  - enable with `XYTARA_PAYMENT_VERIFICATION_MODE=x402_facilitator` and the x402 env below:
+
+```env
+XYTARA_PAYMENT_VERIFICATION_MODE=x402_facilitator
+# what buyers pay, advertised in the 402 (Base Sepolia test USDC shown):
+XYTARA_X402_ACCEPTS_JSON=[{"scheme":"exact","network":"eip155:84532","asset":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","amount":"1000","payTo":"<your-evm-address>","extra":{"name":"USDC","version":"2"},"maxTimeoutSeconds":60}]
+XYTARA_X402_FACILITATOR_URL=https://x402.org/facilitator
+# optional:
+XYTARA_X402_FACILITATOR_HEADERS_JSON={}
+XYTARA_X402_FACILITATOR_TIMEOUT_MS=15000
+XYTARA_X402_SETTLE=true
+```
+
+Confirm the facilitator settles every network you advertise, and verify the mode end to end
+against a mock facilitator with `npm run verify:x402-facilitator`. The payment a buyer signs
+is identical to the one in `services/mcp-execution-target/buyer-demo/` (an EIP-3009 USDC
+authorization in a `PAYMENT-SIGNATURE` header); only the request body differs, since the main
+runtime takes a command-execute body rather than an MCP JSON-RPC call.
+
 ## Minimum Production-Oriented Configuration
 
 Set these environment variables:

package/RELEASE_NOTES.md

@@ -1,14 +1,14 @@
-`xytara` 3.1.0 is the synchronized control-plane and evidence-line release for the live runtime, payment, execution, delivery, treasury activation, and public first-contact line.
-
-This release keeps the public runtime line synchronized after the major cut by preserving the same live runtime truth models, widened finish-line scope, and naxytra public contract, proof, release, and gate surfaces while tightening the installable package experience for outside agents and builders.
-
-Highlights:
-
-- keeps `/v1/execution-truth` and `/v1/execution-truth/summary` as the named runtime fact boundary
-- keeps `/v1/default-path` and `/v1/default-path/summary` as the named multi-surface runtime entry boundary
-- keeps `/v1/payment-rail-truth` and `/v1/payment-rail-truth/summary` as the named payment and settlement-claim boundary
-- keeps `/v1/adapter-protocol-truth` and `/v1/adapter-protocol-truth/summary` as the named first-party front and bounded bridge boundary
-- keeps the live public catalog, full-catalog claim, first-run path, release kit, public proof surfaces, and final `3.1.0` contract/gate references aligned with the release line so operators and outside builders see the same truth
-- keeps the canonical `https://naxytra.com/xytara` public product URL and synchronized naxytra release posture intact
-- surfaces the public evidence lanes for adapter certification, trust portability boundaries, and signed audit/provenance alongside the live public control-plane story
-- verifies the release candidate, full package verifier, umbrella pre-deploy gates, clean-consumer release smoke, and public evidence lane checks before the synchronized control-plane release
+`xytara` 3.1.2 adds trustless, on-chain, pay-per-call settlement to the main runtime.
+
+This release brings the facilitator verify-and-settle mechanism already proven on the public MCP executor to the runtime itself, so every x402 route can settle a real payment on-chain before any work runs, not just the standalone tool server.
+
+Highlights:
+
+- adds a third payment-acceptance mode, `x402_facilitator`, enabled with `XYTARA_PAYMENT_VERIFICATION_MODE=x402_facilitator`
+- when enabled, `/x402/commands/execute` and `/x402/mcp/tools/invoke` return a `402` that advertises the configured `accepts` (network, asset, amount, payTo) in the `PAYMENT-REQUIRED` header
+- a buyer signs a gasless USDC authorization (EIP-3009); on the paid retry a facilitator verifies and settles it on-chain before any work runs, and the response carries a `PAYMENT-RESPONSE` settlement receipt
+- fails closed: if the facilitator is unreachable or the payment does not settle, nothing runs and no result is returned
+- the mode governs only the x402 routes; native and instant lanes fall back to `local_signed`, so no existing paid path is disabled
+- keeps `local_signed` as the default and `presence` as the local-development opt-in
+- adds `npm run verify:x402-facilitator`, an end-to-end check against a mock facilitator covering the advertised challenge, malformed and mismatched payments, facilitator rejection, failed settlement, and a settled success with receipt
+- documents the mode and its environment in `REAL_PAYMENT_SETUP.md` and the architecture in `ARCHITECTURE.md`