Merge pull request #3323 from ethereum/dev

Capella mainnet release

.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+
+name: Publish docs
+on:
+  push:
+    branches:
+      - master 
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Build docs
+        run: make copy_docs
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - uses: actions/cache@v2
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - run: pip install -e .[docs]
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -35,3 +35,11 @@ tests/core/pyspec/eth2spec/test_results.xml
 
 # TOC tool outputs temporary files
 *.tmp
+
+# docs reader build
+docs/specs
+docs/sync
+docs/ssz
+docs/fork_choice
+docs/README.md
+site

Makefile

@@ -19,6 +19,11 @@ GENERATORS = $(sort $(dir $(wildcard $(GENERATOR_DIR)/*/.)))
 # Map this list of generator paths to "gen_{generator name}" entries
 GENERATOR_TARGETS = $(patsubst $(GENERATOR_DIR)/%/, gen_%, $(GENERATORS))
 GENERATOR_VENVS = $(patsubst $(GENERATOR_DIR)/%, $(GENERATOR_DIR)/%venv, $(GENERATORS))
+# Documents
+DOCS_DIR = ./docs
+SSZ_DIR = ./ssz
+SYNC_DIR = ./sync
+FORK_CHOICE_DIR = ./fork_choice
 
 # To check generator matching:
 #$(info $$GENERATOR_TARGETS is [${GENERATOR_TARGETS}])
@@ -214,3 +219,23 @@ detect_generator_incomplete: $(TEST_VECTOR_DIR)
 
 detect_generator_error_log: $(TEST_VECTOR_DIR)
 	[ -f $(GENERATOR_ERROR_LOG_FILE) ] && echo "[ERROR] $(GENERATOR_ERROR_LOG_FILE) file exists" || echo "[PASSED] error log file does not exist"
+
+
+# For docs reader
+install_docs:
+	python3 -m venv venv; . venv/bin/activate; python3 -m pip install -e .[docs];
+
+copy_docs:
+	cp -r $(SPEC_DIR) $(DOCS_DIR);
+	cp -r $(SYNC_DIR) $(DOCS_DIR);
+	cp -r $(SSZ_DIR) $(DOCS_DIR);
+	cp -r $(FORK_CHOICE_DIR) $(DOCS_DIR);
+	cp $(CURRENT_DIR)/README.md $(DOCS_DIR)/README.md
+
+build_docs: copy_docs
+	. venv/bin/activate;
+	mkdocs build
+
+serve_docs:
+	. venv/bin/activate; 
+	mkdocs serve

README.md

@@ -1,6 +1,6 @@
 # Ethereum Proof-of-Stake Consensus Specifications
 
-[![Join the chat at https://discord.gg/qGpsxSA](https://img.shields.io/badge/chat-on%20discord-blue.svg)](https://discord.gg/qGpsxSA) [![Join the chat at https://gitter.im/ethereum/sharding](https://badges.gitter.im/ethereum/sharding.svg)](https://gitter.im/ethereum/sharding?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Join the chat at https://discord.gg/qGpsxSA](https://img.shields.io/badge/chat-on%20discord-blue.svg)](https://discord.gg/qGpsxSA)
 
 To learn more about proof-of-stake and sharding, see the [PoS documentation](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/), [sharding documentation](https://ethereum.org/en/upgrades/sharding/) and the [research compendium](https://notes.ethereum.org/s/H1PGqDhpm).
 
@@ -65,6 +65,10 @@ Documentation on the different components used during spec writing can be found
 * [YAML Test Generators](tests/generators/README.md)
 * [Executable Python Spec, with Py-tests](tests/core/pyspec/README.md)
 
+## Online viewer of the latest release (latest `master` branch)
+
+[Ethereum Consensus Specs](https://ethereum.github.io/consensus-specs/)
+
 ## Consensus spec tests
 
 Conformance tests built from the executable python spec are available in the [Ethereum Proof-of-Stake Consensus Spec Tests](https://github.com/ethereum/consensus-spec-tests) repo. Compressed tarballs are available in [releases](https://github.com/ethereum/consensus-spec-tests/releases).

docs/.pages

@@ -0,0 +1,5 @@
+nav:
+    - Home:
+        - README.md
+    - specs
+    - ...

docs/README.md

@@ -0,0 +1,70 @@
+# Ethereum Proof-of-Stake Consensus Specifications
+
+[![Join the chat at https://discord.gg/qGpsxSA](https://img.shields.io/badge/chat-on%20discord-blue.svg)](https://discord.gg/qGpsxSA) [![Join the chat at https://gitter.im/ethereum/sharding](https://badges.gitter.im/ethereum/sharding.svg)](https://gitter.im/ethereum/sharding?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
+To learn more about proof-of-stake and sharding, see the [PoS documentation](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/), [sharding documentation](https://ethereum.org/en/upgrades/sharding/) and the [research compendium](https://notes.ethereum.org/s/H1PGqDhpm).
+
+This repository hosts the current Ethereum proof-of-stake specifications. Discussions about design rationale and proposed changes can be brought up and discussed as issues. Solidified, agreed-upon changes to the spec can be made through pull requests.
+
+## Specs
+
+[![GitHub release](https://img.shields.io/github/v/release/ethereum/eth2.0-specs)](https://github.com/ethereum/eth2.0-specs/releases/) [![PyPI version](https://badge.fury.io/py/eth2spec.svg)](https://badge.fury.io/py/eth2spec)
+
+Core specifications for Ethereum proof-of-stake clients can be found in [specs](specs/). These are divided into features.
+Features are researched and developed in parallel, and then consolidated into sequential upgrades when ready.
+
+### Stable Specifications
+
+| Seq. | Code Name | Fork Epoch | Specs |
+| - | - | - | - |
+| 0 | **Phase0** |`0` | <ul><li>Core</li><ul><li>[The beacon chain](specs/phase0/beacon-chain.md)</li><li>[Deposit contract](specs/phase0/deposit-contract.md)</li><li>[Beacon chain fork choice](specs/phase0/fork-choice.md)</li></ul><li>Additions</li><ul><li>[Honest validator guide](specs/phase0/validator.md)</li><li>[P2P networking](specs/phase0/p2p-interface.md)</li><li>[Weak subjectivity](specs/phase0/weak-subjectivity.md)</li></ul></ul> |
+| 1 |  **Altair** | `74240` | <ul><li>Core</li><ul><li>[Beacon chain changes](specs/altair/beacon-chain.md)</li><li>[Altair fork](specs/altair/fork.md)</li></ul><li>Additions</li><ul><li>[Light client sync protocol](specs/altair/light-client/sync-protocol.md) ([full node](specs/altair/light-client/full-node.md), [light client](specs/altair/light-client/light-client.md), [networking](specs/altair/light-client/p2p-interface.md))</li><li>[Honest validator guide changes](specs/altair/validator.md)</li><li>[P2P networking](specs/altair/p2p-interface.md)</li></ul></ul> |
+| 2 | **Bellatrix** <br/> (["The Merge"](https://ethereum.org/en/upgrades/merge/)) | `144896` | <ul><li>Core</li><ul><li>[Beacon Chain changes](specs/bellatrix/beacon-chain.md)</li><li>[Bellatrix fork](specs/bellatrix/fork.md)</li><li>[Fork choice changes](specs/bellatrix/fork-choice.md)</li></ul><li>Additions</li><ul><li>[Honest validator guide changes](specs/bellatrix/validator.md)</li><li>[P2P networking](specs/bellatrix/p2p-interface.md)</li></ul></ul> |
+| 3 | **Capella** | `194048` | <ul><li>Core</li><ul><li>[Beacon chain changes](specs/capella/beacon-chain.md)</li><li>[Capella fork](specs/capella/fork.md)</li></ul><li>Additions</li><ul><li>[Light client sync protocol changes](specs/capella/light-client/sync-protocol.md) ([fork](specs/capella/light-client/fork.md), [full node](specs/capella/light-client/full-node.md), [networking](specs/capella/light-client/p2p-interface.md))</li></ul><ul><li>[Validator additions](specs/capella/validator.md)</li><li>[P2P networking](specs/capella/p2p-interface.md)</li></ul></ul> |
+
+### In-development Specifications
+| Code Name or Topic | Specs | Notes |
+| - | - | - |
+| Deneb (tentative) | <ul><li>Core</li><ul><li>[Beacon Chain changes](specs/deneb/beacon-chain.md)</li><li>[Deneb fork](specs/deneb/fork.md)</li><li>[Polynomial commitments](specs/deneb/polynomial-commitments.md)</li><li>[Fork choice changes](specs/deneb/fork-choice.md)</li></ul><li>Additions</li><ul><li>[Light client sync protocol changes](specs/deneb/light-client/sync-protocol.md) ([fork](specs/deneb/light-client/fork.md), [full node](specs/deneb/light-client/full-node.md), [networking](specs/deneb/light-client/p2p-interface.md))</li></ul><ul><li>[Honest validator guide changes](specs/deneb/validator.md)</li><li>[P2P networking](specs/deneb/p2p-interface.md)</li></ul></ul> |
+| Sharding (outdated) | <ul><li>Core</li><ul><li>[Beacon Chain changes](specs/_features/sharding/beacon-chain.md)</li></ul><li>Additions</li><ul><li>[P2P networking](specs/_features/sharding/p2p-interface.md)</li></ul></ul> |
+| Custody Game (outdated) | <ul><li>Core</li><ul><li>[Beacon Chain changes](specs/_features/custody_game/beacon-chain.md)</li></ul><li>Additions</li><ul><li>[Honest validator guide changes](specs/_features/custody_game/validator.md)</li></ul></ul> | Dependent on sharding |
+| Data Availability Sampling (outdated) | <ul><li>Core</li><ul><li>[Core types and functions](specs/_features/das/das-core.md)</li><li>[Fork choice changes](specs/_features/das/fork-choice.md)</li></ul><li>Additions</li><ul><li>[P2P Networking](specs/_features/das/p2p-interface.md)</li><li>[Sampling process](specs/_features/das/sampling.md)</li></ul></ul> | <ul><li> Dependent on sharding</li><li>[Technical explainer](https://hackmd.io/@HWeNw8hNRimMm2m2GH56Cw/B1YJPGkpD)</li></ul> |
+| EIP-6110 | <ul><li>Core</li><ul><li>[Beacon Chain changes](specs/_features/eip6110//beacon-chain.md)</li><li>[EIP-6110 fork](specs/_features/eip6110/fork.md)</li></ul><li>Additions</li><ul><li>[Honest validator guide changes](specs/_features/eip6110/validator.md)</li></ul></ul> |
+
+### Accompanying documents can be found in [specs](specs) and include:
+
+* [SimpleSerialize (SSZ) spec](ssz/simple-serialize.md)
+* [Merkle proof formats](ssz/merkle-proofs.md)
+* [General test format](tests/formats/README.md)
+
+## Additional specifications for client implementers
+
+Additional specifications and standards outside of requisite client functionality can be found in the following repos:
+
+* [Beacon APIs](https://github.com/ethereum/beacon-apis)
+* [Beacon Metrics](https://github.com/ethereum/beacon-metrics/)
+
+## Design goals
+
+The following are the broad design goals for the Ethereum proof-of-stake consensus specifications:
+* to minimize complexity, even at the cost of some losses in efficiency
+* to remain live through major network partitions and when very large portions of nodes go offline
+* to select all components such that they are either quantum secure or can be easily swapped out for quantum secure counterparts when available
+* to utilize crypto and design techniques that allow for a large participation of validators in total and per unit time
+* to allow for a typical consumer laptop with `O(C)` resources to process/validate `O(1)` shards (including any system level validation such as the beacon chain)
+
+## Useful external resources
+
+* [Design Rationale](https://notes.ethereum.org/s/rkhCgQteN#)
+* [Phase 0 Onboarding Document](https://notes.ethereum.org/s/Bkn3zpwxB)
+* [Combining GHOST and Casper paper](https://arxiv.org/abs/2003.03052)
+
+## For spec contributors
+
+Documentation on the different components used during spec writing can be found here:
+* [YAML Test Generators](tests/generators/README.md)
+* [Executable Python Spec, with Py-tests](tests/core/pyspec/README.md)
+
+## Consensus spec tests
+
+Conformance tests built from the executable python spec are available in the [Ethereum Proof-of-Stake Consensus Spec Tests](https://github.com/ethereum/consensus-spec-tests) repo. Compressed tarballs are available in [releases](https://github.com/ethereum/consensus-spec-tests/releases).

docs/docs/new-feature.md

@@ -0,0 +1,163 @@
+# How to add a new feature proposal in consensus-specs
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [A. Make it executable for linter checks](#a-make-it-executable-for-linter-checks)
+  - [1. Create a folder under `./specs/_features`](#1-create-a-folder-under-specs_features)
+  - [2. Choose the "previous fork" to extend: usually, use the scheduled or the latest mainnet fork version.](#2-choose-the-previous-fork-to-extend-usually-use-the-scheduled-or-the-latest-mainnet-fork-version)
+  - [3. Write down your proposed `beacon-chain.md` change](#3-write-down-your-proposed-beacon-chainmd-change)
+  - [4. Add `fork.md`](#4-add-forkmd)
+  - [5. Make it executable](#5-make-it-executable)
+- [B: Make it executable for pytest and test generator](#b-make-it-executable-for-pytest-and-test-generator)
+  - [1. Add `light-client/*` docs if you updated the content of `BeaconBlock`](#1-add-light-client-docs-if-you-updated-the-content-of-beaconblock)
+  - [2. Add the mainnet and minimal presets and update the configs](#2-add-the-mainnet-and-minimal-presets-and-update-the-configs)
+  - [3. Update `context.py`](#3-update-contextpy)
+  - [4. Update `constants.py`](#4-update-constantspy)
+  - [5. Update `genesis.py`:](#5-update-genesispy)
+  - [6. To add fork transition tests, update fork_transition.py](#6-to-add-fork-transition-tests-update-fork_transitionpy)
+  - [7. Update CI configurations](#7-update-ci-configurations)
+- [Others](#others)
+  - [Bonus](#bonus)
+  - [Need help?](#need-help)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+
+## A. Make it executable for linter checks
+
+### 1. Create a folder under `./specs/_features`
+
+For example, if it's an `EIP-9999` CL spec, you can create a `./specs/_features/eip9999` folder.
+
+### 2. Choose the "previous fork" to extend: usually, use the scheduled or the latest mainnet fork version.
+
+For example, if the latest fork is Capella, use `./specs/capella` content as your "previous fork".
+
+### 3. Write down your proposed `beacon-chain.md` change
+- You can either use [Beacon Chain Spec Template](./templates/beacon-chain-template.md), or make a copy of the latest fork content and then edit it.
+- Tips:
+    - We use [`doctoc`](https://www.npmjs.com/package/doctoc) tool to generate the table of content.
+        ```
+        cd consensus-specs
+        doctoc specs
+        ```
+    - The differences between "Constants", "Configurations", and "Presets":
+        - Constants: The constant that should never be changed.
+        - Configurations: The settings that we may change for different networks.
+        - Presets: The settings that we may change for testing.
+    - Readability and simplicity are more important than efficiency and optimization.
+        - Use simple Python rather than the fancy Python dark magic.
+
+### 4. Add `fork.md`
+You can refer to the previous fork's `fork.md` file.
+### 5. Make it executable
+- Update [`constants.py`](https://github.com/ethereum/consensus-specs/blob/dev/tests/core/pyspec/eth2spec/test/helpers/constants.py) with the new feature name.
+- Update [`setup.py`](https://github.com/ethereum/consensus-specs/blob/dev/setup.py):
+    - Add a new `SpecBuilder` with the new feature name constant. e.g., `EIP9999SpecBuilder`
+    - Add the new `SpecBuilder` to `spec_builders` list.
+    - Add the path of the new markdown files in `finalize_options` function.
+
+## B: Make it executable for pytest and test generator
+
+### 1. Add `light-client/*` docs if you updated the content of `BeaconBlock`
+- You can refer to the previous fork's `light-client/*` file.
+- Add the path of the new markdown files in `setup.py`'s `finalize_options` function.
+
+### 2. Add the mainnet and minimal presets and update the configs
+- Add presets: `presets/mainnet/<new-feature-name>.yaml` and `presets/minimal/<new-feature-name>.yaml`
+- Update configs: `configs/mainnet.yaml` and `configs/minimal.yaml`
+
+### 3. Update [`context.py`](https://github.com/ethereum/consensus-specs/blob/dev/tests/core/pyspec/eth2spec/test/context.py)
+- Update `spec_targets` by adding `<NEW_FEATURE>`
+
+```python
+from eth2spec.eip9999 import mainnet as spec_eip9999_mainnet, minimal as spec_eip9999_minimal
+
+...
+
+spec_targets: Dict[PresetBaseName, Dict[SpecForkName, Spec]] = {
+    MINIMAL: {
+        ...
+        EIP9999: spec_eip9999_minimal,
+    },
+    MAINNET: {
+        ...
+        EIP9999: spec_eip9999_mainnet
+    },
+}
+```
+
+### 4. Update [`constants.py`](https://github.com/ethereum/consensus-specs/blob/dev/tests/core/pyspec/eth2spec/test/helpers/constants.py)
+- Add `<NEW_FEATURE>` to `ALL_PHASES` and `TESTGEN_FORKS`
+
+### 5. Update [`genesis.py`](https://github.com/ethereum/consensus-specs/blob/dev/tests/core/pyspec/eth2spec/test/helpers/genesis.py):
+
+We use `create_genesis_state` to create the default `state` in tests.
+
+- Update `create_genesis_state` by adding `fork_version` setting:
+
+```python
+def create_genesis_state(spec, validator_balances, activation_threshold):
+    ...
+    if spec.fork == ALTAIR:
+        current_version = spec.config.ALTAIR_FORK_VERSION
+    ...
+    elif spec.fork == EIP9999:
+        # Add the previous fork version of given fork
+        previous_version = spec.config.<PREVIOUS_FORK_VERSION>
+        current_version = spec.config.EIP9999_FORK_VERSION
+```
+
+- If the given feature changes `BeaconState` fields, you have to set the initial values by adding:
+
+```python
+def create_genesis_state(spec, validator_balances, activation_threshold):
+    ...
+    if is_post_eip9999(spec):
+        state.<NEW_FIELD> = <value>
+
+    return state
+```
+
+- If the given feature changes `ExecutionPayload` fields, you have to set the initial values by updating `get_sample_genesis_execution_payload_header` helper.
+
+### 6. To add fork transition tests, update [fork_transition.py](https://github.com/ethereum/consensus-specs/blob/dev/tests/core/pyspec/eth2spec/test/helpers/fork_transition.py)
+
+```python
+def do_fork(state, spec, post_spec, fork_epoch, with_block=True, sync_aggregate=None, operation_dict=None):
+    ...
+
+    if post_spec.fork == ALTAIR:
+        state = post_spec.upgrade_to_altair(state)
+    ...
+    elif post_spec.fork == EIP9999:
+        state = post_spec.upgrade_to_eip9999(state)
+
+    ...
+
+    if post_spec.fork == ALTAIR:
+        assert state.fork.previous_version == post_spec.config.GENESIS_FORK_VERSION
+        assert state.fork.current_version == post_spec.config.ALTAIR_FORK_VERSION
+    ...
+    elif post_spec.fork == EIP9999:
+        assert state.fork.previous_version == post_spec.config.<PREVIOUS_FORK_VERSION>
+        assert state.fork.current_version == post_spec.config.EIP9999_FORK_VERSION
+
+    ...
+```
+
+### 7. Update CI configurations
+- Update [GitHub Actions config](https://github.com/ethereum/consensus-specs/blob/dev/.github/workflows/run-tests.yml)
+    - Update `pyspec-tests.strategy.matrix.version` list by adding new feature to it
+- Update [CircleCI config](https://github.com/ethereum/consensus-specs/blob/dev/.circleci/config.yml)
+    - Add new job to the `workflows.test_spec.jobs`
+
+## Others
+
+### Bonus
+- Add `validator.md` if honest validator behavior changes with the new feature.
+
+### Need help?
+You can tag spec elves for cleaning up your PR. 🧚

docs/docs/templates/beacon-chain-template.md

@@ -0,0 +1,84 @@
+# `beacon-chain.md` Template
+
+# <FORK_NAME> -- The Beacon Chain
+
+## Table of contents
+<!-- TOC -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- /TOC -->
+
+
+
+## Introduction
+
+## Notation
+
+## Custom types
+
+## Constants
+
+### [CATEGORY OF CONSTANTS]
+
+| Name | Value |
+| - | - |
+| `<CONSTANT_NAME>` | `<VALUE>`` |
+
+## Preset
+
+
+### [CATEGORY OF PRESETS]
+
+| Name | Value |
+| - | - |
+| `<PRESET_FIELD_NAME>` | `<VALUE>` |
+
+## Configuration
+
+### [CATEGORY OF CONFIGURATIONS]
+
+| Name | Value |
+| - | - |
+| `<CONFIGURATION_FIELD_NAME>` | `<VALUE>` |
+
+## Containers
+
+### [CATEGORY OF CONTAINERS]
+
+#### `CONTAINER_NAME`
+
+```python
+class CONTAINER_NAME(Container):
+    FILED_NAME: SSZ_TYPE
+```
+
+## Helper functions
+
+### [CATEGORY OF HELPERS]
+
+```python
+<PYTHON HELPER FUNCTION>
+```
+
+### Epoch processing
+
+
+### Block processing
+
+    
+
+    
+## Testing
+
+*Note*: The function `initialize_beacon_state_from_eth1` is modified for pure <FORK_NAME> testing only.
+
+```python
+def initialize_beacon_state_from_eth1(eth1_block_hash: Hash32,
+                                      eth1_timestamp: uint64,
+                                      deposits: Sequence[Deposit],
+                                      execution_payload_header: ExecutionPayloadHeader=ExecutionPayloadHeader()
+                                      ) -> BeaconState:
+    ...
+```

docs/light-client/.pages

@@ -0,0 +1,5 @@
+nav:
+    - 'Index': index.md
+    - 'Altair': specs/altair/light-client/sync-protocol
+    - 'Capella': specs/capella/light-client/sync-protocol
+    - 'Deneb': specs/deneb/light-client/sync-protocol

docs/light-client/index.md

@@ -0,0 +1 @@
+# Light client specifications

docs/stylesheets/extra.css

@@ -0,0 +1,34 @@
+/* Reference: https://zenn.dev/mebiusbox/articles/81d977a72cee01 */
+
+[data-md-color-scheme=default] {
+  --md-default-fg-color--light: #222 !important;
+}
+[data-md-color-scheme=slate] {
+  --md-default-fg-color--light: #fefefe !important;
+  --md-typeset-a-color: #fc0 !important;
+}
+
+.md-typeset pre {
+    color: #f8f8f2;
+}
+.md-typeset .highlighttable {
+    margin-left:-20px;
+    margin-right: -20px;
+    border-radius: 0;
+}
+.md-typeset .highlighttable > * {
+    --md-code-bg-color: #222 !important;
+    --md-code-fg-color: #fefefe !important;
+}
+.md-typeset .highlighttable .linenos .linenodiv pre span {
+    background-color: #222 !important;
+    color: #fefefe !important;
+}
+.md-typeset .highlighttable .md-clipboard:before,
+.md-typeset .highlighttable .md-clipboard:after {
+    color: rgba(240,240,240,.8);
+}
+.md-typeset .highlighttable .md-clipboard:hover:before,
+.md-typeset .highlighttable .md-clipboard:hover:after {
+    color: rgba(102,217,224,1);
+}

fork_choice/.pages

@@ -0,0 +1,7 @@
+nav:
+    - ...
+    - Fork Choice -- Core:
+        - phase0: specs/phase0/fork-choice
+        - bellatrix: specs/bellatrix/fork-choice
+        - capella: specs/capella/fork-choice
+        - deneb: specs/deneb/fork-choice

fork_choice/safe-block.md

@@ -15,7 +15,7 @@
 ## Introduction
 
 Under honest majority and certain network synchronicity assumptions
-there exist a block that is safe from re-orgs. Normally this block is
+there exists a block that is safe from re-orgs. Normally this block is
 pretty close to the head of canonical chain which makes it valuable
 to expose a safe block to users.
 

mkdocs.yml

@@ -0,0 +1,40 @@
+site_name: Ethereum Consensus Specs
+site_url: https://ethereum.github.io/consensus-specs/
+repo_name: ethereum/consensus-specs
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: black
+      toggle:
+        icon: material/brightness-7 
+        name: Switch to dark mode
+    - scheme: slate
+      primary: black
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - search
+markdown_extensions:
+  - toc:
+      permalink: true
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      use_pygments: true
+      noclasses: true
+      pygments_style: monokai
+      linenums: true
+      anchor_linenums: true
+  - mdx_truly_sane_lists:
+      nested_indent: 4
+plugins:
+  - search
+  - awesome-pages
+extra_css:
+  - stylesheets/extra.css
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/ethereum/consensus-specs

setup.py

@@ -1181,6 +1181,7 @@ setup(
         "test": ["pytest>=4.4", "pytest-cov", "pytest-xdist"],
         "lint": ["flake8==5.0.4", "mypy==0.981", "pylint==2.15.3"],
         "generator": ["python-snappy==0.6.1", "filelock"],
+        "docs": ["mkdocs==1.4.2", "mkdocs-material==9.1.5", "mdx-truly-sane-lists==1.3",  "mkdocs-awesome-pages-plugin==2.8.0"]
     },
     install_requires=[
         "eth-utils>=2.0.0,<3",

specs/.pages

@@ -0,0 +1,4 @@
+nav:
+    - phase0
+    - ...
+    - _features

specs/_features/eip6110/beacon-chain.md

@@ -33,7 +33,7 @@
 This is the beacon chain specification of in-protocol deposits processing mechanism.
 This mechanism relies on the changes proposed by [EIP-6110](http://eips.ethereum.org/EIPS/eip-6110).
 
-*Note:* This specification is built upon [Capella](../../capella/beacon_chain.md) and is under active development.
+*Note:* This specification is built upon [Capella](../../capella/beacon-chain.md) and is under active development.
 
 ## Constants
 

specs/_features/sharding/p2p-interface.md

@@ -47,7 +47,7 @@ Following the same scheme as the [Phase0 gossip topics](../../phase0/p2p-interfa
 | `shard_column_{subnet_id}`      | `SignedShardSample`      |
 | `builder_block_bid`             | `BuilderBlockBid`        |
 
-The [DAS network specification](./das-p2p.md) defines additional topics.
+The [DAS network specification](../das/das-core.md) defines additional topics.
 
 #### Builder block bid
 

specs/deneb/beacon-chain.md

@@ -59,7 +59,7 @@ This upgrade adds blobs to the beacon chain as part of Deneb. This is an extensi
 
 | Name | Value |
 | - | - |
-| `BLOB_TX_TYPE` | `uint8(0x05)` |
+| `BLOB_TX_TYPE` | `uint8(0x03)` |
 | `VERSIONED_HASH_VERSION_KZG` | `Bytes1('0x01')` |
 
 ## Preset

specs/deneb/light-client/sync-protocol.md

@@ -18,7 +18,7 @@
 
 ## Introduction
 
-This upgrade updates light client data to include the Denbeb changes to the [`ExecutionPayload`](../beacon-chain.md) structure. It extends the [Capella Light Client specifications](../../capella/light-client/sync-protocol.md). The [fork document](./fork.md) explains how to upgrade existing Capella based deployments to Deneb.
+This upgrade updates light client data to include the Deneb changes to the [`ExecutionPayload`](../beacon-chain.md) structure. It extends the [Capella Light Client specifications](../../capella/light-client/sync-protocol.md). The [fork document](./fork.md) explains how to upgrade existing Capella based deployments to Deneb.
 
 Additional documents describes the impact of the upgrade on certain roles:
 - [Full node](./full-node.md)

specs/deneb/p2p-interface.md

@@ -16,7 +16,7 @@ The specification of these changes continues in the same format as the network s
   - [`SignedBlobSidecar`](#signedblobsidecar)
   - [`BlobIdentifier`](#blobidentifier)
   - [Helpers](#helpers)
-    - [`verify_sidecar_signature`](#verify_sidecar_signature)
+    - [`verify_blob_sidecar_signature`](#verify_blob_sidecar_signature)
 - [The gossip domain: gossipsub](#the-gossip-domain-gossipsub)
   - [Topics and messages](#topics-and-messages)
     - [Global topics](#global-topics)
@@ -77,7 +77,7 @@ class BlobIdentifier(Container):
 
 ### Helpers
 
-#### `verify_sidecar_signature`
+#### `verify_blob_sidecar_signature`
 
 ```python
 def verify_blob_sidecar_signature(state: BeaconState, signed_blob_sidecar: SignedBlobSidecar) -> bool:
@@ -118,7 +118,7 @@ The *type* of the payload of this topic changes to the (modified) `SignedBeaconB
 
 This topic is used to propagate signed blob sidecars, one for each sidecar index. The number of indices is defined by `MAX_BLOBS_PER_BLOCK`.
 
-The following validations MUST pass before forwarding the `sidecar` on the network, assuming the alias `sidecar = signed_blob_sidecar.message`:
+The following validations MUST pass before forwarding the `signed_blob_sidecar` on the network, assuming the alias `sidecar = signed_blob_sidecar.message`:
 
 - _[REJECT]_ The sidecar is for the correct topic -- i.e. `sidecar.index` matches the topic `{index}`.
 - _[IGNORE]_ The sidecar is not from a future slot (with a `MAXIMUM_GOSSIP_CLOCK_DISPARITY` allowance) -- i.e. validate that `sidecar.slot <= current_slot` (a client MAY queue future sidecars for processing at the appropriate slot).
@@ -126,7 +126,7 @@ The following validations MUST pass before forwarding the `sidecar` on the netwo
 - _[IGNORE]_ The sidecar's block's parent (defined by `sidecar.block_parent_root`) has been seen (via both gossip and non-gossip sources) (a client MAY queue sidecars for processing once the parent block is retrieved).
 - _[REJECT]_ The sidecar's block's parent (defined by `sidecar.block_parent_root`) passes validation.
 - _[REJECT]_ The sidecar is from a higher slot than the sidecar's block's parent (defined by `sidecar.block_parent_root`).
-- _[REJECT]_ The proposer signature, `signed_blob_sidecar.signature`, is valid as verified by `verify_sidecar_signature`.
+- _[REJECT]_ The proposer signature, `signed_blob_sidecar.signature`, is valid as verified by `verify_blob_sidecar_signature`.
 - _[IGNORE]_ The sidecar is the only sidecar with valid signature received for the tuple `(sidecar.block_root, sidecar.index)`.
 - _[REJECT]_ The sidecar is proposed by the expected `proposer_index` for the block's slot in the context of the current shuffling (defined by `block_parent_root`/`slot`).
   If the `proposer_index` cannot immediately be verified against the expected shuffling, the sidecar MAY be queued for later processing while proposers for the block's branch are calculated -- in such a case _do not_ `REJECT`, instead `IGNORE` this message.

specs/phase0/beacon-chain.md

@@ -269,7 +269,7 @@ Additional preset configurations can be found in the [`configs`](../../configs)
 
 - The `INACTIVITY_PENALTY_QUOTIENT` equals `INVERSE_SQRT_E_DROP_TIME**2` where `INVERSE_SQRT_E_DROP_TIME := 2**13` epochs (about 36 days) is the time it takes the inactivity penalty to reduce the balance of non-participating validators to about `1/sqrt(e) ~= 60.6%`. Indeed, the balance retained by offline validators after `n` epochs is about `(1 - 1/INACTIVITY_PENALTY_QUOTIENT)**(n**2/2)`; so after `INVERSE_SQRT_E_DROP_TIME` epochs, it is roughly `(1 - 1/INACTIVITY_PENALTY_QUOTIENT)**(INACTIVITY_PENALTY_QUOTIENT/2) ~= 1/sqrt(e)`. Note this value will be upgraded to `2**24` after Phase 0 mainnet stabilizes to provide a faster recovery in the event of an inactivity leak.
 
-- The `PROPORTIONAL_SLASHING_MULTIPLIER` is set to `1` at initial mainnet launch, resulting in one-third of the minimum accountable safety margin in the event of a finality attack. After Phase 0 mainnet stablizes, this value will be upgraded to `3` to provide the maximal minimum accountable safety margin.
+- The `PROPORTIONAL_SLASHING_MULTIPLIER` is set to `1` at initial mainnet launch, resulting in one-third of the minimum accountable safety margin in the event of a finality attack. After Phase 0 mainnet stabilizes, this value will be upgraded to `3` to provide the maximal minimum accountable safety margin.
 
 ### Max operations per block
 

specs/phase0/validator.md

@@ -162,7 +162,7 @@ The `withdrawal_credentials` field must be such that:
 * `withdrawal_credentials[1:12] == b'\x00' * 11`
 * `withdrawal_credentials[12:] == eth1_withdrawal_address`
 
-After the merge of the current Ethereum application layer into the Beacon Chain,
+After the merge of the current Ethereum execution layer into the Beacon Chain,
 withdrawals to `eth1_withdrawal_address` will simply be increases to the account's ETH balance that do **NOT** trigger any EVM execution.
 
 ### Submit deposit

sync/optimistic.md

@@ -375,7 +375,7 @@ Given all of this, we can say two things:
    justify an honest chain.
 2. **BNs which are syncing can optimistically import transition blocks.** In
    this case a justified chain already exists blocks. The poison block would be
-   quickly reverted and would have no affect on liveness.
+   quickly reverted and would have no effect on liveness.
 
 Astute readers will notice that (2) contains a glaring assumption about network
 liveness. This is necessary because a node cannot feasibly ascertain that the
@@ -408,13 +408,13 @@ Such a scenario requires manual intervention.
 
 An alternative to optimistic sync is to run a light client inside/alongside
 beacon nodes that mitigates the need for optimistic sync by providing
-tip-of-chain blocks to the execution engine. However, light clients comes with
+tip-of-chain blocks to the execution engine. However, light clients come with
 their own set of complexities. Relying on light clients may also restrict nodes
 from syncing from genesis, if they so desire.
 
 A notable thing about optimistic sync is that it's *optional*. Should an
 implementation decide to go the light-client route, then they can just ignore
-optimistic sync all together.
+optimistic sync altogether.
 
 ### What if `TERMINAL_BLOCK_HASH` is used?
 

tests/core/pyspec/eth2spec/VERSION.txt

@@ -1 +1 @@
-1.3.0-rc.5
+1.3.0