commit 8bf2d9b47841b597085cc295cf2b0cdd4ce73394
parent 5cb23d0d5bde68864e41bc6836e4f3631d68452a
Author: Joris Hartog <jorishartog@hotmail.com>
Date: Wed, 19 Aug 2026 21:05:11 +0200
Document candidate upgrade rollback flow
Diffstat:
2 files changed, 35 insertions(+), 3 deletions(-)
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -27,7 +27,7 @@ The current goal is to keep a small real testnet stable while increasing confide
- [ ] Release artifacts are tagged, checksummed, and reproducible enough for testers to verify.
- [ ] Candidate genesis allocation plan, genesis hash, and promotion policy are published and reviewed.
- [ ] Security review is complete for consensus validation, transaction validation, P2P input handling, and wallet/key storage.
-- [ ] Upgrade and rollback instructions exist.
+- [x] Upgrade and rollback instructions exist.
- [x] Basic operational monitoring is available for height, tip hash, peers, last block age, finalizer mode, VDF rounds, mempool, and rejected blocks.
## Pre-Candidate Launch Test Backlog
@@ -82,9 +82,9 @@ Focus: launch the candidate with mainnet-like process and treat it as the chain
- [ ] Create a fresh mainnet-candidate genesis.
- [ ] Publish bootnodes and release artifacts.
- [ ] Publish checksums for every release artifact.
-- [ ] Document node setup, backup, restore, and upgrade steps.
+- [x] Document node setup, backup, restore, and upgrade steps.
- [ ] Run a candidate network for an agreed stability window.
-- [ ] Treat resets as launch-blocking incidents unless explicitly planned.
+- [x] Treat resets as launch-blocking incidents unless explicitly planned.
- [ ] Decide and publish whether the candidate ledger is promoted to mainnet without a second genesis.
### M3: Mainnet Launch
diff --git a/docs/genesis.md b/docs/genesis.md
@@ -183,6 +183,38 @@ Exit criteria:
- backup/restore rehearsal has passed;
- all launch-blocking incidents are fixed or explicitly deferred before mainnet.
+## Upgrade And Rollback
+
+For routine candidate upgrades, preserve local state and replace only the
+software artifact:
+
+1. Stop the node.
+2. Back up `wallet.json`, `config.json`, `chain.sqlite3`, and `ui_data.sqlite3`.
+3. Verify the new release artifact against the published `SHA256SUMS`.
+4. Start the new binary with the same `--data-dir`, `--wallet`, `--chain-db`,
+ P2P, HTTP, and Stratum settings.
+5. Confirm the wallet address, genesis hash, local height, tip hash, launch
+ profile, peer count, and last block age.
+
+Do not start upgrades with `--genesis`. Do not delete `chain.sqlite3` during a
+candidate-to-mainnet promotion. The promoted release must load the existing
+candidate chain database and continue from the current tip.
+
+If the upgraded node fails before it mines or accepts blocks under new rules,
+rollback is a software rollback:
+
+1. Stop the upgraded node.
+2. Restart the previous verified binary with the same data directory.
+3. Confirm the node resumes the same height and tip it had before the upgrade.
+4. Keep peers connected and let normal sync catch up if the network advanced
+ while the node was offline.
+
+If the upgraded node has already accepted blocks that older binaries reject, do
+not silently roll back. Treat that as a possible hard-fork or release incident:
+preserve chain/UI databases, stop public bootnode churn, compare tips across
+operators, and publish a decision before asking operators to delete or replace
+chain data.
+
## Promotion To Mainnet
If the candidate passes the stability window, publish a promotion notice instead of a new genesis plan. The notice should include: