Lean Ethereum Specifications

Quick Start

Prerequisites

Installing uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Installing Python 3.12+

# Install Python 3.12, or latest stable version
uv python install 3.12

Installing Rust Nightly (Temporary)

# Install rustup if not already installed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Install and set nightly as default
rustup install nightly
rustup default nightly
# Verify installation
rustc --version # Should show nightly version

Setup

# Clone this repository
git clone https://github.com/leanEthereum/leanSpec leanSpec
cd leanSpec
# Install and sync project and dev dependencies, using `uv.lock` versions
uv sync
# Run tests to verify setup
uv run pytest

Project Structure

├── src/
│ └── lean_spec/ # Main specifications
│ ├── __init__.py
│ └── subspecs/ # Sub-specifications
│ ├── poseidon2/
│ │ ├── __init__.py
│ │ ├── poseidon2.py
│ │ └── ...
│ ├── ...
│ └── ...
├── tests/ # Test suite
| ├── consensus/ # Tests for consensus
| | └── devnet/ # Tests for devnet
| | ├── fc/ # Tests for fork-choice
| | └── state_transition/ # Tests for stf
│ └── lean_spec/ # Tests for main specs
│ └── subspecs/ # Tests for subspecs
├── docs/ # Documentation
└── pyproject.toml # Project configuration

Workspace Commands

# Install package and dev dependencies or re-sync workspace
uv sync

Development Workflow

Running Tests

# Run all tests from workspace root
uv run pytest
# Run tests in parallel, utilizing all available CPU cores
uv run pytest -n auto
# Run tests in parallel, specifying number of workers (e.g., 4)
uv run pytest -n 4
# Skip slow tests (marked with @pytest.mark.slow)
uv run pytest -m "not slow"
# Fill test vectors from pytest specs.
# Usage: uv run fill --clean --fork=devnet [--output=<dir>]
# --clean Overwrite existing fixtures
# --fork Target fork (default: devnet)
# --output Optional directory for filled fixtures
uv run fill --clean --fork=devnet
# Run API conformance tests against an external client implementation
# Usage: uv run apitest <server-url> [pytest-args]
uv run apitest http://localhost:5052

Code Quality

# Check code style and errors
uv run ruff check
# Auto-fix issues
uv run ruff check --fix
# Format code
uv run ruff format
# Type checking
uv run ty check

Using Tox for Comprehensive Checks

# Run specific environment, like "all quality checks" (lint, typecheck, spellcheck)
uvx tox -e all-checks
# Run all tox environments (all checks + tests + docs)
uvx tox

Documentation

# Serve docs locally (with auto-reload)
uv run mkdocs serve
# Build docs
uv run mkdocs build

Writing Specifications

Example: Writing Tests

# tests/test_new_types.py
import pytest
from pydantic import ValidationError
from lean_spec.types import Withdrawal # Example Pydantic model
TEST_ADDRESS = "0x1234567890abcdef1234567890abcdef12345678"
# Parametrized test - test multiple inputs
@pytest.mark.parametrize("amount", [0, 1, 1000, 2**64 - 1])
def test_withdrawal_amount(amount):
 withdrawal = Withdrawal(
 index=0,
 validator_index=1,
 address=TEST_ADDRESS,
 amount=amount,
 )
 assert withdrawal.amount == amount # Check if amount is set correctly
# Exception testing
def test_withdrawal_amount_above_uint64_max():
 with pytest.raises(ValidationError) as e:
 Withdrawal(
 index=0,
 validator_index=1,
 address=TEST_ADDRESS,
 amount=2**64, # Exceeds uint64 max
 )
 assert " amount " in str(e.value)

Guide to Python Tools

Common Commands Reference

Docker

Building the Docker Image

# Build the test runtime image (default, for running tests)
docker build -t lean-spec:test .
# Build the node image (for running as a consensus node)
docker build --target node -t lean-spec:node .
# Build the development image (includes all dev tools)
docker build --target development -t lean-spec:dev .

Running Tests with Docker

# Run tests (default command for 'test' target)
docker run --rm lean-spec:test
# Run tests in parallel
docker run --rm lean-spec:test uv run pytest -n auto
# Run the fill command
docker run --rm lean-spec:test uv run fill --clean --fork=devnet

Running a Consensus Node with Docker

# Basic node
docker run --rm \
 -v /path/to/genesis:/app/data:ro \
 -p 9000:9000 \
 lean-spec:node \
 --genesis /app/data/config.yaml
# With bootnode
docker run --rm \
 -v /path/to/genesis:/app/data:ro \
 -p 9000:9000 \
 lean-spec:node \
 --genesis /app/data/config.yaml \
 --bootnode /ip4/127.0.0.1/tcp/9000

Documentation

Contributing

License