igneum/docs/spec/00-overview.md

# Igneum protocol specification, section 0: overview

Spec version 0.1, 3 October 2026. Status of this section: Designed.

## 0.1 Scope

This specification defines the Igneum layer 1 so that a stranger can reimplement a node, a miner and a verifier from it and reach the same bits. It covers:

| Section | File | What it fixes |
|---|---|---|
| 1 | `01-lottery-hash.md` | The random-program GPU lottery hash, its memory-hard dataset, the CPU verifier, the epoch, day and era schedules, test vectors and conformance |
| 2 | `02-consensus.md` | The ordering layer as a delta on rusty-kaspa: block rate, GHOSTDAG parameters, difficulty, emission, header changes, duplicate inclusion |
| 3 | `03-finality.md` | Sustained-mining finality, version 2, with the quorum floor |
| 4 | `04-seeds-and-vdf.md` | The epoch and era seed pipeline through the class-group VDF |
| 5 | `05-fees-and-economics.md` | Fees, splits, burns, signalling thresholds, no development fund |
| 6 | `06-open-items.md` | Every parameter or rule that is unmeasured, unreviewed or marked open, with the experiment that closes it |
| 7 | `07-execution.md` | The normative part of the execution layer: EVM semantics on the DAG, shard assignment by sortition, bridges |
| 8 | `08-client-security.md` | The official client and its release process: reproducible builds, the release key, no silent updates, distribution, the seed |

Out of scope for version 0.1: the rest of the zkEVM execution layer (transaction model, gas tables, proof records, the proving interface; `docs/design/execution-layer.md`), the chunked proving protocol, the proof format carried in headers, the external job market's contract, the P2P wire format, the RPC surface, the pool protocol. Where a later section depends on one of these, the dependency is named as a forward reference and the behaviour the dependency must provide is stated.

## 0.2 Normative language

MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as in RFC 2119. A sentence without one of these words is descriptive and carries no conformance weight.

Numbers come in four kinds and every number in this specification is labelled as one of them, in the sentence or in the table column that holds it:

| Label | Meaning | Example |
|---|---|---|
| Measured | Produced on a named machine on a named date by a named command. The bench-log entry is cited | 0.441 ms per warp CPU verify, `docs/bench-log.md`, entry "igneum-pow: Rust crate bit-exact with proto-metal" |
| Implemented | Fixed by code that exists and has test vectors, whether or not the value is final | 64 instructions, 8 iterations, `igneum-pow/src/generator.rs` |
| Designed | Fixed by a decision in the design document and not yet in code | Hard cap 4 billion, halving every two years |
| Target | A number the design aims at and has not measured | A chip gains under 2x over a GPU |

"Prototype value, to be fixed at gate 1" marks a parameter that the implementation carries today and that a named measurement will replace or confirm before the lottery hash is frozen. Every such parameter is listed at the end of section 1 and in section 6.

## 0.3 What is implemented and measured, what is designed

| Component | State on 3 October 2026 | Where |
|---|---|---|
| Lottery hash: generator, interpreter, memory-hard dataset, kernel emitters (Metal, CUDA, OpenCL) | Implemented in Rust (`igneum-pow`) and Swift (`proto-metal`), bit-exact with each other and with four GPU compiler paths on three vendors | `igneum-pow/`, `proto-metal/`, `proto-cuda/packs/`, `proto-opencl/` |
| CPU verification under 10 ms per warp | Measured: 0.41 to 0.58 ms steady, 0.87 ms worst cold, one M5 Max core | `docs/bench-log.md`, igneum-pow entry |
| Memory hardness of the dataset | Measured on Apple only: recomputing items is 4.8x slower than loading them. Not measured on NVIDIA or AMD | `proto-metal/MEMHARD.md` section 2.2 |
| Class-group VDF for the epoch seed | Implemented as a prototype, measured on one core; not reviewed by a second cryptographer | `proto-vdf/` |
| Finality rule version 2 | Designed, simulated with latency, partitions and eclipses (no DAG in the model). Not implemented | `sim/results_v2.md`, design document section "Finality rule, version 2" |
| rusty-kaspa fork | Base built and a 3-node devnet run at Kaspa's own parameters. No fork point implemented | `docs/fork-map.md`, bench-log devnet entry |
| Emission, fees, signalling | Designed | Design document |
| Era draw, instruction-family reserve, dataset growth | Designed at the level of a sentence. No draw procedure or reserve list exists | Design document, section 1.13 here |
| zkEVM, proving protocol, job market | Designed at the level of the design document. Nothing measured | Out of scope |

## 0.4 Versioning of the specification

The specification carries a version of the form MAJOR.MINOR.

- MINOR increments when text is clarified, a test vector is added, or a parameter marked "prototype value" is fixed without changing any existing test vector.
- MAJOR increments when any consensus-relevant behaviour changes: a test vector in section 1 changes, a rule in sections 2 to 5 changes, or a parameter that was Designed becomes Implemented with a different value.
- Version 1.0 is the version frozen at gate 1 for section 1 and at gate 3 for section 3. Until 1.0 any section may change at any MAJOR step.

Each section file carries its own status line (Measured, Designed or Open) and the index `README.md` collects them. The git history of `docs/spec/` is the change log; no separate change log is kept.

Consensus rules in a running chain change only through the upgrade path of section 5.7: new code activates when 90% of blocks in a signalling window carry the signal. The specification is updated to describe the activated rules, not the other way round.

## 0.5 How to submit a break

A break is a reimplementation that disagrees with a test vector, an attack that beats a stated bound, a measurement that contradicts a Measured number, or an argument that a Designed rule fails its stated property.

1. Check `docs/fud-ledger.md`. It holds every criticism received so far with its status. If the break is already there as Open, the entry names the experiment that will settle it and you can go straight to that.
2. If it is not there, write it the way the ledger writes entries: the claim in one paragraph, the evidence (a command and its output, a proof sketch, a reference), and the section and rule it breaks.
3. Submit it by the route named in the ledger's "Submitting a criticism" paragraph. On 3 October 2026 the repository is private and the public route does not yet exist; the ledger says so and the project has committed to opening one before the litepaper is shared (ledger entry X7).
4. Every submission that is not already in the ledger is added to it with credit if wanted, including submissions that turn out to be wrong, with the reason.

A break that reproduces is a MAJOR version change here and a status change in the ledger. Nothing in the ledger is deleted.

## 0.6 Conventions used in every section

- All arithmetic in section 1 is on unsigned 32-bit integers modulo 2^32 unless stated. There is no floating point anywhere in consensus.
- Byte order for hashing memory is little-endian: a 32-bit word w is hashed as the four bytes `w & 0xff, (w >> 8) & 0xff, (w >> 16) & 0xff, w >> 24`.
- Time in sections 2 to 5 is DAA time: difficulty-adjusted seconds derived from DAA score, never wall-clock. One block per second at launch, so one DAA second is about one block.
- Sizes: KiB, MiB, GiB are powers of two. GB in a quoted hardware figure means what the vendor meant.
- The chain's hash function for everything that is not the lottery hash is the one rusty-kaspa uses at the forked commit (BLAKE2b-based `Hash` in `crypto/hashes`), until section 2 says otherwise.