xytara 3.1.17 → 3.2.0

package/.env.example

@@ -1,173 +0,0 @@
-XYTARA_HOST=127.0.0.1
-XYTARA_PORT=4320
-XYTARA_BASE_URL=http://127.0.0.1:4320
-# local_signed is the default; presence (accepts any non-empty payment header) is for local demos;
-# x402_facilitator is trustless on-chain pay-per-call (see REAL_PAYMENT_SETUP.md and the vars below)
-XYTARA_PAYMENT_VERIFICATION_MODE=local_signed
-# used only when mode is x402_facilitator:
-XYTARA_X402_ACCEPTS_JSON=[]
-XYTARA_X402_FACILITATOR_URL=https://x402.org/facilitator
-XYTARA_X402_FACILITATOR_HEADERS_JSON={}
-XYTARA_X402_FACILITATOR_TIMEOUT_MS=15000
-XYTARA_X402_SETTLE=true
-# 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=
-CDP_API_KEY_SECRET=
-# (XYTARA_X402_CDP_KEY_ID / XYTARA_X402_CDP_KEY_SECRET are accepted as aliases for the two above)
-XYTARA_PAYMENT_MAX_AGE_SECONDS=300
-XYTARA_WALLET_REGISTRY_JSON=[]
-XYTARA_TREASURY_DESTINATION_ID=
-XYTARA_TREASURY_DESTINATION_KIND=
-XYTARA_TREASURY_ACCOUNT_ID=
-XYTARA_TREASURY_EXTERNAL_REF=
-XYTARA_TREASURY_DESTINATIONS_JSON={}
-# optional file-backed alternatives to the two *_JSON values above (blank = use the JSON values)
-XYTARA_WALLET_REGISTRY_PATH=
-XYTARA_TREASURY_DESTINATIONS_PATH=
-XYTARA_BSV_TERANODE_NETWORK=mainnet
-XYTARA_BSV_TERANODE_RPC_URL=
-XYTARA_BSV_TERANODE_MODE=opreturn
-XYTARA_BSV_TERANODE_REQUIRED_CONFIRMATIONS=1
-XYTARA_BSV_TERANODE_MERCHANT_ADDRESS=
-XYTARA_BSV_TERANODE_MERCHANT_PAYMAIL=
-XYTARA_BSV_TERANODE_MERCHANT_LABEL=naxytra-runtime
-XYTARA_BSV_TERANODE_USE_METANET=false
-XYTARA_BSV_TERANODE_SATS_PER_USD_CENT=100
-XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE=mock
-# operator write surfaces fail closed until both tokens are set
-XYTARA_CREDIT_BRIDGE_BEARER_TOKEN=
-XYTARA_ACCOUNT_AUTH_BEARER_TOKEN=
-# commerce-bridge write surface (distinct from the credit bridge); also fails closed until set
-XYTARA_COMMERCE_BRIDGE_BEARER_TOKEN=
-# optional: require spend-proof binding on spend-credential use (blank = runtime default)
-XYTARA_REQUIRE_SPEND_PROOF_BINDING=
-# hosted-checkout webhook verification (blank = runtime defaults; set the secret before going live)
-XYTARA_CHECKOUT_WEBHOOK_SECRET=
-XYTARA_HOSTED_CHECKOUT_WEBHOOK_SECRET=
-XYTARA_CHECKOUT_WEBHOOK_VERIFICATION_REQUIRED=
-XYTARA_CHECKOUT_WEBHOOK_MAX_AGE_SECONDS=
-# optional commerce pack map / prep TTL overrides (blank = runtime defaults)
-XYTARA_COMMERCE_PACK_MAP_JSON=
-XYTARA_COMMERCE_PREP_TTL_MS=
-XYTARA_CALLBACK_DELIVERY_ENABLED=true
-XYTARA_CALLBACK_SIGNING_SECRET=
-XYTARA_CALLBACK_TIMEOUT_MS=5000
-XYTARA_CALLBACK_MAX_ATTEMPTS=5
-XYTARA_CALLBACK_RETRY_BASE_MS=2000
-XYTARA_RUNTIME_WORKER_INTERVAL_MS=500
-XYTARA_SETTLEMENT_REFRESH_INTERVAL_MS=1500
-XYTARA_RATE_LIMIT_ENABLED=true
-XYTARA_RATE_LIMIT_WINDOW_MS=60000
-XYTARA_RATE_LIMIT_MAX_REQUESTS=600
-# optional: scope the rate limit per route instead of globally (blank = runtime default)
-XYTARA_RATE_LIMIT_ROUTE_SCOPED=
-XYTARA_REQUEST_TIMEOUT_MS=30000
-XYTARA_HEADERS_TIMEOUT_MS=15000
-XYTARA_EXECUTION_TARGETS_JSON=[]
-# External execution (env targets + registered providers). Cold-start ride-out retries ONLY on
-# not-processed signals (408/429/503, connection refused/DNS). The budget is the TOTAL wall-clock for
-# one buyer call across all retries AND failover candidates, kept inside the ~60s x402 authorization
-# window so a ridden-out call still settles. Per-target timeout_ms is capped at 30000 for the same reason.
-XYTARA_EXTERNAL_EXECUTION_RETRY_WINDOW_MS=45000
-XYTARA_EXTERNAL_EXECUTION_MAX_RETRIES=29
-XYTARA_EXTERNAL_EXECUTION_BUDGET_MS=50000
-# Open execution-provider network (lib/provider_registry.js): providers self-register an endpoint +
-# the capabilities they serve; the runtime routes paid calls to ACTIVE providers and splits revenue.
-# Registration FAILS CLOSED until the bearer is set, UNLESS open registration is turned on. Every
-# provider still lands pending until an operator activates it (the vetting gate). See the live
-# machine contract at GET /v1/provider-network/contract.
-XYTARA_PROVIDER_REGISTRY_BEARER_TOKEN=
-# 1 = permissionless self-registration (no bearer); still rate-limited + pending-capped.
-XYTARA_PROVIDER_OPEN_REGISTRATION=0
-XYTARA_PROVIDER_REGISTRATION_RATE_PER_MIN=5
-XYTARA_PROVIDER_REGISTRATION_RATE_GLOBAL_PER_MIN=60
-XYTARA_PROVIDER_MAX_PENDING=100
-# provider endpoint policy: strict (default when RENDER is set) = https only + no loopback/private/
-# link-local/metadata hosts, re-checked by DNS at dispatch; permissive (default locally) for dev/tests
-XYTARA_PROVIDER_ENDPOINT_POLICY=
-# cap on a provider's revenue share, basis points (10000 = 100%)
-XYTARA_PROVIDER_MAX_REVENUE_SHARE_BPS=10000
-# health/failover: consecutive failures -> unhealthy; cooldown before a half-open retry; max candidates tried
-XYTARA_PROVIDER_UNHEALTHY_THRESHOLD=3
-XYTARA_PROVIDER_UNHEALTHY_COOLDOWN_MS=60000
-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=
-XYTARA_PAYOUT_SIGNER_BEARER=
-XYTARA_PAYOUT_SIGNER_TIMEOUT_MS=20000
-XYTARA_L402_ENABLED=false
-XYTARA_L402_SHARED_SECRET=
-# optional L402 tuning (blank = runtime defaults)
-XYTARA_L402_MAX_AGE_SECONDS=
-XYTARA_L402_INVOICE_RATE_PER_MIN=
-XYTARA_L402_INVOICE_RATE_GLOBAL_PER_MIN=
-XYTARA_BOLT_ENABLED=false
-XYTARA_BOLT_SHARED_SECRET=
-XYTARA_BOLT_NETWORK=mainnet
-XYTARA_BOLT_PROOF_MODE=spv_or_block_header_verifiable
-XYTARA_BOLT_MAX_AGE_SECONDS=300
-XYTARA_MPP_ENABLED=false
-XYTARA_MPP_SHARED_SECRET=
-XYTARA_MPP_PROVIDER=stripe_tempo_compatible
-XYTARA_MPP_SETTLEMENT_FAMILY=cards_or_stablecoin_or_lightning
-XYTARA_MPP_MAX_AGE_SECONDS=300
-# optional minimum MPP amount in minor units (blank = runtime default)
-XYTARA_MPP_MIN_AMOUNT_MINOR=
-XYTARA_NETWORK_DNS_RESULT_ORDER=verbatim
-XYTARA_NETWORK_PREFERRED_IP_FAMILY=auto
-XYTARA_EXTERNAL_EXECUTION_IP_FAMILY=auto
-XYTARA_CALLBACK_IP_FAMILY=auto
-XYTARA_SETTLEMENT_IP_FAMILY=auto
-XYTARA_STATE_FILE=./var/xytara/runtime-state.json
-# 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
-XYTARA_SUPABASE_STATE_KEY=default

package/ADAPTER_START_HERE.md

@@ -1,56 +0,0 @@
-# xytara Adapter Start Here
-
-Use this path if you want to build a third-party adapter against public `xytara`.
-
-## Recommended order
-
-1. Read `adapters/AUTHORING_GUIDE.md`.
-2. Read `adapters/ONBOARDING_POSTURE.md`.
-3. Read `adapters/THIRD_PARTY_SUBMISSION_PROCESS.md`.
-4. Run `npm run verify:adapters`.
-5. Validate and review one example bundle:
-   - `node scripts/registry_cli.js validate-bundle --example protocol`
-   - `node scripts/registry_cli.js review-bundle --example protocol`
-6. Inspect promotion posture:
-   - `node scripts/registry_cli.js promotion-readiness --integration partner.protocol.acme_mcp`
-   - `node scripts/registry_cli.js promotion-action-set --integration partner.protocol.acme_mcp`
-7. When you want the explicit staged-to-trusted walkthrough, continue with:
-   - `ADAPTER_PROMOTION_START_HERE.md`
-
-## Fastest copy-and-adapt starter
-
-If you want the shortest third-party starter path, copy these and rename them:
-
-- `adapters/examples/minimal-third-party-execution-adapter.manifest.json`
-- `adapters/examples/minimal-third-party-execution-adapter.js`
-- `adapters/examples/minimal-third-party-execution-registration.record.json`
-- `adapters/examples/minimal-third-party-execution.certification-pack.json`
-- `adapters/examples/minimal-third-party-execution.submission-bundle.json`
-
-## Adapter classes
-
-- `execution_adapter`
-- `payment_rail_adapter`
-- `settlement_adapter`
-- `agent_protocol_adapter`
-- `identity_registry_adapter`
-
-## Artifact stack
-
-Every serious third-party integration should converge on:
-
-1. adapter manifest
-2. registration record
-3. certification pack
-4. submission bundle
-5. submission bundle set when multiple integrations are reviewed together
-6. registry snapshot for normalized review/import posture
-
-## Public review surfaces
-
-- `/v1/integrations/summary`
-- `/v1/integrations/promotion-readiness`
-- `/v1/integrations/promotion-actions`
-- `/v1/integrations/review/submission-bundle`
-- `/v1/integrations/review/submission-bundle-set`
-- `/v1/integrations/review/registry-snapshot`

package/BSV_TERANODE_PLATFORM_DISCONTINUITY_RUNBOOK.md

@@ -1,126 +0,0 @@
-# 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/CARRIED_HANDOFF_DEMO.md

@@ -1,60 +0,0 @@
-# xytara Carried Handoff Demo
-
-This is the fastest concrete cross-repo path after the phase program closed.
-
-The goal is simple:
-
-1. export a result-package handoff from `xytara`
-2. review it with `xoonya`
-3. run the proof-side continuation
-
-## 1. Export A Real Handoff Bundle
-
-From the `xytara` repo root, run:
-
-```bash
-node examples/export_carried_handoff.js
-```
-
-This writes:
-
-```text
-examples/generated.carried-handoff.json
-```
-
-The file is already shaped for `xoonya-review`.
-
-## 2. Review It In xoonya
-
-From the `xoonya` repo root, run:
-
-```bash
-xoonya-review --file ../xytara/examples/generated.carried-handoff.json --summary
-```
-
-Or run the packaged example:
-
-```bash
-node examples/review_carried_handoff.js --file ../xytara/examples/generated.carried-handoff.json
-```
-
-## 3. What This Proves
-
-This is the clearest public adoption story now that the phase program is complete:
-
-- `xytara` does discovery, execution, and handoff export
-- `xoonya` does carried review and proof-side followthrough
-- the cross-repo seam is an inspectable bundle, not an undocumented internal jump
-
-## 4. Related Surfaces
-
-Runtime side:
-
-- `POST /v1/transaction-center/result-packages/export`
-- `GET /v1/transaction-center/result-package/export-template`
-
-Proof side:
-
-- `POST /v1/proof-center/result-package-handoff/review/summary`
-- `POST /v1/proof-center/result-package-handoff/run`
-- `xoonya-review --file ./handoff.json --summary`

package/EXAMPLE_PATHS.md

@@ -1,53 +0,0 @@
-# xytara Example Paths
-
-These are the recommended public examples for `xytara`.
-
-## Broad package tour
-
-Run:
-
-```bash
-node examples/quickstart.js
-```
-
-Use this when you want the widest package-level walkthrough.
-
-## Cross-repo carried handoff
-
-Run:
-
-```bash
-node examples/export_carried_handoff.js
-```
-
-Use this when you want the clearest handoff into `xoonya`.
-
-## Partner launch walkthrough
-
-Run:
-
-```bash
-node examples/partner_launch_walkthrough.js
-```
-
-Use this when you want the shortest release and launch oriented runtime story.
-
-## Funded runtime walkthrough
-
-Run:
-
-```bash
-node examples/funded_runtime_walkthrough.js
-```
-
-Use this when you want the reusable-balance posture instead of only the broad quickstart.
-
-## Adapter review walkthrough
-
-Run:
-
-```bash
-node examples/adapter_review_walkthrough.js
-```
-
-Use this when you want the neutral third-party adapter promotion and review path.