Update docs for mainnet merge release (#3494)

## Proposed Changes

Update the merge migration docs to encourage updating mainnet configs _now_!

The docs are also updated to recommend _against_ `--suggested-fee-recipient` on the beacon node (https://github.com/sigp/lighthouse/issues/3432).

Additionally the `--help` for the CLI is updated to match with a few small semantic changes:

- `--execution-jwt` is no longer allowed without `--execution-endpoint`. We've ended up without a default for `--execution-endpoint`, so I think that's fine.
- The flags related to the JWT are only allowed if `--execution-jwt` is provided.

beacon_node/src/cli.rs

@@ -235,6 +235,7 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
         .arg(
             Arg::with_name("http-spec-fork")
                 .long("http-spec-fork")
+                .value_name("FORK")
                 .help("Serve the spec for a specific hard fork on /eth/v1/config/spec. It should \
                        not be necessary to set this flag.")
                 .takes_value(true)
@@ -327,9 +328,9 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
         .arg(
             Arg::with_name("staking")
                 .long("staking")
-                .help("Standard option for a staking beacon node. Equivalent to \
+                .help("Standard option for a staking beacon node. This will enable the HTTP server \
-                `lighthouse bn --http --eth1 `. This will enable the http server on localhost:5052 \
+                       on localhost:5052 and import deposit logs from the execution node. This is \
-                and try connecting to an eth1 node on localhost:8545")
+                       equivalent to `--http` on merge-ready networks, or `--http --eth1` pre-merge")
                 .takes_value(false)
         )
 
@@ -419,16 +420,16 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
                 .help("Deprecated. The feature activates automatically when --execution-endpoint \
                     is supplied.")
                 .takes_value(false)
+                .hidden(true)
         )
         .arg(
             Arg::with_name("execution-endpoint")
                 .long("execution-endpoint")
                 .value_name("EXECUTION-ENDPOINT")
                 .alias("execution-endpoints")
-                .help("Server endpoint for an execution layer jwt authenticated HTTP \
+                .help("Server endpoint for an execution layer JWT-authenticated HTTP \
                        JSON-RPC connection. Uses the same endpoint to populate the \
-                       deposit cache. Also enables the --merge flag.\
+                       deposit cache.")
-                       If not provided, uses the default value of http://127.0.0.1:8551")
                 .takes_value(true)
                 .requires("execution-jwt")
         )
@@ -439,6 +440,7 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
                 .alias("jwt-secrets")
                 .help("File path which contains the hex-encoded JWT secret for the \
                        execution endpoint provided in the --execution-endpoint flag.")
+                .requires("execution-endpoint")
                 .takes_value(true)
         )
         .arg(
@@ -449,6 +451,7 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
                 .help("Used by the beacon node to communicate a unique identifier to execution nodes \
                        during JWT authentication. It corresponds to the 'id' field in the JWT claims object.\
                        Set to empty by default")
+                .requires("execution-jwt")
                 .takes_value(true)
         )
         .arg(
@@ -459,16 +462,16 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
                 .help("Used by the beacon node to communicate a client version to execution nodes \
                        during JWT authentication. It corresponds to the 'clv' field in the JWT claims object.\
                        Set to empty by default")
+                .requires("execution-jwt")
                 .takes_value(true)
         )
         .arg(
             Arg::with_name("suggested-fee-recipient")
                 .long("suggested-fee-recipient")
                 .value_name("SUGGESTED-FEE-RECIPIENT")
-                .help("Once the merge has happened, this address will receive transaction fees \
+                .help("Emergency fallback fee recipient for use in case the validator client does \
-                       collected from any blocks produced by this node. Defaults to a junk \
+                       not have one configured. You should set this flag on the validator \
-                       address whilst the merge is in development stages. THE DEFAULT VALUE \
+                       client instead of (or in addition to) setting it here.")
-                       WILL BE REMOVED BEFORE THE MERGE ENTERS PRODUCTION")
                 .requires("execution-endpoint")
                 .takes_value(true)
         )
@@ -632,6 +635,7 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
         .arg(
             Arg::with_name("slasher-backend")
                 .long("slasher-backend")
+                .value_name("DATABASE")
                 .help("Set the database backend to be used by the slasher.")
                 .takes_value(true)
                 .possible_values(slasher::DatabaseBackend::VARIANTS)

book/src/database-migrations.md

@@ -22,6 +22,7 @@ validator client or the slasher**.
 | v2.3.0             | May 2022     | v9             | yes (pre Bellatrix)  |
 | v2.4.0             | Jul 2022     | v9             | yes (pre Bellatrix)  |
 | v2.5.0             | Aug 2022     | v11            | yes                  |
+| v3.0.0             | Aug 2022     | v11            | yes                  |
 
 > **Note**: All point releases (e.g. v2.3.1) are schema-compatible with the prior minor release
 > (e.g. v2.3.0).

book/src/merge-migration.md

@@ -2,7 +2,8 @@
 
 This document provides detail for users who want to run a merge-ready Lighthouse node.
 
-> If you are running a testnet node, this configuration is necessary _now_.
+> The merge is occuring on mainnet in September. You _must_ have a merge-ready setup by September 6
+> 2022.
 
 ## Necessary Configuration
 
@@ -17,20 +18,20 @@ the merge:
    receive transactions tips from blocks proposed by your validators. This is covered on the
    [Suggested fee recipient](./suggested-fee-recipient.md) page.
 
-Additionally, you _must_ update Lighthouse to a merge-compatible release in the weeks before
+Additionally, you _must_ update Lighthouse to v3.0.0 (or later), and must update your execution
-the merge. Merge releases are available now for all testnets.
+engine to a merge-ready version.
 
 ## 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
+* **Mainnet**: the Bellatrix fork is scheduled for epoch 144896, September 6 2022 11:34 UTC.
-  merge-ready node now, but some execution engines will require additional configuration. Please see
+  You must ensure your node configuration is updated before then in order to continue following
-  the section on [Execution engine configuration](#execution-engine-configuration) below.
+  the chain. We recommend updating your configuration now.
 
-* **Goerli (Prater)**, **Ropsten**, **Sepolia**, **Kiln**: you must have a merge-ready configuration
+* **Goerli (Prater)**, **Ropsten**, **Sepolia**, **Kiln**: the Bellatrix fork has already occurred.
-  right now.
+  You must have a merge-ready configuration right now.
 
 ## Connecting to an execution engine
 
@@ -46,6 +47,11 @@ If you set up an execution engine with `--execution-endpoint` then you *must* pr
 using `--execution-jwt`. This is a mandatory form of authentication that ensures that Lighthouse
 has authority to control the execution engine.
 
+The execution engine connection must be **exclusive**, i.e. you must have one execution node
+per beacon node. The reason for this is that the beacon node _controls_ the execution node. Please
+see the [FAQ](#faq) for further information about why many:1 and 1:many configurations are not
+supported.
+
 ### Execution engine configuration
 
 Each execution engine has its own flags for configuring the engine API and JWT. Please consult
@@ -59,9 +65,7 @@ Once you have configured your execution engine to open up the engine API (usuall
 should add the URL to your `lighthouse bn` flags with `--execution-endpoint <URL>`, as well as
 the path to the JWT secret with `--execution-jwt <FILE>`.
 
-> NOTE: Geth v1.10.21 or earlier requires a manual TTD override to communicate with Lighthouse over
+There are merge-ready releases of all compatible execution engines available now.
-> the engine API on mainnet. We recommend waiting for a compatible Geth release before configuring
-> Lighthouse-Geth on mainnet.
 
 ### Example
 
@@ -138,6 +142,27 @@ be used for all such queries. Therefore we can say that where `--execution-endpo
 
 ## FAQ
 
+### How do I know if my node is set up correctly?
+
+Lighthouse will log a message indicating that it is ready for the merge:
+
+```
+INFO Ready for the merge, current_difficulty: 10789363, terminal_total_difficulty: 10790000
+```
+
+Once the merge has occurred you should see that Lighthouse remains in sync and marks blocks
+as `verified` indicating that they have been processed successfully by the execution engine:
+
+```
+INFO Synced, slot: 3690668, block: 0x1244…cb92, epoch: 115333, finalized_epoch: 115331, finalized_root: 0x0764…2a3d, exec_hash: 0x929c…1ff6 (verified), peers: 78
+```
+
+### Can I still use the `--staking` flag?
+
+Yes. The `--staking` flag is just an alias for `--http --eth1`. The `--eth1` flag is now superfluous
+so `--staking` is equivalent to `--http`. You need either `--staking` or `--http` for the validator
+client to be able to connect to the beacon node.
+
 ### 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
@@ -145,9 +170,22 @@ used, an execution node _will not_ provide the necessary engine API on port `854
 not attempt to use `http://localhost:8545` as your engine URL and should instead use
 `http://localhost:8551`.
 
-### What about multiple execution endpoints?
+### Can I share an execution node between multiple beacon nodes (many:1)?
 
-Since an execution engine can only have one connected BN, the value of having multiple execution
+It is **not** possible to connect more than one beacon node to the same execution engine. There must be a 1:1 relationship between beacon nodes and execution nodes.
+
+The beacon node controls the execution node via the engine API, telling it which block is the
+current head of the chain. If multiple beacon nodes were to connect to a single execution node they
+could set conflicting head blocks, leading to frequent re-orgs on the execution node.
+
+We imagine that in future there will be HTTP proxies available which allow users to nominate a
+single controlling beacon node, while allowing consistent updates from other beacon nodes.
+
+### What about multiple execution endpoints (1:many)?
+
+It is **not** possible to connect one beacon node to more than one execution engine. There must be a 1:1 relationship between beacon nodes and execution nodes.
+
+Since an execution engine can only have one controlling 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
 reduce costs.
 

book/src/suggested-fee-recipient.md

@@ -34,6 +34,10 @@ Assuming trustworthy nodes, the priority for the three methods is:
 1. `--suggested-fee-recipient` provided to the VC.
 1. `--suggested-fee-recipient` provided to the BN.
 
+> **NOTE**: It is **not** recommended to _only_ set the fee recipient on the beacon node, as this results
+> in sub-optimal block proposals. See [this issue](https://github.com/sigp/lighthouse/issues/3432)
+> for details.
+
 ### 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`
@@ -66,6 +70,9 @@ validators where a `suggested_fee_recipient` is not loaded from another method.
 The `--suggested-fee-recipient` can be provided to the BN to act as a default value when the
 validator client does not transmit a `suggested_fee_recipient` to the BN.
 
+**This value should be considered an emergency fallback**. You should set the fee recipient in the
+validator client in order for the execution node to be given adequate notice of block proposal.
+
 ## Setting the fee recipient dynamically using the keymanager API
 
 When the [validator client API](api-vc.md) is enabled, the

lighthouse/src/main.rs

@@ -227,7 +227,7 @@ fn main() {
                        Accepts a 256-bit decimal integer (not a hex value). \
                        This flag should only be used if the user has a clear understanding that \
                        the broad Ethereum community has elected to override the terminal difficulty. \
-                       Incorrect use of this flag will cause your node to experience a consensus
+                       Incorrect use of this flag will cause your node to experience a consensus \
                        failure. Be extremely careful with this flag.")
                 .takes_value(true)
                 .global(true)
@@ -239,7 +239,7 @@ fn main() {
                 .help("Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH parameter. \
                        This flag should only be used if the user has a clear understanding that \
                        the broad Ethereum community has elected to override the terminal PoW block. \
-                       Incorrect use of this flag will cause your node to experience a consensus
+                       Incorrect use of this flag will cause your node to experience a consensus \
                        failure. Be extremely careful with this flag.")
                 .requires("terminal-block-hash-epoch-override")
                 .takes_value(true)
@@ -252,7 +252,7 @@ fn main() {
                 .help("Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH \
                        parameter. This flag should only be used if the user has a clear understanding \
                        that the broad Ethereum community has elected to override the terminal PoW block. \
-                       Incorrect use of this flag will cause your node to experience a consensus
+                       Incorrect use of this flag will cause your node to experience a consensus \
                        failure. Be extremely careful with this flag.")
                 .requires("terminal-block-hash-override")
                 .takes_value(true)

validator_client/src/cli.rs

@@ -131,8 +131,9 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
         .arg(
             Arg::with_name("suggested-fee-recipient")
                 .long("suggested-fee-recipient")
-                .help("The fallback address provided to the BN if nothing suitable is found \
+                .help("Once the merge has happened, this address will receive transaction fees \
-                           in the validator definitions or fee recipient file.")
+                       from blocks proposed by this validator client. If a fee recipient is \
+                       configured in the validator definitions it takes priority over this value.")
                 .value_name("FEE-RECIPIENT")
                 .takes_value(true)
         )