xytara 3.1.16 → 3.2.0

package/REAL_PAYMENT_SETUP.md

@@ -1,320 +0,0 @@
-# Real Payment Setup
-
-This guide explains how to move `xytara` from local placeholder payment acceptance into a production-usable payment posture.
-
-## What Changed
-
-`xytara` supports three payment-acceptance modes. `local_signed` is the default; `presence` and `x402_facilitator` are opt-in.
-
-- `presence`
-  - 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`
-  - 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.
-
-### Self-serve credits top-up
-
-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 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, 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
-
-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`.
-
-### Going to Base mainnet (real USDC)
-
-Base Sepolia uses test USDC. To accept real value, advertise a Base mainnet profile and
-settle it through a mainnet-capable facilitator.
-
-Important: the default `https://x402.org/facilitator` settles **Base Sepolia only** (its
-`/supported` list has no `eip155:8453`). Pointing a mainnet `accepts` entry at it fails
-closed and the route is unpayable. For mainnet use a mainnet-capable facilitator, such as
-Coinbase CDP (`https://api.cdp.coinbase.com/platform/v2/x402`), which is supported natively:
-create a CDP Secret API Key (Ed25519) and set its id and secret, and the runtime mints a
-fresh short-lived CDP Bearer JWT per facilitator call (CDP rejects static tokens).
-
-```env
-# advertise mainnet (real USDC on Base); you can keep a Sepolia entry in the array too
-XYTARA_X402_ACCEPTS_JSON=[{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"10000","payTo":"<your-evm-address>","extra":{"name":"USDC","version":"2"},"maxTimeoutSeconds":60}]
-# point at the CDP-hosted facilitator and supply the CDP Secret API Key:
-XYTARA_X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
-CDP_API_KEY_ID=<your-cdp-key-id>
-CDP_API_KEY_SECRET=<your-cdp-ed25519-secret-base64>
-```
-
-The CDP key must use the **Ed25519** signature algorithm (not ECDSA). `CDP_API_KEY_ID` /
-`CDP_API_KEY_SECRET` are the CDP-standard names; `XYTARA_X402_CDP_KEY_ID` /
-`XYTARA_X402_CDP_KEY_SECRET` are accepted as overrides. `amount` is in the asset's base units
-(USDC has 6 decimals, so `10000` = 0.01 USDC). Verify the CDP auth path locally with
-`npm run verify:cdp-facilitator`. Once mainnet is live, buyers spend real USDC.
-
-## Minimum Production-Oriented Configuration
-
-Set these environment variables:
-
-```env
-XYTARA_PAYMENT_VERIFICATION_MODE=local_signed
-XYTARA_PAYMENT_MAX_AGE_SECONDS=300
-XYTARA_WALLET_REGISTRY_JSON=[{"wallet_id":"<wallet-id>","secret":"<shared-secret>","account_id":"<account-id>"}]
-XYTARA_TREASURY_DESTINATION_ID=merchant_treasury_primary
-XYTARA_TREASURY_DESTINATION_KIND=merchant_treasury
-XYTARA_TREASURY_ACCOUNT_ID=merchant-main
-XYTARA_TREASURY_EXTERNAL_REF=merchant-usd-main
-```
-
-You can also load the wallet registry and treasury map from files through:
-
-- `XYTARA_WALLET_REGISTRY_PATH`
-- `XYTARA_TREASURY_DESTINATIONS_PATH`
-
-For multi-rail treasury landings, use:
-
-- private treasury source of truth: `your private treasury source-of-truth file outside the repos`
-
-Important:
-
-- yes, for rails you actually want to receive and store value on, you should enter real receiving destinations
-- in `xytara`, that is the `external_ref` field for each rail
-- for practical purposes, `external_ref` is where the real landing address / paymail / custody account / external receiving reference goes
-
-Examples:
-
-- `bsv_teranode`
-  - BSV address or paymail
-- `evm` / `base`
-  - EVM address
-- `hedera_hbar`
-  - Hedera account id
-- `kaspa_kas`
-  - Kaspa address
-- `polkadot_dot`
-  - Polkadot address
-- `usdc` / `dai`
-  - the stablecoin receiving address on the intended chain
-- `monero`
-  - Monero address, only if you are explicitly enabling the internal optional privacy reserve
-
-Recommended file-driven setup:
-
-```env
-XYTARA_TREASURY_DESTINATIONS_PATH=./TREASURY_DESTINATIONS.production.json
-```
-
-Then upload the privately maintained treasury file from `your private treasury source-of-truth file outside the repos` as the Render secret file named `TREASURY_DESTINATIONS.production.json`, and keep only public receive destinations in it.
-
-## Fastest Live Multi-Rail Activation Path
-
-If you want the public runtime to move from readiness-only treasury breadth into stronger live-landing truth before `3.0.0`, use this exact operator sequence:
-
-1. update the private treasury source-of-truth file at `your private treasury source-of-truth file outside the repos`
-2. upload that file to Render Secret Files as `TREASURY_DESTINATIONS.production.json`
-3. set:
-
-```env
-XYTARA_TREASURY_DESTINATIONS_PATH=./TREASURY_DESTINATIONS.production.json
-```
-
-4. redeploy `xytara`
-5. verify:
-
-```text
-GET /v1/treasury-destinations/summary
-GET /v1/payment-rail-truth/summary
-GET /v1/autonomous-entry/summary
-GET /v1/business-cockpit/summary
-```
-
-You can automate that launch-truth check with:
-
-```env
-XYTARA_VERIFY_BASE_URL=https://xytara.onrender.com
-XYTARA_EXPECTED_BSV_RUNTIME_MODE=arc
-XYTARA_EXPECTED_LIVE_RAILS=bsv_teranode,evm,base,solana_payment,usdc,dai
-XYTARA_EXPECTED_READINESS_ONLY_RAILS=hedera_hbar,kaspa_kas,polkadot_dot,digibyte_dgb,constellation_dag
-```
-
-Then run:
-
-```text
-npm run verify:final-activation
-```
-
-Optional operator-depth verification:
-
-```env
-XYTARA_ACCOUNT_AUTH_BEARER_TOKEN=<operator-bearer-token>
-XYTARA_VERIFY_ACCOUNT_ID=<the same internal xytara account_id you use for live quotes/payments; usually XYTARA_TREASURY_ACCOUNT_ID>
-```
-
-What you want to see:
-
-- a healthy `GET /business-cockpit` page once operator auth is in place
-- a healthy `GET /v1/business-cockpit/summary` machine summary alongside the treasury and payment truth summaries
-
-- `public_claimable_profile_count > 0`
-- `public_live_landing_rail_count > 0`
-- the desired rail family changes from readiness-only to live claimable
-
-What must not happen:
-
-- no real `external_ref`
-- no custody ref
-- no provider ref
-
-should appear on any public surface
-
-## What This Gives You
-
-With `local_signed` enabled:
-
-- `POST /x402/commands/execute` challenges for payment
-- the client signs the exact payment payload
-- if the quote is using native `bsv_teranode`, the payment payload can also carry BSV/Teranode merchant and settlement-reference hints
-- the server verifies:
-  - wallet registration
-  - HMAC signature validity
-  - quote id
-  - amount
-  - currency
-  - settlement binding
-  - timestamp freshness
-  - nonce uniqueness
-- accepted payments are recorded into:
-  - `payment-ledger`
-  - `activity-ledger`
-  - `treasury-summary`
-  - `rail-summary`
-  - `treasury-egress-policy`
-  - `reconciliation-report`
-
-## What It Does Not Do By Itself
-
-The built-in path gives you verifiable payment acceptance and merchant treasury routing posture inside `xytara`.
-
-It does not by itself:
-
-- move fiat into a bank account
-- broadcast on-chain settlement
-- replace an external processor or custodian
-
-For actual external custody, connect `xytara` to the real rail you want behind the payment and settlement boundary.
-
-That is where:
-
-- your payment rail integration
-- your settlement integration
-- your merchant treasury destination
-
-become the actual real-world landing point for accepted funds.
-
-For native `bsv_teranode`, the runtime can now:
-
-- create settlement records automatically when payment is accepted
-- auto-submit them when settlement runtime material is available
-- auto-refresh them toward observed or confirmed state through the background runtime worker
-
-That still does not remove the need for real merchant identity, real transport, and real operator-controlled destinations.
-
-So the short operational rule is:
-
-- no, you should not leave treasury rails as abstract names only
-- yes, you should configure real landing destinations for each rail you claim is operational
-- if a rail does not yet have a real destination, keep it visible as supported architecture, but do not claim it as an active treasury landing path
-- public treasury surfaces now expose `public_claim_status`, `public_claim_allowed`, and `public_claim_boundary`; only rails with `public_claim_allowed: true` should be described as live landing paths
-- rails with `readiness_template_only`, `partial_configuration_not_public_claim`, or `fallback_not_public_multi-rail_claim` are architecture/readiness surfaces until real per-rail destinations exist
-- `internal_policy_gated_not_public` rails must stay out of public live-landing claims
-
-## Best Current Public Model
-
-Use the stack like this:
-
-- `x402` route = payment admission lane
-- `local_signed` = real verifiable acceptance posture in the public package
-- `bsv_teranode` = native first-party settlement base when you want the public stack to expose BSV/Teranode-aware payout posture
-- configured treasury destination = merchant-facing landing posture in the runtime
-- external rail / settlement integration = actual custody and payout layer
-
-If you want the native BSV continuity path specifically, continue with BSV_TERANODE_PLATFORM_DISCONTINUITY_RUNBOOK.md.
-
-All activated treasury rails now follow one centralized operator path:
-
-- maintain the real receive destinations in your private treasury source of truth outside the repos
-- expose only public-safe claim/readiness truth through `xytara`
-- verify the live activation boundary with `npm run verify:final-activation`
-
-That means the treasury activation path for `hedera_hbar`, `kaspa_kas`, `polkadot_dot`, `digibyte_dgb`, `constellation_dag`, `xpr_payment`, `metal_payment`, and `antelope_payment` is now centralized here rather than split across separate per-rail setup files.
-
-## Operator Visibility
-
-After acceptance, inspect:
-
-- `GET /v1/payment-ledger`
-- `GET /v1/activity-ledger`
-- `GET /v1/economics/accounts/:account_id/treasury-summary`
-- `GET /v1/economics/accounts/:account_id/rail-summary`
-- `GET /v1/treasury-destinations`
-- `GET /v1/treasury-destinations/operator-pack`
-- `GET /v1/treasury-egress-policy`
-- `GET /v1/reconciliation-report`
-
-These tell you what was accepted, where it was routed in the runtime model, and what still needs reconciliation against the underlying real-world rail.
-
-If `XYTARA_ACCOUNT_AUTH_BEARER_TOKEN` is configured, the operator-only routes above require that bearer token.
-
-Public/private boundary:
-
-- `GET /v1/treasury-destinations` is the safe readiness surface
-- `GET /v1/treasury-destinations/operator-pack` is where real landing refs belong
-- `GET /v1/autonomous-entry` is the compressed outside-agent view that now reflects payment breadth and public live-landing counts
-- public website and public catalog surfaces should never expose actual treasury destination refs or custody-provider refs