Python specifications and protocol definitions for Ethereum distributed validators. This repository contains the core data structures, validation rules, and protocol specifications needed to implement distributed validator technology.
The goal of these specifications is to describe the Obol distributed validator protocol precisely enough that independent implementations can interoperate within the same cluster.
| Client | Language | Maintainer | Status |
|---|---|---|---|
| Charon | Go | Obol | Production; reference implementation |
| Pluto | Rust | Nethermind | In development |
Charon is the reference implementation these specs are derived from. Pluto is an independent implementation targeting full wire-level compatibility with Charon; these specs are the intended source of truth for that interoperability.
These specs track Charon main and were last validated against Charon
commit 2eb6798e (2026-07-14, after v1.10.3, during v1.11.0 release
candidates).
Note for implementers pinned to older Charon versions (e.g. Pluto currently
targets v1.7.1): some specified behaviors landed after v1.7.1:
| Behavior | First Charon release |
|---|---|
MsgSync.nickname field (DKG sync) |
v1.9.0 |
| Deterministic (genesis-derived) eager double linear round deadlines | v1.9.0 |
| Linear round timer subsequent-round timeout fix | v1.11.0 |
| QBFT DECIDED-resend rate limit and message size/count limits | v1.11.0 |
All of these are backwards compatible on the wire (unknown proto fields are ignored; limits only reject messages no honest peer sends), so implementing the current spec remains interoperable with older Charon peers.
Interoperability specs and reference models:
- Canonical Encoding and Hashing: Deterministic protobuf encoding and the SSZ hash root every signature and value hash is taken over
- Consensus (QBFT): QBFT consensus protocol for reaching agreement among distributed validator nodes
- Partial Signature Exchange (ParSigEx): Protocol for exchanging partially signed duty data among distributed validator nodes
- Signature Aggregation (SigAgg): Threshold trigger and BLS threshold aggregation of partial signatures into the group signature
- Peer Information (PeerInfo): Protocol for exchanging node metadata and monitoring cluster health
- FROST DKG: The default distributed key generation protocol for generating BLS validator keys
- Pedersen DKG: The opt-in alternative DKG algorithm, selected with
dkg_algorithm: pedersen - Cluster Edit Protocols: Reshare, add, remove and replace operators on an existing cluster
- DKG Sync: Synchronization protocol to coordinate distributed key generation ceremonies between nodes
- Reliable Broadcast: Two-phase signed broadcast component to prevent equivocation in DKG protocols
- Cluster Files: File formats for cluster definition and lock files
- ValidatorAPI: Reverse proxy and middleware layer between validator clients and beacon nodes
- Beacon Broadcast: Submitting aggregated signed duty data to the beacon node
- Duty Scheduling: Protocol for scheduling and executing beacon chain duties including slot timing and deadline calculation
- Priority: Protocol for achieving cluster-wide consensus on ordered preference lists
- InfoSync: Cluster-wide agreement on versions, protocols and proposal types; selects the consensus protocol
- Types and primitives: Base types and helpers used by the specs
- Test vectors: Conformance fixtures for implementers, most of them generated by charon itself
- Tests and docs: Verification and documentation for implementers
uv is a fast Python package manager that handles dependencies and Python versions.
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | shThis project requires Python 3.12 or later. Install it via uv:
# Install Python 3.12 (or latest stable version)
uv python install 3.12# Clone this repository
git clone https://github.com/ObolNetwork/distributed-validator-specs distributed-validator-specs
cd distributed-validator-specs
# Install dependencies
uv sync --all-extras
# Run tests to verify setup
uv run pytest├── proto/ # Protocol Buffer definitions
├── src/
│ └── dv_spec/ # Library: specs and reference models
│ ├── validator.py # Core DV data structures (types/helpers)
│ ├── client/ # Client configuration examples
│ ├── cluster/ # Cluster definition and lock files, and their hashes
│ ├── crypto/ # BLS12-381 and secp256k1 signatures
│ ├── encoding/ # Deterministic proto encoding and SSZ hashing
│ ├── subspecs/ # Protocol implementations
│ │ ├── reliable_bcast/ # Reliable broadcast (charon's dkg/bcast)
│ │ ├── consensus/ # QBFT consensus
│ │ ├── dkg/ # FROST and Pedersen DKG, node signatures
│ │ ├── dkg_sync/ # DKG synchronization
│ │ ├── infosync/ # Cluster-wide capability agreement
│ │ ├── parsigex/ # Partial signature exchange
│ │ ├── peerinfo/ # Peer info
│ │ ├── priority/ # Priority protocol
│ │ └── sigagg/ # Threshold signature aggregation
│ └── types/ # Ethereum-compatible base types
├── scripts/ # Test vector generation
├── test_vectors/ # Conformance fixtures (JSON, one file per suite)
├── tests/ # Test suite
└── docs/
├── dv-spec/ # Protocol specifications
│ ├── broadcast.md # Submitting aggregated duty data to the beacon node
│ ├── cluster-files.md # File formats for cluster definition and lock files
│ ├── consensus.md # QBFT consensus protocol for reaching agreement
│ ├── dkg-cluster-edits.md # Reshare, add, remove and replace operators
│ ├── dkg-frost.md # FROST DKG, the default key generation algorithm
│ ├── dkg-pedersen.md # Pedersen DKG, the opt-in alternative algorithm
│ ├── dkg-sync.md # Synchronization protocol for DKG ceremonies
│ ├── duty-scheduling.md # Scheduling and executing beacon chain duties
│ ├── hashing.md # Deterministic proto encoding and SSZ hash roots
│ ├── infosync.md # Cluster-wide capability agreement and protocol selection
│ ├── parsigex.md # Partial signature exchange protocol
│ ├── peerinfo.md # Node metadata exchange and cluster health monitoring
│ ├── priority.md # Cluster-wide consensus on ordered preference lists
│ ├── reliable-broadcast.md # Two-phase broadcast to prevent equivocation
│ ├── sigagg.md # Threshold trigger and BLS threshold aggregation
│ └── validatorapi.md # Reverse proxy and middleware for VC-BN interaction
└── client/ # Additional client documentation
# 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
uv run pytest -n auto# 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| Task | Command |
|---|---|
| Install dependencies | uv sync --all-extras |
| Run tests | uv run pytest |
| Format code | uv run ruff format src tests scripts |
| Lint code | uv run ruff check src tests scripts |
| Fix lint errors | uv run ruff check --fix src tests scripts |
| Type check | uv run mypy src tests scripts |
| Regenerate test vectors | uv run python scripts/generate_test_vectors.py |
| 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 |
- Pydantic models: Type-safe data structures with automatic validation - perfect for protocol specifications
- uv: Ultra-fast Python package manager and project management
- pytest: Testing framework with excellent parametrization and fixtures
- ruff: Lightning-fast linter and formatter (replaces black, flake8, isort)
- mypy: Static type checker that works seamlessly with Pydantic
- tox: Runs tests across multiple Python versions and environments
- mkdocs: Documentation generator for protocol specifications
- coverage: Test coverage reporting to ensure thorough testing
See CONTRIBUTING.md for more guidelines.
MIT License - see LICENSE file for details.