Danny Ryan
GitHub
commit
01b53691dc
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
25
Makefile
25
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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Ethereum Proof-of-Stake Consensus Specifications
|
||||
|
||||
[](https://discord.gg/qGpsxSA) [](https://gitter.im/ethereum/sharding?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
||||
[](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).
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
nav:
|
||||
- Home:
|
||||
- README.md
|
||||
- specs
|
||||
- ...
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
# Ethereum Proof-of-Stake Consensus Specifications
|
||||
|
||||
[](https://discord.gg/qGpsxSA) [](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
|
||||
|
||||
[](https://github.com/ethereum/eth2.0-specs/releases/) [](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).
|
||||
|
|
@ -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. 🧚
|
||||
|
|
@ -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:
|
||||
...
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
@ -0,0 +1 @@
|
|||
# Light client specifications
|
||||
|
|
@ -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);
|
||||
}
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
1
setup.py
1
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",
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
nav:
|
||||
- phase0
|
||||
- ...
|
||||
- _features
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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])))
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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?
|
||||
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
1.3.0-rc.5
|
||||
1.3.0
|
||||
|
|
|
|||
Loading…
Reference in New Issue