gnosis/lighthouse
1
0
Fork 0
mirror of https://github.com/sigp/lighthouse.git synced 2026-03-23 06:44:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update docs for mainnet merge release (#3494)

Browse Source 
## 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
2022-08-23 03:50:58 +00:00
parent 18c61a5e8b
commit aab4a8d2f2
6 changed files with 79 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
book/src/database-migrations.md
View File

@@ -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).

64
book/src/merge-migration.md
View File

@@ -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.

7
book/src/suggested-fee-recipient.md
View File

@@ -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