How ethereum/consensus-specs works
This repository publishes Ethereum proof-of-stake consensus specifications and includes a Python generator that turns Markdown specifications plus preset/configuration data into fork-specific Python spec modules. The principal workflow is selecting a fork and build target, locating inherited and fork-specific documents, parsing them, and assembling generated spec content. The README also identifies rendered viewers and reference tests as consumer-facing capabilities; their publishing and test infrastructure are not mapped here. The generation path is based on sampled source and the source index; links to unsampled assembly details are omitted.
Main entry points: generate_specs.py Generator CLI · md_doc_paths.py Document resolver · specs Fork specifications · md_to_spec.py Markdown parser
Components 14
Consensus specifications
- Fork specifications
specs - Feature specifications
specs/_features
Build inputs
- Network presets
presets - Network configs
configs
Spec generation
- Generator CLI
pysetup/generate_specs.py - Document resolver
pysetup/md_doc_paths.py - Markdown parser
pysetup/md_to_spec.py - Spec data model
pysetup/typing.py - Fork builders
pysetup/spec_builders - Spec assembly helpers
pysetup/helpers.py
Spec consumers
- Generated Python specs
- Rendered viewers
Other components
- Spec contributors
- Client implementers
Connections 13
- Spec contributors → Fork specifications: author
README.md - Spec contributors → Feature specifications: propose features
README.md - Generator CLI → Document resolver: find documents
pysetup/generate_specs.py - Generator CLI → Markdown parser: parse documents
pysetup/generate_specs.py - Generator CLI → Fork builders: select builder
pysetup/generate_specs.py - Generator CLI → Network presets: load preset
- Generator CLI → Network configs: load config
- Markdown parser → Spec data model: build objects
pysetup/md_to_spec.py - Document resolver → Fork specifications: locate documents
pysetup/md_doc_paths.py - Document resolver → Feature specifications: locate features
pysetup/md_doc_paths.py - Generator CLI → Generated Python specs: generate modules
pysetup/generate_specs.py - Generated Python specs → Client implementers: inform implementations
README.md - Fork specifications → Rendered viewers: render specifications
README.md