docs: current-state the bitcoin multi-version design; move its rollout handoff local
bitcoin-multi-version-design.md carried three layers of stale internal content: an 80-line HTML-comment work-tracking block (per-phase status with "UNCOMMITTED on the branch", node numbers, "Next action when resuming", "Decisions still needed from user"); a rendered "Status: design (2026-06-22)" header that was wrong — the feature shipped, all four phases, with the downgrade guard added today; two private `MEMORY →` references; and a node-numbered scheduling note. Now: the comment block is gone, the status reflects reality, the MEMORY references and node numbers are removed, and "verify on a real node" replaced the specific fleet addresses. The design content (source-of-truth decision, phase designs, invariants) is unchanged. Separately, bitcoin-version-bulletproof-rollout.md was an inter-agent rollout handoff — node numbers, branch coordination, "the other agent owns" — not a design or reference doc. Moved to local-only (still on disk, gitignored) like the other handoffs; its two path references (a plan doc and a script comment) are generalized. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
archipelago
co-authored by
Claude Opus 5
Claude Opus 5
parent
b4e4189407
commit
a2efdf7358
@@ -1,91 +1,7 @@
|
||||
# Bitcoin Multi-Version Support — Design
|
||||
|
||||
<!-- ════════════════════════════════════════════════════════════════════
|
||||
PROGRESS TRACKER / RESUME POINT (keep this current — update each session)
|
||||
════════════════════════════════════════════════════════════════════
|
||||
**Branch/worktree:** `bitcoin-multi-version` @ `/home/archipelago/Projects/archy-btcver`
|
||||
(isolated — never touch `main` or the other agent's branch). All work UNCOMMITTED on
|
||||
that branch as of last update.
|
||||
|
||||
**Last updated:** 2026-06-28 (session 2 — software end-to-end implemented)
|
||||
|
||||
**Motivation refresh:** BIP-110 signalling makes per-node version *choice* a real
|
||||
requirement — runners must be able to pick / pin / switch Core & Knots versions.
|
||||
|
||||
**User direction this session:** finish the SOFTWARE end-to-end (Phase 1–3 + UI),
|
||||
DEFER the Phase 0 image build pipeline. Downgrade policy = **warn + confirm + allow**.
|
||||
|
||||
### Status by phase
|
||||
- [x] **Phase 1 — catalog schema** (`app_catalog.rs`): `CatalogVersion` struct +
|
||||
`versions[]` + `catalog_versions()` / `catalog_default_version()` /
|
||||
`catalog_image_for_version()` (same-repo guard) DONE. Pin suppresses update badge
|
||||
in `available_update_for_app()` DONE. `versions[]` now EMITTED by
|
||||
`scripts/generate-app-catalog.sh` (curated `VERSIONS` map) → `releases/app-catalog.json`
|
||||
regenerated; bitcoin-core carries its one built version (28.4.0, default). **Knots
|
||||
versions[] intentionally empty** (only floating `:latest` exists; design forbids
|
||||
advertising floating). More versions light up automatically once Phase 0 builds
|
||||
tagged images and they're appended to the `VERSIONS` map.
|
||||
- [x] **Phase 2 — install-time selection**: `version_config.rs` (pin/auto-update
|
||||
persistence + `is_downgrade()` + `auto_update_apps()`, unit-tested) DONE;
|
||||
`install.rs` `persist_install_version_selection()` DONE; `prod_orchestrator.rs`
|
||||
pinned-wins resolution DONE. **UI:** `MarketplaceAppDetails.vue` install panel shows
|
||||
a version `<select>` (latest pre-selected) when the app offers ≥2 versions — passes
|
||||
the choice to `package.install`. (Hidden today since only 1 version exists.)
|
||||
- [x] **Phase 3 — in-app switch + auto-update toggle**:
|
||||
- `package.versions` RPC (read) + `package.set-config` RPC (write, downgrade-gated)
|
||||
→ new `api/rpc/package/set_config.rs`, wired in `mod.rs` + `dispatcher.rs`.
|
||||
- Auto-update tick: `run_update_scheduler` now takes the orchestrator + calls
|
||||
`apply_per_app_auto_updates()` hourly (opt-in, pin-respecting, catalog-driven).
|
||||
- UI: "Version & Updates" card in `appDetails/AppSidebar.vue` (version switch +
|
||||
auto-update toggle + downgrade warn/confirm); `rpc-client.ts` + types added.
|
||||
- [x] **Phase 0 — image build pipeline**: `scripts/build-bitcoin-image.sh` —
|
||||
downloads the OFFICIAL upstream tarball + SHA256SUMS(.asc), verifies SHA-256 **and**
|
||||
the OpenPGP signature (fail-closed; pinned release-key fingerprints), builds a
|
||||
minimal **rootless** image (debian-slim + verified `bitcoind`/`bitcoin-cli`),
|
||||
smoke-tests `--version`, tags + pushes `:<version>`. Validated on Core 31.0
|
||||
(pinned-GPG pass, smoke `v31.0.0`). **Published curated set** (registry
|
||||
`lfg2025`): Core **31.0, 30.2, 29.3, 27.2, 26.2, 25.2** (28.4 already present —
|
||||
kept, not overwritten) + Knots **29.3.knots20260508**. `VERSIONS` map in
|
||||
`generate-app-catalog.sh` lists them; catalog regenerated. Adding a future release
|
||||
= run the script for it, then prepend it to the map + regenerate.
|
||||
|
||||
### Verification status
|
||||
- `cargo check -p archipelago` GREEN (backend). Frontend `npm run build` GREEN
|
||||
(vue-tsc typecheck passes; new RPC strings confirmed in `web/dist`).
|
||||
- Unit tests: `version_config` had a pre-existing parallel-test race (shared
|
||||
process-global `ARCHIPELAGO_DATA_DIR`) — FIXED with an `ENV_LOCK` mutex + unique
|
||||
per-test dirs. `set_config` `image_tag` test added.
|
||||
- **Phase 0 images verified end-to-end**: SHA-256 + pinned-maintainer OpenPGP
|
||||
signature (deterministic VALIDSIG check), built rootless, smoke-tested, **pushed
|
||||
to the live registry** — confirmed remotely: `bitcoin` tags
|
||||
{25.2,26.2,27.2,28.4,29.3,30.2,31.0} + `bitcoin-knots:29.3.knots20260508`.
|
||||
- **NOT yet verified on `.228`** (CLAUDE.md invariant — do before any tag): install
|
||||
bitcoin-core, open its page, switch/pin a version, confirm recreate. All code
|
||||
UNCOMMITTED on the branch.
|
||||
|
||||
### Gotchas captured (for resume)
|
||||
- `gpg --verify` exit code is unreliable on multi-sig `SHA256SUMS` — must parse
|
||||
`--status-fd` VALIDSIG and require a pinned maintainer fpr (script does this).
|
||||
- `podman push` needs the sandbox disabled (`/var/tmp` is RO under the harness
|
||||
sandbox) and `--tls-verify=false` (registry serves HTTP). Persistent keyring
|
||||
(`BITCOIN_KEYRING_DIR`) avoids flaky per-build keyserver fetches.
|
||||
|
||||
### Next action when resuming
|
||||
1. Re-verify: `cd archy-btcver/core && CARGO_INCREMENTAL=0 cargo check -p archipelago`
|
||||
and `cargo test -p archipelago -- version_config set_config`; `cd neode-ui && npm run build`.
|
||||
2. Live-verify on `.228`: install bitcoin-core, open its detail page → "Version &
|
||||
Updates" card; exercise `package.versions` / `package.set-config` via RPC.
|
||||
3. Commit on the branch (checkpoint).
|
||||
4. **Phase 0** when greenlit: build+push tagged Core/Knots images, then extend the
|
||||
`VERSIONS` map in `scripts/generate-app-catalog.sh` and regenerate the catalog.
|
||||
|
||||
### Decisions still needed from user (see §6 open questions)
|
||||
Curated version set + storage budget (defaulted to current+~3 majors); when to do
|
||||
Phase 0 image pipeline; pruned-node downgrade policy refinement (currently warn+confirm
|
||||
for all). Auto-update default = OFF (opt-in), as recommended.
|
||||
════════════════════════════════════════════════════════════════════ -->
|
||||
|
||||
**Status:** design (2026-06-22)
|
||||
**Status:** implemented — all four phases shipped (catalog schema, install-time selection, in-app switch + auto-update toggle, and the verified image build pipeline). Downgrades are guarded: the update path never offers a lower version than what is running.
|
||||
**Goal:** let a user choose *which* version of Bitcoin Core / Bitcoin Knots to
|
||||
install (latest pre-selected, older versions in a dropdown), and later switch
|
||||
versions or opt into auto-update — all manifest/catalog-driven, all served from
|
||||
@@ -94,13 +10,8 @@ changes.
|
||||
|
||||
See also: [`docs/registry-manifest-design.md`](registry-manifest-design.md)
|
||||
(catalog distribution + signing this builds on),
|
||||
the production test gate (which must be
|
||||
green first), `MEMORY → project_decoupled_app_updates`,
|
||||
`MEMORY → project_manifest_driven_north_star`.
|
||||
and the production test gate (which must be green first).
|
||||
|
||||
> **Scheduling:** this is net-new scope. It lands **after** the production test
|
||||
> gate (`tests/lifecycle/run-20x.sh`) is green on `.228` + `.198`. The data-
|
||||
> preservation invariant (downgrade vs. chainstate) is the highest risk here.
|
||||
|
||||
---
|
||||
|
||||
@@ -260,7 +171,7 @@ free. `version`/`image` stay as the default for back-compat.
|
||||
- **Floating tags** (`latest`) are never advertised as a selectable "version" and
|
||||
never counted as an available update (already handled by
|
||||
`available_update_for_app`).
|
||||
- **Verify on a real node** (`.228` then `.198`) and pass `run-20x` before any
|
||||
- **Verify on a real node** and pass the lifecycle gate before any
|
||||
tag.
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user