igneum/CLAUDE.md

Igneum

A GPU-mined layer 1 whose miners are also the ZK provers for its own zkEVM and for other chains. Josh Malone's project, started 3 October 2026. Named Igneum (Latin: fiery, proven by fire) on 3 October 2026. Repo, Vercel project and Neon database are all "igneum".

Source of truth

The design document (Claude Doc "Igneum", formerly "GPU Prover Network") plus the public litepaper (https://claude.ai/code/artifact/edcf47f6-e918-48c7-95c3-b98e0d65583f) and the brand canvas (https://claude.ai/artifact/CPixnvctTKbrwBwWck3iFj): https://claude.ai/code/artifact/08fa9e06-9240-4964-96f4-76ff1d2f796c Read it with the docs tools before any design discussion. Decisions already taken live there (hard cap 4 billion halving every two years, 80/20 lottery/proving split, NO emission treasury, NO dev fund (removed 3 Oct 2026: the protocol carries no fee to any team, foundation or fund; priority fee 80/20 miners-and-provers/app, external jobs 90/10 provers/burn, 60% signalling kept only for parameters genesis leaves to miners), no stake, miner-only self-contained finality (NO Bitcoin anchoring), 1 block/s at launch, SP1 behind a swappable proving interface, Taiko as first proving customer, 30-day launch ramp).

The design in one paragraph

Leader election by a random-program GPU hash (RandomX idea rebuilt for GPUs, new kernel each ~1h epoch, era parameters drawn automatically every 6 months from chain state inside rules fixed at genesis, NO scheduled human releases; dataset grows on a genesis-fixed schedule and instruction families unlock by height from a genesis reserve (automatic anti-ASIC escalators); only writing new code is human, via 90% miner signalling, never required; warp-unit CPU-verifiable). Ordering by a GHOSTDAG BlockDAG forked from rusty-kaspa. Execution by a zkEVM. Every block ZK-proven by miners in chunks, aggregated 20 to 60 s behind the tip at launch (target under 10 s as provers improve). Finality is miner-only and self-contained: FINALITY RULE V2 (review round 2, 3 Oct 2026): vote weight = blue blocks per BLS vote key (in header) over a flat 30-day DAA window, no damping (the 2x cap was Sybil-void), dust threshold 100 blocks; every voter signs every 30-s checkpoint (VRF picks 8 aggregators only); lock = 2/3 of ALL 30-day weight (DECIDED 4 Oct 2026, O-3.15: the floor was raised from 56.7% of total to 2/3 of total, which makes the 2/3-of-active test implied; finality pauses whenever under 2/3 of the window is connected and signing, and the node reports it; the old floor 0.85 x 2/3 had been added after sim v2 showed the bare active denominator locks both sides of a 50/50 partition after 60 min; with the floor: 0 conflicting locks in every partition and eclipse scenario); equivocation evidence strips weight 30 days; fork choice = GHOSTDAG among tips through all certified checkpoints under Kaspa merge-depth 3,600 s; NO hidden-block n^2 penalty (removed, breaks DAG determinism); epoch seed = 10-min class-group VDF of a certified checkpoint, era draw = 1-h VDF; dataset = 256 MB RandomX-style cache, 8 dependent reads per item (not closed-form, not 64 MB); fees: base fee burned in full on both gas dimensions, priority fee 80/20 (miners and provers / app, attributed per call frame, unregistered share burned), external jobs 90/10 (provers / burn), no dev fund and no fee to any team. Headline: 10 days of 100% hashrate to reach 1/3 of weight, 20 days for 2/3; 51% never reaches 2/3 while honest miners stay. NO stake and NO other chain anywhere in consensus (Bitcoin anchoring was considered on 3 Oct 2026 and REJECTED by Josh: no reliance on Bitcoin). The same prover network sells proofs to rollups and bridges, priced in dollars, settled in the token. The lottery and the proving are kept separate on purpose (Aleo lesson).

The team, as agents

Each role from the design doc's build plan is an agent in .claude/agents/. Ask them by name.

• cryptographer: lottery hash, chunked proving protocol, proof systems, finality on a DAG. Owns gates 1 and 3.
• consensus-engineer: Rust, rusty-kaspa fork, GHOSTDAG, difficulty, P2P, the hash swap. Owns gate 2.
• execution-engineer: Rust, Ethereum clients, zkEVM integration, SP1, the proving interface, external job market.
• miner-community-lead: miner software, pools, launch ramp, what GPU miners will and will not accept. Owns gate 4. They review each other's work. A claim about another chain must cite the repo and file, or be labelled approximate.

Rules that apply to every agent and every file here

• Josh's copy law: no em dashes, no two-beat antithesis, no aphorisms. Short sentences. Numbers in tables.
• Figures from memory are labelled approximate. Figures from a source cite the source.
• The project is Igneum. Never claim an ASIC gain, a proving time or a market size without a measurement or a citation.
• Vendor source lives in vendor/ (git clones of rusty-kaspa, RandomX, SP1, decred dcrd, etc.). Read real code before describing it.
• Nothing here is a token sale and nothing should become one.
• Transactions are public, like Ethereum. Privacy features and shielded pools were considered and REJECTED by Josh on 3 October 2026. Do not add them.

Infrastructure (no URLs yet, by Josh's instruction)

• GitHub: https://github.com/igneum-network/igneum (organisation igneum-network, created 3 Oct 2026; owners igneum-josh (Josh, the igneum.network Google login) and joshmalone117; private, branch master). Commit as igneum-josh 337424239+igneum-josh@users.noreply.github.com (the repo's git config; standing rule 3 Oct 2026: the organisation owner is never publicly visible, so no personal name or email in the history; the 40 commits before this rule carry Josh's name and must be rewritten before the repo goes public). Push only when Josh asks. RENAMED 5 October 2026 (18:00 UTC, by Josh's decision): the owner login igneum-josh is now igneum-labs (GitHub rename; the noreply id 337424239 is unchanged, so the commit address becomes 337424239+igneum-labs@users.noreply.github.com at the fresh-repository step, docs/plans/rotation-phase-2.md 8g; until then commits keep the igneum-josh address). gh on this Mac still stores the token under the OLD name: gh auth token --user igneum-josh is the only way to read it until a re-login as igneum-labs. This checkout's .git/config (shared by every worktree) resets credential.helper and then adds one helper that returns username igneum-labs with that token, so git pushes from here work whichever gh account is active (the global gh auth git-credential helper answered first before this fix and handed out joshmalone117: "repository not found"). Before any gh call: gh auth status must show igneum-josh (the stored name) as the ACTIVE account (gh auth switch --user igneum-josh if not); the joshmalone117 login on this Mac belongs to other projects and has no access to this repository.
• Vercel project: igneum in the vivanmn team, because Vercel refuses the personal account as a scope. Move it to its own team when the venture is named. For the site, explorer and job-market API later.
• Neon database: igneum, id soft-voice-31914738, London (aws-eu-west-2), Postgres 17. Connection string in ~/.config/igneum/env, never in the repo.

Domains (purchased by Josh, 3 October 2026, registrar with "Full Protection"; nothing pointed yet)

igneum.net, igneum.io, igneum.network, igneum.info, igneum.store, igneum.online, igneum.app, igneum.co.uk, igneum.xyz. Also bought 3 Oct 2026 (Josh: "bought all the other domains"): igneum.org and igneum.com, so the full set is held. Applied 3 Oct 2026: all 15 Igneum domains at GoDaddy (also .art, .email, .pro, .shop, .vip) on Vercel nameservers (ns1/ns2.vercel-dns.com) and attached to the Vercel project igneum: igneum.network is the primary site, every other domain 308-redirects to it. igneum.com is still on Afternic nameservers (purchase in transit), attach when it arrives. Site source: site/ (static). Since the evening of 3 Oct 2026 the live site is the igneum project in the igneum team (igneum-josh login, ~/.config/igneum/vercel), deployed by the GitHub integration on every push to master; the vivanmn project of the same name only holds the 13 redirect domains. Link, env and hand-deploy commands: packaging/README-ship.md (checked 4 Oct 2026).

Browser profile (standing rule, 3 October 2026)

Every Igneum task in Claude in Chrome runs in the Chrome profile "josh (igneum.network)". Josh also has profiles for VIVANMN, QUANTUM, PEASEHILL, THRSTY, GEMVEN and JBM EXEC. Confirm the active profile before acting; if it is the wrong one, switch or stop and say so. Never carry Igneum sign-ins, posts or purchases through another brand's profile.

Running agents on this Mac (standing rule, 4 October 2026)

• Code and documents in parallel; BUILDS and MEASUREMENTS one at a time through tools/lock/with-lock.sh build|measure|run <cmd> (measure blocks builds too: hash rate, latency in ms, power; run is for functional runs such as test networks, attack harnesses and simulators whose outputs are counts, locks, forks or seconds, and lets builds continue; use the MAIN checkout's script, /Users/joshm/Projects/igneum/tools/lock/with-lock.sh, from any worktree). A number taken while another build or simulation ran is not a number.
• Builds and test suites run on the PCs, not on this Mac (standing rule, 5 October 2026, Josh: "since building on the pc is so much faster, lets fully utilise both of them"): Linux and Windows binaries and every cargo test suite go out as build jobs (node tools/build-job.mjs run --target ae432dc7|1ccfe586 ..., PC 1 = ae432dc7 for builds, PC 2 = 1ccfe586 for test suites; one job per machine at a time; results come back through the relay, every sha256 checked). Measured 5 October: PC 1 built the Linux and Windows node and app and ran both test suites in 7 min 38 s cold, 5 min 09 s warm. The Mac builds only the macOS binaries and the DMG, under the build lock, and ~/.config/igneum/build-slots (1 to 3) caps how many Mac builds run at once.
• Every agent works in its own git worktree (git worktree add ../igneum-wt-<name>), never the shared checkout, and stages only its own files. Builds: nice -n 19, at most 4 cargo jobs. Windows builds go to the GitHub runner, Linux binaries come from infra/cross/build-linux.sh; nothing is built on a server.
• Never launch /Applications/Google Chrome.app headless (it blocks the owner's Chrome); use the built-in browser pane.
• Keep the Mac on mains with the 140 W charger; on 4 October it hibernated at 1% battery and took node 1 and the observer down.
• A source tree copied to another machine (rsync, zip, tar, scp) is re-stamped with touch before anything builds it, because cargo rebuilds by mtime and the far side keeps its target dir (the stale-build class: shard run 2 on 4 October, the 0.3.6 PC build on 5 October). tools/ci/copied-sources-check.sh fails CI on any script that copies and builds without it. When a bug is fixed, fix its CLASS: grep for every other script with the same shape the same day, and add a check that fails when the shape comes back (Josh, 5 October 2026: "we should not be having same bugs repeated").
• A watcher or gate is trusted only after it has been shown to fire on one known-finished and one known-failed case (4 October 2026: three job watchers waited for a line the closing report never starts with, and a failed shard run reported exit 0; the failure was found by hand half an hour later). Every job's outcome and its error lines are read the moment it ends, done or not.

Every number carries its consequences (standing rule, 5 October 2026, 21:30 UTC)

Josh: "this question and answer should have not needed to be asked ... so that suggestions like this get made without me" (the 12 GB mine-and-prove question, which followed from the 15.6 GB measurement and should have been raised by the agent that measured it). Rule: an agent that measures or reports a number also states, in the same report, what the number means for each user tier and what it will do about it, before anyone asks. The tiers: a home miner with one 8 GB card, one 12 GB card, one 16 GB card, one 24 or 32 GB card; a rig; a pool user; each on Windows, Linux and macOS; each on NVIDIA, AMD and Apple (Intel when it exists). A report that says "peak 15.6 GB" without "so 12 GB cards cannot do both; here is the profile that fits them, measuring now" is incomplete and goes back. The same for hash rates (per watt and per pound for the tiers), times (what deadline it fits), sizes (what disk or memory it needs), and prices. A standing reviewer agent reads every status file, bench-log entry and plan for missed consequences and opens the work; the coordinator does not wait for Josh to notice.

A job never quits or restarts the installed app it did not start (standing rule, 5 October 2026, 23:05 UTC)

Ember Tune's PC 1 playbook read the installed app's app.url file and POSTed /api/quit to it when its own test budget was spent, taking PC 1 off the network from 22:31Z (141 MH/s gone, the 0.3.11 Windows build blocked) with nobody awake to relaunch. Rule: a test engine started by a job runs on its own port and data dir with its own URL file, and a job may quit, pause, resume or restart only an engine it started itself (the URL it created); the installed app is touched only through the signed restart and update-now job kinds. tools/ci carries a check (playbook-quit-check) that fails a playbook which reads %LOCALAPPDATA%\igneum\app\app.url or ~/Library/Application Support/Igneum/app/app.url and sends quit, pause or resume to it; the reviewer's row C35 is the record.