xytara 3.1.0 → 3.1.2

package/.env.example

@@ -1,58 +1,67 @@
-XYTARA_HOST=127.0.0.1
-XYTARA_PORT=4320
-XYTARA_BASE_URL=http://127.0.0.1:4320
-XYTARA_PAYMENT_VERIFICATION_MODE=presence
-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={}
-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
-XYTARA_CREDIT_BRIDGE_BEARER_TOKEN=
-XYTARA_ACCOUNT_AUTH_BEARER_TOKEN=
-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
-XYTARA_EXTERNAL_EXECUTION_REQUIRED=false
-XYTARA_EXECUTION_TARGETS_JSON=[]
-XYTARA_L402_ENABLED=false
-XYTARA_L402_SHARED_SECRET=
-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
-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
-XYTARA_STATE_SNAPSHOT_INTERVAL_MS=5000
-XYTARA_SUPABASE_URL=
-XYTARA_SUPABASE_SERVICE_ROLE_KEY=
-XYTARA_SUPABASE_STATE_TABLE=xytara_runtime_state
-XYTARA_SUPABASE_STATE_KEY=default
+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
+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={}
+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=
+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
+XYTARA_EXTERNAL_EXECUTION_REQUIRED=false
+XYTARA_EXECUTION_TARGETS_JSON=[]
+XYTARA_L402_ENABLED=false
+XYTARA_L402_SHARED_SECRET=
+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
+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
+XYTARA_STATE_SNAPSHOT_INTERVAL_MS=5000
+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 +1,56 @@
-# 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`
+# 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/CARRIED_HANDOFF_DEMO.md

@@ -1,60 +1,60 @@
-# 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`
+# 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 +1,53 @@
-# 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.
+# 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.