From 18d46b4f52318e6f5aed8501999591d369353bce Mon Sep 17 00:00:00 2001 From: Paul Harris Date: Sat, 21 May 2022 04:38:46 +1000 Subject: [PATCH] Doc merge requirements (#360) * draft of merge requirements * Update docs/Concepts/PreparingForTheMerge.md Co-authored-by: Adrian Sutton * Update docs/Concepts/PreparingForTheMerge.md Co-authored-by: Adrian Sutton * Update docs/Concepts/PreparingForTheMerge.md Co-authored-by: Adrian Sutton * Update docs/Concepts/PreparingForTheMerge.md Co-authored-by: Adrian Sutton * Update docs/Concepts/PreparingForTheMerge.md Co-authored-by: Adrian Sutton * 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 Co-authored-by: Alexandra Tran Co-authored-by: Nicolas MASSART --- .circleci/config.yml | 3 +- common | 2 +- docs/Concepts/Merge.md | 40 +++++++---- docs/Concepts/Proof-of-Stake.md | 2 + docs/HowTo/Prepare-for-The-Merge.md | 100 ++++++++++++++++++++++++++++ docs/Reference/CLI/CLI-Syntax.md | 27 +++++--- mkdocs.yml | 1 + 7 files changed, 151 insertions(+), 24 deletions(-) create mode 100644 docs/HowTo/Prepare-for-The-Merge.md diff --git a/.circleci/config.yml b/.circleci/config.yml index df16db59f..0bd53b7fd 100644 --- 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 index d0264dd45..c24086119 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit d0264dd45a50ddf7e600d31cc07aa3bf76472bea +Subproject commit c2408611942188d6136ebe787b3da24aa41f72a1 diff --git a/docs/Concepts/Merge.md b/docs/Concepts/Merge.md index c3e714b98..c6288ba10 100644 --- 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. - -[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 index 98ad13aba..099b1e405 100644 --- 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 new file mode 100644 index 000000000..bad647d9b --- /dev/null +++ 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 +``` + +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 index e583a55c2..947c0be32 100644 --- 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,9 +414,9 @@ 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 @@ -423,8 +424,15 @@ using the [`--initial-state`](#initial-state) option, or start Teku from an exis 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/` +If using a cloud-based service such as [Infura], then set the endpoint to the supplied URL. +For example, `https://goerli.infura.io/v3/`. + +!!! 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 index 5520f59ea..147d91844 100644 --- 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: