Run mdformat

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+- repo: https://github.com/executablebooks/mdformat
+  rev: 0.6.2
+  hooks:
+  - id: mdformat
+    args: [--number]
+    additional_dependencies:
+    - mdformat-gfm

README.md

@@ -6,7 +6,6 @@ To learn more about sharding and Ethereum 2.0 (Serenity), see the [sharding FAQ]
 
 This repository hosts the current Eth2 specifications. Discussions about design rationale and proposed changes can be brought up and discussed as issues. Solidified, agreed-upon changes to the spec can be made through pull requests.
 
-
 ## Specs
 
 [![GitHub release](https://img.shields.io/github/v/release/ethereum/eth2.0-specs)](https://github.com/ethereum/eth2.0-specs/releases/) [![PyPI version](https://badge.fury.io/py/eth2spec.svg)](https://badge.fury.io/py/eth2spec)
@@ -18,80 +17,82 @@ The current features are:
 
 ### Phase 0
 
-* [The Beacon Chain](specs/phase0/beacon-chain.md)
-* [Beacon Chain Fork Choice](specs/phase0/fork-choice.md)
-* [Deposit Contract](specs/phase0/deposit-contract.md)
-* [Honest Validator](specs/phase0/validator.md)
-* [P2P Networking](specs/phase0/p2p-interface.md)
+- [The Beacon Chain](specs/phase0/beacon-chain.md)
+- [Beacon Chain Fork Choice](specs/phase0/fork-choice.md)
+- [Deposit Contract](specs/phase0/deposit-contract.md)
+- [Honest Validator](specs/phase0/validator.md)
+- [P2P Networking](specs/phase0/p2p-interface.md)
 
 ### Altair
 
-* [Beacon chain changes](specs/altair/beacon-chain.md)
-* [Altair fork](specs/altair/fork.md)
-* [Light client sync protocol](specs/altair/sync-protocol.md)
-* [Honest Validator guide changes](specs/altair/validator.md)
+- [Beacon chain changes](specs/altair/beacon-chain.md)
+- [Altair fork](specs/altair/fork.md)
+- [Light client sync protocol](specs/altair/sync-protocol.md)
+- [Honest Validator guide changes](specs/altair/validator.md)
 
 ### Merge
 
 The merge is still actively in R&D. The specifications outline a general direction for engineering work,
 while the details are in review and may change.
 
-* Background material:
-  * An [ethresear.ch](https://ethresear.ch) post [describing the basic mechanism](https://ethresear.ch/t/the-eth1-eth2-transition/6265)
-  * [ethereum.org](https://ethereum.org) high-level description of the merge [here](https://ethereum.org/en/eth2/docking/)
-* Specifications:
-  * [Beacon Chain changes](specs/merge/beacon-chain.md)
-  * [Fork Choice changes](specs/merge/fork-choice.md)
-  * [Validator additions](specs/merge/validator.md)
+- Background material:
+  - An [ethresear.ch](https://ethresear.ch) post [describing the basic mechanism](https://ethresear.ch/t/the-eth1-eth2-transition/6265)
+  - [ethereum.org](https://ethereum.org) high-level description of the merge [here](https://ethereum.org/en/eth2/docking/)
+- Specifications:
+  - [Beacon Chain changes](specs/merge/beacon-chain.md)
+  - [Fork Choice changes](specs/merge/fork-choice.md)
+  - [Validator additions](specs/merge/validator.md)
 
 ### Sharding
 
 Sharding follows the merge, and is divided into three parts:
 
-* Sharding base functionality - In early engineering phase
-  * [Beacon Chain changes](specs/sharding/beacon-chain.md)
-  * [P2P Network changes](specs/sharding/p2p-interface.md)
-* Custody Game - Ready, dependent on sharding 
-  * [Beacon Chain changes](specs/custody_game/beacon-chain.md)
-  * [Validator custody work](specs/custody_game/validator.md)
-* Data Availability Sampling - In active R&D
-  * Technical details [here](https://hackmd.io/@HWeNw8hNRimMm2m2GH56Cw/B1YJPGkpD).
-  * [Core types and functions](specs/das/das-core.md)
-  * [P2P Networking](specs/das/p2p-interface.md)
-  * [Fork Choice](specs/das/fork-choice.md)
-  * [Sampling process](specs/das/sampling.md)
+- Sharding base functionality - In early engineering phase
+  - [Beacon Chain changes](specs/sharding/beacon-chain.md)
+  - [P2P Network changes](specs/sharding/p2p-interface.md)
+- Custody Game - Ready, dependent on sharding
+  - [Beacon Chain changes](specs/custody_game/beacon-chain.md)
+  - [Validator custody work](specs/custody_game/validator.md)
+- Data Availability Sampling - In active R&D
+  - Technical details [here](https://hackmd.io/@HWeNw8hNRimMm2m2GH56Cw/B1YJPGkpD).
+  - [Core types and functions](specs/das/das-core.md)
+  - [P2P Networking](specs/das/p2p-interface.md)
+  - [Fork Choice](specs/das/fork-choice.md)
+  - [Sampling process](specs/das/sampling.md)
 
 ### Accompanying documents can be found in [specs](specs) and include:
 
-* [SimpleSerialize (SSZ) spec](ssz/simple-serialize.md)
-* [Merkle proof formats](ssz/merkle-proofs.md)
-* [General test format](tests/formats/README.md)
+- [SimpleSerialize (SSZ) spec](ssz/simple-serialize.md)
+- [Merkle proof formats](ssz/merkle-proofs.md)
+- [General test format](tests/formats/README.md)
 
 ## Additional specifications for client implementers
 
 Additional specifications and standards outside of requisite client functionality can be found in the following repos:
 
-* [Eth2 APIs](https://github.com/ethereum/eth2.0-apis)
-* [Eth2 Metrics](https://github.com/ethereum/eth2.0-metrics/)
-* [Interop Standards in Eth2 PM](https://github.com/ethereum/eth2.0-pm/tree/master/interop)
+- [Eth2 APIs](https://github.com/ethereum/eth2.0-apis)
+- [Eth2 Metrics](https://github.com/ethereum/eth2.0-metrics/)
+- [Interop Standards in Eth2 PM](https://github.com/ethereum/eth2.0-pm/tree/master/interop)
 
 ## 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
-* to remain live through major network partitions and when very large portions of nodes go offline
-* to select all components such that they are either quantum secure or can be easily swapped out for quantum secure counterparts when available
-* to utilize crypto and design techniques that allow for a large participation of validators in total and per unit time
-* to allow for a typical consumer laptop with `O(C)` resources to process/validate `O(1)` shards (including any system level validation such as the beacon chain)
+
+- to minimize complexity, even at the cost of some losses in efficiency
+- to remain live through major network partitions and when very large portions of nodes go offline
+- to select all components such that they are either quantum secure or can be easily swapped out for quantum secure counterparts when available
+- to utilize crypto and design techniques that allow for a large participation of validators in total and per unit time
+- to allow for a typical consumer laptop with `O(C)` resources to process/validate `O(1)` shards (including any system level validation such as the beacon chain)
 
 ## Useful external resources
 
-* [Design Rationale](https://notes.ethereum.org/s/rkhCgQteN#)
-* [Phase 0 Onboarding Document](https://notes.ethereum.org/s/Bkn3zpwxB)
-* [Combining GHOST and Casper paper](https://arxiv.org/abs/2003.03052)
+- [Design Rationale](https://notes.ethereum.org/s/rkhCgQteN)
+- [Phase 0 Onboarding Document](https://notes.ethereum.org/s/Bkn3zpwxB)
+- [Combining GHOST and Casper paper](https://arxiv.org/abs/2003.03052)
 
 ## For spec contributors
 
 Documentation on the different components used during spec writing can be found here:
-* [YAML Test Generators](tests/generators/README.md)
-* [Executable Python Spec, with Py-tests](tests/core/pyspec/README.md)
+
+- [YAML Test Generators](tests/generators/README.md)
+- [Executable Python Spec, with Py-tests](tests/core/pyspec/README.md)

configs/README.md

@@ -5,7 +5,6 @@ This directory contains a set of constants presets used for testing, testnets, a
 A preset file contains all the constants known for its target.
 Later-fork constants can be ignored, e.g. ignore Sharding constants as a client that only supports Phase 0 currently.
 
-
 ## Forking
 
 Configs are not replaced, but extended with forks. This is to support syncing from one state to the other over a fork boundary, without hot-swapping a config.
@@ -18,16 +17,17 @@ A previous iteration of forking made use of "timelines", but this collides with
 Instead, the config essentially doubles as fork definition now, e.g. changing the value for `ALTAIR_FORK_SLOT` changes the fork.
 
 Another reason to prefer forking through constants is the ability to program a forking moment based on context, instead of being limited to a static slot number.
- 
+
 ## 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 either:
- - an unsigned integer number, can be up to 64 bits (incl.)
- - a hexadecimal string, prefixed with `0x`
+
+- 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.
 

solidity_deposit_contract/README.md

@@ -14,16 +14,17 @@ In August 2020, version `r2` was released with metadata modifications and relice
 ## Compiling solidity deposit contract
 
 In the `eth2.0-specs` directory run:
+
 ```sh
 make compile_deposit_contract
 ```
 
 The following parameters were used to generate the bytecode for the `DepositContract` available in this repository:
 
-* Contract Name: `DepositContract`
-* Compiler Version: Solidity `v0.6.11+commit.5ef660b1`
-* Optimization Enabled: `Yes` with `5000000` runs
-* Metadata Options: `--metadata-literal` (to verify metadata hash)
+- Contract Name: `DepositContract`
+- Compiler Version: Solidity `v0.6.11+commit.5ef660b1`
+- Optimization Enabled: `Yes` with `5000000` runs
+- Metadata Options: `--metadata-literal` (to verify metadata hash)
 
 ```sh
 solc --optimize --optimize-runs 5000000 --metadata-literal --bin deposit_contract.sol

specs/altair/beacon-chain.md

@@ -3,7 +3,9 @@
 ## Table of contents
 
 <!-- TOC -->
+
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
+
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 - [Introduction](#introduction)
@@ -54,48 +56,49 @@
     - [Sync committee updates](#sync-committee-updates)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 <!-- /TOC -->
 
 ## Introduction
 
 Altair is the first beacon chain hard fork. Its main features are:
 
-* sync committees to support light clients
-* incentive accounting reforms to reduce spec complexity
-* penalty parameter updates towards their planned maximally punitive values
+- sync committees to support light clients
+- incentive accounting reforms to reduce spec complexity
+- penalty parameter updates towards their planned maximally punitive values
 
 ## Custom types
 
-| Name | SSZ equivalent | Description |
-| - | - | - |
-| `ParticipationFlags` | `uint8` | a succinct representation of 8 boolean participation flags |
+| Name                 | SSZ equivalent | Description                                                |
+| -------------------- | -------------- | ---------------------------------------------------------- |
+| `ParticipationFlags` | `uint8`        | a succinct representation of 8 boolean participation flags |
 
 ## Constants
 
 ### Participation flag indices
 
-| Name | Value |
-| - | - |
-| `TIMELY_HEAD_FLAG_INDEX` | `0` |
-| `TIMELY_SOURCE_FLAG_INDEX` | `1` |
-| `TIMELY_TARGET_FLAG_INDEX` | `2` |
+| Name                       | Value |
+| -------------------------- | ----- |
+| `TIMELY_HEAD_FLAG_INDEX`   | `0`   |
+| `TIMELY_SOURCE_FLAG_INDEX` | `1`   |
+| `TIMELY_TARGET_FLAG_INDEX` | `2`   |
 
 ### Incentivization weights
 
-| Name | Value |
-| - | - |
-| `TIMELY_HEAD_WEIGHT` | `uint64(12)` |
+| Name                   | Value        |
+| ---------------------- | ------------ |
+| `TIMELY_HEAD_WEIGHT`   | `uint64(12)` |
 | `TIMELY_SOURCE_WEIGHT` | `uint64(12)` |
 | `TIMELY_TARGET_WEIGHT` | `uint64(24)` |
-| `SYNC_REWARD_WEIGHT` | `uint64(8)` |
-| `WEIGHT_DENOMINATOR` | `uint64(64)` |
+| `SYNC_REWARD_WEIGHT`   | `uint64(8)`  |
+| `WEIGHT_DENOMINATOR`   | `uint64(64)` |
 
 *Note*: The sum of the weight fractions (7/8) plus the proposer inclusion fraction (1/8) equals 1.
 
 ### Misc
 
-| Name | Value |
-| - | - |
+| Name                   | Value                                  |
+| ---------------------- | -------------------------------------- |
 | `G2_POINT_AT_INFINITY` | `BLSSignature(b'\xc0' + b'\x00' * 95)` |
 
 ## Configuration
@@ -106,33 +109,33 @@ This patch updates a few configuration values to move penalty parameters toward
 
 *Note*: The spec does *not* override previous configuration values but instead creates new values and replaces usage throughout.
 
-| Name | Value |
-| - | - |
-| `INACTIVITY_PENALTY_QUOTIENT_ALTAIR` | `uint64(3 * 2**24)` (= 50,331,648) |
-| `MIN_SLASHING_PENALTY_QUOTIENT_ALTAIR` | `uint64(2**6)` (= 64) |
-| `PROPORTIONAL_SLASHING_MULTIPLIER_ALTAIR` | `uint64(2)` |
+| Name                                      | Value                              |
+| ----------------------------------------- | ---------------------------------- |
+| `INACTIVITY_PENALTY_QUOTIENT_ALTAIR`      | `uint64(3 * 2**24)` (= 50,331,648) |
+| `MIN_SLASHING_PENALTY_QUOTIENT_ALTAIR`    | `uint64(2**6)` (= 64)              |
+| `PROPORTIONAL_SLASHING_MULTIPLIER_ALTAIR` | `uint64(2)`                        |
 
 ### Misc
 
-| Name | Value |
-| - | - |
-| `SYNC_COMMITTEE_SIZE` | `uint64(2**10)` (= 1,024) |
-| `SYNC_PUBKEYS_PER_AGGREGATE` | `uint64(2**6)` (= 64) |
-| `INACTIVITY_SCORE_BIAS` | `uint64(4)` |
+| Name                         | Value                     |
+| ---------------------------- | ------------------------- |
+| `SYNC_COMMITTEE_SIZE`        | `uint64(2**10)` (= 1,024) |
+| `SYNC_PUBKEYS_PER_AGGREGATE` | `uint64(2**6)` (= 64)     |
+| `INACTIVITY_SCORE_BIAS`      | `uint64(4)`               |
 
 ### Time parameters
 
-| Name | Value | Unit | Duration |
-| - | - | :-: | :-: |
+| Name                               | Value                 |  Unit  | Duration  |
+| ---------------------------------- | --------------------- | :----: | :-------: |
 | `EPOCHS_PER_SYNC_COMMITTEE_PERIOD` | `Epoch(2**8)` (= 256) | epochs | ~27 hours |
 
 ### Domain types
 
-| Name | Value |
-| - | - |
-| `DOMAIN_SYNC_COMMITTEE` | `DomainType('0x07000000')` |
+| Name                                    | Value                      |
+| --------------------------------------- | -------------------------- |
+| `DOMAIN_SYNC_COMMITTEE`                 | `DomainType('0x07000000')` |
 | `DOMAIN_SYNC_COMMITTEE_SELECTION_PROOF` | `DomainType('0x08000000')` |
-| `DOMAIN_CONTRIBUTION_AND_PROOF` | `DomainType('0x09000000')` |
+| `DOMAIN_CONTRIBUTION_AND_PROOF`         | `DomainType('0x09000000')` |
 
 ## Containers
 

specs/altair/fork.md

@@ -5,6 +5,7 @@
 ## Table of contents
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
+
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 - [Introduction](#introduction)
@@ -23,10 +24,10 @@ This document describes the process of the first upgrade of Ethereum 2.0: the Al
 
 Warning: this configuration is not definitive.
 
-| Name | Value |
-| - | - |
+| Name                  | Value                   |
+| --------------------- | ----------------------- |
 | `ALTAIR_FORK_VERSION` | `Version('0x01000000')` |
-| `ALTAIR_FORK_SLOT` | `Slot(0)` **TBD** |
+| `ALTAIR_FORK_SLOT`    | `Slot(0)` **TBD**       |
 
 ## Fork to Altair