igneum/docs/fork-map.md

# Igneum fork map for rusty-kaspa

Base: rusty-kaspa commit `01b532e8b553523216471682649693af92f0fd16` (v2.1.0, 22 Sep 2026), cloned to `vendor/rusty-kaspa` on 3 Oct 2026.
Line numbers are from that commit. Re-check them after any vendor update. "Igneum change" follows the design paragraph in CLAUDE.md.
Risk: how much of the node's logic the change touches and how easy it is to get wrong. Nothing here has been implemented yet.

## The six fork points

| # | What | File (vendor/rusty-kaspa/) | Lines | Today in Kaspa | Igneum changes it to | Risk |
|---|---|---|---|---|---|---|
| a1 | PoW hash, stage 1: `PowHash` = cSHAKE256("ProofOfWorkHash") over pre-PoW header hash, timestamp, nonce | `crypto/hashes/src/pow_hashers.rs` | 4, 9 to 37 | Keccak f1600 with a fixed initial state | Replaced by the random-program GPU hash: the kernel is drawn per ~1 h epoch from a VDF seed of a certified checkpoint, reads a 256 MB RandomX-style cache (8 dependent reads per item), warp-unit CPU-verifiable | High. New primitive, needs bit-exact GPU and CPU paths (proto-metal and proto-cuda already agree on one program). |
| a2 | PoW hash, stage 2: `KHeavyHash` = 64x64 4-bit matrix multiply then cSHAKE256("HeavyHash") | `crypto/hashes/src/pow_hashers.rs`; `consensus/pow/src/matrix.rs` | 39 to 60; `Matrix::generate` 28 to 37, `heavy_hash` 101 to 125 | Matrix from xoshiro seeded by the pre-PoW hash, rank-64 check | Deleted. The program generator replaces the matrix; the epoch seed replaces the per-block matrix seed | Medium. Pure removal, but `kaspa_pow::State` callers assume a per-header precompute. |
| a3 | PoW state and check: `State::new`, `calculate_pow`, `check_pow`, `calc_level_from_pow` | `consensus/pow/src/lib.rs` | 19 to 56, 58 to 77 | `pow <= target` on a Uint256 from the heavy hash | Same interface, new body. `State` must carry the epoch program (looked up by header DAA score or timestamp), not a matrix | Medium. Block level (used by pruning proofs, 74 to 77) assumes a uniform 256-bit output; the new hash must keep that. |
| a4 | PoW validation call site in header processing | `consensus/src/pipeline/header_processor/pre_ghostdag_validation.rs` | 16 to 22 (`validate_header_in_isolation`), 102 to 106 (`check_pow_and_calc_block_level`) | `RuleError::InvalidPoW` unless `skip_proof_of_work` | Unchanged shape, but the check needs the epoch program for that header's epoch, so it gains a dependency on chain state (the VDF-certified checkpoint) | High. Header validation today needs nothing beyond the header. An epoch lookup during IBD and pruning-proof validation (`consensus/src/processes/pruning_proof/validate.rs:192`) must be deterministic from headers alone. |
| a5 | Pre-PoW header hash (what the nonce commits to) | `consensus/core/src/hashing/header.rs` | 7 to 30 (`hash_override_nonce_time`), 33 to 35 (`hash`) | BlockHash over version, parents, 3 roots, timestamp, bits, nonce, daa_score, blue_score, blue_work, pruning_point | Adds the vote key (see d) between `pruning_point` and the end, so the vote key is PoW-committed | Low. Mechanical, but every header hash test vector changes, genesis hashes included. |
| b1 | Block subsidy schedule | `consensus/src/processes/coinbase.rs` | 23 (`SECONDS_PER_MONTH`), 25 to 26 (table type), 222 to 234 (`calc_block_subsidy`), 236 to 255 (`subsidy_month`), 280 (`SUBSIDY_BY_MONTH_TABLE`, 426 entries) | Pre-deflationary flat subsidy, then a 426-month table (approximate reading: yearly halving in 12 monthly steps, see the table itself) | Hard cap 4 billion, halving every two years from genesis, no pre-deflationary phase, no table: a closed form `base >> (daa_score / blocks_per_two_years)` at 1 BPS. NO emission treasury | Medium. Simple maths, but `bps_history` and Crescendo per-BPS table rescaling (76 to 78) must be stripped rather than kept half-alive. |
| b2 | Subsidy parameters | `consensus/core/src/config/params.rs`; `consensus/core/src/config/bps.rs` | params 637 to 638 (mainnet `deflationary_phase_daa_score`, `pre_deflationary_phase_base_subsidy`), 342 to 344 (fields); bps 131 to 137 | 50 KAS per second split by BPS | New fields: `cap_sompi` (4e9 x 1e8), `halving_interval_blocks`, launch ramp (30 days) | Low. |
| b3 | Coinbase payee and split | `consensus/src/processes/coinbase.rs` | 97 to 142 (`expected_coinbase_transaction`), 144 to 220 (payload serialize, modify, deserialize) | One coinbase output per blue block to that block's miner, red blocks unpaid | 80/20 lottery/proving split: the 20% goes to the prover set recorded for the proven block, so the coinbase gains prover outputs. Fees: base fee burned in full, priority fee 65/15/15/5 with the 5% dev share per call frame (fee logic lives in the execution layer, not here) | High. Changes coinbase payload format and the "miner data" validation of every peer; the prover set must be known at coinbase construction time (20 to 60 s lag). |
| c1 | Difficulty adjustment (sampled DAA, KIP-4) | `consensus/src/processes/difficulty.rs` | 97 to 135 (`SampledDifficultyManager`), 166 to 198 (`calculate_difficulty_bits`), 211 to 223 (`calc_work`) | Average target of a 661-sample window (sample every 4 s), `new_target = avg x measured / expected`, clamp to `max_difficulty_target`, min window 150 samples | Kept as the retarget, but the hash speed jumps at every ~1 h epoch (bench: 35 to 48 Mhash/s across seeds on the same GPU) so the window must be short enough to track within an epoch, or the kernel generator must equalise cost per program. The 30-day vote-weight window (finality rule v2) is a new reader of DAA scores, not a retarget change | Medium. A per-epoch 30% hashrate step with a 44-minute window means roughly half an epoch at the wrong block rate. |
| c2 | DAA constants | `consensus/core/src/config/constants.rs` | 40 to 44 (`MAX_DIFFICULTY_TARGET` 2^255 - 1), 54 (`MIN_DIFFICULTY_WINDOW_SIZE` 150), 57 (`DIFFICULTY_WINDOW_DURATION` 2641 s), 60 (sample interval 4 s), 63 (sampled size 661) | As listed | Candidates: window 1800 s or shorter, keep 4 s samples; evaluate in simpa before deciding | Low. |
| d | Block header struct (vote key field) | `consensus/core/src/header.rs` | 154 to 172 (`Header`), 176 to 207 (`new_finalized`), 210 to 212 (`finalize`) | 12 fields, hash cached | Add `vote_key: [u8; 48]` (BLS12-381 G1 compressed public key; the finality vote weight is blue blocks per vote key over a flat 30-day DAA window, dust threshold 100 blocks). Every block carries it; equivocation evidence strips that key's weight for 30 days | High by spread, low by depth. Also edit: p2p wire `protocol/p2p/proto/p2p.proto:76 to 89` and `protocol/p2p/src/convert/header.rs:13, 45`; RPC `rpc/grpc/core/proto/rpc.proto:25` and `rpc/core/src/model/header.rs:85, 105, 248`; genesis headers `consensus/core/src/config/genesis.rs`; DB store `consensus/src/model/stores/headers.rs:24` (serde, re-sync needed); header mass. 48 bytes x 86,400 blocks/day = 4.1 MB/day extra. |
| e1 | Merge depth and finality depth constants | `consensus/core/src/config/constants.rs` | 70 (`FINALITY_DURATION` 43,200 s), 73 (`PRUNING_DURATION` 108,000 s), 81 (`MERGE_DEPTH_DURATION` 3600 s), 84 (`PRUNING_PROOF_M` 1000) | Scaled by BPS in `bps.rs:88 to 108` (at 10 BPS: merge 36,000 blocks, finality 432,000, pruning 1,080,000) | Merge depth kept at Kaspa's 3,600 s (design: fork choice is GHOSTDAG among tips through all certified checkpoints under merge-depth 3,600 s). Finality depth becomes a backstop only: the live finality is the 30-s certified checkpoint (2/3 of ACTIVE weight over a 2-hour presence window). Pruning depth must stay above the longest checkpoint gap | Medium. |
| e2 | Where depth is enforced | `consensus/src/processes/block_depth.rs`; `consensus/src/pipeline/header_processor/post_pow_validation.rs`; `consensus/src/pipeline/virtual_processor/processor.rs` | block_depth 51 to 69 (`calc_merge_depth_root`, `calc_finality_point`); post_pow 79 to 100 (`check_bounded_merge_depth`, kosherizing blues); processor 377 to 390 (`virtual_finality_point`) | Depth from blue score only | `virtual_finality_point` returns the latest certified checkpoint when one is newer than the depth point; virtual selection must refuse tips that do not descend from every certified checkpoint. The hidden-block n^2 penalty is NOT added (removed in review round 2, it broke DAG determinism) | High. Touches the virtual processor and finality-violation handling, which assume finality is a pure function of the DAG. |
| f1 | BPS and GHOSTDAG k | `consensus/core/src/config/bps.rs` | 24 (`TenBps`), 38 to 46 (k table: 1 BPS => 18, 10 BPS => 124), 49 to 54 (`target_time_per_block` = 1000 / BPS), 57 to 73 (max parents), 75 to 86 (mergeset limit), 119 to 121 (coinbase maturity) | k = 124 at 10 BPS (delta 0.01, network delay bound 5 s, `constants.rs:13 to 16`) | 1 block/s at launch: `Bps::<1>` gives k = 18, 1000 ms blocks, 10 max parents, mergeset limit 180, merge depth 3,600 blocks, finality 43,200 blocks, pruning 108,000 blocks, coinbase maturity 100 blocks | Low. This is the code path Kaspa mainnet ran before Crescendo. |
| f2 | Where the network picks its BPS | `consensus/core/src/config/params.rs` | 180 to 215 (`BlockrateParams`), 643 (mainnet `BlockrateParams::new::<10>()`), 645 (`pre_crescendo_target_time_per_block: 1000`), 648 (`crescendo_activation`), 699, 742, 783 (testnet, simnet, devnet) | 10 BPS everywhere, Crescendo and Toccata fork activations | Igneum mainnet params: `BlockrateParams::new::<1>()`, `ForkActivation::always()` for every past Kaspa fork (no history to replay), own genesis, own DNS seeders, own address prefix and ports (`consensus/core/src/network.rs:42 to 60, 238 to 252`) | Low to medium. The fork-activation plumbing (`bps_history`, `ForkedParam`) is woven through coinbase, difficulty and mass; strip it in one pass. |

## Notes from the 3 Oct 2026 devnet run (see docs/bench-log.md)

- Devnet and simnet in this commit run `BlockrateParams::new::<10>()`: 10 BPS, k 124, 100 ms blocks, merge depth 36,000 blocks, finality depth 432,000, pruning depth 1,080,000, coinbase maturity 200 (params.rs 783, 806 to 815). Simnet also sets `skip_proof_of_work: true` (params.rs 737) and allows 64 parents (742).
- Devnet genesis bits `0x1e21bc1c` (genesis.rs 193) means about 248,663 expected hashes per block, held fixed until 150 samples x 40 blocks = 6,000 blocks (difficulty.rs 170 to 177).
- `kaspad` ships no miner. `cli/src/modules/miner.rs` only spawns an external `kaspa-cpu-miner` binary (`daemon/src/cpu_miner/mod.rs:52 to 89`). The 3-node test used a 150-line miner built on `kaspa-pow::State` (real kHeavyHash), kept outside the repo.