igneum-network/igneum
1
0
Fork 0
Code Issues Pull requests Releases Activity

Merge branch 'ledger-design' into fud-close

Browse source
This commit is contained in:
igneum-labs 2026-10-05 23:34:33 +00:00
commit 277710c4a9
5 changed files with 56 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/design/developer-adoption.md
View file

@ -197,6 +197,8 @@ What a builder expects on day one, what Igneum has, and the order to build the r
Order in one line: docs and templates first because they cost a day and nothing else is usable without them; the missing RPC methods second because the explorer and the debugger depend on them; a public endpoint, chain-id listing, wallet tests and faucet third; the explorer fourth; indexers fifth; the bridge after phase two; the audit before mainnet by rule.
Owner and gate (5 October 2026, night; ledger D5, round 2). The order is confirmed as written: step 1 the docs and the Hardhat and Foundry templates; step 2 `debug_traceTransaction`, `trace_block`, `eth_subscribe` and `eth_getProof`, with the `pending`, `safe` and `finalized` tags resolving by the four-state rule of design 2.4; step 3 a public devnet RPC with a rate limit, the chain-id listing on ethereum-lists/chains, the wallet tests of R11 and a faucet; step 4 the Blockscout fork. Owner: the execution engineer, for every step; the public docs site also waits on the public-repository decision (G11), which is the project lead's. Gate: no outside team is invited to build on the devnet before step 2 is done, and done means the methods answer on the devnet nodes with Foundry's debugger and the Blockscout fork running against them, not on a branch. The ledger's D5 entry carries the status of each step.
## 6. Ten reasons a sharp founder says no
Each answered or conceded. The conceded ones are ledger section 9, entries D1 to D6.

21
docs/design/phone-app.md
View file

@ -70,16 +70,19 @@ The app changes nothing on the rig. Start, stop, pool switching and overclocks s
### 4.1 What the Miners screen must show
Rules from the external review of 3 October 2026 (ledger X17, O-8.2). They bind the phone's display; the desktop client carries the same rules in O-8.2 and the isolation design in O-8.3.
Rules from the external review of 3 October 2026 (ledger X17, O-8.2), written out on 5 October 2026 (night, ledger close round 2) as the six display rules of the ledger's X17 answer. They bind the phone's display and the desktop client alike; the isolation rule behind the sixth is spec 8.8. "Ember 0.3.9 shows" names what the shipped app already displays, read from `app/igneum-app/ui/index.html`, `ui/app.js` and `src/state.rs`; "New" is what must be built, on the desktop first and then here.
| Rule | Display |
|---|---|
| Net earnings | Per card and per day, after an electricity tariff the user enters in Settings; the gross beside it; "estimate" until the pool or the chain has paid |
| Two incomes | Mining income (coinbase under the user's key) and proving income (proof records naming the user's prover key) in separate columns, never summed into one number without both parts visible |
| Failed jobs | Every failed or retried shard or job the pool or node reports, with its reason, as a list the user can open |
| Release state | The rig's running release and its hash, and any pending release the user has not accepted (spec 8.2 item 4), read from the node card's status lines |
| Isolation | The phone holds no proving job and no key; the Miners screen states that the desktop prover runs apart from the wallet (O-8.3) |
| States | Everywhere the app shows a transaction it uses the four words of `docs/design/execution-layer.md` 2.4 (included, executed, proven, finalised); the three-word status line of section 3 becomes four, and "finality not active" replaces finalised while spec 3.9's flag is false |
| Rule | Display | Ember 0.3.9 shows | New |
|---|---|---|---|
| 1. Net earnings | Per card and per day, after an electricity tariff the user enters in Settings; the gross beside it; "estimate" until the pool or the chain has paid | Hash rate per card and in total (`hash_now`, `hash_avg`), blocks accepted, power draw and the limit in force per card (`power_w`, `power_limit_w`), MH per watt (`eff_mhw`), the dev-fee share of the session. No earnings figure in IGN or in a currency, no tariff | The tariff field; per card per day the gross (blocks under the card's keys times the subsidy share, plus proving credit) and the net (gross minus `power_w` times hours times the tariff), always shown together |
| 2. Two incomes | Mining income (coinbase under the user's key) and proving income (proof records paid to the payout address) in separate columns, never summed into one number without both parts visible | Blocks found per card and in the last 10 minutes and hour; the proving tile's assigned, submitted and paid counts and `paid_wei` for the machine | Both incomes in IGN per card per day in the same card, the proving column from `paid_wei` by day and by card |
| 3. Compatibility and power | Per card: whether it can mine and whether it can prove, stated separately as the benchmark reports them (ledger P16), with the power limit in force, the card's default and the chosen cap | Card kind, vendor, VRAM, worker (Metal, CUDA, OpenCL), why a card is off by default (`reason`), the 80% NVIDIA default cap with the per-card slider and the efficiency sweep (`cards-power` note), the proving backend (CPU or CUDA) for the whole machine, "on a Mac the CPU prover is slow" | A proving line per card: can prove, CPU only, or cannot, with the measured shard time for that card model from the public benchmark when one exists and "not measured" otherwise; a card whose VRAM is under the measured proving peak (`docs/bench-log.md`) says it cannot mine and prove at once (decisions item 12) |
| 4. Failed jobs | Every failed or retried shard or job the pool or node reports, with its reason, as a list the user can open | The proving tile's `failed` count and the last `message`; the Events feed, newest first, with the prover's log lines | A list per shard or job with the reason the prover host returned, the retry count and time, kept across restarts |
| 5. Release state | The rig's running release and its hash, and any pending release the user has not accepted (spec 8.2 item 4), read from the node card's status lines | The running version (footer, Settings, the node's version beside the chain name); the update card with the pending version, its size, its notes, Install now and Later; the download's sha256 is checked against the signed manifest (`src/ota.rs`) but not displayed | The running binary's hash and the pending release's hash on the card and in Settings, beside the reproduction line of spec 8.1 item 2 |
| 6. Isolation | The phone holds no proving job and no key; the Miners screen states that the desktop prover runs apart from the wallet, under the OS user or sandbox spec 8.8 names, and when its escape test last passed | The proving tile's note ("this machine proves the shards the chain assigns to its keys"); nothing about keys. In 0.3.9 the prover host and the signer run under the same OS user as the wallet (spec 8.8, status paragraph) | The statement, the OS user or sandbox, and the escape-test date (O-8.3) |
| States | Everywhere the app shows a transaction it uses the four words of `docs/design/execution-layer.md` 2.4 (included, executed, proven, finalised); the three-word status line of section 3 becomes four, and "finality not active" replaces finalised while spec 3.9's flag is false | | |
Measurement: O-8.2 checks rules 1 to 5 against the pool protocol's `stats` and the node card on the phase 4 devnet; O-8.3 is the escape test of spec 8.8 item 5. Fields the pool protocol and the node card do not yet carry are open item P8 of section 11.
## 5. The node card

30
docs/fud-ledger.md
View file

@ -323,7 +323,7 @@ Evidence: design doc "Unit economics of a proof"; litepaper "What Igneum does no
### P3. A phone verifies in milliseconds is a SNARK-wrapper claim
"Hash-based STARK proofs are hundreds of kilobytes and take real work to verify. Milliseconds on a phone means a Groth16 or Plonk wrapper, and wrapping SP1 proofs needs a big machine for minutes."
Status: Open (the wrapper on consumer hardware, phase two), text stated (5 October 2026, night): `site/litepaper.html`, Proving, "Wrapped for light clients, a phone checks it in milliseconds; the wrapping cost is a phase two measurement", followed by the certificate-half numbers (139 to 155 ms cold, 58 to 68 ms warm, laptop core, no phone) from `docs/bench-log.md` "FUD ledger sweep round 6", P3. Was: Open, the certificate half measured in a phone-sized tab, the wrapper half unmeasured and unbuilt (5 October 2026, evening sweep). Was: Open, experiment scheduled. Sweep (5 October 2026): hardware item (the wrapper on consumer hardware); not runnable here.
Status: Open, blocked on phase 2 (the Groth16 or Plonk wrapper of the SP1 compressed proof is unbuilt; the certificate half is measured): next measurement the phase 2 benchmark, design R4 (Nov 2026 to Jan 2027 per the litepaper roadmap), a wrapped segment proof timed on a 12 GB and a 24 GB card and verified on a phone. Was: Open (the wrapper on consumer hardware, phase two), text stated (5 October 2026, night): `site/litepaper.html`, Proving, "Wrapped for light clients, a phone checks it in milliseconds; the wrapping cost is a phase two measurement", followed by the certificate-half numbers (139 to 155 ms cold, 58 to 68 ms warm, laptop core, no phone) from `docs/bench-log.md` "FUD ledger sweep round 6", P3. Was: Open, the certificate half measured in a phone-sized tab, the wrapper half unmeasured and unbuilt (5 October 2026, evening sweep). Was: Open, experiment scheduled. Sweep (5 October 2026): hardware item (the wrapper on consumer hardware); not runnable here.
Sweep (5 October 2026, evening): what the homepage verifier measures is a BLS certificate, not a SNARK: `site/verify/core.js` recomputes 21 header hashes (BLAKE2b), checks the voter list's canonical order, sums the 16 signers' G1 keys and checks one BLS12-381 aggregate signature, in pure JavaScript (`@noble/curves` 2.4.0). Measured tonight on `https://igneum.network/verify/test.html` against the live checkpoint 3668 (16 of 21 signers, 72.3% of weight): in the built-in browser pane's mobile emulation (375 x 812, an Android user agent, three loads) the genuine certificate verified in 139.1, 150.2 and 155.3 ms cold and 68.3, 58.4 and 64.8 ms warm; the same page at desktop size on the same machine 151 and 63.3 ms. Emulation changes the viewport and the user agent and nothing else: the CPU is this M5 Max under a load average above 100 (two builds and the C4 harness running), so the mobile and desktop numbers are the same number, and the 15 to 66 ms of `docs/plans/morning-2026-10-04.md` is the same laptop idle. What is NOT measured: any phone (a 2024 phone core is 2x to 4x slower than this laptop core on scalar JavaScript, approximate, so 150 to 600 ms cold for the certificate alone); and the thing the critic names, the wrapped block proof. No wrapper exists: the light verifier of the pinned SP1 compressed proof takes 1.3 to 2.1 s of setup plus 2 to 108 ms per verify on this Mac (bench-log 5 October, "the program id split"), is a 58 MB native binary, and a Groth16 or Plonk wrap of it is unbuilt (phase 2 benchmark). The litepaper's phone claim stays "wrapped for light clients" until the wrapper is measured on a phone.
@ -331,6 +331,8 @@ Answer: Correct. The light-client proof is the aggregated block proof wrapped on
Evidence: not yet. Fix: overclaims list, item 25.
Round 2 (5 October 2026, night): status made terminal-explicit. Blocker: the wrapper (design 5.6 `wrap`, R4) does not exist in the repository; the light verifier of the pinned compressed proof is a 58 MB native binary (bench-log 5 October, "the program id split"). Next date: the phase 2 benchmark. Nothing else in the entry changes.
### P4. Trustless light clients need a consensus proof you do not have
"Checking 'one proof and one locked checkpoint' means verifying a BLS certificate against two thirds of active 30-day weight. Computing that weight needs 30 days of headers. Your own review scoped the consensus proof as phase two. The litepaper sells it at launch."
@ -1490,13 +1492,15 @@ Evidence: `infra/cloud-devnet/results/2026-10-04/partition-sin-20261004-140305/p
### P16. The proving gate can be passed by shrinking the shard
"'A mid-range GPU proves a shard in under 20 s.' Your own R2 says: if missed, halve the shard and re-measure. That is the trap. Fix the workload first, measure the whole journey, and have strangers reproduce it."
Status: Open, experiment scheduled (O-7.1). The journey's phase 2 gate was rewritten the same night. Sweep (5 October 2026): hardware item (the 12 GB card end to end); the standard is written.
Status: Open, blocked on a 12 GB card (decisions item 12, already pointed: a 3060-class NVIDIA part for PC 2 before the public benchmark): next measurement O-7.1 end to end on that card when it arrives, inside the phase 2 gate (Nov 2026 to Jan 2027 per the litepaper roadmap). Was: Open, experiment scheduled (O-7.1). The journey's phase 2 gate was rewritten the same night. Sweep (5 October 2026): hardware item (the 12 GB card end to end); the standard is written.
Decision owner: the project lead (a 12 GB card for the end-to-end run). Decision request: `docs/plans/ledger-decisions.md`, item 12 (5 October 2026, night).
Answer: Correct. P1 conceded that the 20-s figure is a target; this is about how the target is tested. `docs/design/execution-layer.md` 9.1 R2 passes at any shard size by halving `S_p` until the time fits, so a pass says nothing about throughput, and R4 measures the wrapper only. The phase 2 benchmark now has an acceptance standard: a fixed published workload (real transactions, never empty blocks or tiny shards) with its shard plan, proven end to end from job received to proof accepted, including queueing, transfers, aggregation, verification and payment; the median and the slowest 5% and 1%; failure and retry rates; full cost (electricity, host, bandwidth, aggregation, failed work, hardware); results per advertised card with mining and proving compatibility stated separately; sustained with no growing backlog; reproduced by at least three unrelated operators from the published code and configuration. A halved shard is a new declared workload, never a pass. The reviewer's figure for SP1's cluster requirement (NVIDIA, 24 GB, approximate; not checked, SP1 is not in `vendor/`) is why a 12 GB card has to show the whole pipeline, which R2 and R4 already target.
Evidence: P1; execution-layer 9.1 R2 and R4; `docs/bench-log.md` (no shard has been proven on any card). Experiment: O-7.1. Review: external, point 1.
Round 2 (5 October 2026, night): status made terminal-explicit. Blocker: no 12 GB card is on the fleet (the cards measured so far are listed in `docs/bench-log.md`; the 5090 is not the gate's card, litepaper Proving). The acceptance standard in the Answer is unchanged and is what the card runs when it arrives. Next date: the phase 2 gate.
### P17. Interfaces must show four states, and the design shows three
"Included, executed, proven, finalised are four different facts. Your status call returns executed, proven, locked and a list of blocks. A wallet that shows a balance at 'included' is lying by omission."
@ -1578,12 +1582,14 @@ Run (5 October 2026, night): `tools/lock/with-lock.sh run node tools/finality-at
### X15. Remove the founders from a test network and show what continues
"'The chain runs without its founders' is a sentence. Take the team's miners, provers, aggregators, seed nodes, observer and site off a running testnet and show what keeps producing blocks, proofs and locks."
Status: Open, experiment scheduled (O-X.2). Sweep (5 October 2026): a public-testnet experiment; not runnable before it exists.
Status: Open, blocked on the public testnet (August 2027 per the litepaper roadmap): next step O-X.2 run at a published time on that testnet, with the protocol already in the Answer below (every project-run node, miner, prover, aggregator and seed stopped, the observer and live page down, 24 hours of blocks per second, proof lag, certificates per hour and a fresh sync from the shipped seed list). Was: Open, experiment scheduled (O-X.2). Sweep (5 October 2026): a public-testnet experiment; not runnable before it exists.
Answer: Correct, and it is the right test for the litepaper's sentence (Governance). The test: on the public testnet, at a published time, stop every node, miner, prover, aggregator and seed node the project runs, take the observer feed and the live page down, and record for 24 hours: blocks per second, proof lag, certificates per hour, and a fresh node syncing from the seed list in the client (spec 10.6). What continues is what the sentence may claim. Dependencies the test will expose: the seed list, the release key (G7), the reference pool, the VDF evaluators (every node ships one, 4.5) and the founders' own hashrate share (E2).
Evidence: `site/litepaper.html` Governance; spec 10.6, 4.5; G7, E2. Experiment: O-X.2, before mainnet. Review: external, point 6.
Round 2 (5 October 2026, night): status made terminal-explicit. Blocker: the test needs a network the project does not run alone, which exists from the public testnet (phase 5, Aug to Oct 2027 on the litepaper roadmap). Next date: a published time in that window, before mainnet. The devnet cannot stand in: its nodes are all the project's (developer-adoption section 5, RPC providers row).
### X16. An evidence page with four labels
"Every claim needs a status, a software version, the test that produced it, the result and whether anyone outside reproduced it. 'Implemented', 'tested by the team', 'reproduced externally' and 'reviewed independently' are four different things, and your bench-log uses one voice for all of them."
@ -1596,12 +1602,14 @@ Evidence: `docs/bench-log.md`; `docs/spec/README.md` labels; G2. Publication: O-
### X17. The miner app must show net earnings and keep jobs away from keys
"Show me what a card earns after my electricity tariff, mining and proving separately, which jobs failed and why, which release I am on and whether I accepted it, and promise that a proving job can never read my wallet. Your spec covers the update and the seed, and nothing else on that list."
Status: Open, design and measurement scheduled (O-8.2, O-8.3); update control and the seed are answered by design (spec 8.2 item 4, 8.5). Sweep (5 October 2026): design and devnet items (O-8.2, O-8.3); nothing runnable.
Status: Designed (5 October 2026, night): spec 8.8 and phone-app 4.1; measurement O-8.2 and the escape test O-8.3 scheduled for the phase 4 devnet. Was: Open, design and measurement scheduled (O-8.2, O-8.3); update control and the seed are answered by design (spec 8.2 item 4, 8.5). Sweep (5 October 2026): design and devnet items (O-8.2, O-8.3); nothing runnable.
Answer: Update control and the seed are decided (spec 8.2 item 4: no silent updates, the user accepts each release; 8.5: seed confirmed, hardware wallet). The litepaper promises earnings "in IGN and in your currency" and M13 promised projected earnings before mining starts; neither nets off power. New requirements for the official client and the phone monitor: (a) net earnings per card after an electricity tariff the user enters, the gross beside it; (b) mining income and proving income reported separately, per card and per day; (c) hardware compatibility and power limits per card, with mining and proving capability stated separately as the benchmark reports them (P16); (d) every failed or retried job visible with its reason; (e) the running release, its hash and any pending release the user has not accepted; (f) isolation: proving jobs run guest programs supplied by strangers, so the prover process holds no wallet key, no seed and no vote key, runs under a separate OS user or sandbox, and reaches the signer only through a local socket that signs payout claims and nothing else, designed and reviewed before the first external job runs. The phone app carries (a), (b), (d) and (e) as display rules (phone-app 4.1).
Evidence: spec 8.2, 8.5; `site/litepaper.html` For miners; M13; `proto-cuda/windows-app/README.txt`. Experiment: O-8.2 (display rules measured against the pool protocol's `stats` on the phase 4 devnet), O-8.3 (isolation design reviewed, then an escape test with a hostile guest program). Review: external, point 7.
Round 2 (5 October 2026, night): the isolation rule is written as `docs/spec/08-client-security.md` 8.8, labelled Designed: the prover process holds no wallet key, seed or vote key; it runs under a separate OS user or sandbox (a WSL2 distribution without the data directory on Windows); it reaches the signer only through one local socket that signs proof records and payout claims for work the engine handed out and nothing else; the escape test is a hostile guest program on the phase 4 devnet that tries the wallet file, the environment, the engine's memory, outbound connections and the signer's refused messages, passing when every attempt fails and the wallet file is byte-identical; the user is told on the tile and in Settings. The six display rules are written in `docs/design/phone-app.md` 4.1 against what Ember 0.3.9 already shows (hash rate per card and total, blocks, cards with VRAM, worker and the off-by-default reason, the 80% NVIDIA power cap with the slider and the efficiency sweep, the proving tile's assigned, submitted, paid and failed counts, the running version, the update card with version, size and notes) and what is new (the tariff and net earnings per card per day with the gross beside it; mining and proving income in separate columns per card per day; a proving line per card stating can prove, CPU only or cannot, with the measured shard time or "not measured"; the failed-job list with reasons and retries; the release hash on the card and the pending release's hash; the isolation statement with the escape-test date). Fact found while reading the app: in 0.3.9 the engine spawns the prover host and the record signer under the same OS user as itself (`app/igneum-app/src/prover.rs`), the wallet is `wallet.json` under that user (`src/keys.rs`) and the vote keys derive from the worker label the engine passes `igneum-miner` (`src/engine.rs`), so a guest program today runs as a user that can read all three; 8.8 changes that before the first external job. No app code was written in this round.
## Execution attack findings (4 October 2026): fixed
### P18. The mempool queues transactions no block can carry
@ -1652,13 +1660,17 @@ Decision owner: the project lead. Decision request: `docs/plans/ledger-decisions
Answer: Correct for v0, and by design for now. The consensus check on a carried record is the native-execution veto (spec 7.2 item 5): the statement must equal the node's own 328-byte shard statement for that shard and payout address, so no record can move state or pay for a wrong claim. The SP1 proof is verified off the consensus path by the proof pool's verifier (`igneum-prove-host --mode verify`), and a producer offers only verified records to its templates; a producer that includes unverified records (trust mode, test networks only) can pay a prover who did not prove. The damage is bounded to that prover's payout. What closes it: the aggregated segment record of design 5.4 verified in consensus, which needs the SP1 verifier inside the node (the SDK dependency the node does not carry today) or a bounded in-consensus verification budget. Until then the devnet runs v0 with every producer verifying.
Round 2 (5 October 2026, night): the public text now carries the v0 fact, labelled Open: `site/litepaper.html`, Proving, "How a block gets proven": "Open: in proving v0 the SP1 proof itself is checked off the consensus path, by every block producer before it carries a record, and the native-execution check is what consensus enforces; whether the SP1 verifier moves inside consensus is a decision before the public testnet." Status unchanged: decision owner the project lead, decisions item 11.
### P22. The rewards and payouts are inputs to the shard proof, not outputs
"The shard guest takes the segment's rewards and the prover payouts as data and commits the post-root after them. A host can feed any list and the proof still verifies."
Status: Open, stated in spec 7.7 item 6 (4 October 2026). Sweep (5 October 2026): stated; nothing runnable.
Status: Open, blocked on the phase 2 consensus proof (design 7: the aggregator derives the rewards and payouts from consensus data it verifies, so they become outputs of the proof): next step that consensus-proof work, in phase 2 (Nov 2026 to Jan 2027 per the litepaper roadmap), no earlier date. Was: Open, stated in spec 7.7 item 6 (4 October 2026). Sweep (5 October 2026): stated; nothing runnable.
Answer: Correct, and already true of the rewards since devnet v4 (`BlockFixture.rewards`, `proving_pool_credit`): the shard statement is "from this pre-root, these transactions, these rewards and payouts, the post-root is X". The node checks the statement against its own execution, which used the rewards and payouts consensus derived, so a proof over a different list does not match any node's statement and pays nothing. Closing it in the proof itself means the aggregator deriving the rewards and payouts from consensus data it verifies (the mergeset's blue blocks and the carried records), which is the consensus-proof work of design section 7.
Round 2 (5 October 2026, night): status made terminal-explicit. Blocker: until the consensus proof of design 7 exists, the rewards and payouts stay data inputs to the shard statement (spec 7.7 item 6) and the node's own derivation is the check. Next date: phase 2. The D6 review of this round names the same class for job outputs, where no consensus derivation exists to check against (`docs/review/d6-forged-job-result-2026-10-05.md`, section 1).
## Status updates, 4 October 2026 (branch fin-fixes, commit da1eb889)
- **F17** (keys are free, the draw is per key). Status: Fixed in the node (4 October 2026). `is_aggregator` draws the 8 aggregators by weight, `output x total < 8 x weight x 2^64`, so a splitter holds the tickets its weight buys and no more; spec 3.10 S1 row; unit test `sortition_is_by_weight_not_key_count` (200 dust keys plus 6 real ones); attack harness scenario 2 re-run: honest keys drew 1.61 seats per crowded checkpoint against 1.55 expected by weight, where master drew 0.32 against 0.33 per key (`docs/bench-log.md`, "finality fixes F17 and F1"). Still open from this entry: the client's one-key default, S2 (O-3.5), the bitmap size (O-3.12). Was: Rule fixed (spec 7.2 and W6), node per key.
@ -1729,21 +1741,25 @@ Evidence: spec 7.3; ledger E7; `docs/review/round-3-2026-10-03.md` line 344.
### D5. I cannot debug a revert
"No `eth_subscribe`, no `debug_traceTransaction`, no `eth_getProof`, no explorer, no public RPC, no faucet, `finalized` resolves to the executed tip. You are inviting builders to a chain they cannot inspect."
Status: Conceded, scheduled. Sweep (5 October 2026): unchanged on the `proving` branch (no `debug_*`, `eth_subscribe` or `eth_getProof` in `igneum/exec/src/rpc.rs`); scheduled work, execution engineer.
Status: Conceded, scheduled (5 October 2026, night): `docs/design/developer-adoption.md` section 5, owner and gate named (the execution engineer; no outside team is invited before step 2 is done). Was: Conceded, scheduled. Sweep (5 October 2026): unchanged on the `proving` branch (no `debug_*`, `eth_subscribe` or `eth_getProof` in `igneum/exec/src/rpc.rs`); scheduled work, execution engineer.
Answer: Correct on every item on 4 October 2026 (`docs/design/execution-layer.md` 10.3 items 1, 6, 7). The order in `docs/design/developer-adoption.md` section 5: docs and the Hardhat and Foundry templates first; `debug_*`, `eth_subscribe` and `eth_getProof` second, because the Blockscout fork and Foundry's debugger need them; a public devnet RPC, the chain-id listing on ethereum-lists/chains, wallet tests (R11) and a faucet third; the explorer fourth. No outside team is invited before the second step is done.
Evidence: `docs/design/execution-layer.md` 10.1 (RPC table, "Missing"), 10.3; design 8.1, 8.4, R10, R11.
Round 2 (5 October 2026, night): the order in `docs/design/developer-adoption.md` section 5 is confirmed and the paragraph "Owner and gate" added below its table: step 1 the docs and the Hardhat and Foundry templates; step 2 `debug_traceTransaction`, `trace_block`, `eth_subscribe` and `eth_getProof` with the four-state tags; step 3 a public devnet RPC, the chain-id listing, the wallet tests of R11 and a faucet; step 4 the Blockscout fork. Owner: the execution engineer for every step, the docs site also waiting on the public-repository decision G11. Gate: no outside team is invited to build on the devnet before step 2 is done, with done meaning the methods answer on the devnet nodes under Foundry's debugger and the Blockscout fork, not on a branch.
### D6. A forged job result reaches my contract and nobody vetoes it
"Segments have the native-execution veto. Jobs do not: full nodes cannot re-run an arbitrary program, so for a precompile job the proof is the only check. A soundness bug in SP1 writes whatever the attacker wants into my callback."
Status: Conceded, contained by rule, review scheduled. Sweep (5 October 2026): a review item (R12 with the cryptographer); nothing runnable.
Status: Conceded, contained by rule, reviewed (5 October 2026, night): `docs/review/d6-forged-job-result-2026-10-05.md`. Next step: the three devnet checks of that review's section 6 (containment under a deliberately broken verifier; the version gate and the overlap; the callback boundary), on the phase 4 devnet once the precompile of design 6 exists (design 10.3 item 5). Was: Conceded, contained by rule, review scheduled. Sweep (5 October 2026): a review item (R12 with the cryptographer); nothing runnable.
Answer: Correct. Design 6 says it in those words. The containment: a job output cannot mint IGN or touch system contracts (R12), jobs are gated behind the proof-system version with the three-month overlap and the 90% signal (design 5.6), and the emergency path for a live soundness bug is the version bump of spec 5.7. The rule for an app, the same one the customer brief gives rollups: anything that acts irreversibly on a job output keeps its own fallback. R12 is reviewed with the cryptographer before devnet v2.
Evidence: `docs/design/execution-layer.md` 6, 5.6, 9.1 R12; spec 5.7; ledger P7; `docs/commercial/prover-customer-brief.md` "Risks".
Round 2 (5 October 2026, night): reviewed by the cryptographer agent, `docs/review/d6-forged-job-result-2026-10-05.md`. The attack as reviewed: a soundness bug in the proof system version in force lets a prover sign a job statement with a chosen output; the native-execution veto cannot catch it because every full node consumes the output as an input to `onProof` and computes the same root (design 6, 5.5), so the chain is consistent and wrong in one place. What the rules guarantee: no IGN is minted (emission and the pool are state transitions from consensus data, design 1.1 and 4.4; the only IGN moved is the job's escrow, 90% to the forger and 10% burned, design 6); no system contract is written except the job's own result slot in `Prover` (design 4.5, 6), so R12's "touch system contracts" wording needs that narrower sentence; the version gate (design 5.6, steps 1 to 5) and the emergency bump (design 5.5, spec 5.7) close a bug for good. What they do not: the callback's own state and everything downstream of it; the window between disclosure and activation, in which nothing pauses jobs and the 3-month overlap keeps a known-broken verifier reaching callbacks unless job records of the old version are cut at activation (the review's recommendations 2 and 3); the forger's payout; light clients, which agree with full nodes here. The rule for an app (review section 4): a job output is one party's word, and anything irreversible it drives keeps a fallback the app controls (a delay longer than the emergency activation time, a value cap, a second check, or a human veto). Design changes asked: the containment as a normative rule with the precise boundary; job records of version N invalid from the activation of N+1; the emergency release may cut jobs at activation while keeping the segment overlap; the prover is paid when the callback reverts. Devnet checks named (review section 6, phase 4): a job forged against a deliberately broken verifier, with the IGN total, the registry and `Prover` storage compared before and after; the swap procedure in fast time with version-N job records at each stage, the exposure window counted in blocks; four callbacks at the boundary (re-entrant request, past the stipend, reverting, and the app rule with a delay and a second check).
## Round 4 entries (4 October 2026, afternoon): what is live
Review: `docs/review/round-4-2026-10-04.md`. Scope: devnet v4 through `a21ff239` (HEAD `3bfe346f`), the prebuilt workers, the Igneum Miner app 0.3.1 to 0.3.3, the relay, the Windows CI, the downloads host, the live site and the economics after the day's measurements. No secret value appears in any entry; comparisons were count-only.

18
docs/spec/08-client-security.md
View file

@ -60,3 +60,21 @@ The two findings it answers. An app that auto-updates on ten thousand machines i
1. The official client MUST NOT let an environment variable, a setting or an update change a consensus parameter on mainnet or testnet. The node it wraps ignores `IGNEUM_POW_*` outside devnet and simnet and refuses the override file on mainnet (section 2.8); the app passes an override file only to a devnet or simnet node, and the packaged file (`node_override_params`) exists for the devnet's height switches alone.
2. A node refuses any peer whose consensus params digest differs from its own (section 2.8). The client SHOULD show the digest its node printed at start, so an operator can compare two machines by eye (not built yet); a refused peer is reported by the node's log line, never silently.
## 8.8 Proving jobs and the keys (Designed, 5 October 2026, night; ledger X17, O-8.3)
Status: Designed. Not implemented. In Ember 0.3.9 the engine process spawns the prover host (`igneum-prove-host`) and the record signer (`igneum-miner sign-record`) itself, under the same OS user, from `app/igneum-app/src/prover.rs`; the payout wallet is `wallet.json` in the app data directory with its permissions locked to that user (`app/igneum-app/src/keys.rs`); the vote keys are derived by `igneum-miner` from the worker label the engine passes it (`app/igneum-app/src/engine.rs`, the label comment above the worker spawn). A guest program proven on that machine therefore runs as a user that can read all three. The rules below change that before the first external job (design document section 6) runs on any client the project ships. They bind shard proving the same way, because a shard proof runs the chain's own guest and a job runs a stranger's.
1. The prover holds no key. The process that runs a guest program (the prover host, and on Windows the WSL2 distribution it runs in) MUST NOT hold, read or be able to read the payout wallet, the seed, the vote keys or any release key material. It receives shard or job inputs and returns proof bytes and a statement, nothing else.
2. A separate OS user or sandbox. The prover host runs under its own OS user (Linux, macOS) or inside a WSL2 distribution with no mount of the app data directory (Windows), with no read access to the engine's data directory and no write access outside its own work directory. Where the platform offers a sandbox (macOS App Sandbox, a Linux user namespace or seccomp profile, Windows AppContainer), the client uses it in addition to the user split, never instead of it.
3. One local socket, one kind of message. The engine exposes a signer to the prover over a local socket (a Unix domain socket, a named pipe on Windows) that accepts exactly one request: sign a proof record (the 274-byte record of section 7.7 item 1) or an external-job payout claim, for a shard or job the engine itself handed to this prover, with the payout address the user configured. The signer refuses any other message, any record for work the engine did not hand out, any payout address other than the configured one, and any request rate above what the machine can prove. It never signs a transaction, a vote, a signalling bit or a release.
4. The vote key stays with the engine. Voting (section 3) and signing records are the engine's work; the prover never sees the vote key. The app shows the vote key as a mining key and never as a wallet (8.5 item 4).
5. The escape test (O-8.3). Before the first external job runs on a shipped client, and again at every release that touches the prover, the project runs a hostile guest program on the phase 4 devnet: one that tries to read the app data directory, the wallet file, the process environment and the engine's memory, to open outbound connections, and to send the signer a transaction, a vote and a record for work it was not handed. The test passes when every attempt fails and is logged, the wallet file is byte-identical before and after, no outbound connection other than the proof submission opens, and the signer's refusal count equals the number of hostile requests. A release whose escape test has not passed on every platform it ships for does not ship with proving on by default.
6. What the user is told. The client states on the proving tile and in Settings that the prover runs apart from the wallet and holds no key, naming the OS user or sandbox it runs under and the date its escape test last passed; the phone app repeats the statement (`docs/design/phone-app.md` 4.1, Isolation).
| Parameter | Value | Label |
|---|---|---|
| Keys readable by the prover process | none | Designed |
| Prover isolation | separate OS user, or a WSL2 distribution without the data directory; a platform sandbox in addition | Designed |
| Signer interface | one local socket; proof records and payout claims for handed-out work only; nothing else signed | Designed |
| Escape test | hostile guest program on the phase 4 devnet, before the first external job and at every prover release | Designed (O-8.3) |

2
site/litepaper.html
View file

@ -447,7 +447,7 @@ body.all .pager{display:none}
<h2>Proving: the miners are the provers</h2>
<p>Every Igneum block is proven with a zero-knowledge proof, and the miners produce it. Proving is a useful GPU workload that is cheaply verifiable by construction. A proof is right or it is not. Wrapped for light clients, a phone checks it in milliseconds; the wrapping cost is a phase two measurement. Measured so far, the certificate half only: the browser verifier on the home page checks a devnet finality certificate, one BLS aggregate signature over 16 keys and 21 header hashes, in 139 to 155 ms cold and 58 to 68 ms warm in a phone-sized tab on a laptop core (5 October 2026). No phone has been measured, and no wrapped block proof exists yet.</p>
<h3>How a block gets proven</h3>
<p>Blocks carry transactions only and make no claim about state. Every node executes the ordered transactions natively at once, so users see their transaction land in about a second. The execution is then split into shards of a fixed proving cost. Shards are assigned by lot to eight provers for ten seconds, then open to anyone; there is no bond. Provers run them on consumer cards, and the shard proofs are folded by recursive aggregation into one proof for the block. That proof lands on-chain within about a minute at launch. Because the proof computes the state from the ordered sequence, no node accepts a block with a wrong state root. Full nodes also execute every block natively and reject a proof record whose result differs from their own execution, so a forged proof is a light-client problem and never a chain split. Implemented: the native-execution check on every carried proof record, proving v0 on the devnet (specification section 7). The emergency path for a soundness bug in the proof system is a human one: a new proof-system version is written by people and activates only on miner signalling. Invalid transactions are skipped by rule, the way Kaspa skips conflicting spends.</p>
<p>Blocks carry transactions only and make no claim about state. Every node executes the ordered transactions natively at once, so users see their transaction land in about a second. The execution is then split into shards of a fixed proving cost. Shards are assigned by lot to eight provers for ten seconds, then open to anyone; there is no bond. Provers run them on consumer cards, and the shard proofs are folded by recursive aggregation into one proof for the block. That proof lands on-chain within about a minute at launch. Because the proof computes the state from the ordered sequence, no node accepts a block with a wrong state root. Full nodes also execute every block natively and reject a proof record whose result differs from their own execution, so a forged proof is a light-client problem and never a chain split. Implemented: the native-execution check on every carried proof record, proving v0 on the devnet (specification section 7). Open: in proving v0 the SP1 proof itself is checked off the consensus path, by every block producer before it carries a record, and the native-execution check is what consensus enforces; whether the SP1 verifier moves inside consensus is a decision before the public testnet. The emergency path for a soundness bug in the proof system is a human one: a new proof-system version is written by people and activates only on miner signalling. Invalid transactions are skipped by rule, the way Kaspa skips conflicting spends.</p>
<h3>The proving budget</h3>
<p>Gas prices execution. Proving cost is a different number, so Igneum meters it separately: every transaction pays in both dimensions, and each block has a proving-cost budget set in consensus from measured prover throughput. A transaction that is cheap to run and expensive to prove pays for what it costs the provers. Target: shard size will be set so a 12 GB card proves one shard in about 20 seconds. That number is the phase 2 gate on the roadmap and is not measured yet on the card the gate names. The first proofs exist: on 4 October 2026 an RTX 5090 proved a small two-transaction block in 1.4 seconds (2.7 seconds compressed), verified in 0.22 and 0.038 seconds, and a laptop CPU proved a three-shard block end to end in 19 minutes. Later that day the same card proved a full shard at the provisional size, 6.75 million prover gas, which executed in 60.8 million cycles: core proof 8.3 seconds, compressed proof 10.9 seconds, verified in 0.040 seconds; a four-shard block took 44.5 seconds of GPU stages end to end. Since 5 October 2026 shards are assigned and proven on the live devnet. The gate asks for a mid-range card, and an RTX 5090 is not one, so the gate stands open. Once the gate is measured, the budget rises by schedule as hardware improves. The proof system is hash-based, which is what runs on consumer cards, and sits behind a versioned interface, so Igneum can adopt a better proof system when one exists by a miner-signalled release, and runs for ever on the current one if none is adopted.</p>
<h3>Proving for everyone else</h3>