verifying-crypto-with-lean/README.md

Verifying Cryptography with Lean 4

A hands-on curriculum for undergraduates with zero formal-verification background — from 1 + 1 = 2 to reading (and extending) real, machine-checked proofs that production elliptic-curve code is correct.

This is the educational companion to a family of verification projects in which complete Ed25519 proof pyramids (from curve25519-dalek and three production forks — field, group law, scalars, and the signature verifier itself) and the Pasta curves' field layer were machine-checked in Lean 4 against models extracted from the actual Rust sources:

Companion project	What is verified there
dalek-ed25519-verified	the complete pyramid, upstream dalek: field 𝔽ₚ + Edwards group law + scalar arithmetic mod ℓ + the four-tier signature apex (accept ⇔ decompress(R) = k+[s]B, hash opaque)
anza-ed25519-verified	the complete pyramid, Solana's fork, its own extraction
risc0-ed25519-verified	the complete pyramid, RISC Zero's fork
betrusted-ed25519-verified	the complete pyramid, Betrusted's fork
pasta-pallas-verified	Pallas modulus primality (Lucas/Pratt), Montgomery foundations
formal-verification-control	the method: invariants, terrain map, failure map, tooling

The book

main.pdf — fourteen chapters + interlude + three appendices, full color, built with LaTeX/TikZ from the sources in this repo (./build.sh, tectonic, no root needed). No prior Lean or formal methods assumed; high-school algebra and a little programming suffice.

1. Why Verify? — the carry bug testing cannot find
2. Meet Lean — programs, types, inductive data
3. Propositions as Types — Curry–Howard: proofs are programs
4. Tactics — proving as a dialogue with the goal state
5. Numbers and Automation — omega, ring, norm_num, decide, and the simp discipline
6. Modular Arithmetic — clock worlds, fields, why 2²⁵⁵ − 19
7. Primality Certificates — convincing a paranoid kernel a 77-digit number is prime
8. From Rust to Lean — the Charon/Aeneas extraction pipeline
9. The Denotation Bridge — the commuting square at the heart of it all — Interlude — a complete verification, entirely by hand, then re-enacted in Lean line by line
10. Verifying a Field — the full campaign, told honestly (including the crash)
11. Honesty and Axioms — #print axioms, hollow certificates, trusted bases
12. The Pyramid — group law, scalars, signatures, and where you come in
13. The Second Summit — a hash-based pyramid for the quantum era: SLH-DSA (FIPS 205), Winternitz chains and the checksum see-saw, the virtual hypertree, the eleven certificates and their cone-growth table, and leaf 18 live
14. The Attestation Protocol — what it takes to make "it is proven" checkable by a stranger; closes with Go and touch the real thing: a guided reading of the estate's live transparency log (ltl.zkdefi.org — 19 leaves, the four ed25519 pyramids at 44 certificates, the log's own Merkle proofs as leaf 17, and the first post-quantum leaf, SLH-DSA, as leaf 18), including the fifteen-minute verify-it-yourself exercise

Appendices: A — the pen-and-paper toolkit (recipe cards with drills); B — guided walkthroughs of every exercise-file hole; C — a tour of the real repositories. Plus a glossary and a fourteen-week course plan.

The didactic machinery, deliberately heavy:

• Pen-and-paper worked examples in every chapter — computations with the real constants (2²⁵⁵−19, radix 2⁵¹, the fold constant 19, the actual 254-squaring inversion chain, the true Pratt tree p−1 = 2²·3·65147·Q), because the real numbers carry the real arguments. Highlights: inverting 19 modulo the 77-digit prime in five lines of Euclid; a fully hand-checked primality certificate for 97; the ×19 fold derived at the real weights; the 16p subtraction constant audited to the bit (8 fails by 151); the complete Bernstein–Lange completeness chain.
• Solutions immediately after every exercise set — each one leads with the pathway (how a person finds the answer) before the answer itself.
• Boxed Big idea / Try it / Pitfall / Aha / Checkpoint elements, TikZ figures throughout.

Everything the book claims about the companion projects reflects their actual, auditable state — including open frontiers.

The exercises (they run!)

exercises/ChNN.lean are working files with sorry holes; solutions/ChNN.lean are complete. Every solution file compiles with zero errors against the pinned toolchain (Lean v4.30.0-rc2, Mathlib 5450b53e); solutions to proof exercises contain no sorry.

Setup (one-time, ~5 min + Mathlib cache download):

# 1. install elan (Lean version manager) if you haven't:
curl https://elan.lean-lang.org/elan-init.sh -sSf | sh
# 2. fetch the Mathlib build cache (do NOT build Mathlib yourself):
cd verifying-crypto-with-lean
lake exe cache get
# 3. open the folder in VS Code with the "Lean 4" extension, or:
lake build Solutions   # compiles all solution files as a check

Chapters 2–4 need no Mathlib at all — you can start them with any Lean 4 install while the cache downloads.

The button

Like every repository in this estate, the book has one command that earns its claims — and it is the only source of the words "ALL GREEN" here:

./check-book.sh

It rebuilds the PDF from the committed sources and then verifies ~90 countable claims printed in the book against reality measured at run time: chapter and week-plan counts, exercise↔solution pairing per chapter, every chapter ending on its checkpoint, the recomputed SLH-DSA arithmetic (digest split, signature size, the 3,824-call worst case), the transparency log's 19 leaves and per-leaf certificate counts, leaf 18's axiom cones, the first dual-signed head at size 14, the extracted SLH-DSA-SHA2-128s parameter card, and chapter 7's 71-digit Q — digit for digit against P25519.lean. Numbers are parsed out of the prose and compared to measurements, so editing either side alone turns the button red. Cross-repo checks need the sibling estate repos checked out next to this one (BOOK_LOCAL_ONLY=1 skips them, loudly, and never prints ALL GREEN). ./check-book.sh --selftest mutates copies of the sources seven ways and proves each mutation is caught by its own check.

Building the book

The repo's own recipe (tectonic, user-space, no root — installs itself on first run):

./build.sh

Or any TeX Live ≥ 2023 with tikz, tcolorbox, listings, lmodern:

pdflatex main.tex && pdflatex main.tex   # twice for the TOC

Honesty ledger

In the spirit of Chapter 11:

• All solutions/*.lean were compiled (and their #eval outputs checked against their comments) at authoring time with the pinned versions above.
• Exercise templates compile with sorry warnings only.
• The book's claims about the companion projects (what is proven, what is frontier) mirror those repos' own READMEs and TRUSTED-BASE ledgers at the time of writing; the repos, not this book, are the source of truth. Re-audited 2026-07-06 after the signature apex reached its final four-tier form (coherence pass 4): chapter 12's status diagram, apex section, and audit-drill solution, chapter 11's boundary example, chapter 8's extraction notes, the repo tour, and this table were brought up to the proven state.
• Didactic revision (2026-07-06, same day): the book now states and keeps a "ratchet rule" (chapter 1) — every load-bearing idea worked at napkin scale AND at real scale with the full 77-digit constants printed, nothing elided. Chapter 12 gained the missing rungs: the addition law run by hand on a mod-13 curve and then on the real base point (with a machine-supplied quotient witness audited by casting out nines and elevens), the scalar cycle felt on the napkin curve, decompression run twice (mod-13 sign-bit walk, then the real compressed base point: byte-31 sign bit, and the full-size hand verification 5·y_B − 4 = 4·p, every digit printed), plus a new paper exercise (12.4). Every printed constant was machine-verified before typesetting.
• The PDF in the repo is built from the committed sources by ./build.sh and recommitted alongside source changes; rebuild it yourself if you don't trust binaries (good instinct), and you should get the same fourteen-chapter book.
• The three named solution certificates were kernel-audited (coherence pass 2, 2026-07-03): Ch09.add_spec depends on [propext, Classical.choice, Quot.sound]; Ch09.mulVal_spec and Ch12.addFixed_spec on [propext, Quot.sound] only. The Interlude's "compiled and axiom-audited" phrase shipped one pass before its audit had actually been run — caught by the verification projects' own coherence process and made true; recorded here in the spirit of Chapter 11.