diff --git a/docs/plans/public-repo.md b/docs/plans/public-repo.md new file mode 100644 index 000000000..cfaf40453 --- /dev/null +++ b/docs/plans/public-repo.md @@ -0,0 +1,124 @@ +# Public repository `igneum-network/spec`: prepared, not published + +3 October 2026, 22:28 UTC. The public subset of this repository is exported to `/Users/joshm/Projects/igneum-public/` +(its own git repository, outside this one). It is PREPARED ONLY. Nothing has been created on GitHub and nothing has +been pushed. the project lead decides in the morning. This file is internal. + +## State at export + +| Item | Value | +|---|---| +| Directory | `/Users/joshm/Projects/igneum-public/` | +| Size | 3.8 MB working tree (no `target/`), 117 tracked files | +| Commit | one, `main`, author and committer `Igneum contributors `, 2026-10-03T22:28:24+00:00, no history from this repository | +| Identity grep | 0 hits over the tree (41 patterns, list below) and 0 hits over the commit metadata (author, committer, dates, subject, body) | +| igneum-pow tests | `nice -n 19 cargo test --release -j 4` inside the public checkout: 16 unit tests and 13 pack tests pass, 0 failed; proves the crate plus `proto-cuda/packs/` are self-contained | +| Licence | MIT, copyright "The Igneum contributors", `LICENSE`. PROVISIONAL: the project lead must confirm the licence before publishing (`docs/provenance.md` "Licence of Igneum's own code"); the public README says "the maintainers confirm it before the first release" | +| Export source | the working tree of this repository at export time, not HEAD (igneum-pow and the spec had uncommitted edits; they are in the export) | + +## File list (117) + +Top level: `README.md` (what it is, experimental, how to run the vectors and the simulators, how to submit a break +via hello@igneum.network and the site), `CONTRIBUTING.md`, `SECURITY.md`, `LICENSE`, `.gitignore`. + +| Path | Files | From | +|---|---|---| +| `docs/spec/` | 12 | `docs/spec/` whole (00 to 10 and README) | +| `docs/provenance.md`, `docs/bench-log.md` | 2 | scrubbed, see rules | +| `docs/analysis/` | 2 | census and difficulty analyses | +| `igneum-pow/` | 14 | Cargo.toml, Cargo.lock, README, rustfmt.toml, .gitignore, src (8), tests/packs.rs; no `target/` | +| `igneum-census/` | 4 | Cargo.toml, Cargo.lock, .gitignore, src/main.rs (path dependency `../igneum-pow` resolves inside the public tree) | +| `proto-cuda/packs/` | 23 | igneum-genesis (7), igneum-genesis-mh (9), igneum-hourly (7); all three are read by the pack tests | +| `proto-cuda/` | 9 | README, CHECKLIST, host.cu, build.sh, build.bat, .gitignore, emu/{emu.sh, shim.cpp, cuda_runtime.h} | +| `proto-metal/` | 4 | README, MEMHARD, TESTS, main.swift | +| `proto-opencl/` | 9 | README, WAVEFRONT, host.c, build.sh, build.bat, .gitignore, emu/{emu.sh, emu_main.cpp, emu_opencl.h} | +| `sim/` | 11 | README, finality_sim.py, finality_v2.py, results.md, results_v2.md, difficulty/{README, sim.py, results.md, 3 csv} | +| `tools/harness/` | 16 | README, run.mjs, lib (6), scenarios (8); no results | +| `tools/exec-attacks/` | 5 | net.sh, lib/common.mjs, scenario1/2/5 (in progress by another agent at export time: no README yet, `node_modules` symlink and empty `contracts/`, `results/` dropped). the project lead may want this out until it has a README | +| `tools/sync.sh` | 1 | the re-export script | + +Not present in this repository, so not exported: `docs/benchmarks/`, `docs/evidence.md`, `tools/finality-attacks/`. +Referenced by the spec but deliberately not exported (open with the node fork later): `vendor/`, `docs/fork-map.md`, +`docs/fork-divergence.md`, `docs/design/`, `proto-vdf/` (the spec section 4 cites its numbers; candidate for a later +export), `tools/observer/`, `tools/upstream/`, `tools/evm-smoke/`. The public README lists these as "not in this +repository". + +EXCLUDED on purpose (internal): `CLAUDE.md`, `.claude/`, `docs/fud-ledger.md`, `docs/fud-fixes.md`, `docs/review/`, +`docs/commercial/`, `docs/legal/`, `docs/plans/`, `infra/`, `packaging/`, `proving/` (windows-wsl2 and igneum-prove), +`proto-cuda/windows-app`, `windows-miner`, `windows-node`, `WINDOWS-MINER.md` (LAN address, log upload), `site/`, `brand/`, +`.vercel`, every built binary, every `emu/build-*`. + +## Scrub rules applied (all in `tools/sync.sh` unless marked local) + +1. Machine names to model names: "Windows PC" to "an RTX 5090 on Windows"; "the PC", "the PC's", "PC joins/start/period" + to "the RTX 5090 machine" forms; "the PC node at 192.168.68.67" to "the RTX 5090 node on the LAN". In `docs/bench-log.md` + only: "the Mac", "the Mac's", "Mac side only" to "the Apple M5 Max" forms. Everywhere else "the Mac" is left (it is not + a machine name; "MacBook" never occurs). +2. Addresses: every `192.168.x.x` to `` (one occurrence, the `--addpeer` flag in the sync test). No Tailscale + `100.x` address, hostname or `DESKTOP-KMCV30N` occurred in the candidate files. +3. Paths: `~/Desktop/` prefixes removed (two zip names in the bench log); `~/.cargo/bin/cargo` to `cargo`; any + `/Users/` to `~` and `C:\Users\` to `%USERPROFILE%` (none occurred; the rule stays for future exports). + `C:\Program Files\...` and `/tmp/...` paths are kept. +4. Times: every "hh:mm BST" and "hh:mm to hh:mm BST" converted to UTC (minus one hour); "19:07:49 UTC = 20:07 BST" + collapsed to the UTC half; the bare "22:35" next to a converted range made "21:35 UTC". Dates unchanged. +5. Unpublished documents: `docs/fud-ledger.md` references become "the break ledger (kept by the maintainers, not yet + published; see SECURITY.md)"; spec 00 section 0.5 steps 1 and 3 rewritten to point at hello@igneum.network and + SECURITY.md; "CLAUDE.md" becomes "the design document" (sim/README.md, sim/finality_v2.py, harness stubs.mjs). +6. Local rules (`tools/sync.local.sed`, gitignored, NOT in the public commit, recreate from here if lost): + `Pending the project lead's decision.` to `Pending the maintainers' decision.` (provenance); `decision, the project lead (key custody)` to + `decision, the maintainers (key custody)` (06-open-items O-8.1); any other `the project lead` to `the maintainers`; the sentence + " Not deployed to Vercel tonight." removed from the bench log. +7. Pruned: `target/`, `out/`, `__pycache__`, `*.pyc`, `build-*/`, `node_modules` (dirs and symlinks), `.DS_Store`, + `tools/harness/{results,runs}`. + +Identity pattern file (`tools/identity.local`, gitignored, NOT in the public commit; one ERE per line): +`the project lead [second-owner-login] igneum-labs 337424239 [other-business] [other-business] [other-business] Quantum DESKTOP-KMCV30N MacBook 192\.168\. +100\.[0-9]+\.[0-9]+\.[0-9]+ \+0100 \bBST\b Leeds \bUK\b Hetzner hetzner deSEC desec Vercel vercel Neon neon\.tech GoDaddy +godaddy Tailscale tailscale ts\.net log-intake LOG_INTAKE intake[_-]?key /Users/ C:\\Users ~/Desktop` and the em dash. +The script itself passes the grep (its time rule is written `B[S]T` so the literal never appears in the public tree). + +Grep result at export: `identity grep: 0 hits` (tree), `0` (commit metadata). The word "token" occurs in the spec +only in its protocol sense (the coin, an RPC bearer token for an operator's own miner); no credential anywhere. + +## Publish (only after the project lead says yes) + +``` +gh auth status # ACTIVE account must be igneum-labs +gh auth switch --user igneum-labs # if it is not +cd /Users/joshm/Projects/igneum-public +git log --format='%an <%ae> %cn <%ce> %ad' --date=iso-strict # one commit, Igneum contributors, +00:00 +tools/sync.sh /Users/joshm/Projects/igneum # optional final re-export; must print "identity grep: 0 hits" +gh repo create igneum-network/spec --public --source=. --remote=origin --push \ + --description "Igneum: protocol specification, reference lottery hash, simulators, test vectors and benchmark harnesses (experimental)" \ + --homepage https://igneum.network +``` + +`gh repo create --source --push` adds the remote `origin` (https://github.com/igneum-network/spec.git) and pushes +`main` in one step. If the repository is created first in the browser instead: +`git remote add origin https://github.com/igneum-network/spec.git && git push -u origin main`. +After the push: enable Issues (the README says "once issues are enabled"), disable Wiki and Projects, set the +default branch protection as wanted, and confirm the organisation members list shows only the `igneum-labs` login. +Before the push the project lead confirms the licence (MIT, "The Igneum contributors"). + +## Re-export whenever this repository changes + +``` +cd /Users/joshm/Projects/igneum-public +tools/sync.sh /Users/joshm/Projects/igneum # copies, prunes, scrubs, greps; exits 1 on any identity hit +git status # review the diff +TZ=UTC git add -A && TZ=UTC git commit -m "" +git log -1 --format='%an <%ae> %ad' --date=iso-strict # must read Igneum contributors, +00:00 +git log --format='%an %ae %cn %ce %ad %cd %s %b' | grep -Ef tools/identity.local # must print nothing +git push # only when the project lead says +``` + +The script requires `tools/sync.local.sed` and `tools/identity.local` next to it (both gitignored). It replaces the +synced subtrees wholesale, so any hand edit in the public tree must instead be made here or in the script. Before +committing, run `TZ=UTC` and check `git config user.name` is still "Igneum contributors" (set locally in the public +repository). New files in this repository that should go public must be added to the `DIRS`, `FILES` or `OPTIONAL_*` +lists in `tools/sync.sh`; a new private name, host or service must be added to `tools/identity.local` (and, if it has +to be rewritten rather than refused, to `tools/sync.local.sed`) before the next export. + +Open for the morning: whether `tools/exec-attacks/` ships now or after its README; whether `proto-vdf/` joins the +export (spec section 4 cites it); the licence confirmation; whether the 40 pre-rule commits of this private +repository matter (they do not touch the public repository, which has no shared history).