Doc merge requirements (#360)

* draft of merge requirements * Update docs/Concepts/PreparingForTheMerge.md Co-authored-by: Adrian Sutton <adrian@symphonious.net> * Update docs/Concepts/PreparingForTheMerge.md Co-authored-by: Adrian Sutton <adrian@symphonious.net> * Update docs/Concepts/PreparingForTheMerge.md Co-authored-by: Adrian Sutton <adrian@symphonious.net> * Update docs/Concepts/PreparingForTheMerge.md Co-authored-by: Adrian Sutton <adrian@symphonious.net> * Update docs/Concepts/PreparingForTheMerge.md Co-authored-by: Adrian Sutton <adrian@symphonious.net> * review feedback * review feedback * update Merge content * minor edits * updating submodule to latest * minor clarifications * integrate reviewer comments * integrate reviewer feedback * fix Vale install process * extract only vale bin * arrrrrg tar options... Co-authored-by: Adrian Sutton <adrian@symphonious.net> Co-authored-by: Alexandra Tran <alexandratran@protonmail.com> Co-authored-by: Nicolas MASSART <nicolas.massart@consensys.net>
Consensys · May 20, 2022 · 18d46b4 · 18d46b4
1 parent 5af8edb
commit 18d46b4
Show file tree

Hide file tree

Showing 7 changed files with 151 additions and 24 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -67,7 +67,8 @@ jobs:
  - run:
  name: Install dependencies
  command: |
- curl -sfL https://install.goreleaser.com/github.com/ValeLint/vale.sh | sh -s v2.4.2
+ wget https://github.com/errata-ai/vale/releases/download/v2.6.0/vale_2.6.0_Linux_64-bit.tar.gz
+ mkdir bin && tar -xvzf vale_2.6.0_Linux_64-bit.tar.gz -C bin vale
  - run:
  name: Run Vale
  command: |

diff --git a/common b/common
diff --git a/docs/Concepts/Merge.md b/docs/Concepts/Merge.md
@@ -4,11 +4,14 @@ description: What is the Merge?
 
 # The Merge
 
-The Ethereum upgrade known as [The Merge](https://ethereum.org/en/upgrades/merge/) will merge the [Beacon Chain] into
-Ethereum Mainnet, turning Mainnet into a combination of an
-[execution layer and consensus layer](#execution-and-consensus-clients).
+The Ethereum upgrade known as [The Merge](https://ethereum.org/en/upgrades/merge/) will merge the
+[Beacon Chain](https://ethereum.org/en/upgrades/beacon-chain/) into Ethereum Mainnet, turning Mainnet into a combination
+of an [execution layer and consensus layer](#execution-and-consensus-clients).
 The Merge will transition Mainnet from proof of work to [proof of stake consensus](Proof-of-Stake.md).
 
+You can [prepare Teku for The Merge](../HowTo/Prepare-for-The-Merge.md) and
+[test Teku with Hyperledger Besu on the Kiln Merge testnet](https://besu.hyperledger.org/en/stable/Tutorials/Merge-Testnet/).
+
 ## Execution and consensus clients
 
 After The Merge, a full Ethereum Mainnet node will be a combination of an execution client (previously called an
@@ -22,29 +25,40 @@ Execution and consensus clients communicate with each other using the
 
 ### Execution clients
 
-Execution clients, such as [Besu], manage the state and execute transactions on the execution layer.
+Execution clients, such as [Besu](https://besu.hyperledger.org/en/stable/), manage the execution layer, including
+executing transactions and updating the world state.
 Execution clients serve [JSON-RPC API](https://besu.hyperledger.org/en/stable/Reference/API-Methods/) requests and
 communicate with each other in a peer-to-peer network.
 
 ### Consensus clients
 
 Consensus clients, such as Teku, contain beacon node and validator client implementations.
-The beacon node is the primary link to the [Beacon Chain] (consensus layer).
+The beacon node is the primary link to the [Beacon Chain](https://ethereum.org/en/upgrades/beacon-chain/) (consensus layer).
 The validator client performs [validator duties](Proof-of-Stake.md) on the consensus layer.
 Consensus clients serve [REST API](../Reference/Rest_API/Rest.md) requests and communicate with each other in a
 peer-to-peer network.
 
-### Run a node
+## What happens during The Merge
+
+Before The Merge, the execution and consensus clients' configurations will be
+[updated](../HowTo/Prepare-for-The-Merge.md#update-teku) to listen for a certain total terminal difficulty (TTD) to be
+reached on the [execution endpoint](../Reference/CLI/CLI-Syntax.md#ee-endpoint).
+
+Teku will periodically request information about the execution client's configuration to check that they agree on the
+configuration and can connect.
+Teku will log warnings if the configuration doesn't match.
+
+The consensus layer will enable the Merge configuration (Bellatrix) before reaching the TTD.
+Once the execution layer blocks reach the TTD, the Beacon Chain will merge into Ethereum Mainnet, and Ethereum will move
+to a proof of stake network.
 
 After The Merge, a Mainnet node operator must run both an execution client and a beacon node at the same time.
 To become a validator, you must also run a validator client (either
 [in the same process as the beacon node](../HowTo/Get-Started/Run-Teku.md#start-the-clients-in-a-single-process) or
-[separately](../HowTo/Get-Started/Run-Teku.md#run-the-clients-separately).
-
-You can [test Teku with Besu on the Kiln Merge testnet](https://besu.hyperledger.org/en/latest/Tutorials/Merge-Testnet/).
+[separately](../HowTo/Get-Started/Run-Teku.md#run-the-clients-separately)).
 
-You can [run Teku with Besu on Ethereum Mainnet](../HowTo/Get-Started/Connect/Connect-To-Mainnet.md).
+After The Merge, in addition to validators earning rewards for performing [validator duties](Proof-of-Stake.md),
+[fee recipients](../HowTo/Prepare-for-The-Merge.md#fee-recipient) will also earn rewards for the inclusion of execution
+layer transactions.
 
-<!-- links -->
-[Beacon Chain]: https://ethereum.org/en/upgrades/beacon-chain/
-[Besu]: https://besu.hyperledger.org/en/stable/
+You can [prepare Teku for The Merge](../HowTo/Prepare-for-The-Merge.md).
diff --git a/docs/Concepts/Proof-of-Stake.md b/docs/Concepts/Proof-of-Stake.md
@@ -28,6 +28,8 @@ Proposers are responsible for proposing new consensus blocks, and non-proposing
 validating (attesting to) proposed blocks.
 Validators are rewarded for proposing and attesting to consensus blocks eventually included in the Beacon Chain, and
 penalized for malicious behavior.
+Validators also receive [transaction fees](../HowTo/Prepare-for-The-Merge.md#configure-the-fee-recipient) for included
+blocks.
 
 Each consensus block contains an execution payload, which contains a list of transactions and other data required to
 execute and validate the payload.

diff --git a/docs/HowTo/Prepare-for-The-Merge.md b/docs/HowTo/Prepare-for-The-Merge.md
@@ -0,0 +1,100 @@
+---
+description: How to prepare for The Merge
+---
+
+# Prepare for The Merge
+
+If you're running one or more Teku beacon nodes and validators on Ethereum Mainnet, prepare for
+[The Merge](../Concepts/Merge.md) by:
+
+1. [Configuring the execution client](#configure-the-execution-client).
+1. [Configuring the fee recipient](#configure-the-fee-recipient).
+1. [Staying up to date on Teku releases](#update-teku).
+
+You can make the configuration changes in Teku's [configuration file](Configure/Use-Configuration-File.md) before The Merge.
+
+You can also
+[test Teku with Hyperledger Besu on the Kiln Merge testnet](https://besu.hyperledger.org/en/stable/Tutorials/Merge-Testnet/).
+
+## Configure the execution client
+
+Before The Merge, validators require an [execution client](../Concepts/Merge.md#execution-clients) to get deposits for
+block proposals.
+Block proposals are intermittent, and a validator can get the data from other blocks if its execution client is offline.
+
+After The Merge, execution clients will play a more crucial role in executing transactions.
+Service providers that provide execution layer access, such as Infura, won't be adequate for a beacon node to continue
+to function on the network.
+You must set up an execution client for each beacon node you maintain, using the following steps.
+You can use any execution client with Teku.
+
+!!! note "Notes"
+
+ - After The Merge, a beacon node won't be able to have a failover execution client; a validator client will need a
+  beacon node and execution client pair to provide failover functionality.
+ - When planning your solution, take into account that the traffic between the execution client and beacon node
+  will be relatively high.
+
+### 1. Configure the execution endpoint
+
+Specify the execution client endpoint using [`ee-endpoint`](../Reference/CLI/CLI-Syntax.md#ee-endpoint) in the Teku
+configuration file.
+This can replace [`eth1-endpoint`](../Reference/CLI/CLI-Syntax.md#eth1-endpoint-eth1-endpoints).
+
+!!! important
+
+ After The Merge, you can't use `eth1-endpoint` to specify an external execution layer provider.
+ This option will be replaced by specifying `ee-endpoint` for each beacon node.
+
+### 2. Sync the execution client
+
+Validators can't produce attestations or blocks without a fully synced execution endpoint.
+To expedite network participation, sync your execution client on Ethereum Mainnet before the Merge configuration
+(Bellatrix) comes online.
+
+### 3. Configure the Java Web Token
+
+Java Web Token (JWT) authentication is used to secure the communication between the beacon node and execution client.
+You can generate a JWT using a command line tool, for example:
+
+```bash
+openssl rand -hex 32 -out <file>
+```
+
+Provide the JWT to Teku using the [`ee-jwt-secret-file`](../Reference/CLI/CLI-Syntax.md#ee-jwt-secret-file)
+configuration option, and to the execution client using its configuration options.
+For example, provide the JWT to [Hyperledger Besu](https://besu.hyperledger.org/) using the
+[`engine-jwt-secret`](https://besu.hyperledger.org/en/stable/Reference/CLI/CLI-Syntax/#engine-jwt-secret) option.
+
+## Configure the fee recipient
+
+After The Merge, execution layer transactions will be included in beacon node blocks, and validators will earn
+transaction fees.
+You can configure the recipient of these fees for each validator key.
+
+For simpler configurations, configure the beacon node (and validator client if
+[run in a separate process](Get-Started/Run-Teku.md#run-the-clients-separately)) with a default fee recipient using
+the [`validators-proposer-default-fee-recipient`](../Reference/CLI/CLI-Syntax.md#validators-proposer-default-fee-recipient)
+option.
+This fee recipient will be used for any duties performed by the beacon node.
+
+For more complex configurations, provide a proposer configuration file that defines the default fee recipient plus
+non-default fee recipients for any validators using the
+[`validators-proposer-config`](../Reference/CLI/CLI-Syntax.md#validators-proposer-config) option.
+
+A full consensus client (beacon node and validator client combined) can use either configuration option.
+A stand-alone validator client should only specify `validators-proposer-config`, and its attached beacon node should
+specify `validators-proposer-default-fee-recipient`.
+
+## Update Teku
+
+Once Bellatrix is scheduled for activation on Mainnet, Teku will be released with updated configuration for Mainnet.
+Ensure your Teku client and execution client is up to date before Bellatrix is enabled.
+
+You can follow Teku notifications by:
+
+- Signing up to the [release announcements](https://pages.consensys.net/teku-sign-up) email list (release and important
+ announcements only, no marketing).
+- Following Teku on [Twitter](https://twitter.com/Teku_ConsenSys).
+- Following the Teku channel in the ConsenSys [Discord](https://discord.gg/7hPv2T6).
+- Subscribing to release notifications on GitHub for [Teku](https://github.com/ConsenSys/teku).
diff --git a/docs/Reference/CLI/CLI-Syntax.md b/docs/Reference/CLI/CLI-Syntax.md
@@ -288,7 +288,8 @@ is specified using [`--data-base-path`](#data-base-path-data-path).
  ee-endpoint: "http://localhost:8550"
  ```
 
-URL of the [execution client's](../../Concepts/Merge.md#execution-and-consensus-clients) Engine JSON-RPC APIs.
+URL of the [execution client's](../../Concepts/Merge.md#execution-clients) Engine JSON-RPC APIs.
+This replaces [`eth1-endpoint`](#eth1-endpoint-eth1-endpoints) after [The Merge](../../Concepts/Merge.md).
 
 ### ee-jwt-secret-file
 
@@ -320,7 +321,7 @@ Shared secret used to authenticate [execution clients](../../Concepts/Merge.md#e
 using the Engine JSON-RPC API.
 Contents of file must be 32 hex-encoded bytes.
 May be a relative or absolute path.
-See an [example of how to generate this](https://besu.hyperledger.org/en/latest/Tutorials/Merge-Testnet/).
+See an [example of how to generate this](../../HowTo/Prepare-for-The-Merge.md#configure-the-java-web-token).
 
 ### eth1-deposit-contract-address
 
@@ -413,18 +414,25 @@ receiving warnings that the ETH1 node is unavailable.
  eth1-endpoint: ["http://localhost:8545","https://mainnet.infura.io/v3/d0e21ccd0b1e4eef7784422eabc51111"]
  ```
 
-Comma-separated list of JSON-RPC URLs of execution layer (Ethereum 1.0) nodes. Each time Teku makes a call, it finds
-the first provider in the list that is available, on the right chain, and in sync. This option must
-be specified if running a validator.
+Comma-separated list of JSON-RPC URLs of execution layer (Ethereum 1.0) nodes.
+Each time Teku makes a call, it finds the first provider in the list that is available, on the right chain, and in sync.
+This option must be specified if running a validator.
 
 If not specified (that is, you're running a beacon node only), then provide an initial state
 using the [`--initial-state`](#initial-state) option, or start Teku from an existing database using
 [`--data-path`](#data-base-path-data-path), which provides the initial state to work from. You do not need to
 provide an initial state if running a public network which has already started (for example,
 Mainnet or Prater).
 
-If using a cloud-based service such as [Infura], then set the endpoint to the supplied URL. For
-example, `https://goerli.infura.io/v3/<Project_ID>`
+If using a cloud-based service such as [Infura], then set the endpoint to the supplied URL.
+For example, `https://goerli.infura.io/v3/<Project_ID>`.
+
+!!! important
+
+ After [The Merge](../../Concepts/Merge.md), you can't use `eth1-endpoint` to specify an external execution layer
+ provider.
+ This option will be replaced by [`ee-endpoint`](#ee-endpoint) for each beacon node.
+ You can [configure your execution client](../../HowTo/Prepare-for-The-Merge.md) before The Merge.
 
 ### help
 
@@ -2377,7 +2385,8 @@ When `LOGGING` is enabled, attestation and block performance is reported as log
  validators-proposer-config: "/home/me/node/proposerConfig.json"
  ```
 
-Remote URL or local file path to the proposer configuration file, which is a JSON file that specifies:
+Remote URL or local file path to the [proposer configuration file](../../HowTo/Prepare-for-The-Merge.md), which is a
+JSON file that specifies:
 
 * `proposer_config` - (optional) A proposer configuration for multiple validator public keys.
 * `default_config` - (required) A default proposer configuration for validator public keys not included in
@@ -2456,7 +2465,7 @@ The default is `false`.
  validators-proposer-default-fee-recipient: "0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"
  ```
 
-Default fee recipient for all validator keys.
+Default [fee recipient](../../HowTo/Prepare-for-The-Merge.md#configure-the-fee-recipient) for all validator keys.
 When running a validator, this is an alternative to the `fee_recipient` in the
 [default proposer configuration](#validators-proposer-config).
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -80,6 +80,7 @@ nav:
  - Specify NAT methods: HowTo/Find-and-Connect/Specifying-NAT.md
  - Voluntary exit: HowTo/Voluntary-Exit.md
  - Migrate database: HowTo/Migrate-Database.md
+ - Prepare for The Merge: HowTo/Prepare-for-The-Merge.md
  - Troubleshoot:
  - Solve common problems: HowTo/Troubleshoot/Troubleshooting.md
  - Concepts: