From 8267c018b436a8790755fb49880fec045e0c05da Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 10:51:04 -0500 Subject: [PATCH 01/80] Update README.md --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 27ff7fcb1e..4c4808059f 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,14 @@ [![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 eth2.0/Serenity, see the [sharding FAQ](https://github.com/ethereum/wiki/wiki/Sharding-FAQ) and the [research compendium](https://notes.ethereum.org/s/H1PGqDhpm). +To learn more about sharding and Ethereum 2.0 (Serenity), see the [sharding FAQ](https://github.com/ethereum/wiki/wiki/Sharding-FAQ) and the [research compendium](https://notes.ethereum.org/s/H1PGqDhpm). -This repo hosts the current eth2.0 specifications. Discussions about design rationale and proposed changes can be brought up and discussed as issues. Solidified, agreed upon changes to spec can be made through pull requests. +This repository hosts the current Eth 2.0 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 -Core specifications for eth2.0 client validation can be found in [specs/core](specs/core). These are divided into phases. Each subsequent phase depends upon the prior. The current phases specified are: +Core specifications for Eth 2.0 client validation can be found in [specs/core](specs/core). These are divided into phases. Each subsequent phase depends upon the prior. The current phases specified are: ### Phase 0 * [The Beacon Chain](specs/core/0_beacon-chain.md) @@ -30,7 +30,7 @@ Core specifications for eth2.0 client validation can be found in [specs/core](sp * [Light client syncing protocol](specs/light_client/sync_protocol.md) -### Design goals +## Design goals The following are the broad design goals for Ethereum 2.0: * to minimize complexity, even at the cost of some losses in efficiency From 7fbba424b80861e4d6622b4ebd95888cbbdbe352 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 11:00:55 -0500 Subject: [PATCH 02/80] Update 0_beacon-chain.md --- specs/core/0_beacon-chain.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/specs/core/0_beacon-chain.md b/specs/core/0_beacon-chain.md index 7c5e39599f..d5fb104e6a 100644 --- a/specs/core/0_beacon-chain.md +++ b/specs/core/0_beacon-chain.md @@ -1,12 +1,12 @@ # Ethereum 2.0 Phase 0 -- The Beacon Chain -**NOTICE**: This document is a work in progress for researchers and implementers. +**NOTICE**: This document is a work-in-progress for researchers and implementers. -## Table of contents +## Table of Contents - [Ethereum 2.0 Phase 0 -- The Beacon Chain](#ethereum-20-phase-0----the-beacon-chain) - - [Table of contents](#table-of-contents) + - [Table of Contents](#table-of-contents) - [Introduction](#introduction) - [Notation](#notation) - [Terminology](#terminology) @@ -151,8 +151,8 @@ Code snippets appearing in `this style` are to be interpreted as Python code. ## Constants -Note: the default mainnet values for the constants are included here for spec-design purposes. -The different configurations for mainnet, testnets, and yaml-based testing can be found in the `configs/constant_presets/` directory. +*Note*: The default mainnet values for the constants are included here for spec-design purposes. +The different configurations for mainnet, testnets, and YAML-based testing can be found in the `configs/constant_presets/` directory. These configurations are updated for releases, but may be out of sync during `dev` changes. ### Misc @@ -165,7 +165,7 @@ These configurations are updated for releases, but may be out of sync during `de | `MIN_PER_EPOCH_CHURN_LIMIT` | `2**2` (= 4) | | `CHURN_LIMIT_QUOTIENT` | `2**16` (= 65,536) | | `BASE_REWARDS_PER_EPOCH` | `5` | -| `SHUFFLE_ROUND_COUNT` | 90 | +| `SHUFFLE_ROUND_COUNT` | `90` | * For the safety of crosslinks `TARGET_COMMITTEE_SIZE` exceeds [the recommended minimum committee size of 111](https://vitalik.ca/files/Ithaca201807_Sharding.pdf); with sufficient active validators (at least `SLOTS_PER_EPOCH * TARGET_COMMITTEE_SIZE`), the shuffling algorithm ensures committee sizes of at least `TARGET_COMMITTEE_SIZE`. (Unbiasable randomness with a Verifiable Delay Function (VDF) will improve committee robustness and lower the safe minimum committee size.) @@ -229,7 +229,7 @@ These configurations are updated for releases, but may be out of sync during `de | `INACTIVITY_PENALTY_QUOTIENT` | `2**25` (= 33,554,432) | | `MIN_SLASHING_PENALTY_QUOTIENT` | `2**5` (= 32) | -* **The `BASE_REWARD_QUOTIENT` is NOT final. Once all other protocol details are finalized it will be adjusted, to target a theoretical maximum total issuance of `2**21` ETH per year if `2**27` ETH is validating (and therefore `2**20` per year if `2**25` ETH is validating, etc etc)** +* **The `BASE_REWARD_QUOTIENT` is NOT final. Once all other protocol details are finalized, it will be adjusted to target a theoretical maximum total issuance of `2**21` ETH per year if `2**27` ETH is validating (and therefore `2**20` per year if `2**25` ETH is validating, etc etc)** * The `INACTIVITY_PENALTY_QUOTIENT` equals `INVERSE_SQRT_E_DROP_TIME**2` where `INVERSE_SQRT_E_DROP_TIME := 2**12 epochs` (~18 days) is the time it takes the inactivity penalty to reduce the balance of non-participating [validators](#dfn-validator) to about `1/sqrt(e) ~= 60.6%`. Indeed, the balance retained by offline [validators](#dfn-validator) 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)`. ### Max operations per block @@ -604,7 +604,7 @@ We define the following Python custom types for type hinting and readability: ## Helper functions -Note: The definitions below are for specification purposes and are not necessarily optimal implementations. +*Note*: The definitions below are for specification purposes and are not necessarily optimal implementations. ### `xor` @@ -617,7 +617,7 @@ def xor(bytes1: Bytes32, bytes2: Bytes32) -> Bytes32: The `hash` function is SHA256. -Note: We aim to migrate to a S[T/N]ARK-friendly hash function in a future Ethereum 2.0 deployment phase. +*Note*: We aim to migrate to a S[T/N]ARK-friendly hash function in a future Ethereum 2.0 deployment phase. ### `hash_tree_root` @@ -1120,7 +1120,7 @@ def get_churn_limit(state: BeaconState) -> int: ### Routines for updating validator status -Note: All functions in this section mutate `state`. +*Note*: All functions in this section mutate `state`. #### `initiate_validator_exit` @@ -1224,9 +1224,9 @@ Transition section notes: * The per-slot transitions focus on the slot counter. * The per-block transitions generally focus on verifying aggregate signatures and saving temporary records relating to the per-block activity in the `BeaconState`. -Beacon blocks that trigger unhandled Python exceptions (e.g. out-of-range list accesses) and failed `assert`s during the state transition are considered invalid. +Beacon blocks that trigger unhandled Python exceptions (e.g., out-of-range list accesses) and failed `assert`s during the state transition are considered invalid. -Note: If there are skipped slots between a block and its parent block, run the steps in the [state-root](#state-caching), [per-epoch](#per-epoch-processing), and [per-slot](#per-slot-processing) sections once for each skipped slot and then once for the slot containing the new block. +*Note*: If there are skipped slots between a block and its parent block, run the steps in the [state-root](#state-caching), [per-epoch](#per-epoch-processing), and [per-slot](#per-slot-processing) sections once for each skipped slot and then once for the slot containing the new block. ### State caching @@ -1632,7 +1632,7 @@ def process_eth1_data(state: BeaconState, block: BeaconBlock) -> None: #### Operations -Note: All functions in this section mutate `state`. +*Note*: All functions in this section mutate `state`. ##### Proposer slashings From c221a192067e83ec22d1507b62be61297a7ceddd Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 11:06:53 -0500 Subject: [PATCH 03/80] Update 0_deposit-contract.md --- specs/core/0_deposit-contract.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/specs/core/0_deposit-contract.md b/specs/core/0_deposit-contract.md index 6843e407ec..adea629b85 100644 --- a/specs/core/0_deposit-contract.md +++ b/specs/core/0_deposit-contract.md @@ -1,12 +1,12 @@ # Ethereum 2.0 Phase 0 -- Deposit Contract -**NOTICE**: This document is a work in progress for researchers and implementers. +**NOTICE**: This document is a work-in-progress for researchers and implementers. -## Table of contents +## Table of Contents - [Ethereum 2.0 Phase 0 -- Deposit Contract](#ethereum-20-phase-0----deposit-contract) - - [Table of contents](#table-of-contents) + - [Table of Contents](#table-of-contents) - [Introduction](#introduction) - [Constants](#constants) - [Gwei values](#gwei-values) @@ -24,7 +24,7 @@ ## Introduction -This document represents is 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 Ethereum 2.0 Phase 0. ## Constants @@ -40,11 +40,11 @@ This document represents is the specification for the beacon chain deposit contr | - | - | | `DEPOSIT_CONTRACT_ADDRESS` | **TBD** | | `DEPOSIT_CONTRACT_TREE_DEPTH` | `2**5` (= 32) | -| `CHAIN_START_FULL_DEPOSIT_THRESHOLD` | `2**16` (=65,536) | +| `CHAIN_START_FULL_DEPOSIT_THRESHOLD` | `2**16` (= 65,536) | ## Ethereum 1.0 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 Ethereum 1.0 for deposits of ETH to the beacon chain. Validator balances will be withdrawable to the shards in phase 2, i.e. when the EVM2.0 is deployed and the shards have state. +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 Ethereum 1.0 for deposits of ETH to the beacon chain. Validator balances will be withdrawable to the shards in Phase 2 (i.e., when the EVM 2.0 is deployed and the shards have state). ### Arguments @@ -52,12 +52,12 @@ The deposit contract has a `deposit` function which takes the amount in Ethereum #### Withdrawal credentials -One of the `DepositData` fields is `withdrawal_credentials`. It is a commitment to credentials for withdrawals to shards. The first byte of `withdrawal_credentials` is a version number. As of now the only expected format is as follows: +One of the `DepositData` fields is `withdrawal_credentials`. It is a commitment to credentials for withdrawals to shards. The first byte of `withdrawal_credentials` is a version number. As of now, the only expected format is as follows: * `withdrawal_credentials[:1] == BLS_WITHDRAWAL_PREFIX_BYTE` * `withdrawal_credentials[1:] == hash(withdrawal_pubkey)[1:]` where `withdrawal_pubkey` is a BLS pubkey -The private key corresponding to `withdrawal_pubkey` will be required to initiate a withdrawal. It can be stored separately until a withdrawal is required, e.g. in cold storage. +The private key corresponding to `withdrawal_pubkey` will be required to initiate a withdrawal. It can be stored separately until a withdrawal is required, e.g., in cold storage. #### Amount @@ -84,10 +84,10 @@ When `CHAIN_START_FULL_DEPOSIT_THRESHOLD` of full deposits have been made, the d The source for the Vyper contract lives in a [separate repository](https://github.com/ethereum/deposit_contract) at [https://github.com/ethereum/deposit_contract/blob/master/deposit_contract/contracts/validator_registration.v.py](https://github.com/ethereum/deposit_contract/blob/master/deposit_contract/contracts/validator_registration.v.py). -Note: to save ~10x on gas this contract uses a somewhat unintuitive progressive Merkle root calculation algo that requires only O(log(n)) storage. See https://github.com/ethereum/research/blob/master/beacon_chain_impl/progressive_merkle_tree.py for an implementation of the same algo in python tested for correctness. +*Note*: To save ~10x on gas, this contract uses a somewhat unintuitive progressive Merkle root calculation algo that requires only O(log(n)) storage. See https://github.com/ethereum/research/blob/master/beacon_chain_impl/progressive_merkle_tree.py for an implementation of the same algo in Python tested for correctness. For convenience, we provide the interface to the contract here: * `__init__()`: initializes the contract * `get_deposit_root() -> bytes32`: returns the current root of the deposit tree -* `deposit(pubkey: bytes[48], withdrawal_credentials: bytes[32], signature: bytes[96])`: adds a deposit instance to the deposit tree, incorporating the input arguments and the value transferred in the given call. Note: the amount of value transferred *must* be at least `MIN_DEPOSIT_AMOUNT`. Each of these constants are specified in units of Gwei. +* `deposit(pubkey: bytes[48], withdrawal_credentials: bytes[32], signature: bytes[96])`: adds a deposit instance to the deposit tree, incorporating the input arguments and the value transferred in the given call. *Note*: The amount of value transferred *must* be at least `MIN_DEPOSIT_AMOUNT`. Each of these constants are specified in units of Gwei. From c94d2cf5c231c79c02dc407f3159c7148d34287f Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 11:10:59 -0500 Subject: [PATCH 04/80] Update 0_fork-choice.md --- specs/core/0_fork-choice.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/specs/core/0_fork-choice.md b/specs/core/0_fork-choice.md index 6936df55c8..dc8ebca7a4 100644 --- a/specs/core/0_fork-choice.md +++ b/specs/core/0_fork-choice.md @@ -1,12 +1,12 @@ # Ethereum 2.0 Phase 0 -- Beacon Chain Fork Choice -**NOTICE**: This document is a work in progress for researchers and implementers. +**NOTICE**: This document is a work-in-progress for researchers and implementers. -## Table of contents +## Table of Contents - [Ethereum 2.0 Phase 0 -- Beacon Chain Fork Choice](#ethereum-20-phase-0----beacon-chain-fork-choice) - - [Table of contents](#table-of-contents) + - [Table of Contents](#table-of-contents) - [Introduction](#introduction) - [Prerequisites](#prerequisites) - [Constants](#constants) @@ -18,7 +18,7 @@ ## Introduction -This document represents is the specification for the beacon chain fork choice rule, part of Ethereum 2.0 phase 0. +This document represents the specification for the beacon chain fork choice rule, part of Ethereum 2.0 Phase 0. ## Prerequisites @@ -40,17 +40,17 @@ Processing the beacon chain is similar to processing the Ethereum 1.0 chain. Cli * An Ethereum 1.0 block pointed to by the `state.latest_eth1_data.block_hash` has been processed and accepted. * The node's Unix time is greater than or equal to `state.genesis_time + block.slot * SECONDS_PER_SLOT`. -Note: Leap seconds mean that slots will occasionally last `SECONDS_PER_SLOT + 1` or `SECONDS_PER_SLOT - 1` seconds, possibly several times a year. +*Note*: Leap seconds mean that slots will occasionally last `SECONDS_PER_SLOT + 1` or `SECONDS_PER_SLOT - 1` seconds, possibly several times a year. -Note: Nodes needs to have a clock that is roughly (i.e. within `SECONDS_PER_SLOT` seconds) synchronized with the other nodes. +*Note*: Nodes needs to have a clock that is roughly (i.e., within `SECONDS_PER_SLOT` seconds) synchronized with the other nodes. ### Beacon chain fork choice rule -The beacon chain fork choice rule is a hybrid that combines justification and finality with Latest Message Driven (LMD) Greediest Heaviest Observed SubTree (GHOST). At any point in time a validator `v` subjectively calculates the beacon chain head as follows. +The beacon chain fork choice rule is a hybrid that combines justification and finality with Latest Message Driven (LMD) Greediest Heaviest Observed SubTree (GHOST). At any point in time, a validator `v` subjectively calculates the beacon chain head as follows. -* Abstractly define `Store` as the type of storage object for the chain data and `store` be the set of attestations and blocks that the validator `v` has observed and verified (in particular, block ancestors must be recursively verified). Attestations not yet included in any chain are still included in `store`. -* Let `finalized_head` be the finalized block with the highest epoch. (A block `B` is finalized if there is a descendant of `B` in `store` the processing of which sets `B` as finalized.) -* Let `justified_head` be the descendant of `finalized_head` with the highest epoch that has been justified for at least 1 epoch. (A block `B` is justified if there is a descendant of `B` in `store` the processing of which sets `B` as justified.) If no such descendant exists set `justified_head` to `finalized_head`. +* Abstractly define `Store` as the type of storage object for the chain data, and let `store` be the set of attestations and blocks that the validator `v` has observed and verified (in particular, block ancestors must be recursively verified). Attestations not yet included in any chain are still included in `store`. +* Let `finalized_head` be the finalized block with the highest epoch. (A block `B` is finalized if there is a descendant of `B` in `store`, the processing of which sets `B` as finalized.) +* Let `justified_head` be the descendant of `finalized_head` with the highest epoch that has been justified for at least 1 epoch. (A block `B` is justified if there is a descendant of `B` in `store` the processing of which sets `B` as justified.) If no such descendant exists, set `justified_head` to `finalized_head`. * Let `get_ancestor(store: Store, block: BeaconBlock, slot: Slot) -> BeaconBlock` be the ancestor of `block` with slot number `slot`. The `get_ancestor` function can be defined recursively as: ```python @@ -68,7 +68,7 @@ def get_ancestor(store: Store, block: BeaconBlock, slot: Slot) -> BeaconBlock: * Let `get_latest_attestation(store: Store, index: ValidatorIndex) -> Attestation` be the attestation with the highest slot number in `store` from the validator with the given `index`. If several such attestations exist, use the one the validator `v` observed first. * Let `get_latest_attestation_target(store: Store, index: ValidatorIndex) -> BeaconBlock` be the target block in the attestation `get_latest_attestation(store, index)`. -* Let `get_children(store: Store, block: BeaconBlock) -> List[BeaconBlock]` returns the child blocks of the given `block`. +* Let `get_children(store: Store, block: BeaconBlock) -> List[BeaconBlock]` return the child blocks of the given `block`. * Let `justified_head_state` be the resulting `BeaconState` object from processing the chain up to the `justified_head`. * The `head` is `lmd_ghost(store, justified_head_state, justified_head)` where the function `lmd_ghost` is defined below. Note that the implementation below is suboptimal; there are implementations that compute the head in time logarithmic in slot count. From 209e6c77a88951f01a0058d7fb155be465eee650 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 11:16:01 -0500 Subject: [PATCH 05/80] Update 1_custody-game.md --- specs/core/1_custody-game.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/specs/core/1_custody-game.md b/specs/core/1_custody-game.md index d565266110..f1963897a5 100644 --- a/specs/core/1_custody-game.md +++ b/specs/core/1_custody-game.md @@ -1,13 +1,13 @@ # Ethereum 2.0 Phase 1 -- Custody Game -**NOTICE**: This spec is a work-in-progress for researchers and implementers. +**NOTICE**: This document is a work-in-progress for researchers and implementers. -## Table of contents +## Table of Contents - [Ethereum 2.0 Phase 1 -- Custody Game](#ethereum-20-phase-1----custody-game) - - [Table of contents](#table-of-contents) + - [Table of Contents](#table-of-contents) - [Introduction](#introduction) - [Terminology](#terminology) - [Constants](#constants) @@ -53,22 +53,22 @@ ## Introduction -This document details the beacon chain additions and changes in Phase 1 of Ethereum 2.0 to support the shard data custody game, building upon the [phase 0](0_beacon-chain.md) specification. +This document details the beacon chain additions and changes in Phase 1 of Ethereum 2.0 to support the shard data custody game, building upon the [Phase 0](0_beacon-chain.md) specification. ## Terminology -* **Custody game**: -* **Custody period**: -* **Custody chunk**: -* **Custody chunk bit**: -* **Custody chunk challenge**: -* **Custody bit**: -* **Custody bit challenge**: -* **Custody key**: -* **Custody key reveal**: -* **Custody key mask**: -* **Custody response**: -* **Custody response deadline**: +* **Custody game** - +* **Custody period** - +* **Custody chunk** - +* **Custody chunk bit** - +* **Custody chunk challenge** - +* **Custody bit** - +* **Custody bit challenge** - +* **Custody key** - +* **Custody key reveal** - +* **Custody key mask** - +* **Custody response** - +* **Custody response deadline** - ## Constants @@ -330,7 +330,7 @@ def replace_empty_or_append(list: List[Any], new_element: Any) -> int: ### Operations -Add the following operations to the per-block processing, in order the given below and after all other operations in phase 0. +Add the following operations to the per-block processing, in the order given below and after all other operations in Phase 0. #### Custody key reveals From e67517cef0d6e10e9e3f999f712f6df60f31df00 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 11:17:49 -0500 Subject: [PATCH 06/80] Update 1_shard-data-chains.md --- specs/core/1_shard-data-chains.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specs/core/1_shard-data-chains.md b/specs/core/1_shard-data-chains.md index 33ef8632b0..5ccb8b910e 100644 --- a/specs/core/1_shard-data-chains.md +++ b/specs/core/1_shard-data-chains.md @@ -53,8 +53,8 @@ This document describes the shard data layer and the shard fork choice rule in P | Name | Value | Unit | Duration | | - | - | :-: | :-: | -| `CROSSLINK_LOOKBACK` | 2**0 (= 1) | epochs | 6.2 minutes | -| `PERSISTENT_COMMITTEE_PERIOD` | 2**11 (= 2,048) | epochs | ~9 days | +| `CROSSLINK_LOOKBACK` | `2**0` (= 1) | epochs | 6.2 minutes | +| `PERSISTENT_COMMITTEE_PERIOD` | `2**11` (= 2,048) | epochs | ~9 days | ### Signature domains @@ -363,7 +363,7 @@ Let: * `shard_blocks` be the `ShardBlock` list such that `shard_blocks[slot]` is the canonical `ShardBlock` for shard `shard` at slot `slot` * `beacon_state` be the canonical `BeaconState` * `valid_attestations` be the list of valid `Attestation`, recursively defined -* `candidate` be a candidate `Attestation` which is valid under phase 0 rules, and for which validity is to be determined under phase 1 rules by running `is_valid_beacon_attestation` +* `candidate` be a candidate `Attestation` which is valid under Phase 0 rules, and for which validity is to be determined under Phase 1 rules by running `is_valid_beacon_attestation` ```python def is_valid_beacon_attestation(shard: Shard, @@ -400,4 +400,4 @@ def is_valid_beacon_attestation(shard: Shard, ## Shard fork choice rule -The fork choice rule for any shard is LMD GHOST using the shard attestations of the persistent committee and the beacon chain attestations of the crosslink committee currently assigned to that shard, but instead of being rooted in the genesis it is rooted in the block referenced in the most recent accepted crosslink (i.e. `state.crosslinks[shard].shard_block_root`). Only blocks whose `beacon_chain_root` is the block in the main beacon chain at the specified `slot` should be considered. (If the beacon chain skips a slot, then the block at that slot is considered to be the block in the beacon chain at the highest slot lower than that slot.) +The fork choice rule for any shard is LMD GHOST using the shard attestations of the persistent committee and the beacon chain attestations of the crosslink committee currently assigned to that shard, but instead of being rooted in the genesis it is rooted in the block referenced in the most recent accepted crosslink (i.e., `state.crosslinks[shard].shard_block_root`). Only blocks whose `beacon_chain_root` is the block in the main beacon chain at the specified `slot` should be considered. (If the beacon chain skips a slot, then the block at that slot is considered to be the block in the beacon chain at the highest slot lower than that slot.) From 278f245f9149a8952e6e8c1ed971836e6c85ae7e Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 11:26:03 -0500 Subject: [PATCH 07/80] Update 0_beacon-chain-validator.md --- specs/validator/0_beacon-chain-validator.md | 60 ++++++++++----------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/specs/validator/0_beacon-chain-validator.md b/specs/validator/0_beacon-chain-validator.md index ca7f0eb3b3..c7eefb7e24 100644 --- a/specs/validator/0_beacon-chain-validator.md +++ b/specs/validator/0_beacon-chain-validator.md @@ -1,6 +1,6 @@ # Ethereum 2.0 Phase 0 -- Honest Validator -__NOTICE__: This document is a work-in-progress for researchers and implementers. This is an accompanying document to [Ethereum 2.0 Phase 0 -- The Beacon Chain](../core/0_beacon-chain.md) that describes the expected actions of a "validator" participating in the Ethereum 2.0 protocol. +**NOTICE**: This document is a work-in-progress for researchers and implementers. This is an accompanying document to [Ethereum 2.0 Phase 0 -- The Beacon Chain](../core/0_beacon-chain.md), which describes the expected actions of a "validator" participating in the Ethereum 2.0 protocol. ## Table of Contents @@ -60,7 +60,7 @@ __NOTICE__: This document is a work-in-progress for researchers and implementers ## 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 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. 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 a miner provides collateral in the form of hardware/hash-power to seek returns in exchange for building and securing the protocol. @@ -96,7 +96,7 @@ The validator constructs their `withdrawal_credentials` via the following: ### Submit deposit -In phase 0, all incoming validator deposits originate from the Ethereum 1.0 PoW chain. Deposits are made to the [deposit contract](../core/0_deposit-contract.md) located at `DEPOSIT_CONTRACT_ADDRESS`. +In Phase 0, all incoming validator deposits originate from the Ethereum 1.0 PoW chain. Deposits are made to the [deposit contract](../core/0_deposit-contract.md) located at `DEPOSIT_CONTRACT_ADDRESS`. To submit a deposit: @@ -106,11 +106,11 @@ To submit a deposit: * Let `signature` be the result of `bls_sign` of the `signing_root(deposit_data)` with `domain=DOMAIN_DEPOSIT`. * 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])` 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.validator_registry` 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`. +*Note*: Deposits made for the same `pubkey` are treated as for the same validator. A singular `Validator` will be added to `state.validator_registry` 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.0 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.0 blocks (~4 hours) plus `ETH1_DATA_VOTING_PERIOD` epochs (~1.7 hours). Once the requisite eth1.0 data is added, the deposit will normally be added to a beacon chain block and processed into the `state.validator_registry` 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 Eth 1.0 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` Eth 1.0 blocks (~4 hours) plus `ETH1_DATA_VOTING_PERIOD` epochs (~1.7 hours). Once the requisite Eth 1.0 data is added, the deposit will normally be added to a beacon chain block and processed into the `state.validator_registry` within an epoch or two. The validator is then in a queue to be activated. ### Validator index @@ -130,17 +130,17 @@ is_active = is_active_validator(validator, shuffling_epoch) Once a validator is activated, the validator is assigned [responsibilities](#beacon-chain-responsibilities) until exited. -_Note_: There is a maximum validator churn per finalized epoch so the delay until activation is variable depending upon finality, total active validator balance, and the number of validators in the queue to be activated. +*Note*: There is a maximum validator churn per finalized epoch so the delay until activation is variable depending upon finality, total active validator balance, and the number of validators in the queue to be activated. ## Beacon chain responsibilities -A validator has two primary responsibilities to the beacon chain -- [proposing blocks](block-proposal) and [creating attestations](attestations-1). Proposals happen infrequently, whereas attestations should be created once per epoch. +A validator has two primary responsibilities to the beacon chain: [proposing blocks](block-proposal) and [creating attestations](attestations-1). Proposals happen infrequently, whereas attestations should be created once per epoch. ### Block proposal A validator is expected to propose a [`BeaconBlock`](../core/0_beacon-chain.md#beaconblock) at the beginning of any slot during which `get_beacon_proposer_index(state)` returns the validator's `validator_index`. To propose, the validator selects the `BeaconBlock`, `parent`, that in their view of the fork choice is the head of the chain during `slot - 1`. The validator is to create, sign, and broadcast a `block` that is a child of `parent` and that executes a valid [beacon chain state transition](../core/0_beacon-chain.md#beacon-chain-state-transition-function). -There is one proposer per slot, so if there are N active validators any individual validator will on average be assigned to propose once per N slots (e.g. at 312500 validators = 10 million ETH, that's once per ~3 weeks). +There is one proposer per slot, so if there are N active validators any individual validator will on average be assigned to propose once per N slots (e.g., at 312500 validators = 10 million ETH, that's once per ~3 weeks). #### Block header @@ -148,7 +148,7 @@ There is one proposer per slot, so if there are N active validators any individu Set `block.slot = slot` where `slot` is the current slot at which the validator has been selected to propose. The `parent` selected must satisfy that `parent.slot < block.slot`. -_Note:_ there might be "skipped" slots between the `parent` and `block`. These skipped slots are processed in the state transition function without per-block processing. +*Note*: There might be "skipped" slots between the `parent` and `block`. These skipped slots are processed in the state transition function without per-block processing. ##### Parent root @@ -158,7 +158,7 @@ Set `block.previous_block_root = signing_root(parent)`. Set `block.state_root = hash_tree_root(state)` of the resulting `state` of the `parent -> block` state transition. -_Note_: To calculate `state_root`, the validator should first run the state transition function on an unsigned `block` containing a stub for the `state_root`. It is useful to be able to run a state transition function that does _not_ validate signatures or state root for this purpose. +*Note*: To calculate `state_root`, the validator should first run the state transition function on an unsigned `block` containing a stub for the `state_root`. It is useful to be able to run a state transition function that does _not_ validate signatures or state root for this purpose. ##### Randao reveal @@ -181,12 +181,12 @@ epoch_signature = bls_sign( `block.eth1_data` is a mechanism used by block proposers vote on a recent Ethereum 1.0 block hash and an associated deposit root found in the Ethereum 1.0 deposit contract. When consensus is formed, `state.latest_eth1_data` is updated, and validator deposits up to this root can be processed. The deposit root can be calculated by calling the `get_deposit_root()` function of the deposit contract using the post-state of the block hash. * Let `D` be the set of `Eth1DataVote` objects `vote` in `state.eth1_data_votes` where: - * `vote.eth1_data.block_hash` is the hash of an eth1.0 block that is (i) part of the canonical chain, (ii) >= `ETH1_FOLLOW_DISTANCE` blocks behind the head, and (iii) newer than `state.latest_eth1_data.block_hash`. - * `vote.eth1_data.deposit_count` is the deposit count of the eth1.0 deposit contract at the block defined by `vote.eth1_data.block_hash`. - * `vote.eth1_data.deposit_root` is the deposit root of the eth1.0 deposit contract at the block defined by `vote.eth1_data.block_hash`. + * `vote.eth1_data.block_hash` is the hash of an Eth 1.0 block that is (i) part of the canonical chain, (ii) >= `ETH1_FOLLOW_DISTANCE` blocks behind the head, and (iii) newer than `state.latest_eth1_data.block_hash`. + * `vote.eth1_data.deposit_count` is the deposit count of the Eth 1.0 deposit contract at the block defined by `vote.eth1_data.block_hash`. + * `vote.eth1_data.deposit_root` is the deposit root of the Eth 1.0 deposit contract at the block defined by `vote.eth1_data.block_hash`. * If `D` is empty: - * Let `block_hash` be the block hash of the `ETH1_FOLLOW_DISTANCE`'th ancestor of the head of the canonical eth1.0 chain. - * Let `deposit_root` and `deposit_count` be the deposit root and deposit count of the eth1.0 deposit contract in the post-state of the block referenced by `block_hash` + * Let `block_hash` be the block hash of the `ETH1_FOLLOW_DISTANCE`'th ancestor of the head of the canonical Eth 1.0 chain. + * Let `deposit_root` and `deposit_count` be the deposit root and deposit count of the Eth 1.0 deposit contract in the post-state of the block referenced by `block_hash` * Let `best_vote_data = Eth1Data(block_hash=block_hash, deposit_root=deposit_root, deposit_count=deposit_count)`. * If `D` is nonempty: * Let `best_vote_data` be the `eth1_data` of the member of `D` that has the highest `vote.vote_count`, breaking ties by favoring block hashes with higher associated block height. @@ -224,7 +224,7 @@ Up to `MAX_ATTESTATIONS` aggregate attestations can be included in the `block`. ##### Deposits -If there are any unprocessed deposits for the existing `state.latest_eth1_data` (i.e. `state.latest_eth1_data.deposit_count > state.deposit_index`), then pending deposits _must_ be added to the block. The expected number of deposits is exactly `min(MAX_DEPOSITS, latest_eth1_data.deposit_count - state.deposit_index)`. These [`deposits`](../core/0_beacon-chain.md#deposit) are constructed from the `Deposit` logs from the [Eth1.0 deposit contract](../core/0_deposit-contract) and must be processed in sequential order. The deposits included in the `block` must satisfy the verification conditions found in [deposits processing](../core/0_beacon-chain.md#deposits). +If there are any unprocessed deposits for the existing `state.latest_eth1_data` (i.e., `state.latest_eth1_data.deposit_count > state.deposit_index`), then pending deposits _must_ be added to the block. The expected number of deposits is exactly `min(MAX_DEPOSITS, latest_eth1_data.deposit_count - state.deposit_index)`. These [`deposits`](../core/0_beacon-chain.md#deposit) are constructed from the `Deposit` logs from the [Eth 1.0 deposit contract](../core/0_deposit-contract) and must be processed in sequential order. The deposits included in the `block` must satisfy the verification conditions found in [deposits processing](../core/0_beacon-chain.md#deposits). The `proof` for each deposit must be constructed against the deposit root contained in `state.latest_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 `latest_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. @@ -236,7 +236,7 @@ Up to `MAX_VOLUNTARY_EXITS` [`VoluntaryExit`](../core/0_beacon-chain.md#voluntar A validator is expected to create, sign, and broadcast an attestation during each epoch. The slot during which the validator performs this role is any slot at which `get_crosslink_committees_at_slot(state, slot)` contains a committee that contains `validator_index`. -A validator should create and broadcast the attestation halfway through the `slot` during which the validator is assigned -- that is `SECONDS_PER_SLOT * 0.5` seconds after the start of `slot`. +A validator should create and broadcast the attestation halfway through the `slot` during which the validator is assigned ― that is, `SECONDS_PER_SLOT * 0.5` seconds after the start of `slot`. #### Attestation data @@ -265,7 +265,7 @@ Set `attestation_data.source_root = head_state.current_justified_root`. Set `attestation_data.target_root = signing_root(epoch_boundary)` where `epoch_boundary` is the block at the most recent epoch boundary. -_Note:_ This can be looked up in the state using: +*Note*: This can be looked up in the state using: * Let `epoch_start_slot = get_epoch_start_slot(get_current_epoch(head_state))`. * Set `epoch_boundary = head if epoch_start_slot == head_state.slot else get_block_root(state, epoch_start_slot)`. @@ -281,7 +281,7 @@ Set `attestation_data.previous_crosslink_root = hash_tree_root(head_state.curren Set `attestation_data.crosslink_data_root = ZERO_HASH`. -_Note:_ This is a stub for phase 0. +*Note*: This is a stub for Phase 0. #### Construct attestation @@ -298,14 +298,14 @@ Set `attestation.data = attestation_data` where `attestation_data` is the `Attes * Set `aggregation_bitfield[index_into_committee // 8] |= 2 ** (index_into_committee % 8)`. * Set `attestation.aggregation_bitfield = aggregation_bitfield`. -_Note_: Calling `get_attesting_indices(state, attestation.data, attestation.aggregation_bitfield)` should return a list of length equal to 1, containing `validator_index`. +*Note*: Calling `get_attesting_indices(state, attestation.data, attestation.aggregation_bitfield)` should return a list of length equal to 1, containing `validator_index`. ##### Custody bitfield * Let `custody_bitfield` be a byte array filled with zeros of length `(len(committee) + 7) // 8`. * Set `attestation.custody_bitfield = custody_bitfield`. -_Note:_ This is a stub for phase 0. +*Note*: This is a stub for Phase 0. ##### Aggregate signature @@ -379,14 +379,14 @@ def is_proposer_at_slot(state: BeaconState, return get_beacon_proposer_index(state) == validator_index ``` -_Note_: To see if a validator is assigned to proposer during the slot, the validator must run an empty slot transition from the previous state to the current slot. +*Note*: To see if a validator is assigned to proposer during the slot, the validator must run an empty slot transition from the previous state to the current slot. ### Lookahead -The beacon chain shufflings are designed to provide a minimum of 1 epoch lookahead on the validator's upcoming committee assignments for attesting dictated by the shuffling and slot. Note that this lookahead does not apply to proposing which must checked during the slot in question. +The beacon chain shufflings are designed to provide a minimum of 1 epoch lookahead on the validator's upcoming committee assignments for attesting dictated by the shuffling and slot. Note that this lookahead does not apply to proposing, which must checked during the slot in question. -`get_committee_assignment` should be called at the start of each epoch to get the assignment for the next epoch (`current_epoch + 1`). A validator should plan for future assignments which involves noting at which future slot one will have to attest and also which shard one should begin syncing (in phase 1+). +`get_committee_assignment` should be called at the start of each epoch to get the assignment for the next epoch (`current_epoch + 1`). A validator should plan for future assignments which involves noting at which future slot one will have to attest and also which shard one should begin syncing (in Phase 1+). Specifically, a validator should call `get_committee_assignment(state, next_epoch, validator_index)` when checking for next epoch assignments. @@ -394,19 +394,19 @@ Specifically, a validator should call `get_committee_assignment(state, next_epoc "Slashing" is the burning of some amount of validator funds and immediate ejection from the active validator set. In Phase 0, there are two ways in which funds can be slashed -- [proposer slashing](#proposer-slashing) and [attester slashing](#attester-slashing). Although being slashed has serious repercussions, it is simple enough to avoid being slashed all together by remaining _consistent_ with respect to the messages a validator has previously signed. -_Note_: Signed data must be within a sequential `Fork` context to conflict. Messages cannot be slashed across diverging forks. If the previous fork version is 1 and the chain splits into fork 2 and 102, messages from 1 can slashable against messages in forks 1, 2, and 102. Messages in 2 cannot be slashable against messages in 102 and vice versa. +*Note*: Signed data must be within a sequential `Fork` context to conflict. Messages cannot be slashed across diverging forks. If the previous fork version is 1 and the chain splits into fork 2 and 102, messages from 1 can slashable against messages in forks 1, 2, and 102. Messages in 2 cannot be slashable against messages in 102 and vice versa. ### Proposer slashing To avoid "proposer slashings", a validator must not sign two conflicting [`BeaconBlock`](../core/0_beacon-chain.md#beaconblock) where conflicting is defined as two distinct blocks within the same epoch. -_In phase 0, as long as the validator does not sign two different beacon blocks for the same epoch, the validator is safe against proposer slashings._ +*In Phase 0, as long as the validator does not sign two different beacon blocks for the same epoch, the validator is safe against proposer slashings.* -Specifically, when signing an `BeaconBlock`, a validator should perform the following steps in the following order: -1. Save a record to hard disk that an beacon block has been signed for the `epoch=slot_to_epoch(block.slot)`. +Specifically, when signing a `BeaconBlock`, a validator should perform the following steps in the following order: +1. Save a record to hard disk that a beacon block has been signed for the `epoch=slot_to_epoch(block.slot)`. 2. Generate and broadcast the block. -If the software crashes at some point within this routine, then when the validator comes back online the hard disk has the record of the _potentially_ signed/broadcast block and can effectively avoid slashing. +If the software crashes at some point within this routine, then when the validator comes back online the hard disk has the record of the *potentially* signed/broadcast block and can effectively avoid slashing. ### Attester slashing @@ -416,4 +416,4 @@ Specifically, when signing an `Attestation`, a validator should perform the foll 1. Save a record to hard disk that an attestation has been signed for source -- `attestation_data.source_epoch` -- and target -- `slot_to_epoch(attestation_data.slot)`. 2. Generate and broadcast attestation. -If the software crashes at some point within this routine, then when the validator comes back online the hard disk has the record of the _potentially_ signed/broadcast attestation and can effectively avoid slashing. +If the software crashes at some point within this routine, then when the validator comes back online the hard disk has the record of the *potentially* signed/broadcast attestation and can effectively avoid slashing. From c7ba69d2e5087bd4845e884dfe67c3a6c0ad8be7 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 11:34:37 -0500 Subject: [PATCH 08/80] Update simple-serialize.md --- specs/simple-serialize.md | 53 +++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/specs/simple-serialize.md b/specs/simple-serialize.md index 0080f24471..04b0a058f8 100644 --- a/specs/simple-serialize.md +++ b/specs/simple-serialize.md @@ -1,23 +1,28 @@ # SimpleSerialize (SSZ) -This is a **work in progress** describing typing, serialization and Merkleization of Ethereum 2.0 objects. - -## Table of contents - -- [Constants](#constants) -- [Typing](#typing) - - [Basic types](#basic-types) - - [Composite types](#composite-types) - - [Aliases](#aliases) - - [Default values](#default-values) -- [Serialization](#serialization) - - [`"uintN"`](#uintn) - - [`"bool"`](#bool) - - [Containers, vectors, lists](#containers-vectors-lists) -- [Deserialization](#deserialization) -- [Merkleization](#merkleization) -- [Self-signed containers](#self-signed-containers) -- [Implementations](#implementations) +This document is a **work-in-progress** describing typing, serialization, and Merkleization of Ethereum 2.0 objects. + +## Table of Contents + + +- [SimpleSerialize (SSZ)](#simpleserialize-ssz) + - [Table of Contents](#table-of-contents) + - [Constants](#constants) + - [Typing](#typing) + - [Basic types](#basic-types) + - [Composite types](#composite-types) + - [Aliases](#aliases) + - [Default values](#default-values) + - [Serialization](#serialization) + - [`"uintN"`](#uintn) + - [`"bool"`](#bool) + - [Containers, vectors, lists](#containers-vectors-lists) + - [Deserialization](#deserialization) + - [Merkleization](#merkleization) + - [Self-signed containers](#self-signed-containers) + - [Implementations](#implementations) + + ## Constants @@ -36,11 +41,11 @@ This is a **work in progress** describing typing, serialization and Merkleizatio ### Composite types * **container**: ordered heterogeneous collection of values - * key-pair curly bracket notation `{}`, e.g. `{"foo": "uint64", "bar": "bool"}` + * key-pair curly bracket notation `{}`, e.g., `{"foo": "uint64", "bar": "bool"}` * **vector**: ordered fixed-length homogeneous collection of values - * angle bracket notation `[type, N]`, e.g. `["uint64", N]` + * angle bracket notation `[type, N]`, e.g., `["uint64", N]` * **list**: ordered variable-length homogeneous collection of values - * angle bracket notation `[type]`, e.g. `["uint64"]` + * angle bracket notation `[type]`, e.g., `["uint64"]` We recursively define "variable-size" types to be lists and all types that contains a variable-size type. All other types are said to be "fixed-size". @@ -99,7 +104,7 @@ return b"".join(fixed_parts + variable_parts) ## Deserialization -Because serialization is an injective function (i.e. two distinct objects of the same type will serialize to different values) any bytestring has at most one object it could deserialize to. Efficient algorithms for computing this object can be found in [the implementations](#implementations). +Because serialization is an injective function (i.e., two distinct objects of the same type will serialize to different values) any bytestring has at most one object it could deserialize to. Efficient algorithms for computing this object can be found in [the implementations](#implementations). ## Merkleization @@ -118,7 +123,7 @@ We now define Merkleization `hash_tree_root(value)` of an object `value` recursi ## Self-signed containers -Let `value` be a self-signed container object. The convention is that the signature (e.g. a `"bytes96"` BLS12-381 signature) be the last field of `value`. Further, the signed message for `value` is `signing_root(value) = hash_tree_root(truncate_last(value))` where `truncate_last` truncates the last element of `value`. +Let `value` be a self-signed container object. The convention is that the signature (e.g., a `"bytes96"` BLS12-381 signature) be the last field of `value`. Further, the signed message for `value` is `signing_root(value) = hash_tree_root(truncate_last(value))` where `truncate_last` truncates the last element of `value`. ## Implementations @@ -133,4 +138,4 @@ Let `value` be a self-signed container object. The convention is that the signat | Go | Prysm | Prysmatic Labs | [https://github.com/prysmaticlabs/prysm/tree/master/shared/ssz](https://github.com/prysmaticlabs/prysm/tree/master/shared/ssz) | | Swift | Yeeth | Dean Eigenmann | [https://github.com/yeeth/SimpleSerialize.swift](https://github.com/yeeth/SimpleSerialize.swift) | | C# | | Jordan Andrews | [https://github.com/codingupastorm/csharp-ssz](https://github.com/codingupastorm/csharp-ssz) | -| C++ | | | [https://github.com/NAKsir-melody/cpp_ssz](https://github.com/NAKsir-melody/cpp_ssz) | +| C++ | | Jiyun Kim | [https://github.com/NAKsir-melody/cpp_ssz](https://github.com/NAKsir-melody/cpp_ssz) | From 109799b7ec7e8188c1716f7f4589d10551323208 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 11:37:59 -0500 Subject: [PATCH 09/80] Update bls_signature.md --- specs/bls_signature.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specs/bls_signature.md b/specs/bls_signature.md index 18e2d8c9a0..4726c42c22 100644 --- a/specs/bls_signature.md +++ b/specs/bls_signature.md @@ -2,11 +2,11 @@ **Warning: This document is pending academic review and should not yet be considered secure.** -## Table of contents +## Table of Contents - [BLS signature verification](#bls-signature-verification) - - [Table of contents](#table-of-contents) + - [Table of Contents](#table-of-contents) - [Curve parameters](#curve-parameters) - [Point representations](#point-representations) - [G1 points](#g1-points) @@ -88,7 +88,7 @@ def hash_to_G2(message_hash: Bytes32, domain: uint64) -> [uint384]: `modular_squareroot(x)` returns a solution `y` to `y**2 % q == x`, and `None` if none exists. If there are two solutions, the one with higher imaginary component is favored; if both solutions have equal imaginary component, the one with higher real component is favored (note that this is equivalent to saying that the single solution with either imaginary component > p/2 or imaginary component zero and real component > p/2 is favored). -The following is a sample implementation; implementers are free to implement modular square roots as they wish. Note that `x2 = -x1` is an _additive modular inverse_ so real and imaginary coefficients remain in `[0 .. q-1]`. `coerce_to_int(element: Fq) -> int` is a function that takes Fq element `element` (i.e. integers `mod q`) and converts it to a regular integer. +The following is a sample implementation; implementers are free to implement modular square roots as they wish. Note that `x2 = -x1` is an _additive modular inverse_ so real and imaginary coefficients remain in `[0 .. q-1]`. `coerce_to_int(element: Fq) -> int` is a function that takes Fq element `element` (i.e., integers `mod q`) and converts it to a regular integer. ```python Fq2_order = q ** 2 - 1 @@ -118,7 +118,7 @@ Let `bls_aggregate_signatures(signatures: List[Bytes96]) -> Bytes96` return `sig ## Signature verification -In the following `e` is the pairing function and `g` is the G1 generator with the following coordinates (see [here](https://github.com/zkcrypto/pairing/tree/master/src/bls12_381#g1)): +In the following, `e` is the pairing function and `g` is the G1 generator with the following coordinates (see [here](https://github.com/zkcrypto/pairing/tree/master/src/bls12_381#g1)): ```python g_x = 3685416753713387016781088315183077757961620795782546409894578378688607592378376318836054947676345821548104185464507 From 79a77036f93ca8a706ba94f41cbbdc41da864f94 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 11:49:11 -0500 Subject: [PATCH 10/80] Update README.md --- specs/test_formats/README.md | 76 ++++++++++++++++++++---------------- 1 file changed, 43 insertions(+), 33 deletions(-) diff --git a/specs/test_formats/README.md b/specs/test_formats/README.md index 273659ce93..bd2f05a9ee 100644 --- a/specs/test_formats/README.md +++ b/specs/test_formats/README.md @@ -1,17 +1,27 @@ # General test format -This document defines the YAML format and structure used for ETH 2.0 testing. - -## ToC - -* [About](#about) -* [Glossary](#glossary) -* [Test format philosophy](#test-format-philosophy) -* [Test Suite](#test-suite) -* [Config](#config) -* [Fork-timeline](#fork-timeline) -* [Config sourcing](#config-sourcing) -* [Test structure](#test-structure) +This document defines the YAML format and structure used for Eth 2.0 testing. + +## Table of Contents + + +- [General test format](#general-test-format) + - [Table of Contents](#table-of-contents) + - [About](#about) + - [Test-case formats](#test-case-formats) + - [Glossary](#glossary) + - [Test format philosophy](#test-format-philosophy) + - [Config design](#config-design) + - [Fork config design](#fork-config-design) + - [Test completeness](#test-completeness) + - [Test Suite](#test-suite) + - [Config](#config) + - [Fork-timeline](#fork-timeline) + - [Config sourcing](#config-sourcing) + - [Test structure](#test-structure) + - [Note for implementers](#note-for-implementers) + + ## About @@ -52,28 +62,28 @@ Test formats: ### Config design After long discussion, the following types of configured constants were identified: -- Never changing: genesis data -- Changing, but reliant on old value: e.g. an epoch time may change, but if you want to do the conversion - `(genesis data, timestamp) -> epoch number` you end up needing both constants. +- Never changing: genesis data. +- Changing, but reliant on old value: e.g., an epoch time may change, but if you want to do the conversion + `(genesis data, timestamp) -> epoch number`, you end up needing both constants. - Changing, but kept around during fork transition: finalization may take a while, - e.g. an executable has to deal with new deposits and old deposits at the same time. Another example may be economic constants. -- Additional, back-wards compatible: new constants are introduced for later phases + e.g., an executable has to deal with new deposits and old deposits at the same time. Another example may be economic constants. +- Additional, backwards compatible: new constants are introduced for later phases. - Changing: there is a very small chance some constant may really be *replaced*. In this off-chance, it is likely better to include it as an additional variable, - and some clients may simply stop supporting the old one, if they do not want to sync from genesis. + and some clients may simply stop supporting the old one if they do not want to sync from genesis. Based on these types of changes, we model the config as a list of key value pairs, - that only grows with every fork (they may change in development versions of forks however, git manages this). -With this approach, configurations are backwards compatible (older clients ignore unknown variables), and easy to maintain. + that only grows with every fork (they may change in development versions of forks, however; git manages this). +With this approach, configurations are backwards compatible (older clients ignore unknown variables) and easy to maintain. ### Fork config design There are two types of fork-data: -1) timeline: when does a fork take place? -2) coverage: what forks are covered by a test? +1) Timeline: When does a fork take place? +2) Coverage: What forks are covered by a test? The first is neat to have as a separate form: we prevent duplication, and can run with different presets - (e.g. fork timeline for a minimal local test, for a public testnet, or for mainnet) + (e.g., fork timeline for a minimal local test, for a public testnet, or for mainnet). The second does not affect the result of the tests, it just states what is covered by the tests, so that the right suites can be executed to see coverage for a certain fork. @@ -111,11 +121,11 @@ test_cases: A configuration is a separate YAML file. Separation of configuration and tests aims to: - Prevent duplication of configuration -- Make all tests easy to upgrade (e.g. when a new config constant is introduced) +- Make all tests easy to upgrade (e.g., when a new config constant is introduced) - Clearly define which constants to use -- Shareable between clients, for cross-client short or long lived testnets +- Shareable between clients, for cross-client short- or long-lived testnets - Minimize the amounts of different constants permutations to compile as a client. - Note: Some clients prefer compile-time constants and optimizations. + *Note*: Some clients prefer compile-time constants and optimizations. They should compile for each configuration once, and run the corresponding tests per build target. The format is described in [`configs/constant_presets`](../../configs/constant_presets/README.md#format). @@ -124,9 +134,9 @@ The format is described in [`configs/constant_presets`](../../configs/constant_p ## Fork-timeline A fork timeline is (preferably) loaded in as a configuration object into a client, as opposed to the constants configuration: - - we do not allocate or optimize any code based on epoch numbers - - when we transition from one fork to the other, it is preferred to stay online. - - we may decide on an epoch number for a fork based on external events (e.g. Eth1 log event), + - We do not allocate or optimize any code based on epoch numbers. + - When we transition from one fork to the other, it is preferred to stay online. + - We may decide on an epoch number for a fork based on external events (e.g., Eth1 log event); a client should be able to activate a fork dynamically. The format is described in [`configs/fork_timelines`](../../configs/fork_timelines/README.md#format). @@ -181,18 +191,18 @@ To prevent parsing of hundreds of different YAML files to test a specific test t The basic pattern for test-suite loading and running is: -Iterate suites for given test-type, or sub-type (e.g. `operations > deposits`): +Iterate suites for given test-type, or sub-type (e.g., `operations > deposits`): 1. Filter test-suite, options: - Config: Load first few lines, load into YAML, and check `config`, either: - Pass the suite to the correct compiled target - Ignore the suite if running tests as part of a compiled target with different configuration - Load the correct configuration for the suite dynamically before running the suite - Select by file name - - Filter for specific suites (e.g. for a specific fork) + - Filter for specific suites (e.g., for a specific fork) 2. Load the YAML - - Optionally translate the data into applicable naming, e.g. `snake_case` to `PascalCase` + - Optionally translate the data into applicable naming, e.g., `snake_case` to `PascalCase` 3. Iterate through the `test_cases` -4. Ask test-runner to allocate a new test-case (i.e. objectify the test-case, generalize it with a `TestCase` interface) +4. Ask test-runner to allocate a new test-case (i.e., objectify the test-case, generalize it with a `TestCase` interface) Optionally pass raw test-case data to enable dynamic test-case allocation. 1. Load test-case data into it. 2. Make the test-case run. From 4460dc8a41ae8468d35d449d3cd4d882db30a00a Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 11:52:19 -0500 Subject: [PATCH 11/80] Update merkle_proofs.md --- specs/light_client/merkle_proofs.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/specs/light_client/merkle_proofs.md b/specs/light_client/merkle_proofs.md index b38167bb5f..c2072d7d62 100644 --- a/specs/light_client/merkle_proofs.md +++ b/specs/light_client/merkle_proofs.md @@ -1,16 +1,19 @@ +# Merkle proof formats + **NOTICE**: This document is a work-in-progress for researchers and implementers. ## Table of Contents -- [Table of Contents](#table-of-contents) -- [Constants](#constants) -- [Generalized Merkle tree index](#generalized-merkle-tree-index) -- [SSZ object to index](#ssz-object-to-index) -- [Merkle multiproofs](#merkle-multiproofs) -- [MerklePartial](#merklepartial) - - [`SSZMerklePartial`](#sszmerklepartial) - - [Proofs for execution](#proofs-for-execution) +- [Merkle proof formats](#merkle-proof-formats) + - [Table of Contents](#table-of-contents) + - [Constants](#constants) + - [Generalized Merkle tree index](#generalized-merkle-tree-index) + - [SSZ object to index](#ssz-object-to-index) + - [Merkle multiproofs](#merkle-multiproofs) + - [MerklePartial](#merklepartial) + - [`SSZMerklePartial`](#sszmerklepartial) + - [Proofs for execution](#proofs-for-execution) @@ -102,7 +105,7 @@ def get_generalized_indices(obj: Any, path: List[int], root: int=1) -> List[int] ## Merkle multiproofs -We define a Merkle multiproof as a minimal subset of nodes in a Merkle tree needed to fully authenticate that a set of nodes actually are part of a Merkle tree with some specified root, at a particular set of generalized indices. For example, here is the Merkle multiproof for positions 0, 1, 6 in an 8-node Merkle tree (i.e. generalized indices 8, 9, 14): +We define a Merkle multiproof as a minimal subset of nodes in a Merkle tree needed to fully authenticate that a set of nodes actually are part of a Merkle tree with some specified root, at a particular set of generalized indices. For example, here is the Merkle multiproof for positions 0, 1, 6 in an 8-node Merkle tree (i.e., generalized indices 8, 9, 14): ``` . From 95addd084c02724c8e6b1d2245b85beb02ef5e1b Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 11:56:14 -0500 Subject: [PATCH 12/80] Update sync_protocol.md --- specs/light_client/sync_protocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/light_client/sync_protocol.md b/specs/light_client/sync_protocol.md index 7cb1f69287..54c7289b38 100644 --- a/specs/light_client/sync_protocol.md +++ b/specs/light_client/sync_protocol.md @@ -1,6 +1,6 @@ # Beacon Chain Light Client Syncing -__NOTICE__: This document is a work-in-progress for researchers and implementers. One of the design goals of the eth2 beacon chain is light-client friendliness, both to allow low-resource clients (mobile phones, IoT, etc) to maintain access to the blockchain in a reasonably safe way, but also to facilitate the development of "bridges" between the eth2 beacon chain and other chains. +**NOTICE**: This document is a work-in-progress for researchers and implementers. One of the design goals of the Eth 2.0 beacon chain is light-client friendliness, not only to allow low-resource clients (mobile phones, IoT, etc.) to maintain access to the blockchain in a reasonably safe way, but also to facilitate the development of "bridges" between the Eth 2.0 beacon chain and other chains. ## Table of Contents @@ -27,7 +27,7 @@ __NOTICE__: This document is a work-in-progress for researchers and implementers ### Expansions -We define an "expansion" of an object as an object where a field in an object that is meant to represent the `hash_tree_root` of another object is replaced by the object. Note that defining expansions is not a consensus-layer-change; it is merely a "re-interpretation" of the object. Particularly, the `hash_tree_root` of an expansion of an object is identical to that of the original object, and we can define expansions where, given a complete history, it is always possible to compute the expansion of any object in the history. The opposite of an expansion is a "summary" (e.g. `BeaconBlockHeader` is a summary of `BeaconBlock`). +We define an "expansion" of an object as an object where a field in an object that is meant to represent the `hash_tree_root` of another object is replaced by the object. Note that defining expansions is not a consensus-layer-change; it is merely a "re-interpretation" of the object. Particularly, the `hash_tree_root` of an expansion of an object is identical to that of the original object, and we can define expansions where, given a complete history, it is always possible to compute the expansion of any object in the history. The opposite of an expansion is a "summary" (e.g., `BeaconBlockHeader` is a summary of `BeaconBlock`). We define two expansions: From d5c0a050a9d3bfdda23f7c2e6d1915854817f69a Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 11:58:36 -0500 Subject: [PATCH 13/80] Update messaging.md --- specs/networking/messaging.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/specs/networking/messaging.md b/specs/networking/messaging.md index b64e1d5d83..1f86d435bc 100644 --- a/specs/networking/messaging.md +++ b/specs/networking/messaging.md @@ -1,23 +1,22 @@ -ETH 2.0 Networking Spec - Messaging -=== +# Eth 2.0 Networking Spec - Messaging -# Abstract +## Abstract This specification describes how individual Ethereum 2.0 messages are represented on the wire. -The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL”, NOT", “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. +The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL”, NOT", “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). -# Motivation +## Motivation -This specification seeks to define a messaging protocol that is flexible enough to be changed easily as the ETH 2.0 specification evolves. +This specification seeks to define a messaging protocol that is flexible enough to be changed easily as the Eth 2.0 specification evolves. Note that while `libp2p` is the chosen networking stack for Ethereum 2.0, as of this writing some clients do not have workable `libp2p` implementations. To allow those clients to communicate, we define a message envelope that includes the body's compression, encoding, and body length. Once `libp2p` is available across all implementations, this message envelope will be removed because `libp2p` will negotiate the values defined in the envelope upfront. -# Specification +## Specification -## Message Structure +### Message Structure -An ETH 2.0 message consists of an envelope that defines the message's compression, encoding, and length followed by the body itself. +An Eth 2.0 message consists of an envelope that defines the message's compression, encoding, and length followed by the body itself. Visually, a message looks like this: @@ -35,12 +34,12 @@ Visually, a message looks like this: +--------------------------+ ``` -Clients MUST ignore messages with mal-formed bodies. The compression/encoding nibbles MUST be one of the following values: +Clients MUST ignore messages with malformed bodies. The compression/encoding nibbles MUST be one of the following values: -## Compression Nibble Values +### Compression Nibble Values - `0x0`: no compression -## Encoding Nibble Values +### Encoding Nibble Values - `0x1`: SSZ From b30da4e74f341927142fdf7408f742ac136130f5 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 11:59:50 -0500 Subject: [PATCH 14/80] Update node-identification.md --- specs/networking/node-identification.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/specs/networking/node-identification.md b/specs/networking/node-identification.md index 0f1f9832b7..e1123d8cc2 100644 --- a/specs/networking/node-identification.md +++ b/specs/networking/node-identification.md @@ -1,13 +1,12 @@ -ETH 2.0 Networking Spec - Node Identification -=== +# Eth 2.0 Networking Spec - Node Identification -# Abstract +## Abstract This specification describes how Ethereum 2.0 nodes identify and address each other on the network. -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL", NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL", NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). -# Specification +## Specification Clients use Ethereum Node Records (as described in [EIP-778](http://eips.ethereum.org/EIPS/eip-778)) to discover one another. Each ENR includes, among other things, the following keys: @@ -21,11 +20,11 @@ The keys above are enough to construct a [multiaddr](https://github.com/multifor It is RECOMMENDED that clients set their TCP port to the default of `9000`. -## Peer ID Generation +### Peer ID Generation The `libp2p` networking stack identifies peers via a "peer ID." Simply put, a node's Peer ID is the SHA2-256 `multihash` of the node's public key struct (serialized in protobuf, refer to the [Peer ID spec](https://github.com/libp2p/specs/pull/100)). `go-libp2p-crypto` contains the canonical implementation of how to hash `secp256k1` keys for use as a peer ID. -# See Also +## See Also - [multiaddr](https://github.com/multiformats/multiaddr) - [multihash](https://multiformats.io/multihash/) From 7eeb61f13953fe504e942e9707ef36eacad00028 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 12:04:37 -0500 Subject: [PATCH 15/80] Update rpc-interface.md --- specs/networking/rpc-interface.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/specs/networking/rpc-interface.md b/specs/networking/rpc-interface.md index f1da8f7e3d..338a3ca5e0 100644 --- a/specs/networking/rpc-interface.md +++ b/specs/networking/rpc-interface.md @@ -1,13 +1,12 @@ -ETH 2.0 Networking Spec - RPC Interface -=== +# Eth 2.0 Networking Spec - RPC Interface -# Abstract +## Abstract The Ethereum 2.0 networking stack uses two modes of communication: a broadcast protocol that gossips information to interested parties via GossipSub, and an RPC protocol that retrieves information from specific clients. This specification defines the RPC protocol. -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL", NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL", NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). -# Dependencies +## Dependencies This specification assumes familiarity with the [Messaging](./messaging.md), [Node Identification](./node-identification.md), and [Beacon Chain](../core/0_beacon-chain.md) specifications. @@ -26,7 +25,7 @@ Message body schemas are notated like this: Embedded types are serialized as SSZ Containers unless otherwise noted. -All referenced data structures can be found in the [0-beacon-chain](../core/0_beacon-chain.md#data-structures) specification. +All referenced data structures can be found in the [Beacon Chain](../core/0_beacon-chain.md#data-structures) specification. ## `libp2p` Protocol Names @@ -273,7 +272,7 @@ Requests the `block_bodies` associated with the provided `block_roots` from the ### Beacon Chain State -**Note:** This section is preliminary, pending the definition of the data structures to be transferred over the wire during fast sync operations. +*Note*: This section is preliminary, pending the definition of the data structures to be transferred over the wire during fast sync operations. **Method ID:** `13` From 70a1f3352293148482c09b7f50885281e3745ef7 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 12:08:37 -0500 Subject: [PATCH 16/80] Update README.md --- test_generators/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/test_generators/README.md b/test_generators/README.md index 43bf7af031..25288d42ef 100644 --- a/test_generators/README.md +++ b/test_generators/README.md @@ -2,7 +2,7 @@ This directory contains all the generators for YAML tests, consumed by Eth 2.0 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-tests](https://github.com/ethereum/eth2.0-tests). +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). Whenever a release is made, the new tests are automatically built, and [eth2TestGenBot](https://github.com/eth2TestGenBot) commits the changes to the test repository. @@ -12,7 +12,7 @@ Whenever a release is made, the new tests are automatically built, and Prerequisites: - Python 3 installed - PIP 3 -- GNU make +- GNU Make ### Cleaning @@ -66,7 +66,7 @@ eth-utils==1.4.1 The config helper and pyspec is optional, but preferred. We encourage generators to derive tests from the spec itself in order to prevent code duplication and outdated tests. Applying configurations to the spec is simple and enables you to create test suites with different contexts. -Note: make sure to run `make pyspec` from the root of the specs repository in order to build the pyspec requirement. +*Note*: Make sure to run `make pyspec` from the root of the specs repository in order to build the pyspec requirement. Install all the necessary requirements (re-run when you add more): ```bash @@ -132,9 +132,9 @@ if __name__ == "__main__": ``` Recommendations: -- You can have more than just one suite creator, e.g. ` gen_runner.run_generator("foo", [bar_test_suite, abc_test_suite, example_test_suite])`. +- You can have more than just one suite creator, e.g., ` gen_runner.run_generator("foo", [bar_test_suite, abc_test_suite, example_test_suite])`. - You can concatenate lists of test cases if you don't want to split it up in suites, however, make sure they can be run with one handler. -- You can split your suite creators into different python files/packages; this is good for code organization. +- You can split your suite creators into different Python files/packages; this is good for code organization. - Use config "minimal" for performance, but also implement a suite with the default config where necessary. - You may be able to write your test suite creator in a way where it does not make assumptions on constants. If so, you can generate test suites with different configurations for the same scenario (see example). @@ -157,8 +157,8 @@ To add a new test generator that builds `New Tests`: [circleci config file](https://github.com/ethereum/eth2.0-test-generators/blob/master/.circleci/config.yml) if desired to increase code quality. -Note: you do not have to change the makefile. -However, if necessary (e.g. not using python, or mixing in other languages), submit an issue, and it can be a special case. +*Note*: You do not have to change the makefile. +However, if necessary (e.g., not using Python, or mixing in other languages), submit an issue, and it can be a special case. Do note that generators should be easy to maintain, lean, and based on the spec. @@ -167,5 +167,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-tests`](https://github.com/ethereum/eth2.0-tests) repository by opening a PR there. +2. Remove the generated tests in the [`eth2.0-spec-tests`](https://github.com/ethereum/eth2.0-spec-tests) repository by opening a PR there. 3. Make a new release. From d7381ddaaa81bce021de89f054827a742a775cce Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 12:12:48 -0500 Subject: [PATCH 17/80] Update README.md --- test_libs/pyspec/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/test_libs/pyspec/README.md b/test_libs/pyspec/README.md index df18342100..569df538cc 100644 --- a/test_libs/pyspec/README.md +++ b/test_libs/pyspec/README.md @@ -1,11 +1,11 @@ -# ETH 2.0 PySpec +# Eth 2.0 Executable Python Spec (PySpec) -The Python executable spec is built from the ETH 2.0 specification, +The executable Python spec is built from the Eth 2.0 specification, complemented with the necessary helper functions for hashing, BLS, and more. With this executable spec, test-generators can easily create test-vectors for client implementations, - and the spec itself can be verified to be consistent and coherent, through sanity tests implemented with pytest. + and the spec itself can be verified to be consistent and coherent through sanity tests implemented with pytest. ## Building @@ -14,12 +14,12 @@ All the dynamic parts of the spec can be build at once with `make pyspec`. Alternatively, you can build a sub-set of the pyspec: `make phase0`. -Or, to build a single file, specify the path, e.g. `make test_libs/pyspec/eth2spec/phase0/spec.py` +Or, to build a single file, specify the path, e.g., `make test_libs/pyspec/eth2spec/phase0/spec.py`. ## Py-tests -After building, you can install the dependencies for running the `pyspec` tests with `make install_test` +After building, you can install the dependencies for running the `pyspec` tests with `make install_test`. These tests are not intended for client-consumption. These tests are sanity tests, to verify if the spec itself is consistent. @@ -28,7 +28,7 @@ These tests are sanity tests, to verify if the spec itself is consistent. #### Automated -Run `make test` from the root of the spec repository. +Run `make test` from the root of the specs repository. #### Manual @@ -40,7 +40,7 @@ python3 -m venv venv . venv/bin/activate pip3 install -r requirements-testing.txt ``` -Note: make sure to run `make -B pyspec` from the root of the specs repository, +*Note*: Make sure to run `make -B pyspec` from the root of the specs repository, to build the parts of the pyspec module derived from the markdown specs. The `-B` flag may be helpful to force-overwrite the `pyspec` output after you made a change to the markdown source files. @@ -58,4 +58,4 @@ The pyspec is not a replacement. ## License -Same as the spec itself, see [LICENSE](../../LICENSE) file in spec repository root. +Same as the spec itself; see [LICENSE](../../LICENSE) file in the specs repository root. From 6958d8015acf0f9a77998c195cba9c820947a1a6 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 12:17:10 -0500 Subject: [PATCH 18/80] Update README.md --- configs/constant_presets/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/configs/constant_presets/README.md b/configs/constant_presets/README.md index 45148862e7..43463e0c48 100644 --- a/configs/constant_presets/README.md +++ b/configs/constant_presets/README.md @@ -3,18 +3,18 @@ This directory contains a set of constants presets used for testing, testnets, and mainnet. A preset file contains all the constants known for its target. -Later-fork constants can be ignored, e.g. ignore phase1 constants as a client that only supports phase 0 currently. +Later-fork constants can be ignored, e.g., ignore phase1 constants as a client that only supports phase 0 currently. ## Format Each preset is a key-value mapping. **Key**: an `UPPER_SNAKE_CASE` (a.k.a. "macro case") formatted string, name of the constant. + **Value**: can be any of: - an unsigned integer number, can be up to 64 bits (incl.) - a hexadecimal string, prefixed with `0x` Presets may contain comments to describe the values. -See `mainnet.yaml` for a complete example. - +See [`mainnet.yaml`](./mainnet.yaml) for a complete example. From e8effc9e304cd2c0eeb99a28718d24442ed92400 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 12:18:14 -0500 Subject: [PATCH 19/80] Update README.md --- configs/fork_timelines/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/configs/fork_timelines/README.md b/configs/fork_timelines/README.md index c93b415f50..72ebd7d437 100644 --- a/configs/fork_timelines/README.md +++ b/configs/fork_timelines/README.md @@ -3,16 +3,17 @@ This directory contains a set of fork timelines used for testing, testnets, and mainnet. A timeline file contains all the forks known for its target. -Later forks can be ignored, e.g. ignore fork `phase1` as a client that only supports phase 0 currently. +Later forks can be ignored, e.g., ignore fork `phase1` as a client that only supports phase 0 currently. ## Format Each preset is a key-value mapping. **Key**: an `lower_snake_case` (a.k.a. "python case") formatted string, name of the fork. + **Value**: an unsigned integer number, epoch number of activation of the fork Timelines may contain comments to describe the values. -See `mainnet.yaml` for a complete example. +See [`mainnet.yaml`](./mainnet.yaml) for a complete example. From d4d03edcb097a4e46a6da144a22c513a0a94f420 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 12:19:10 -0500 Subject: [PATCH 20/80] Update README.md --- specs/test_formats/bls/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/test_formats/bls/README.md b/specs/test_formats/bls/README.md index db63bba1d3..4d95bdfd77 100644 --- a/specs/test_formats/bls/README.md +++ b/specs/test_formats/bls/README.md @@ -1,7 +1,7 @@ # BLS tests A test type for BLS. Primarily geared towards verifying the *integration* of any BLS library. -We do not recommend to roll your own crypto, or use an untested BLS library. +We do not recommend rolling your own crypto or using an untested BLS library. The BLS test suite runner has the following handlers: @@ -12,4 +12,4 @@ The BLS test suite runner has the following handlers: - [`priv_to_pub`](./priv_to_pub.md) - [`sign_msg`](./sign_msg.md) -Note: signature-verification and aggregate-verify test cases are not yet supported. +*Note*: Signature-verification and aggregate-verify test cases are not yet supported. From b24b613bef6a11f4737be3714f73febf342f00f2 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 12:21:18 -0500 Subject: [PATCH 21/80] Update README.md --- specs/test_formats/shuffling/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specs/test_formats/shuffling/README.md b/specs/test_formats/shuffling/README.md index 57be965657..25074742d5 100644 --- a/specs/test_formats/shuffling/README.md +++ b/specs/test_formats/shuffling/README.md @@ -1,16 +1,16 @@ # Test format: shuffling -The runner of the Shuffling test type has only one handler: `core` +The runner of the Shuffling test type has only one handler: `core`. -This does not mean however that testing is limited. +However, this does not mean that testing is limited. Clients may take different approaches to shuffling, for optimizing, and supporting advanced lookup behavior back in older history. For implementers, possible test runners implementing testing can include: -1) just test permute-index, run it for each index `i` in `range(count)`, and check against expected `output[i]` (default spec implementation) -2) test un-permute-index (the reverse lookup. Implemented by running the shuffling rounds in reverse: from `round_count-1` to `0`) -3) test the optimized complete shuffle, where all indices are shuffled at once, test output in one go. -4) test complete shuffle in reverse (reverse rounds, same as 2) +1) Just test permute-index, run it for each index `i` in `range(count)`, and check against expected `output[i]` (default spec implementation). +2) Test un-permute-index (the reverse lookup; implemented by running the shuffling rounds in reverse, from `round_count-1` to `0`). +3) Test the optimized complete shuffle, where all indices are shuffled at once; test output in one go. +4) Test complete shuffle in reverse (reverse rounds, same as #2). ## Test case format From 989a47ab9a8aef2be33a9a78df3cc05c235210a0 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 12:22:51 -0500 Subject: [PATCH 22/80] Update README.md --- specs/test_formats/ssz_generic/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specs/test_formats/ssz_generic/README.md b/specs/test_formats/ssz_generic/README.md index 9fda0c368d..da0898087d 100644 --- a/specs/test_formats/ssz_generic/README.md +++ b/specs/test_formats/ssz_generic/README.md @@ -3,7 +3,7 @@ This set of test-suites provides general testing for SSZ: to instantiate any container/list/vector/other type from binary data. -Since SSZ is in a development-phase, not the full suite of features is covered yet. +Since SSZ is in a development-phase, the full suite of features is not covered yet. Note that these tests are based on the older SSZ package. The tests are still relevant, but limited in scope: more complex object encodings have changed since the original SSZ testing. @@ -11,10 +11,10 @@ The tests are still relevant, but limited in scope: A minimal but useful series of tests covering `uint` encoding and decoding is provided. This is a direct port of the older SSZ `uint` tests (minus outdated test cases). -[uint test format](./uint.md). +Test format documentation can be found here: [uint test format](./uint.md). -Note: the current phase-0 spec does not use larger uints, and uses byte vectors (fixed length) instead to represent roots etc. +*Note*: The current Phase 0 spec does not use larger uints, and uses byte vectors (fixed length) instead to represent roots etc. The exact uint lengths to support may be redefined in the future. -Extension of the SSZ tests collection is planned, with an update to the new spec-maintained `minimal_ssz.py`, +Extension of the SSZ tests collection is planned, with an update to the new spec-maintained `minimal_ssz.py`; see CI/testing issues for progress tracking. From 5017662d12e3d7558ab9672a35a1dfbbd782d85b Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 12:23:15 -0500 Subject: [PATCH 23/80] Update README.md --- specs/test_formats/ssz_static/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/test_formats/ssz_static/README.md b/specs/test_formats/ssz_static/README.md index 413b00c75b..7348342ea5 100644 --- a/specs/test_formats/ssz_static/README.md +++ b/specs/test_formats/ssz_static/README.md @@ -1,8 +1,8 @@ # SSZ, static tests This set of test-suites provides static testing for SSZ: - to instantiate just the known ETH-2.0 SSZ types from binary data. + to instantiate just the known Eth 2.0 SSZ types from binary data. -This series of tests is based on the spec-maintained `minimal_ssz.py`, i.e. fully consistent with the SSZ spec. +This series of tests is based on the spec-maintained `minimal_ssz.py`, i.e., fully consistent with the SSZ spec. Test format documentation can be found here: [core test format](./core.md). From b47db35c5073866b8bbeed7a451d5e601bb3ce6b Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 12:24:09 -0500 Subject: [PATCH 24/80] Update core.md --- specs/test_formats/ssz_static/core.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/test_formats/ssz_static/core.md b/specs/test_formats/ssz_static/core.md index 1d470c3381..eae2c263c5 100644 --- a/specs/test_formats/ssz_static/core.md +++ b/specs/test_formats/ssz_static/core.md @@ -1,7 +1,7 @@ # Test format: SSZ static types The goal of this type is to provide clients with a solid reference for how the known SSZ objects should be encoded. -Each object described in the Phase-0 spec is covered. +Each object described in the Phase 0 spec is covered. This is important, as many of the clients aiming to serialize/deserialize objects directly into structs/classes do not support (or have alternatives for) generic SSZ encoding/decoding. This test-format ensures these direct serializations are covered. @@ -27,6 +27,6 @@ A test-runner can implement the following assertions: ## References -**`serialized`**: [SSZ serialization](../../simple-serialize.md#serialization) +**`serialized`** - [SSZ serialization](../../simple-serialize.md#serialization) **`root`** - [hash_tree_root](../../simple-serialize.md#merkleization) function **`signing_root`** - [signing_root](../../simple-serialize.md#self-signed-containers) function From 750ac7ce245828834a47a53033c042ff5a018d44 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:11:43 -0500 Subject: [PATCH 25/80] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4c4808059f..5f2e78ebde 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![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://github.com/ethereum/wiki/wiki/Sharding-FAQ) and the [research compendium](https://notes.ethereum.org/s/H1PGqDhpm). +To learn more about sharding and Eth 2.0, see the [sharding FAQ](https://github.com/ethereum/wiki/wiki/Sharding-FAQ) and the [research compendium](https://notes.ethereum.org/s/H1PGqDhpm). This repository hosts the current Eth 2.0 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. From 26d4f01116ef66fccc8412cb157a39024a9706ab Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:23:45 -0500 Subject: [PATCH 26/80] Update README.md --- configs/constant_presets/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/configs/constant_presets/README.md b/configs/constant_presets/README.md index 43463e0c48..61c9a3a630 100644 --- a/configs/constant_presets/README.md +++ b/configs/constant_presets/README.md @@ -3,7 +3,7 @@ This directory contains a set of constants presets used for testing, testnets, and mainnet. A preset file contains all the constants known for its target. -Later-fork constants can be ignored, e.g., ignore phase1 constants as a client that only supports phase 0 currently. +Later-fork constants can be ignored, e.g. ignore phase1 constants as a client that only supports phase 0 currently. ## Format @@ -11,7 +11,7 @@ Each preset is a key-value mapping. **Key**: an `UPPER_SNAKE_CASE` (a.k.a. "macro case") formatted string, name of the constant. -**Value**: can be any of: +**Value** can be either: - an unsigned integer number, can be up to 64 bits (incl.) - a hexadecimal string, prefixed with `0x` From d060f3a151876e9b547be2a38d70fcb56da44a91 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:24:17 -0500 Subject: [PATCH 27/80] Update README.md --- configs/fork_timelines/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configs/fork_timelines/README.md b/configs/fork_timelines/README.md index 72ebd7d437..3e23c246c5 100644 --- a/configs/fork_timelines/README.md +++ b/configs/fork_timelines/README.md @@ -3,7 +3,7 @@ This directory contains a set of fork timelines used for testing, testnets, and mainnet. A timeline file contains all the forks known for its target. -Later forks can be ignored, e.g., ignore fork `phase1` as a client that only supports phase 0 currently. +Later forks can be ignored, e.g. ignore fork `phase1` as a client that only supports phase 0 currently. ## Format From 1f66969f19b1c15fdb46634e023ab6c7581eaa3b Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:24:49 -0500 Subject: [PATCH 28/80] Update bls_signature.md --- specs/bls_signature.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/bls_signature.md b/specs/bls_signature.md index 4726c42c22..82371fe428 100644 --- a/specs/bls_signature.md +++ b/specs/bls_signature.md @@ -88,7 +88,7 @@ def hash_to_G2(message_hash: Bytes32, domain: uint64) -> [uint384]: `modular_squareroot(x)` returns a solution `y` to `y**2 % q == x`, and `None` if none exists. If there are two solutions, the one with higher imaginary component is favored; if both solutions have equal imaginary component, the one with higher real component is favored (note that this is equivalent to saying that the single solution with either imaginary component > p/2 or imaginary component zero and real component > p/2 is favored). -The following is a sample implementation; implementers are free to implement modular square roots as they wish. Note that `x2 = -x1` is an _additive modular inverse_ so real and imaginary coefficients remain in `[0 .. q-1]`. `coerce_to_int(element: Fq) -> int` is a function that takes Fq element `element` (i.e., integers `mod q`) and converts it to a regular integer. +The following is a sample implementation; implementers are free to implement modular square roots as they wish. Note that `x2 = -x1` is an _additive modular inverse_ so real and imaginary coefficients remain in `[0 .. q-1]`. `coerce_to_int(element: Fq) -> int` is a function that takes Fq element `element` (i.e. integers `mod q`) and converts it to a regular integer. ```python Fq2_order = q ** 2 - 1 From e5de2a5460e14239d8349f7f20ab810e6c542040 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:38:10 -0500 Subject: [PATCH 29/80] Update 0_beacon-chain.md --- specs/core/0_beacon-chain.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/core/0_beacon-chain.md b/specs/core/0_beacon-chain.md index d5fb104e6a..dc3dd4ae8b 100644 --- a/specs/core/0_beacon-chain.md +++ b/specs/core/0_beacon-chain.md @@ -1224,7 +1224,7 @@ Transition section notes: * The per-slot transitions focus on the slot counter. * The per-block transitions generally focus on verifying aggregate signatures and saving temporary records relating to the per-block activity in the `BeaconState`. -Beacon blocks that trigger unhandled Python exceptions (e.g., out-of-range list accesses) and failed `assert`s during the state transition are considered invalid. +Beacon blocks that trigger unhandled Python exceptions (e.g. out-of-range list accesses) and failed `assert`s during the state transition are considered invalid. *Note*: If there are skipped slots between a block and its parent block, run the steps in the [state-root](#state-caching), [per-epoch](#per-epoch-processing), and [per-slot](#per-slot-processing) sections once for each skipped slot and then once for the slot containing the new block. From d6fdf50ceee6ba8b761fd1b08551bc09c8e8398b Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:39:09 -0500 Subject: [PATCH 30/80] Update 0_deposit-contract.md --- specs/core/0_deposit-contract.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/core/0_deposit-contract.md b/specs/core/0_deposit-contract.md index adea629b85..5a0478f81b 100644 --- a/specs/core/0_deposit-contract.md +++ b/specs/core/0_deposit-contract.md @@ -1,6 +1,6 @@ # Ethereum 2.0 Phase 0 -- Deposit Contract -**NOTICE**: This document is a work-in-progress for researchers and implementers. +**Notice**: This document is a work-in-progress for researchers and implementers. ## Table of Contents @@ -44,7 +44,7 @@ This document represents the specification for the beacon chain deposit contract ## Ethereum 1.0 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 Ethereum 1.0 for deposits of ETH to the beacon chain. Validator balances will be withdrawable to the shards in Phase 2 (i.e., when the EVM 2.0 is deployed and the shards have state). +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 Ethereum 1.0 for deposits of ETH to the beacon chain. Validator balances will be withdrawable to the shards in Phase 2 (i.e. when the EVM 2.0 is deployed and the shards have state). ### Arguments @@ -57,7 +57,7 @@ One of the `DepositData` fields is `withdrawal_credentials`. It is a commitment * `withdrawal_credentials[:1] == BLS_WITHDRAWAL_PREFIX_BYTE` * `withdrawal_credentials[1:] == hash(withdrawal_pubkey)[1:]` where `withdrawal_pubkey` is a BLS pubkey -The private key corresponding to `withdrawal_pubkey` will be required to initiate a withdrawal. It can be stored separately until a withdrawal is required, e.g., in cold storage. +The private key corresponding to `withdrawal_pubkey` will be required to initiate a withdrawal. It can be stored separately until a withdrawal is required, e.g. in cold storage. #### Amount From 175658fc0e79c981664140ceb77dba8ab713151d Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:40:00 -0500 Subject: [PATCH 31/80] Update 0_fork-choice.md --- specs/core/0_fork-choice.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/core/0_fork-choice.md b/specs/core/0_fork-choice.md index dc8ebca7a4..e9171060f4 100644 --- a/specs/core/0_fork-choice.md +++ b/specs/core/0_fork-choice.md @@ -1,6 +1,6 @@ # Ethereum 2.0 Phase 0 -- Beacon Chain Fork Choice -**NOTICE**: This document is a work-in-progress for researchers and implementers. +**Notice**: This document is a work-in-progress for researchers and implementers. ## Table of Contents From 88f6f7d0528e750614fcd0fc34142a11e40a1caa Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:40:43 -0500 Subject: [PATCH 32/80] Update 0_fork-choice.md --- specs/core/0_fork-choice.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/core/0_fork-choice.md b/specs/core/0_fork-choice.md index e9171060f4..b72e8da6bd 100644 --- a/specs/core/0_fork-choice.md +++ b/specs/core/0_fork-choice.md @@ -42,7 +42,7 @@ Processing the beacon chain is similar to processing the Ethereum 1.0 chain. Cli *Note*: Leap seconds mean that slots will occasionally last `SECONDS_PER_SLOT + 1` or `SECONDS_PER_SLOT - 1` seconds, possibly several times a year. -*Note*: Nodes needs to have a clock that is roughly (i.e., within `SECONDS_PER_SLOT` seconds) synchronized with the other nodes. +*Note*: Nodes needs to have a clock that is roughly (i.e. within `SECONDS_PER_SLOT` seconds) synchronized with the other nodes. ### Beacon chain fork choice rule From d7471378d514a84d8f88e204bbe3d025137907dc Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:41:42 -0500 Subject: [PATCH 33/80] Update 1_custody-game.md --- specs/core/1_custody-game.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/specs/core/1_custody-game.md b/specs/core/1_custody-game.md index f1963897a5..093f7c2999 100644 --- a/specs/core/1_custody-game.md +++ b/specs/core/1_custody-game.md @@ -57,18 +57,18 @@ This document details the beacon chain additions and changes in Phase 1 of Ether ## Terminology -* **Custody game** - -* **Custody period** - -* **Custody chunk** - -* **Custody chunk bit** - -* **Custody chunk challenge** - -* **Custody bit** - -* **Custody bit challenge** - -* **Custody key** - -* **Custody key reveal** - -* **Custody key mask** - -* **Custody response** - -* **Custody response deadline** - +* **Custody game** — +* **Custody period** — +* **Custody chunk** — +* **Custody chunk bit** — +* **Custody chunk challenge** — +* **Custody bit** — +* **Custody bit challenge** — +* **Custody key** — +* **Custody key reveal** — +* **Custody key mask** — +* **Custody response** — +* **Custody response deadline** — ## Constants From 9b63bba5ce4ac176ccb37b07830ba66c182eeba1 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:42:26 -0500 Subject: [PATCH 34/80] Update merkle_proofs.md --- specs/light_client/merkle_proofs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/light_client/merkle_proofs.md b/specs/light_client/merkle_proofs.md index c2072d7d62..cf0864bf67 100644 --- a/specs/light_client/merkle_proofs.md +++ b/specs/light_client/merkle_proofs.md @@ -105,7 +105,7 @@ def get_generalized_indices(obj: Any, path: List[int], root: int=1) -> List[int] ## Merkle multiproofs -We define a Merkle multiproof as a minimal subset of nodes in a Merkle tree needed to fully authenticate that a set of nodes actually are part of a Merkle tree with some specified root, at a particular set of generalized indices. For example, here is the Merkle multiproof for positions 0, 1, 6 in an 8-node Merkle tree (i.e., generalized indices 8, 9, 14): +We define a Merkle multiproof as a minimal subset of nodes in a Merkle tree needed to fully authenticate that a set of nodes actually are part of a Merkle tree with some specified root, at a particular set of generalized indices. For example, here is the Merkle multiproof for positions 0, 1, 6 in an 8-node Merkle tree (i.e. generalized indices 8, 9, 14): ``` . From 130289d5e63c7b05ffa5fb4950a7280763f50f19 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:43:08 -0500 Subject: [PATCH 35/80] Update sync_protocol.md --- specs/light_client/sync_protocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/light_client/sync_protocol.md b/specs/light_client/sync_protocol.md index 54c7289b38..b679f33ef7 100644 --- a/specs/light_client/sync_protocol.md +++ b/specs/light_client/sync_protocol.md @@ -1,6 +1,6 @@ # Beacon Chain Light Client Syncing -**NOTICE**: This document is a work-in-progress for researchers and implementers. One of the design goals of the Eth 2.0 beacon chain is light-client friendliness, not only to allow low-resource clients (mobile phones, IoT, etc.) to maintain access to the blockchain in a reasonably safe way, but also to facilitate the development of "bridges" between the Eth 2.0 beacon chain and other chains. +**Notice**: This document is a work-in-progress for researchers and implementers. One of the design goals of the Eth 2.0 beacon chain is light-client friendliness, not only to allow low-resource clients (mobile phones, IoT, etc.) to maintain access to the blockchain in a reasonably safe way, but also to facilitate the development of "bridges" between the Eth 2.0 beacon chain and other chains. ## Table of Contents @@ -27,7 +27,7 @@ ### Expansions -We define an "expansion" of an object as an object where a field in an object that is meant to represent the `hash_tree_root` of another object is replaced by the object. Note that defining expansions is not a consensus-layer-change; it is merely a "re-interpretation" of the object. Particularly, the `hash_tree_root` of an expansion of an object is identical to that of the original object, and we can define expansions where, given a complete history, it is always possible to compute the expansion of any object in the history. The opposite of an expansion is a "summary" (e.g., `BeaconBlockHeader` is a summary of `BeaconBlock`). +We define an "expansion" of an object as an object where a field in an object that is meant to represent the `hash_tree_root` of another object is replaced by the object. Note that defining expansions is not a consensus-layer-change; it is merely a "re-interpretation" of the object. Particularly, the `hash_tree_root` of an expansion of an object is identical to that of the original object, and we can define expansions where, given a complete history, it is always possible to compute the expansion of any object in the history. The opposite of an expansion is a "summary" (e.g. `BeaconBlockHeader` is a summary of `BeaconBlock`). We define two expansions: From 72a6ac6ccdac3e0d09cca931746ae60afe12d34d Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:44:48 -0500 Subject: [PATCH 36/80] Update rpc-interface.md --- specs/networking/rpc-interface.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/networking/rpc-interface.md b/specs/networking/rpc-interface.md index 338a3ca5e0..f90a84cc1b 100644 --- a/specs/networking/rpc-interface.md +++ b/specs/networking/rpc-interface.md @@ -144,7 +144,7 @@ Root B ^ +---+ ``` -Once the handshake completes, the client with the higher `latest_finalized_epoch` or `best_slot` (if the clients have equal `latest_finalized_epoch`s) SHOULD request beacon block roots from its counterparty via `beacon_block_roots` (i.e., RPC method `10`). +Once the handshake completes, the client with the higher `latest_finalized_epoch` or `best_slot` (if the clients have equal `latest_finalized_epoch`s) SHOULD request beacon block roots from its counterparty via `beacon_block_roots` (i.e. RPC method `10`). ### Goodbye @@ -244,7 +244,7 @@ Requests a list of block roots and slots from the peer. The `count` parameter MU ) ``` -Requests beacon block headers from the peer starting from `(start_root, start_slot)`. The response MUST contain no more than `max_headers` headers. `skip_slots` defines the maximum number of slots to skip between blocks. For example, requesting blocks starting at slots `2` a `skip_slots` value of `1` would return the blocks at `[2, 4, 6, 8, 10]`. In cases where a slot is empty for a given slot number, the closest previous block MUST be returned. For example, if slot `4` were empty in the previous example, the returned array would contain `[2, 3, 6, 8, 10]`. If slot three were further empty, the array would contain `[2, 6, 8, 10]` - i.e., duplicate blocks MUST be collapsed. A `skip_slots` value of `0` returns all blocks. +Requests beacon block headers from the peer starting from `(start_root, start_slot)`. The response MUST contain no more than `max_headers` headers. `skip_slots` defines the maximum number of slots to skip between blocks. For example, requesting blocks starting at slots `2` a `skip_slots` value of `1` would return the blocks at `[2, 4, 6, 8, 10]`. In cases where a slot is empty for a given slot number, the closest previous block MUST be returned. For example, if slot `4` were empty in the previous example, the returned array would contain `[2, 3, 6, 8, 10]`. If slot three were further empty, the array would contain `[2, 6, 8, 10]` - i.e. duplicate blocks MUST be collapsed. A `skip_slots` value of `0` returns all blocks. The function of the `skip_slots` parameter helps facilitate light client sync - for example, in [#459](https://github.com/ethereum/eth2.0-specs/issues/459) - and allows clients to balance the peers from whom they request headers. Clients could, for instance, request every 10th block from a set of peers where each peer has a different starting block in order to populate block data. @@ -268,7 +268,7 @@ The function of the `skip_slots` parameter helps facilitate light client sync - ) ``` -Requests the `block_bodies` associated with the provided `block_roots` from the peer. Responses MUST return `block_roots` in the order provided in the request. If the receiver does not have a particular `block_root`, it must return a zero-value `block_body` (i.e., a `block_body` container with all zero fields). +Requests the `block_bodies` associated with the provided `block_roots` from the peer. Responses MUST return `block_roots` in the order provided in the request. If the receiver does not have a particular `block_root`, it must return a zero-value `block_body` (i.e. a `block_body` container with all zero fields). ### Beacon Chain State From 5f691b5e1671e2526f691c353531dbe00f7bdf30 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:46:18 -0500 Subject: [PATCH 37/80] Update simple-serialize.md --- specs/simple-serialize.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specs/simple-serialize.md b/specs/simple-serialize.md index 04b0a058f8..340bc0ec09 100644 --- a/specs/simple-serialize.md +++ b/specs/simple-serialize.md @@ -41,11 +41,11 @@ This document is a **work-in-progress** describing typing, serialization, and Me ### Composite types * **container**: ordered heterogeneous collection of values - * key-pair curly bracket notation `{}`, e.g., `{"foo": "uint64", "bar": "bool"}` + * key-pair curly bracket notation `{}`, e.g. `{"foo": "uint64", "bar": "bool"}` * **vector**: ordered fixed-length homogeneous collection of values - * angle bracket notation `[type, N]`, e.g., `["uint64", N]` + * angle bracket notation `[type, N]`, e.g. `["uint64", N]` * **list**: ordered variable-length homogeneous collection of values - * angle bracket notation `[type]`, e.g., `["uint64"]` + * angle bracket notation `[type]`, e.g. `["uint64"]` We recursively define "variable-size" types to be lists and all types that contains a variable-size type. All other types are said to be "fixed-size". @@ -104,7 +104,7 @@ return b"".join(fixed_parts + variable_parts) ## Deserialization -Because serialization is an injective function (i.e., two distinct objects of the same type will serialize to different values) any bytestring has at most one object it could deserialize to. Efficient algorithms for computing this object can be found in [the implementations](#implementations). +Because serialization is an injective function (i.e. two distinct objects of the same type will serialize to different values) any bytestring has at most one object it could deserialize to. Efficient algorithms for computing this object can be found in [the implementations](#implementations). ## Merkleization @@ -123,7 +123,7 @@ We now define Merkleization `hash_tree_root(value)` of an object `value` recursi ## Self-signed containers -Let `value` be a self-signed container object. The convention is that the signature (e.g., a `"bytes96"` BLS12-381 signature) be the last field of `value`. Further, the signed message for `value` is `signing_root(value) = hash_tree_root(truncate_last(value))` where `truncate_last` truncates the last element of `value`. +Let `value` be a self-signed container object. The convention is that the signature (e.g. a `"bytes96"` BLS12-381 signature) be the last field of `value`. Further, the signed message for `value` is `signing_root(value) = hash_tree_root(truncate_last(value))` where `truncate_last` truncates the last element of `value`. ## Implementations From 9a333ab3bb3464c69da7f92033a4582e79c229ed Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:47:21 -0500 Subject: [PATCH 38/80] Update README.md --- specs/test_formats/README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/specs/test_formats/README.md b/specs/test_formats/README.md index bd2f05a9ee..abc35b5b44 100644 --- a/specs/test_formats/README.md +++ b/specs/test_formats/README.md @@ -63,10 +63,10 @@ Test formats: After long discussion, the following types of configured constants were identified: - Never changing: genesis data. -- Changing, but reliant on old value: e.g., an epoch time may change, but if you want to do the conversion +- Changing, but reliant on old value: e.g. an epoch time may change, but if you want to do the conversion `(genesis data, timestamp) -> epoch number`, you end up needing both constants. - Changing, but kept around during fork transition: finalization may take a while, - e.g., an executable has to deal with new deposits and old deposits at the same time. Another example may be economic constants. + e.g. an executable has to deal with new deposits and old deposits at the same time. Another example may be economic constants. - Additional, backwards compatible: new constants are introduced for later phases. - Changing: there is a very small chance some constant may really be *replaced*. In this off-chance, it is likely better to include it as an additional variable, @@ -83,7 +83,7 @@ There are two types of fork-data: 2) Coverage: What forks are covered by a test? The first is neat to have as a separate form: we prevent duplication, and can run with different presets - (e.g., fork timeline for a minimal local test, for a public testnet, or for mainnet). + (e.g. fork timeline for a minimal local test, for a public testnet, or for mainnet). The second does not affect the result of the tests, it just states what is covered by the tests, so that the right suites can be executed to see coverage for a certain fork. @@ -121,7 +121,7 @@ test_cases: A configuration is a separate YAML file. Separation of configuration and tests aims to: - Prevent duplication of configuration -- Make all tests easy to upgrade (e.g., when a new config constant is introduced) +- Make all tests easy to upgrade (e.g. when a new config constant is introduced) - Clearly define which constants to use - Shareable between clients, for cross-client short- or long-lived testnets - Minimize the amounts of different constants permutations to compile as a client. @@ -136,7 +136,7 @@ The format is described in [`configs/constant_presets`](../../configs/constant_p A fork timeline is (preferably) loaded in as a configuration object into a client, as opposed to the constants configuration: - We do not allocate or optimize any code based on epoch numbers. - When we transition from one fork to the other, it is preferred to stay online. - - We may decide on an epoch number for a fork based on external events (e.g., Eth1 log event); + - We may decide on an epoch number for a fork based on external events (e.g. Eth1 log event); a client should be able to activate a fork dynamically. The format is described in [`configs/fork_timelines`](../../configs/fork_timelines/README.md#format). @@ -191,18 +191,18 @@ To prevent parsing of hundreds of different YAML files to test a specific test t The basic pattern for test-suite loading and running is: -Iterate suites for given test-type, or sub-type (e.g., `operations > deposits`): +Iterate suites for given test-type, or sub-type (e.g. `operations > deposits`): 1. Filter test-suite, options: - Config: Load first few lines, load into YAML, and check `config`, either: - Pass the suite to the correct compiled target - Ignore the suite if running tests as part of a compiled target with different configuration - Load the correct configuration for the suite dynamically before running the suite - Select by file name - - Filter for specific suites (e.g., for a specific fork) + - Filter for specific suites (e.g. for a specific fork) 2. Load the YAML - - Optionally translate the data into applicable naming, e.g., `snake_case` to `PascalCase` + - Optionally translate the data into applicable naming, e.g. `snake_case` to `PascalCase` 3. Iterate through the `test_cases` -4. Ask test-runner to allocate a new test-case (i.e., objectify the test-case, generalize it with a `TestCase` interface) +4. Ask test-runner to allocate a new test-case (i.e. objectify the test-case, generalize it with a `TestCase` interface) Optionally pass raw test-case data to enable dynamic test-case allocation. 1. Load test-case data into it. 2. Make the test-case run. From 39c68dab026ab05fb409e1eb97d11dea0578d586 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:48:05 -0500 Subject: [PATCH 39/80] Update README.md --- specs/test_formats/ssz_static/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/test_formats/ssz_static/README.md b/specs/test_formats/ssz_static/README.md index 7348342ea5..1df2cb5f66 100644 --- a/specs/test_formats/ssz_static/README.md +++ b/specs/test_formats/ssz_static/README.md @@ -3,6 +3,6 @@ This set of test-suites provides static testing for SSZ: to instantiate just the known Eth 2.0 SSZ types from binary data. -This series of tests is based on the spec-maintained `minimal_ssz.py`, i.e., fully consistent with the SSZ spec. +This series of tests is based on the spec-maintained `minimal_ssz.py`, i.e. fully consistent with the SSZ spec. Test format documentation can be found here: [core test format](./core.md). From 851ddc160a0ef8fecfba1357c323451efb33e955 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:48:57 -0500 Subject: [PATCH 40/80] Update core.md --- specs/test_formats/ssz_static/core.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/test_formats/ssz_static/core.md b/specs/test_formats/ssz_static/core.md index eae2c263c5..fd80f1b1e5 100644 --- a/specs/test_formats/ssz_static/core.md +++ b/specs/test_formats/ssz_static/core.md @@ -27,6 +27,6 @@ A test-runner can implement the following assertions: ## References -**`serialized`** - [SSZ serialization](../../simple-serialize.md#serialization) -**`root`** - [hash_tree_root](../../simple-serialize.md#merkleization) function -**`signing_root`** - [signing_root](../../simple-serialize.md#self-signed-containers) function +**`serialized`** — [SSZ serialization](../../simple-serialize.md#serialization) +**`root`** — [hash_tree_root](../../simple-serialize.md#merkleization) function +**`signing_root`** — [signing_root](../../simple-serialize.md#self-signed-containers) function From 12b8dc96647d5a8d73f7def0fd085c1b75639c73 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:49:54 -0500 Subject: [PATCH 41/80] Update 0_beacon-chain-validator.md --- specs/validator/0_beacon-chain-validator.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specs/validator/0_beacon-chain-validator.md b/specs/validator/0_beacon-chain-validator.md index c7eefb7e24..3ae2f03e1c 100644 --- a/specs/validator/0_beacon-chain-validator.md +++ b/specs/validator/0_beacon-chain-validator.md @@ -1,6 +1,6 @@ # Ethereum 2.0 Phase 0 -- Honest Validator -**NOTICE**: This document is a work-in-progress for researchers and implementers. This is an accompanying document to [Ethereum 2.0 Phase 0 -- The Beacon Chain](../core/0_beacon-chain.md), which describes the expected actions of a "validator" participating in the Ethereum 2.0 protocol. +**Notice**: This document is a work-in-progress for researchers and implementers. This is an accompanying document to [Ethereum 2.0 Phase 0 -- The Beacon Chain](../core/0_beacon-chain.md), which describes the expected actions of a "validator" participating in the Ethereum 2.0 protocol. ## Table of Contents @@ -60,7 +60,7 @@ ## 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 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. 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 a miner provides collateral in the form of hardware/hash-power to seek returns in exchange for building and securing the protocol. @@ -140,7 +140,7 @@ A validator has two primary responsibilities to the beacon chain: [proposing blo A validator is expected to propose a [`BeaconBlock`](../core/0_beacon-chain.md#beaconblock) at the beginning of any slot during which `get_beacon_proposer_index(state)` returns the validator's `validator_index`. To propose, the validator selects the `BeaconBlock`, `parent`, that in their view of the fork choice is the head of the chain during `slot - 1`. The validator is to create, sign, and broadcast a `block` that is a child of `parent` and that executes a valid [beacon chain state transition](../core/0_beacon-chain.md#beacon-chain-state-transition-function). -There is one proposer per slot, so if there are N active validators any individual validator will on average be assigned to propose once per N slots (e.g., at 312500 validators = 10 million ETH, that's once per ~3 weeks). +There is one proposer per slot, so if there are N active validators any individual validator will on average be assigned to propose once per N slots (e.g. at 312500 validators = 10 million ETH, that's once per ~3 weeks). #### Block header @@ -224,7 +224,7 @@ Up to `MAX_ATTESTATIONS` aggregate attestations can be included in the `block`. ##### Deposits -If there are any unprocessed deposits for the existing `state.latest_eth1_data` (i.e., `state.latest_eth1_data.deposit_count > state.deposit_index`), then pending deposits _must_ be added to the block. The expected number of deposits is exactly `min(MAX_DEPOSITS, latest_eth1_data.deposit_count - state.deposit_index)`. These [`deposits`](../core/0_beacon-chain.md#deposit) are constructed from the `Deposit` logs from the [Eth 1.0 deposit contract](../core/0_deposit-contract) and must be processed in sequential order. The deposits included in the `block` must satisfy the verification conditions found in [deposits processing](../core/0_beacon-chain.md#deposits). +If there are any unprocessed deposits for the existing `state.latest_eth1_data` (i.e. `state.latest_eth1_data.deposit_count > state.deposit_index`), then pending deposits _must_ be added to the block. The expected number of deposits is exactly `min(MAX_DEPOSITS, latest_eth1_data.deposit_count - state.deposit_index)`. These [`deposits`](../core/0_beacon-chain.md#deposit) are constructed from the `Deposit` logs from the [Eth 1.0 deposit contract](../core/0_deposit-contract) and must be processed in sequential order. The deposits included in the `block` must satisfy the verification conditions found in [deposits processing](../core/0_beacon-chain.md#deposits). The `proof` for each deposit must be constructed against the deposit root contained in `state.latest_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 `latest_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. From b2187987f3198e473ab012c3a6bf78d052a010bf Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:50:57 -0500 Subject: [PATCH 42/80] Update README.md --- test_generators/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test_generators/README.md b/test_generators/README.md index 25288d42ef..073219abe9 100644 --- a/test_generators/README.md +++ b/test_generators/README.md @@ -132,7 +132,7 @@ if __name__ == "__main__": ``` Recommendations: -- You can have more than just one suite creator, e.g., ` gen_runner.run_generator("foo", [bar_test_suite, abc_test_suite, example_test_suite])`. +- You can have more than just one suite creator, e.g. ` gen_runner.run_generator("foo", [bar_test_suite, abc_test_suite, example_test_suite])`. - You can concatenate lists of test cases if you don't want to split it up in suites, however, make sure they can be run with one handler. - You can split your suite creators into different Python files/packages; this is good for code organization. - Use config "minimal" for performance, but also implement a suite with the default config where necessary. @@ -158,7 +158,7 @@ To add a new test generator that builds `New Tests`: if desired to increase code quality. *Note*: You do not have to change the makefile. -However, if necessary (e.g., not using Python, or mixing in other languages), submit an issue, and it can be a special case. +However, if necessary (e.g. not using Python, or mixing in other languages), submit an issue, and it can be a special case. Do note that generators should be easy to maintain, lean, and based on the spec. From 29edd806d3fa4e46ffa700889611270a918ca046 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:51:37 -0500 Subject: [PATCH 43/80] Update README.md --- test_libs/pyspec/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test_libs/pyspec/README.md b/test_libs/pyspec/README.md index 569df538cc..bb6991a930 100644 --- a/test_libs/pyspec/README.md +++ b/test_libs/pyspec/README.md @@ -14,7 +14,7 @@ All the dynamic parts of the spec can be build at once with `make pyspec`. Alternatively, you can build a sub-set of the pyspec: `make phase0`. -Or, to build a single file, specify the path, e.g., `make test_libs/pyspec/eth2spec/phase0/spec.py`. +Or, to build a single file, specify the path, e.g. `make test_libs/pyspec/eth2spec/phase0/spec.py`. ## Py-tests From 9e56396a9bb1559ff99e9f995ffeecc1c0c90be2 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:52:36 -0500 Subject: [PATCH 44/80] Update 1_shard-data-chains.md --- specs/core/1_shard-data-chains.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/core/1_shard-data-chains.md b/specs/core/1_shard-data-chains.md index 5ccb8b910e..4db3db12a9 100644 --- a/specs/core/1_shard-data-chains.md +++ b/specs/core/1_shard-data-chains.md @@ -1,6 +1,6 @@ # Ethereum 2.0 Phase 1 -- Shard Data Chains -**NOTICE**: This document is a work-in-progress for researchers and implementers. +**Notice**: This document is a work-in-progress for researchers and implementers. ## Table of Contents @@ -400,4 +400,4 @@ def is_valid_beacon_attestation(shard: Shard, ## Shard fork choice rule -The fork choice rule for any shard is LMD GHOST using the shard attestations of the persistent committee and the beacon chain attestations of the crosslink committee currently assigned to that shard, but instead of being rooted in the genesis it is rooted in the block referenced in the most recent accepted crosslink (i.e., `state.crosslinks[shard].shard_block_root`). Only blocks whose `beacon_chain_root` is the block in the main beacon chain at the specified `slot` should be considered. (If the beacon chain skips a slot, then the block at that slot is considered to be the block in the beacon chain at the highest slot lower than that slot.) +The fork choice rule for any shard is LMD GHOST using the shard attestations of the persistent committee and the beacon chain attestations of the crosslink committee currently assigned to that shard, but instead of being rooted in the genesis it is rooted in the block referenced in the most recent accepted crosslink (i.e. `state.crosslinks[shard].shard_block_root`). Only blocks whose `beacon_chain_root` is the block in the main beacon chain at the specified `slot` should be considered. (If the beacon chain skips a slot, then the block at that slot is considered to be the block in the beacon chain at the highest slot lower than that slot.) From e38c04e269e4f0c5013db7c26c97bf114309110e Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:55:54 -0500 Subject: [PATCH 45/80] Update 0_beacon-chain.md --- specs/core/0_beacon-chain.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/specs/core/0_beacon-chain.md b/specs/core/0_beacon-chain.md index dc3dd4ae8b..6e8cf74313 100644 --- a/specs/core/0_beacon-chain.md +++ b/specs/core/0_beacon-chain.md @@ -134,20 +134,20 @@ Code snippets appearing in `this style` are to be interpreted as Python code. ## Terminology -* **Validator** - a registered participant in the beacon chain. You can become one by sending ether into the Ethereum 1.0 deposit contract. -* **Active validator** - an active participant in the Ethereum 2.0 consensus invited to, among other things, propose and attest to blocks and vote for crosslinks. -* **Committee** - a (pseudo-) randomly sampled subset of [active validators](#dfn-active-validator). When a committee is referred to collectively, as in "this committee attests to X", this is assumed to mean "some subset of that committee that contains enough [validators](#dfn-validator) that the protocol recognizes it as representing the committee". -* **Proposer** - the [validator](#dfn-validator) that creates a beacon chain block. -* **Attester** - a [validator](#dfn-validator) that is part of a committee that needs to sign off on a beacon chain block while simultaneously creating a link (crosslink) to a recent shard block on a particular shard chain. -* **Beacon chain** - the central PoS chain that is the base of the sharding system. -* **Shard chain** - one of the chains on which user transactions take place and account data is stored. -* **Block root** - a 32-byte Merkle root of a beacon chain block or shard chain block. Previously called "block hash". -* **Crosslink** - a set of signatures from a committee attesting to a block in a shard chain that can be included into the beacon chain. Crosslinks are the main means by which the beacon chain "learns about" the updated state of shard chains. -* **Slot** - a period during which one proposer has the ability to create a beacon chain block and some attesters have the ability to make attestations. -* **Epoch** - an aligned span of slots during which all [validators](#dfn-validator) get exactly one chance to make an attestation. -* **Finalized**, **justified** - see the [Casper FFG paper](https://arxiv.org/abs/1710.09437). -* **Withdrawal period** - the number of slots between a [validator](#dfn-validator) exit and the [validator](#dfn-validator) balance being withdrawable. -* **Genesis time** - the Unix time of the genesis beacon chain block at slot 0. +* **Validator** — a registered participant in the beacon chain. You can become one by sending ether into the Ethereum 1.0 deposit contract. +* **Active validator** — an active participant in the Ethereum 2.0 consensus invited to, among other things, propose and attest to blocks and vote for crosslinks. +* **Committee** — a (pseudo-) randomly sampled subset of [active validators](#dfn-active-validator). When a committee is referred to collectively, as in "this committee attests to X", this is assumed to mean "some subset of that committee that contains enough [validators](#dfn-validator) that the protocol recognizes it as representing the committee". +* **Proposer** — the [validator](#dfn-validator) that creates a beacon chain block. +* **Attester** — a [validator](#dfn-validator) that is part of a committee that needs to sign off on a beacon chain block while simultaneously creating a link (crosslink) to a recent shard block on a particular shard chain. +* **Beacon chain** — the central PoS chain that is the base of the sharding system. +* **Shard chain** — one of the chains on which user transactions take place and account data is stored. +* **Block root** — a 32-byte Merkle root of a beacon chain block or shard chain block. Previously called "block hash". +* **Crosslink** — a set of signatures from a committee attesting to a block in a shard chain that can be included into the beacon chain. Crosslinks are the main means by which the beacon chain "learns about" the updated state of shard chains. +* **Slot** — a period during which one proposer has the ability to create a beacon chain block and some attesters have the ability to make attestations. +* **Epoch** — an aligned span of slots during which all [validators](#dfn-validator) get exactly one chance to make an attestation. +* **Finalized**, **justified** — see the [Casper FFG paper](https://arxiv.org/abs/1710.09437). +* **Withdrawal period** — the number of slots between a [validator](#dfn-validator) exit and the [validator](#dfn-validator) balance being withdrawable. +* **Genesis time** — the Unix time of the genesis beacon chain block at slot 0. ## Constants From 54381acaee3ee2c3a3b4bca00e4a50aa1b10df04 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 15:57:23 -0500 Subject: [PATCH 46/80] Update 0_beacon-chain.md --- specs/core/0_beacon-chain.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/core/0_beacon-chain.md b/specs/core/0_beacon-chain.md index 6e8cf74313..f0813fb279 100644 --- a/specs/core/0_beacon-chain.md +++ b/specs/core/0_beacon-chain.md @@ -1,6 +1,6 @@ # Ethereum 2.0 Phase 0 -- The Beacon Chain -**NOTICE**: This document is a work-in-progress for researchers and implementers. +**Notice**: This document is a work-in-progress for researchers and implementers. ## Table of Contents From b34ecb44d091ed84e9351cae8028e7c36083428c Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:00:28 -0500 Subject: [PATCH 47/80] Update rpc-interface.md --- specs/networking/rpc-interface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/networking/rpc-interface.md b/specs/networking/rpc-interface.md index f90a84cc1b..dc9129d886 100644 --- a/specs/networking/rpc-interface.md +++ b/specs/networking/rpc-interface.md @@ -244,7 +244,7 @@ Requests a list of block roots and slots from the peer. The `count` parameter MU ) ``` -Requests beacon block headers from the peer starting from `(start_root, start_slot)`. The response MUST contain no more than `max_headers` headers. `skip_slots` defines the maximum number of slots to skip between blocks. For example, requesting blocks starting at slots `2` a `skip_slots` value of `1` would return the blocks at `[2, 4, 6, 8, 10]`. In cases where a slot is empty for a given slot number, the closest previous block MUST be returned. For example, if slot `4` were empty in the previous example, the returned array would contain `[2, 3, 6, 8, 10]`. If slot three were further empty, the array would contain `[2, 6, 8, 10]` - i.e. duplicate blocks MUST be collapsed. A `skip_slots` value of `0` returns all blocks. +Requests beacon block headers from the peer starting from `(start_root, start_slot)`. The response MUST contain no more than `max_headers` headers. `skip_slots` defines the maximum number of slots to skip between blocks. For example, requesting blocks starting at slots `2` a `skip_slots` value of `1` would return the blocks at `[2, 4, 6, 8, 10]`. In cases where a slot is empty for a given slot number, the closest previous block MUST be returned. For example, if slot `4` were empty in the previous example, the returned array would contain `[2, 3, 6, 8, 10]`. If slot three were further empty, the array would contain `[2, 6, 8, 10]` — i.e. duplicate blocks MUST be collapsed. A `skip_slots` value of `0` returns all blocks. The function of the `skip_slots` parameter helps facilitate light client sync - for example, in [#459](https://github.com/ethereum/eth2.0-specs/issues/459) - and allows clients to balance the peers from whom they request headers. Clients could, for instance, request every 10th block from a set of peers where each peer has a different starting block in order to populate block data. From e62725f518f6348f89d3ba29c18f0f7b4bbcd991 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:02:21 -0500 Subject: [PATCH 48/80] Update README.md --- test_generators/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test_generators/README.md b/test_generators/README.md index 073219abe9..f8124f9a78 100644 --- a/test_generators/README.md +++ b/test_generators/README.md @@ -167,5 +167,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 PR there. +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. 3. Make a new release. From be1440dda11d6663f1ff9369b4e89124f9920522 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:03:52 -0500 Subject: [PATCH 49/80] Update 1_custody-game.md --- specs/core/1_custody-game.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/core/1_custody-game.md b/specs/core/1_custody-game.md index 093f7c2999..2c1810c37e 100644 --- a/specs/core/1_custody-game.md +++ b/specs/core/1_custody-game.md @@ -1,6 +1,6 @@ # Ethereum 2.0 Phase 1 -- Custody Game -**NOTICE**: This document is a work-in-progress for researchers and implementers. +**Notice**: This document is a work-in-progress for researchers and implementers. ## Table of Contents From 77bc139a49dd276377087c7583df3dd6c15473cb Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:08:55 -0500 Subject: [PATCH 50/80] Update simple-serialize.md --- specs/simple-serialize.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/simple-serialize.md b/specs/simple-serialize.md index 340bc0ec09..c8cfa498ff 100644 --- a/specs/simple-serialize.md +++ b/specs/simple-serialize.md @@ -1,6 +1,6 @@ # SimpleSerialize (SSZ) -This document is a **work-in-progress** describing typing, serialization, and Merkleization of Ethereum 2.0 objects. +**Notice**: This document is a work-in-progress describing typing, serialization, and Merkleization of Ethereum 2.0 objects. ## Table of Contents From 1197dac51b1e49892da880a5b594098dac9ce88b Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:09:34 -0500 Subject: [PATCH 51/80] Update simple-serialize.md --- specs/simple-serialize.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/simple-serialize.md b/specs/simple-serialize.md index c8cfa498ff..4a3600a9f9 100644 --- a/specs/simple-serialize.md +++ b/specs/simple-serialize.md @@ -1,6 +1,6 @@ # SimpleSerialize (SSZ) -**Notice**: This document is a work-in-progress describing typing, serialization, and Merkleization of Ethereum 2.0 objects. +**Notice**: This document is a work-in-progress describing typing, serialization, and Merkleization of Eth 2.0 objects. ## Table of Contents From 7f292959ea8ea54e62bac4f2ba0bdf2c4e77de43 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:10:15 -0500 Subject: [PATCH 52/80] Update merkle_proofs.md --- specs/light_client/merkle_proofs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/light_client/merkle_proofs.md b/specs/light_client/merkle_proofs.md index cf0864bf67..3a90ed6ab2 100644 --- a/specs/light_client/merkle_proofs.md +++ b/specs/light_client/merkle_proofs.md @@ -1,6 +1,6 @@ # Merkle proof formats -**NOTICE**: This document is a work-in-progress for researchers and implementers. +**Notice**: This document is a work-in-progress for researchers and implementers. ## Table of Contents From 29a4f27601195c31364e87834d5ec0db0f5e98ce Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:14:10 -0500 Subject: [PATCH 53/80] Update 1_custody-game.md --- specs/core/1_custody-game.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/core/1_custody-game.md b/specs/core/1_custody-game.md index 2c1810c37e..9bc60a94a4 100644 --- a/specs/core/1_custody-game.md +++ b/specs/core/1_custody-game.md @@ -220,7 +220,7 @@ Add the following fields to the end of the specified container objects. Fields w #### `Validator` ```python - # next_custody_reveal_period is initialised to the custody period + # next_custody_reveal_period is initialized to the custody period # (of the particular validator) in which the validator is activated # = get_validators_custody_reveal_period(...) 'next_custody_reveal_period': 'uint64', From 95bf2be337009cee78781ce8d99d245ea54ca1da Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:15:16 -0500 Subject: [PATCH 54/80] Update rpc-interface.md --- specs/networking/rpc-interface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/networking/rpc-interface.md b/specs/networking/rpc-interface.md index dc9129d886..ec1bf21940 100644 --- a/specs/networking/rpc-interface.md +++ b/specs/networking/rpc-interface.md @@ -29,7 +29,7 @@ All referenced data structures can be found in the [Beacon Chain](../core/0_beac ## `libp2p` Protocol Names -A "Protocol ID" in `libp2p` parlance refers to a human-readable identifier `libp2p` uses in order to identify sub-protocols and stream messages of different types over the same connection. Peers exchange supported protocol IDs via the `Identify` protocol upon connection. When opening a new stream, peers pin a particular protocol ID to it, and the stream remains contextualised thereafter. Since messages are sent inside a stream, they do not need to bear the protocol ID. +A "Protocol ID" in `libp2p` parlance refers to a human-readable identifier `libp2p` uses in order to identify sub-protocols and stream messages of different types over the same connection. Peers exchange supported protocol IDs via the `Identify` protocol upon connection. When opening a new stream, peers pin a particular protocol ID to it, and the stream remains contextualized thereafter. Since messages are sent inside a stream, they do not need to bear the protocol ID. ## RPC-Over-`libp2p` From 6c8665c7673ec0cd61d62cc6b94e114c7fb2876a Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:25:05 -0500 Subject: [PATCH 55/80] Update 0_beacon-chain.md --- specs/core/0_beacon-chain.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/core/0_beacon-chain.md b/specs/core/0_beacon-chain.md index f0813fb279..d95771b14b 100644 --- a/specs/core/0_beacon-chain.md +++ b/specs/core/0_beacon-chain.md @@ -45,7 +45,7 @@ - [`BeaconBlock`](#beaconblock) - [Beacon state](#beacon-state) - [`BeaconState`](#beaconstate) - - [Custom Types](#custom-types) + - [Custom types](#custom-types) - [Helper functions](#helper-functions) - [`xor`](#xor) - [`hash`](#hash) @@ -587,7 +587,7 @@ The types are defined topologically to aid in facilitating an executable version } ``` -## Custom Types +## Custom types We define the following Python custom types for type hinting and readability: From 7ce653c9037b637884cfbaa1150ac2435647b7f7 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:27:05 -0500 Subject: [PATCH 56/80] Update 1_custody-game.md --- specs/core/1_custody-game.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/core/1_custody-game.md b/specs/core/1_custody-game.md index 9bc60a94a4..581b734de2 100644 --- a/specs/core/1_custody-game.md +++ b/specs/core/1_custody-game.md @@ -23,7 +23,7 @@ - [`CustodyChunkChallengeRecord`](#custodychunkchallengerecord) - [`CustodyBitChallengeRecord`](#custodybitchallengerecord) - [`CustodyResponse`](#custodyresponse) - - [New Beacon operations](#new-beacon-operations) + - [New beacon operations](#new-beacon-operations) - [`CustodyKeyReveal`](#custodykeyreveal) - [`EarlyDerivedSecretReveal`](#earlyderivedsecretreveal) - [Phase 0 container updates](#phase-0-container-updates) @@ -181,7 +181,7 @@ This document details the beacon chain additions and changes in Phase 1 of Ether } ``` -### New Beacon operations +### New beacon operations #### `CustodyKeyReveal` From f17a80ac1cdc2cc5f6c9c5b319d3a87ae1561b3a Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:30:27 -0500 Subject: [PATCH 57/80] Update README.md --- specs/test_formats/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/test_formats/README.md b/specs/test_formats/README.md index abc35b5b44..4708ea6509 100644 --- a/specs/test_formats/README.md +++ b/specs/test_formats/README.md @@ -14,7 +14,7 @@ This document defines the YAML format and structure used for Eth 2.0 testing. - [Config design](#config-design) - [Fork config design](#fork-config-design) - [Test completeness](#test-completeness) - - [Test Suite](#test-suite) + - [Test suite](#test-suite) - [Config](#config) - [Fork-timeline](#fork-timeline) - [Config sourcing](#config-sourcing) @@ -100,7 +100,7 @@ The aim is to provide clients with a well-defined scope of work to run a particu - Clients that are not complete in functionality can choose to ignore suites that use certain test-runners, or specific handlers of these test-runners. - Clients that are on older versions can test their work based on older releases of the generated tests, and catch up with newer releases when possible. -## Test Suite +## Test suite ``` title: -- Display name for the test suite From b498aeb0c908a9ed48a9d37f5c59fe74b9f3f176 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:32:19 -0500 Subject: [PATCH 58/80] Update messaging.md --- specs/networking/messaging.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/networking/messaging.md b/specs/networking/messaging.md index 1f86d435bc..d7cb5bb5bb 100644 --- a/specs/networking/messaging.md +++ b/specs/networking/messaging.md @@ -14,7 +14,7 @@ Note that while `libp2p` is the chosen networking stack for Ethereum 2.0, as of ## Specification -### Message Structure +### Message structure An Eth 2.0 message consists of an envelope that defines the message's compression, encoding, and length followed by the body itself. @@ -36,10 +36,10 @@ Visually, a message looks like this: Clients MUST ignore messages with malformed bodies. The compression/encoding nibbles MUST be one of the following values: -### Compression Nibble Values +### Compression nibble values - `0x0`: no compression -### Encoding Nibble Values +### Encoding nibble values - `0x1`: SSZ From c484a443ba528409da940e7929d885f655d851e1 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:33:31 -0500 Subject: [PATCH 59/80] Update node-identification.md --- specs/networking/node-identification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/networking/node-identification.md b/specs/networking/node-identification.md index e1123d8cc2..32ec4dfad1 100644 --- a/specs/networking/node-identification.md +++ b/specs/networking/node-identification.md @@ -20,11 +20,11 @@ The keys above are enough to construct a [multiaddr](https://github.com/multifor It is RECOMMENDED that clients set their TCP port to the default of `9000`. -### Peer ID Generation +### Peer ID generation The `libp2p` networking stack identifies peers via a "peer ID." Simply put, a node's Peer ID is the SHA2-256 `multihash` of the node's public key struct (serialized in protobuf, refer to the [Peer ID spec](https://github.com/libp2p/specs/pull/100)). `go-libp2p-crypto` contains the canonical implementation of how to hash `secp256k1` keys for use as a peer ID. -## See Also +## See also - [multiaddr](https://github.com/multiformats/multiaddr) - [multihash](https://multiformats.io/multihash/) From 6fbaebae0a379724dc154903081b5fc595bcad6b Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:35:35 -0500 Subject: [PATCH 60/80] Update rpc-interface.md --- specs/networking/rpc-interface.md | 38 +++++++++++++++---------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/specs/networking/rpc-interface.md b/specs/networking/rpc-interface.md index ec1bf21940..fc0eb9ecda 100644 --- a/specs/networking/rpc-interface.md +++ b/specs/networking/rpc-interface.md @@ -12,7 +12,7 @@ This specification assumes familiarity with the [Messaging](./messaging.md), [No # Specification -## Message Schemas +## Message schemas Message body schemas are notated like this: @@ -27,11 +27,11 @@ Embedded types are serialized as SSZ Containers unless otherwise noted. All referenced data structures can be found in the [Beacon Chain](../core/0_beacon-chain.md#data-structures) specification. -## `libp2p` Protocol Names +## `libp2p` protocol names A "Protocol ID" in `libp2p` parlance refers to a human-readable identifier `libp2p` uses in order to identify sub-protocols and stream messages of different types over the same connection. Peers exchange supported protocol IDs via the `Identify` protocol upon connection. When opening a new stream, peers pin a particular protocol ID to it, and the stream remains contextualized thereafter. Since messages are sent inside a stream, they do not need to bear the protocol ID. -## RPC-Over-`libp2p` +## RPC-over-`libp2p` To facilitate RPC-over-`libp2p`, a single protocol name is used: `/eth/serenity/beacon/rpc/1`. The version number in the protocol name is neither backwards or forwards compatible, and will be incremented whenever changes to the below structures are required. @@ -87,7 +87,7 @@ The first 1,000 values in `response_code` are reserved for system use. The follo 3. `30`: Method not found. 4. `40`: Server error. -### Alternative for Non-`libp2p` Clients +### Alternative for non-`libp2p` clients Since some clients are waiting for `libp2p` implementations in their respective languages. As such, they MAY listen for raw TCP messages on port `9000`. To distinguish RPC messages from other messages on that port, a byte prefix of `ETH` (`0x455448`) MUST be prepended to all messages. This option will be removed once `libp2p` is ready in all supported languages. @@ -166,11 +166,11 @@ Client MAY send `goodbye` messages upon disconnection. The reason field MAY be o Clients MAY define custom goodbye reasons as long as the value is larger than `1000`. -### Get Status +### Get status **Method ID:** `2` -**Request Body:** +**Request body:** ``` ( @@ -180,7 +180,7 @@ Clients MAY define custom goodbye reasons as long as the value is larger than `1 ) ``` -**Response Body:** +**Response body:** ``` ( @@ -192,11 +192,11 @@ Clients MAY define custom goodbye reasons as long as the value is larger than `1 Returns metadata about the remote node. -### Request Beacon Block Roots +### Request beacon block roots **Method ID:** `10` -**Request Body** +**Request body** ``` ( @@ -205,7 +205,7 @@ Returns metadata about the remote node. ) ``` -**Response Body:** +**Response body:** ``` # BlockRootSlot @@ -221,11 +221,11 @@ Returns metadata about the remote node. Requests a list of block roots and slots from the peer. The `count` parameter MUST be less than or equal to `32768`. The slots MUST be returned in ascending slot order. -### Beacon Block Headers +### Beacon block headers **Method ID:** `11` -**Request Body** +**Request body** ``` ( @@ -236,7 +236,7 @@ Requests a list of block roots and slots from the peer. The `count` parameter MU ) ``` -**Response Body:** +**Response body:** ``` ( @@ -248,11 +248,11 @@ Requests beacon block headers from the peer starting from `(start_root, start_sl The function of the `skip_slots` parameter helps facilitate light client sync - for example, in [#459](https://github.com/ethereum/eth2.0-specs/issues/459) - and allows clients to balance the peers from whom they request headers. Clients could, for instance, request every 10th block from a set of peers where each peer has a different starting block in order to populate block data. -### Beacon Block Bodies +### Beacon block bodies **Method ID:** `12` -**Request Body:** +**Request body:** ``` ( @@ -260,7 +260,7 @@ The function of the `skip_slots` parameter helps facilitate light client sync - ) ``` -**Response Body:** +**Response body:** ``` ( @@ -270,13 +270,13 @@ The function of the `skip_slots` parameter helps facilitate light client sync - Requests the `block_bodies` associated with the provided `block_roots` from the peer. Responses MUST return `block_roots` in the order provided in the request. If the receiver does not have a particular `block_root`, it must return a zero-value `block_body` (i.e. a `block_body` container with all zero fields). -### Beacon Chain State +### Beacon chain state *Note*: This section is preliminary, pending the definition of the data structures to be transferred over the wire during fast sync operations. **Method ID:** `13` -**Request Body:** +**Request body:** ``` ( @@ -284,7 +284,7 @@ Requests the `block_bodies` associated with the provided `block_roots` from the ) ``` -**Response Body:** TBD +**Response body:** TBD Requests contain the hashes of Merkle tree nodes that when merkleized yield the block's `state_root`. From 0a39ef3c13458459bbd3d1a3f7961a755310ac01 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:40:31 -0500 Subject: [PATCH 61/80] Update 0_beacon-chain.md --- specs/core/0_beacon-chain.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/core/0_beacon-chain.md b/specs/core/0_beacon-chain.md index d95771b14b..c14e389262 100644 --- a/specs/core/0_beacon-chain.md +++ b/specs/core/0_beacon-chain.md @@ -2,11 +2,11 @@ **Notice**: This document is a work-in-progress for researchers and implementers. -## Table of Contents +## Table of contents - [Ethereum 2.0 Phase 0 -- The Beacon Chain](#ethereum-20-phase-0----the-beacon-chain) - - [Table of Contents](#table-of-contents) + - [Table of contents](#table-of-contents) - [Introduction](#introduction) - [Notation](#notation) - [Terminology](#terminology) From 0dcdbba88e0c4974de77b05916e872989a5143d4 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:41:35 -0500 Subject: [PATCH 62/80] Update 0_deposit-contract.md --- specs/core/0_deposit-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/core/0_deposit-contract.md b/specs/core/0_deposit-contract.md index 5a0478f81b..917adaecb1 100644 --- a/specs/core/0_deposit-contract.md +++ b/specs/core/0_deposit-contract.md @@ -2,11 +2,11 @@ **Notice**: This document is a work-in-progress for researchers and implementers. -## Table of Contents +## Table of contents - [Ethereum 2.0 Phase 0 -- Deposit Contract](#ethereum-20-phase-0----deposit-contract) - - [Table of Contents](#table-of-contents) + - [Table of contents](#table-of-contents) - [Introduction](#introduction) - [Constants](#constants) - [Gwei values](#gwei-values) From 3196cf027c85889ff6ccb368ab505d622d0ead4d Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:41:41 -0500 Subject: [PATCH 63/80] Update 1_custody-game.md --- specs/core/1_custody-game.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/core/1_custody-game.md b/specs/core/1_custody-game.md index 581b734de2..7c079c093c 100644 --- a/specs/core/1_custody-game.md +++ b/specs/core/1_custody-game.md @@ -2,12 +2,12 @@ **Notice**: This document is a work-in-progress for researchers and implementers. -## Table of Contents +## Table of contents - [Ethereum 2.0 Phase 1 -- Custody Game](#ethereum-20-phase-1----custody-game) - - [Table of Contents](#table-of-contents) + - [Table of contents](#table-of-contents) - [Introduction](#introduction) - [Terminology](#terminology) - [Constants](#constants) From 214943b7be5a2194a332c1a0ecab11d70cbcb76f Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:41:47 -0500 Subject: [PATCH 64/80] Update 1_shard-data-chains.md --- specs/core/1_shard-data-chains.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/core/1_shard-data-chains.md b/specs/core/1_shard-data-chains.md index 4db3db12a9..470f6e1375 100644 --- a/specs/core/1_shard-data-chains.md +++ b/specs/core/1_shard-data-chains.md @@ -2,12 +2,12 @@ **Notice**: This document is a work-in-progress for researchers and implementers. -## Table of Contents +## Table of contents - [Ethereum 2.0 Phase 1 -- Shards Data Chains](#ethereum-20-phase-1----shard-data-chains) - - [Table of Contents](#table-of-contents) + - [Table of contents](#table-of-contents) - [Introduction](#introduction) - [Constants](#constants) - [Misc](#misc) From b8cce7f5653ec9a46f9c4dd3d0c7fe276566fd88 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:42:25 -0500 Subject: [PATCH 65/80] Update 0_fork-choice.md --- specs/core/0_fork-choice.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/core/0_fork-choice.md b/specs/core/0_fork-choice.md index b72e8da6bd..11b736ea6b 100644 --- a/specs/core/0_fork-choice.md +++ b/specs/core/0_fork-choice.md @@ -2,11 +2,11 @@ **Notice**: This document is a work-in-progress for researchers and implementers. -## Table of Contents +## Table of contents - [Ethereum 2.0 Phase 0 -- Beacon Chain Fork Choice](#ethereum-20-phase-0----beacon-chain-fork-choice) - - [Table of Contents](#table-of-contents) + - [Table of contents](#table-of-contents) - [Introduction](#introduction) - [Prerequisites](#prerequisites) - [Constants](#constants) From 33134d49aed561d798f4a2cfde28cabf653b2c68 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:43:50 -0500 Subject: [PATCH 66/80] Update 0_beacon-chain-validator.md --- specs/validator/0_beacon-chain-validator.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/validator/0_beacon-chain-validator.md b/specs/validator/0_beacon-chain-validator.md index 3ae2f03e1c..600ed08391 100644 --- a/specs/validator/0_beacon-chain-validator.md +++ b/specs/validator/0_beacon-chain-validator.md @@ -2,12 +2,12 @@ **Notice**: This document is a work-in-progress for researchers and implementers. This is an accompanying document to [Ethereum 2.0 Phase 0 -- The Beacon Chain](../core/0_beacon-chain.md), which describes the expected actions of a "validator" participating in the Ethereum 2.0 protocol. -## Table of Contents +## Table of contents - [Ethereum 2.0 Phase 0 -- Honest Validator](#ethereum-20-phase-0----honest-validator) - - [Table of Contents](#table-of-contents) + - [Table of contents](#table-of-contents) - [Introduction](#introduction) - [Prerequisites](#prerequisites) - [Constants](#constants) From 182cc310a2e65daf9d172b25f8aca291b7dd43f1 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:45:09 -0500 Subject: [PATCH 67/80] Update simple-serialize.md --- specs/simple-serialize.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/simple-serialize.md b/specs/simple-serialize.md index 4a3600a9f9..343c967d4a 100644 --- a/specs/simple-serialize.md +++ b/specs/simple-serialize.md @@ -2,11 +2,11 @@ **Notice**: This document is a work-in-progress describing typing, serialization, and Merkleization of Eth 2.0 objects. -## Table of Contents +## Table of contents - [SimpleSerialize (SSZ)](#simpleserialize-ssz) - - [Table of Contents](#table-of-contents) + - [Table of contents](#table-of-contents) - [Constants](#constants) - [Typing](#typing) - [Basic types](#basic-types) From 4f7139ff408d53117ab3ec65d8b2b2d9a8528014 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:45:15 -0500 Subject: [PATCH 68/80] Update bls_signature.md --- specs/bls_signature.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/bls_signature.md b/specs/bls_signature.md index 82371fe428..d119c4499c 100644 --- a/specs/bls_signature.md +++ b/specs/bls_signature.md @@ -2,11 +2,11 @@ **Warning: This document is pending academic review and should not yet be considered secure.** -## Table of Contents +## Table of contents - [BLS signature verification](#bls-signature-verification) - - [Table of Contents](#table-of-contents) + - [Table of contents](#table-of-contents) - [Curve parameters](#curve-parameters) - [Point representations](#point-representations) - [G1 points](#g1-points) From b9024d10dc1820e5f257957d2413600281a4d72a Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:45:22 -0500 Subject: [PATCH 69/80] Update README.md --- specs/test_formats/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/test_formats/README.md b/specs/test_formats/README.md index 4708ea6509..4783dc475c 100644 --- a/specs/test_formats/README.md +++ b/specs/test_formats/README.md @@ -2,11 +2,11 @@ This document defines the YAML format and structure used for Eth 2.0 testing. -## Table of Contents +## Table of contents - [General test format](#general-test-format) - - [Table of Contents](#table-of-contents) + - [Table of contents](#table-of-contents) - [About](#about) - [Test-case formats](#test-case-formats) - [Glossary](#glossary) From 5f55735e1cc643be9bd277dfb3b2eb8b516d9fde Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:45:29 -0500 Subject: [PATCH 70/80] Update merkle_proofs.md --- specs/light_client/merkle_proofs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/light_client/merkle_proofs.md b/specs/light_client/merkle_proofs.md index 3a90ed6ab2..f009d97375 100644 --- a/specs/light_client/merkle_proofs.md +++ b/specs/light_client/merkle_proofs.md @@ -2,11 +2,11 @@ **Notice**: This document is a work-in-progress for researchers and implementers. -## Table of Contents +## Table of contents - [Merkle proof formats](#merkle-proof-formats) - - [Table of Contents](#table-of-contents) + - [Table of contents](#table-of-contents) - [Constants](#constants) - [Generalized Merkle tree index](#generalized-merkle-tree-index) - [SSZ object to index](#ssz-object-to-index) From a850bbe798d6c0e1d2863aec8119ac4ab4d7b072 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:46:52 -0500 Subject: [PATCH 71/80] Update sync_protocol.md --- specs/light_client/sync_protocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/light_client/sync_protocol.md b/specs/light_client/sync_protocol.md index b679f33ef7..f6e3d22657 100644 --- a/specs/light_client/sync_protocol.md +++ b/specs/light_client/sync_protocol.md @@ -2,12 +2,12 @@ **Notice**: This document is a work-in-progress for researchers and implementers. One of the design goals of the Eth 2.0 beacon chain is light-client friendliness, not only to allow low-resource clients (mobile phones, IoT, etc.) to maintain access to the blockchain in a reasonably safe way, but also to facilitate the development of "bridges" between the Eth 2.0 beacon chain and other chains. -## Table of Contents +## Table of contents - [Beacon Chain Light Client Syncing](#beacon-chain-light-client-syncing) - - [Table of Contents](#table-of-contents) + - [Table of contents](#table-of-contents) - [Preliminaries](#preliminaries) - [Expansions](#expansions) - [`get_active_validator_indices`](#get_active_validator_indices) From bcf98c5bbff228cc0eb20e1fd2c7260283284929 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:51:13 -0500 Subject: [PATCH 72/80] Update README.md --- configs/fork_timelines/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configs/fork_timelines/README.md b/configs/fork_timelines/README.md index 3e23c246c5..111c518196 100644 --- a/configs/fork_timelines/README.md +++ b/configs/fork_timelines/README.md @@ -3,7 +3,7 @@ This directory contains a set of fork timelines used for testing, testnets, and mainnet. A timeline file contains all the forks known for its target. -Later forks can be ignored, e.g. ignore fork `phase1` as a client that only supports phase 0 currently. +Later forks can be ignored, e.g. ignore fork `phase1` as a client that only supports Phase 0 currently. ## Format From 854363fca45b4c0b50139f68cb74a5dad11804e9 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 16:51:39 -0500 Subject: [PATCH 73/80] Update README.md --- configs/fork_timelines/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configs/fork_timelines/README.md b/configs/fork_timelines/README.md index 111c518196..da7445767c 100644 --- a/configs/fork_timelines/README.md +++ b/configs/fork_timelines/README.md @@ -11,7 +11,7 @@ Each preset is a key-value mapping. **Key**: an `lower_snake_case` (a.k.a. "python case") formatted string, name of the fork. -**Value**: an unsigned integer number, epoch number of activation of the fork +**Value**: an unsigned integer number, epoch number of activation of the fork. Timelines may contain comments to describe the values. From a29dc5e2eac60dd50fcf23909d3c361852254103 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Fri, 3 May 2019 17:23:29 -0500 Subject: [PATCH 74/80] Update 0_beacon-chain.md --- specs/core/0_beacon-chain.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/core/0_beacon-chain.md b/specs/core/0_beacon-chain.md index c14e389262..beadea6a3a 100644 --- a/specs/core/0_beacon-chain.md +++ b/specs/core/0_beacon-chain.md @@ -229,7 +229,7 @@ These configurations are updated for releases, but may be out of sync during `de | `INACTIVITY_PENALTY_QUOTIENT` | `2**25` (= 33,554,432) | | `MIN_SLASHING_PENALTY_QUOTIENT` | `2**5` (= 32) | -* **The `BASE_REWARD_QUOTIENT` is NOT final. Once all other protocol details are finalized, it will be adjusted to target a theoretical maximum total issuance of `2**21` ETH per year if `2**27` ETH is validating (and therefore `2**20` per year if `2**25` ETH is validating, etc etc)** +* **The `BASE_REWARD_QUOTIENT` is NOT final. Once all other protocol details are finalized, it will be adjusted to target a theoretical maximum total issuance of `2**21` ETH per year if `2**27` ETH is validating (and therefore `2**20` per year if `2**25` ETH is validating, etc.)** * The `INACTIVITY_PENALTY_QUOTIENT` equals `INVERSE_SQRT_E_DROP_TIME**2` where `INVERSE_SQRT_E_DROP_TIME := 2**12 epochs` (~18 days) is the time it takes the inactivity penalty to reduce the balance of non-participating [validators](#dfn-validator) to about `1/sqrt(e) ~= 60.6%`. Indeed, the balance retained by offline [validators](#dfn-validator) 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)`. ### Max operations per block From 54243ecd1dcec8e7af2d229e351b8dd8128d19fa Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Sat, 4 May 2019 00:56:04 -0500 Subject: [PATCH 75/80] Update rpc-interface.md --- specs/networking/rpc-interface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/networking/rpc-interface.md b/specs/networking/rpc-interface.md index fc0eb9ecda..ab7a08392c 100644 --- a/specs/networking/rpc-interface.md +++ b/specs/networking/rpc-interface.md @@ -244,7 +244,7 @@ Requests a list of block roots and slots from the peer. The `count` parameter MU ) ``` -Requests beacon block headers from the peer starting from `(start_root, start_slot)`. The response MUST contain no more than `max_headers` headers. `skip_slots` defines the maximum number of slots to skip between blocks. For example, requesting blocks starting at slots `2` a `skip_slots` value of `1` would return the blocks at `[2, 4, 6, 8, 10]`. In cases where a slot is empty for a given slot number, the closest previous block MUST be returned. For example, if slot `4` were empty in the previous example, the returned array would contain `[2, 3, 6, 8, 10]`. If slot three were further empty, the array would contain `[2, 6, 8, 10]` — i.e. duplicate blocks MUST be collapsed. A `skip_slots` value of `0` returns all blocks. +Requests beacon block headers from the peer starting from `(start_root, start_slot)`. The response MUST contain no more than `max_headers` headers. `skip_slots` defines the maximum number of slots to skip between blocks. For example, requesting blocks starting at slots `2` a `skip_slots` value of `1` would return the blocks at `[2, 4, 6, 8, 10]`. In cases where a slot is empty for a given slot number, the closest previous block MUST be returned. For example, if slot `4` were empty in the previous example, the returned array would contain `[2, 3, 6, 8, 10]`. If slot three were further empty, the array would contain `[2, 6, 8, 10]`—i.e. duplicate blocks MUST be collapsed. A `skip_slots` value of `0` returns all blocks. The function of the `skip_slots` parameter helps facilitate light client sync - for example, in [#459](https://github.com/ethereum/eth2.0-specs/issues/459) - and allows clients to balance the peers from whom they request headers. Clients could, for instance, request every 10th block from a set of peers where each peer has a different starting block in order to populate block data. From db6bd3860b72aa07a37cadc0af0ca03607755a73 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Sat, 4 May 2019 20:37:25 -0500 Subject: [PATCH 76/80] Update 0_beacon-chain.md --- specs/core/0_beacon-chain.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/specs/core/0_beacon-chain.md b/specs/core/0_beacon-chain.md index beadea6a3a..9014364c48 100644 --- a/specs/core/0_beacon-chain.md +++ b/specs/core/0_beacon-chain.md @@ -134,20 +134,20 @@ Code snippets appearing in `this style` are to be interpreted as Python code. ## Terminology -* **Validator** — a registered participant in the beacon chain. You can become one by sending ether into the Ethereum 1.0 deposit contract. -* **Active validator** — an active participant in the Ethereum 2.0 consensus invited to, among other things, propose and attest to blocks and vote for crosslinks. -* **Committee** — a (pseudo-) randomly sampled subset of [active validators](#dfn-active-validator). When a committee is referred to collectively, as in "this committee attests to X", this is assumed to mean "some subset of that committee that contains enough [validators](#dfn-validator) that the protocol recognizes it as representing the committee". -* **Proposer** — the [validator](#dfn-validator) that creates a beacon chain block. -* **Attester** — a [validator](#dfn-validator) that is part of a committee that needs to sign off on a beacon chain block while simultaneously creating a link (crosslink) to a recent shard block on a particular shard chain. -* **Beacon chain** — the central PoS chain that is the base of the sharding system. -* **Shard chain** — one of the chains on which user transactions take place and account data is stored. -* **Block root** — a 32-byte Merkle root of a beacon chain block or shard chain block. Previously called "block hash". -* **Crosslink** — a set of signatures from a committee attesting to a block in a shard chain that can be included into the beacon chain. Crosslinks are the main means by which the beacon chain "learns about" the updated state of shard chains. -* **Slot** — a period during which one proposer has the ability to create a beacon chain block and some attesters have the ability to make attestations. -* **Epoch** — an aligned span of slots during which all [validators](#dfn-validator) get exactly one chance to make an attestation. -* **Finalized**, **justified** — see the [Casper FFG paper](https://arxiv.org/abs/1710.09437). -* **Withdrawal period** — the number of slots between a [validator](#dfn-validator) exit and the [validator](#dfn-validator) balance being withdrawable. -* **Genesis time** — the Unix time of the genesis beacon chain block at slot 0. +* **Validator**—a registered participant in the beacon chain. You can become one by sending ether into the Ethereum 1.0 deposit contract. +* **Active validator**—an active participant in the Ethereum 2.0 consensus invited to, among other things, propose and attest to blocks and vote for crosslinks. +* **Committee**—a (pseudo-) randomly sampled subset of [active validators](#dfn-active-validator). When a committee is referred to collectively, as in "this committee attests to X", this is assumed to mean "some subset of that committee that contains enough [validators](#dfn-validator) that the protocol recognizes it as representing the committee". +* **Proposer**—the [validator](#dfn-validator) that creates a beacon chain block. +* **Attester**—a [validator](#dfn-validator) that is part of a committee that needs to sign off on a beacon chain block while simultaneously creating a link (crosslink) to a recent shard block on a particular shard chain. +* **Beacon chain**—the central PoS chain that is the base of the sharding system. +* **Shard chain**—one of the chains on which user transactions take place and account data is stored. +* **Block root**—a 32-byte Merkle root of a beacon chain block or shard chain block. Previously called "block hash". +* **Crosslink**—a set of signatures from a committee attesting to a block in a shard chain that can be included into the beacon chain. Crosslinks are the main means by which the beacon chain "learns about" the updated state of shard chains. +* **Slot**—a period during which one proposer has the ability to create a beacon chain block and some attesters have the ability to make attestations. +* **Epoch**—an aligned span of slots during which all [validators](#dfn-validator) get exactly one chance to make an attestation. +* **Finalized**, **justified**—see the [Casper FFG paper](https://arxiv.org/abs/1710.09437). +* **Withdrawal period**—the number of slots between a [validator](#dfn-validator) exit and the [validator](#dfn-validator) balance being withdrawable. +* **Genesis time**—the Unix time of the genesis beacon chain block at slot 0. ## Constants From 2fb970029972b65f3884f3e3c36d8d2e003ee784 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Sat, 4 May 2019 20:38:28 -0500 Subject: [PATCH 77/80] Update 1_custody-game.md --- specs/core/1_custody-game.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/specs/core/1_custody-game.md b/specs/core/1_custody-game.md index 7c079c093c..b3ab519fa0 100644 --- a/specs/core/1_custody-game.md +++ b/specs/core/1_custody-game.md @@ -57,18 +57,18 @@ This document details the beacon chain additions and changes in Phase 1 of Ether ## Terminology -* **Custody game** — -* **Custody period** — -* **Custody chunk** — -* **Custody chunk bit** — -* **Custody chunk challenge** — -* **Custody bit** — -* **Custody bit challenge** — -* **Custody key** — -* **Custody key reveal** — -* **Custody key mask** — -* **Custody response** — -* **Custody response deadline** — +* **Custody game**— +* **Custody period**— +* **Custody chunk**— +* **Custody chunk bit**— +* **Custody chunk challenge**— +* **Custody bit**— +* **Custody bit challenge**— +* **Custody key**— +* **Custody key reveal**— +* **Custody key mask**— +* **Custody response**— +* **Custody response deadline**— ## Constants From 83423435a49e453847351fc76b8a722f5587cf48 Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Sat, 4 May 2019 20:48:31 -0500 Subject: [PATCH 78/80] Update core.md --- specs/test_formats/ssz_static/core.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/test_formats/ssz_static/core.md b/specs/test_formats/ssz_static/core.md index fd80f1b1e5..64b09a3296 100644 --- a/specs/test_formats/ssz_static/core.md +++ b/specs/test_formats/ssz_static/core.md @@ -27,6 +27,6 @@ A test-runner can implement the following assertions: ## References -**`serialized`** — [SSZ serialization](../../simple-serialize.md#serialization) -**`root`** — [hash_tree_root](../../simple-serialize.md#merkleization) function -**`signing_root`** — [signing_root](../../simple-serialize.md#self-signed-containers) function +**`serialized`**—[SSZ serialization](../../simple-serialize.md#serialization) +**`root`**—[hash_tree_root](../../simple-serialize.md#merkleization) function +**`signing_root`**—[signing_root](../../simple-serialize.md#self-signed-containers) function From c8e4db48d3c5203ef97a16e1556c3d779e9e494f Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Sat, 4 May 2019 22:04:02 -0500 Subject: [PATCH 79/80] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5f2e78ebde..4c4808059f 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![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 Eth 2.0, see the [sharding FAQ](https://github.com/ethereum/wiki/wiki/Sharding-FAQ) and the [research compendium](https://notes.ethereum.org/s/H1PGqDhpm). +To learn more about sharding and Ethereum 2.0 (Serenity), see the [sharding FAQ](https://github.com/ethereum/wiki/wiki/Sharding-FAQ) and the [research compendium](https://notes.ethereum.org/s/H1PGqDhpm). This repository hosts the current Eth 2.0 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. From 63657f7e2412c4a62212559e967da9b581a2640f Mon Sep 17 00:00:00 2001 From: JSON <49416440+JSON@users.noreply.github.com> Date: Sun, 5 May 2019 15:51:29 -0500 Subject: [PATCH 80/80] Update 1_shard-data-chains.md --- specs/core/1_shard-data-chains.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/core/1_shard-data-chains.md b/specs/core/1_shard-data-chains.md index 470f6e1375..14eb511931 100644 --- a/specs/core/1_shard-data-chains.md +++ b/specs/core/1_shard-data-chains.md @@ -6,7 +6,7 @@ -- [Ethereum 2.0 Phase 1 -- Shards Data Chains](#ethereum-20-phase-1----shard-data-chains) +- [Ethereum 2.0 Phase 1 -- Shard Data Chains](#ethereum-20-phase-1----shard-data-chains) - [Table of contents](#table-of-contents) - [Introduction](#introduction) - [Constants](#constants)