From 8ee81e04c9e82080116c42fa6b7b7259c50923a7 Mon Sep 17 00:00:00 2001 From: archipelago Date: Sun, 2 Aug 2026 23:50:37 -0400 Subject: [PATCH] =?UTF-8?q?docs(roadmap):=20add=20Phase=2012=20=E2=80=94?= =?UTF-8?q?=20Bitcoin=20node=20settings,=20Core/Knots=20parity?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per the operator: every option umbrelOS surfaces must be reachable in the UI, Knots-only options surfaced separately from the ones Core shares, and network mode a setting whose DEFAULT is Tor rather than clearnet. Scoped as a phase rather than done inline because bitcoind's arguments are currently hardcoded in three places (first-boot-containers.sh, container-specs.sh, apps/bitcoin-knots/manifest.yml) — the same triplication that produced the lnd-ui HTTP 000 defect. There is nowhere for a UI to write, so BTCSET-01 is a settings model those three render FROM, not another restatement. Two constraints recorded up front so they are not discovered late: - Knots-only flags gated to Knots is a CORRECTNESS requirement — offering one on Core yields a node that refuses to start. - Several options are not freely reversible: txindex forces a reindex, prune is destructive and needs a full resync to undo. On a node that is somebody's wallet backend those must be labelled and gated, not silently applied. Any change at all restarts bitcoind, interrupting LND, electrs and the fedimint gateways. Inbound onion is explicitly out of scope: it needs Tor's ControlPort, which is deliberately disabled for security, so the node reaches .onion peers but stays unlisted. The UI must say so rather than imply otherwise. Co-Authored-By: Claude Opus 5 (1M context) --- .planning/ROADMAP.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index cad83120..5d11dce4 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -28,6 +28,7 @@ signed/decentralized registry and a user installs it on their node. - [ ] **Phase 7: Developer Tooling CLI** - `archy app validate/render/local-install/lifecycle-test` + developer guide - [ ] **Phase 8: Decentralized Marketplace** - DID-signed publish to Nostr relays, trust-tier discovery, verified third-party install end-to-end - [ ] **Phase 9: BotFights Platform Upgrade** - Native nostr signer login, one self-contained AI bot-setup prompt, shared public VPS2 match endpoint so all nodes see all fighters, registry updated +- [ ] **Phase 12: Bitcoin Node Settings & Core/Knots Parity** - Every bitcoind option reachable in the UI, Knots-only options gated to Knots, network mode a setting defaulting to Tor ## Phase Details @@ -307,3 +308,19 @@ Plans: Plans: - [ ] TBD (run /gsd-plan-phase 11 to break down) + +### Phase 12: Bitcoin Node Settings & Core/Knots Parity + +**Goal:** The Bitcoin node's configuration is something the operator chooses in the UI, not something baked into three shell scripts. Every option umbrelOS surfaces for its Bitcoin app is reachable, the options that exist **only** on Knots are surfaced separately from the ones Core shares, and the node's network mode is a first-class setting whose **default is Tor, not clearnet**. + +**Requirements**: BTCSET-01 **a single source of truth for bitcoind arguments** — today they are hardcoded and duplicated across `scripts/first-boot-containers.sh:666`, `scripts/container-specs.sh:193-202` and `apps/bitcoin-knots/manifest.yml:43`, which is the exact triplication that produced the lnd-ui bridge/host defect (`HTTP 000`, found 2026-08-02); a persisted settings model must replace it, with those three call sites rendering FROM it rather than restating it; BTCSET-02 **network mode is a setting, defaulting to Tor** — Tor / clearnet / both, wired to the archy-net SOCKS listener shipped in `f0494193` via `-onion=:9050` (onion-only) or `-proxy=` (everything), with the operator's 2026-08-02 choice of onion-only as the shipped default for the "both" mode; **inbound onion is out of scope and must be stated as such in the UI** — it needs Tor's ControlPort, deliberately disabled for security, so the node can reach .onion peers but stays unlisted; BTCSET-03 **Core options surfaced** (prune, dbcache, txindex, maxconnections, maxmempool, mempoolexpiry, persistmempool, blocksonly, peerbloomfilters, blockfilterindex, and the rest of the umbrelOS set, researched from `getumbrel/umbrel-bitcoin` rather than assumed); BTCSET-04 **Knots-only options surfaced separately and gated to Knots** (`datacarrier`, `datacarriersize`, `permitbaremultisig`, `rejectparasites`, `maxscriptsize`, the spam-filter family) — offering a Knots-only flag on Core would produce a node that refuses to start, so the gate is a correctness requirement, not a cosmetic one; BTCSET-05 house-style UI verified on the `:8100` dev preview against archi-dev before any deploy, mobile included. + +**The hazard this phase must not get wrong:** several of these options are **not freely reversible**. Turning `txindex` on forces a full reindex; turning `prune` on is destructive to block data and cannot be undone without a full resync; lowering `prune` below what is already pruned is meaningless. Any setting in that class must be labelled, confirmed, and — where it implies hours of resync on a node that is somebody's wallet backend — refused or gated rather than silently applied. Changing any option at all requires a bitcoind restart, which interrupts LND, electrs and the fedimint gateways that depend on it. + +**Depends on:** `f0494193` (the archy-net SOCKS listener) for BTCSET-02's Tor path to exist at all. Independent of Phases 1–11 otherwise. + +**Plans:** 0 plans + +Plans: + +- [ ] TBD (run /gsd-plan-phase 12 to break down)