igneum-network/igneum
1
0
Fork 0
Code Issues Pull requests Releases Activity
igneum/tools/harness/README.md
igneum-labs 6b72c3b3e6 Fast time: the devnet at 60x for test networks (override-60x.json, --fast-time in both harnesses, proof script) 
infra/fast-time/override-60x.json is the devnet with every clock-like consensus parameter divided by 60 and every
block count unchanged (finality window, ban and min_daa 120 DAA; merge depth 60; Kaspa finality depth 720; pruning
depth at the anticone bound 13,838; coinbase maturity 2; the hourly program epoch 60 blocks with a 10-block lead;
the dataset day 24 minutes). The epoch length, lead and day are consensus parameters of the node since devnet-v4
a5ef8b07, carried by the override file. README lists each field, why it scales or not, the flags and the numbers.

Measured (simnet.mjs, three devnet-v4 nodes, three vmine voters at 1 block/s, one real-hash CPU miner): next
epoch seed in the template at 56.1 s, program swap at 65.1 s wall (DAA 60), first finality lock at 185.5 s wall
(checkpoint 5, DAA 149). Both harnesses take --fast-time: finality-attacks s3 PASS in 113 s wall with 16 locks
per node (the devnet rule needs 20 min of warm-up at 6 blocks/s before any lock); harness s3 partition and heal
43 s wall for three cuts against 983 s for four on the devnet profile with the same binary. Bench-log entry.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-04 10:34:19 +00:00

6.2 KiB
Raw Blame History

Igneum consensus attack harness

Plays the standard consensus-attack catalogue against a private test network of our own Igneum nodes, with a pass criterion per scenario taken from the spec and a measured result for each. This is robustness and conformance testing of our own devnet software, the practice upstream Kaspa (simpa, testing/integration) and the Ethereum clients follow.

What it is built on

  • The in-process network simulator from rusty-kaspa (kaspa_utils::sim, the engine simpa uses): one real Consensus per node in virtual time. The harness adds hash-share miners, a withholder, timestamp policies, a cut-and-heal topology and reorg records. Source: vendor/igneum-node-harness/igneum/harness-sim.
  • Real igneumd processes on 127.0.0.1, driven over wRPC JSON, for the live scenarios (5, 6, 7 Part B).
  • A p2p probe that speaks the fork's own protocol (handshake, InvRelayBlock, RequestRelayBlocks, Block) to deliver malformed blocks on the wire. Source: vendor/igneum-node-harness/igneum/p2p-probe.

All nodes run with skip_proof_of_work (the harness never hashes), so the harness controls each miner's hash share exactly. Every other consensus rule (timestamps, DAA, GHOSTDAG, merge depth, mass, coinbase) runs unchanged, so the harness exercises the ordering layer, not a weakened copy of it.

Ports and isolation

The test network uses 127.0.0.1 ports 27200 and up and data under /tmp/igneum-harness. It never touches the live devnet (gRPC 26610, P2P 26611, observer 26640/26641/28640), the PC node at 192.168.68.67, or any port other agents use (up to 27199). Loopback peers are never gossiped (components/addressmanager/src/lib.rs), so no link forms that a scenario did not ask for. Everything the harness starts is stopped at the end, including on SIGINT.

Build

The harness binaries live in the harness worktree of the node fork:

cd vendor/igneum-node/ && git worktree add -b harness ../igneum-node-harness HEAD   # once
cd ../igneum-node-harness
CARGO_TARGET_DIR=target nice -n 19 ~/.cargo/bin/cargo build --release -j 4 \
  -p kaspad -p igneum-miner --features kaspad/igneum-pow
CARGO_TARGET_DIR=target nice -n 19 ~/.cargo/bin/cargo build --release -j 4 \
  -p igneum-p2p-probe -p igneum-harness-sim

This produces target/release/igneumd, igneum-miner, igneum-p2p-probe and igneum-harness-sim. The run scripts find them there; override with IGNEUMD, IGNEUM_P2P_PROBE, IGNEUM_HARNESS_SIM.

Run

node tools/harness/run.mjs                # the full catalogue, priority order 5,2,1,3,6,4,7
node tools/harness/run.mjs s5 s2 --quick  # named scenarios, short durations
node tools/harness/run.mjs --no-bench-log # do not append to docs/bench-log.md
node tools/harness/scenarios/s1-withhold.mjs --quick   # one scenario on its own
node tools/harness/run.mjs s3 s4 --fast-time   # the 60x fast-time profile (infra/fast-time): merge depth 60 s, so the
                                               # partition and eclipse cuts are 10, 30 and 62 s instead of 600, 1,800 and
                                               # 3,700; nodes and the simulator come from vendor/igneum-node/target-integration

Each run appends one dated entry to docs/bench-log.md with a row per scenario (criterion, measured result, pass or fail), writes full JSON per scenario under /tmp/igneum-harness/results and /tmp/igneum-harness/sim, and leaves the test network stopped. Exit code is non-zero if any scenario failed.

The catalogue

# Scenario Where Criterion (spec)
1 Withheld-block mining (10, 25, 33, 45% share, release every 5 and 20) sim spec 02 2.1: attacker blue-block share within 2 sigma of hash share over 2,000 blocks; reorg depth distribution recorded
2 Timestamp manipulation: past-median and future-time edges; a 33% miner stretching inside the rules live + sim spec 02 2.3: rejected exactly at the boundary; block-rate drift of the controller measured
3 Partition and heal (2, 10, 30 min, plus one beyond merge depth) sim spec 02 2.1: one chain after the merge-depth rule; reorg depth and time to heal recorded
4 Eclipse of one node (victim fed a slower side chain) sim spec 02 2.1: rejoins the honest chain on reconnection within the merge-depth bound
5 Malformed and boundary inputs on every p2p message and RPC method the fork touches live + p2p fork-divergence header and RPC rows; ledger M15: rejected without a crash or a cache build
6 Resource exhaustion (50x template, submit and mempool floods from one peer) live honest template p95 under 200 ms, node under its memory bound; numbers recorded
7 Fast-miner flood (50x joins at once, the devnet event) live + sim node stays responsive; controller trajectory recorded for the difficulty branch

Scenario 5 overlaps the r3-fixes branch (ledger M15): that branch runs the cheap checks before the lottery engine, caps cache builds and bans the peer. On this node branch (HEAD, d62708a8, before r3-fixes) the engine keeps three caches, so a stream of bogus past-day headers can still force a build; scenario 5 records whether any case built a 256 MiB cache, which is the quantity r3-fixes drives to zero.

Stubs (finality and difficulty-controller branches)

Finality and the difficulty controller live on their own branches. Their scenarios are stubs here, with criteria written and a one-line plan for running them once the branch is merged into the harness worktree. See scenarios/stubs.mjs. In short: 1b (withhold vs vote weight), 3b (partition vs lock revocation, ledger F16), 4b (eclipse vs presence window, ledger F2), 2b (timestamp stretch on the dual-lane controller), 7b (the 50x flood on the dual-lane controller, against the kaspa-sampled baseline this harness records).

Files

  • run.mjs scenario runner and bench-log writer.
  • scenarios/s1..s7 one file per scenario; each exports run({ quick }) and runs standalone.
  • scenarios/stubs.mjs the finality and controller stubs.
  • lib/net.mjs node processes, topology, TCP proxy for a cuttable link, cleanup.
  • lib/rpc.mjs wRPC JSON client. lib/miner.mjs virtual miner and latency probe. lib/address.mjs devnet address encoder. lib/sim.mjs runs igneum-harness-sim. lib/report.mjs results and bench-log entry.