# ethereum/consensus-specs architecture

> Architecture diagram of the GitHub repository ethereum/consensus-specs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ethereum/consensus-specs
- Repository: https://github.com/ethereum/consensus-specs

## Overview

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: [`pysetup/generate_specs.py`](https://github.com/ethereum/consensus-specs/blob/master/pysetup/generate_specs.py) (Generator CLI), [`pysetup/md_doc_paths.py`](https://github.com/ethereum/consensus-specs/blob/master/pysetup/md_doc_paths.py) (Document resolver), [`specs`](https://github.com/ethereum/consensus-specs/tree/master/specs) (Fork specifications), [`pysetup/md_to_spec.py`](https://github.com/ethereum/consensus-specs/blob/master/pysetup/md_to_spec.py) (Markdown parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_specs["Consensus specifications"]
  node_fork_docs["Fork specifications"]
  node_feature_docs["Feature specifications"]
end

subgraph group_inputs["Build inputs"]
  node_presets["Network presets"]
  node_configs["Network configs"]
end

subgraph group_generator["Spec generation"]
  node_generator_cli["Generator CLI<br/>[generate_specs.py]"]
  node_path_resolver["Document resolver<br/>[md_doc_paths.py]"]
  node_markdown_parser["Markdown parser<br/>[md_to_spec.py]"]
  node_spec_types["Spec data model<br/>[typing.py]"]
  node_fork_builders["Fork builders"]
  node_assembly_helpers["Spec assembly helpers<br/>[helpers.py]"]
end

subgraph group_consumers["Spec consumers"]
  node_generated_specs["Generated Python specs"]
  node_spec_viewers["Rendered viewers"]
end

node_engineers(("Spec contributors"))
node_client_implementers(("Client implementers"))

node_engineers -->|"author"| node_fork_docs
node_engineers -->|"propose features"| node_feature_docs
node_generator_cli -->|"find documents"| node_path_resolver
node_generator_cli -->|"parse documents"| node_markdown_parser
node_generator_cli -->|"select builder"| node_fork_builders
node_generator_cli -.->|"load preset"| node_presets
node_generator_cli -.->|"load config"| node_configs
node_markdown_parser -->|"build objects"| node_spec_types
node_path_resolver -->|"locate documents"| node_fork_docs
node_path_resolver -->|"locate features"| node_feature_docs
node_generator_cli -->|"generate modules"| node_generated_specs
node_generated_specs -->|"inform implementations"| node_client_implementers
node_fork_docs -->|"render specifications"| node_spec_viewers

click node_fork_docs "https://github.com/ethereum/consensus-specs/tree/master/specs"
click node_feature_docs "https://github.com/ethereum/consensus-specs/tree/master/specs/_features"
click node_presets "https://github.com/ethereum/consensus-specs/tree/master/presets"
click node_configs "https://github.com/ethereum/consensus-specs/tree/master/configs"
click node_generator_cli "https://github.com/ethereum/consensus-specs/blob/master/pysetup/generate_specs.py"
click node_path_resolver "https://github.com/ethereum/consensus-specs/blob/master/pysetup/md_doc_paths.py"
click node_markdown_parser "https://github.com/ethereum/consensus-specs/blob/master/pysetup/md_to_spec.py"
click node_spec_types "https://github.com/ethereum/consensus-specs/blob/master/pysetup/typing.py"
click node_fork_builders "https://github.com/ethereum/consensus-specs/tree/master/pysetup/spec_builders"
click node_assembly_helpers "https://github.com/ethereum/consensus-specs/blob/master/pysetup/helpers.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fork_docs,node_feature_docs,node_client_implementers toneBlue
class node_presets,node_configs toneAmber
class node_generator_cli,node_path_resolver,node_markdown_parser,node_spec_types,node_fork_builders,node_assembly_helpers toneMint
class node_generated_specs,node_spec_viewers toneRose
class node_engineers toneIndigo
```

## Components

### Consensus specifications

- [Fork specifications](https://github.com/ethereum/consensus-specs/tree/master/specs): `specs`
- [Feature specifications](https://github.com/ethereum/consensus-specs/tree/master/specs/_features): `specs/_features`

### Build inputs

- [Network presets](https://github.com/ethereum/consensus-specs/tree/master/presets): `presets`
- [Network configs](https://github.com/ethereum/consensus-specs/tree/master/configs): `configs`

### Spec generation

- [Generator CLI](https://github.com/ethereum/consensus-specs/blob/master/pysetup/generate_specs.py): `pysetup/generate_specs.py`
- [Document resolver](https://github.com/ethereum/consensus-specs/blob/master/pysetup/md_doc_paths.py): `pysetup/md_doc_paths.py`
- [Markdown parser](https://github.com/ethereum/consensus-specs/blob/master/pysetup/md_to_spec.py): `pysetup/md_to_spec.py`
- [Spec data model](https://github.com/ethereum/consensus-specs/blob/master/pysetup/typing.py): `pysetup/typing.py`
- [Fork builders](https://github.com/ethereum/consensus-specs/tree/master/pysetup/spec_builders): `pysetup/spec_builders`
- [Spec assembly helpers](https://github.com/ethereum/consensus-specs/blob/master/pysetup/helpers.py): `pysetup/helpers.py`

### Spec consumers

- **Generated Python specs**
- **Rendered viewers**

### Other components

- **Spec contributors**
- **Client implementers**

## Connections

- Spec contributors → Fork specifications: author (evidence: `README.md`)
- Spec contributors → Feature specifications: propose features (evidence: `README.md`)
- Generator CLI → Document resolver: find documents (evidence: `pysetup/generate_specs.py`)
- Generator CLI → Markdown parser: parse documents (evidence: `pysetup/generate_specs.py`)
- Generator CLI → Fork builders: select builder (evidence: `pysetup/generate_specs.py`)
- Generator CLI → Network presets: load preset
- Generator CLI → Network configs: load config
- Markdown parser → Spec data model: build objects (evidence: `pysetup/md_to_spec.py`)
- Document resolver → Fork specifications: locate documents (evidence: `pysetup/md_doc_paths.py`)
- Document resolver → Feature specifications: locate features (evidence: `pysetup/md_doc_paths.py`)
- Generator CLI → Generated Python specs: generate modules (evidence: `pysetup/generate_specs.py`)
- Generated Python specs → Client implementers: inform implementations (evidence: `README.md`)
- Fork specifications → Rendered viewers: render specifications (evidence: `README.md`)
