Repolode
Submit
ethereum

ethereum/EthLib

Formally verified Ethereum primitives written in Lean, meant as a shared library of specifications and proofs for Lean projects.

View on GitHub
Stars
83
Forks
22
Open issues
25
Last commit
13 hours ago

What is it?

EthLib provides Ethereum definitions and their proofs in Lean, so that Lean projects can build on one common implementation rather than each maintaining its own. It covers the building blocks of the protocol: 256-bit words, hash and signature primitives such as Keccak, secp256k1, BLS12-381 and KZG, encodings like RLP and SSZ, networking pieces including discv4, discv5, RLPx and gossipsub parameters, and execution-layer components such as the EVM opcodes, precompiles, state, transactions, blocks and the Merkle Patricia Trie. Consensus-layer definitions cover configuration, slots and epochs, committees and fork choice models.

The library is organised in layers, and a module imports only from its own layer or lower ones, with the execution and consensus layers kept apart. Some primitives are exported through C bindings, which Ethereum clients may use either as a temporary stopgap until a native implementation exists or permanently if performance is adequate.

Building requires elan and Mathlib, and `lake build` compiles the primitives and checks every proof. A separate test suite exercises the Python bindings.

Key features

  • 01Covers 256-bit EVM words, cryptographic hashes, and signature schemes including secp256k1, BLS and KZG.
  • 02Includes RLP and SSZ serialization used by the execution and consensus layers.
  • 03Provides networking definitions for discv4, discv5, RLPx, and gossipsub parameters.
  • 04Models EVM opcodes, all 18 precompiles, state, transactions, and blocks by fork.
  • 05Exposes some primitives through C bindings usable from Ethereum clients.

Use cases

  • Building a Lean project that needs verified Ethereum specifications instead of its own implementation.
  • Using the bindings in an Ethereum client as a stopgap before a native implementation exists.
  • Checking the behaviour of EVM precompiles or transaction rules against formal definitions.
  • Studying how Ethereum's execution and consensus protocols are specified in a theorem prover.

Quick start

  1. 1

    Install elan, the Lean toolchain manager, using the official install script from the README

  2. 2

    Download Mathlib dependencies from the cache

    lake exe cache get
  3. 3

    Compile the primitives and check every proof

    lake build

Things to know

  • Building requires the Lean toolchain via elan and the Mathlib dependency.
  • Using the Python bindings requires a native extension build with uv.

Topics

#ethereum#formal-verification#lean#blockchain#cryptography#evm

FAQ

What is EthLib?
Formally verified Ethereum primitives written in Lean, meant as a shared library of specifications and proofs for Lean projects. EthLib provides Ethereum definitions and their proofs in Lean, so that Lean projects can build on one common implementation rather than each maintaining its own. It covers the building blocks of the protocol: 256-bit words, hash and signature primitives such as Keccak, secp256k1, BLS12-381 and KZG, encodings like RLP and SSZ, networking pieces including discv4, discv5, RLPx and gossipsub parameters, and execution-layer components such as the EVM opcodes, precompiles, state, transactions, blocks and the Merkle Patricia Trie. Consensus-layer definitions cover configuration, slots and epochs, committees and fork choice models.
Is EthLib free to use? What license does it have?
EthLib is open source under the CC0-1.0 license. Check the license terms before using it in commercial products.
Is EthLib still maintained?
Actively maintained. The last commit to EthLib was on Nov 6, 2026.
What can I use EthLib for?
Building a Lean project that needs verified Ethereum specifications instead of its own implementation. Using the bindings in an Ethereum client as a stopgap before a native implementation exists. Checking the behaviour of EVM precompiles or transaction rules against formal definitions. Studying how Ethereum's execution and consensus protocols are specified in a theorem prover.
How do I install EthLib?
Install elan, the Lean toolchain manager, using the official install script from the README Download Mathlib dependencies from the cache: lake exe cache get Compile the primitives and check every proof: lake build
Where can I get EthLib?
The source code and installation instructions are on GitHub: https://github.com/ethereum/EthLib

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects