From 83666e04fd0aaff31249f94c7c01383a20927f58 Mon Sep 17 00:00:00 2001 From: Michael Sproul Date: Fri, 5 Aug 2022 06:46:59 +0000 Subject: [PATCH] Expand merge migration docs (#3430) ## Issue Addressed Resolves #3424 ## Proposed Changes This PR expands the merge migration docs to include (hopefully) clearer guidance on the steps required. It's inspired by @winksaville's work in #3426 but takes a more drastic approach to rewriting large sections. * Add a prominent _When?_ section * Add links to execution engine configuration guides * Add links to community guides * Fix the location of the _Strict fee recipient_ section --- book/src/merge-migration.md | 96 ++++++++++++++++++++++++----- book/src/suggested-fee-recipient.md | 41 +++++++----- 2 files changed, 108 insertions(+), 29 deletions(-) diff --git a/book/src/merge-migration.md b/book/src/merge-migration.md index 6ed6a9977..e2d54ea0a 100644 --- a/book/src/merge-migration.md +++ b/book/src/merge-migration.md @@ -1,20 +1,69 @@ # Merge Migration -This document provides detail for users who have been running a Lighthouse node *before* the merge -and are now preparing their node for the merge transition. +This document provides detail for users who want to run a merge-ready Lighthouse node. -## "Pre-Merge" and "Post-Merge" +> If you are running a testnet node, this configuration is necessary _now_. -As of [v2.4.0](https://github.com/sigp/lighthouse/releases/tag/v2.4.0) Lighthouse can be considered -to have two modes: +## Necessary Configuration -- "Pre-merge": `--execution-endpoint` flag *is not* provided. -- "Post-merge": `--execution-endpoint` flag *is* provided. +There are two configuration changes required for a Lighthouse node to operate correctly throughout +the merge: -A "pre-merge" node, by definition, will fail to transition through the merge. Such a node *must* be -upgraded before the Bellatrix upgrade. +1. You *must* run your own execution engine such as Geth or Nethermind alongside Lighthouse. + You *must* update your Lighthouse configuration to connect to the execution engine using new + flags which are documented on this page in the + [Connecting to an execution engine](#connecting-to-an-execution-engine) section. +2. If your Lighthouse node has validators attached you *must* nominate an Ethereum address to + receive transactions tips from blocks proposed by your validators. This is covered on the + [Suggested fee recipient](./suggested-fee-recipient.md) page. -## Migration +Additionally, you _must_ update Lighthouse to a merge-compatible release in the weeks before +the merge. Merge releases are available now for all testnets. + +## When? + +You must configure your node to be merge-ready before the Bellatrix fork occurs on the network +on which your node is operating. + +* **Mainnet**: the Bellatrix fork epoch has not yet been announced. It's possible to set up a + merge-ready node now, but some execution engines will require additional configuration. Please see + the section on [Execution engine configuration](#execution-engine-configuration) below. + +* **Goerli (Prater)**, **Ropsten**, **Sepolia**, **Kiln**: you must have a merge-ready configuration + right now. + +## Connecting to an execution engine + +The Lighthouse beacon node must connect to an execution engine in order to validate the transactions +present in post-merge blocks. Two new flags are used to configure this connection: + +- `--execution-endpoint `: the URL of the execution engine API. Often this will be + `http://localhost:8551`. +- `--execution-jwt `: the path to the file containing the JWT secret shared by Lighthouse and the + execution engine. + +If you set up an execution engine with `--execution-endpoint` then you *must* provide a JWT secret +using `--execution-jwt`. This is a mandatory form of authentication that ensures that Lighthouse +has authority to control the execution engine. + +### Execution engine configuration + +Each execution engine has its own flags for configuring the engine API and JWT. Please consult +the relevant page for your execution engine for the required flags: + +- [Geth: Connecting to Consensus Clients](https://geth.ethereum.org/docs/interface/consensus-clients) +- [Nethermind: Running Nethermind Post Merge](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge) +- [Besu: Prepare For The Merge](https://besu.hyperledger.org/en/stable/HowTo/Upgrade/Prepare-for-The-Merge/) + +Once you have configured your execution engine to open up the engine API (usually on port 8551) you +should add the URL to your `lighthouse bn` flags with `--execution-endpoint `, as well as +the path to the JWT secret with `--execution-jwt `. + +> NOTE: Geth v1.10.21 or earlier requires a manual TTD override to communicate with Lighthouse over +> the engine API on mainnet. We recommend waiting for a compatible Geth release before configuring +> Lighthouse-Geth on mainnet. + +### Example Let us look at an example of the command line arguments for a pre-merge production staking BN: @@ -60,10 +109,7 @@ merge are ensuring that `--execution-endpoint` and `--execution-jwt` flags are p you can even leave the `--eth1-endpoints` flag there, it will be ignored. This is not recommended as a deprecation warning will be logged and Lighthouse *may* remove these flags in the future. -There are no changes required for the validator client, apart from ensure it has been updated to the -same version as the beacon node. Check the version with `lighthouse --version`. - -## The relationship between `--eth1-endpoints` and `--execution-endpoint` +### The relationship between `--eth1-endpoints` and `--execution-endpoint` Pre-merge users will be familiar with the `--eth1-endpoints` flag. This provides a list of Ethereum "eth1" nodes (e.g., Geth, Nethermind, etc). Each beacon node (BN) can have multiple eth1 endpoints @@ -90,7 +136,16 @@ contains the transaction history of the Ethereum chain, there is no longer a nee be used for all such queries. Therefore we can say that where `--execution-endpoint` is included `--eth1-endpoints` should be omitted. -## What about multiple execution endpoints? +## FAQ + +### Can I use `http://localhost:8545` for the execution endpoint? + +Most execution nodes use port `8545` for the Ethereum JSON-RPC API. Unless custom configuration is +used, an execution node _will not_ provide the necessary engine API on port `8545`. You should +not attempt to use `http://localhost:8545` as your engine URL and should instead use +`http://localhost:8551`. + +### What about multiple execution endpoints? Since an execution engine can only have one connected BN, the value of having multiple execution engines connected to the same BN is very low. An execution engine cannot be shared between BNs to @@ -99,3 +154,14 @@ reduce costs. Whilst having multiple execution engines connected to a single BN might be useful for advanced testing scenarios, Lighthouse (and other consensus clients) have decided to support *only one* execution endpoint. Such scenarios could be resolved with a custom-made HTTP proxy. + +## Additional Resources + +There are several community-maintained guides which provide more background information, as well as +guidance for specific setups. + +- [Ethereum.org: The Merge](https://ethereum.org/en/upgrades/merge/) +- [Ethereum Staking Launchpad: Merge Readiness](https://launchpad.ethereum.org/en/merge-readiness). +- [CoinCashew: Ethereum Merge Upgrade Checklist](https://www.coincashew.com/coins/overview-eth/ethereum-merge-upgrade-checklist-for-home-stakers-and-validators) +- [EthDocker: Merge Preparation](https://eth-docker.net/docs/About/MergePrep/) +- [Remy Roy: How to join the Goerli/Prater merge testnet](https://github.com/remyroy/ethstaker/blob/main/merge-goerli-prater.md) diff --git a/book/src/suggested-fee-recipient.md b/book/src/suggested-fee-recipient.md index a584be306..d862cf1a6 100644 --- a/book/src/suggested-fee-recipient.md +++ b/book/src/suggested-fee-recipient.md @@ -1,8 +1,10 @@ # Suggested Fee Recipient -*Note: these documents are not relevant until the Bellatrix (Merge) upgrade has occurred.* +The _fee recipient_ is an Ethereum address nominated by a beacon chain validator to receive +tips from user transactions. If you run validators on a network that has already merged +or is due to merge soon then you should nominate a fee recipient for your validators. -## Fee recipient trust assumptions +## Background During post-merge block production, the Beacon Node (BN) will provide a `suggested_fee_recipient` to the execution node. This is a 20-byte Ethereum address which the EL might choose to set as the @@ -13,32 +15,25 @@ it may use any address it chooses. It is assumed that an honest execution node * `suggested_fee_recipient`, but users should note this trust assumption. Check out the [strict fee recipient](#strict-fee-recipient) section for how to mitigate this assumption. -The `suggested_fee_recipient` can be provided to the VC, who will transmit it to the BN. The BN also +The `suggested_fee_recipient` can be provided to the VC, which will transmit it to the BN. The BN also has a choice regarding the fee recipient it passes to the execution node, creating another noteworthy trust assumption. To be sure *you* control your fee recipient value, run your own BN and execution node (don't use third-party services). -The Lighthouse VC provides three methods for setting the `suggested_fee_recipient` (also known +## How to configure a suggested fee recipient + +The Lighthouse VC provides two methods for setting the `suggested_fee_recipient` (also known simply as the "fee recipient") to be passed to the execution layer during block production. The Lighthouse BN also provides a method for defining this value, should the VC not transmit a value. -Assuming trustworthy nodes, the priority for the four methods is: +Assuming trustworthy nodes, the priority for the three methods is: 1. `validator_definitions.yml` 1. `--suggested-fee-recipient` provided to the VC. 1. `--suggested-fee-recipient` provided to the BN. -## Strict Fee Recipient - -If the flag `--strict-fee-recipient` is set in the validator client, Lighthouse will refuse to sign any block whose -`fee_recipient` does not match the `suggested_fee_recipient` sent by this validator. This applies to both the normal -block proposal flow and block proposals through the builder API. Proposals through the builder API are more likely -to have a discrepancy in `fee_recipient` so you should be aware of how your connected relay sends proposer payments before -using this flag. If this flag is used, a fee recipient mismatch in the builder API flow will result in a fallback to the -local execution engine for payload construction, where a strict fee recipient check will still be applied. - ### 1. Setting the fee recipient in the `validator_definitions.yml` Users can set the fee recipient in `validator_definitions.yml` with the `suggested_fee_recipient` @@ -168,4 +163,22 @@ curl -X DELETE \ null ``` +## Strict Fee Recipient +If the flag `--strict-fee-recipient` is set in the validator client, Lighthouse will refuse to sign any block whose +`fee_recipient` does not match the `suggested_fee_recipient` sent by this validator. This applies to both the normal +block proposal flow and block proposals through the builder API. Proposals through the builder API are more likely +to have a discrepancy in `fee_recipient` so you should be aware of how your connected relay sends proposer payments before +using this flag. If this flag is used, a fee recipient mismatch in the builder API flow will result in a fallback to the +local execution engine for payload construction, where a strict fee recipient check will still be applied. + +## FAQ + +### Why do I have to nominate an Ethereum address as the fee recipient? + +You might wonder why the validator can't just accumulate transactions fees in the same way that it +accumulates other staking rewards. The reason for this is that transaction fees are computed and +validated by the execution node, and therefore need to be paid to an address that exists on the +execution chain. Validators use BLS keys which do not correspond to Ethereum addresses, so they +have no "presence" on the execution chain. Therefore it's necessary for each validator to nominate +a separate fee recipient address.