ethlib 0.3.0

Install it with pip install ethlib==0.3.0 (PyPI).

Released on 2026-11-06.

0.2.0 had Python bindings for BLS and KZG only.
In 0.3.0, the package ethlib has a subpackage for each layer of EthLib:

• ethlib.cryptography: aes, bls, crc32, crc32c, ethash, hmac, kdf, keccak, kzg, secp256k1, secp256r1, sha256, sphincs, vrf and xmss
• ethlib.serialization: rlp and ssz
• ethlib.networking: devp2p, discv4, discv5, enr, forkid, gossip, reqresp, rlpx, snappy and varint
• ethlib.execution: blocks, evm, fees, network, pow, transactions and trie, with ethlib.precompiles, ethlib.state and ethlib.chain
• ethlib.consensus and ethlib.engine, for the consensus layer and the Engine API

The sections below list the changes that a caller of 0.2.0, or of master before this release, may need to act on.

Typed errors in the Python bindings

A failed call into the Python bindings now raises an exception that carries the code and the message of the Lean error (#310).
Before, most failures raised a bare RuntimeError or ValueError with the name of the operation, and the Lean message went to standard error.

The new module ethlib.errors defines one exception class for each primitive, such as KzgError or BlsError.
Each class derives from EthLibError, which has two attributes:

• code, an integer that names the kind of failure;
• message, the text of the Lean error.

Each class also derives from the class that the same failure raised before: RuntimeError, ValueError or both.
So a caller that catches RuntimeError or ValueError still catches it.
A caller that parsed the text of an old message must now read message.
A message no longer starts with the name of the operation.

The Lean type of each error defines its codes, one for each constructor, from 1.
When one Python class carries several Lean error types, the second type takes its codes from 101, the third from 201, and so on.
A theorem for each error type shows that two errors with one code come from one constructor.

Code 0 means a failure that has no Lean error code.
Examples are an unknown fork name and an input that the export reads before the specification runs.
No Lean error type uses code 0.
Some checks on the type or the length of an argument run in C first, and raise TypeError or ValueError with no code.

The C signatures of the fallible exports change too.
Each one returns the code and the message of its error, in place of a Lean IO error.

Precompiles

The module ethlib.precompiles reaches every precompile by its address, at a fork named by the caller.
run(fork, address, data, gas) returns the output, and price(fork, address, data) returns the gas that the call charges (#459).
A failed call raises PrecompileError, whose code names the precompile.

Before the release, master also had the modules ethlib.precompiles.ecrecover, modexp, sha256 and ripemd160, with the classes EcrecoverError, ModexpError and Sha256PrecompileError.
They are removed, and 0.3.0 does not have them.
A caller of modexp.modexp(data, gas) now calls run(fork, 0x05, data, gas), and a caller of modexp.gas_cost(data) calls price(fork, 0x05, data).

Other changes that break callers

• The KZG operations take the trusted setup as an argument and no longer run in IO (#235), and their byte inputs are typed (#346).
• leanXMSS replaced XMSS, with two layers of height 16 (#134), and hashes with Keccak-256 in place of BLAKE2s (#138).
• The C exports moved into a Lean library of their own, so Lean code that imported them changes its imports (#119).
• An integer argument out of its range raises OverflowError, as Python's own conversions to a C integer do (#718).
  Before, an integer outside [0, 2^64), an EVM opcode above 255 and the range checks of the Python wrappers raised ValueError.
  A caller that caught ValueError for such an argument now catches OverflowError.
• consensus.verify_data_column_sidecar takes the signed block before the configuration, in the order of its native export (#729).

Full list of changes: v0.2.0...v0.3.0

ethlib 0.2.0

First release of the Python package under the name ethlib: pip install ethlib==0.2.0 (PyPI).
The previous tag, v0.1.0, predates the rename.

What it contains

Lean 4 specifications with their proofs:

• BLS12-381 signatures
• KZG polynomial commitments
• XMSS signatures (BLAKE2s-256, the Winternitz one-time signature and the target-sum encoding)

The Python package exposes BLS (ethlib.cryptography.bls) and KZG (ethlib.cryptography.kzg), compiled from the same Lean code.
XMSS has no Python binding in this release.

Wheels

The wheels cover CPython 3.10 to 3.14, including the free-threaded 3.14t, on Linux x86_64 and aarch64 (manylinux_2_34) and on macOS arm64.
An sdist is published too.

Full list of changes: v0.1.0...v0.2.0

v0.1.0

Initial commit