diff --git a/.gitignore b/.gitignore index 788410645..76fe21ddd 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,7 @@ build/ output/ dist/ -eth2.0-spec-tests/ +consensus-spec-tests/ .pytest_cache .mypy_cache diff --git a/Makefile b/Makefile index d637d26cf..9f32b4568 100644 --- a/Makefile +++ b/Makefile @@ -6,7 +6,7 @@ TEST_GENERATORS_DIR = ./tests/generators PY_SPEC_DIR = $(TEST_LIBS_DIR)/pyspec ETH2SPEC_MODULE_DIR = $(PY_SPEC_DIR)/eth2spec TEST_REPORT_DIR = $(PY_SPEC_DIR)/test-reports -TEST_VECTOR_DIR = ../eth2.0-spec-tests/tests +TEST_VECTOR_DIR = ../consensus-spec-tests/tests GENERATOR_DIR = ./tests/generators SOLIDITY_DEPOSIT_CONTRACT_DIR = ./solidity_deposit_contract SOLIDITY_DEPOSIT_CONTRACT_SOURCE = ${SOLIDITY_DEPOSIT_CONTRACT_DIR}/deposit_contract.sol diff --git a/README.md b/README.md index f5ac598b6..bc4ba100b 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,17 @@ -# Ethereum 2.0 Specifications +# 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 sharding and Ethereum 2.0 (Serenity), see the [sharding FAQ](https://eth.wiki/sharding/Sharding-FAQs) and the [research compendium](https://notes.ethereum.org/s/H1PGqDhpm). +To learn more about proof-of-stake and sharding, see the [PoS FAQ](https://eth.wiki/en/concepts/proof-of-stake-faqs), [sharding FAQ](https://eth.wiki/sharding/Sharding-FAQs) and the [research compendium](https://notes.ethereum.org/s/H1PGqDhpm). -This repository hosts the current Eth2 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. +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 Eth2 clients can be found in [specs](specs/). These are divided into features. +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. The current features are: @@ -73,13 +73,12 @@ Sharding follows the merge, and is divided into three parts: Additional specifications and standards outside of requisite client functionality can be found in the following repos: -* [Eth2 APIs](https://github.com/ethereum/eth2.0-apis) -* [Eth2 Metrics](https://github.com/ethereum/eth2.0-metrics/) -* [Interop Standards in Eth2 PM](https://github.com/ethereum/eth2.0-pm/tree/master/interop) +* [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 Ethereum 2.0: +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 @@ -97,3 +96,7 @@ The following are the broad design goals for Ethereum 2.0: 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/specs/altair/beacon-chain.md b/specs/altair/beacon-chain.md index 7c4d20fe5..dbd3e6368 100644 --- a/specs/altair/beacon-chain.md +++ b/specs/altair/beacon-chain.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Altair Beacon chain changes +# Altair -- The Beacon Chain ## Table of contents diff --git a/specs/altair/bls.md b/specs/altair/bls.md index 06b0313a9..8492e95c3 100644 --- a/specs/altair/bls.md +++ b/specs/altair/bls.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Altair BLS extensions +# Altair -- BLS extensions ## Table of contents diff --git a/specs/altair/fork.md b/specs/altair/fork.md index f7aa89c42..f80064a83 100644 --- a/specs/altair/fork.md +++ b/specs/altair/fork.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Altair fork +# Altair -- Fork Logic **Notice**: This document is a work-in-progress for researchers and implementers. @@ -17,7 +17,7 @@ ## Introduction -This document describes the process of the first upgrade of Ethereum 2.0: the Altair hard fork, introducing light client support and other improvements. +This document describes the process of the first upgrade of the beacon chain: the Altair hard fork, introducing light client support and other improvements. ## Configuration diff --git a/specs/altair/p2p-interface.md b/specs/altair/p2p-interface.md index 6820fd10a..f2700b311 100644 --- a/specs/altair/p2p-interface.md +++ b/specs/altair/p2p-interface.md @@ -1,6 +1,6 @@ -# Ethereum Altair networking specification +# Altair -- Networking -This document contains the networking specification for Ethereum 2.0 clients added during the Altair deployment. +This document contains the networking specification for Altair. This document should be viewed as additive to the [document from Phase 0](../phase0/p2p-interface.md) and will be referred to as the "Phase 0 document" hereafter. Readers should understand the Phase 0 document and use it as a basis to understand the changes outlined in this document. diff --git a/specs/altair/sync-protocol.md b/specs/altair/sync-protocol.md index 119d0f998..24c35f891 100644 --- a/specs/altair/sync-protocol.md +++ b/specs/altair/sync-protocol.md @@ -1,4 +1,4 @@ -# Minimal Light Client +# Altair -- Minimal Light Client **Notice**: This document is a work-in-progress for researchers and implementers. @@ -28,8 +28,8 @@ ## Introduction -Eth2 is designed to be light client friendly for constrained environments to -access Eth2 with reasonable safety and liveness. +The beacon chain is designed to be light client friendly for constrained environments to +access Ethereum with reasonable safety and liveness. Such environments include resource-constrained devices (e.g. phones for trust-minimised wallets) and metered VMs (e.g. blockchain VMs for cross-chain bridges). @@ -184,7 +184,7 @@ def process_light_client_update(store: LightClientStore, update: LightClientUpda ): # Apply update if (1) 2/3 quorum is reached and (2) we have a finality proof. # Note that (2) means that the current light client design needs finality. - # It may be changed to re-organizable light client design. See the on-going issue eth2.0-specs#2182. + # It may be changed to re-organizable light client design. See the on-going issue consensus-specs#2182. apply_light_client_update(store.snapshot, update) store.valid_updates = set() elif current_slot > store.snapshot.header.slot + update_timeout: diff --git a/specs/altair/validator.md b/specs/altair/validator.md index badef2de5..461c9a70d 100644 --- a/specs/altair/validator.md +++ b/specs/altair/validator.md @@ -1,6 +1,6 @@ -# Ethereum 2.0 Altair -- Honest Validator +# Altair -- Honest Validator -This is an accompanying document to [Ethereum 2.0 Altair -- The Beacon Chain](./beacon-chain.md), which describes the expected actions of a "validator" participating in the Ethereum 2.0 protocol. +This is an accompanying document to [Altair -- The Beacon Chain](./beacon-chain.md), which describes the expected actions of a "validator" participating in the Ethereum proof-of-stake protocol. ## Table of contents @@ -49,8 +49,8 @@ This is an accompanying document to [Ethereum 2.0 Altair -- The Beacon Chain](./ ## Introduction -This document represents the expected behavior of an "honest validator" with respect to the Altair upgrade of the Ethereum 2.0 protocol. -It builds on the [previous document for the behavior of an "honest validator" from Phase 0](../phase0/validator.md) of the Ethereum 2.0 protocol. +This document represents the expected behavior of an "honest validator" with respect to the Altair upgrade of the Ethereum proof-of-stake protocol. +It builds on the [previous document for the behavior of an "honest validator" from Phase 0](../phase0/validator.md) of the Ethereum proof-of-stake protocol. This previous document is referred to below as the "Phase 0 document". Altair introduces a new type of committee: the sync committee. Sync committees are responsible for signing each block of the canonical chain and there exists an efficient algorithm for light clients to sync the chain using the output of the sync committees. diff --git a/specs/custody_game/beacon-chain.md b/specs/custody_game/beacon-chain.md index ad99527f7..6f9f61cf9 100644 --- a/specs/custody_game/beacon-chain.md +++ b/specs/custody_game/beacon-chain.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Custody Game -- Beacon Chain +# Custody Game -- The Beacon Chain **Notice**: This document is a work-in-progress for researchers and implementers. @@ -57,7 +57,7 @@ ## Introduction -This document details the beacon chain additions and changes of Ethereum 2.0 to support the shard data custody game, +This document details the beacon chain additions and changes of to support the shard data custody game, building upon the [Sharding](../sharding/beacon-chain.md) specification. ## Constants diff --git a/specs/custody_game/validator.md b/specs/custody_game/validator.md index a495924c9..05ceb854d 100644 --- a/specs/custody_game/validator.md +++ b/specs/custody_game/validator.md @@ -1,8 +1,8 @@ -# Ethereum 2.0 Custody Game -- Honest Validator +# Custody Game -- Honest Validator **Notice**: This document is a work-in-progress for researchers and implementers. -This is an accompanying document to the [Ethereum 2.0 Custody Game](./), which describes the expected actions of a "validator" -participating in the Ethereum 2.0 Custody Game. +This is an accompanying document to the [Custody Game](./), which describes the expected actions of a "validator" +participating in the shard data Custody Game. ## Table of contents diff --git a/specs/das/das-core.md b/specs/das/das-core.md index ce39565a1..f683cbbe1 100644 --- a/specs/das/das-core.md +++ b/specs/das/das-core.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Data Availability Sampling -- Core +# Data Availability Sampling -- Core **Notice**: This document is a work-in-progress for researchers and implementers. diff --git a/specs/das/fork-choice.md b/specs/das/fork-choice.md index ec9f3ab59..f8ee68eab 100644 --- a/specs/das/fork-choice.md +++ b/specs/das/fork-choice.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Data Availability Sampling -- Fork Choice +# Data Availability Sampling -- Fork Choice **Notice**: This document is a work-in-progress for researchers and implementers. @@ -17,7 +17,7 @@ ## Introduction -This document is the beacon chain fork choice spec for Ethereum 2.0 Data Availability Sampling. The only change that we add from phase 0 is that we add a concept of "data dependencies"; +This document is the beacon chain fork choice spec for Data Availability Sampling. The only change that we add from phase 0 is that we add a concept of "data dependencies"; a block is only eligible for consideration in the fork choice after a data availability test has been successfully completed for all dependencies. The "root" of a shard block for data dependency purposes is considered to be a `DataCommitment` object, which is a pair of a Kate commitment and a length. diff --git a/specs/das/p2p-interface.md b/specs/das/p2p-interface.md index fcc7616da..b4a0a9d2c 100644 --- a/specs/das/p2p-interface.md +++ b/specs/das/p2p-interface.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Data Availability Sampling -- Network specification +# Data Availability Sampling -- Networking **Notice**: This document is a work-in-progress for researchers and implementers. diff --git a/specs/das/sampling.md b/specs/das/sampling.md index aedcf5fd5..53685c650 100644 --- a/specs/das/sampling.md +++ b/specs/das/sampling.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Data Availability Sampling +# Data Availability Sampling -- Sampling **Notice**: This document is a work-in-progress for researchers and implementers. diff --git a/specs/merge/beacon-chain.md b/specs/merge/beacon-chain.md index 5defa6bcb..ed12d3eb6 100644 --- a/specs/merge/beacon-chain.md +++ b/specs/merge/beacon-chain.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 The Merge +# The Merge -- The Beacon Chain **Notice**: This document is a work-in-progress for researchers and implementers. diff --git a/specs/merge/fork-choice.md b/specs/merge/fork-choice.md index e21b54a7e..900d8b331 100644 --- a/specs/merge/fork-choice.md +++ b/specs/merge/fork-choice.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 The Merge +# The Merge -- Fork Choice **Notice**: This document is a work-in-progress for researchers and implementers. diff --git a/specs/merge/fork.md b/specs/merge/fork.md index c89e00cf9..0a1271d82 100644 --- a/specs/merge/fork.md +++ b/specs/merge/fork.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 The Merge +# The Merge -- Fork Logic **Notice**: This document is a work-in-progress for researchers and implementers. diff --git a/specs/merge/p2p-interface.md b/specs/merge/p2p-interface.md index c79d14b05..85a96c31e 100644 --- a/specs/merge/p2p-interface.md +++ b/specs/merge/p2p-interface.md @@ -1,6 +1,6 @@ -# Ethereum Merge networking specification +# The Merge -- Networking -This document contains the networking specification for Ethereum 2.0 clients added during the Merge deployment. +This document contains the networking specification for the Merge. The specification of these changes continues in the same format as the network specifications of previous upgrades, and assumes them as pre-requisite. This document should be viewed as additive to the documents from [Phase 0](../phase0/p2p-interface.md) and from [Altair](../altair/p2p-interface.md) and will be referred to as the "Phase 0 document" and "Altair document" respectively, hereafter. diff --git a/specs/merge/validator.md b/specs/merge/validator.md index baf716760..84207e49c 100644 --- a/specs/merge/validator.md +++ b/specs/merge/validator.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 The Merge +# The Merge -- Honest Validator **Notice**: This document is a work-in-progress for researchers and implementers. diff --git a/specs/phase0/beacon-chain.md b/specs/phase0/beacon-chain.md index 5ab9b75fd..e2e235acf 100644 --- a/specs/phase0/beacon-chain.md +++ b/specs/phase0/beacon-chain.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Phase 0 -- The Beacon Chain +# Phase 0 -- The Beacon Chain ## Table of contents @@ -140,10 +140,10 @@ ## Introduction -This document represents the specification for Phase 0 of Ethereum 2.0 -- The Beacon Chain. +This document represents the specification for Phase 0 -- The Beacon Chain. -At the core of Ethereum 2.0 is a system chain called the "beacon chain". The beacon chain stores and manages the registry of validators. In the initial deployment phases of Ethereum 2.0, the only mechanism to become a validator is to make a one-way ETH transaction to a deposit contract on Ethereum 1.0. Activation as a validator happens when Ethereum 1.0 deposit receipts are processed by the beacon chain, the activation balance is reached, and a queuing process is completed. Exit is either voluntary or done forcibly as a penalty for misbehavior. -The primary source of load on the beacon chain is "attestations". Attestations are simultaneously availability votes for a shard block (in a later Eth2 upgrade) and proof-of-stake votes for a beacon block (Phase 0). +At the core of Ethereum proof-of-stake is a system chain called the "beacon chain". The beacon chain stores and manages the registry of validators. In the initial deployment phases of proof-of-stake, the only mechanism to become a validator is to make a one-way ETH transaction to a deposit contract on the Ethereum proof-of-work chain. Activation as a validator happens when deposit receipts are processed by the beacon chain, the activation balance is reached, and a queuing process is completed. Exit is either voluntary or done forcibly as a penalty for misbehavior. +The primary source of load on the beacon chain is "attestations". Attestations are simultaneously availability votes for a shard block (in a later upgrade) and proof-of-stake votes for a beacon block (Phase 0). ## Notation @@ -1166,13 +1166,13 @@ def slash_validator(state: BeaconState, ## Genesis -Before the Ethereum 2.0 genesis has been triggered, and for every Ethereum 1.0 block, let `candidate_state = initialize_beacon_state_from_eth1(eth1_block_hash, eth1_timestamp, deposits)` where: +Before the Ethereum beacon chain genesis has been triggered, and for every Ethereum proof-of-work block, let `candidate_state = initialize_beacon_state_from_eth1(eth1_block_hash, eth1_timestamp, deposits)` where: -- `eth1_block_hash` is the hash of the Ethereum 1.0 block +- `eth1_block_hash` is the hash of the Ethereum proof-of-work block - `eth1_timestamp` is the Unix timestamp corresponding to `eth1_block_hash` - `deposits` is the sequence of all deposits, ordered chronologically, up to (and including) the block with hash `eth1_block_hash` -Eth1 blocks must only be considered once they are at least `SECONDS_PER_ETH1_BLOCK * ETH1_FOLLOW_DISTANCE` seconds old (i.e. `eth1_timestamp + SECONDS_PER_ETH1_BLOCK * ETH1_FOLLOW_DISTANCE <= current_unix_time`). Due to this constraint, if `GENESIS_DELAY < SECONDS_PER_ETH1_BLOCK * ETH1_FOLLOW_DISTANCE`, then the `genesis_time` can happen before the time/state is first known. Values should be configured to avoid this case. +Proof-of-work blocks must only be considered once they are at least `SECONDS_PER_ETH1_BLOCK * ETH1_FOLLOW_DISTANCE` seconds old (i.e. `eth1_timestamp + SECONDS_PER_ETH1_BLOCK * ETH1_FOLLOW_DISTANCE <= current_unix_time`). Due to this constraint, if `GENESIS_DELAY < SECONDS_PER_ETH1_BLOCK * ETH1_FOLLOW_DISTANCE`, then the `genesis_time` can happen before the time/state is first known. Values should be configured to avoid this case. ```python def initialize_beacon_state_from_eth1(eth1_block_hash: Bytes32, diff --git a/specs/phase0/deposit-contract.md b/specs/phase0/deposit-contract.md index 02e762dae..51786129c 100644 --- a/specs/phase0/deposit-contract.md +++ b/specs/phase0/deposit-contract.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Phase 0 -- Deposit Contract +# Phase 0 -- Deposit Contract ## Table of contents @@ -8,7 +8,7 @@ - [Introduction](#introduction) - [Constants](#constants) - [Configuration](#configuration) -- [Ethereum 1.0 deposit contract](#ethereum-10-deposit-contract) +- [Staking deposit contract](#staking-deposit-contract) - [`deposit` function](#deposit-function) - [Deposit amount](#deposit-amount) - [Withdrawal credentials](#withdrawal-credentials) @@ -20,7 +20,7 @@ ## Introduction -This document represents the specification for the beacon chain deposit contract, part of Ethereum 2.0 Phase 0. +This document represents the specification for the beacon chain deposit contract, part of Phase 0. ## Constants @@ -42,9 +42,9 @@ These configurations are updated for releases and may be out of sync during `dev | `DEPOSIT_NETWORK_ID` | `1` | | `DEPOSIT_CONTRACT_ADDRESS` | `0x00000000219ab540356cBB839Cbe05303d7705Fa` | -## Ethereum 1.0 deposit contract +## Staking deposit contract -The initial deployment phases of Ethereum 2.0 are implemented without consensus changes to Ethereum 1.0. A deposit contract at address `DEPOSIT_CONTRACT_ADDRESS` is added to the Ethereum 1.0 chain defined by the [chain-id](https://eips.ethereum.org/EIPS/eip-155) -- `DEPOSIT_CHAIN_ID` -- and the network-id -- `DEPOSIT_NETWORK_ID` -- for deposits of ETH to the beacon chain. Validator balances will be withdrawable to the shards in Phase 2. +The initial deployment phases of Ethereum proof-of-stake are implemented without consensus changes to the existing Ethereum proof-of-work chain. A deposit contract at address `DEPOSIT_CONTRACT_ADDRESS` is added to the Ethereum proof-of-work chain defined by the [chain-id](https://eips.ethereum.org/EIPS/eip-155) -- `DEPOSIT_CHAIN_ID` -- and the network-id -- `DEPOSIT_NETWORK_ID` -- for deposits of ETH to the beacon chain. Validator balances will be withdrawable to the execution-layer in a followup fork after the Merge. _Note_: See [here](https://chainid.network/) for a comprehensive list of public Ethereum chain chain-id's and network-id's. @@ -54,7 +54,7 @@ The deposit contract has a public `deposit` function to make deposits. It takes #### Deposit amount -The amount of ETH (rounded down to the closest Gwei) sent to the deposit contract is the deposit amount, which must be of size at least `MIN_DEPOSIT_AMOUNT` Gwei. Note that ETH consumed by the deposit contract is no longer usable on Ethereum 1.0. +The amount of ETH (rounded down to the closest Gwei) sent to the deposit contract is the deposit amount, which must be of size at least `MIN_DEPOSIT_AMOUNT` Gwei. Note that ETH consumed by the deposit contract is no longer usable on the execution-layer until sometime after the Merge. #### Withdrawal credentials @@ -68,7 +68,7 @@ Support for new withdrawal prefixes can be added without modifying the deposit c #### `DepositEvent` log -Every Ethereum 1.0 deposit emits a `DepositEvent` log for consumption by the beacon chain. The deposit contract does little validation, pushing most of the validator onboarding logic to the beacon chain. In particular, the proof of possession (a BLS12-381 signature) is not verified by the deposit contract. +Every deposit emits a `DepositEvent` log for consumption by the beacon chain. The deposit contract does little validation, pushing most of the validator onboarding logic to the beacon chain. In particular, the proof of possession (a BLS12-381 signature) is not verified by the deposit contract. ## Solidity code diff --git a/specs/phase0/fork-choice.md b/specs/phase0/fork-choice.md index 181a874fb..7d382a9ab 100644 --- a/specs/phase0/fork-choice.md +++ b/specs/phase0/fork-choice.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Phase 0 -- Beacon Chain Fork Choice +# Phase 0 -- Beacon Chain Fork Choice ## Table of contents @@ -35,7 +35,7 @@ ## Introduction -This document is the beacon chain fork choice spec, part of Ethereum 2.0 Phase 0. It assumes the [beacon chain state transition function spec](./beacon-chain.md). +This document is the beacon chain fork choice spec, part of Phase 0. It assumes the [beacon chain state transition function spec](./beacon-chain.md). ## Fork choice @@ -51,7 +51,7 @@ Any of the above handlers that trigger an unhandled exception (e.g. a failed ass 1) **Leap seconds**: Slots will last `SECONDS_PER_SLOT + 1` or `SECONDS_PER_SLOT - 1` seconds around leap seconds. This is automatically handled by [UNIX time](https://en.wikipedia.org/wiki/Unix_time). 2) **Honest clocks**: Honest nodes are assumed to have clocks synchronized within `SECONDS_PER_SLOT` seconds of each other. -3) **Eth1 data**: The large `ETH1_FOLLOW_DISTANCE` specified in the [honest validator document](./validator.md) should ensure that `state.latest_eth1_data` of the canonical Ethereum 2.0 chain remains consistent with the canonical Ethereum 1.0 chain. If not, emergency manual intervention will be required. +3) **Eth1 data**: The large `ETH1_FOLLOW_DISTANCE` specified in the [honest validator document](./validator.md) should ensure that `state.latest_eth1_data` of the canonical beacon chain remains consistent with the canonical Ethereum proof-of-work chain. If not, emergency manual intervention will be required. 4) **Manual forks**: Manual forks may arbitrarily change the fork choice rule but are expected to be enacted at epoch transitions, with the fork details reflected in `state.fork`. 5) **Implementation**: The implementation found in this specification is constructed for ease of understanding rather than for optimization in computation, space, or any other resource. A number of optimized alternatives can be found [here](https://github.com/protolambda/lmd-ghost). diff --git a/specs/phase0/p2p-interface.md b/specs/phase0/p2p-interface.md index 29fea5713..f5c138f99 100644 --- a/specs/phase0/p2p-interface.md +++ b/specs/phase0/p2p-interface.md @@ -1,13 +1,13 @@ -# Ethereum 2.0 networking specification +# Phase 0 -- Networking -This document contains the networking specification for Ethereum 2.0 clients. +This document contains the networking specification for Phase 0. It consists of four main sections: 1. A specification of the network fundamentals. -2. A specification of the three network interaction *domains* of Eth2: (a) the gossip domain, (b) the discovery domain, and (c) the Req/Resp domain. +2. A specification of the three network interaction *domains* of the proof-of-stake consensus layer: (a) the gossip domain, (b) the discovery domain, and (c) the Req/Resp domain. 3. The rationale and further explanation for the design choices made in the previous two sections. -4. An analysis of the maturity/state of the libp2p features required by this spec across the languages in which Eth2 clients are being developed. +4. An analysis of the maturity/state of the libp2p features required by this spec across the languages in which clients are being developed. ## Table of contents @@ -19,7 +19,7 @@ It consists of four main sections: - [Encryption and identification](#encryption-and-identification) - [Protocol Negotiation](#protocol-negotiation) - [Multiplexing](#multiplexing) -- [Eth2 network interaction domains](#eth2-network-interaction-domains) +- [Consensus-layer network interaction domains](#consensus-layer-network-interaction-domains) - [Configuration](#configuration) - [MetaData](#metadata) - [The gossip domain: gossipsub](#the-gossip-domain-gossipsub) @@ -113,7 +113,7 @@ It consists of four main sections: # Network fundamentals -This section outlines the specification for the networking stack in Ethereum 2.0 clients. +This section outlines the specification for the networking stack in Ethereum consensus-layer clients. ## Transport @@ -163,7 +163,7 @@ and MAY support [yamux](https://github.com/hashicorp/yamux/blob/master/spec.md). If both are supported by the client, yamux MUST take precedence during negotiation. See the [Rationale](#design-decision-rationale) section below for tradeoffs. -# Eth2 network interaction domains +# Consensus-layer network interaction domains ## Configuration @@ -435,7 +435,7 @@ The following validations MUST pass before forwarding the `attestation` on the s Attestation broadcasting is grouped into subnets defined by a topic. The number of subnets is defined via `ATTESTATION_SUBNET_COUNT`. The correct subnet for an attestation can be calculated with `compute_subnet_for_attestation`. -`beacon_attestation_{subnet_id}` topics, are rotated through throughout the epoch in a similar fashion to rotating through shards in committees (future Eth2 upgrade). +`beacon_attestation_{subnet_id}` topics, are rotated through throughout the epoch in a similar fashion to rotating through shards in committees (future beacon chain upgrade). The subnets are rotated through with `committees_per_slot = get_committee_count_per_slot(state, attestation.data.target.epoch)` subnets per slot. Unaggregated attestations are sent as `Attestation`s to the subnet topic, @@ -904,7 +904,7 @@ This integration enables the libp2p stack to subsequently form connections and s ### ENR structure -The Ethereum Node Record (ENR) for an Ethereum 2.0 client MUST contain the following entries +The Ethereum Node Record (ENR) for an Ethereum consensus client MUST contain the following entries (exclusive of the sequence number and signature, which MUST be present in an ENR): - The compressed secp256k1 publickey, 33 bytes (`secp256k1` field). @@ -933,7 +933,7 @@ If a node's `MetaData.attnets` is composed of all zeros, the ENR MAY optionally #### `eth2` field ENRs MUST carry a generic `eth2` key with an 16-byte value of the node's current fork digest, next fork version, -and next fork epoch to ensure connections are made with peers on the intended eth2 network. +and next fork epoch to ensure connections are made with peers on the intended Ethereum network. | Key | Value | |:-------------|:--------------------| @@ -998,7 +998,7 @@ The libp2p QUIC transport inherently relies on TLS 1.3 per requirement in sectio of the [QUIC protocol specification](https://tools.ietf.org/html/draft-ietf-quic-transport-22#section-7) and the accompanying [QUIC-TLS document](https://tools.ietf.org/html/draft-ietf-quic-tls-22). -The usage of one handshake procedure or the other shall be transparent to the Eth2 application layer, +The usage of one handshake procedure or the other shall be transparent to the application layer, once the libp2p Host/Node object has been configured appropriately. ### What are the advantages of using TCP/QUIC/Websockets? @@ -1019,7 +1019,7 @@ Provided that we use the same port numbers and encryption mechanisms as HTTP/3, and we may only become subject to standard IP-based firewall filtering—something we can counteract via other mechanisms. WebSockets and/or WebRTC transports are necessary for interaction with browsers, -and will become increasingly important as we incorporate browser-based light clients to the Eth2 network. +and will become increasingly important as we incorporate browser-based light clients to the Ethereum network. ### Why do we not just support a single transport? @@ -1186,7 +1186,7 @@ Enforcing hashes for topic names would preclude us from leveraging such features No security or privacy guarantees are lost as a result of choosing plaintext topic names, since the domain is finite anyway, and calculating a digest's preimage would be trivial. -Furthermore, the Eth2 topic names are shorter than their digest equivalents (assuming SHA-256 hash), +Furthermore, the topic names are shorter than their digest equivalents (assuming SHA-256 hash), so hashing topics would bloat messages unnecessarily. ### Why are we using the `StrictNoSign` signature policy? @@ -1211,7 +1211,7 @@ Some examples of where messages could be duplicated: ### Why are these specific gossip parameters chosen? - `D`, `D_low`, `D_high`, `D_lazy`: recommended defaults. -- `heartbeat_interval`: 0.7 seconds, recommended for eth2 in the [GossipSub evaluation report by Protocol Labs](https://gateway.ipfs.io/ipfs/QmRAFP5DBnvNjdYSbWhEhVRJJDFCLpPyvew5GwCCB4VxM4). +- `heartbeat_interval`: 0.7 seconds, recommended for the beacon chain in the [GossipSub evaluation report by Protocol Labs](https://gateway.ipfs.io/ipfs/QmRAFP5DBnvNjdYSbWhEhVRJJDFCLpPyvew5GwCCB4VxM4). - `fanout_ttl`: 60 seconds, recommended default. Fanout is primarily used by committees publishing attestations to subnets. This happens once per epoch per validator and the subnet changes each epoch @@ -1285,7 +1285,7 @@ due to not being fully synced to ensure that such (amplified) DOS attacks are no In Phase 0, peers for attestation subnets will be found using the `attnets` entry in the ENR. -Although this method will be sufficient for early phases of Eth2, we aim to use the more appropriate discv5 topics for this and other similar tasks in the future. +Although this method will be sufficient for early upgrade of the beacon chain, we aim to use the more appropriate discv5 topics for this and other similar tasks in the future. ENRs should ultimately not be used for this purpose. They are best suited to store identity, location, and capability information, rather than more volatile advertisements. @@ -1319,7 +1319,7 @@ Requests are segregated by protocol ID to: 4. Enable flexibility and agility for clients adopting spec changes that impact the request, by signalling to peers exactly which subset of new/old requests they support. 5. Enable clients to explicitly choose backwards compatibility at the request granularity. Without this, clients would be forced to support entire versions of the coarser request protocol. -6. Parallelise RFCs (or Eth2 EIPs). +6. Parallelise RFCs (or EIPs). By decoupling requests from one another, each RFC that affects the request protocol can be deployed/tested/debated independently without relying on a synchronization point to version the general top-level protocol. 1. This has the benefit that clients can explicitly choose which RFCs to deploy @@ -1476,8 +1476,8 @@ discv5 supports self-certified, flexible peer records (ENRs) and topic-based adv On the other hand, libp2p Kademlia DHT is a fully-fledged DHT protocol/implementations with content routing and storage capabilities, both of which are irrelevant in this context. -Eth 1.0 nodes will evolve to support discv5. -By sharing the discovery network between Eth 1.0 and 2.0, +Ethereum execution-layer nodes will evolve to support discv5. +By sharing the discovery network between Ethereum consensus-layer and execution-layer clients, we benefit from the additive effect on network size that enhances resilience and resistance against certain attacks, to which smaller networks are more vulnerable. It should also help light clients of both networks find nodes with specific capabilities. @@ -1502,17 +1502,17 @@ discv5 uses ENRs and we will presumably need to: 1. Add `multiaddr` to the dictionary, so that nodes can advertise their multiaddr under a reserved namespace in ENRs. – and/or – 2. Define a bi-directional conversion function between multiaddrs and the corresponding denormalized fields in an ENR - (ip, ip6, tcp, tcp6, etc.), for compatibility with nodes that do not support multiaddr natively (e.g. Eth 1.0 nodes). + (ip, ip6, tcp, tcp6, etc.), for compatibility with nodes that do not support multiaddr natively (e.g. Ethereum execution-layer nodes). ### Why do we not form ENRs and find peers until genesis block/state is known? -Although client software might very well be running locally prior to the solidification of the eth2 genesis state and block, +Although client software might very well be running locally prior to the solidification of the beacon chain genesis state and block, clients cannot form valid ENRs prior to this point. ENRs contain `fork_digest` which utilizes the `genesis_validators_root` for a cleaner separation between chains so prior to knowing genesis, we cannot use `fork_digest` to cleanly find peers on our intended chain. Once genesis data is known, we can then form ENRs and safely find peers. -When using an eth1 deposit contract for deposits, `fork_digest` will be known `GENESIS_DELAY` (7 days in mainnet configuration) before `genesis_time`, +When using a proof-of-work deposit contract for deposits, `fork_digest` will be known `GENESIS_DELAY` (7 days in mainnet configuration) before `genesis_time`, providing ample time to find peers and form initial connections and gossip subnets prior to genesis. ## Compression/Encoding @@ -1586,4 +1586,4 @@ It is advisable to derive these lengths from the SSZ type definitions in use, to # libp2p implementations matrix This section will soon contain a matrix showing the maturity/state of the libp2p features required -by this spec across the languages in which Eth2 clients are being developed. +by this spec across the languages in which clients are being developed. diff --git a/specs/phase0/validator.md b/specs/phase0/validator.md index a548003e1..814859c12 100644 --- a/specs/phase0/validator.md +++ b/specs/phase0/validator.md @@ -1,6 +1,6 @@ -# Ethereum 2.0 Phase 0 -- Honest Validator +# Phase 0 -- Honest Validator -This is an accompanying document to [Ethereum 2.0 Phase 0 -- The Beacon Chain](./beacon-chain.md), which describes the expected actions of a "validator" participating in the Ethereum 2.0 protocol. +This is an accompanying document to [Phase 0 -- The Beacon Chain](./beacon-chain.md), which describes the expected actions of a "validator" participating in the Ethereum proof-of-stake protocol. ## Table of contents @@ -74,9 +74,9 @@ This is an accompanying document to [Ethereum 2.0 Phase 0 -- The Beacon Chain](. ## Introduction -This document represents the expected behavior of an "honest validator" with respect to Phase 0 of the Ethereum 2.0 protocol. This document does not distinguish between a "node" (i.e. the functionality of following and reading the beacon chain) and a "validator client" (i.e. the functionality of actively participating in consensus). The separation of concerns between these (potentially) two pieces of software is left as a design decision that is out of scope. +This document represents the expected behavior of an "honest validator" with respect to Phase 0 of the Ethereum proof-of-stake protocol. This document does not distinguish between a "node" (i.e. the functionality of following and reading the beacon chain) and a "validator client" (i.e. the functionality of actively participating in consensus). The separation of concerns between these (potentially) two pieces of software is left as a design decision that is out of scope. -A validator is an entity that participates in the consensus of the Ethereum 2.0 protocol. This is an optional role for users in which they can post ETH as collateral and verify and attest to the validity of blocks to seek financial returns in exchange for building and securing the protocol. This is similar to proof-of-work networks in which miners provide collateral in the form of hardware/hash-power to seek returns in exchange for building and securing the protocol. +A validator is an entity that participates in the consensus of the Ethereum proof-of-stake protocol. This is an optional role for users in which they can post ETH as collateral and verify and attest to the validity of blocks to seek financial returns in exchange for building and securing the protocol. This is similar to proof-of-work networks in which miners provide collateral in the form of hardware/hash-power to seek returns in exchange for building and securing the protocol. ## Prerequisites @@ -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 (Eth1) into the Beacon Chain (Eth2), +After the merge of the current Ethereum application layer into the Beacon Chain, withdrawals to `eth1_withdrawal_address` will be normal ETH transfers (with no payload other than the validator's ETH) triggered by a user transaction that will set the gas price and gas limit as well pay fees. As long as the account or contract with address `eth1_withdrawal_address` can receive ETH transfers, @@ -170,7 +170,7 @@ the future withdrawal protocol is agnostic to all other implementation details. ### Submit deposit -In Phase 0, all incoming validator deposits originate from the Ethereum 1.0 chain defined by `DEPOSIT_CHAIN_ID` and `DEPOSIT_NETWORK_ID`. Deposits are made to the [deposit contract](./deposit-contract.md) located at `DEPOSIT_CONTRACT_ADDRESS`. +In Phase 0, all incoming validator deposits originate from the Ethereum proof-of-work chain defined by `DEPOSIT_CHAIN_ID` and `DEPOSIT_NETWORK_ID`. Deposits are made to the [deposit contract](./deposit-contract.md) located at `DEPOSIT_CONTRACT_ADDRESS`. To submit a deposit: @@ -182,13 +182,13 @@ To submit a deposit: - Let `deposit_message` be a `DepositMessage` with all the `DepositData` contents except the `signature`. - Let `signature` be the result of `bls.Sign` of the `compute_signing_root(deposit_message, domain)` with `domain=compute_domain(DOMAIN_DEPOSIT)`. (_Warning_: Deposits _must_ be signed with `GENESIS_FORK_VERSION`, calling `compute_domain` without a second argument defaults to the correct version). - Let `deposit_data_root` be `hash_tree_root(deposit_data)`. -- Send a transaction on the Ethereum 1.0 chain to `DEPOSIT_CONTRACT_ADDRESS` executing `def deposit(pubkey: bytes[48], withdrawal_credentials: bytes[32], signature: bytes[96], deposit_data_root: bytes32)` along with a deposit of `amount` Gwei. +- Send a transaction on the Ethereum proof-of-work chain to `DEPOSIT_CONTRACT_ADDRESS` executing `def deposit(pubkey: bytes[48], withdrawal_credentials: bytes[32], signature: bytes[96], deposit_data_root: bytes32)` along with a deposit of `amount` Gwei. *Note*: Deposits made for the same `pubkey` are treated as for the same validator. A singular `Validator` will be added to `state.validators` with each additional deposit amount added to the validator's balance. A validator can only be activated when total deposits for the validator pubkey meet or exceed `MAX_EFFECTIVE_BALANCE`. ### Process deposit -Deposits cannot be processed into the beacon chain until the Eth1 block in which they were deposited or any of its descendants is added to the beacon chain `state.eth1_data`. This takes _a minimum_ of `ETH1_FOLLOW_DISTANCE` Eth1 blocks (~8 hours) plus `EPOCHS_PER_ETH1_VOTING_PERIOD` epochs (~6.8 hours). Once the requisite Eth1 data is added, the deposit will normally be added to a beacon chain block and processed into the `state.validators` within an epoch or two. The validator is then in a queue to be activated. +Deposits cannot be processed into the beacon chain until the proof-of-work block in which they were deposited or any of its descendants is added to the beacon chain `state.eth1_data`. This takes _a minimum_ of `ETH1_FOLLOW_DISTANCE` Eth1 blocks (~8 hours) plus `EPOCHS_PER_ETH1_VOTING_PERIOD` epochs (~6.8 hours). Once the requisite proof-of-work block data is added, the deposit will normally be added to a beacon chain block and processed into the `state.validators` within an epoch or two. The validator is then in a queue to be activated. ### Validator index @@ -401,9 +401,9 @@ Up to `MAX_ATTESTATIONS`, aggregate attestations can be included in the `block`. ##### Deposits -If there are any unprocessed deposits for the existing `state.eth1_data` (i.e. `state.eth1_data.deposit_count > state.eth1_deposit_index`), then pending deposits _must_ be added to the block. The expected number of deposits is exactly `min(MAX_DEPOSITS, eth1_data.deposit_count - state.eth1_deposit_index)`. These [`deposits`](./beacon-chain.md#deposit) are constructed from the `Deposit` logs from the [Eth1 deposit contract](./deposit-contract.md) and must be processed in sequential order. The deposits included in the `block` must satisfy the verification conditions found in [deposits processing](./beacon-chain.md#deposits). +If there are any unprocessed deposits for the existing `state.eth1_data` (i.e. `state.eth1_data.deposit_count > state.eth1_deposit_index`), then pending deposits _must_ be added to the block. The expected number of deposits is exactly `min(MAX_DEPOSITS, eth1_data.deposit_count - state.eth1_deposit_index)`. These [`deposits`](./beacon-chain.md#deposit) are constructed from the `Deposit` logs from the [deposit contract](./deposit-contract.md) and must be processed in sequential order. The deposits included in the `block` must satisfy the verification conditions found in [deposits processing](./beacon-chain.md#deposits). -The `proof` for each deposit must be constructed against the deposit root contained in `state.eth1_data` rather than the deposit root at the time the deposit was initially logged from the 1.0 chain. This entails storing a full deposit merkle tree locally and computing updated proofs against the `eth1_data.deposit_root` as needed. See [`minimal_merkle.py`](https://github.com/ethereum/research/blob/master/spec_pythonizer/utils/merkle_minimal.py) for a sample implementation. +The `proof` for each deposit must be constructed against the deposit root contained in `state.eth1_data` rather than the deposit root at the time the deposit was initially logged from the proof-of-work chain. This entails storing a full deposit merkle tree locally and computing updated proofs against the `eth1_data.deposit_root` as needed. See [`minimal_merkle.py`](https://github.com/ethereum/research/blob/master/spec_pythonizer/utils/merkle_minimal.py) for a sample implementation. ##### Voluntary exits diff --git a/specs/phase0/weak-subjectivity.md b/specs/phase0/weak-subjectivity.md index 3748a7391..52953c34d 100644 --- a/specs/phase0/weak-subjectivity.md +++ b/specs/phase0/weak-subjectivity.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Phase 0 -- Weak Subjectivity Guide +# Phase 0 -- Weak Subjectivity Guide ## Table of contents @@ -26,11 +26,11 @@ ## Introduction -This document is a guide for implementing the Weak Subjectivity protections in Phase 0 of Ethereum 2.0. +This document is a guide for implementing the Weak Subjectivity protections in Phase 0. This document is still a work-in-progress, and is subject to large changes. For more information about weak subjectivity and why it is required, please refer to: -- [Weak Subjectivity in Eth2.0](https://notes.ethereum.org/@adiasg/weak-subjectvity-eth2) +- [Weak Subjectivity in Ethereum Proof-of-Stake](https://notes.ethereum.org/@adiasg/weak-subjectvity-eth2) - [Proof of Stake: How I Learned to Love Weak Subjectivity](https://blog.ethereum.org/2014/11/25/proof-stake-learned-love-weak-subjectivity/) ## Prerequisites @@ -77,7 +77,7 @@ a safety margin of at least `1/3 - SAFETY_DECAY/100`. A detailed analysis of the calculation of the weak subjectivity period is made in [this report](https://github.com/runtimeverification/beacon-chain-verification/blob/master/weak-subjectivity/weak-subjectivity-analysis.pdf). -*Note*: The expressions in the report use fractions, whereas eth2.0-specs uses only `uint64` arithmetic. The expressions have been simplified to avoid computing fractions, and more details can be found [here](https://www.overleaf.com/read/wgjzjdjpvpsd). +*Note*: The expressions in the report use fractions, whereas the consensus-specs only use `uint64` arithmetic. The expressions have been simplified to avoid computing fractions, and more details can be found [here](https://www.overleaf.com/read/wgjzjdjpvpsd). *Note*: The calculations here use `Ether` instead of `Gwei`, because the large magnitude of balances in `Gwei` can cause an overflow while computing using `uint64` arithmetic operations. Using `Ether` reduces the magnitude of the multiplicative factors by an order of `ETH_TO_GWEI` (`= 10**9`) and avoid the scope for overflows in `uint64`. diff --git a/specs/sharding/beacon-chain.md b/specs/sharding/beacon-chain.md index 9269d1461..2e2c3d487 100644 --- a/specs/sharding/beacon-chain.md +++ b/specs/sharding/beacon-chain.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Sharding -- Beacon Chain changes +# Sharding -- The Beacon Chain **Notice**: This document is a work-in-progress for researchers and implementers. diff --git a/specs/sharding/p2p-interface.md b/specs/sharding/p2p-interface.md index 93ff1e26d..c47d2ee07 100644 --- a/specs/sharding/p2p-interface.md +++ b/specs/sharding/p2p-interface.md @@ -1,4 +1,4 @@ -# Ethereum 2.0 Sharding -- Network specification +# Sharding -- Networking **Notice**: This document is a work-in-progress for researchers and implementers. diff --git a/tests/core/pyspec/README.md b/tests/core/pyspec/README.md index 4a4e20854..baa132277 100644 --- a/tests/core/pyspec/README.md +++ b/tests/core/pyspec/README.md @@ -1,6 +1,6 @@ -# Eth2 Executable Python Spec (PySpec) +# Executable Python Spec (PySpec) -The executable Python spec is built from the Eth2 specification, +The executable Python spec is built from the consensus specifications, complemented with the necessary helper functions for hashing, BLS, and more. With this executable spec, @@ -27,7 +27,7 @@ to enable debuggers to navigate between packages and generated code, without fra By default, when installing the `eth2spec` as package in non-develop mode, the distutils implementation of the `setup` runs `build`, which is extended to run the same `pyspec` work, but outputs into the standard `./build/lib` output. -This enables the `eth2.0-specs` repository to be installed like any other python package. +This enables the `consensus-specs` repository to be installed like any other python package. ## Py-tests diff --git a/tests/core/pyspec/eth2spec/config/README.md b/tests/core/pyspec/eth2spec/config/README.md index 5a64d39ba..c03d890c2 100644 --- a/tests/core/pyspec/eth2spec/config/README.md +++ b/tests/core/pyspec/eth2spec/config/README.md @@ -1,4 +1,4 @@ -# Eth2 config util +# Consensus specs config util For run-time configuration, see [Configs documentation](../../../../../configs/README.md). @@ -13,7 +13,7 @@ from eth2spec.phase0 import mainnet as spec from pathlib import Path # To load the default configurations -config_util.load_defaults(Path("eth2.0-specs/configs")) # change path to point to equivalent of specs `configs` dir. +config_util.load_defaults(Path("consensus-specs/configs")) # change path to point to equivalent of specs `configs` dir. # After loading the defaults, a config can be chosen: 'mainnet', 'minimal', or custom network config (by file path) spec.config = spec.Configuration(**config_util.load_config_file(Path('mytestnet.yaml'))) ``` diff --git a/tests/core/pyspec/eth2spec/gen_helpers/README.md b/tests/core/pyspec/eth2spec/gen_helpers/README.md index 5bd76b99f..bf791ccfe 100644 --- a/tests/core/pyspec/eth2spec/gen_helpers/README.md +++ b/tests/core/pyspec/eth2spec/gen_helpers/README.md @@ -1,4 +1,4 @@ -# Eth2 test generator helpers +# Consensus test generator helpers ## `gen_base` diff --git a/tests/formats/README.md b/tests/formats/README.md index 39968832f..e4f2bcb29 100644 --- a/tests/formats/README.md +++ b/tests/formats/README.md @@ -1,6 +1,6 @@ # General test format -This document defines the YAML format and structure used for Eth2 testing. +This document defines the YAML format and structure used for consensus spec testing. ## Table of contents @@ -151,7 +151,7 @@ Between all types of tests, a few formats are common: - **`.yaml`**: A YAML file containing structured data to describe settings or test contents. - **`.ssz`**: A file containing raw SSZ-encoded data. Previously widely used in tests, but replaced with compressed variant. - **`.ssz_snappy`**: Like `.ssz`, but compressed with Snappy block compression. - Snappy block compression is already applied to SSZ in Eth2 gossip, available in client implementations, and thus chosen as compression method. + Snappy block compression is already applied to SSZ in consensus-layer gossip, available in client implementations, and thus chosen as compression method. #### Special output parts diff --git a/tests/formats/ssz_static/README.md b/tests/formats/ssz_static/README.md index 1ac91cb13..ffa737334 100644 --- a/tests/formats/ssz_static/README.md +++ b/tests/formats/ssz_static/README.md @@ -1,7 +1,7 @@ # SSZ, static tests This set of test-suites provides static testing for SSZ: - to instantiate just the known Eth2 SSZ types from binary data. + to instantiate just the known Ethereum SSZ types from binary data. This series of tests is based on the spec-maintained `eth2spec/utils/ssz/ssz_impl.py`, i.e. fully consistent with the SSZ spec. diff --git a/tests/generators/README.md b/tests/generators/README.md index 731184326..a84331dcb 100644 --- a/tests/generators/README.md +++ b/tests/generators/README.md @@ -1,9 +1,9 @@ -# Eth2 test generators +# Consensus test generators -This directory contains all the generators for tests, consumed by Eth2 client implementations. +This directory contains all the generators for tests, consumed by consensus-layer client implementations. Any issues with the generators and/or generated tests should be filed in the repository that hosts the generator outputs, - here: [ethereum/eth2.0-spec-tests](https://github.com/ethereum/eth2.0-spec-tests). + here: [ethereum/consensus-spec-tests](https://github.com/ethereum/consensus-spec-tests). On releases, test generators are run by the release manager. Test-generation of mainnet tests can take a significant amount of time, and is better left out of a CI setup. @@ -36,7 +36,7 @@ Prerequisites: ### Cleaning -This removes the existing virtual environments (`/tests/generators//venv`) and generated tests (`../eth2.0-spec-tests/tests`). +This removes the existing virtual environments (`/tests/generators//venv`) and generated tests (`../consensus-spec-tests/tests`). ```bash make clean @@ -226,5 +226,5 @@ Do note that generators should be easy to maintain, lean, and based on the spec. If a test generator is not needed anymore, undo the steps described above and make a new release: 1. Remove the generator directory. -2. Remove the generated tests in the [`eth2.0-spec-tests`](https://github.com/ethereum/eth2.0-spec-tests) repository by opening a pull request there. +2. Remove the generated tests in the [`consensus-spec-tests`](https://github.com/ethereum/consensus-spec-tests) repository by opening a pull request there. 3. Make a new release. diff --git a/tests/generators/shuffling/README.md b/tests/generators/shuffling/README.md index fae06ad7e..81ddaba15 100644 --- a/tests/generators/shuffling/README.md +++ b/tests/generators/shuffling/README.md @@ -1,10 +1,10 @@ # Shuffling Tests -Tests for the swap-or-not shuffling in Eth2. +Tests for the swap-or-not shuffling in the beacon chain. Tips for initial shuffling write: - run with `round_count = 1` first, do the same with pyspec. - start with permute index - optimized shuffling implementations: - - vitalik, Python: https://github.com/ethereum/eth2.0-specs/pull/576#issue-250741806 + - vitalik, Python: https://github.com/ethereum/consensus-specs/pull/576#issue-250741806 - protolambda, Go: https://github.com/protolambda/eth2-shuffle diff --git a/tests/generators/ssz_static/README.md b/tests/generators/ssz_static/README.md index 160d1ebb4..3434fe174 100644 --- a/tests/generators/ssz_static/README.md +++ b/tests/generators/ssz_static/README.md @@ -1,6 +1,6 @@ # SSZ-static The purpose of this test-generator is to provide test-vectors for the most important applications of SSZ: - the serialization and hashing of Eth2 data types. + the serialization and hashing of Ethereum data type. Test-format documentation can be found [here](../../formats/ssz_static/README.md).