Merge pull request #4082 from jtraglia/fix-nits

Fix various nits in markdown files

README.md

@@ -81,7 +81,6 @@ Documentation on the different components used during spec writing can be found
 
 Conformance tests built from the executable python spec are available in the [Ethereum Proof-of-Stake Consensus Spec Tests](https://github.com/ethereum/consensus-spec-tests) repo. Compressed tarballs are available in [releases](https://github.com/ethereum/consensus-spec-tests/releases).
 
-
 ## Installation and Usage
 The consensus-specs repo can be used by running the tests locally or inside a docker container.
 

docker/README.md

@@ -1,10 +1,11 @@
 ## Docker related information
 
 This dockerfile sets up the dependencies required to run consensus-spec tests. The docker image can be locally built with:
-- `docker build ./ -t $IMAGE_NAME -f ./docker/Dockerfile`
 
+- `docker build ./ -t $IMAGE_NAME -f ./docker/Dockerfile`
 
 Handy commands:
+
 - `docker run -it $IMAGE_NAME /bin/sh` will give you a shell inside the docker container to manually run any tests
 - `docker run $IMAGE_NAME make test` will run the make test command inside the docker container
 
@@ -13,6 +14,7 @@ Ideally manual running of docker containers is for advanced users, we recommend
 The `scripts/build_run_docker_tests.sh` script will cover most use cases. The script allows the user to configure the fork(altair/bellatrix/capella..), `$IMAGE_NAME` (specifies the container to use), preset type (mainnet/minimal), and test all forks flags. Ideally, this is the main way that users interact with the spec tests instead of running it locally with varying versions of dependencies.
 
 E.g:
+
 - `./build_run_docker_tests.sh --p mainnet` will run the mainnet preset tests
 - `./build_run_docker_tests.sh --a` will run all the tests across all the forks
 - `./build_run_docker_tests.sh --f deneb` will only run deneb tests

docs/docs/new-feature.md

@@ -1,8 +1,9 @@
 # How to add a new feature proposal in consensus-specs
 
+## 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 -->
-## Table of Contents
 
 - [A. Make it executable for linter checks](#a-make-it-executable-for-linter-checks)
   - [1. Create a folder under `./specs/_features`](#1-create-a-folder-under-specs_features)
@@ -23,7 +24,6 @@
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-
 ## A. Make it executable for linter checks
 
 ### 1. Create a folder under `./specs/_features`
@@ -35,6 +35,7 @@ For example, if it's an `EIP-9999` CL spec, you can create a `./specs/_features/
 For example, if the latest fork is Capella, use `./specs/capella` content as your "previous fork".
 
 ### 3. Write down your proposed `beacon-chain.md` change
+
 - You can either use [Beacon Chain Spec Template](./templates/beacon-chain-template.md), or make a copy of the latest fork content and then edit it.
 - Tips:
     - We use [`doctoc`](https://www.npmjs.com/package/doctoc) tool to generate the table of content.
@@ -50,8 +51,11 @@ For example, if the latest fork is Capella, use `./specs/capella` content as you
         - Use simple Python rather than the fancy Python dark magic.
 
 ### 4. Add `fork.md`
+
 You can refer to the previous fork's `fork.md` file.
+
 ### 5. Make it executable
+
 - Update Pyspec [`constants.py`](https://github.com/ethereum/consensus-specs/blob/dev/tests/core/pyspec/eth2spec/test/helpers/constants.py) with the new feature name.
 - Update helpers for [`setup.py`](https://github.com/ethereum/consensus-specs/blob/dev/setup.py) for building the spec:
     - Update [`pysetup/constants.py`](https://github.com/ethereum/consensus-specs/blob/dev/pysetup/constants.py) with the new feature name as Pyspec `constants.py` defined.
@@ -63,17 +67,21 @@ You can refer to the previous fork's `fork.md` file.
 ## B: Make it executable for pytest and test generator
 
 ### 1. [Optional] Add `light-client/*` docs if you updated the content of `BeaconBlock`
+
 - You can refer to the previous fork's `light-client/*` file.
 - Add the path of the new markdown files in [`pysetup/md_doc_paths.py`](https://github.com/ethereum/consensus-specs/blob/dev/pysetup/md_doc_paths.py)'s `get_md_doc_paths` function.
 
 ### 2. Add the mainnet and minimal presets and update the configs
+
 - Add presets: `presets/mainnet/<new-feature-name>.yaml` and `presets/minimal/<new-feature-name>.yaml`
 - Update configs: `configs/mainnet.yaml` and `configs/minimal.yaml`
 
 ### 3. Update [`context.py`](https://github.com/ethereum/consensus-specs/blob/dev/tests/core/pyspec/eth2spec/test/context.py)
+
 - [Optional] Add `with_<new-feature-name>_and_later` decorator for writing pytest cases. e.g., `with_capella_and_later`.
 
 ### 4. Update [`constants.py`](https://github.com/ethereum/consensus-specs/blob/dev/tests/core/pyspec/eth2spec/test/helpers/constants.py)
+
 - Add `<NEW_FEATURE>` to `ALL_PHASES` and `TESTGEN_FORKS`
 
 ### 5. Update [`genesis.py`](https://github.com/ethereum/consensus-specs/blob/dev/tests/core/pyspec/eth2spec/test/helpers/genesis.py):
@@ -94,6 +102,7 @@ def create_genesis_state(spec, validator_balances, activation_threshold):
 - If the given feature changes `ExecutionPayload` fields, you have to set the initial values by updating `get_sample_genesis_execution_payload_header` helper.
 
 ### 6. Update CI configurations
+
 - Update [GitHub Actions config](https://github.com/ethereum/consensus-specs/blob/dev/.github/workflows/run-tests.yml)
     - Update `pyspec-tests.strategy.matrix.version` list by adding new feature to it
 - Update [CircleCI config](https://github.com/ethereum/consensus-specs/blob/dev/.circleci/config.yml)
@@ -102,7 +111,9 @@ def create_genesis_state(spec, validator_balances, activation_threshold):
 ## Others
 
 ### Bonus
+
 - Add `validator.md` if honest validator behavior changes with the new feature.
 
 ### Need help?
+
 You can tag spec elves for cleaning up your PR. 🧚

docs/docs/templates/beacon-chain-template.md

@@ -3,15 +3,14 @@
 # <FORK_NAME> -- The Beacon Chain
 
 ## Table of contents
+
 <!-- TOC -->
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- /TOC -->
 
-
-
 ## Introduction
 
 ## Notation
@@ -28,7 +27,6 @@
 
 ## Preset
 
-
 ### [CATEGORY OF PRESETS]
 
 | Name | Value |
@@ -64,5 +62,4 @@ class CONTAINER_NAME(Container):
 
 ### Epoch processing
 
-
 ### Block processing

fork_choice/safe-block.md

@@ -1,6 +1,7 @@
 # Fork Choice -- Safe Block
 
 ## 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 -->

solidity_deposit_contract/README.md

@@ -14,6 +14,7 @@ In August 2020, version `r2` was released with metadata modifications and relice
 ## Compiling solidity deposit contract
 
 In this directory run:
+
 ```sh
 make compile_deposit_contract
 ```

specs/_features/custody_game/beacon-chain.md

@@ -55,7 +55,6 @@
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- /TOC -->
 
-
 ## Introduction
 
 This document details the beacon chain additions and changes of to support the shard data custody game,
@@ -101,7 +100,6 @@ building upon the [Sharding](../sharding/beacon-chain.md) specification.
 | `MAX_CUSTODY_CHUNK_CHALLENGE_RESPONSES` | `uint64(2**4)` (= 16) |
 | `MAX_CUSTODY_SLASHINGS` | `uint64(2**0)` (= 1) |
 
-
 ### Size parameters
 
 | Name | Value | Unit |
@@ -355,7 +353,6 @@ def get_custody_period_for_validator(validator_index: ValidatorIndex, epoch: Epo
     return (epoch + validator_index % EPOCHS_PER_CUSTODY_PERIOD) // EPOCHS_PER_CUSTODY_PERIOD
 ```
 
-
 ## Per-block processing
 
 ### Block processing

specs/_features/custody_game/validator.md

@@ -1,8 +1,6 @@
 # Custody Game -- Honest Validator
 
 **Notice**: This document is a work-in-progress for researchers and implementers.
-This is an accompanying document to [Custody Game -- The Beacon Chain](./beacon-chain.md), which describes the expected actions of a "validator"
-participating in the shard data Custody Game.
 
 ## Table of contents
 
@@ -24,9 +22,11 @@ participating in the shard data Custody Game.
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- /TOC -->
 
-
 ## Introduction
 
+This is an accompanying document to [Custody Game -- The Beacon Chain](./beacon-chain.md), which describes the expected actions of a "validator"
+participating in the shard data Custody Game.
+
 ## Prerequisites
 
 This document is an extension of the [Sharding -- Validator](../sharding/validator.md). All behaviors and definitions defined in the Sharding doc carry over unless explicitly noted or overridden.
@@ -58,7 +58,6 @@ Up to `MAX_EARLY_DERIVED_SECRET_REVEALS`, [`EarlyDerivedSecretReveal`](./beacon-
 
 `attestation.data`, `attestation.aggregation_bits`, and `attestation.signature` are unchanged from Phase 0. But safety/validity in signing the message is premised upon calculation of the "custody bit" [TODO].
 
-
 ## How to avoid slashing
 
 Proposer and Attester slashings described in Phase 0 remain in place with the addition of the following.

specs/_features/das/das-core.md

@@ -24,7 +24,6 @@
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- /TOC -->
 
-
 ## Custom types
 
 We define the following Python custom types for type hinting and readability:
@@ -33,7 +32,6 @@ We define the following Python custom types for type hinting and readability:
 | - | - | - |
 | `SampleIndex` | `uint64` | A sample index, corresponding to chunk of extended data |
 
-
 ## Configuration
 
 ### Misc
@@ -42,7 +40,6 @@ We define the following Python custom types for type hinting and readability:
 | - | - | - |
 | `MAX_RESAMPLE_TIME` | `TODO` (= TODO) | Time window to sample a shard blob and put it on vertical subnets |
 
-
 ## New containers
 
 ### `DASSample`

specs/_features/das/fork-choice.md

@@ -14,7 +14,6 @@
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- /TOC -->
 
-
 ## Introduction
 
 This document is the beacon chain fork choice spec for Data Availability Sampling. The only change that we add from phase 0 is that we add a concept of "data dependencies";

specs/_features/das/p2p-interface.md

@@ -95,7 +95,6 @@ Since the messages are content-addressed (instead of origin-stamped),
 multiple publishers of the same samples on a vertical subnet do not hurt performance,
 but actually improve it by shortcutting regular propagation on the vertical subnet, and thus lowering the latency to a sample.
 
-
 ### Vertical subnets
 
 Vertical subnets propagate the samples to every peer that is interested.
@@ -161,7 +160,6 @@ Take `blob = signed_blob.blob`:
 
 The [DAS participation spec](sampling.md#horizontal-subnets) outlines when and where to participate in DAS on horizontal subnets.
 
-
 #### Vertical subnets: `das_sample_{subnet_index}`
 
 Shard blob samples can be verified with just a 48 byte KZG proof (commitment quotient polynomial),
@@ -185,7 +183,6 @@ The following validations MUST pass before forwarding the `sample` on the vertic
 Upon receiving a valid sample, it SHOULD be retained for a buffer period if the local node is part of the backbone that covers this sample.
 This is to serve other peers that may have missed it.
 
-
 ## DAS in the Req-Resp domain: Pull
 
 To pull samples from nodes, in case of network instability when samples are unavailable, a new query method is added to the Req-Resp domain.
@@ -201,13 +198,15 @@ Note that DAS networking uses a different protocol prefix: `/eth2/das/req`
 **Protocol ID:** `/eth2/das/req/query/1/`
 
 Request Content:
+
 ```
 (
   sample_index: SampleIndex
 )
 ```
 
 Response Content:
+
 ```
 (
   DASSample

specs/_features/das/sampling.md

@@ -22,7 +22,6 @@
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- /TOC -->
 
-
 ## Data Availability Sampling
 
 TODO: Summary of Data Availability problem
@@ -45,7 +44,6 @@ TODO
 
 TODO
 
-
 ### DAS during network instability
 
 The GossipSub based retrieval of samples may not always work.

specs/_features/eip6800/beacon-chain.md

@@ -1,5 +1,7 @@
 # EIP6800 -- The Beacon Chain
 
+**Notice**: This document is a work-in-progress for researchers and implementers.
+
 ## Table of contents
 
 <!-- TOC -->

specs/_features/eip6800/fork.md

@@ -1,7 +1,10 @@
 # EIP-6800 -- Fork Logic
 
+**Notice**: This document is a work-in-progress for researchers and implementers.
+
 ## 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 -->
 
@@ -15,6 +18,7 @@
   - [Upgrading the state](#upgrading-the-state)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- /TOC -->
 
 ## Introduction
 
@@ -29,7 +33,6 @@ Warning: this configuration is not definitive.
 | `EIP6800_FORK_VERSION` | `Version('0x05000000')` |
 | `EIP6800_FORK_EPOCH` | `Epoch(18446744073709551615)` **TBD** |
 
-
 ## Helper functions
 
 ### Misc

specs/_features/eip6914/beacon-chain.md

@@ -1,5 +1,7 @@
 # EIP-6914 -- The Beacon Chain
 
+**Notice**: This document is a work-in-progress for researchers and implementers.
+
 ## Table of contents
 
 <!-- TOC -->

specs/_features/eip6914/fork-choice.md

@@ -1,5 +1,7 @@
 # EIP-6914 -- Fork Choice
 
+**Notice**: This document is a work-in-progress for researchers and implementers.
+
 ## Table of contents
 
 <!-- TOC -->

specs/_features/eip7732/beacon-chain.md

@@ -1,5 +1,7 @@
 # EIP-7732 -- The Beacon Chain
 
+**Notice**: This document is a work-in-progress for researchers and implementers.
+
 ## Table of contents
 
 <!-- TOC -->

specs/_features/eip7732/builder.md

@@ -1,7 +1,10 @@
 # EIP-7732 -- Honest Builder
 
-This is an accompanying document which describes the expected actions of a "builder" participating in the Ethereum proof-of-stake protocol.
+**Notice**: This document is a work-in-progress for researchers and implementers.
+
+## 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 -->
 
@@ -13,9 +16,12 @@ This is an accompanying document which describes the expected actions of a "buil
   - [Honest payload withheld messages](#honest-payload-withheld-messages)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- /TOC -->
 
 ## Introduction
 
+This is an accompanying document which describes the expected actions of a "builder" participating in the Ethereum proof-of-stake protocol.
+
 With the EIP-7732 Fork, the protocol includes new staked participants of the protocol called *Builders*. While Builders are a subset of the validator set, they have extra attributions that are optional. Validators may opt to not be builders and as such we collect the set of guidelines for those validators that want to act as builders in this document.
 
 ## Builders attributions
@@ -113,14 +119,17 @@ To construct the `execution_payload_envelope` the builder must perform the follo
 After setting these parameters, the builder should run `process_execution_payload(state, signed_envelope, verify=False)` and this function should not trigger an exception.
 
 6. Set `state_root` to `hash_tree_root(state)`.
+
 After preparing the `envelope` the builder should sign the envelope using:
+
 ```python
 def get_execution_payload_envelope_signature(
         state: BeaconState, envelope: ExecutionPayloadEnvelope, privkey: int) -> BLSSignature:
     domain = get_domain(state, DOMAIN_BEACON_BUILDER, compute_epoch_at_slot(state.slot))
     signing_root = compute_signing_root(envelope, domain)
     return bls.Sign(privkey, signing_root)
 ```
+
 The builder assembles then `signed_execution_payload_envelope = SignedExecutionPayloadEnvelope(message=envelope, signature=signature)` and broadcasts it on the `execution_payload` global gossip topic.
 
 ### Honest payload withheld messages