igneum/docs/provenance.md

Igneum provenance: what is borrowed, what changed, how it is measured

Decision of 3 October 2026. Igneum credits every borrowed component in public, replaces only what its own design requires, and measures every change. This table is the public record of that decision. It is kept current with docs/fork-divergence.md (the node fork, change by change) and docs/bench-log.md (every measurement with its command).

How to read the licence column. "Verified" means the LICENSE file or the crate's Cargo.toml was read in this repository on 3 October 2026. "Approximate" means the licence is stated from memory because the source is not cloned under vendor/ yet; it is checked again when the clone lands, and before the repository goes public.

The table

Component	Origin (project, licence, repository)	What Igneum changed	Why the design needs the change	How the change is measured
GHOSTDAG ordering	Kaspa, rusty-kaspa. ISC, verified (vendor/rusty-kaspa/LICENSE, "Copyright (c) 2022-2024 Kaspa developers"; workspace license = "ISC"). https://github.com/kaspanet/rusty-kaspa	Unchanged algorithm. Parameters set for 1 block per second: k 18, 10 max parents, mergeset limit 180, merge depth 3,600 blocks (consensus/core/src/config/bps.rs, params.rs)	Launch rate is 1 block a second (CLAUDE.md), rising later. These are the values Kaspa mainnet ran before Crescendo, so nothing new is asserted about the ordering	Spec section 2.1; bench-log "igneum-node devnet v0: 3-node igneum-devnet at 1 BPS"; a test in params.rs pins every value
Node software (the fork)	rusty-kaspa v2.1.0, commit 01b532e8 (22 Sep 2026). ISC, verified. Fork at vendor/igneum-node, one commit per change on top of the base	Header gains vote_key_hash; genesis blocks; network ids igneum-*; devnet ports; DNS seeders emptied; address prefixes; emission schedule and 80/20 coinbase; PoW engine trait; PoW check moved after GHOSTDAG; rename of every user-visible string to igneumd. Full list: docs/fork-divergence.md	Each row there states the reason. The short version: finality rule v2 needs a vote key in every header, the emission is Igneum's own, the lottery hash needs chain state, and no Igneum node may ever dial a Kaspa peer	docs/fork-divergence.md (file, change, why, risk, merge note per row); bench-log devnet v0 and "first devnet blocks on the real lottery hash" entries; the four-node rename test of 3 Oct 2026
Difficulty controller	Kaspa sampled DAA (KIP-4) in rusty-kaspa, ISC, verified, kept as the retarget. Prior art studied: LWMA by Zawy (zawy12/difficulty-algorithms, licence approximate: MIT) and Monero's sorted and trimmed window (monero-project/monero, approximate: BSD-3-Clause). No code from either	Unchanged in the fork today (comment block only, consensus/core/src/config/constants.rs). The hash speed steps at every hourly program change, so a rule that tracks a step within an epoch is in progress: a two-speed rule (fast response to a step, slow drift otherwise). Not in spec 0.1	Programs differ in cost (35 to 48 Mhash/s across seeds on one GPU), so a 44-minute window spends half an epoch at the wrong block rate	Spec section 2.3 names the two remedies and the gate 2 simpa run that decides; bench-log first-run and RTX 5090 entries hold the per-seed rates. The two-speed rule gets its own bench-log entry when it is simulated
Random-program idea	RandomX by tevador, Monero. Licence approximate: BSD-3-Clause. https://github.com/tevador/RandomX (not yet cloned under vendor/; CLAUDE.md asks for it)	The idea only. Igneum's generator is new code (igneum-pow/src/generator.rs): a program drawn once per hourly epoch and compiled to native GPU code, with a per-hash random data path. RandomX draws a program per hash and interprets it on a CPU	A GPU cannot interpret a fresh program per hash at a useful rate; it compiles one program per hour instead. The target hardware is the opposite of RandomX's by design	Spec section 1 (generator, test vectors); bench-log "proto-metal first run", "RTX 5090 first run", "igneum-pow bit-exact" (96/96 vectors, three GPU vendors)
Memory-hard dataset	RandomX cache lineage (tevador, BSD-3-Clause approximate): a small cache that derives a large dataset by dependent reads	New construction, same shape: 256 MiB cache of chained ChaCha12 blocks, 8 dependent reads per item, dataset 1 GiB in the prototype and 2 GB at genesis, growing on a genesis-fixed schedule (igneum-pow/src/memhard.rs, proto-metal/MEMHARD.md)	A light verifier must hold only the cache; a miner must hold the dataset; the dataset must outgrow any fixed chip memory. RandomX's dataset has one size for ever	proto-metal/MEMHARD.md section 2.2 (recompute 4.8x slower than load, Apple only); bench-log "memory-hard dataset" entries on Metal and the RTX 5090
ChaCha, SplitMix64, FNV-1a inside the lottery hash	ChaCha by D. J. Bernstein (public domain, approximate); SplitMix64 by Steele, Lea and Flood (algorithm from the 2014 paper, approximate); FNV-1a by Fowler, Noll and Vo (public domain, approximate). All three re-implemented from the definitions in igneum-pow, no code imported	Used as published: ChaCha12 core with feed-forward for the cache fill, SplitMix64 as the program stream, FNV-1a 64 for seed words and the cache digest	Standard, well-studied primitives for a cache fill and a seed stream; nothing in the design asks for more	Spec sections 1.3 and 1.8 with test vectors; bench-log "igneum-pow bit-exact" (cache digest 48c4f5bf24166b2e matches Swift and C++)
ProgPoW and KAWPOW	ProgPoW (EIP-1057 text, ifdefelse/ProgPOW; KAWPOW on Ravencoin since 2020, RavenProject/Ravencoin, MIT approximate). Prior art, no code used. Not yet cloned; docs/fud-fixes.md item 48 asks for the clone and citation before the repository is public	Nothing taken. The difference: ProgPoW and KAWPOW randomise the maths inside a fixed program shape every few blocks; Igneum regenerates the whole program every hour over a growing dataset, with automatic era draws and no human in the loop	Stated so that the "first" claim in the litepaper is accurate (FUD ledger M4)	Litepaper "What has never been done before", row 1, rewritten 3 Oct 2026
Class-group VDF	Chia, chiavdf. Apache-2.0, verified (vendor/chiavdf/LICENSE), commit 7e62ce14. Wesolowski's proof (Efficient Verifiable Delay Functions, EUROCRYPT 2019), a paper, no licence	NUDUPL and NUCOMP ported from chiavdf's qfb_nudupl and qfb_nucomp into proto-vdf (Rust, over GMP through rug); fresh 1024-bit prime discriminant per input; 256-bit Fiat-Shamir prime (Chia uses 264); Igneum tags for the epoch and era paths. The textbook composition is kept as an oracle	The program seed must come from a certified checkpoint with a delay no miner can skip, so the seed cannot be ground. Chia's group needs no trusted setup	Spec section 4.2 (15,000 random cases agree with the oracle; 163,000 squarings per second; 4.5 ms verify); bench-log "proto-vdf" entry. GMP itself: LGPL-3.0 or GPL-2.0 dual, approximate, prototype only; the production dependency is decided with the wire format (O-4.5)
revm	Ethereum ecosystem, bluealloy/revm. Licence approximate: MIT. https://github.com/bluealloy/revm (not yet cloned)	Unchanged, credited. Driven by an Igneum block executor that feeds it the DAG's canonical sequence with the environment table of spec 7.1 and two-dimensional gas	The same EVM runs natively and inside the zkVM (reth, rsp and SP1 Reth all use it), so native and proven execution share one code path	docs/design/execution-layer.md D6 and section 2.1; differential test plan against reth (section 8.5). Nothing measured yet
SP1-class provers	Succinct, succinctlabs/sp1. Licence approximate: MIT or Apache-2.0. Not yet cloned	Unchanged, behind the versioned ProofSystem trait (docs/design/execution-layer.md 5.6). Version 1 is SP1 (Hypercube class, hash-based). Devnet v1 runs a stub that signs claims	Consumer cards prove hash-based systems without elliptic-curve MSM; the trait makes a swap a release (90% signalling, 3-month overlap, one wrap), never a redesign	No SP1 shard has been proven on any card in this repository (FUD ledger P1, P3). Phase 2 gate: shard time on a 3060-class card, published pass or fail
BLS12-381	Curve by Barreto, Lynn and Scott; blst by Supranational. Licence approximate: Apache-2.0. https://github.com/supranational/blst (not yet cloned)	Unchanged, credited. The header carries the BLAKE2b hash of a G1 compressed public key (48 bytes); every voter signs every 30-s checkpoint; signatures aggregate	Finality rule v2 needs one aggregate signature per checkpoint from thousands of keys	Spec section 3.1 (W1) and 2.4; sim/results_v2.md for the rule itself. Signature cost not yet measured
Hashing in the node	rusty-kaspa crypto/hashes, ISC, verified. Crates linked by the fork, licences read from the local cargo registry: blake2b_simd 1.0.2 (MIT), blake3 1.8.3 (CC0-1.0 or Apache-2.0), sha2 0.10.8 (MIT or Apache-2.0), keccak 0.1.6 (Apache-2.0 or MIT); sha3 0.10.8 not in the local registry, approximate: MIT or Apache-2.0	Unchanged, credited. BLAKE2b with domain separation for block, transaction and PoW pre-hashes (BlockHash, TransactionHash, ...), BLAKE3 keyed for the sequencing-commitment and payload hashers, SHA-256 for ECDSA signing hashes, cSHAKE256 (Keccak) in the kHeavyHash stub that stays as the default engine and for pruning-proof block levels	The chain's hash for everything except the lottery is the one the forked commit uses (spec 0.6), so nothing unverified enters consensus	hash_override_nonce_time gained one field (fork-divergence row 1); every header-hash test vector was regenerated and the four genesis hashes re-derived
Address format	Bitcoin BIP 173 character set (bech32, Pieter Wuille and Greg Maxwell; BIP licence approximate: BSD-2-Clause) with the CashAddr polymod checksum of Bitcoin Cash (the source cites bch.info), as implemented in rusty-kaspa crypto/addresses/src/bech32.rs, ISC, verified	Prefixes only: igneum, igneumtest, igneumsim, igneumdev (Kaspa: kaspa, kaspatest, kaspasim, kaspadev). The script public key behind an address is unchanged	No Igneum address string may parse as a Kaspa address on any network	Fork-divergence row 9; test vectors in addresses and txscript regenerated and passing
The EVM	Ethereum (Yellow Paper and ethereum/execution-specs, CC0 approximate). Cancun opcode set, precompiles 0x01 to 0x09	Semantics on a DAG: block.number is selected-chain height, block.timestamp is non-decreasing by a max rule, prevrandao is the VDF epoch seed, chain ids 4461, 4462, 4463; 0x0a absent; gas has a second dimension	Blocks on a DAG have no single parent and no header state root; proving cost is a second resource; the random beacon must be unbiasable	Spec section 7.1 (normative table); devnet measurement R9 for timestamp drift; ethereum/tests replay in the differential plan
kHeavyHash (kept as a stub)	Kaspa, rusty-kaspa crypto/hashes/src/pow_hashers.rs and consensus/pow/src/matrix.rs, ISC, verified	Kept untouched as HeavyHashEngine, the default engine when the igneum-pow feature is off, and the block-level source for pruning proofs until seeds are threaded through	Lets the devnet run and lets upstream pow changes merge cleanly	Fork-divergence rows 14 and 15; open item in the same file (pruning-proof block levels)

What is new in Igneum

Nothing here has a precedent that Igneum could have copied. Each item names the measurement or specification it rests on.

Piece	What it is	Where it is specified or measured
The hourly header-bound GPU program	A program drawn per epoch from a VDF seed, compiled to native GPU code, with the nonce-zeroed header hash absorbed into the init words so one nonce serves one header	Spec section 1 and igneum-pow/src/bind.rs; bench-log "first devnet blocks on the real lottery hash"
Sustained-mining finality, rule v2	Vote weight is blue blocks per BLS vote key over a flat 30-day window; every voter signs every 30-s checkpoint; lock at 2/3 of active weight and at least 56.7% of total weight; no stake, no other chain	Spec section 3; sim/results_v2.md (0 conflicting locks in every partition and eclipse scenario)
Two-dimensional gas and the per-frame app share	Execution gas on Ethereum's schedule plus proving gas from a calibrated table; 20% of the priority fee attributed per call frame to the registered developer of the contract that ran	Spec sections 5.1, 5.2; docs/design/execution-layer.md section 4
The shard market and the native proving precompile	Shards cut from the native trace, assigned by sortition to 8 eligible provers for 10 s, then open; a Prover system contract that takes a job and returns the result by a later proof record	Spec section 7.2; docs/design/execution-layer.md sections 5 and 6
Automatic era draws	Era parameters drawn every 6 months from chain state through a 1-h VDF, inside rules fixed at genesis; dataset growth and instruction-family unlocks by height, with no scheduled human release	Spec section 4.4; spec section 1 era schedule (Designed, not yet in code)

What we will adopt from upstream when it is ready

Item	Source	Condition
DagKnight	Kaspa's parameterless successor to GHOSTDAG (Sompolinsky and Sutton, approximate), once it ships in a rusty-kaspa release	Merged through tools/upstream/ after review against spec section 2; the finality rule reads blue blocks, so the weight table must be re-derived under the new ordering before activation
Upstream security fixes	rusty-kaspa tagged releases	Every tagged release is fetched and merged on a branch by tools/upstream/sync-upstream.sh; any change to a consensus rule is reviewed against docs/spec before the merge commit
Upstream pow and pruning-proof refactors	rusty-kaspa	Taken as long as kaspa_pow::State stays untouched (the Igneum engine sits beside it, never inside it)

Licence of Igneum's own code

Recommended: MIT, for the node fork's additions, igneum-pow, the prototypes and the tools. igneum-pow/Cargo.toml already declares license = "MIT" and should be read as provisional until the decision below.

Pending the project lead's decision. Two obligations hold whatever is chosen: the fork keeps Kaspa's ISC copyright notice in vendor/igneum-node/LICENSE (ISC requires it), and the VDF code keeps chiavdf's Apache-2.0 notice and a statement of what was changed (Apache-2.0 section 4).