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.
This commit is contained in:
Michael Sproul
parent
18c61a5e8b
commit
aab4a8d2f2
@ -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 \
|
||||
`lighthouse bn --http --eth1 `. This will enable the http server on localhost:5052 \
|
||||
and try connecting to an eth1 node on localhost:8545")
|
||||
.help("Standard option for a staking beacon node. This will enable the HTTP server \
|
||||
on localhost:5052 and import deposit logs from the execution node. This is \
|
||||
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.\
|
||||
If not provided, uses the default value of http://127.0.0.1:8551")
|
||||
deposit cache.")
|
||||
.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 \
|
||||
collected from any blocks produced by this node. Defaults to a junk \
|
||||
address whilst the merge is in development stages. THE DEFAULT VALUE \
|
||||
WILL BE REMOVED BEFORE THE MERGE ENTERS PRODUCTION")
|
||||
.help("Emergency fallback fee recipient for use in case the validator client does \
|
||||
not have one configured. You should set this flag on the validator \
|
||||
client instead of (or in addition to) setting it here.")
|
||||
.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)
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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
|
||||
the merge. Merge releases are available now for all testnets.
|
||||
Additionally, you _must_ update Lighthouse to v3.0.0 (or later), and must update your execution
|
||||
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
|
||||
merge-ready node now, but some execution engines will require additional configuration. Please see
|
||||
the section on [Execution engine configuration](#execution-engine-configuration) below.
|
||||
* **Mainnet**: the Bellatrix fork is scheduled for epoch 144896, September 6 2022 11:34 UTC.
|
||||
You must ensure your node configuration is updated before then in order to continue following
|
||||
the chain. We recommend updating your configuration now.
|
||||
|
||||
* **Goerli (Prater)**, **Ropsten**, **Sepolia**, **Kiln**: you must have a merge-ready configuration
|
||||
right now.
|
||||
* **Goerli (Prater)**, **Ropsten**, **Sepolia**, **Kiln**: the Bellatrix fork has already occurred.
|
||||
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
|
||||
> the engine API on mainnet. We recommend waiting for a compatible Geth release before configuring
|
||||
> Lighthouse-Geth on mainnet.
|
||||
There are merge-ready releases of all compatible execution engines available now.
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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 \
|
||||
in the validator definitions or fee recipient file.")
|
||||
.help("Once the merge has happened, this address will receive transaction fees \
|
||||
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)
|
||||
)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user