igneum/docs/plans/cutover-2026-10-04.md

Devnet v4 cut-over: runbook for the morning of 4 October 2026

Staged overnight by the release engineer (packages built, seed build installed, nothing switched). The cut-over is a ten-minute operation in this order. Background: docs/fork-divergence.md, section "Integration 4 Oct 2026" (what v4 is, why it is a new chain, the test-network numbers). All Mac commands run from /Users/joshm/Projects/igneum unless a cd says otherwise. Times are BST.

What is staged

Item	Where	What it carries
Windows combined package 0.2.0	~/Desktop/igneum-windows-v4.zip (26,238,253 bytes, rebuilt 08:56 BST)	v4 igneumd.exe and igneum-miner.exe (cross-build of 6457ca95: generator v2 and the 2/3 floor), the three mingw DLLs, the launchers: peers = seed 188.245.5.161:26611 then Mac 192.168.68.64:26611, appdir %LOCALAPPDATA%\igneum\devnet-v4, MINERS=8 as --identities 8 on ONE worker per card, --evm-address (PAYOUT_EVM, else derived from the PC name per vendor), voting on, --prepare-packs for the hot swap, --exit-on-seed-change kept as the fallback, PLAIN=1 kept, version in the dashboard header
Windows node-only package	/tmp/igneum-integration/igneum-node-windows-v4.zip and ~/Desktop/igneum-node-windows-v4.zip (32,973,919 bytes, rebuilt 08:57 BST from 6457ca95)	same exes, src.zip, START-NODE.bat with appdir devnet-v4 and EXTRA_ARGS=--addpeer=188.245.5.161:26611 --yes
Mac app 0.2.0	packaging/mac/dist/Igneum-Miner-0.2.0.dmg (19,924,804 bytes, rebuilt 08:56 BST from 6457ca95; the Metal worker carries the generator v2 port)	v4 igneumd and igneum-miner from target-integration/release, the Metal worker rebuilt from the hot-swap source with -target arm64-apple-macos11 (prepare 1), SEED_PEERS = seed then Mac, data ~/Library/Application Support/Igneum/devnet-v4, --evm-address and --identities
Seed node v4	igneum-seed-1 (188.245.5.161): /opt/igneum/v4/bin/{igneumd,igneum-miner,run-seed-v4.sh}, /var/lib/igneum-v4 (empty), /etc/igneum/seed-v4.env, unit igneumd-v4 installed and DISABLED	first staged from dc749905 overnight; RE-STAGED from 6457ca95 (generator v2, 2/3 floor) starting 08:55 BST on 4 October (stage-v4.sh igneum-seed-1 start, log infra/seed-nodes/build/stage-v4-gen2-run.out); originally built from plus the working-tree igneum-pow (infra/seed-nodes/stage-v4.sh; log infra/seed-nodes/build/stage-v4-igneum-seed-1.log). The v3 unit igneumd keeps running on /var/lib/igneum until step (c)
Mac binaries	vendor/igneum-node/target-integration/release/igneumd (40,463,680 bytes), igneum-miner (7,916,096)	built from dc749905

Not staged, by design: the live devnet (node 1 on 26610/26611, the observer peer on 26640/26641/28640, observer.mjs, the Mac seed relay on 26680/26681) and the seed's v3 unit all still run the v3 chain.

The order

(a) the founder stops the PC

In both windows on the PC: Ctrl+C (the mining window first, then the node window; or one window if START-IGNEUM.bat was running: it stops the miners first, then the node). Wait for "Igneum has stopped" / "The node has stopped". Expected: the PC's node leaves the Mac's peer list within a few seconds (step (e) checks peers). The old folder C:\igneum (or wherever v3 was extracted) and %LOCALAPPDATA%\igneum\devnet are left as they are.

(b) Main session cuts the Mac over

# 1. stop node 1 (caffeinate exits with it) and move the v3 database aside
kill -INT 72039; while kill -0 72039 2>/dev/null; do sleep 1; done
mv /tmp/igneum-devnet/node1 /tmp/igneum-devnet/node1-v3-2026-10-04

# 2. start igneumd v4: same appdir path, rpclisten and listen, plus the two peers (seed, PC)
cd /Users/joshm/Projects/igneum/vendor/igneum-node
nohup caffeinate -dims target-integration/release/igneumd --devnet --nodnsseed --disable-upnp --enable-unsynced-mining \
  --appdir=/tmp/igneum-devnet/node1 --rpclisten=0.0.0.0:26610 --listen=0.0.0.0:26611 \
  --addpeer=188.245.5.161:26611 --addpeer=192.168.68.67:26611 --nologfiles --yes > /tmp/igneum-devnet/node1-v4.out 2>&1 &
# the execution layer starts with it (eth_ JSON-RPC on 127.0.0.1:26790); expected in node1-v4.out within 5 s:
#   "GRPC Server starting on: 0.0.0.0:26610", "P2P Server starting on: 0.0.0.0:26611", the genesis as the sink, 0 blocks

# 3. restart the observer peer from the same binary (fresh appdir) and observer.mjs
kill -INT 73692; kill -INT 74029
nohup target-integration/release/igneumd --devnet --nodnsseed --disable-upnp --appdir=/tmp/igneum-devnet/observer-v4 \
  --rpclisten=127.0.0.1:26640 --rpclisten-json=127.0.0.1:28640 --listen=127.0.0.1:26641 --connect=127.0.0.1:26611 \
  --nologfiles --yes > /tmp/igneum-devnet/observer-v4.out 2>&1 &
cd /Users/joshm/Projects/igneum && IGNEUM_RPC=ws://127.0.0.1:28640 nohup node tools/observer/observer.mjs > /tmp/igneum-devnet/observer-mjs-v4.out 2>&1 &
# block numbers restart at 0 on the new chain; LIVE_TABLE_PREFIX=v4_ keeps the v3 rows apart if wanted

# 4. the Mac seed relay (pid 72139, v3 binary): stop it; node 1 now dials the seed itself (--addpeer above), so the
#    relay is not needed. If the seed should also be reached through a second path, start it again from v4:
kill -INT 72139
#    RELAY_BIN=vendor/igneum-node/target-integration/release/igneumd infra/seed-nodes/addpeer-from-mac.sh relay start   (optional; it needs
#    its own fresh appdir: rm -rf /tmp/igneum-seed-relay first, or the v3 database refuses to open)

Where the Mac miner runs (the Metal worker, /tmp/igneum-devnet/metal-worker.log): restart it from target-integration/release/igneum-miner with --evm-address 0x... (any address the founder holds) once node 1 is up; an old miner's blocks are rejected from the first epoch boundary (DAA 3,600).

Expected after (b): igneum-miner watch 1 grpc://127.0.0.1:26610 prints blocks=1 headers=1 ... peers=0 synced=true (the genesis only, --enable-unsynced-mining reports synced); the live page shows the new chain from block 0.

(c) Seed: switch to v4

cd /Users/joshm/Projects/igneum/infra/seed-nodes
./stage-v4.sh igneum-seed-1 status      # expect: build=done | ... | v4: installed igneumd 2.1.0, unit igneumd-v4 disabled/inactive | v3: unit igneumd enabled/active
./switch-v4.sh igneum-seed-1            # stop+disable igneumd, enable+start igneumd-v4, then one sync line every 10 s

Expected output of the switch: igneumd: disabled/inactive igneumd-v4: enabled/active, six journal lines ending in P2P Server starting on: 0.0.0.0:26611 and WRPC Server starting on: 127.0.0.1:28610, then lines like synced=False version=2.1.0 blocks=1 headers=1 daa=0 sink=... peers=0 active turning into synced=True ... peers=1 within a minute once node 1 (which dials the seed) has connected and the few v4 blocks have crossed. ./health.sh then prints unit=active-v4. The seed never mines; it relays. Rollback of this step alone: ./switch-v4.sh igneum-seed-1 --back.

(d) the founder starts the PC on v4

1. Extract igneum-windows-v4.zip to a FRESH folder, for example C:\igneum-v4 (not over the old one: the old package's built workers and packs must not be mixed in).
2. Double-click START-IGNEUM.bat. Settings at the top are already right (peers, devnet-v4, MINERS=8). If the founder wants a specific payout address, set PAYOUT_EVM=0x... first; otherwise the launcher derives one per card and prints it.
3. Firewall prompt for the new igneumd.exe path: tick Private networks, Allow access (new exe path = new prompt).

Expected on the dashboard (header "Igneum: node and miners devnet v4, package 0.2.0"): NODE card "starting", then "syncing" with blocks climbing (the v4 chain is minutes old, so sync is seconds), "peer joined (1 peers)" then "(2 peers)" in the events, "synced in N s", then "exporting the program pack", "building the RTX 5090 worker (about 30 s for CUDA)", "started 8 RTX 5090 identities (1 miner)", "RTX 5090 worker ready, hot swap at the hour boundary" and the first "RTX 5090 found a block" within a minute. The launcher log (igneum-<stamp>.log next to the bat) carries the EVM address line and the full miner command line.

If the worker's ready event says "no hot swap (nvcc missing)", nvcc is not on the PATH of the launcher: the old exit-42 path rebuilds the worker at the boundary (about 30 s of no mining per hour), nothing else changes.

(e) Checks

Check	Command (Mac)	Expected
node 1 peers	vendor/igneum-node/target-integration/release/igneum-miner watch 1 grpc://127.0.0.1:26610	peers=2 (seed and PC), synced=true, blocks climbing about 1 per second once the PC mines
PC synced, blocks flowing	the PC dashboard NODE card: synced, blocks equal to the Mac's within a few blocks; chain N blocks/s near 1.00	the Mac's watch line shows the same sink as the PC's launcher log status block
seed synced	infra/seed-nodes/health.sh	OK ... unit=active-v4 rpc=yes synced=True blocks=<same as node 1> peers=1..2
live page	https://igneum.network/live	LIVE dot, the strip (blocks, miners, difficulty, peers) counting from the new genesis, the finality lock markers appear only after the first lock (next row)
first checkpoint lock	IGNEUM_RPC=ws://127.0.0.1:28640 python3 infra/cloud-devnet/node/wrpc.py call getFinalityCheckpoints	"window filling, N of 7,200" until the sink's DAA score reaches 7,200: the devnet weight window and min_daa are 7,200 DAA seconds, which is TWO HOURS of chain time after the v4 genesis (finality.rs DEVNET). The first lock lands at the first checkpoint whose DAA score is at least 7,200: expect it about 2 h after the chain starts, and observer.mjs then emits "checkpoint N locked (xx% of weight)" and the live page draws the lock marker. Locks every 30 s after that
hourly program swap	the PC events at the first boundary (DAA 3,600, about one hour after the v4 genesis; the pack for the next program is written 600 DAA s, 10 minutes, before it)	"the next hourly program is compiled and resident (hot swap ready)" about 10 minutes before the boundary, no miner restart at the boundary, hash rate unbroken. On the Mac miner's log: prepared ... then jobs on the new seed. Test-network numbers: first block of the new epoch accepted 0.5 to 2.2 s after the last of the old (fork-divergence)
EVM smoke	cd tools/evm-smoke && IGNEUM_RPCS=http://127.0.0.1:26790 IGNEUM_MINER_KEY=<the private key of an --evm-address that has mined> node smoke.mjs	SMOKE SUMMARY: 84 checks passed, 1 failed is the known result (the one failure wants duplicate sends in parallel blocks and a PoW network with one tip rarely offers any); fewer passes means the execution layer is not running. The quick check without a key: curl -s -X POST http://127.0.0.1:26790 -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}' returns "0x116f" (4463) and eth_blockNumber climbs

Shorter finality window for the first day (optional). The two-hour wait is the window filling; to see locks sooner, every node on the network must carry the same override file (it is a consensus parameter, so node 1, the observer peer, the seed and the PC all need it, and a node without it rejects nothing but certifies on a different schedule, which the lock rule treats as disagreement). The override file, with every finality field present (the parser takes the whole object):

{ "finality": { "checkpoint_interval": 30, "checkpoint_depth": 20, "weight_window": 1800, "dust": 5,
                "presence_window": 20, "aggregators": 8, "equivocation_ban": 1800, "min_daa": 1800, "aggregator_fallback": 15 } }

Flag on every node: --override-params-file=/path/override.json (Mac: in the two nohup lines above; PC: EXTRA_ARGS at the top of START-IGNEUM.bat, for example --override-params-file=C:\igneum-v4\override.json; seed: EXTRA_ARGS= in /etc/igneum/seed-v4.env, then systemctl restart igneumd-v4). 1,800 DAA s = 30 minutes to the first lock. The recommendation is to leave the default (7,200) and let the first lock arrive two hours in: that is the rule the network will run and the window is the test. The 300-DAA window of the integration test was the same mechanism.

(f) Rollback to v3 (two commands per machine)

Mac (node 1; the observer peer and observer.mjs the same way with their v3 commands from docs/fork-divergence.md):

pkill -INT -f 'target-integration/release/igneumd --devnet --nodnsseed --disable-upnp --enable-unsynced-mining --appdir=/tmp/igneum-devnet/node1'; sleep 3; mv /tmp/igneum-devnet/node1 /tmp/igneum-devnet/node1-v4-abandoned && mv /tmp/igneum-devnet/node1-v3-2026-10-04 /tmp/igneum-devnet/node1
cd vendor/igneum-node && nohup caffeinate -dims ./target/release/kaspad --devnet --nodnsseed --disable-upnp --enable-unsynced-mining --appdir=/tmp/igneum-devnet/node1 --rpclisten=0.0.0.0:26610 --listen=0.0.0.0:26611 --addpeer=192.168.68.67:26611 --nologfiles > /tmp/igneum-devnet/node1-v3-again.out 2>&1 &

(pkill -f with the full v4 command line only, never a bare name: the observer peer and the relay must not match.)

Seed: infra/seed-nodes/switch-v4.sh igneum-seed-1 --back (stops igneumd-v4, starts igneumd on the untouched /var/lib/igneum).

PC: Ctrl+C in the v4 window, then START-IGNEUM.bat in the OLD folder (its igneumd.exe, igneum-miner.exe and %LOCALAPPDATA%\igneum\devnet are untouched).

Mac app users: the 0.1.0 app and its devnet data folder are untouched by 0.2.0.

What the old chain's data means

Nothing is lost. The v3 chain (3 October, 12,000+ blocks, the finality v2 locks, the hash-rate measurements) stays in /tmp/igneum-devnet/node1-v3-2026-10-04 on the Mac, /var/lib/igneum on the seed, %LOCALAPPDATA%\igneum\devnet on the PC and ~/Library/Application Support/Igneum/devnet on any Mac that ran 0.1.0. The v3 binaries (target/release/kaspad, target-finality/release/igneumd, the old zips and Igneum-Miner-0.1.0.dmg) can read it. The live page's v3 rows stay in the live_* tables unless LIVE_TABLE_PREFIX=v4_ is set (then both chains keep their rows apart). The v3 chain is kept aside for reference and rollback; it is not deleted by any step above. The v4 chain starts again from the same genesis with block numbers from 0, so comparisons across the cut (block counts, DAA scores, difficulty) restart as well.

Untested before the morning

Item	Why
Windows package on the PC	no Windows machine on the Mac side; the PowerShell edits are checked by hand and by a bracket and quote balance pass (no pwsh on this Mac: the Homebrew cask is unavailable), not parsed by PowerShell. The CUDA worker's hot swap (host.cu with prepare, uncommitted working tree) has not run on the PC either; the exit-42 rebuild path stays underneath it
Mac app sync and mining	tested on this Mac with MINERS=0 on ports 28900/28901 against a dead peer (launch, version line, EVM address line, node up, Terminal title escape, --stop in 4 s, ports free, live devnet untouched); no v4 node was running, so sync and the Metal miner were not exercised by the 0.2.0 bundle (the same binaries mined on the integration test network)
Seed v4 unit	built and installed, never started; switch-v4.sh is new code, its rollback too
First lock and the hourly swap on the real devnet values	7,200 and 3,600 DAA; only the 300/60 test values ran