Skip to content

fix: bootstrap public discovery roots without changing node defaults #649

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ty-everett merged 1 commit into from
Sep 27, 2026
Merged

fix: bootstrap public discovery roots without changing node defaults #649

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 47 additions & 35 deletions docs/infrastructure/overlay-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
id: infra-overlay-server
title: 'Overlay Server'
kind: infra
version: '2.1.43'
last_updated: '2026-09-26'
last_verified: '2026-09-26'
version: '2.1.44'
last_updated: '2026-09-27'
last_verified: '2026-09-27'
review_cadence_days: 30
status: stable
tags: [overlay, topic-manager, lookup-service, transaction-routing]
Expand Down Expand Up @@ -75,38 +75,39 @@ None (HTTP-only OverlayExpress endpoints).

## Configuration (env vars)

| Variable | Required | Description |
| -------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| NODE_NAME | Yes | One-word, lowercase overlay service node identifier |
| SERVER_PRIVATE_KEY | Yes | 32-byte hex root private key for server wallet |
| HOSTING_URL | Yes | Public URL where the node is reachable |
| ADMIN_TOKEN | Yes | Independent random secret of at least 32 characters for admin API access |
| WALLET_STORAGE_URL | Yes | BSV wallet storage endpoint (e.g., `https://store-us-1.bsvb.tech`) |
| NETWORK | Yes | `main` or `test` (BSV blockchain network) |
| ARC_API_KEY | Conditionally | Arc key for fallback transaction broadcasting. Required only when `ARCADE_URL` is unset. |
| ARC_CALLBACK_TOKEN | No | Independent random secret of at least 32 characters expected on `/arc-ingest` callbacks |
| ARCADE_URL | Conditionally | Arcade endpoint used as the first-choice broadcaster and proof lookup provider. Required only when `ARC_API_KEY` is unset. |
| ARCADE_API_KEY | No | Arcade API key, when the deployment requires one. |
| ARCADE_DEPLOYMENT_ID | No | Stable Arcade deployment identifier used for callback/proof routing. |
| CHAINTRACKS_URL | No | Explicit go-chaintracks compatible endpoint for headers and reorg SSE. If unset, Arcade can be reused when `USE_ARCADE_CHAINTRACKS=true`. |
| CHAINTRACKS_API_PREFIX | No | Chaintracks API prefix. Defaults to `/chaintracks/v2` for Arcade-mounted Chaintracks. |
| USE_ARCADE_CHAINTRACKS | No | Reuse `ARCADE_URL` for Chaintracks when `CHAINTRACKS_URL` is unset. Defaults to true when `ARCADE_URL` is set. |
| THROW_ON_BROADCAST_FAIL | No | Reject overlay admission if no broadcast provider accepts the transaction. Defaults to `true`. |
| MONGO_URL | Yes | MongoDB connection string |
| KNEX_URL | Yes | MySQL connection string for Knex |
| GASP_ENABLED | No | `true` or `false` (Graph Aware Sync Protocol for overlay sync) |
| MANDALA_ENABLED | No | Enable the regulated Mandala topic. Defaults to `false`; see the production restriction below. |
| MANDALA_VERIFIER_PRIVATE_KEY | When enabled | Dedicated 32-byte linkage-verifier root, distinct from the node and Mandala admin roots. |
| MANDALA_ADMIN_PRIVATE_KEY | When enabled | Dedicated 32-byte administrative root, distinct from the node and verifier roots. |
| MANDALA_STATIC_DENYLIST_JSON | When enabled | Explicit bounded JSON array of compressed identity keys for reference/local screening only. |
| BASM_ENABLED | No | Enable BRC-136 BASM synchronization. Defaults to `false`. |
| BASM_REORG_STREAM_ENABLED | No | Subscribe to Chaintracks reorg SSE when Chaintracks is configured. Defaults to `true`. |
| BASM_REORG_SCAN_DEPTH | No | Number of recent blocks to revalidate on reorg reconnect/poll. |
| BASM_BLOCK_POLL_INTERVAL_MS | No | Interval for BASM anchor/header polling. Set to `0` to disable periodic polling. |
| UNPROVEN_EVICTION_BLOCKS | No | Block-age threshold for unproven transaction eviction. |
| UNPROVEN_MAINTENANCE_INTERVAL_MS | No | Periodic refresh-then-evict cadence for unproven transactions. `0` disables periodic maintenance. |
| LOG_LEVEL | No | pino log level. Defaults to `info`. |
| OTEL_* | No | OpenTelemetry exporter/resource configuration. See `infra/OBSERVABILITY.md`. |
| Variable | Required | Description |
| -------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NODE_NAME | Yes | One-word, lowercase overlay service node identifier |
| SERVER_PRIVATE_KEY | Yes | 32-byte hex root private key for server wallet |
| HOSTING_URL | Yes | Public URL where the node is reachable |
| ADMIN_TOKEN | Yes | Independent random secret of at least 32 characters for admin API access |
| WALLET_STORAGE_URL | Yes | BSV wallet storage endpoint (e.g., `https://store-us-1.bsvb.tech`) |
| NETWORK | Yes | `main`, `test` or `ttn` (BSV blockchain network) |
| ARC_API_KEY | Conditionally | Arc key for fallback transaction broadcasting. Required only when `ARCADE_URL` is unset. |
| ARC_CALLBACK_TOKEN | No | Independent random secret of at least 32 characters expected on `/arc-ingest` callbacks |
| ARCADE_URL | Conditionally | Arcade endpoint used as the first-choice broadcaster and proof lookup provider. Required only when `ARC_API_KEY` is unset. |
| ARCADE_API_KEY | No | Arcade API key, when the deployment requires one. |
| ARCADE_DEPLOYMENT_ID | No | Stable Arcade deployment identifier used for callback/proof routing. |
| CHAINTRACKS_URL | No | Explicit go-chaintracks compatible endpoint for headers and reorg SSE. If unset, Arcade can be reused when `USE_ARCADE_CHAINTRACKS=true`. |
| CHAINTRACKS_API_PREFIX | No | Chaintracks API prefix. Defaults to `/chaintracks/v2` for Arcade-mounted Chaintracks. |
| USE_ARCADE_CHAINTRACKS | No | Reuse `ARCADE_URL` for Chaintracks when `CHAINTRACKS_URL` is unset. Defaults to true when `ARCADE_URL` is set. |
| THROW_ON_BROADCAST_FAIL | No | Reject overlay admission if no broadcast provider accepts the transaction. Defaults to `true`. |
| MONGO_URL | Yes | MongoDB connection string |
| KNEX_URL | Yes | MySQL connection string for Knex |
| GASP_ENABLED | No | `true` or `false` (Graph Aware Sync Protocol for overlay sync) |
| DISCOVERY_ROOT | No | Opt in to public SHIP/SLAP root registration and self-origin advertisement bootstrap. Defaults to `false`; requires a credential-free HTTPS hosting origin. |
| MANDALA_ENABLED | No | Enable the regulated Mandala topic. Defaults to `false`; see the production restriction below. |
| MANDALA_VERIFIER_PRIVATE_KEY | When enabled | Dedicated 32-byte linkage-verifier root, distinct from the node and Mandala admin roots. |
| MANDALA_ADMIN_PRIVATE_KEY | When enabled | Dedicated 32-byte administrative root, distinct from the node and verifier roots. |
| MANDALA_STATIC_DENYLIST_JSON | When enabled | Explicit bounded JSON array of compressed identity keys for reference/local screening only. |
| BASM_ENABLED | No | Enable BRC-136 BASM synchronization. Defaults to `false`. |
| BASM_REORG_STREAM_ENABLED | No | Subscribe to Chaintracks reorg SSE when Chaintracks is configured. Defaults to `true`. |
| BASM_REORG_SCAN_DEPTH | No | Number of recent blocks to revalidate on reorg reconnect/poll. |
| BASM_BLOCK_POLL_INTERVAL_MS | No | Interval for BASM anchor/header polling. Set to `0` to disable periodic polling. |
| UNPROVEN_EVICTION_BLOCKS | No | Block-age threshold for unproven transaction eviction. |
| UNPROVEN_MAINTENANCE_INTERVAL_MS | No | Periodic refresh-then-evict cadence for unproven transactions. `0` disables periodic maintenance. |
| LOG_LEVEL | No | pino log level. Defaults to `info`. |
| OTEL_* | No | OpenTelemetry exporter/resource configuration. See `infra/OBSERVABILITY.md`. |

At least one transaction propagation provider must be configured:
`ARCADE_URL` or `ARC_API_KEY`. Production deployments should prefer
Expand Down Expand Up @@ -253,3 +254,14 @@ counts.

- [GitHub](https://github.com/bsv-blockchain/ts-stack/tree/main/infra/overlay-server)
- [npm package](https://npmjs.com/package/@bsv/overlay-express)

### Discovery-root bootstrap

Set `DISCOVERY_ROOT=true` only for an operator-designated public root. This keeps
the default discovery topics/services in advertisement synchronization and points
the advertiser's SHIP/SLAP lookups at the node's own HTTPS origin. It allows a root
with no existing `ls_ship` discovery registration to create that registration.
Normal clients keep their network presets, and ordinary deployments keep their
existing defaults. Validate both direct and default SDK SHIP/SLAP discovery,
transaction propagation and signed UHRP admission before completing promotion.
No schema or wire migration is required.
3 changes: 2 additions & 1 deletion docs/reference/service-operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ Incident handling follows this evidence-preserving sequence:
### overlay-server

- Configuration: required `HOSTING_URL`, `KNEX_URL`, `MONGO_URL`, `NETWORK`, `NODE_NAME`, `SERVER_PRIVATE_KEY`, `WALLET_STORAGE_URL`; optional
`ADMIN_TOKEN`, `ARCADE_API_KEY`, `ARCADE_DEPLOYMENT_ID`, `ARCADE_URL`, `ARC_API_KEY`, `ARC_CALLBACK_TOKEN`, `CHAINTRACKS_URL`, `GASP_ENABLED`; secret-bearing
`ADMIN_TOKEN`, `ARCADE_API_KEY`, `ARCADE_DEPLOYMENT_ID`, `ARCADE_URL`, `ARC_API_KEY`, `ARC_CALLBACK_TOKEN`, `CHAINTRACKS_URL`, `GASP_ENABLED`, `DISCOVERY_ROOT`; secret-bearing
`ADMIN_TOKEN`, `ARCADE_API_KEY`, `ARC_API_KEY`, `ARC_CALLBACK_TOKEN`, `KNEX_URL`, `MONGO_URL`, `OTEL_EXPORTER_OTLP_HEADERS`, `SERVER_PRIVATE_KEY`.
- Telemetry: ESM bootstrap
`src/telemetry.ts`, logger
Expand All @@ -180,6 +180,7 @@ Incident handling follows this evidence-preserving sequence:
- query each enabled lookup service
- ingest and classify provider callbacks
- reconcile GASP/BASM state across a reorganization
- discover SHIP/SLAP services through default SDK network presets when operating as a discovery root
- Alerts:
- readiness dependency checks fail or provider callback processing errors repeat
- unproven rows age beyond policy or maintenance repeatedly fails
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/stack-facts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ the separately released and verified image digest.
| --- | --- | --- | --- | --- | --- | --- |
| BSV Chaintracks Server | `chaintracks-server` | `1.1.24` | `>=24 <25` | node, linux/amd64 | ghcr-keyless | [infra/chaintracks-server](https://github.com/bsv-blockchain/ts-stack/tree/main/infra/chaintracks-server) |
| BSV Message Box Server | `@bsv/messagebox-server` | `1.1.47` | `>=24 <25` | node, linux/amd64 | ghcr-keyless | [infra/message-box-server](https://github.com/bsv-blockchain/ts-stack/tree/main/infra/message-box-server) |
| BSV Overlay Server | `@bsv/overlay-express-examples` | `2.1.43` | `>=24 <25` | node, linux/amd64 | ghcr-keyless | [infra/overlay-server](https://github.com/bsv-blockchain/ts-stack/tree/main/infra/overlay-server) |
| BSV Overlay Server | `@bsv/overlay-express-examples` | `2.1.44` | `>=24 <25` | node, linux/amd64 | ghcr-keyless | [infra/overlay-server](https://github.com/bsv-blockchain/ts-stack/tree/main/infra/overlay-server) |
| BSV UHRP Basic Server | `@bsv/uhrp-lite` | `0.1.43` | `>=24 <25` | node, linux/amd64 | ghcr-keyless | [infra/uhrp-server-basic](https://github.com/bsv-blockchain/ts-stack/tree/main/infra/uhrp-server-basic) |
| BSV UHRP Cloud Bucket Server | `@bsv/uhrp-storage-server` | `0.2.46` | `>=24 <25` | node, linux/amd64 | ghcr-keyless | [infra/uhrp-server-cloud-bucket](https://github.com/bsv-blockchain/ts-stack/tree/main/infra/uhrp-server-cloud-bucket) |
| Wallet Authentication Backend | `@bsv/wab-server` | `1.8.7` | `>=24 <25` | node, linux/amd64 | ghcr-and-aws-marketplace-keyless | [infra/wab](https://github.com/bsv-blockchain/ts-stack/tree/main/infra/wab) |
Expand Down
6 changes: 4 additions & 2 deletions governance/service-operations.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -251,7 +251,8 @@
"ARC_API_KEY",
"ARC_CALLBACK_TOKEN",
"CHAINTRACKS_URL",
"GASP_ENABLED"
"GASP_ENABLED",
"DISCOVERY_ROOT"
],
"secrets": [
"ADMIN_TOKEN",
Expand Down Expand Up @@ -280,7 +281,8 @@
"submit and propagate a transaction without creating local-only state",
"query each enabled lookup service",
"ingest and classify provider callbacks",
"reconcile GASP/BASM state across a reorganization"
"reconcile GASP/BASM state across a reorganization",
"discover SHIP/SLAP services through default SDK network presets when operating as a discovery root"
],
"alerts": [
"readiness dependency checks fail or provider callback processing errors repeat",
Expand Down
2 changes: 2 additions & 0 deletions infra/overlay-server/.env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ NETWORK=main
NODE_NAME=your-overlay-node
ADMIN_TOKEN=replace-with-at-least-32-random-characters
GASP_ENABLED=false
# Opt in only for a public SHIP/SLAP discovery root.
DISCOVERY_ROOT=false
# Regulated Mandala processing is disabled by default. The bundled static
# denylist adapter is for deliberate reference/local use; production code must
# inject an authoritative, continuously maintained ScreeningProvider.
Expand Down
Loading
Loading