diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..eab3bba17 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index c56a658ce..82026c27b 100644 --- a/.gitignore +++ b/.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 diff --git a/Makefile b/Makefile index 1ec399e3a..ab5521663 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index 9f2528263..28d61ad40 100644 --- a/README.md +++ b/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). diff --git a/docs/.pages b/docs/.pages new file mode 100644 index 000000000..d9e382ede --- /dev/null +++ b/docs/.pages @@ -0,0 +1,5 @@ +nav: + - Home: + - README.md + - specs + - ... diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..9f2528263 --- /dev/null +++ b/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` | | +| 1 | **Altair** | `74240` | | +| 2 | **Bellatrix**
(["The Merge"](https://ethereum.org/en/upgrades/merge/)) | `144896` | | +| 3 | **Capella** | `194048` | | + +### In-development Specifications +| Code Name or Topic | Specs | Notes | +| - | - | - | +| Deneb (tentative) | | +| Sharding (outdated) | | +| Custody Game (outdated) | | Dependent on sharding | +| Data Availability Sampling (outdated) | | | +| EIP-6110 | | + +### 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). diff --git a/docs/docs/new-feature.md b/docs/docs/new-feature.md new file mode 100644 index 000000000..5e6180329 --- /dev/null +++ b/docs/docs/new-feature.md @@ -0,0 +1,163 @@ +# How to add a new feature proposal in consensus-specs + + + +## 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) + + + + +## 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/.yaml` and `presets/minimal/.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 `` + +```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 `` 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. + 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. = + + 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. + 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. 🧚 diff --git a/docs/docs/templates/beacon-chain-template.md b/docs/docs/templates/beacon-chain-template.md new file mode 100644 index 000000000..4d22d3908 --- /dev/null +++ b/docs/docs/templates/beacon-chain-template.md @@ -0,0 +1,84 @@ +# `beacon-chain.md` Template + +# -- The Beacon Chain + +## Table of contents + + + + + + + + + +## Introduction + +## Notation + +## Custom types + +## Constants + +### [CATEGORY OF CONSTANTS] + +| Name | Value | +| - | - | +| `` | ``` | + +## Preset + + +### [CATEGORY OF PRESETS] + +| Name | Value | +| - | - | +| `` | `` | + +## Configuration + +### [CATEGORY OF CONFIGURATIONS] + +| Name | Value | +| - | - | +| `` | `` | + +## Containers + +### [CATEGORY OF CONTAINERS] + +#### `CONTAINER_NAME` + +```python +class CONTAINER_NAME(Container): + FILED_NAME: SSZ_TYPE +``` + +## Helper functions + +### [CATEGORY OF HELPERS] + +```python + +``` + +### Epoch processing + + +### Block processing + + + + +## Testing + +*Note*: The function `initialize_beacon_state_from_eth1` is modified for pure 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: + ... +``` diff --git a/docs/light-client/.pages b/docs/light-client/.pages new file mode 100644 index 000000000..a372a5d2e --- /dev/null +++ b/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 diff --git a/docs/light-client/index.md b/docs/light-client/index.md new file mode 100644 index 000000000..32155b185 --- /dev/null +++ b/docs/light-client/index.md @@ -0,0 +1 @@ +# Light client specifications diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 000000000..384976248 --- /dev/null +++ b/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); +} diff --git a/fork_choice/.pages b/fork_choice/.pages new file mode 100644 index 000000000..a5e6ccc90 --- /dev/null +++ b/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 diff --git a/fork_choice/safe-block.md b/fork_choice/safe-block.md index 490d24538..b76285b3a 100644 --- a/fork_choice/safe-block.md +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..dc6b352ba --- /dev/null +++ b/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 diff --git a/setup.py b/setup.py index 52bad2b71..fc3acb806 100644 --- a/setup.py +++ b/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", diff --git a/specs/.pages b/specs/.pages new file mode 100644 index 000000000..7e47dc5f7 --- /dev/null +++ b/specs/.pages @@ -0,0 +1,4 @@ +nav: + - phase0 + - ... + - _features diff --git a/specs/_features/eip6110/beacon-chain.md b/specs/_features/eip6110/beacon-chain.md index 70a72a5f4..01999a929 100644 --- a/specs/_features/eip6110/beacon-chain.md +++ b/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 diff --git a/specs/_features/sharding/p2p-interface.md b/specs/_features/sharding/p2p-interface.md index c29146fe9..553444eff 100644 --- a/specs/_features/sharding/p2p-interface.md +++ b/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 diff --git a/specs/deneb/beacon-chain.md b/specs/deneb/beacon-chain.md index a0ac783b7..df1da8e2a 100644 --- a/specs/deneb/beacon-chain.md +++ b/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 diff --git a/specs/deneb/light-client/sync-protocol.md b/specs/deneb/light-client/sync-protocol.md index 6f948257b..c691a113d 100644 --- a/specs/deneb/light-client/sync-protocol.md +++ b/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) diff --git a/specs/deneb/p2p-interface.md b/specs/deneb/p2p-interface.md index 9be028620..0b6381e20 100644 --- a/specs/deneb/p2p-interface.md +++ b/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. diff --git a/specs/phase0/beacon-chain.md b/specs/phase0/beacon-chain.md index 3794cd6be..b77e017ab 100644 --- a/specs/phase0/beacon-chain.md +++ b/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 @@ -1036,7 +1036,7 @@ def get_total_balance(state: BeaconState, indices: Set[ValidatorIndex]) -> Gwei: """ Return the combined effective balance of the ``indices``. ``EFFECTIVE_BALANCE_INCREMENT`` Gwei minimum to avoid divisions by zero. - Math safe up to ~10B ETH, afterwhich this overflows uint64. + Math safe up to ~10B ETH, after which this overflows uint64. """ return Gwei(max(EFFECTIVE_BALANCE_INCREMENT, sum([state.validators[index].effective_balance for index in indices]))) ``` diff --git a/specs/phase0/validator.md b/specs/phase0/validator.md index 54b344791..2a4d5b920 100644 --- a/specs/phase0/validator.md +++ b/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 diff --git a/sync/optimistic.md b/sync/optimistic.md index 79a5271c2..14eb99fb1 100644 --- a/sync/optimistic.md +++ b/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? diff --git a/tests/core/pyspec/eth2spec/VERSION.txt b/tests/core/pyspec/eth2spec/VERSION.txt index d4f06976f..f0bb29e76 100644 --- a/tests/core/pyspec/eth2spec/VERSION.txt +++ b/tests/core/pyspec/eth2spec/VERSION.txt @@ -1 +1 @@ -1.3.0-rc.5 +1.3.0