Skip to content

Commit aab4a8d

Browse files
committed
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 (#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.
1 parent 18c61a5 commit aab4a8d

File tree

6 files changed

+79
-28
lines changed

6 files changed

+79
-28
lines changed

beacon_node/src/cli.rs

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -235,6 +235,7 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
235235
.arg(
236236
Arg::with_name("http-spec-fork")
237237
.long("http-spec-fork")
238+
.value_name("FORK")
238239
.help("Serve the spec for a specific hard fork on /eth/v1/config/spec. It should \
239240
not be necessary to set this flag.")
240241
.takes_value(true)
@@ -327,9 +328,9 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
327328
.arg(
328329
Arg::with_name("staking")
329330
.long("staking")
330-
.help("Standard option for a staking beacon node. Equivalent to \
331-
`lighthouse bn --http --eth1 `. This will enable the http server on localhost:5052 \
332-
and try connecting to an eth1 node on localhost:8545")
331+
.help("Standard option for a staking beacon node. This will enable the HTTP server \
332+
on localhost:5052 and import deposit logs from the execution node. This is \
333+
equivalent to `--http` on merge-ready networks, or `--http --eth1` pre-merge")
333334
.takes_value(false)
334335
)
335336

@@ -419,16 +420,16 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
419420
.help("Deprecated. The feature activates automatically when --execution-endpoint \
420421
is supplied.")
421422
.takes_value(false)
423+
.hidden(true)
422424
)
423425
.arg(
424426
Arg::with_name("execution-endpoint")
425427
.long("execution-endpoint")
426428
.value_name("EXECUTION-ENDPOINT")
427429
.alias("execution-endpoints")
428-
.help("Server endpoint for an execution layer jwt authenticated HTTP \
430+
.help("Server endpoint for an execution layer JWT-authenticated HTTP \
429431
JSON-RPC connection. Uses the same endpoint to populate the \
430-
deposit cache. Also enables the --merge flag.\
431-
If not provided, uses the default value of http://127.0.0.1:8551")
432+
deposit cache.")
432433
.takes_value(true)
433434
.requires("execution-jwt")
434435
)
@@ -439,6 +440,7 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
439440
.alias("jwt-secrets")
440441
.help("File path which contains the hex-encoded JWT secret for the \
441442
execution endpoint provided in the --execution-endpoint flag.")
443+
.requires("execution-endpoint")
442444
.takes_value(true)
443445
)
444446
.arg(
@@ -449,6 +451,7 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
449451
.help("Used by the beacon node to communicate a unique identifier to execution nodes \
450452
during JWT authentication. It corresponds to the 'id' field in the JWT claims object.\
451453
Set to empty by default")
454+
.requires("execution-jwt")
452455
.takes_value(true)
453456
)
454457
.arg(
@@ -459,16 +462,16 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
459462
.help("Used by the beacon node to communicate a client version to execution nodes \
460463
during JWT authentication. It corresponds to the 'clv' field in the JWT claims object.\
461464
Set to empty by default")
465+
.requires("execution-jwt")
462466
.takes_value(true)
463467
)
464468
.arg(
465469
Arg::with_name("suggested-fee-recipient")
466470
.long("suggested-fee-recipient")
467471
.value_name("SUGGESTED-FEE-RECIPIENT")
468-
.help("Once the merge has happened, this address will receive transaction fees \
469-
collected from any blocks produced by this node. Defaults to a junk \
470-
address whilst the merge is in development stages. THE DEFAULT VALUE \
471-
WILL BE REMOVED BEFORE THE MERGE ENTERS PRODUCTION")
472+
.help("Emergency fallback fee recipient for use in case the validator client does \
473+
not have one configured. You should set this flag on the validator \
474+
client instead of (or in addition to) setting it here.")
472475
.requires("execution-endpoint")
473476
.takes_value(true)
474477
)
@@ -632,6 +635,7 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
632635
.arg(
633636
Arg::with_name("slasher-backend")
634637
.long("slasher-backend")
638+
.value_name("DATABASE")
635639
.help("Set the database backend to be used by the slasher.")
636640
.takes_value(true)
637641
.possible_values(slasher::DatabaseBackend::VARIANTS)

book/src/database-migrations.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ validator client or the slasher**.
2222
| v2.3.0 | May 2022 | v9 | yes (pre Bellatrix) |
2323
| v2.4.0 | Jul 2022 | v9 | yes (pre Bellatrix) |
2424
| v2.5.0 | Aug 2022 | v11 | yes |
25+
| v3.0.0 | Aug 2022 | v11 | yes |
2526

2627
> **Note**: All point releases (e.g. v2.3.1) are schema-compatible with the prior minor release
2728
> (e.g. v2.3.0).

book/src/merge-migration.md

Lines changed: 51 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
This document provides detail for users who want to run a merge-ready Lighthouse node.
44

5-
> If you are running a testnet node, this configuration is necessary _now_.
5+
> The merge is occuring on mainnet in September. You _must_ have a merge-ready setup by September 6
6+
> 2022.
67
78
## Necessary Configuration
89

@@ -17,20 +18,20 @@ the merge:
1718
receive transactions tips from blocks proposed by your validators. This is covered on the
1819
[Suggested fee recipient](./suggested-fee-recipient.md) page.
1920

20-
Additionally, you _must_ update Lighthouse to a merge-compatible release in the weeks before
21-
the merge. Merge releases are available now for all testnets.
21+
Additionally, you _must_ update Lighthouse to v3.0.0 (or later), and must update your execution
22+
engine to a merge-ready version.
2223

2324
## When?
2425

2526
You must configure your node to be merge-ready before the Bellatrix fork occurs on the network
2627
on which your node is operating.
2728

28-
* **Mainnet**: the Bellatrix fork epoch has not yet been announced. It's possible to set up a
29-
merge-ready node now, but some execution engines will require additional configuration. Please see
30-
the section on [Execution engine configuration](#execution-engine-configuration) below.
29+
* **Mainnet**: the Bellatrix fork is scheduled for epoch 144896, September 6 2022 11:34 UTC.
30+
You must ensure your node configuration is updated before then in order to continue following
31+
the chain. We recommend updating your configuration now.
3132

32-
* **Goerli (Prater)**, **Ropsten**, **Sepolia**, **Kiln**: you must have a merge-ready configuration
33-
right now.
33+
* **Goerli (Prater)**, **Ropsten**, **Sepolia**, **Kiln**: the Bellatrix fork has already occurred.
34+
You must have a merge-ready configuration right now.
3435

3536
## Connecting to an execution engine
3637

@@ -46,6 +47,11 @@ If you set up an execution engine with `--execution-endpoint` then you *must* pr
4647
using `--execution-jwt`. This is a mandatory form of authentication that ensures that Lighthouse
4748
has authority to control the execution engine.
4849

50+
The execution engine connection must be **exclusive**, i.e. you must have one execution node
51+
per beacon node. The reason for this is that the beacon node _controls_ the execution node. Please
52+
see the [FAQ](#faq) for further information about why many:1 and 1:many configurations are not
53+
supported.
54+
4955
### Execution engine configuration
5056

5157
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
5965
should add the URL to your `lighthouse bn` flags with `--execution-endpoint <URL>`, as well as
6066
the path to the JWT secret with `--execution-jwt <FILE>`.
6167

62-
> NOTE: Geth v1.10.21 or earlier requires a manual TTD override to communicate with Lighthouse over
63-
> the engine API on mainnet. We recommend waiting for a compatible Geth release before configuring
64-
> Lighthouse-Geth on mainnet.
68+
There are merge-ready releases of all compatible execution engines available now.
6569

6670
### Example
6771

@@ -138,16 +142,50 @@ be used for all such queries. Therefore we can say that where `--execution-endpo
138142

139143
## FAQ
140144

145+
### How do I know if my node is set up correctly?
146+
147+
Lighthouse will log a message indicating that it is ready for the merge:
148+
149+
```
150+
INFO Ready for the merge, current_difficulty: 10789363, terminal_total_difficulty: 10790000
151+
```
152+
153+
Once the merge has occurred you should see that Lighthouse remains in sync and marks blocks
154+
as `verified` indicating that they have been processed successfully by the execution engine:
155+
156+
```
157+
INFO Synced, slot: 3690668, block: 0x1244…cb92, epoch: 115333, finalized_epoch: 115331, finalized_root: 0x0764…2a3d, exec_hash: 0x929c…1ff6 (verified), peers: 78
158+
```
159+
160+
### Can I still use the `--staking` flag?
161+
162+
Yes. The `--staking` flag is just an alias for `--http --eth1`. The `--eth1` flag is now superfluous
163+
so `--staking` is equivalent to `--http`. You need either `--staking` or `--http` for the validator
164+
client to be able to connect to the beacon node.
165+
141166
### Can I use `http://localhost:8545` for the execution endpoint?
142167

143168
Most execution nodes use port `8545` for the Ethereum JSON-RPC API. Unless custom configuration is
144169
used, an execution node _will not_ provide the necessary engine API on port `8545`. You should
145170
not attempt to use `http://localhost:8545` as your engine URL and should instead use
146171
`http://localhost:8551`.
147172

148-
### What about multiple execution endpoints?
173+
### Can I share an execution node between multiple beacon nodes (many:1)?
174+
175+
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.
176+
177+
The beacon node controls the execution node via the engine API, telling it which block is the
178+
current head of the chain. If multiple beacon nodes were to connect to a single execution node they
179+
could set conflicting head blocks, leading to frequent re-orgs on the execution node.
180+
181+
We imagine that in future there will be HTTP proxies available which allow users to nominate a
182+
single controlling beacon node, while allowing consistent updates from other beacon nodes.
183+
184+
### What about multiple execution endpoints (1:many)?
185+
186+
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.
149187

150-
Since an execution engine can only have one connected BN, the value of having multiple execution
188+
Since an execution engine can only have one controlling BN, the value of having multiple execution
151189
engines connected to the same BN is very low. An execution engine cannot be shared between BNs to
152190
reduce costs.
153191

book/src/suggested-fee-recipient.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,10 @@ Assuming trustworthy nodes, the priority for the three methods is:
3434
1. `--suggested-fee-recipient` provided to the VC.
3535
1. `--suggested-fee-recipient` provided to the BN.
3636

37+
> **NOTE**: It is **not** recommended to _only_ set the fee recipient on the beacon node, as this results
38+
> in sub-optimal block proposals. See [this issue](https://github.com/sigp/lighthouse/issues/3432)
39+
> for details.
40+
3741
### 1. Setting the fee recipient in the `validator_definitions.yml`
3842

3943
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.
6670
The `--suggested-fee-recipient` can be provided to the BN to act as a default value when the
6771
validator client does not transmit a `suggested_fee_recipient` to the BN.
6872

73+
**This value should be considered an emergency fallback**. You should set the fee recipient in the
74+
validator client in order for the execution node to be given adequate notice of block proposal.
75+
6976
## Setting the fee recipient dynamically using the keymanager API
7077

7178
When the [validator client API](api-vc.md) is enabled, the

lighthouse/src/main.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -227,7 +227,7 @@ fn main() {
227227
Accepts a 256-bit decimal integer (not a hex value). \
228228
This flag should only be used if the user has a clear understanding that \
229229
the broad Ethereum community has elected to override the terminal difficulty. \
230-
Incorrect use of this flag will cause your node to experience a consensus
230+
Incorrect use of this flag will cause your node to experience a consensus \
231231
failure. Be extremely careful with this flag.")
232232
.takes_value(true)
233233
.global(true)
@@ -239,7 +239,7 @@ fn main() {
239239
.help("Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH parameter. \
240240
This flag should only be used if the user has a clear understanding that \
241241
the broad Ethereum community has elected to override the terminal PoW block. \
242-
Incorrect use of this flag will cause your node to experience a consensus
242+
Incorrect use of this flag will cause your node to experience a consensus \
243243
failure. Be extremely careful with this flag.")
244244
.requires("terminal-block-hash-epoch-override")
245245
.takes_value(true)
@@ -252,7 +252,7 @@ fn main() {
252252
.help("Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH \
253253
parameter. This flag should only be used if the user has a clear understanding \
254254
that the broad Ethereum community has elected to override the terminal PoW block. \
255-
Incorrect use of this flag will cause your node to experience a consensus
255+
Incorrect use of this flag will cause your node to experience a consensus \
256256
failure. Be extremely careful with this flag.")
257257
.requires("terminal-block-hash-override")
258258
.takes_value(true)

validator_client/src/cli.rs

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -131,8 +131,9 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> {
131131
.arg(
132132
Arg::with_name("suggested-fee-recipient")
133133
.long("suggested-fee-recipient")
134-
.help("The fallback address provided to the BN if nothing suitable is found \
135-
in the validator definitions or fee recipient file.")
134+
.help("Once the merge has happened, this address will receive transaction fees \
135+
from blocks proposed by this validator client. If a fee recipient is \
136+
configured in the validator definitions it takes priority over this value.")
136137
.value_name("FEE-RECIPIENT")
137138
.takes_value(true)
138139
)

0 commit comments

Comments
 (0)