igneum/igneum-pow/README.md

# igneum-pow

The Igneum lottery hash in Rust: the generator, the acceptance rule, the memory-hard dataset, the CPU verifier and the
kernel emitters. This is the crate the rusty-kaspa fork calls (`docs/fork-map.md`, rows a1 to a3) and, since
4 October 2026, the source of every program pack in `proto-cuda/packs/`. No dependency outside the standard
library; `serde_json` is a dev-dependency for reading the packs in the tests.

Dates: 3 October 2026 (crate, bit-exact with the Swift prototype), 4 October 2026 (generator version 2 and the
acceptance rule; every vector re-cut). Toolchain: rustc 1.99.0 via rustup (the Homebrew 1.69 on PATH is too old;
use `~/.cargo/bin/cargo`). Crate version 0.2.0.

## Modules

| Module | What it is | Swift namesake |
|---|---|---|
| `seed` | 32-byte seed words from bytes (FNV-1a 64, four salts, finalised); `seed_words_from_bytes` is the boundary where the chain feeds the epoch seed; SplitMix64 | `seedWordsBytes`, `SplitMix64` |
| `generator` | version 2: 16 load slots drawn first from instructions 1..63, fresh-source loads, the other 48 ops from the ten non-load weights; attempts `k = 0, 1, ...` of a seed; the program id. The retired version 1 generator stays as `generate_v1` for the census and the lever measurements | `generateProgramV2`, `candidateProgram`, `generateProgramV1` |
| `accept` | the acceptance rule of spec 01 section 1.4.6: two static tests and the 64-unit dynamic test on the seed-keyed closed-form dataset | `acceptProgram` |
| `memhard` | 256 MiB cache (2^16 chains of 64 ChaCha12 blocks), mixer parameters, 8-round item derivation with the 32 lanes interleaved, `MemhardCpu::fetch` | `cpuFillCache`, `MixParams`, `deriveItems`, `MemhardCPU` |
| `verify` | the 32-lane warp interpreter, `DatasetMode::{ClosedForm, MemoryHard}`, `Epoch`, `hash_warp`, `verify_block` | `cpuWarp`, `DatasetSource` |
| `emit` | Metal, CUDA and OpenCL source, program.h, memhard.h, vectors.h, program.json, vectors.json, the header-bound kernels, `export_pack` | `generateMSL`, `generateCUDA`, `generateOpenCL`, `exportPack` |
| `bind` | header binding (spec 01 section 1.6): init words from `"igneum-block/" \|\| H \|\| nonce_hi_le32`, bound hash API on `Epoch`, the 256-bit pow mapping, the interim day seed bytes | `blockInitWords` |

## Generator version 2 (4 October 2026)

Adopted from `docs/analysis/weak-program-census-2026-10-03.md` (ledger M5 and M6). Three parts, all in this crate
and mirrored in `proto-metal/main.swift` so the Metal worker derives the same program from the same seed:

| Part | Rule | Where |
|---|---|---|
| G1, exact load count | 16 `load` instructions per program, a uniform 16-subset of slots 1..63 drawn first by partial Fisher-Yates over the program stream; the other 48 ops from `add 12, xor 10, mul 8, mad 8, shfl 8, rotl 7, sub 6, mulhi 6, rotr 6, or 4` (sum 75). 128 loads per hash, 4,096 items per unit | `generator::candidate_from_words` |
| G2, fresh source | a load's source is drawn from the registers other than `dst` written by an earlier instruction and not read by a load since, so no load repeats an earlier load's address in the hash | same |
| R, acceptance | (a) no load whose source is unwritten since the previous load from it, cyclically; (b) every register has an `add`, `sub`, `xor`, `mad`, `shfl` or `load` write; (c) 64 units at base nonces from `SplitMix64(FNV-1a-64("igneum-accept/" \|\| seed words LE))`, init words = seed words, closed-form dataset `dataset_elem(idx, S[0], S[1])` at 2^28 words: no constant register bit, no lane-constant load site in any unit, fewer than 164 saturated final values, every output bit within 136 of 1,024, distinct addresses above 245,760 over the 2,048 hashes | `accept::check` |
| Attempts | a rejected candidate is replaced by `seed_words_from_bytes(seed \|\| k_le32)` for `k = 1, 2, ...`; 32 consecutive rejections are a consensus fault (probability below 2^-136 at the measured 5 percent rate) | `generator::generate_from_seed_bytes` |
| Program id | `FNV-1a-64("igneum-program/" \|\| 2_le32 \|\| seed words LE \|\| attempt_le32)`, written into program.json and program.h with the generator version and the attempt, so a version 1 pack or another attempt can never pass for the current program | `Program::program_id` |

Measured on this crate (`igneum-pow accept`): `igneum-genesis` attempt 0 accepted, program id `bcc1248b10cc90f2`,
op mix `load=16 add=8 shfl=8 xor=6 mad=5 mul=5 mulhi=5 sub=4 rotl=3 rotr=3 or=1`, 128.000 distinct addresses per
hash; `igneum-hourly` attempt 0, id `a4c4d00961c855df`; seeds `igneum-census-2026-10-03/22`, `/37` and `/51` have
attempt 0 rejected ((b) r7 without an injecting write; (c) 119.74 distinct addresses; (b) r4) and attempt 1
accepted (ids `22ed0609d079f4cf`, `947705cc4eb1df0a`, `9869afcc028bf9f1`); those three are the conformance vectors
for the attempt rule. The rule costs 1.3 to 3.4 ms per seed on one core. The 20,000-program census under this
generator is in `docs/bench-log.md` (4 October 2026 entry).

## The API the fork calls

```rust
use igneum_pow::{Epoch, DatasetMode};

// Once per epoch and day: derives the accepted program and fills the 256 MiB cache (about 0.2 s on one core).
let epoch = Epoch::memory_hard("igneum-genesis", "2026-10-03");

let h: u64 = epoch.hash(nonce);                 // one nonce (computes its aligned 32-nonce warp)
let w: [u64; 32] = epoch.hash_warp(base_nonce); // one warp
let ok: bool = epoch.verify_block(nonce, target_u64);

// Miner programs for the epoch: the pack every worker compiles.
let pack = igneum_pow::emit::export_pack(&epoch, "2026-10-03", "igneum node");
pack.write_to(std::path::Path::new("out"))?;   // kernel.cu, kernel.cl, program.metal, memhard.h, ...
```

## The header-bound form (what the chain uses)

The pack form above initialises the lane registers from the program's own seed words, so one nonce has one
hash per epoch whatever block is mined. On the chain the init words commit to the block (spec 01 section 1.6,
`src/bind.rs`):

```
H        = header hash with the nonce field zeroed, every other field as mined
           (rusty-kaspa hash_override_nonce_time(header, 0, header.timestamp))
nonce    = 64 bits; lane nonce n = low 32 bits; nonce_hi = high 32 bits
I        = seed_words_from_bytes("igneum-block/" || H || nonce_hi_le32)      (49 bytes in)
hash     = interpret(program, I, n)                                          (section 1.7 of the spec)
pow256   = hash in the top 64 bits, low 192 bits zero (little-endian bytes 24..32)
valid    = pow256 <= target256, which is exactly hash <= target256 >> 192
```

`H` keeps the timestamp (Kaspa zeroes it in the pre-PoW hash and absorbs it in cSHAKE afterwards; the lane hash has
no afterwards, so a nonce would otherwise be reusable across timestamps). The interim day seed is
`"igneum-day/" || day_le64` with `day = timestamp_ms / 86,400,000`. The epoch seed bytes are the 32 bytes of the
epoch block hash (devnet); the program is `generate_from_seed_bytes(epoch_seed)`, attempts included.

```rust
use igneum_pow::{bind, Epoch};

let epoch = Epoch::from_seed_bytes(epoch_hash.as_bytes(), &bind::day_bytes(day), "label");
let lane: u64 = epoch.hash_bound(&prehash, nonce);               // one 64-bit nonce
let warp: [u64; 32] = epoch.hash_warp_bound(&prehash, nonce);    // its aligned 32-nonce group
let init = bind::block_init_words(&prehash, nonce);              // what a GPU kernel takes as its argument
let same = epoch.hash_warp_init(&init, nonce as u32 & !31);     // == warp
let pow: [u8; 32] = epoch.pow_bound(&prehash, nonce);
let ok = epoch.verify_block_bound(&prehash, nonce, bind::target64_from_le256(&target_le));
```

On the GPU the init words are a kernel argument: `igneum_hash_bound` in `program_bound.metal` takes
`constant uint* initw [[buffer(3)]]`, `kernel_bound.cu` takes `IgneumInitWords iw` by value, `kernel_bound.cl` an
`initw` buffer. All three differ from `igneum_hash` only in the kernel name, the argument and the eight init lines.

Bound vectors (seed `igneum-genesis`, day `2026-10-03`, memory-hard, 2^28 words, generator v2; `igneum-pow hash-bound`):

| H | nonce | hash_bound |
|---|---|---|
| 32 zero bytes | 0 | `746c567b090acf6a` |
| 32 zero bytes | 1 | `45a619f860880c73` |
| 32 zero bytes | 31 | `9aa495e43dedbfe6` |
| 32 zero bytes | 4096 | `2e6ffd7624d3cba2` |
| 32 zero bytes | 4294967296 (1 << 32) | `38a5cea1fb01431a` |
| bytes 00 01 02 .. 1f | 0 | `2a79c5e4797bf6aa` |
| bytes 00 01 02 .. 1f | 4294967301 ((1 << 32) + 5) | `a243e0c61aa1b82e` |
| bytes 00 01 02 .. 1f | 18446744073709551615 (u64::MAX) | `9c7bbfbd064fe1a4` |

Init words for H = 32 zero bytes, nonce 0: `595a8f8a 37647e95 faadade1 cbbcf2a4 54f7cc13 f6851b5e 8c68ca04 7991ea9c`
(unchanged by v2: the binding does not depend on the program). The eight are pinned in `bind::tests::bound_vectors`.
The version 1 bound vectors of 3 October 2026 are retired.

`Epoch` is `Send + Sync`; build one and share it. `DatasetMode::ClosedForm` is the interpreter regression dataset
of the packs `igneum-genesis` and `igneum-hourly` and is not memory-hard.

## CLI

```
cargo build --release
./target/release/igneum-pow bench  --seed igneum-genesis [--warps 20] [--closed-form] [--day 2026-10-03]
./target/release/igneum-pow export --seed igneum-genesis --out <dir> [--closed-form]
./target/release/igneum-pow export --epoch-hex <64 hex> --day-hex <hex> --out <dir>     the chain's byte seeds
./target/release/igneum-pow hash   --seed igneum-genesis --nonce 4103
./target/release/igneum-pow hash-bound --seed igneum-genesis --prehash <64 hex> --nonce <u64>
./target/release/igneum-pow accept --seed igneum-census-2026-10-03/22      every candidate with its verdict
./target/release/igneum-pow show   --seed igneum-genesis                   the accepted program, one line per instruction
```

The packs were regenerated on 4 October 2026 with exactly these commands:

```
igneum-pow export --closed-form --seed igneum-genesis --out ../proto-cuda/packs/igneum-genesis
igneum-pow export --closed-form --seed igneum-hourly  --out ../proto-cuda/packs/igneum-hourly
igneum-pow export --seed igneum-genesis --out ../proto-cuda/packs/igneum-genesis-mh
igneum-pow export --epoch-hex edc4fa844da9dc98d37e965176f6558a31560e40502ab3ae5491b21aaaabfb07 \
                  --day-hex 69676e65756d2d6461792ffa50000000000000 --out ../proto-cuda/packs/igneum-devnet-v4-epoch0
```

The last is the chain's own derivation for devnet v4 epoch 0: the devnet genesis hash as the epoch seed and
`bind::day_bytes(20730)` (2026-10-04) as the day bytes.

## Tests

`cargo test --release` (39 tests, about 2 s after compile; the dev profile is optimised so the cache fill is quick):

| Check | Pack | Result |
|---|---|---|
| program.json instruction by instruction from `seed_bytes`, generator 2, attempt, program id, op mix, 128 loads, acceptance | all four | match |
| Mixer parameters (key, rot, mul, rc) | igneum-genesis-mh, igneum-devnet-v4-epoch0 | match |
| Cache head, last line, FNV-1a 64 (`48c4f5bf24166b2e` for day 2026-10-03, `448274a57f508cbc` for day bytes 20730) | the two memory-hard packs | match |
| Dataset head (16), `[MASK]`, 64 sampled words | all four | match |
| 96 hash vectors (3 warps x 32 lanes) | all four | 96/96 each |
| kernel.cu, kernel_bound.cu, program.metal, program_bound.metal, kernel.cl, kernel_bound.cl, program.h, program.json byte-identical; 16 masked loads per kernel | all four | identical |
| memhard.h, memhard.metal byte-identical | the two memory-hard packs | identical |
| vectors.json, vectors.h byte-identical; no stale file in any pack directory | all four | identical |
| bound vectors (8), bound warp == bound single, H and nonce_hi enter the hash | igneum-genesis-mh | pass |
| the devnet pack equals `Epoch::from_seed_bytes(genesis, day_bytes(20730))` | igneum-devnet-v4-epoch0 | pass |
| acceptance: instrumented interpreter == `hash_warp`, cyclic stale-load detection, injecting-write detection, rejection under 12.5 percent and distinct loads above 127 on 400 census seeds, version 1 programs mostly rejected | unit tests | pass |
| generator: 16 loads, none at instruction 0, contract on 200 candidates; fresh sources; attempt words; program ids separate versions and attempts | unit tests | pass |

## Measured, Apple M5 Max, one core, release build

| Step | 3 October 2026 (v1, 104 loads) | 4 October 2026 (v2, 128 loads, 4,096 items) |
|---|---|---|
| Cache fill, 256 MiB | 175 to 181 ms | 179 ms |
| CPU verify per warp, igneum-genesis, avg of 20 | 0.441 ms (3,328 items) | 0.631 ms |
| Cold single warps (bases 0, 4096, 1000000) | 0.41 to 0.87 ms | 0.67 to 0.81 ms |
| Acceptance rule per candidate | | 1.3 to 3.4 ms |
| Closed form, igneum-genesis | 0.002 ms | 0.002 ms |

The 10 ms gate holds with a margin of about 16x steady on this core. Every verified unit now derives exactly 4,096
items, the design bound of spec section 1.11.

## Not done here

- No GPU. The vectors tie this crate to the Metal, CUDA and OpenCL results through the packs; nothing here runs a kernel.
- The epoch seed enters at `Epoch::from_seed_bytes` (the epoch block hash on devnet); the VDF output replaces it there.
- The dynamic acceptance test is specified on the closed-form dataset at 2^28 words; if the prototype mask ever changes, the rule's constant stays at 2^28.