xytara 3.1.8 → 3.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +112 -1228
  2. package/REAL_PAYMENT_SETUP.md +313 -313
  3. package/RELEASE_NOTES.md +4 -6
  4. package/START_HERE.md +272 -272
  5. package/XT1_EXECUTION_TRUTH_STANDARD.md +1 -1
  6. package/adapters/AUTHORING_GUIDE.md +28 -28
  7. package/adapters/ONBOARDING_POSTURE.md +1 -1
  8. package/examples/generated.carried-handoff.json +3 -3
  9. package/lib/a2a_rpc.js +280 -0
  10. package/lib/account_auth.js +585 -518
  11. package/lib/agent_identity.js +162 -0
  12. package/lib/bolt_adapter.js +187 -0
  13. package/lib/bolt_payment_front.js +224 -172
  14. package/lib/checkout_processor_adapter.js +217 -0
  15. package/lib/command_flow.js +561 -411
  16. package/lib/commerce_artifacts.js +530 -503
  17. package/lib/commerce_bridge.js +274 -0
  18. package/lib/commerce_cases.js +399 -317
  19. package/lib/commerce_client.js +7694 -7687
  20. package/lib/commerce_runtime.js +322 -315
  21. package/lib/execution_dedupe.js +86 -0
  22. package/lib/external_credit_bridge.js +142 -142
  23. package/lib/external_execution_runtime.js +100 -34
  24. package/lib/http_transport.js +81 -73
  25. package/lib/l402_adapter.js +241 -0
  26. package/lib/l402_payment_front.js +265 -192
  27. package/lib/mpp_adapter.js +237 -0
  28. package/lib/payment_verification.js +52 -9
  29. package/lib/provider_network_contract.js +143 -0
  30. package/lib/provider_payout_execution.js +137 -0
  31. package/lib/provider_registry.js +666 -0
  32. package/lib/rate_limiter.js +81 -0
  33. package/lib/runtime_state_store.js +369 -354
  34. package/lib/stripe_mpp_payment_front.js +258 -158
  35. package/package.json +26 -5
  36. package/scripts/verify_a2a_rpc.js +105 -0
  37. package/scripts/verify_agent_identity.js +153 -0
  38. package/scripts/verify_bolt_adapter.js +128 -0
  39. package/scripts/verify_checkout_processor.js +109 -0
  40. package/scripts/verify_commerce_bridge.js +177 -0
  41. package/scripts/verify_execution_dedupe.js +189 -0
  42. package/scripts/verify_execution_surfacing.js +76 -0
  43. package/scripts/verify_external_execution_retry.js +140 -0
  44. package/scripts/verify_l402_adapter.js +86 -0
  45. package/scripts/verify_mpp_adapter.js +128 -0
  46. package/scripts/verify_provider_network.js +567 -0
  47. package/scripts/verify_rate_limiter.js +52 -0
  48. package/scripts/verify_refund_credit.js +106 -0
  49. package/scripts/verify_service.js +15421 -15410
  50. package/scripts/verify_settlement.js +116 -0
  51. package/scripts/verify_verify_execute_settle.js +208 -0
  52. package/server.js +684 -16
@@ -1,313 +1,313 @@
1
- # Real Payment Setup
2
-
3
- This guide explains how to move `xytara` from local placeholder payment acceptance into a production-usable payment posture.
4
-
5
- ## What Changed
6
-
7
- `xytara` supports three payment-acceptance modes. `local_signed` is the default; `presence` and `x402_facilitator` are opt-in.
8
-
9
- - `presence`
10
- - development/demo mode only, enabled with `XYTARA_PAYMENT_VERIFICATION_MODE=presence`
11
- - payment headers are required, but not cryptographically verified
12
- - the server logs a warning at startup when this mode is active
13
-
14
- - `local_signed`
15
- - the default and the production-oriented built-in mode
16
- - signed payment payloads are cryptographically verified against a configured wallet registry
17
- - quote replay and nonce replay are blocked
18
- - accepted payments are routed into your configured merchant treasury destination posture
19
-
20
- - `x402_facilitator`
21
- - trustless, on-chain, pay-per-call, the same mechanism proven live on the MCP executor
22
- - the `/x402/commands/execute` and `/x402/mcp/tools/invoke` routes return a `402` that
23
- advertises the configured `accepts` (network, asset, amount, payTo) in the
24
- `PAYMENT-REQUIRED` header; a buyer signs a gasless x402 USDC authorization (EIP-3009)
25
- - on the paid retry, a facilitator verifies the payment and settles it on-chain before any
26
- work runs; the response carries a `PAYMENT-RESPONSE` settlement receipt
27
- - fails closed: if the facilitator is unreachable or the payment does not settle, nothing runs
28
- - the buyer needs no native gas token; the facilitator broadcasts the transfer
29
- - enable with `XYTARA_PAYMENT_VERIFICATION_MODE=x402_facilitator` and the x402 env below:
30
-
31
- ```env
32
- XYTARA_PAYMENT_VERIFICATION_MODE=x402_facilitator
33
- # what buyers pay, advertised in the 402 (Base Sepolia test USDC shown):
34
- XYTARA_X402_ACCEPTS_JSON=[{"scheme":"exact","network":"eip155:84532","asset":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","amount":"1000","payTo":"<your-evm-address>","extra":{"name":"USDC","version":"2"},"maxTimeoutSeconds":60}]
35
- XYTARA_X402_FACILITATOR_URL=https://x402.org/facilitator
36
- # optional:
37
- XYTARA_X402_FACILITATOR_HEADERS_JSON={}
38
- XYTARA_X402_FACILITATOR_TIMEOUT_MS=15000
39
- XYTARA_X402_SETTLE=true
40
- ```
41
-
42
- Confirm the facilitator settles every network you advertise, and verify the mode end to end
43
- against a mock facilitator with `npm run verify:x402-facilitator`. The payment a buyer signs
44
- is identical to the one in `services/mcp-execution-target/buyer-demo/` (an EIP-3009 USDC
45
- authorization in a `PAYMENT-SIGNATURE` header); only the request body differs, since the main
46
- runtime takes a command-execute body rather than an MCP JSON-RPC call.
47
-
48
- ### Self-serve credits top-up
49
-
50
- Beyond paying per call, a buyer can convert a single x402 payment into spendable
51
- runtime credits with no operator grant, via `POST /x402/credits/topup`:
52
-
53
- - without a `PAYMENT-SIGNATURE`, it returns `402` advertising the same `accepts` plus
54
- `credits_per_topup` (how many credit units one payment buys)
55
- - with a valid payment, the facilitator settles it on-chain and the runtime mints the
56
- credits to the account, returning the grant, the new balance, and a `PAYMENT-RESPONSE`
57
- settlement receipt
58
- - credits land on `account_id` from the body, falling back to the paying wallet address
59
- - replays are idempotent: the payment nonce keys the grant, so re-sending the same settled
60
- payment never mints twice
61
-
62
- Each top-up grants `XYTARA_X402_TOPUP_UNITS` credit units (default `1000`), unless the matched
63
- `accepts` entry sets its own `extra.credits`. The route is live only in `x402_facilitator`
64
- mode with `XYTARA_X402_ACCEPTS_JSON` set, and credits persist only when runtime state
65
- persistence (`XYTARA_SUPABASE_*` or `XYTARA_STATE_FILE`) is configured. A runnable buyer is in
66
- `services/mcp-execution-target/buyer-demo/x402-credits-topup-demo.js`.
67
-
68
- ### Going to Base mainnet (real USDC)
69
-
70
- Base Sepolia uses test USDC. To accept real value, advertise a Base mainnet profile and
71
- settle it through a mainnet-capable facilitator.
72
-
73
- Important: the default `https://x402.org/facilitator` settles **Base Sepolia only** (its
74
- `/supported` list has no `eip155:8453`). Pointing a mainnet `accepts` entry at it fails
75
- closed and the route is unpayable. For mainnet use a mainnet-capable facilitator, such as
76
- Coinbase CDP (`https://api.cdp.coinbase.com/platform/v2/x402`), which is supported natively:
77
- create a CDP Secret API Key (Ed25519) and set its id and secret, and the runtime mints a
78
- fresh short-lived CDP Bearer JWT per facilitator call (CDP rejects static tokens).
79
-
80
- ```env
81
- # advertise mainnet (real USDC on Base); you can keep a Sepolia entry in the array too
82
- XYTARA_X402_ACCEPTS_JSON=[{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"10000","payTo":"<your-evm-address>","extra":{"name":"USDC","version":"2"},"maxTimeoutSeconds":60}]
83
- # point at the CDP-hosted facilitator and supply the CDP Secret API Key:
84
- XYTARA_X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
85
- CDP_API_KEY_ID=<your-cdp-key-id>
86
- CDP_API_KEY_SECRET=<your-cdp-ed25519-secret-base64>
87
- ```
88
-
89
- The CDP key must use the **Ed25519** signature algorithm (not ECDSA). `CDP_API_KEY_ID` /
90
- `CDP_API_KEY_SECRET` are the CDP-standard names; `XYTARA_X402_CDP_KEY_ID` /
91
- `XYTARA_X402_CDP_KEY_SECRET` are accepted as overrides. `amount` is in the asset's base units
92
- (USDC has 6 decimals, so `10000` = 0.01 USDC). Verify the CDP auth path locally with
93
- `npm run verify:cdp-facilitator`. Once mainnet is live, buyers spend real USDC.
94
-
95
- ## Minimum Production-Oriented Configuration
96
-
97
- Set these environment variables:
98
-
99
- ```env
100
- XYTARA_PAYMENT_VERIFICATION_MODE=local_signed
101
- XYTARA_PAYMENT_MAX_AGE_SECONDS=300
102
- XYTARA_WALLET_REGISTRY_JSON=[{"wallet_id":"<wallet-id>","secret":"<shared-secret>","account_id":"<account-id>"}]
103
- XYTARA_TREASURY_DESTINATION_ID=merchant_treasury_primary
104
- XYTARA_TREASURY_DESTINATION_KIND=merchant_treasury
105
- XYTARA_TREASURY_ACCOUNT_ID=merchant-main
106
- XYTARA_TREASURY_EXTERNAL_REF=merchant-usd-main
107
- ```
108
-
109
- You can also load the wallet registry and treasury map from files through:
110
-
111
- - `XYTARA_WALLET_REGISTRY_PATH`
112
- - `XYTARA_TREASURY_DESTINATIONS_PATH`
113
-
114
- For multi-rail treasury landings, use:
115
-
116
- - private treasury source of truth: `your private treasury source-of-truth file outside the repos`
117
-
118
- Important:
119
-
120
- - yes, for rails you actually want to receive and store value on, you should enter real receiving destinations
121
- - in `xytara`, that is the `external_ref` field for each rail
122
- - for practical purposes, `external_ref` is where the real landing address / paymail / custody account / external receiving reference goes
123
-
124
- Examples:
125
-
126
- - `bsv_teranode`
127
- - BSV address or paymail
128
- - `evm` / `base`
129
- - EVM address
130
- - `hedera_hbar`
131
- - Hedera account id
132
- - `kaspa_kas`
133
- - Kaspa address
134
- - `polkadot_dot`
135
- - Polkadot address
136
- - `usdc` / `dai`
137
- - the stablecoin receiving address on the intended chain
138
- - `monero`
139
- - Monero address, only if you are explicitly enabling the internal optional privacy reserve
140
-
141
- Recommended file-driven setup:
142
-
143
- ```env
144
- XYTARA_TREASURY_DESTINATIONS_PATH=./TREASURY_DESTINATIONS.production.json
145
- ```
146
-
147
- 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.
148
-
149
- ## Fastest Live Multi-Rail Activation Path
150
-
151
- 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:
152
-
153
- 1. update the private treasury source-of-truth file at `your private treasury source-of-truth file outside the repos`
154
- 2. upload that file to Render Secret Files as `TREASURY_DESTINATIONS.production.json`
155
- 3. set:
156
-
157
- ```env
158
- XYTARA_TREASURY_DESTINATIONS_PATH=./TREASURY_DESTINATIONS.production.json
159
- ```
160
-
161
- 4. redeploy `xytara`
162
- 5. verify:
163
-
164
- ```text
165
- GET /v1/treasury-destinations/summary
166
- GET /v1/payment-rail-truth/summary
167
- GET /v1/autonomous-entry/summary
168
- GET /v1/business-cockpit/summary
169
- ```
170
-
171
- You can automate that launch-truth check with:
172
-
173
- ```env
174
- XYTARA_VERIFY_BASE_URL=https://xytara.onrender.com
175
- XYTARA_EXPECTED_BSV_RUNTIME_MODE=arc
176
- XYTARA_EXPECTED_LIVE_RAILS=bsv_teranode,evm,base,solana_payment,usdc,dai
177
- XYTARA_EXPECTED_READINESS_ONLY_RAILS=hedera_hbar,kaspa_kas,polkadot_dot,digibyte_dgb,constellation_dag
178
- ```
179
-
180
- Then run:
181
-
182
- ```text
183
- npm run verify:final-activation
184
- ```
185
-
186
- Optional operator-depth verification:
187
-
188
- ```env
189
- XYTARA_ACCOUNT_AUTH_BEARER_TOKEN=<operator-bearer-token>
190
- XYTARA_VERIFY_ACCOUNT_ID=<the same internal xytara account_id you use for live quotes/payments; usually XYTARA_TREASURY_ACCOUNT_ID>
191
- ```
192
-
193
- What you want to see:
194
-
195
- - a healthy `GET /business-cockpit` page once operator auth is in place
196
- - a healthy `GET /v1/business-cockpit/summary` machine summary alongside the treasury and payment truth summaries
197
-
198
- - `public_claimable_profile_count > 0`
199
- - `public_live_landing_rail_count > 0`
200
- - the desired rail family changes from readiness-only to live claimable
201
-
202
- What must not happen:
203
-
204
- - no real `external_ref`
205
- - no custody ref
206
- - no provider ref
207
-
208
- should appear on any public surface
209
-
210
- ## What This Gives You
211
-
212
- With `local_signed` enabled:
213
-
214
- - `POST /x402/commands/execute` challenges for payment
215
- - the client signs the exact payment payload
216
- - if the quote is using native `bsv_teranode`, the payment payload can also carry BSV/Teranode merchant and settlement-reference hints
217
- - the server verifies:
218
- - wallet registration
219
- - HMAC signature validity
220
- - quote id
221
- - amount
222
- - currency
223
- - settlement binding
224
- - timestamp freshness
225
- - nonce uniqueness
226
- - accepted payments are recorded into:
227
- - `payment-ledger`
228
- - `activity-ledger`
229
- - `treasury-summary`
230
- - `rail-summary`
231
- - `treasury-egress-policy`
232
- - `reconciliation-report`
233
-
234
- ## What It Does Not Do By Itself
235
-
236
- The built-in path gives you verifiable payment acceptance and merchant treasury routing posture inside `xytara`.
237
-
238
- It does not by itself:
239
-
240
- - move fiat into a bank account
241
- - broadcast on-chain settlement
242
- - replace an external processor or custodian
243
-
244
- For actual external custody, connect `xytara` to the real rail you want behind the payment and settlement boundary.
245
-
246
- That is where:
247
-
248
- - your payment rail integration
249
- - your settlement integration
250
- - your merchant treasury destination
251
-
252
- become the actual real-world landing point for accepted funds.
253
-
254
- For native `bsv_teranode`, the runtime can now:
255
-
256
- - create settlement records automatically when payment is accepted
257
- - auto-submit them when settlement runtime material is available
258
- - auto-refresh them toward observed or confirmed state through the background runtime worker
259
-
260
- That still does not remove the need for real merchant identity, real transport, and real operator-controlled destinations.
261
-
262
- So the short operational rule is:
263
-
264
- - no, you should not leave treasury rails as abstract names only
265
- - yes, you should configure real landing destinations for each rail you claim is operational
266
- - 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
267
- - 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
268
- - 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
269
- - `internal_policy_gated_not_public` rails must stay out of public live-landing claims
270
-
271
- ## Best Current Public Model
272
-
273
- Use the stack like this:
274
-
275
- - `x402` route = payment admission lane
276
- - `local_signed` = real verifiable acceptance posture in the public package
277
- - `bsv_teranode` = native first-party settlement base when you want the public stack to expose BSV/Teranode-aware payout posture
278
- - configured treasury destination = merchant-facing landing posture in the runtime
279
- - external rail / settlement integration = actual custody and payout layer
280
-
281
- If you want the native BSV continuity path specifically, continue with [BSV_TERANODE_PLATFORM_DISCONTINUITY_RUNBOOK.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/BSV_TERANODE_PLATFORM_DISCONTINUITY_RUNBOOK.md).
282
-
283
- All activated treasury rails now follow one centralized operator path:
284
-
285
- - maintain the real receive destinations in your private treasury source of truth outside the repos
286
- - expose only public-safe claim/readiness truth through `xytara`
287
- - verify the live activation boundary with `npm run verify:final-activation`
288
-
289
- 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.
290
-
291
- ## Operator Visibility
292
-
293
- After acceptance, inspect:
294
-
295
- - `GET /v1/payment-ledger`
296
- - `GET /v1/activity-ledger`
297
- - `GET /v1/economics/accounts/:account_id/treasury-summary`
298
- - `GET /v1/economics/accounts/:account_id/rail-summary`
299
- - `GET /v1/treasury-destinations`
300
- - `GET /v1/treasury-destinations/operator-pack`
301
- - `GET /v1/treasury-egress-policy`
302
- - `GET /v1/reconciliation-report`
303
-
304
- 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.
305
-
306
- If `XYTARA_ACCOUNT_AUTH_BEARER_TOKEN` is configured, the operator-only routes above require that bearer token.
307
-
308
- Public/private boundary:
309
-
310
- - `GET /v1/treasury-destinations` is the safe readiness surface
311
- - `GET /v1/treasury-destinations/operator-pack` is where real landing refs belong
312
- - `GET /v1/autonomous-entry` is the compressed outside-agent view that now reflects payment breadth and public live-landing counts
313
- - public website and public catalog surfaces should never expose actual treasury destination refs or custody-provider refs
1
+ # Real Payment Setup
2
+
3
+ This guide explains how to move `xytara` from local placeholder payment acceptance into a production-usable payment posture.
4
+
5
+ ## What Changed
6
+
7
+ `xytara` supports three payment-acceptance modes. `local_signed` is the default; `presence` and `x402_facilitator` are opt-in.
8
+
9
+ - `presence`
10
+ - development/demo mode only, enabled with `XYTARA_PAYMENT_VERIFICATION_MODE=presence`
11
+ - payment headers are required, but not cryptographically verified
12
+ - the server logs a warning at startup when this mode is active
13
+
14
+ - `local_signed`
15
+ - the default and the production-oriented built-in mode
16
+ - signed payment payloads are cryptographically verified against a configured wallet registry
17
+ - quote replay and nonce replay are blocked
18
+ - accepted payments are routed into your configured merchant treasury destination posture
19
+
20
+ - `x402_facilitator`
21
+ - trustless, on-chain, pay-per-call, the same mechanism proven live on the MCP executor
22
+ - the `/x402/commands/execute` and `/x402/mcp/tools/invoke` routes return a `402` that
23
+ advertises the configured `accepts` (network, asset, amount, payTo) in the
24
+ `PAYMENT-REQUIRED` header; a buyer signs a gasless x402 USDC authorization (EIP-3009)
25
+ - on the paid retry, a facilitator verifies the payment and settles it on-chain before any
26
+ work runs; the response carries a `PAYMENT-RESPONSE` settlement receipt
27
+ - fails closed: if the facilitator is unreachable or the payment does not settle, nothing runs
28
+ - the buyer needs no native gas token; the facilitator broadcasts the transfer
29
+ - enable with `XYTARA_PAYMENT_VERIFICATION_MODE=x402_facilitator` and the x402 env below:
30
+
31
+ ```env
32
+ XYTARA_PAYMENT_VERIFICATION_MODE=x402_facilitator
33
+ # what buyers pay, advertised in the 402 (Base Sepolia test USDC shown):
34
+ XYTARA_X402_ACCEPTS_JSON=[{"scheme":"exact","network":"eip155:84532","asset":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","amount":"1000","payTo":"<your-evm-address>","extra":{"name":"USDC","version":"2"},"maxTimeoutSeconds":60}]
35
+ XYTARA_X402_FACILITATOR_URL=https://x402.org/facilitator
36
+ # optional:
37
+ XYTARA_X402_FACILITATOR_HEADERS_JSON={}
38
+ XYTARA_X402_FACILITATOR_TIMEOUT_MS=15000
39
+ XYTARA_X402_SETTLE=true
40
+ ```
41
+
42
+ Confirm the facilitator settles every network you advertise, and verify the mode end to end
43
+ against a mock facilitator with `npm run verify:x402-facilitator`. The payment a buyer signs
44
+ is identical to the one in `services/mcp-execution-target/buyer-demo/` (an EIP-3009 USDC
45
+ authorization in a `PAYMENT-SIGNATURE` header); only the request body differs, since the main
46
+ runtime takes a command-execute body rather than an MCP JSON-RPC call.
47
+
48
+ ### Self-serve credits top-up
49
+
50
+ Beyond paying per call, a buyer can convert a single x402 payment into spendable
51
+ runtime credits with no operator grant, via `POST /x402/credits/topup`:
52
+
53
+ - without a `PAYMENT-SIGNATURE`, it returns `402` advertising the same `accepts` plus
54
+ `credits_per_topup` (how many credit units one payment buys)
55
+ - with a valid payment, the facilitator settles it on-chain and the runtime mints the
56
+ credits to the account, returning the grant, the new balance, and a `PAYMENT-RESPONSE`
57
+ settlement receipt
58
+ - credits land on `account_id` from the body, falling back to the paying wallet address
59
+ - replays are idempotent: the payment nonce keys the grant, so re-sending the same settled
60
+ payment never mints twice
61
+
62
+ Each top-up grants `XYTARA_X402_TOPUP_UNITS` credit units (default `1000`), unless the matched
63
+ `accepts` entry sets its own `extra.credits`. The route is live only in `x402_facilitator`
64
+ mode with `XYTARA_X402_ACCEPTS_JSON` set, and credits persist only when runtime state
65
+ persistence (`XYTARA_SUPABASE_*` or `XYTARA_STATE_FILE`) is configured. A runnable buyer is in
66
+ `services/mcp-execution-target/buyer-demo/x402-credits-topup-demo.js`.
67
+
68
+ ### Going to Base mainnet (real USDC)
69
+
70
+ Base Sepolia uses test USDC. To accept real value, advertise a Base mainnet profile and
71
+ settle it through a mainnet-capable facilitator.
72
+
73
+ Important: the default `https://x402.org/facilitator` settles **Base Sepolia only** (its
74
+ `/supported` list has no `eip155:8453`). Pointing a mainnet `accepts` entry at it fails
75
+ closed and the route is unpayable. For mainnet use a mainnet-capable facilitator, such as
76
+ Coinbase CDP (`https://api.cdp.coinbase.com/platform/v2/x402`), which is supported natively:
77
+ create a CDP Secret API Key (Ed25519) and set its id and secret, and the runtime mints a
78
+ fresh short-lived CDP Bearer JWT per facilitator call (CDP rejects static tokens).
79
+
80
+ ```env
81
+ # advertise mainnet (real USDC on Base); you can keep a Sepolia entry in the array too
82
+ XYTARA_X402_ACCEPTS_JSON=[{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"10000","payTo":"<your-evm-address>","extra":{"name":"USDC","version":"2"},"maxTimeoutSeconds":60}]
83
+ # point at the CDP-hosted facilitator and supply the CDP Secret API Key:
84
+ XYTARA_X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
85
+ CDP_API_KEY_ID=<your-cdp-key-id>
86
+ CDP_API_KEY_SECRET=<your-cdp-ed25519-secret-base64>
87
+ ```
88
+
89
+ The CDP key must use the **Ed25519** signature algorithm (not ECDSA). `CDP_API_KEY_ID` /
90
+ `CDP_API_KEY_SECRET` are the CDP-standard names; `XYTARA_X402_CDP_KEY_ID` /
91
+ `XYTARA_X402_CDP_KEY_SECRET` are accepted as overrides. `amount` is in the asset's base units
92
+ (USDC has 6 decimals, so `10000` = 0.01 USDC). Verify the CDP auth path locally with
93
+ `npm run verify:cdp-facilitator`. Once mainnet is live, buyers spend real USDC.
94
+
95
+ ## Minimum Production-Oriented Configuration
96
+
97
+ Set these environment variables:
98
+
99
+ ```env
100
+ XYTARA_PAYMENT_VERIFICATION_MODE=local_signed
101
+ XYTARA_PAYMENT_MAX_AGE_SECONDS=300
102
+ XYTARA_WALLET_REGISTRY_JSON=[{"wallet_id":"<wallet-id>","secret":"<shared-secret>","account_id":"<account-id>"}]
103
+ XYTARA_TREASURY_DESTINATION_ID=merchant_treasury_primary
104
+ XYTARA_TREASURY_DESTINATION_KIND=merchant_treasury
105
+ XYTARA_TREASURY_ACCOUNT_ID=merchant-main
106
+ XYTARA_TREASURY_EXTERNAL_REF=merchant-usd-main
107
+ ```
108
+
109
+ You can also load the wallet registry and treasury map from files through:
110
+
111
+ - `XYTARA_WALLET_REGISTRY_PATH`
112
+ - `XYTARA_TREASURY_DESTINATIONS_PATH`
113
+
114
+ For multi-rail treasury landings, use:
115
+
116
+ - private treasury source of truth: `your private treasury source-of-truth file outside the repos`
117
+
118
+ Important:
119
+
120
+ - yes, for rails you actually want to receive and store value on, you should enter real receiving destinations
121
+ - in `xytara`, that is the `external_ref` field for each rail
122
+ - for practical purposes, `external_ref` is where the real landing address / paymail / custody account / external receiving reference goes
123
+
124
+ Examples:
125
+
126
+ - `bsv_teranode`
127
+ - BSV address or paymail
128
+ - `evm` / `base`
129
+ - EVM address
130
+ - `hedera_hbar`
131
+ - Hedera account id
132
+ - `kaspa_kas`
133
+ - Kaspa address
134
+ - `polkadot_dot`
135
+ - Polkadot address
136
+ - `usdc` / `dai`
137
+ - the stablecoin receiving address on the intended chain
138
+ - `monero`
139
+ - Monero address, only if you are explicitly enabling the internal optional privacy reserve
140
+
141
+ Recommended file-driven setup:
142
+
143
+ ```env
144
+ XYTARA_TREASURY_DESTINATIONS_PATH=./TREASURY_DESTINATIONS.production.json
145
+ ```
146
+
147
+ 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.
148
+
149
+ ## Fastest Live Multi-Rail Activation Path
150
+
151
+ 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:
152
+
153
+ 1. update the private treasury source-of-truth file at `your private treasury source-of-truth file outside the repos`
154
+ 2. upload that file to Render Secret Files as `TREASURY_DESTINATIONS.production.json`
155
+ 3. set:
156
+
157
+ ```env
158
+ XYTARA_TREASURY_DESTINATIONS_PATH=./TREASURY_DESTINATIONS.production.json
159
+ ```
160
+
161
+ 4. redeploy `xytara`
162
+ 5. verify:
163
+
164
+ ```text
165
+ GET /v1/treasury-destinations/summary
166
+ GET /v1/payment-rail-truth/summary
167
+ GET /v1/autonomous-entry/summary
168
+ GET /v1/business-cockpit/summary
169
+ ```
170
+
171
+ You can automate that launch-truth check with:
172
+
173
+ ```env
174
+ XYTARA_VERIFY_BASE_URL=https://xytara.onrender.com
175
+ XYTARA_EXPECTED_BSV_RUNTIME_MODE=arc
176
+ XYTARA_EXPECTED_LIVE_RAILS=bsv_teranode,evm,base,solana_payment,usdc,dai
177
+ XYTARA_EXPECTED_READINESS_ONLY_RAILS=hedera_hbar,kaspa_kas,polkadot_dot,digibyte_dgb,constellation_dag
178
+ ```
179
+
180
+ Then run:
181
+
182
+ ```text
183
+ npm run verify:final-activation
184
+ ```
185
+
186
+ Optional operator-depth verification:
187
+
188
+ ```env
189
+ XYTARA_ACCOUNT_AUTH_BEARER_TOKEN=<operator-bearer-token>
190
+ XYTARA_VERIFY_ACCOUNT_ID=<the same internal xytara account_id you use for live quotes/payments; usually XYTARA_TREASURY_ACCOUNT_ID>
191
+ ```
192
+
193
+ What you want to see:
194
+
195
+ - a healthy `GET /business-cockpit` page once operator auth is in place
196
+ - a healthy `GET /v1/business-cockpit/summary` machine summary alongside the treasury and payment truth summaries
197
+
198
+ - `public_claimable_profile_count > 0`
199
+ - `public_live_landing_rail_count > 0`
200
+ - the desired rail family changes from readiness-only to live claimable
201
+
202
+ What must not happen:
203
+
204
+ - no real `external_ref`
205
+ - no custody ref
206
+ - no provider ref
207
+
208
+ should appear on any public surface
209
+
210
+ ## What This Gives You
211
+
212
+ With `local_signed` enabled:
213
+
214
+ - `POST /x402/commands/execute` challenges for payment
215
+ - the client signs the exact payment payload
216
+ - if the quote is using native `bsv_teranode`, the payment payload can also carry BSV/Teranode merchant and settlement-reference hints
217
+ - the server verifies:
218
+ - wallet registration
219
+ - HMAC signature validity
220
+ - quote id
221
+ - amount
222
+ - currency
223
+ - settlement binding
224
+ - timestamp freshness
225
+ - nonce uniqueness
226
+ - accepted payments are recorded into:
227
+ - `payment-ledger`
228
+ - `activity-ledger`
229
+ - `treasury-summary`
230
+ - `rail-summary`
231
+ - `treasury-egress-policy`
232
+ - `reconciliation-report`
233
+
234
+ ## What It Does Not Do By Itself
235
+
236
+ The built-in path gives you verifiable payment acceptance and merchant treasury routing posture inside `xytara`.
237
+
238
+ It does not by itself:
239
+
240
+ - move fiat into a bank account
241
+ - broadcast on-chain settlement
242
+ - replace an external processor or custodian
243
+
244
+ For actual external custody, connect `xytara` to the real rail you want behind the payment and settlement boundary.
245
+
246
+ That is where:
247
+
248
+ - your payment rail integration
249
+ - your settlement integration
250
+ - your merchant treasury destination
251
+
252
+ become the actual real-world landing point for accepted funds.
253
+
254
+ For native `bsv_teranode`, the runtime can now:
255
+
256
+ - create settlement records automatically when payment is accepted
257
+ - auto-submit them when settlement runtime material is available
258
+ - auto-refresh them toward observed or confirmed state through the background runtime worker
259
+
260
+ That still does not remove the need for real merchant identity, real transport, and real operator-controlled destinations.
261
+
262
+ So the short operational rule is:
263
+
264
+ - no, you should not leave treasury rails as abstract names only
265
+ - yes, you should configure real landing destinations for each rail you claim is operational
266
+ - 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
267
+ - 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
268
+ - 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
269
+ - `internal_policy_gated_not_public` rails must stay out of public live-landing claims
270
+
271
+ ## Best Current Public Model
272
+
273
+ Use the stack like this:
274
+
275
+ - `x402` route = payment admission lane
276
+ - `local_signed` = real verifiable acceptance posture in the public package
277
+ - `bsv_teranode` = native first-party settlement base when you want the public stack to expose BSV/Teranode-aware payout posture
278
+ - configured treasury destination = merchant-facing landing posture in the runtime
279
+ - external rail / settlement integration = actual custody and payout layer
280
+
281
+ If you want the native BSV continuity path specifically, continue with BSV_TERANODE_PLATFORM_DISCONTINUITY_RUNBOOK.md.
282
+
283
+ All activated treasury rails now follow one centralized operator path:
284
+
285
+ - maintain the real receive destinations in your private treasury source of truth outside the repos
286
+ - expose only public-safe claim/readiness truth through `xytara`
287
+ - verify the live activation boundary with `npm run verify:final-activation`
288
+
289
+ 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.
290
+
291
+ ## Operator Visibility
292
+
293
+ After acceptance, inspect:
294
+
295
+ - `GET /v1/payment-ledger`
296
+ - `GET /v1/activity-ledger`
297
+ - `GET /v1/economics/accounts/:account_id/treasury-summary`
298
+ - `GET /v1/economics/accounts/:account_id/rail-summary`
299
+ - `GET /v1/treasury-destinations`
300
+ - `GET /v1/treasury-destinations/operator-pack`
301
+ - `GET /v1/treasury-egress-policy`
302
+ - `GET /v1/reconciliation-report`
303
+
304
+ 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.
305
+
306
+ If `XYTARA_ACCOUNT_AUTH_BEARER_TOKEN` is configured, the operator-only routes above require that bearer token.
307
+
308
+ Public/private boundary:
309
+
310
+ - `GET /v1/treasury-destinations` is the safe readiness surface
311
+ - `GET /v1/treasury-destinations/operator-pack` is where real landing refs belong
312
+ - `GET /v1/autonomous-entry` is the compressed outside-agent view that now reflects payment breadth and public live-landing counts
313
+ - public website and public catalog surfaces should never expose actual treasury destination refs or custody-provider refs
package/RELEASE_NOTES.md CHANGED
@@ -1,9 +1,7 @@
1
- `xytara` 3.1.8 refreshes the public MCP executor's machine-readable description so it leads with its pay-per-call story.
2
-
3
- The server card and discovery surfaces previously described the executor as a generic tool list ("summaries, DNS lookup, catalog, replies, and JSON checks"). They now lead with what matters to an agent: pay-per-call MCP tools settled with x402 (USDC on Base mainnet). This improves how the executor is presented wherever its card is pulled — the MCP registry, Glama, x402scan, and any discovery-aware agent.
1
+ `xytara` 3.1.10 adds a free-tier cold-start ride-out and a reference payout signer, and refreshes the public collateral.
4
2
 
5
3
  Highlights:
6
4
 
7
- - the executor's `server.json`, served server card, and 402 discovery description now read "Pay-per-call MCP tools for agents, settled with x402 (USDC on Base mainnet). No API keys."
8
- - bumps the MCP executor to 3.1.8; the release workflow republishes it to the official MCP registry with the new description, which Glama then syncs
9
- - no change to tools, payment, settlement, or any route
5
+ - **Cold-start ride-out** — external execution now retries only not-processed signals (408/429/503 and connection-refused) within the x402 settlement window, so a cold free-tier provider warms up mid-retry instead of failing an unsettled call. No always-on keepalive is required. An ambiguous timeout or reset is never retried, so there is no double-execution.
6
+ - **Reference payout signer** (`services/payout-signer`) — a separately-deployed service that sends provider payouts on Base while the runtime stays key-less. Fail-closed and double-pay-safe, with an optional durable (Supabase) idempotency store so a free-tier restart cannot cause a re-send.
7
+ - Refreshed README and package metadata to lead with the proven, mainnet-demonstrated capabilities.