Update Lighthouse book and some FAQs (sigp#4178)

## Issue Addressed Updated Lighthouse book on Section 2 and added some FAQs ## Proposed Changes All changes are made in the book/src .md files. ## Additional Info Please provide any additional information. For example, future considerations or information useful for reviewers. Co-authored-by: chonghe <[email protected]> Co-authored-by: Michael Sproul <[email protected]>
oone-world · Jul 13, 2023 · 028ae62 · 028ae62
1 parent 9447b27
commit 028ae62
Show file tree

Hide file tree

Showing 8 changed files with 147 additions and 86 deletions.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -2,7 +2,6 @@
 
 * [Introduction](./intro.md)
 * [Installation](./installation.md)
-    * [System Requirements](./system-requirements.md)
     * [Pre-Built Binaries](./installation-binaries.md)
     * [Docker](./docker.md)
     * [Build from Source](./installation-source.md)

diff --git a/book/src/docker.md b/book/src/docker.md
@@ -16,28 +16,28 @@ way to run Lighthouse without building the image yourself.
 Obtain the latest image with:
 
 ```bash
-$ docker pull sigp/lighthouse
+docker pull sigp/lighthouse
 ```
 
 Download and test the image with:
 
 ```bash
-$ docker run sigp/lighthouse lighthouse --version
+docker run sigp/lighthouse lighthouse --version
 ```
 
 If you can see the latest [Lighthouse release](https://github.com/sigp/lighthouse/releases) version
 (see example below), then you've successfully installed Lighthouse via Docker.
 
-> Pro tip: try the `latest-modern` image for a 20-30% speed-up! See [Available Docker
-> Images](#available-docker-images) below.
-
 ### Example Version Output
 
 ```
 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.
@@ -47,11 +47,10 @@ Lighthouse with optimizations enabled. If you are running on older hardware then
 `latest` image bundles a _portable_ version of Lighthouse which is slower but with better hardware
 compatibility (see [Portability](./installation-binaries.md#portability)).
 
-To install a specific tag (in this case `latest-modern`) add the tag name to your `docker` commands
-like so:
+To install a specific tag (in this case `latest-modern`), add the tag name to your `docker` commands:
 
 ```
-$ docker pull sigp/lighthouse:latest-modern
+docker pull sigp/lighthouse:latest-modern
 ```
 
 Image tags follow this format:
@@ -65,17 +64,17 @@ The `version` is:
 * `vX.Y.Z` for a tagged Lighthouse release, e.g. `v2.1.1`
 * `latest` for the `stable` branch (latest release) or `unstable` branch
 
-The `stability` is:
-
-* `-unstable` for the `unstable` branch
-* empty for a tagged release or the `stable` branch
-
 The `arch` is:
 
 * `-amd64` for x86_64, e.g. Intel, AMD
 * `-arm64` for aarch64, e.g. Raspberry Pi 4
 * empty for a multi-arch image (works on either `amd64` or `arm64` platforms)
 
+The `stability` is:
+
+* `-unstable` for the `unstable` branch
+* empty for a tagged release or the `stable` branch
+
 The `modernity` is:
 
 * `-modern` for optimized builds
@@ -99,26 +98,26 @@ To build the image from source, navigate to
 the root of the repository and run:
 
 ```bash
-$ docker build . -t lighthouse:local
+docker build . -t lighthouse:local
 ```
 
 The build will likely take several minutes. Once it's built, test it with:
 
 ```bash
-$ docker run lighthouse:local lighthouse --help
+docker run lighthouse:local lighthouse --help
 ```
 
 ## Using the Docker image
 
 You can run a Docker beacon node with the following command:
 
 ```bash
-$ docker run -p 9000:9000/tcp -p 9000:9000/udp -p 127.0.0.1:5052:5052 -v $HOME/.lighthouse:/root/.lighthouse sigp/lighthouse lighthouse --network mainnet beacon --http --http-address 0.0.0.0
+docker run -p 9000:9000/tcp -p 9000:9000/udp -p 127.0.0.1:5052:5052 -v $HOME/.lighthouse:/root/.lighthouse sigp/lighthouse lighthouse --network mainnet beacon --http --http-address 0.0.0.0
 ```
 
-> To join the Prater testnet, use `--network prater` instead.
+> To join the Goerli testnet, use `--network goerli` instead.
 
-> The `-p` and `-v` and values are described below.
+> The `-v` (Volumes) and `-p` (Ports) and values are described below.
 
 ### Volumes
 
@@ -131,7 +130,7 @@ The following example runs a beacon node with the data directory
 mapped to the users home directory:
 
 ```bash
-$ docker run -v $HOME/.lighthouse:/root/.lighthouse sigp/lighthouse lighthouse beacon
+docker run -v $HOME/.lighthouse:/root/.lighthouse sigp/lighthouse lighthouse beacon
 ```
 
 ### Ports
@@ -140,14 +139,14 @@ In order to be a good peer and serve other peers you should expose port `9000` f
 Use the `-p` flag to do this:
 
 ```bash
-$ docker run -p 9000:9000/tcp -p 9000:9000/udp sigp/lighthouse lighthouse beacon
+docker run -p 9000:9000/tcp -p 9000:9000/udp sigp/lighthouse lighthouse beacon
 ```
 
 If you use the `--http` flag you may also want to expose the HTTP port with `-p
 127.0.0.1:5052:5052`.
 
 ```bash
-$ docker run -p 9000:9000/tcp -p 9000:9000/udp -p 127.0.0.1:5052:5052 sigp/lighthouse lighthouse beacon --http --http-address 0.0.0.0
+docker run -p 9000:9000/tcp -p 9000:9000/udp -p 127.0.0.1:5052:5052 sigp/lighthouse lighthouse beacon --http --http-address 0.0.0.0
 ```
 
 [docker_hub]: https://hub.docker.com/repository/docker/sigp/lighthouse/
diff --git a/book/src/faq.md b/book/src/faq.md
@@ -9,6 +9,11 @@
 - [What is "Syncing deposit contract block cache"?](#what-is-syncing-deposit-contract-block-cache)
 - [Can I use redundancy in my staking setup?](#can-i-use-redundancy-in-my-staking-setup)
 - [How can I monitor my validators?](#how-can-i-monitor-my-validators)
+- [I see beacon logs showing `WARN: Execution engine called failed`, what should I do?](#i-see-beacon-logs-showing-warn-execution-engine-called-failed-what-should-i-do)
+- [How do I check or update my withdrawal credentials?](#how-do-i-check-or-update-my-withdrawal-credentials)
+- [I am missing attestations. Why?](#i-am-missing-attestations-why)
+- [Sometimes I miss the attestation head vote, resulting in penalty. Is this normal?](#sometimes-i-miss-the-attestation-head-vote-resulting-in-penalty-is-this-normal)
+- [My beacon node is stuck at downloading historical block using checkpoing sync. What can I do?](#my-beacon-node-is-stuck-at-downloading-historical-block-using-checkpoing-sync-what-can-i-do)
 
 ### Why does it take so long for a validator to be activated?
 
@@ -185,4 +190,47 @@ However, there are some components which can be configured with redundancy. See
 
 Apart from using block explorers, you may use the "Validator Monitor" built into Lighthouse which
 provides logging and Prometheus/Grafana metrics for individual validators. See [Validator
-Monitoring](./validator-monitoring.md) for more information.
+Monitoring](./validator-monitoring.md) for more information. Lighthouse has also developed Lighthouse UI (Siren) to monitor performance, see [Lighthouse UI (Siren)](./lighthouse-ui.md).
+
+### I see beacon logs showing `WARN: Execution engine called failed`, what should I do?
+
+The `WARN Execution engine called failed` log is shown when the beacon node cannot reach the execution engine. When this warning occurs, it will be followed by a detailed message. A frequently encountered example of the error message is:
+
+`error: Reqwest(reqwest::Error { kind: Request, url: Url { scheme: "http", cannot_be_a_base: false, username: "", password: None, host: Some(Ipv4(127.0.0.1)), port: Some(8551), path: "/", query: None, fragment: None }, source: TimedOut }), 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. 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.
+1. Your SSD is slow. Check if your SSD is in "The Bad" list [here](https://gist.github.com/yorickdowne/f3a3e79a573bf35767cd002cc977b038). If your SSD is in "The Bad" list, it means it cannot keep in sync to the network and you may want to consider upgrading to a better SSD.
+
+If the reason for the error message is caused by no. 1 above, you may want to look further. If the execution engine is out of sync suddenly, it is usually caused by ungraceful shutdown. The common causes for ungraceful shutdown are:
+- Power outage. If power outages are an issue at your place, consider getting a UPS to avoid ungraceful shutdown of services. 
+- The service file is not stopped properly. To overcome this, make sure that the process is stop properly, e.g., during client updates. 
+- Out of memory (oom) error. This can happen when the system memory usage has reached its maximum and causes the execution engine to be killed. When this occurs, the log file will show `Main process exited, code=killed, status=9/KILL`.  You can also run `sudo journalctl -a --since "18 hours ago" | grep -i "killed process` to confirm that the execution client has been killed due to oom. If you are using geth as the execution client, a short term solution is to reduce the resources used, for example: (1) reduce the cache by adding the flag `--cache 2048` (2) connect to less peers using the flag `--maxpeers 10`. If the oom occurs rather frequently, a long term solution is to increase the memory capacity of the computer.
+
+
+### How do I check or update my withdrawal credentials? 
+Withdrawals will be available after the Capella/Shanghai upgrades on 12<sup>th</sup> April 2023. To check that if you are eligible for withdrawals, go to [Staking launchpad](https://launchpad.ethereum.org/en/withdrawals), enter your validator index and click `verify on mainnet`:
+- `withdrawals enabled` means you will automatically receive withdrawals to the withdrawal address that you set.
+- `withdrawals not enabled` means you will need to update your withdrawal credentials from `0x00` type to `0x01` type. The common way to do this is using `Staking deposit CLI` or `ethdo`, with the instructions available [here](https://launchpad.ethereum.org/en/withdrawals#update-your-keys). 
+
+For the case of `withdrawals not enabled`, you can update your withdrawal credentials **anytime**, and there is no deadline for that. The catch is that as long as you do not update your withdrawal credentials, your rewards in the beacon chain will continue to be locked in the beacon chain. Only after you update the withdrawal credentials, will the rewards be withdrawn to the withdrawal address.
+
+
+### I am missing attestations. Why? 
+The first thing is to ensure both consensus and execution clients are synced with the network. If they are synced, there may still be some issues with the node setup itself that is causing the missed attestations. Check the setup to ensure that:
+- the clock is synced
+- the computer has sufficient resources and is not overloaded
+- the internet is working well
+- you have sufficient peers
+
+You can see more information on the [Ethstaker KB](https://ethstaker.gitbook.io/ethstaker-knowledge-base/help/missed-attestations). Once the above points are good, missing attestation should be a rare occurance. 
+
+### Sometimes I miss the attestation head vote, resulting in penalty. Is this normal?
+
+In general it is unavoiadable to have some penalties occasionally. This is particularly the case when you are assigned to attest on the first slot of an epoch and if the proposer of that slot releases the block late, then you will get penalised for missing the target and head votes. Your attestation performance does not only depend on your own setup, but also on everyone else's performance.
+
+
+### My beacon node is stuck at downloading historical block using checkpoing sync. What can I do?
+
+Check the number of peers you are connected to. If you have low peers (less than 50), try to do port forwarding on the port 9000 TCP/UDP to increase peer count.
diff --git a/book/src/installation-binaries.md b/book/src/installation-binaries.md
@@ -23,21 +23,24 @@ For details, see [Portability](#portability).
 ## Usage
 
 Each binary is contained in a `.tar.gz` archive. For this example, lets assume the user needs
-a portable `x86_64` binary.
+a `x86_64` binary.
 
 ### Steps
 
 1. Go to the [Releases](https://github.com/sigp/lighthouse/releases) page and
    select the latest release.
-1. Download the `lighthouse-${VERSION}-x86_64-unknown-linux-gnu-portable.tar.gz` binary.
-1. Extract the archive:
-    1. `cd Downloads`
-    1. `tar -xvf lighthouse-${VERSION}-x86_64-unknown-linux-gnu.tar.gz`
+1. Download the `lighthouse-${VERSION}-x86_64-unknown-linux-gnu.tar.gz` binary. For example, to obtain the binary file for v4.0.1 (the latest version at the time of writing), a user can run the following commands in a linux terminal:
+    ```bash
+    cd ~
+    curl -LO https://github.com/sigp/lighthouse/releases/download/v4.0.1/lighthouse-v4.0.1-x86_64-unknown-linux-gnu.tar.gz
+    tar -xvf lighthouse-v4.0.1-x86_64-unknown-linux-gnu.tar.gz
+    ```
 1. Test the binary with `./lighthouse --version` (it should print the version).
-1. (Optional) Move the `lighthouse` binary to a location in your `PATH`, so the `lighthouse` command can be called from anywhere.
-    - E.g., `cp lighthouse /usr/bin`
+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 3 from PowerShell.
+
+
+> Windows users will need to execute the commands in Step 2 from PowerShell.
 
 ## Portability
 
@@ -64,4 +67,4 @@ WARN CPU seems incompatible with optimized Lighthouse build, advice: If you get
 
 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.
+continues to function, it's nothing to worry about.
diff --git a/book/src/installation-source.md b/book/src/installation-source.md
@@ -5,8 +5,20 @@ the instructions below, and then proceed to [Building Lighthouse](#build-lightho
 
 ## Dependencies
 
-First, **install Rust** using [rustup](https://rustup.rs/). The rustup installer provides an easy way
-to update the Rust compiler, and works on all platforms.
+First, **install Rust** using [rustup](https://rustup.rs/)： 
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+The rustup installer provides an easy way to update the Rust compiler, and works on all platforms.
+
+> Tips:
+>
+> - During installation, when prompted, enter `1` for the default installation.
+> - After Rust installation completes, try running `cargo version` . If it cannot
+>   be found, run `source $HOME/.cargo/env`. After that, running `cargo version` should return the version, for example `cargo 1.68.2`.
+> - It's generally advisable to append `source $HOME/.cargo/env` to `~/.bashrc`.
 
 With Rust installed, follow the instructions below to install dependencies relevant to your
 operating system.
@@ -19,10 +31,17 @@ Install the following packages:
 sudo apt install -y git gcc g++ make cmake pkg-config llvm-dev libclang-dev clang protobuf-compiler
 ```
 
+> Tips:
+>
+> - If there are difficulties, try updating the package manager with `sudo apt
+>   update`.
+
 > Note: Lighthouse requires CMake v3.12 or newer, which isn't available in the package repositories
 > of Ubuntu 18.04 or earlier. On these distributions CMake can still be installed via PPA:
 > [https://apt.kitware.com/](https://apt.kitware.com)
 
+After this, you are ready to [build Lighthouse](#build-lighthouse).
+
 #### macOS
 
 1. Install the [Homebrew][] package manager.
@@ -39,10 +58,19 @@ brew install protobuf
 
 [Homebrew]: https://brew.sh/
 
+After this, you are ready to [build Lighthouse](#build-lighthouse).
+
 #### Windows
 
-1. Install [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+1. Install [Git](https://git-scm.com/download/win).
 1. Install the [Chocolatey](https://chocolatey.org/install) package manager for Windows.
+    > Tips: 
+    > - Use PowerShell to install. In Windows, search for PowerShell and run as administrator.
+    > - You must ensure `Get-ExecutionPolicy` is not Restricted. To test this, run `Get-ExecutionPolicy` in PowerShell. If it returns `restricted`, then run `Set-ExecutionPolicy AllSigned`, and then run
+    ```bash 
+    Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
+    ```
+    > - To verify that Chocolatey is ready, run `choco` and it should return the version.
 1. Install Make, CMake, LLVM and protoc using Chocolatey:
 
 ```
@@ -67,6 +95,8 @@ should follow the instructions for Ubuntu listed in the [Dependencies (Ubuntu)](
 
 [WSL]: https://docs.microsoft.com/en-us/windows/wsl/about
 
+After this, you are ready to [build Lighthouse](#build-lighthouse).
+
 ## Build Lighthouse
 
 Once you have Rust and the build dependencies you're ready to build Lighthouse:
@@ -136,7 +166,7 @@ Commonly used features include:
 * `spec-minimal`: support for the minimal preset (useful for testing).
 
 Default features (e.g. `slasher-mdbx`) may be opted out of using the `--no-default-features`
-argument for `cargo`, which can plumbed in via the `CARGO_INSTALL_EXTRA_FLAGS` environment variable.
+argument for `cargo`, which can be plumbed in via the `CARGO_INSTALL_EXTRA_FLAGS` environment variable.
 E.g.
 
 ```
@@ -171,12 +201,11 @@ PROFILE=maxperf make
 Lighthouse will be installed to `CARGO_HOME` or `$HOME/.cargo`. This directory
 needs to be on your `PATH` before you can run `$ lighthouse`.
 
-See ["Configuring the `PATH` environment variable"
-(rust-lang.org)](https://www.rust-lang.org/tools/install) for more information.
+See ["Configuring the `PATH` environment variable"](https://www.rust-lang.org/tools/install) for more information.
 
 ### Compilation error
 
-Make sure you are running the latest version of Rust. If you have installed Rust using rustup, simply type `rustup update`.
+Make sure you are running the latest version of Rust. If you have installed Rust using rustup, simply run `rustup update`.
 
 If you can't install the latest version of Rust you can instead compile using the Minimum Supported
 Rust Version (MSRV) which is listed under the `rust-version` key in Lighthouse's
@@ -185,7 +214,7 @@ Rust Version (MSRV) which is listed under the `rust-version` key in Lighthouse's
 If compilation fails with `(signal: 9, SIGKILL: kill)`, this could mean your machine ran out of
 memory during compilation. If you are on a resource-constrained device you can
 look into [cross compilation](./cross-compiling.md), or use a [pre-built
-binary](./installation-binaries.md).
+binary](https://github.com/sigp/lighthouse/releases).
 
 If compilation fails with `error: linking with cc failed: exit code: 1`, try running `cargo clean`.