The Lean Ethereum protocol specifications and cryptographic subspecifications.
uv is a fast Python package manager that handles dependencies and Python versions.
curl -LsSf https://astral.sh/uv/install.sh | shThis project requires Python 3.12 or later and should be installed via uv:
# Install Python 3.12, or latest stable version
uv python install 3.12# Clone this repository
git clone https://github.com/leanEthereum/leanSpec leanSpec
cd leanSpec
# Install dependencies
uv sync --all-extras
# Run tests to verify setup
uv run pytest├── src/
│ ├── lean_spec/ # Main specifications
│ │ ├── __init__.py
│ │ └── ...
│ └── subspecs/ # Sub-specifications
│ ├── poseidon2/
│ │ ├── __init__.py
│ │ ├── poseidon2.py
│ │ └── ...
│ ├── ...
│ └── ...
├── tests/ # Test suite
│ ├── lean_spec/ # Tests for main specs
│ └── subspecs/ # Tests for subspecs
├── docs/ # Documentation
└── pyproject.toml # Project configuration
# Install package and required dependencies or re-sync workspace
uv sync
# Install package along with all dependencies, including optional / extras
uv sync --all-extras# 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"# Check code style and errors
uv run ruff check src tests
# Auto-fix issues
uv run ruff check --fix src tests
# Format code
uv run ruff format src tests
# Type checking
uv run mypy src testsAfter running uv sync --all-extras, you can use tox with uv run:
# Run all quality checks (lint, typecheck, spellcheck)
uv run tox -e all-checks
# Run all tox environments (all checks + tests + docs)
uv run tox
# Run specific environment
uv run tox -e lintAlternative: Using uvx (no setup required)
If you haven't run uv sync --all-extras or want to use tox in isolation,
you can use uvx, which:
- Creates a temporary environment just for tox
- Doesn't require
uv syncfirst - Uses tox-uv for faster dependency installation
uvx --with=tox-uv tox -e all-checks# Serve docs locally (with auto-reload)
uv run mkdocs serve
# Build docs
uv run mkdocs build# 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)- Pydantic models: Think of these as strongly-typed data structures that validate inputs automatically
- pytest: Testing framework - just name test files
test_*.pyand functionstest_* - uv: Fast Python package manager - like npm/yarn but for Python
- ruff: Linter and formatter
- mypy: Type checker that works with Pydantic models
- tox: Automation tool for running tests across multiple environments
- mkdocs: Documentation generator - write docs in Markdown, serve them locally
| Task | Command |
|---|---|
| Install dependencies | uv sync --all-extras |
| Run tests | uv run pytest |
| Format code | uv run ruff format src tests |
| Lint code | uv run ruff check src tests |
| Fix lint errors | uv run ruff check --fix src tests |
| Type check | uv run mypy src tests |
| Build docs | uv run mkdocs build |
| Serve docs | uv run mkdocs serve |
| Run all quality checks (no tests/docs) | uv run tox -e all-checks |
| Run everything (checks + tests + docs) | uv run tox |
| Run specific tox environment | uv run tox -e lint |
If you have not run uv sync --all-extras or want to use tox in isolation,
you can use uvx:
| Task | Command |
|---|---|
| Run all quality checks (no tests/docs) | uvx --with=tox-uv tox -e all-checks |
| Run everything (checks + tests + docs) | uvx --with=tox-uv tox |
| Run specific tox environment | uvx --with=tox-uv tox -e lint |
See CONTRIBUTING.md for more guidelines.
MIT License - see LICENSE file for details.