commit 91fe8c69a51ea2c89b3077733d4c10de7c9262ba
parent c4dc4cd718bab729c5c51956797169386e1a0b9b
Author: Joris Hartog <jorishartog@hotmail.com>
Date: Wed, 19 Aug 2026 16:42:48 +0200
Document candidate promotion path
Diffstat:
3 files changed, 36 insertions(+), 14 deletions(-)
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -1,6 +1,6 @@
# Roadmap
-iuna is currently an experimental cryptocurrency devnet. This roadmap is the canonical planning document for moving from devnet/testnet hardening toward a mainnet candidate and, eventually, a mainnet launch.
+iuna is currently an experimental cryptocurrency devnet. This roadmap is the canonical planning document for moving from devnet/testnet hardening toward a mainnet candidate and, if the candidate stays healthy, promoting that same chain to mainnet.
## Current Phase
@@ -13,7 +13,7 @@ The current goal is to keep a small real testnet stable while increasing confide
- [x] Protocol rules are frozen for mainnet candidate.
- [x] Block, transaction, ticket, VDF, recovery, fork-choice, and peer compatibility rules are documented.
- [ ] Long-running testnet has stayed stable with independent nodes for an agreed window.
-- [ ] Mainnet-candidate testnet has launched from a fresh genesis using release artifacts.
+- [ ] Mainnet-candidate network has launched from a fresh genesis using release artifacts.
- [ ] New nodes can sync from genesis without manual intervention.
- [ ] Stale nodes can reconnect and catch up from old snapshots/range sync.
- [ ] Network partitions heal according to fork choice.
@@ -25,16 +25,16 @@ The current goal is to keep a small real testnet stable while increasing confide
- [ ] Block selection stays bounded by transaction count and size limits.
- [ ] Long-running chaos/property tests pass in release deployment.
- [ ] Release artifacts are tagged, checksummed, and reproducible enough for testers to verify.
-- [ ] Genesis allocation plan is published and reviewed.
+- [ ] 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] Basic operational monitoring is available for height, tip hash, peers, last block age, finalizer mode, VDF rounds, mempool, and rejected blocks.
-## Pre-Reset Mainnet-Candidate Test Backlog
+## Pre-Candidate Launch Test Backlog
-These items are not protocol rules. They are the attack and reliability checks to finish or consciously defer before the planned devnet reset that should become the mainnet-candidate network.
+These items are not protocol rules. They are the attack and reliability checks to finish or consciously defer before the planned devnet reset that creates the mainnet-candidate network. If that candidate stays healthy through the agreed window, the same genesis, chain history, UTXOs, and mined coins should be promoted to mainnet instead of being reset again.
-### Must Before Reset
+### Must Before Candidate Genesis
- [x] Burn bundle relay cannot import embedded burns before bundle metadata, membership, signature, fee ordering, and size are prechecked.
- [x] Block validation with burn attestations remains independent of local mempool contents, including empty and conflicting mempools.
@@ -76,7 +76,7 @@ Focus: make failure modes boring and observable.
### M2: Mainnet Candidate
-Focus: rehearse mainnet with mainnet-like process, but without mainnet permanence.
+Focus: launch the candidate with mainnet-like process and treat it as the chain that can become mainnet if it stays healthy.
- [x] Freeze protocol parameters for the candidate.
- [ ] Create a fresh mainnet-candidate genesis.
@@ -85,15 +85,17 @@ Focus: rehearse mainnet with mainnet-like process, but without mainnet permanenc
- [ ] 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.
+- [ ] Decide and publish whether the candidate ledger is promoted to mainnet without a second genesis.
### M3: Mainnet Launch
-Focus: launch only after the candidate process has already made launch boring.
+Focus: promote the stable candidate ledger. Mainnet launch should not create a second genesis unless the candidate failed and the reset is explicitly announced.
-- [ ] Publish final genesis plan and genesis hash.
-- [ ] Tag the mainnet release.
+- [ ] Publish the promotion decision, candidate genesis hash, promoted tip height, and promoted tip hash.
+- [ ] Tag the mainnet release from the promoted candidate code line.
- [ ] Publish release artifacts and checksums.
-- [ ] Start bootnodes.
+- [ ] Upgrade or restart bootnodes on the mainnet release while preserving chain data.
+- [ ] If the P2P network ID changes from `iuna-mainnet-candidate-v1` to `iuna-mainnet-v1`, coordinate the cutover without changing genesis or launch profile rules.
- [ ] Monitor first blocks and first recovery/fallback events.
- [ ] Keep feature changes frozen during the launch window.
- [ ] Document any required hard-fork or emergency procedure before launch.
@@ -122,3 +124,4 @@ Normal local development may skip ignored long-running property tests, but deplo
- 2026-08-14: Keep `ROADMAP.md` in the repo as the source of truth.
- 2026-08-14: Long-running property/soak tests are marked `#[ignore]` for normal local runs and are required in `deployment.sh`.
+- 2026-08-19: The mainnet-candidate chain is intended to be promotable to mainnet without a second genesis if it satisfies the stability window and release gates.
diff --git a/docs/genesis.md b/docs/genesis.md
@@ -2,11 +2,13 @@
This is operator documentation for bootstrapping a iuna devnet or mainnet-candidate network. Most users should join an existing bootnode instead of creating genesis.
+The mainnet-candidate genesis is not disposable by default. It is the genesis that can become mainnet if the candidate passes the agreed stability window and release gates. In that case, mined coins, UTXOs, tickets, and chain history remain on the same ledger; promotion is a coordinated release and network-identity cutover, not a second genesis.
+
Keep the management UI bound to `127.0.0.1`. Only the P2P listener should be internet-facing.
## Candidate Manifest
-Before a mainnet-candidate reset, publish one manifest in the release notes or operator coordination channel:
+Before creating the mainnet-candidate genesis, publish one manifest in the release notes or operator coordination channel:
```text
version:
@@ -16,6 +18,7 @@ genesis operator:
genesis start time:
genesis hash:
stability window:
+promotion policy:
bootnodes:
checksums:
```
@@ -27,6 +30,7 @@ Fill it with:
- the genesis operator and UTC start time;
- the genesis hash after the first node starts;
- the agreed no-reset stability window, for example one week;
+- whether a healthy candidate will be promoted to mainnet without a second genesis;
- every public bootnode as `<host>:<p2p-port>`;
- a link or pasted copy of `downloads/SHA256SUMS`.
@@ -56,7 +60,7 @@ Publish the checksums with the release artifacts. A node operator should be able
## Create Genesis
-Genesis requires a fresh wallet path and a fresh chain database. Use a new data directory for the reset candidate:
+Genesis requires a fresh wallet path and a fresh chain database. Use a new data directory for the candidate genesis:
```sh
iuna --genesis --data-dir ~/.iuna-candidate-genesis --p2p 0.0.0.0:9444 --http 127.0.0.1:18661
@@ -145,7 +149,7 @@ Never use `--genesis` to recover a node. `--genesis` is only for creating a fres
## No-Reset Stability Window
-For the mainnet-candidate rehearsal, treat unplanned resets as launch-blocking incidents unless they were explicitly scheduled before the window started.
+For the mainnet-candidate network, treat unplanned resets as launch-blocking incidents unless they were explicitly scheduled before the window started. Operators may mine and transact during this window with the expectation that the ledger can become mainnet if the candidate passes.
Start the window only after:
@@ -173,3 +177,16 @@ Exit criteria:
- release artifact checksums are independently verified;
- backup/restore rehearsal has passed;
- all launch-blocking incidents are fixed or explicitly deferred before mainnet.
+
+## Promotion To Mainnet
+
+If the candidate passes the stability window, publish a promotion notice instead of a new genesis plan. The notice should include:
+
+- candidate genesis hash;
+- promoted tip height and tip hash;
+- final candidate release tag and mainnet release tag;
+- bootnodes that will remain online through the cutover;
+- whether the P2P network ID changes from `iuna-mainnet-candidate-v1` to `iuna-mainnet-v1`;
+- the exact upgrade window for operators.
+
+Do not delete chain data when promoting. Nodes should keep `chain.sqlite3`, wallet files, and UI data, then upgrade or restart with the promoted release. A P2P network ID change fences upgraded mainnet nodes away from old candidate binaries, but it must not change genesis, launch profile rules, or any existing ledger state.
diff --git a/docs/protocol.md b/docs/protocol.md
@@ -46,6 +46,8 @@ The current mainnet-candidate parameter set is intentionally close to Bitcoin wh
Changing any value in this section requires a conscious mainnet-candidate reset or later hard-fork process.
+If the mainnet-candidate network is promoted to mainnet, the candidate genesis, chain history, UTXOs, tickets, and launch profile remain intact. A later P2P network ID change to `iuna-mainnet-v1` is only a peer-network cutover unless it is accompanied by an explicitly announced hard fork or reset.
+
Block size is checked from the node's canonical serialized block representation after parsing, so alternate JSON whitespace or key order cannot make a block count smaller. Transaction selection and fee-rate policy use compact economic transaction size: addresses, hashes, signatures, and Stratum headers count as their decoded byte lengths, and numeric fields count as compact base-128 varint widths. That keeps hex text and JSON decimal formatting from making transactions look larger or smaller economically than their protocol data.
## Coins and Transactions