ethereum · jtraglia · Oct 1, 2025 · Oct 1, 2025 · Oct 1, 2025 · Oct 1, 2025
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -1,9 +1,11 @@
 version: 2
 updates:
-   - package-ecosystem: pip
-     directory: /
+
+updates:
+   - package-ecosystem: "uv"
+     directory: "/"
      schedule:
-        interval: weekly
+       interval: "weekly"
      groups:
         actions:
            patterns:

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -1,4 +1,3 @@
-
 name: Publish docs
 
 on:
@@ -16,11 +15,16 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
-      - name: Setup python
+      - name: Set up Python
         uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
         with:
-          python-version: '3.13'
-          cache: 'pip'
+          python-version-file: "pyproject.toml"
+
+      - name: Install uv ${{ vars.UV_VERSION }}
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          enable-cache: true
+          version: ${{ vars.UV_VERSION }}
 
       - name: Install dependencies to venv
         run: make _pyspec
@@ -29,4 +33,4 @@ jobs:
         run: make _copy_docs
 
       - name: Deploy
-        run: venv/bin/mkdocs gh-deploy --force
+        run: uv run mkdocs gh-deploy --force
diff --git a/.github/workflows/generate_vectors.yml b/.github/workflows/generate_vectors.yml
@@ -18,24 +18,28 @@ on:
         type: string
         required: true
   schedule:
-    - cron:  '0 2 * * *'
+    - cron: "0 2 * * *"
 
 jobs:
   generate-tests:
-    timeout-minutes: 720  # 12 hours
+    timeout-minutes: 720 # 12 hours
     runs-on: [self-hosted-ghr-custom, size-xl-x64, profile-consensusSpecs]
     steps:
       - name: Checkout repository
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           repository: ${{ inputs.repo }}
-          path: 'consensus-specs'
+          path: "consensus-specs"
           ref: ${{ inputs.ref }}
-      - name: Setup Python
+      - name: Set up Python
         uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
         with:
-          python-version: '3.13'
-          cache: ''
+          python-version-file: "consensus-specs/pyproject.toml"
+      - name: Install uv ${{ vars.UV_VERSION }}
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          enable-cache: true
+          version: ${{ vars.UV_VERSION }}
       - name: Generate tests
         run: |
           cd consensus-specs

diff --git a/.github/workflows/nightly-tests.yml b/.github/workflows/nightly-tests.yml
@@ -14,11 +14,11 @@ on:
         required: true
   schedule:
     # Every day at 00:00 UTC
-    - cron: '0 0 * * *'
+    - cron: "0 0 * * *"
 
 jobs:
   tests:
-    timeout-minutes: 720  # 12 hours
+    timeout-minutes: 720 # 12 hours
     runs-on: [self-hosted-ghr-custom, size-s-x64, profile-consensusSpecs]
     strategy:
       fail-fast: false
@@ -37,10 +37,15 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
-      - name: Setup Python
+      - name: Set up Python
         uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
         with:
-          python-version: '3.13'
+          python-version-file: "pyproject.toml"
+      - name: Install uv ${{ vars.UV_VERSION }}
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          enable-cache: true
+          version: ${{ vars.UV_VERSION }}
       - name: test-${{ matrix.fork }}
         run: make test component=pyspec preset=mainnet fork=${{ matrix.fork }}
       - name: Prepare test results for upload

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -3,11 +3,11 @@ name: Release
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
 
 jobs:
   release:
-    timeout-minutes: 1440  # 24 hours
+    timeout-minutes: 1440 # 24 hours
     runs-on: [self-hosted-ghr-custom, size-xl-x64, profile-consensusSpecs]
     permissions:
       contents: write
@@ -19,13 +19,19 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
-          path: 'consensus-specs'
+          path: "consensus-specs"
 
       # Setup python
-      - name: Setup Python
+      - name: Set up Python
         uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
         with:
-          python-version: '3.13'
+          python-version-file: "consensus-specs/pyproject.toml"
+
+      - name: Install uv ${{ vars.UV_VERSION }}
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          enable-cache: true
+          version: ${{ vars.UV_VERSION }}
 
       # Check the tag matches the version
       - name: Version check

diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
@@ -18,11 +18,15 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
-      - name: Setup python
+      - name: Set up Python
         uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
         with:
-          python-version: '3.13'
-          cache: 'pip'
+          python-version-file: "pyproject.toml"
+      - name: Install uv ${{ vars.UV_VERSION }}
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          enable-cache: true
+          version: ${{ vars.UV_VERSION }}
       - name: Run linter for pyspec
         run: |
           make lint
@@ -45,11 +49,10 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
-      - name: Setup python
+      - name: Set up Python
         uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
         with:
-          python-version: '3.13'
-          cache: 'pip'
+          python-version-file: "pyproject.toml"
       - name: Check fork comments
         run: python3 scripts/check_fork_comments.py
 
@@ -58,11 +61,15 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
-      - name: Setup python
+      - name: Set up Python
         uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
         with:
-          python-version: '3.13'
-          cache: 'pip'
+          python-version-file: "pyproject.toml"
+      - name: Install uv ${{ vars.UV_VERSION }}
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          enable-cache: true
+          version: ${{ vars.UV_VERSION }}
       - name: Run framework tests
         run: make test component=fw
       - name: Prepare test results for upload
@@ -94,11 +101,15 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
-      - name: Setup python
+      - name: Set up Python
         uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
         with:
-          python-version: '3.13'
-          cache: 'pip'
+          python-version-file: "pyproject.toml"
+      - name: Install uv ${{ vars.UV_VERSION }}
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          enable-cache: true
+          version: ${{ vars.UV_VERSION }}
       - name: Run pyspec tests for ${{ matrix.fork }}
         run: make test component=pyspec preset=minimal fork=${{ matrix.fork }}
       - name: Prepare test results for upload

diff --git a/Makefile b/Makefile
@@ -18,6 +18,7 @@ ALL_EXECUTABLE_SPEC_NAMES = \
 
 # A list of fake targets.
 .PHONY: \
+	_sync         \
 	clean         \
 	coverage      \
 	help          \
@@ -173,7 +174,7 @@ help-verbose:
 	@echo "$(BOLD)make clean$(NORM)"
 	@echo ""
 	@echo "  Removes all untracked files. This includes:"
-	@echo "    - Virtual environment (venv/)"
+	@echo "    - Virtual environment (.venv/)"
 	@echo "    - Build artifacts"
 	@echo "    - Cache files"
 	@echo ""
@@ -187,19 +188,18 @@ help-verbose:
 # Virtual Environment
 ###############################################################################
 
-VENV = venv
-PYTHON_VENV = $(VENV)/bin/python3
-PIP_VENV = $(VENV)/bin/pip3
-CODESPELL_VENV = $(VENV)/bin/codespell
-MDFORMAT_VENV = $(VENV)/bin/mdformat
-MKDOCS_VENV = $(VENV)/bin/mkdocs
+VENV = .venv
+UV_RUN = uv run
 
-# Make a virtual environment.
-$(VENV):
-	@python3 scripts/check_python_version.py
-	@echo "Creating virtual environment"
-	@python3 -m venv $(VENV)
-	@$(PIP_VENV) install --quiet --upgrade uv
+# Sync dependencies using uv.
+_sync: MAYBE_VERBOSE := $(if $(filter true,$(verbose)),--verbose)
+_sync: pyproject.toml
+	@command -v uv >/dev/null 2>&1 || { \
+		echo "Error: uv is required but not installed."; \
+		echo "Install with: curl -LsSf https://astral.sh/uv/install.sh | sh"; \
+		exit 1; \
+	}
+	@uv sync --all-extras $(MAYBE_VERBOSE)
 
 ###############################################################################
 # Specification
@@ -210,14 +210,8 @@ PYSPEC_DIR = $(TEST_LIBS_DIR)/pyspec
 
 # Create the pyspec for all phases.
 _pyspec: MAYBE_VERBOSE := $(if $(filter true,$(verbose)),--verbose)
-_pyspec: $(VENV) setup.py pyproject.toml
-	@python3 scripts/check_python_version.py
-	@$(PYTHON_VENV) -m uv pip install $(MAYBE_VERBOSE) --reinstall-package=eth2spec .[docs,lint,test,generator]
-	@for dir in $(ALL_EXECUTABLE_SPEC_NAMES); do \
-	    mkdir -p "./tests/core/pyspec/eth2spec/$$dir"; \
-	    cp "./build/lib/eth2spec/$$dir/mainnet.py" "./tests/core/pyspec/eth2spec/$$dir/mainnet.py"; \
-	    cp "./build/lib/eth2spec/$$dir/minimal.py" "./tests/core/pyspec/eth2spec/$$dir/minimal.py"; \
-	done
+_pyspec: _sync
+	@$(UV_RUN) python -m pysetup.generate_specs --all-forks $(MAYBE_VERBOSE)
 
 ###############################################################################
 # Testing
@@ -237,7 +231,7 @@ test: MAYBE_ETH2SPEC := $(if $(filter fw,$(component)),,$(PYSPEC_DIR)/eth2spec)
 test: MAYBE_INFRA := $(if $(filter pyspec,$(component)),,$(CURDIR)/tests/infra)
 test: _pyspec
 	@mkdir -p $(TEST_REPORT_DIR)
-	@$(PYTHON_VENV) -m pytest \
+	@$(UV_RUN) pytest \
 		$(MAYBE_PARALLEL) \
 		--capture=no \
 		$(MAYBE_TEST) \
@@ -263,7 +257,7 @@ COVERAGE_SCOPE := $(foreach S,$(ALL_EXECUTABLE_SPEC_NAMES), --cov=eth2spec.$S.$(
 _test_with_coverage: MAYBE_TEST := $(if $(k),-k=$(k))
 _test_with_coverage: MAYBE_FORK := $(if $(fork),--fork=$(fork))
 _test_with_coverage: _pyspec
-	@$(PYTHON_VENV) -m pytest \
+	@$(UV_RUN) pytest \
 		-n auto \
 		$(MAYBE_TEST) \
 		$(MAYBE_FORK) \
@@ -300,27 +294,25 @@ _copy_docs:
 
 # Start a local documentation server.
 serve_docs: _pyspec _copy_docs
-	@$(MKDOCS_VENV) build
-	@$(MKDOCS_VENV) serve
+	@$(UV_RUN) mkdocs build
+	@$(UV_RUN) mkdocs serve
 
 ###############################################################################
 # Checks
 ###############################################################################
 
-MYPY_CONFIG = $(CURDIR)/mypy.ini
-PYLINT_CONFIG = $(CURDIR)/pylint.ini
-
-PYLINT_SCOPE := $(foreach S,$(ALL_EXECUTABLE_SPEC_NAMES), $(PYSPEC_DIR)/eth2spec/$S)
-MYPY_SCOPE := $(foreach S,$(ALL_EXECUTABLE_SPEC_NAMES), -p eth2spec.$S)
 MARKDOWN_FILES := $(shell find $(CURDIR) -name '*.md')
+MYPY_PACKAGE_BASE := $(subst /,.,$(PYSPEC_DIR:$(CURDIR)/%=%))
+MYPY_SCOPE := $(foreach S,$(ALL_EXECUTABLE_SPEC_NAMES), -p $(MYPY_PACKAGE_BASE).eth2spec.$S)
 
 # Check for mistakes.
 lint: _pyspec
-	@$(MDFORMAT_VENV) --number --wrap=80 $(MARKDOWN_FILES)
-	@$(CODESPELL_VENV) . --skip "./.git,$(VENV),$(PYSPEC_DIR)/.mypy_cache" -I .codespell-whitelist
-	@$(PYTHON_VENV) -m ruff check --fix --quiet $(CURDIR)/tests $(CURDIR)/pysetup $(CURDIR)/setup.py
-	@$(PYTHON_VENV) -m ruff format --quiet $(CURDIR)/tests $(CURDIR)/pysetup $(CURDIR)/setup.py
-	@$(PYTHON_VENV) -m mypy --config-file $(MYPY_CONFIG) $(MYPY_SCOPE)
+	@uv --quiet lock --check
+	@$(UV_RUN) mdformat --number --wrap=80 $(MARKDOWN_FILES)
+	@$(UV_RUN) codespell . --skip "./.git,$(VENV),$(PYSPEC_DIR)/.mypy_cache" -I .codespell-whitelist
+	@$(UV_RUN) ruff check --fix --quiet $(CURDIR)/tests $(CURDIR)/pysetup $(CURDIR)/setup.py
+	@$(UV_RUN) ruff format --quiet $(CURDIR)/tests $(CURDIR)/pysetup $(CURDIR)/setup.py
+	@$(UV_RUN) mypy $(MYPY_SCOPE)
 
 ###############################################################################
 # Generators
@@ -338,7 +330,7 @@ reftests: MAYBE_TESTS := $(if $(k),--cases $(subst ${COMMA}, ,$(k)))
 reftests: MAYBE_FORKS := $(if $(fork),--forks $(subst ${COMMA}, ,$(fork)))
 reftests: MAYBE_PRESETS := $(if $(preset),--presets $(subst ${COMMA}, ,$(preset)))
 reftests: _pyspec
-	@$(PYTHON_VENV) -m tests.generators.main \
+	@$(UV_RUN) python -m tests.generators.main \
 		--output $(TEST_VECTOR_DIR) \
 		$(MAYBE_VERBOSE) \
 		$(MAYBE_THREADS) \
@@ -354,7 +346,7 @@ comptests: MAYBE_FORKS := $(if $(fork),--forks $(subst ${COMMA}, ,$(fork)))
 comptests: MAYBE_PRESETS := $(if $(preset),--presets $(subst ${COMMA}, ,$(preset)))
 comptests: MAYBE_SEED := $(if $(seed),--fc-gen-seed $(seed))
 comptests: _pyspec
-	@$(PYTHON_VENV) -m tests.generators.compliance_runners.fork_choice.test_gen \
+	@$(UV_RUN) python -m tests.generators.compliance_runners.fork_choice.test_gen \
 		--output $(COMP_TEST_VECTOR_DIR) \
 		--fc-gen-config $(FC_GEN_CONFIG) \
 		$(MAYBE_THREADS) \

diff --git a/README.md b/README.md
@@ -61,6 +61,21 @@ reference tests are available
 
 ## Contributors
 
+### Prerequisites
+
+This project uses `uv` ([docs.astral.sh/uv](https://docs.astral.sh/uv/)) to
+manage its dependencies and virtual environment. `uv` can
+[download Python](https://docs.astral.sh/uv/guides/install-python/#installing-a-specific-version)
+for your target platform if one of the required versions (3.10-3.13) is not
+available natively.
+
+`uv` can be installed via curl (recommended over a pip-install as it can
+self-update and manage Python versions):
+
+```console
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
 ### Installation and usage
 
 Clone the repository with:

diff --git a/mypy.ini b/mypy.ini
diff --git a/pylint.ini b/pylint.ini