xytara 3.1.12 → 3.1.14

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=
@@ -127,7 +132,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/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,7 @@
-`xytara` 3.1.12 makes the public adapter-depth surface report open-network providers truthfully.
+`xytara` 3.1.14 makes runtime state durable under backend failures, writes it more lightly, and backs it up off-site.
 
-- `/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.
+- **Write guard** — if the boot-time restore of durable state fails (e.g. the state backend times out), the runtime never writes: writing would overwrite the good snapshot with near-empty state. It retries the restore in the background, merges the snapshot under anything that happened since boot, and only then resumes writes. Proven in production during a state-backend outage: the full snapshot was restored with nothing lost.
+- **Lighter writes** — the snapshot is written only when its content changed (identical rewrites are skipped and counted), the default check interval is 15s, and expired never-paid quotes are pruned after 7 days (`XYTARA_QUOTE_RETENTION_MS`).
+- **Rolling history** — in Supabase mode the snapshot is also kept in rotating hourly history rows (24 by default), so a bad write can be rolled back.
+- **Off-site encrypted backups** — `scripts/state_backup_offsite.js` (gzip + AES-256-GCM; refuses a near-empty snapshot so a failed scheduled run is an alert; decrypt and guarded restore modes) with a daily workflow.
+- Published through npm trusted publishing (GitHub OIDC) — no npm token involved.