[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"X2E9krBa8M":3},"![Etheorem](etheorem_owl.png)\n\n# Etheorem\n\n> **Status — early-stage, experimental, single-developer; personal\n> project, not an EF release.** The libraries here pass the\n> upstream consensus-spec test corpus and ship the three central\n> SSZ theorems on a `BasicSupported` cut, but production-grade\n> stability and a stable release line are not implied.\n\nA Lean 4 monorepo for Ethereum consensus-spec types and SSZ\n([Simple Serialize](https://github.com/ethereum/consensus-specs/blob/dev/ssz/simple-serialize.md))\nwith machine-checked correctness on the verified core.\n\nUpstream repository: \u003Chttps://github.com/etheorem/etheorem>.\n\n## Layout\n\n```\nLeanSha256 ─────────────┐\n                        ├─→ SizzLean  ←  LeanEthCS\nLeanHazmatSha256 ───────┘   (SSZ +        (consensus\n   (FFI SHA-256)            cache)        containers,\n                                          Phase0…Gloas)\n\nLeanHazmat* (FFI crypto family):  Sha256 · Bls · Kzg   (consumed à la carte)\n\nLeanPoseidon (pure Poseidon2, standalone island — nothing depends on it yet)\n```\n\nLake subpackages under `packages/`, each with its own lakefile and\nindependent build target:\n\n- **[`packages/LeanSha256/`](packages/LeanSha256/README.md)** — pure-Lean\n  SHA-256 reference. NIST CAVP-validated, kernel-reducible. No FFI.\n- **[`packages/SizzLean/`](packages/SizzLean/README.md)** — SSZ\n  library: spec types, serialization, deserialization, Merkleization,\n  the `SSZRepr` deriving handler, the cache layer, the `sszUpdate`\n  macro, plus the `Hasher` typeclass + `Sha256` instance (delegating to\n  the `LeanHazmatSha256` FFI binding) and the FFI ≡ spec equivalence\n  axioms — the one layer importing both the FFI binding and the spec.\n- **[`packages/LeanEthCS/`](packages/LeanEthCS/README.md)** —\n  Ethereum consensus-spec containers from Phase 0 through Gloas,\n  the preset-struct macro, and the `ssz_static` CLI runner\n  (`eth_ssz_vector_runner`, driven by `scripts/run_conformance.py`).\n- **[`packages/LeanHazmat*/`](hazmat-docs/ARCHITECTURE.md)** — the FFI\n  crypto family: one package per primitive family wrapping a\n  battle-tested native library behind `@[extern]`. Consensus families\n  ship today — `LeanHazmatSha256` (OpenSSL), `LeanHazmatBls` (blst),\n  `LeanHazmatKzg` (c-kzg-4844), consumed à la carte. The aggregator\n  meta-packages (`LeanHazmatConsensus`, …) and execution-layer families\n  are deferred. See [`hazmat-docs/`](hazmat-docs/).\n- **[`packages/LeanPoseidon/`](packages/LeanPoseidon/README.md)** —\n  pure-Lean **Poseidon2** algebraic hash (BN254 *and* BLS12-381 scalar\n  fields, `t = 3`): the permutation, the 2-to-1 `compress`, and a sponge.\n  A *standalone island* parallel to `LeanSha256` — depends on nothing in\n  the monorepo and nothing depends on it yet. Conformance-validated by a\n  differential test against the HorizenLabs `zkhash` Rust oracle\n  (test-only) plus committed KATs; the kernel-/`native_decide`-reducible\n  core needs no Rust. A sibling **`LeanPoseidonProofs`** package (mathlib,\n  standalone) proves `permute = permuteRef` (the shipped fast layers equal\n  the textbook dense reference) with a clean axiom footprint.\n\nThe umbrella `lakefile.toml` declares no Lean libraries of its own — it\njust coordinates the subpackages via `[[require]]` blocks\n(`LeanPoseidonProofs` is built on its own, keeping mathlib out of the\nroot). Per-package publication repos will exist later; this is a\ndevelopment monorepo.\n\n**Status: conformance-validated.** The Layer 1 spec\n(total serialize / deserialize / hashTreeRoot), the `SSZRepr`\ntypeclass + deriving handler, the FFI SHA-256 backend, the\npure-Lean `Sha256Spec` reference, and the cache layer\n(persistent `Node`, `Node.ofShape`, cached merkle walker,\ngindex-driven `setManyAt`, fused commit `Node.commitAndHash`,\nclosure-based pending overlay, `sszUpdate` macro,\n`SSZ.Box` user surface) are all landed. Consensus containers\ncover Phase 0 through Gloas, including Fulu's `proposer_lookahead`\nand the full Gloas ePBS `BeaconState` (nine EIP-7732 fields plus\nthe supporting `Builder` / `ExecutionPayloadBid` types).\nConformance pinned at consensus-spec-tests\n[v1.6.0-beta.0](https://github.com/ethereum/consensus-spec-tests/releases/tag/v1.6.0-beta.0)\nin `scripts/run_conformance.py`. The universal proof set\n(`decode_encode`, `serialize_injective`, `encode_size_le_max`\nover `SSZType.Supported`) and the AVX-512 SIMD inner loop for\n`sha256BatchCombine` remain as planned follow-ups; see\n[`packages/SizzLean/docs/PLAN.md`](packages/SizzLean/docs/PLAN.md)\nfor the staged roadmap.\n\n## Documents\n\nPer-subpackage design docs live next to the code they describe:\n\n- [`packages/SizzLean/docs/ARCHITECTURE.md`](packages/SizzLean/docs/ARCHITECTURE.md) —\n  the SSZ library's binding design (`SSZType` universe, `SSZRepr`\n  typeclass + deriving, cached Merkle tree, FFI SHA-256, trust\n  boundary, module layout).\n- [`packages/SizzLean/docs/PLAN.md`](packages/SizzLean/docs/PLAN.md) —\n  SizzLean's stage-by-stage deliverables and acceptance.\n- [`packages/SizzLean/docs/OPTIMISATION.md`](packages/SizzLean/docs/OPTIMISATION.md) —\n  implementation-level companion to ARCHITECTURE.md §6: the cache\n  layer's data structures, how each Phase 17 sub-stage is wired,\n  and the bench-gating story.\n- [`packages/SizzLean/docs/research/`](packages/SizzLean/docs/research/) —\n  background research (`pre-research.md`, `cache-research.md`).\n- [`packages/\u003CPkg>/README.md`](packages/) — per-subpackage READMEs.\n\nRepo-wide docs:\n\n- [`docs/monorepo-arch.md`](docs/monorepo-arch.md) — how the monorepo is\n  laid out: the three-subpackage shape, which lakefiles are TOML vs\n  procedural, where the FFI C shim lives, the LeanSha256 standalone\n  mirror, and the naming / dep / build conventions.\n- [`CLAUDE.md`](CLAUDE.md) — style and discipline conventions, project-wide.\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — PR / issue workflow,\n  toolchain setup, code-style pointers.\n- [`SECURITY.md`](SECURITY.md) — vulnerability-disclosure policy.\n- [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) — community guidelines.\n\n## Prerequisites\n\nOn a fresh machine you need four things before `lake build` will\nwork. The Lean toolchain and `just` itself aren't installed by\nthe project — they're external tools the recipes assume.\n\n1. **`elan`** (the Lean toolchain manager — provides `lake` /\n   `lean`). The version in [`lean-toolchain`](lean-toolchain) is\n   installed on first use.\n\n   ```bash\n   curl https://elan.lean-lang.org/elan-init.sh -sSf | sh\n   ```\n\n2. **`just`** (task runner — every workflow below is wrapped in\n   a `just` recipe; `just doctor` won't run until `just` itself\n   is installed). Install via your platform's package manager:\n   `brew install just` (macOS), `cargo install just` (anywhere\n   with Rust), or see \u003Chttps://just.systems> for distro packages.\n\n3. **OpenSSL 3.x + `pkg-config`** (system-level build deps for\n   the SHA-256 FFI shim — see [Native dependencies](#native-dependencies)\n   below for the per-platform one-liners). The Justfile's\n   `doctor-native` recipe pinpoints what's missing.\n\n4. **`python3` + `uv`** (only for `official-ssz-vector-tests*`).\n   Run `just setup-python` once to create `.venv/` and install\n   the harness deps.\n\nVerify everything in one shot:\n\n```bash\njust doctor          # checks elan/lake/lean + pkg-config/OpenSSL + python3/uv\n```\n\n`just doctor` prints actionable platform-specific install hints\nif anything's missing. The CI runs the slimmer `just doctor-native`\ngate (build-time native deps only — the Lean toolchain is\ninstalled by `leanprover/lean-action` later in the workflow).\n\n## Build\n\nToolchain pinned in [`lean-toolchain`](lean-toolchain) (elan picks it up).\n\n```bash\n# From the repo root — common targets by name:\nlake build LeanSha256\nlake build SizzLean\nlake build LeanEthCS\nlake build LeanPoseidon     # standalone Poseidon2 island (fires its anchor KAT)\n\n# Test suites (per package, run on demand):\nlake build LeanSha256Tests\nlake build SizzLeanTests\nlake build LeanEthCSTests\nlake build LeanPoseidonTests # committed Poseidon2 KATs (no Rust)\nlake exe   poseidon_fuzz     # Poseidon2 differential test vs the zkhash oracle (needs cargo)\njust test-poseidon-proofs    # mathlib equivalence proof permute = permuteRef (standalone; fetches olean cache)\n\n# Bench + profile executables:\nlake build ssz_bench       # microbench grid, S1–S7 (see SizzLeanBench.lean)\nlake build ssz_profile     # phase-by-phase profile of one workload\n\n# ssz_static / ssz_generic CLI driver (consumed by scripts/run_conformance.py):\nlake build eth_ssz_vector_runner\n\n# Or build a single subpackage in isolation:\ncd packages/SizzLean && lake build\n```\n\nThe repo's [`Justfile`](Justfile) wraps the common workflows\n(`just build`, `just test`, `just bench`,\n`just official-ssz-vector-tests-static`, …) — see `just --list`\nfor the full set.\n\nCI runs `lake build` for each named library on the pinned\ntoolchain via `leanprover/lean-action`.\n\n### Native dependencies\n\nThe FFI SHA-256 shim (`packages/LeanHazmatSha256/csrc/sha256_shim.c`,\nused by SizzLean's hash path) links against OpenSSL's `libcrypto`,\ndiscovered via `pkg-config` (Debian/Ubuntu fallback baked in). The Lake\nbuild expects:\n\n- **Linux (Debian/Ubuntu, including CI):** `libssl-dev` for the headers\n  (`/usr/include/openssl/evp.h`) and the versioned `libcrypto.so.3`\n  shared library, plus `pkg-config`. Install via:\n\n  ```bash\n  sudo apt-get install libssl-dev pkg-config\n  ```\n\n- **macOS:** `openssl@3` + `pkg-config` via Homebrew (the `pkg-config`\n  discovery handles the keg-only include/lib paths).\n\nRun `just doctor-native` to verify the build-time native deps\n(`cc`, `git`, `pkg-config`, OpenSSL 3.x).\n\n**Vendored crypto (the LeanHazmat BLS / KZG families).** `LeanHazmatBls`\n(blst) and `LeanHazmatKzg` (c-kzg-4844) wrap *vendored* native libraries,\nfetched at pinned tags by `just vendor-bls` / `just vendor-kzg` into\ngitignored `vendor/` trees before `lake build` (never git submodules; see\n[`hazmat-docs/ARCHITECTURE.md`](hazmat-docs/ARCHITECTURE.md) §6). `just\nbuild` runs both vendor steps for you. The C / C++ compilers are invoked\nthrough the Lean toolchain's `cc` wrapper — no separate configuration\nrequired.\n\n## Conformance harness\n\n`scripts/run_conformance.py` drives the Lean `eth_ssz_vector_runner` CLI against\n`ethereum/consensus-spec-tests` release archives. Default mode runs\nthe **`ssz_generic`** suite (type-agnostic SSZ tests for `uints`,\n`basic_vector`, `bitvector`, `bitlist`, `boolean`, `containers`),\nwith a `--limit N` subset cap by default.\n\n```bash\n# One-time: create `.venv/` with the harness deps (cramjam + PyYAML).\n# Wraps `uv venv` + `uv pip install -r scripts/requirements.txt`.\njust setup-python\n\n# Default: ssz_generic subset (5 cases per handler/suite)\n.venv/bin/python scripts/run_conformance.py\n\n# Full ssz_generic sweep\n.venv/bin/python scripts/run_conformance.py --all\n\n# Switch to ssz_static (per-fork consensus types)\n.venv/bin/python scripts/run_conformance.py --suite static\n\n# Single-shape focus\n.venv/bin/python scripts/run_conformance.py --include 'generic:uints/*'\n```\n\n### Current dispatch coverage\n\nNumbers below are against consensus-spec-tests **v1.6.0-beta.0**\n(the tag pinned in `scripts/run_conformance.py`). Both presets\ngreen across every fork Phase 0 → Fulu — Gloas and EIP-7805 test\nvectors exist in the corpus but aren't yet in the CLI dispatch\ntable or the harness's `FORKS` list.\n\n- **`ssz_generic`**: **2188 / 2188 in-scope cases pass** across\n  all handlers (uints, basic_vector, bitvector, bitlist, boolean,\n  containers). 292 progressive-container cases are deliberately\n  out of scope. The test-only structs (`SingleFieldTestStruct`,\n  `SmallTestStruct`, `FixedTestStruct`, `VarTestStruct`,\n  `ComplexTestStruct`, `BitsStruct`) have their SSZ shapes\n  hardcoded in `packages/LeanEthCS/LeanEthCS/Cli/Main.lean`.\n- **`ssz_static --config mainnet --all`**: **1585 / 1585 cases\n  pass** across every fork Phase 0 → Fulu.\n- **`ssz_static --config minimal --all`**: **38991 / 38991 cases\n  pass** across every fork Phase 0 → Fulu — including\n  variable-size composites (`Attestation`, `BeaconBlockBody`,\n  `BeaconState`) and all fork deltas\n  (Altair / Bellatrix / Capella / Deneb / Electra / Fulu).\n- **One-command full sweep**: `just official-ssz-vector-tests-all`\n  drives generic + static-mainnet + static-minimal end-to-end.\n",1780846773454]