diff --git a/docs/commercial/prover-customer-brief.md b/docs/commercial/prover-customer-brief.md new file mode 100644 index 000000000..b49dca8a5 --- /dev/null +++ b/docs/commercial/prover-customer-brief.md @@ -0,0 +1,64 @@ +# Igneum proving: brief for a first customer at testnet + +Version 0.1, 3 October 2026. For a rollup or bridge team considering Igneum as a proving supplier. One page. Everything below is subject to the gates on the public roadmap, and nothing in it is an offer to sell anything. + +## What Igneum is + +A proof-of-work chain mined on consumer GPUs, where the same cards prove every Igneum block with zero-knowledge proofs and take proving jobs from other chains. The miners are the provers. At public testnet they are a network of independent GPU owners, 1,000 of them by the testnet gate, already paid by the chain to keep their cards on, so external jobs are marginal work for them. + +## What you get + +| Item | What it is | Status today | +|---|---|---| +| Proofs for your chain | Your batches or blocks proven by Igneum's GPU prover network and returned to the address you name | Designed. No shard has been proven on a card yet | +| Price in dollars | Jobs are priced in dollars per proof. At launch the fee is paid on your own chain, in your currency, to a payout contract keyed by miner address, because Igneum cannot yet see your chain. Settlement in the coin follows when the proof bridge exists | Spec section 5.4 | +| Delivery rule | A job is claimed with a bond that is slashed on a late or bad proof; a job nobody proves by its deadline expires and refunds in full. At launch your chain's own bond and slashing apply to the miner who claimed the job | Design document, execution layer, sections 5.2 and 6. Bond size and timeout are open (O-5.6) | +| A versioned interface | Jobs run against the `ProofSystem` trait, version 1 of which is SP1. A later version is a release with its own test-vector set and a three-month overlap, so your integration survives a prover swap | Design document, execution layer, section 5.6 | +| Verification you can run | A job proof is a single proof your contract verifies on your own chain; Igneum's own segment proofs recursively verify it, so no relayer or committee is in the path | Designed | + +## What you must do + +1. Integrate against the versioned prover interface: the guest program hash (`program_id`) your batches are proven under, the public-input layout, and the proof encoding for version 1. +2. Supply test vectors: at least 100 historical batches or blocks with the expected public inputs and outputs, so Igneum's provers and your verifier agree before any job carries value. +3. Name the deadline and the maximum proving budget per job (the `maxPgas` of the interface), and the address on your chain that receives proofs. +4. Sign for testnet. Phase 4's gate is "one rollup signs for testnet"; a signed letter of intent with no payment is what the gate asks for. + +## Timeline, tied to the public roadmap + +| Phase | When | What it means for you | +|---|---|---| +| 2. Prove the proving | Nov 2026 to Jan 2027 | The shard benchmark on consumer cards. If a mid-range GPU cannot prove a shard in under 20 s, Igneum says so and the project stops. You see the numbers, pass or fail | +| 4. Finality and job market | Apr to Jul 2027 | External proving jobs exist on the devnet. Integration work happens here. Gate: one rollup signs for testnet | +| 5. Public testnet | Aug to Oct 2027 | Your proofs delivered by the live prover network. Gate: rollup proofs delivered on time, measured and published. No coin exists yet | +| 6. Mainnet | Nov 2027 | Jobs priced in dollars, paid on your chain at first, settled in the coin once the proof bridge exists | + +Dates from `site/journey.json`. Each gate is published whether it passes or fails. + +## Risks, stated plainly + +- Prototype prover. The devnet runs a stub that signs claims. No SP1 shard has been proven on any card in Igneum's repository yet. Phase 2 measures it. +- Testnet. Proofs at testnet come from a network that is itself being tested. Expect missed deadlines and interface changes; the version number exists for that. +- No coin value. There is no coin at testnet and nothing in this brief is a sale of one. Mainnet settlement in the coin depends on the proof bridge, which is phase two of the execution design. +- Soundness. A soundness bug in the proof system is a risk for every SP1 user, Igneum included. Igneum's own blocks carry a native-execution veto; your chain's verifier should keep whatever fallback it has today. +- Market size. Rollup proving spend is small today, low millions of dollars a year, approximate. Igneum's edge is cost, because the cards already run on domestic power. That is an edge and nothing more. + +## Candidate first customers + +Taiko is the first target (CLAUDE.md). The rest are approximate, from memory as of the design date, and need a conversation to confirm. + +| Candidate | Why, in one line | +|---|---| +| Taiko | Named first target. Based rollup with a permissionless multi-proof design that already accepts SP1 proofs, so the interface is close to what exists. Approximate | +| Scroll | zkEVM rollup with its own prover stack and a public interest in outsourced proving capacity. Approximate | +| Linea | Consensys zkEVM with an in-house prover; a second supplier is a resilience story for them. Approximate | +| zkSync Era and ZK Stack chains | A family of chains on one prover design; one integration could serve several. Approximate | +| Polygon CDK and Agglayer chains | CDK chains with a type-1 prover path built on SP1, so the guest program may already match version 1. Approximate | +| Aztec | Rollup proving for a privacy chain; client proofs stay with users, the rollup proof is outsourceable. Approximate | +| OP Stack chains using OP Succinct | SP1 fault proofs on OP Stack chains are exactly the job shape Igneum's version 1 runs. Approximate | +| SP1 light-client bridges | Bridges built on SP1 light clients (the Helios class) need a steady proof supply at a known price. Approximate | +| Igra and Kasplex | EVM layers on Kaspa, the chain Igneum's node is forked from; shared tooling and a shared miner community. Approximate | +| Starknet | A different proof system today, so a longer road; worth one conversation about the versioned interface. Approximate | + +## Contact + +Through the repository once it is public (January 2027) or the team page at public testnet. Igneum is honest about what is measured and what is planned; ask for the bench log. diff --git a/docs/provenance.md b/docs/provenance.md new file mode 100644 index 000000000..620ab5ce2 --- /dev/null +++ b/docs/provenance.md @@ -0,0 +1,51 @@ +# 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). diff --git a/site/index.html b/site/index.html index b71fbc56d..65d9c8f45 100644 --- a/site/index.html +++ b/site/index.html @@ -270,7 +270,7 @@ footer .wrap{padding-block:48px 32px}

Watch the chain prove itself

-

Blocks arrive every second. Miners prove them in shards. A checkpoint locks every 30 seconds. All of it will be on this page, live.

+

Blocks arrive one a second at launch, rising as the proving layer allows. Miners prove them in shards. A checkpoint locks every 30 seconds. All of it will be on this page, live.

@@ -327,6 +327,7 @@ footer .wrap{padding-block:48px 32px}

RandomX proved that a random program beats a chip when the only hardware that runs it well is the hardware everyone already owns. Igneum does the same for the card in your PC, and makes the program keep moving without a human. Run the benchmark on your own card from the repository and post the number.

+

Built on the shoulders: Kaspa's GHOSTDAG and node, Monero's RandomX idea, Chia's class-group VDF, Ethereum's EVM, Succinct's SP1, BLS12-381 and Bitcoin's address format, each credited in public.
What changed, why, and how every change is measured: the provenance section of the litepaper.

@@ -436,6 +437,7 @@ footer .wrap{padding-block:48px 32px} Litepaper What Igneum does not claim Igneum vs RandomX + Built on the shoulders Engineering log