xytara 3.1.13 → 3.1.14

package/.env.example

@@ -132,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/RELEASE_NOTES.md

@@ -1,5 +1,7 @@
-`xytara` 3.1.13 adds signed delivery receipts and makes the direct MCP path charge only on success.
+`xytara` 3.1.14 makes runtime state durable under backend failures, writes it more lightly, and backs it up off-site.
 
-- **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`).
+- **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.