E46 work orders: C++ libraries and build workflow

Written: 7 October 2026 · Spec: CHAIN-DESIGN.md · Status: planned, nothing built Rule: nothing is “done” until the project owner’s reviewer (Claude) has re-run its tests and checked it against the spec.

Start here (for the builder)

1. Baseline first: the project folder must be under git with a clean first commit before any build work, so every change can be reviewed as a diff. (Ask the owner if it isn’t.)

2. Order: WO-01 → WO-02 → WO-04 → WO-03 → WO-08 (Rad prototype) → WO-14 (Grover re-run) → then WO-05, 06, 07, 11, 12, 09, 10, 13.

3. One work order at a time, each on its own branch wo-XX-name, each finished with its WO-XX-REPORT.md.

4. Put new code under e46/ (C++: e46/src, e46/include, e46/tests, e46/golden for Python references and vector JSON). Don’t modify existing research files, phase3-runs/ evidence, PEER_REVIEW/ or the QTL test runs.

5. Stop and ask before installing libraries (XKCP/OpenSSL, liboqs, a test framework), before long runs, and whenever the spec is unclear. Never guess a consensus rule.

6. Write every question down. Unclear rules, spec gaps and limitations go into DECISIONS-NEEDED.md (Open) and the work order’s report, never only in chat, because the owner may miss a chat message. Reply BLOCKED WO-NN until it is answered.

7. Never rewrite history or delete files. No reset, rebase, amend of pushed commits, force-push, or deleting/moving files outside your work order. If something must be undone or reorganized, stop and ask the owner. (Added 8 Oct 2026 after 89 owner files vanished from the working folder during a history rewrite; they were restored from commit 9d73bc6, kept as branch backup/making-it-better-9d73bc6.)

The map

                       ┌───────────────────────────── FOUNDATION ─────────────────────────────┐
                       │  WO-01 RL v3 lib     WO-02 SHAKE/KMAC wrap     WO-04 Bech32m          │
                       └──────┬───────────────────────┬──────────────────────────┬────────────┘
                              │                       │                          │
              ┌───────────────┴──────┐    ┌───────────┴───────────┐    ┌─────────┴─────────┐
              │ WO-08 Rad engine  ★  │    │ WO-03 Merkle roots    │    │ WO-05 Addresses   │
              │ (prototype first)    │    │ merkle + event root   │    │ & IDs             │
              └──────┬───────────────┘    └───────────┬───────────┘    └─────────┬─────────┘
                     │                                │                          │
                     └──────────────┬─────────────────┴──────────┬───────────────┘
                                    │                            │
                     ┌──────────────┴─────────┐     ┌────────────┴────────────┐
                     │ WO-06 Header + PoW     │     │ WO-11 SLH-DSA + KMAC    │
                     │ + ASERT                │     │ keys (liboqs)           │
                     └──────────────┬─────────┘     └────────────┬────────────┘
                                    │                            │
                     ┌──────────────┴─────────┐     ┌────────────┴────────────┐
                     │ WO-07 Emission, pools, │     │ WO-12 Transactions,     │
                     │ E46i, neutrino         │     │ sighash, output types   │
                     └──────────────┬─────────┘     └────────────┬────────────┘
                                    │                            │
                                    └──────────────┬─────────────┘
                                                   │
                     ┌───────────────┬─────────────┴───────────┬────────────────────┐
                     │ WO-09 Block   │ WO-10 Genesis miner      │ WO-13 QTL v2 port  │
                     │ QTL commits   │ + chainparams            │ (SHAKE, dual delay)│
                     └───────────────┴──────────────────────────┴────────────────────┘
                                                   │
                                  WO-14 Grover re-run on the built libs
                                                   │
                                  LOCAL TESTNET (RL v3)  →  later: P2P, GUI, FIDO2, RL W

★ = build first (agreed): the Rad prototype measures Z_base and Z_commit on real Rad puzzles.

Workflow for every work order

1. SPEC       read the CHAIN-DESIGN.md section(s) named in the work order
2. GOLDEN     write or reuse a Python reference (the "golden" version) → generate test vectors (JSON)
3. C++        implement in C++20 against the same spec, NOT by translating the Python line by line
4. MATCH      C++ output == golden vectors, byte for byte, + ≥ 1,000 random inputs + edge cases
5. HARDEN     build with -Wall -Wextra -Werror, AddressSanitizer + UndefinedBehaviorSanitizer; fuzz parsers
6. MEASURE    benchmark (≤ 4 worker threads; the Mac's fans)
7. REPORT     a short WO-xx-REPORT.md: what was built, test output, measurements, anything unsure
8. REVIEW     Claude re-runs everything, checks spec line by line, and runs a SURPRISE EXAM: fresh random
              inputs from an unpublished seed, answered by the Python reference (Sunday) → owner approves → merge

House rules (all work orders)

• No SHA-2 anywhere in chain code (SHA-256 only as a labelled test control).

• No floating point in consensus code. Integers only; explicit little-endian serialization; clamp every unsigned subtraction (remaining = max(T − E, 0)).

• Never write cryptography that a vetted library provides: SHAKE/KMAC (XKCP or OpenSSL 3), SLH-DSA (liboqs). Refracting Light is the only hash we implement ourselves.

• Two implementations agree (golden Python + C++) before anything counts as done.

• Golden files are public and frozen. They are never edited to make a test pass; any change to e46/golden/ is a red flag in review.

• Ask the owner before installing any library or running anything longer than ~10 minutes.

• Never put keys, passwords or private IPs in files.

• Before building starts: put the project under git, so every change can be reviewed as a diff.

Work orders

WO	Name	Spec	Needs	Deliverable	Done when
01	RL v3 C++ library librl	RL-V3-PAPER §1; spec §8	—	rl.hpp/.cpp: rl_v3_128(bytes), rl_v3_unfolded(bytes), streaming API, header PoW helper	all v2/v3 vectors + 1,000 random match Python and rl_search.c; ≥ 250k short hashes/s/core
02	SHAKE256 / KMAC256 wrapper	§2a, §2e	XKCP or OpenSSL 3 (approval)	shake256(tag, data, out_len), kmac256(key, data, custom, out_len), domain-tag helper	NIST FIPS 202 / SP 800-185 test vectors pass; matches Python hashlib.shake_256
03	Merkle roots (merkle_root, event_root)	§2b, §2f	02	tree build, root, inclusion proof create/verify; typed event leaves (0x02 Rad, 0x03 commitment); sort rules	golden vectors for 0, 1, 2, 3, 5, 1,000 leaves; odd node carried (never duplicated); tags 0x00/0x01; proofs verify and tampered proofs fail
04	Bech32m codec	§2a	—	encode/decode with prefixes e46 te46 tes tess e46tx e46blk e46rad (+ testnet), versions q p z	BIP-350 official vectors pass; all spec example strings reproduce; wrong network/prefix/checksum rejected
05	Addresses and IDs	§2a	01, 02, 04	single-owner RL128 ‖ SHAKE128, shared k-of-n, txid, wtxid, block ID, Rad ID	spec examples reproduce exactly; golden vectors match
06	Header, PoW, ASERT	§2, §2b, §2d	01, 02	120-byte header (de)serialize; RL_v3(header) ≤ target; compact bits; ASERT (integer, half-life 7,200 s); median-time-past; future-time limit	golden header vectors; ASERT matches a Python reference over 100,000 simulated blocks incl. hashrate jumps
07	Emission, pools, E46i	§3, §5	06	reward(h), 80/10/10 split, N-pool and Z-pool accounting, E46i v >> epochs, neutrino floor	1,000-year simulation: Σ(miner+N+Z) = Σ reward every block; no underflow at years 100/114/118; totals match spec tables
08 ★	Rad engine + prototype	§4	01, 02, 03	Rad stamp, nonce-bound puzzle, Z-level, byte tiers, verify, Rad leaf; measurement harness	verifies honest Rads, rejects forged/stolen/out-of-window ones; report measured Rads/block vs Z (set Z_base (provisional 43; see CHAIN-DESIGN §6 “Paradox A”)) and stamp time (set Z_commit (provisional 18))
09	Block QTL commitments	§2f	02, 03, 08	commitment build, Z_commit stamp, reveal check (6 ≤ depth ≤ 2,016), per-block limit 1,000	reveal before 6 blocks rejected; expired rejected; mismatched rejected; limit enforced
10	Genesis miner + chainparams	§2b, §2d	03, 05, 06	genesis_miner: coinbase with pszTimestamp, 0-E46 OP_RETURN, nonce search, prints chainparams	anyone reproduces the same genesis from the same pszTimestamp; testnet and mainnet genesis separate
11	SLH-DSA keys + KMAC derivation	§2e	02, liboqs (approval)	keygen from seed, sign, verify (SLH-DSA-SHAKE-128s); seed_i = KMAC256(master, …)	NIST KAT vectors for SLH-DSA-SHAKE-128s pass; sizes 32 / 64 / 7,856 B confirmed against FIPS 205
12	Transactions	§2e	03, 05, 11	serialization, txid/wtxid, sighash, output types 0x00–0x04, coinbase rules, maturity	golden vectors; malformed inputs rejected (fuzzed); sighash commits to spent values
13	QTL v2 port	QTL-V2-ANTI-LOCKOUT.md; spec S16	02	swap SHA-256 fingerprint and HKDF-SHA256 for SHAKE256/KMAC256; dual delay 50/50 (Lock A squaring, Lock B hash chain + chain bank)	all 13 anti-lockout cases still pass; a Lock-B-only attacker still waits ≥ half the delay
14	Grover re-run on the built libraries	GROVER-TEST-HANDOFF.md; PHASE3-RESULTS §L	01 (and 08 for Rad puzzles)	re-run grover_rl_test.py (toy widths w = 2, 3, 4 stay Python-only: a table oracle makes the Grover curve function-independent) and cross-check the actual C++ librl against the Python reference at w = 64 (decision #14, option C); extend to the Rad puzzle (preimage of a Z-bit match) and the 18-bit commitment stamp	librl matches Python at w = 64; all Grover curves match theory (as in §L); new section M in PHASE3-RESULTS.md with quantum costs: Rads are collisions, so BHT ≈ 2^(Z/3) ≈ 2^14.3 at Z = 43 (matching a given Rad’s bits by Grover ≈ 2^(Z/2) = 2^21.5); stamps by Grover ≈ 2^9 at 18 bits. State what this means for quantum miners of Rads

WO-15 (build note only, not yet ordered): mining software, example pool, example explorer

• CGMiner and BFGMiner support: an RL v3 algorithm driver (the rl_v3 hashing core from librl, the header layout from WO-06, the target check) so these established miners can mine E46. Both are GPL-3.0 projects, so the E46 driver lives in separate GPL-licensed forks while E46’s own code stays MIT. CGMiner today mostly targets ASICs and FPGAs, so a CPU/GPU path may suit BFGMiner or a small native E46 miner better; decide when ordered.

• Stratum support: the mining protocol pools and miners speak, adapted to E46’s 120-byte header, 64-bit nonce and 64-bit time.

• Example pool: a minimal open-source pool (stratum server, share accounting, payouts in E46) for the testnet, clearly labelled as an example.

• Example block explorer: a read-only web page showing blocks, transactions, e46… / tes… / e461z… addresses, Rads and Z-levels, Block QTL commitments, decay epochs and E46i timers.

• Depends on: WO-01, 03, 05, 06, 07, 08, 12 and a running local testnet.

Later (not yet ordered)

P2P networking (Tor/I2P behind build flags, off by default) · GUI wallet (FIDO2 optional, E46i timers shown) · Quantum Rads (by consensus) · Refracting Light W and shard variants (after the local testnet).