gnosis/lighthouse
1
0
Fork 0
mirror of https://github.com/sigp/lighthouse.git synced 2026-04-19 05:48:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'unstable' into vc-fallback

Browse Source
This commit is contained in:
Mac L
2024-08-20 00:35:36 +10:00
parent 526a894a2b d957161740
commit 1fdb4ec57e
244 changed files with 9028 additions and 4028 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
book/src/cross-compiling.md
View File

@@ -15,18 +15,10 @@ project.
### Targets
The `Makefile` in the project contains four targets for cross-compiling:
The `Makefile` in the project contains two targets for cross-compiling:
- `build-x86_64`: builds an optimized version for x86_64 processors (suitable for most users).
- `build-x86_64-portable`: builds a version for x86_64 processors which avoids using some modern CPU
instructions that are incompatible with older CPUs.
- `build-aarch64`: builds an optimized version for 64-bit ARM processors (suitable for Raspberry Pi 4).
- `build-aarch64-portable`: builds a version for 64-bit ARM processors which avoids using some
modern CPU instructions. In practice, very few ARM processors lack the instructions necessary to
run the faster non-portable build.
For more information about optimized vs portable builds see
[Portability](./installation-binaries.md#portability).
### Example

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

@@ -16,7 +16,7 @@ validator client or the slasher**.
| Lighthouse version | Release date | Schema version | Downgrade available? |
|--------------------|--------------|----------------|----------------------|
| v5.3.0 | Aug 2024 TBD | v22 TBD | no (TBD) |
| v5.3.0 | Aug 2024 | v21 | yes |
| v5.2.0 | Jun 2024 | v19 | no |
| v5.1.0 | Mar 2024 | v19 | no |
| v5.0.0 | Feb 2024 | v19 | no |
@@ -208,6 +208,7 @@ Here are the steps to prune historic states:
| Lighthouse version | Release date | Schema version | Downgrade available? |
|--------------------|--------------|----------------|-------------------------------------|
| v5.3.0 | Aug 2024 | v21 | yes |
| v5.2.0 | Jun 2024 | v19 | yes before Deneb using <= v5.2.1 |
| v5.1.0 | Mar 2024 | v19 | yes before Deneb using <= v5.2.1 |
| v5.0.0 | Feb 2024 | v19 | yes before Deneb using <= v5.2.1 |

27
book/src/docker.md
View File

@@ -35,28 +35,23 @@ Lighthouse vx.x.xx-xxxxxxxxx
BLS Library: xxxx-xxxxxxx
```
> Pro tip: try the `latest-modern` image for a 20-30% speed-up! See [Available Docker
> Images](#available-docker-images) below.
### Available Docker Images
There are several images available on Docker Hub.
Most users should use the `latest-modern` tag, which corresponds to the latest stable release of
Lighthouse with optimizations enabled. If you are running on older hardware then the default
`latest` image bundles a _portable_ version of Lighthouse which is slower but with better hardware
compatibility (see [Portability](./installation-binaries.md#portability)).
Most users should use the `latest` tag, which corresponds to the latest stable release of
Lighthouse with optimizations enabled.
To install a specific tag (in this case `latest-modern`), add the tag name to your `docker` commands:
To install a specific tag (in this case `latest`), add the tag name to your `docker` commands:
```bash
docker pull sigp/lighthouse:latest-modern
docker pull sigp/lighthouse:latest
```
Image tags follow this format:
```text
${version}${arch}${stability}${modernity}${features}
${version}${arch}${stability}
```
The `version` is:
@@ -75,19 +70,9 @@ The `stability` is:
* `-unstable` for the `unstable` branch
* empty for a tagged release or the `stable` branch
The `modernity` is:
* `-modern` for optimized builds
* empty for a `portable` unoptimized build
The `features` is:
* `-dev` for a development build with `minimal` preset enabled (`spec-minimal` feature).
* empty for a standard build with no custom feature enabled.
Examples:
* `latest-unstable-modern`: most recent `unstable` build for all modern CPUs (x86_64 or ARM)
* `latest-unstable`: most recent `unstable` build
* `latest-amd64`: most recent Lighthouse release for older x86_64 CPUs
* `latest-amd64-unstable`: most recent `unstable` build for older x86_64 CPUs

14
book/src/faq.md
View File

@@ -8,7 +8,6 @@
- [My beacon node is stuck at downloading historical block using checkpoint sync. What should I do?](#bn-download-historical)
- [I proposed a block but the beacon node shows `could not publish message` with error `duplicate` as below, should I be worried?](#bn-duplicate)
- [I see beacon node logs `Head is optimistic` and I am missing attestations. What should I do?](#bn-optimistic)
- [My beacon node logs `CRIT Beacon block processing error error: ValidatorPubkeyCacheLockTimeout`, what should I do?](#bn-timeout)
- [My beacon node logs `WARN BlockProcessingFailure outcome: MissingBeaconBlock`, what should I do?](#bn-missing-beacon)
- [After checkpoint sync, the progress of `downloading historical blocks` is slow. Why?](#bn-download-slow)
- [My beacon node logs `WARN Error processing HTTP API request`, what should I do?](#bn-http)
@@ -84,7 +83,7 @@ The `WARN Execution engine called failed` log is shown when the beacon node cann
`error: HttpClient(url: http://127.0.0.1:8551/, kind: timeout, detail: operation timed out), service: exec`
which says `TimedOut` at the end of the message. This means that the execution engine has not responded in time to the beacon node. One option is to add the flags `--execution-timeout-multiplier 3` and `--disable-lock-timeouts` to the beacon node. However, if the error persists, it is worth digging further to find out the cause. There are a few reasons why this can occur:
which says `TimedOut` at the end of the message. This means that the execution engine has not responded in time to the beacon node. One option is to add the flag `--execution-timeout-multiplier 3` to the beacon node. However, if the error persists, it is worth digging further to find out the cause. There are a few reasons why this can occur:
1. The execution engine is not synced. Check the log of the execution engine to make sure that it is synced. If it is syncing, wait until it is synced and the error will disappear. You will see the beacon node logs `INFO Execution engine online` when it is synced.
1. The computer is overloaded. Check the CPU and RAM usage to see if it has overloaded. You can use `htop` to check for CPU and RAM usage.
@@ -140,17 +139,6 @@ WARN Head is optimistic execution_block_hash: 0x47e7555f1d4215d1ad409b1ac1
It means the beacon node will follow the chain, but it will not be able to attest or produce blocks. This is because the execution client is not synced, so the beacon chain cannot verify the authenticity of the chain head, hence the word `optimistic`. What you need to do is to make sure that the execution client is up and syncing. Once the execution client is synced, the error will disappear.
### <a name="bn-timeout"></a> My beacon node logs `CRIT Beacon block processing error error: ValidatorPubkeyCacheLockTimeout, service: beacon`, what should I do?
An example of the log is shown below:
```text
CRIT Beacon block processing error error: ValidatorPubkeyCacheLockTimeout, service: beacon
WARN BlockProcessingFailure outcome: ValidatorPubkeyCacheLockTimeout, msg: unexpected condition in processing block.
```
A `Timeout` error suggests that the computer may be overloaded at the moment, for example, the execution client is still syncing. You may use the flag `--disable-lock-timeouts` to silence this error, although it will not fix the underlying slowness. Nevertheless, this is a relatively harmless log, and the error should go away once the resources used are back to normal.
### <a name="bn-missing-beacon"></a> My beacon node logs `WARN BlockProcessingFailure outcome: MissingBeaconBlock`, what should I do?
An example of the full log is shown below:

4
book/src/help_bn.md
View File

@@ -480,9 +480,7 @@ Flags:
--disable-inbound-rate-limiter
Disables the inbound rate limiter (requests received by this node).
--disable-lock-timeouts
Disable the timeouts applied to some internal locks by default. This
can lead to less spurious failures on slow hardware but is considered
experimental as it may obscure performance issues.
This flag is deprecated and has no effect.
--disable-log-timestamp
If present, do not include timestamps in logging output.
--disable-malloc-tuning

5
book/src/help_vc.md
View File

@@ -281,10 +281,7 @@ Flags:
If this flag is set, Lighthouse will always prefer blocks constructed
by builders, regardless of payload value.
--produce-block-v3
Enable block production via the block v3 endpoint for this validator
client. This should only be enabled when paired with a beacon node
that has this endpoint implemented. This flag will be enabled by
default in future.
This flag is deprecated and is no longer in use.
--unencrypted-http-transport
This is a safety flag to ensure that the user is aware that the http
transport is unencrypted and using a custom HTTP address is unsafe.

34
book/src/installation-binaries.md
View File

@@ -13,13 +13,6 @@ Binaries are supplied for four platforms:
- `x86_64-apple-darwin`: macOS with Intel chips
- `x86_64-windows`: Windows with 64-bit processors
Additionally there is also a `-portable` suffix which indicates if the `portable` feature is used:
- Without `portable`: uses modern CPU instructions to provide the fastest signature verification times (may cause `Illegal instruction` error on older CPUs)
- With `portable`: approx. 20% slower, but should work on all modern 64-bit processors.
For details, see [Portability](#portability).
## Usage
Each binary is contained in a `.tar.gz` archive. For this example, lets assume the user needs
@@ -41,30 +34,3 @@ a `x86_64` binary.
1. (Optional) Move the `lighthouse` binary to a location in your `PATH`, so the `lighthouse` command can be called from anywhere. For example, to copy `lighthouse` from the current directory to `usr/bin`, run `sudo cp lighthouse /usr/bin`.
> Windows users will need to execute the commands in Step 2 from PowerShell.
## Portability
Portable builds of Lighthouse are designed to run on the widest range of hardware possible, but
sacrifice the ability to make use of modern CPU instructions.
If you have a modern CPU then you should try running a non-portable build to get a 20-30% speed up.
- For **x86_64**, any CPU supporting the [ADX](https://en.wikipedia.org/wiki/Intel_ADX) instruction set
extension is compatible with the optimized build. This includes Intel Broadwell (2014)
and newer, and AMD Ryzen (2017) and newer.
- For **ARMv8**, most CPUs are compatible with the optimized build, including the Cortex-A72 used by
the Raspberry Pi 4.
## Troubleshooting
If you get a SIGILL (exit code 132), then your CPU is incompatible with the optimized build
of Lighthouse and you should switch to the `-portable` build. In this case, you will see a
warning like this on start-up:
```
WARN CPU seems incompatible with optimized Lighthouse build, advice: If you get a SIGILL, please try Lighthouse portable build
```
On some VPS providers, the virtualization can make it appear as if CPU features are not available,
even when they are. In this case you might see the warning above, but so long as the client
continues to function, it's nothing to worry about.

3
book/src/installation-source.md
View File

@@ -160,8 +160,7 @@ FEATURES=gnosis,slasher-lmdb make
Commonly used features include:
- `gnosis`: support for the Gnosis Beacon Chain.
- `portable`: support for legacy hardware.
- `modern`: support for exclusively modern hardware.
- `portable`: the default feature as Lighthouse now uses runtime detection of hardware CPU features.
- `slasher-lmdb`: support for the LMDB slasher backend. Enabled by default.
- `slasher-mdbx`: support for the MDBX slasher backend.
- `jemalloc`: use [`jemalloc`][jemalloc] to allocate memory. Enabled by default on Linux and macOS.

2
book/src/installation.md
View File

@@ -23,7 +23,7 @@ There are also community-maintained installation methods:
Before [The Merge](https://ethereum.org/en/roadmap/merge/), Lighthouse was able to run on its own with low to mid-range consumer hardware, but would perform best when provided with ample system resources.
After [The Merge](https://ethereum.org/en/roadmap/merge/) on 15<sup>th</sup> September 2022, it is necessary to run Lighthouse together with an execution client ([Nethermind](https://nethermind.io/), [Besu](https://www.hyperledger.org/use/besu), [Erigon](https://github.com/ledgerwatch/erigon), [Geth](https://geth.ethereum.org/)). The following system requirements listed are therefore for running a Lighthouse beacon node combined with an execution client , and a validator client with a modest number of validator keys (less than 100):
After [The Merge](https://ethereum.org/en/roadmap/merge/) on 15<sup>th</sup> September 2022, it is necessary to run Lighthouse together with an execution client ([Nethermind](https://nethermind.io/), [Besu](https://www.hyperledger.org/use/besu), [Erigon](https://github.com/ledgerwatch/erigon), [Geth](https://geth.ethereum.org/), [Reth](https://github.com/paradigmxyz/reth)). The following system requirements listed are therefore for running a Lighthouse beacon node combined with an execution client , and a validator client with a modest number of validator keys (less than 100):
- CPU: Quad-core AMD Ryzen, Intel Broadwell, ARMv8 or newer
- Memory: 32 GB RAM*

4
book/src/late-block-re-orgs.md
View File

@@ -50,10 +50,10 @@ A pair of messages at `INFO` level will be logged if a re-org opportunity is det
> INFO Proposing block to re-org current head head_to_reorg: 0xf64f…2b49, slot: 1105320
This should be followed shortly after by a `WARN` log indicating that a re-org occurred. This is
This should be followed shortly after by a `INFO` log indicating that a re-org occurred. This is
expected and normal:
> WARN Beacon chain re-org reorg_distance: 1, new_slot: 1105320, new_head: 0x72791549e4ca792f91053bc7cf1e55c6fbe745f78ce7a16fc3acb6f09161becd, previous_slot: 1105319, previous_head: 0xf64f8e5ed617dc18c1e759dab5d008369767c3678416dac2fe1d389562842b49
> INFO Beacon chain re-org reorg_distance: 1, new_slot: 1105320, new_head: 0x72791549e4ca792f91053bc7cf1e55c6fbe745f78ce7a16fc3acb6f09161becd, previous_slot: 1105319, previous_head: 0xf64f8e5ed617dc18c1e759dab5d008369767c3678416dac2fe1d389562842b49
In case a re-org is not viable (which should be most of the time), Lighthouse will just propose a
block as normal and log the reason the re-org was not attempted at debug level:

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

@@ -7,7 +7,7 @@
There are two configuration changes required for a Lighthouse node to operate correctly throughout
the merge:
1. You *must* run your own execution engine such as Besu, Erigon, Geth or Nethermind alongside Lighthouse.
1. You *must* run your own execution engine such as Besu, Erigon, Reth, Geth or Nethermind alongside Lighthouse.
You *must* update your `lighthouse bn` 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.
@@ -65,6 +65,7 @@ Each execution engine has its own flags for configuring the engine API and JWT.
the relevant page for your execution engine for the required flags:
- [Geth: Connecting to Consensus Clients](https://geth.ethereum.org/docs/getting-started/consensus-clients)
- [Reth: Running the Consensus Layer](https://reth.rs/run/mainnet.html?highlight=consensus#running-the-consensus-layer)
- [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/)
- [Erigon: Beacon Chain (Consensus Layer)](https://github.com/ledgerwatch/erigon#beacon-chain-consensus-layer)
@@ -123,7 +124,7 @@ a deprecation warning will be logged and Lighthouse *may* remove these flags in
### 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 (Besu, Erigon, Geth or Nethermind). Each beacon node (BN) can have multiple eth1 endpoints
"eth1" nodes (Besu, Erigon, Reth, Geth or Nethermind). Each beacon node (BN) can have multiple eth1 endpoints
and each eth1 endpoint can have many BNs connection (many-to-many relationship). The eth1 node
provides a source of truth for the [deposit
contract](https://ethereum.org/en/staking/deposit-contract/) and beacon chain proposers include this
@@ -134,7 +135,7 @@ achieve this.
To progress through the Bellatrix upgrade nodes will need a *new* connection to an "eth1" node;
`--execution-endpoint`. This connection has a few different properties. Firstly, the term "eth1
node" has been deprecated and replaced with "execution engine". Whilst "eth1 node" and "execution
engine" still refer to the same projects (Besu, Erigon, Geth or Nethermind), the former refers to the pre-merge
engine" still refer to the same projects (Besu, Erigon, Reth, Geth or Nethermind), the former refers to the pre-merge
versions and the latter refers to post-merge versions. Secondly, there is a strict one-to-one
relationship between Lighthouse and the execution engine; only one Lighthouse node can connect to
one execution engine. Thirdly, it is impossible to fully verify the post-merge chain without an

1
book/src/run_a_node.md
View File

@@ -26,6 +26,7 @@ per beacon node. The reason for this is that the beacon node *controls* the exec
- [Besu](https://besu.hyperledger.org/en/stable/public-networks/get-started/connect/mainnet/)
- [Erigon](https://github.com/ledgerwatch/erigon#beacon-chain-consensus-layer)
- [Geth](https://geth.ethereum.org/docs/getting-started/consensus-clients)
- [Reth](https://reth.rs/run/mainnet.html)
> Note: Each execution engine has its own flags for configuring the engine API and JWT secret to connect to a beacon node. Please consult the relevant page of your execution engine as above for the required flags.