xytara 3.1.13 → 3.1.15

package/.env.example

@@ -10,9 +10,36 @@ XYTARA_X402_FACILITATOR_URL=https://x402.org/facilitator
 XYTARA_X402_FACILITATOR_HEADERS_JSON={}
 XYTARA_X402_FACILITATOR_TIMEOUT_MS=15000
 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
+# self-serve /x402/credits/topup: priced at this multiple of the per-call accepts amount
+# (default 100: $0.01 -> $1.00); credits = amount paid / XYTARA_CREDIT_UNIT_PRICE_ATOMIC
+# (USDC base units per credit; default 2500 = $0.0025). An accepts entry's extra.credits may
+# lower the grant, never raise it. Testnet networks cannot buy credits unless this is 1:
+XYTARA_X402_TOPUP_AMOUNT_MULTIPLIER=100
+XYTARA_CREDIT_UNIT_PRICE_ATOMIC=2500
+XYTARA_X402_TESTNET_TOPUP=0
+# floor for the advertised maxTimeoutSeconds (buyers sign validBefore = now + this)
+XYTARA_X402_MIN_TIMEOUT_SECONDS=300
+# money-safety policies: "strict" by default on a hosted deploy (RENDER set), "permissive" locally.
+#  paid execution: only tasks with a real execution target can be quoted/charged
+#  credit spend:   spending credits needs the account's spend credential (xytara_spend_...)
+#  ledger reads:   ledger/quote-list/receipts/operations/revenue GETs are operator-only
+XYTARA_PAID_EXECUTION_POLICY=
+XYTARA_CREDIT_SPEND_POLICY=
+XYTARA_LEDGER_READ_POLICY=
+# provider calls: per-attempt timeout floor for registered providers (default 25000 on Render)
+XYTARA_PROVIDER_MIN_TIMEOUT_MS=
+# chain RPC used to check whether an x402 authorization settled after a facilitator timeout
+XYTARA_RPC_URL_EIP155_8453=https://mainnet.base.org
+XYTARA_RPC_URL_EIP155_84532=https://sepolia.base.org
+# buyer event log: ring size, payer-hash salt, and the token the MCP executor uses to forward
+# its events to POST /v1/operator/buyer-events/ingest
+XYTARA_BUYER_EVENT_LOG_MAX=500
+XYTARA_BUYER_EVENT_SALT=
+XYTARA_EVENT_INGEST_TOKEN=
+# Supabase request timeout (ms) for state restore/flush
+XYTARA_SUPABASE_TIMEOUT_MS=10000
+# public base URL advertised in OpenAPI/AsyncAPI
+XYTARA_PUBLIC_BASE_URL=https://xytara.onrender.com
 # 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=
@@ -132,7 +159,14 @@ XYTARA_EXTERNAL_EXECUTION_IP_FAMILY=auto
 XYTARA_CALLBACK_IP_FAMILY=auto
 XYTARA_SETTLEMENT_IP_FAMILY=auto
 XYTARA_STATE_FILE=./var/xytara/runtime-state.json
-XYTARA_STATE_SNAPSHOT_INTERVAL_MS=5000
+# How often the durable snapshot is checked for changes; an unchanged snapshot is never rewritten.
+XYTARA_STATE_SNAPSHOT_INTERVAL_MS=15000
+# Supabase mode: also keep rolling history copies of the snapshot in the same table
+# (rows "<state key>::history::<n>"), one per interval, rotating over N slots. 0 disables.
+XYTARA_STATE_HISTORY_INTERVAL_MS=3600000
+XYTARA_STATE_HISTORY_SLOTS=24
+# Expired, never-paid quotes are dropped from durable state after this long (default 7 days).
+XYTARA_QUOTE_RETENTION_MS=604800000
 XYTARA_SUPABASE_URL=
 XYTARA_SUPABASE_SERVICE_ROLE_KEY=
 XYTARA_SUPABASE_STATE_TABLE=xytara_runtime_state

package/BSV_TERANODE_PLATFORM_DISCONTINUITY_RUNBOOK.md

@@ -1,126 +1,126 @@
-# BSV Teranode Platform Discontinuity Runbook
-
-Date: `2026-05-06`
-
-## Purpose
-
-This runbook explains how to keep `xytara` production-safe through the announced shutdown of the legacy Teranode web platform on `2026-05-15`.
-
-The important distinction is:
-
-- the dashboard/control-plane website is being discontinued
-- your runtime settlement contract in `xytara` should continue to depend on live ARC submission and live observation endpoints, not on the retiring dashboard
-
-## What The Notice Means Operationally
-
-Treat the notice as saying:
-
-- do not depend on `https://platform.teranode.group/` remaining available for operator workflows after `2026-05-15`
-- existing API keys may continue working, but you should not treat that as your only launch-safe posture
-- if you want a replacement ARC key after the shutdown, request it proactively before launch
-- WhatsOnChain support and contact ownership are separate from the retiring dashboard
-
-## Immediate Pre-3.0.0 Actions
-
-1. Back up the operator information you still need from the legacy platform now.
-   - current API key labels
-   - network association
-   - any usage or billing screenshots you care about
-   - any endpoint, auth, or support notes you may need later
-
-2. Do not expose or rotate secrets casually.
-   - keep the current live ARC key in place until a tested replacement exists
-   - treat screenshots or copied values as sensitive
-
-3. Acquire a replacement or second ARC key before cutover if possible.
-   - that gives us a tested rollback-safe key path instead of a launch-week scramble
-
-4. Keep the observer path independent.
-   - `xytara` already defaults to WhatsOnChain for observation unless overridden
-   - if you want a different observer, set it explicitly
-
-5. Keep the runtime provider-neutral.
-   - prefer the neutral `XYTARA_BSV_*` aliases going forward
-   - legacy `XYTARA_BSV_TERANODE_*` envs remain supported for compatibility
-
-## Preferred Environment Shape Going Forward
-
-Use these neutral envs where practical:
-
-```env
-XYTARA_BSV_NETWORK=mainnet
-XYTARA_BSV_SETTLEMENT_RUNTIME_MODE=arc
-XYTARA_BSV_MERCHANT_ADDRESS=<real-bsv-address-or-paymail>
-XYTARA_BSV_ARC_RPC_URL=<live-arc-submit-endpoint>
-XYTARA_BSV_ARC_RPC_API_KEY=<live-arc-api-key>
-XYTARA_BSV_ARC_RPC_AUTH_HEADER=authorization
-XYTARA_BSV_ARC_RPC_AUTH_SCHEME=
-XYTARA_BSV_OBSERVER_URL=https://api.whatsonchain.com/v1/bsv/main
-```
-
-Legacy compatibility envs are still accepted:
-
-- `XYTARA_BSV_TERANODE_NETWORK`
-- `XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE`
-- `XYTARA_BSV_TERANODE_MERCHANT_ADDRESS`
-- `XYTARA_BSV_TERANODE_MERCHANT_PAYMAIL`
-- `XYTARA_BSV_ARC_RPC_URL`
-- `XYTARA_BSV_ARC_RPC_API_KEY`
-- `XYTARA_BSV_ARC_RPC_AUTH_HEADER`
-- `XYTARA_BSV_ARC_RPC_AUTH_SCHEME`
-- legacy `XYTARA_BSV_TERANODE_RPC_*` aliases remain accepted
-- `XYTARA_BSV_TERANODE_OBSERVER_URL`
-
-## Cutover Validation Sequence
-
-After you have either confirmed the current key still works or obtained a replacement ARC key:
-
-1. update the live Render envs for `xytara`
-2. redeploy `xytara`
-3. check:
-
-```text
-GET /v1/settlement/bsv-teranode/readiness
-GET /v1/settlement/bsv-teranode
-GET /v1/payment-rail-truth/summary
-GET /v1/autonomous-entry/summary
-```
-
-4. run one real settlement path validation
-   - one quote
-   - one payment acceptance path
-   - one settlement record
-   - one submit/refresh loop
-
-5. confirm:
-   - live submission still works in `arc` mode
-   - live observation still works
-   - the runtime does not depend on the retiring dashboard
-
-## What To Change If The Provider Changes Endpoint Or Auth Style
-
-If the ARC provider gives you:
-
-- a new submit URL
-- a new auth header
-- a new auth scheme
-- a replacement API key
-
-you should only need to update env values, not the public `bsv_teranode` product contract.
-
-That is exactly why the runtime should remain:
-
-- provider-neutral in config
-- stable in public naming
-- explicit in readiness checks
-
-## Launch Rule
-
-Do not let the old dashboard shutdown weaken the `3.0.0` product truth unnecessarily.
-
-The right finish-line standard is:
-
-- `bsv_teranode` remains the native public settlement name
-- `xytara` remains provider-neutral behind that name
-- live ARC submission and live observation remain validated at operator level
-- the public product keeps working even if the original dashboard disappears
+# BSV Teranode Platform Discontinuity Runbook
+
+Date: `2026-05-06`
+
+## Purpose
+
+This runbook explains how to keep `xytara` production-safe through the announced shutdown of the legacy Teranode web platform on `2026-05-15`.
+
+The important distinction is:
+
+- the dashboard/control-plane website is being discontinued
+- your runtime settlement contract in `xytara` should continue to depend on live ARC submission and live observation endpoints, not on the retiring dashboard
+
+## What The Notice Means Operationally
+
+Treat the notice as saying:
+
+- do not depend on `https://platform.teranode.group/` remaining available for operator workflows after `2026-05-15`
+- existing API keys may continue working, but you should not treat that as your only launch-safe posture
+- if you want a replacement ARC key after the shutdown, request it proactively before launch
+- WhatsOnChain support and contact ownership are separate from the retiring dashboard
+
+## Immediate Pre-3.0.0 Actions
+
+1. Back up the operator information you still need from the legacy platform now.
+   - current API key labels
+   - network association
+   - any usage or billing screenshots you care about
+   - any endpoint, auth, or support notes you may need later
+
+2. Do not expose or rotate secrets casually.
+   - keep the current live ARC key in place until a tested replacement exists
+   - treat screenshots or copied values as sensitive
+
+3. Acquire a replacement or second ARC key before cutover if possible.
+   - that gives us a tested rollback-safe key path instead of a launch-week scramble
+
+4. Keep the observer path independent.
+   - `xytara` already defaults to WhatsOnChain for observation unless overridden
+   - if you want a different observer, set it explicitly
+
+5. Keep the runtime provider-neutral.
+   - prefer the neutral `XYTARA_BSV_*` aliases going forward
+   - legacy `XYTARA_BSV_TERANODE_*` envs remain supported for compatibility
+
+## Preferred Environment Shape Going Forward
+
+Use these neutral envs where practical:
+
+```env
+XYTARA_BSV_NETWORK=mainnet
+XYTARA_BSV_SETTLEMENT_RUNTIME_MODE=arc
+XYTARA_BSV_MERCHANT_ADDRESS=<real-bsv-address-or-paymail>
+XYTARA_BSV_ARC_RPC_URL=<live-arc-submit-endpoint>
+XYTARA_BSV_ARC_RPC_API_KEY=<live-arc-api-key>
+XYTARA_BSV_ARC_RPC_AUTH_HEADER=authorization
+XYTARA_BSV_ARC_RPC_AUTH_SCHEME=
+XYTARA_BSV_OBSERVER_URL=https://api.whatsonchain.com/v1/bsv/main
+```
+
+Legacy compatibility envs are still accepted:
+
+- `XYTARA_BSV_TERANODE_NETWORK`
+- `XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE`
+- `XYTARA_BSV_TERANODE_MERCHANT_ADDRESS`
+- `XYTARA_BSV_TERANODE_MERCHANT_PAYMAIL`
+- `XYTARA_BSV_ARC_RPC_URL`
+- `XYTARA_BSV_ARC_RPC_API_KEY`
+- `XYTARA_BSV_ARC_RPC_AUTH_HEADER`
+- `XYTARA_BSV_ARC_RPC_AUTH_SCHEME`
+- legacy `XYTARA_BSV_TERANODE_RPC_*` aliases remain accepted
+- `XYTARA_BSV_TERANODE_OBSERVER_URL`
+
+## Cutover Validation Sequence
+
+After you have either confirmed the current key still works or obtained a replacement ARC key:
+
+1. update the live Render envs for `xytara`
+2. redeploy `xytara`
+3. check:
+
+```text
+GET /v1/settlement/bsv-teranode/readiness
+GET /v1/settlement/bsv-teranode
+GET /v1/payment-rail-truth/summary
+GET /v1/autonomous-entry/summary
+```
+
+4. run one real settlement path validation
+   - one quote
+   - one payment acceptance path
+   - one settlement record
+   - one submit/refresh loop
+
+5. confirm:
+   - live submission still works in `arc` mode
+   - live observation still works
+   - the runtime does not depend on the retiring dashboard
+
+## What To Change If The Provider Changes Endpoint Or Auth Style
+
+If the ARC provider gives you:
+
+- a new submit URL
+- a new auth header
+- a new auth scheme
+- a replacement API key
+
+you should only need to update env values, not the public `bsv_teranode` product contract.
+
+That is exactly why the runtime should remain:
+
+- provider-neutral in config
+- stable in public naming
+- explicit in readiness checks
+
+## Launch Rule
+
+Do not let the old dashboard shutdown weaken the `3.0.0` product truth unnecessarily.
+
+The right finish-line standard is:
+
+- `bsv_teranode` remains the native public settlement name
+- `xytara` remains provider-neutral behind that name
+- live ARC submission and live observation remain validated at operator level
+- the public product keeps working even if the original dashboard disappears

package/REAL_PAYMENT_SETUP.md

@@ -50,17 +50,24 @@ runtime takes a command-execute body rather than an MCP JSON-RPC call.
 Beyond paying per call, a buyer can convert a single x402 payment into spendable
 runtime credits with no operator grant, via `POST /x402/credits/topup`:
 
-- without a `PAYMENT-SIGNATURE`, it returns `402` advertising the same `accepts` plus
-  `credits_per_topup` (how many credit units one payment buys)
+- without a `PAYMENT-SIGNATURE`, it returns `402` advertising the top-up `accepts` (each
+  per-call amount x `XYTARA_X402_TOPUP_AMOUNT_MULTIPLIER`, default 100: $0.01 -> $1.00),
+  `credits_per_topup` and a `topup_options` list (network, amount, credits)
 - with a valid payment, the facilitator settles it on-chain and the runtime mints the
-  credits to the account, returning the grant, the new balance, and a `PAYMENT-RESPONSE`
-  settlement receipt
-- credits land on `account_id` from the body, falling back to the paying wallet address
+  credits to the account, returning the grant, the new balance, a `PAYMENT-RESPONSE`
+  settlement receipt and — when the credits went to the paying address — a
+  `spend_credential` (`Bearer xytara_spend_...`, shown once) for spending them
+- credits land on the paying wallet address by default; credits sent to another `account_id`
+  are a gift and carry no spend credential
 - replays are idempotent: the payment nonce keys the grant, so re-sending the same settled
   payment never mints twice
 
-Each top-up grants `XYTARA_X402_TOPUP_UNITS` credit units (default `1000`), unless the matched
-`accepts` entry sets its own `extra.credits`. The route is live only in `x402_facilitator`
+Credits are derived from what was paid: amount / `XYTARA_CREDIT_UNIT_PRICE_ATOMIC` (default
+2500 base units = $0.0025 per credit, so $1.00 buys 400 credits; a task costs 1–8 credits by
+tier). A matched `accepts` entry's `extra.credits` may lower that, never raise it. Testnet
+networks (Base Sepolia) cannot buy credits unless `XYTARA_X402_TESTNET_TOPUP=1`. Spend them with
+`payment_preference: "credits_first"` and the spend credential as the bearer — on a hosted
+deploy a bare `account_id` is never authority. The route is live only in `x402_facilitator`
 mode with `XYTARA_X402_ACCEPTS_JSON` set, and credits persist only when runtime state
 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`.

package/RELEASE_NOTES.md

@@ -1,5 +1,10 @@
-`xytara` 3.1.13 adds signed delivery receipts and makes the direct MCP path charge only on success.
+`xytara` 3.1.15 makes the buyer path safe end to end: a buyer is never charged for a result that was not produced, every failed attempt is visible to the operator, and standard x402 MCP clients can pay the MCP server directly.
 
-- **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`).
+- **Pay only for real work** — on a hosted deploy a task is quoted and charged only when it resolves to a real execution target (an operator-pinned target or an active open-network provider). Anything else is refused up front with `501 capability_not_executable` and the list of executable tasks; no payment is requested. The catalog marks every task with `purchase.executable_now` and its per-call price. Post-quantum proof verification (`adapter.xoonya.invoke`) is now a catalog task.
+- **Verify, execute, then settle — everywhere** — paid A2A calls now settle only after the skill succeeds, like the HTTP routes. If the facilitator times out at settlement, the runtime checks the EIP-3009 `authorizationState` on-chain: a used authorization is a settled payment and the result is delivered; otherwise the finished result is held and returned when the buyer resends the same payment (bound to the original request). A resent settled payment returns its stored result instead of failing. The execution deadline stays inside the signed authorization's `validBefore`, and the advertised `maxTimeoutSeconds` has a floor of 300.
+- **Credits are safe and priced from what was paid** — spending credits requires the account's spend credential; a bare `account_id` is never authority. A self-serve top-up is priced at 100x the per-call amount, is mainnet-only by default, grants credits derived from the amount paid (default $0.0025 per credit), and returns a spend credential to the paying address. Provider revenue on credit spends accrues on the credits' purchase value, never on the catalog quote. Credit routes answer `503` with `Retry-After` while durable state is still being restored.
+- **Buyer event log** — every failed buyer attempt is recorded with its stage, reason, fault (ours, upstream, buyer) and a request id the buyer also receives (`X-Request-Id`), with per-day counters for challenges issued and paid calls served. No signatures, request bodies, tokens or full addresses are stored. Operator-only `GET /v1/operator/buyer-events` and `/summary`; the MCP server forwards its events to `POST /v1/operator/buyer-events/ingest`; a daily report job flags money that moved without a delivered result.
+- **MCP server** — speaks the x402 MCP transport natively (payment-required tool result; payment in `_meta["x402/payment"]`, `PAYMENT-SIGNATURE` or `X-PAYMENT`; settlement in `_meta["x402/payment-response"]`), with `/mcp/http402` for fetch-wrapper clients. Bad arguments and unknown tools are rejected before any payment, `GET /mcp` is no longer a paid route, and CORS is enabled. Every paid tool was corrected so that an empty, invalid or unverifiable answer is an error and never charged; `json.validate` validates against a JSON Schema subset, `x402.verify-receipt` confirms only a matching USDC transfer, ABI tools are strict, and hostile inputs are bounded.
+- **Request-bound agent signatures** — the credit lifecycle routes (reserve, release, reverse) honour the agent's signed binding to the exact account, amount and task.
+- **Robustness and privacy** — malformed JSON is a `400` (oversize `413`), internal errors are logged under the request id without leaking details, state-store calls time out, registered providers get a cold-start timeout floor and are woken when a buyer is quoted, and ledger, quote-list, receipt, operations and revenue reads are operator-only on a hosted deploy. x402 challenges show the price actually charged; OpenAPI and AsyncAPI point at the hosted runtime.
+- Published through npm trusted publishing (GitHub OIDC) — no npm token involved.

package/fixtures/catalog.js

@@ -779,6 +779,28 @@ const tasks = [
     capabilities: ["adapter.mcp.invoke"],
     adapters: ["mcp"]
   }),
+  makeTask({
+    task_ref: "internal.adapter.xoonya.invoke",
+    public_task_ref: "adapter.xoonya.invoke",
+    public_category: "adapter",
+    public_title: "Post-quantum proof verification (xoonya)",
+    execution_mode: "direct_http",
+    pricing_band: "decision_support",
+    public_launch_price: { amount_minor: 1, currency: "USD_CENTS" },
+    latency_class: "near_real_time",
+    failure_posture: "retry_bounded",
+    input_schema: {
+      type: "object",
+      required: ["tool_name"],
+      properties: {
+        tool_name: { type: "string", enum: ["proof.verify-signature", "proof.verify-bundle"] },
+        arguments: { type: "object" }
+      },
+      additionalProperties: false
+    },
+    capabilities: ["adapter.xoonya.invoke"],
+    adapters: ["xoonya"]
+  }),
   makeTask({
     task_ref: "internal.adapter.mcp.catalog",
     public_task_ref: "adapter.mcp.catalog",