status-im/nimbus-eth2
2
0
Fork 0
mirror of https://github.com/status-im/nimbus-eth2.git synced 2025-01-22 12:30:08 +00:00
Code Issues Projects Releases Wiki Activity

book edits (#3903)

Browse Source 
* Reorganise menu, putting tabs on top
* Use tabs for specific content
* cleanups and consistency edits
This commit is contained in:
Jacek Sieka 2022-07-24 22:13:47 +02:00 committed by GitHub
parent e4051710be
commit dcea09ea5c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
28 changed files with 359 additions and 343 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
docs/the_nimbus_book/mkdocs.yml
View File

@ -5,7 +5,9 @@ theme:
name: material
features:
- navigation.expand
- navigation.tabs
- navigation.top
- content.tabs.link
palette:
scheme: default
primary: orange
@ -20,6 +22,7 @@ docs_dir: src
markdown_extensions:
- admonition
- meta
- pymdownx.details
- pymdownx.highlight:
anchor_linenums: true
@ -28,9 +31,10 @@ markdown_extensions:
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
- tables
nav:
- Summary:
- About:
- 'philosophy.md'
- 'hardware.md'
- 'preparation.md'
@ -43,49 +47,50 @@ nav:
- Downloads:
- 'binaries.md'
- 'docker.md'
- How-to (beacon node):
- 'install.md'
- 'build.md'
- 'start-syncing.md'
- 'trusted-node-sync.md'
- 'web3-backup.md'
- How-to (validator):
- 'deposit.md'
- 'keys.md'
- 'connect-eth2.md'
- 'graffiti.md'
- 'suggested-fee-recipient.md'
- 'keep-an-eye.md'
- 'voluntary-exit.md'
- 'validator-monitor.md'
- 'more-keys.md'
- 'additional-validator.md'
- 'validator-client.md'
- How-to (misc):
- 'keep-updated.md'
- 'eth1.md'
- 'goerli-eth.md'
- 'beacon-node-systemd.md'
- 'log-rotate.md'
- 'checksums.md'
- 'database-backup.md'
- 'logging.md'
- 'email-notifications.md'
- 'profits.md'
- 'health.md'
- 'networking.md'
- 'prater.md'
- 'kiln.md'
- How-to:
- Beacon node:
- 'install.md'
- 'build.md'
- 'start-syncing.md'
- 'trusted-node-sync.md'
- 'networking.md'
- 'web3-backup.md'
- Validator:
- 'deposit.md'
- 'keys.md'
- 'connect-eth2.md'
- 'graffiti.md'
- 'suggested-fee-recipient.md'
- 'keep-an-eye.md'
- 'voluntary-exit.md'
- 'validator-monitor.md'
- 'more-keys.md'
- 'additional-validator.md'
- 'validator-client.md'
- General:
- 'keep-updated.md'
- 'eth1.md'
- 'goerli-eth.md'
- 'beacon-node-systemd.md'
- 'logging.md'
- 'log-rotate.md'
- 'database-backup.md'
- 'email-notifications.md'
- 'profits.md'
- 'health.md'
- 'prater.md'
- 'kiln.md'
- Guides:
- 'metrics-pretty-pictures.md'
- 'infura-guide.md'
- 'migration.md'
- 'metrics-pretty-pictures.md'
- 'pi-guide.md'
- 'attestation-performance.md'
- 'infura-guide.md'
- Security:
- 'security_issues.md'
@ -93,9 +98,9 @@ nav:
- 'distribution_internals.md'
- Reference:
- 'options.md'
- 'rest-api.md'
- 'keymanager-api.md'
- 'options.md'
- 'data-dir.md'
- 'migration-options.md'
- 'troubleshooting.md'

2
docs/the_nimbus_book/src/api.md
View File

@ -1,4 +1,4 @@
# JSON-RPC API
# JSON-RPC API (deprecated)
!!! warning
As of v22.6.0, the Nimbus JSON-RPC interface has been **removed** following an extended deprecation period. You are encouraged to migrate your applications to the [REST API](./rest-api.md).

8
docs/the_nimbus_book/src/binaries.md
View File

@ -1,4 +1,4 @@
# Nimbus binaries
# Binaries
Binary releases can be downloaded from [https://github.com/status-im/nimbus-eth2/releases/latest](https://github.com/status-im/nimbus-eth2/releases/latest).
@ -8,7 +8,7 @@ We currently have binaries available for Linux `AMD64`, `ARM` and `ARM64`, Windo
The binaries are available at the bottom of the page under `Assets`. You should see a list that looks like the following:
![](https://i.imgur.com/6wuvM2d.png)
![Assets](https://i.imgur.com/6wuvM2d.png)
Click on the file that corresponds to your OS and architecture, unpack the archive, read the README and run the binary directly (or through one of our provided wrapper scripts).
@ -25,10 +25,6 @@ tar xvf nimbus-eth2_Linux_amd64_22.6.1_2444e994.tar.gz --strip-components 1 -C n
After unpacking, you may wish to [verify the checksum](./checksums.md).
## Docker
Nimbus binaries are also published via [Docker](./docker.md).
## Reproducible builds
We've designed the build process to be reproducible. In practice, this means that anyone can verify that these exact binaries were produced from the corresponding source code commits. For more about the philosophy and importance of this feature see [reproducible-builds.org](https://reproducible-builds.org/).

73
docs/the_nimbus_book/src/build.md
View File

@ -1,8 +1,8 @@
# Build the beacon node
# Build from source
Building the beacon node from source ensures that all hardware-specific optimizations are turned on. The build process itself is simple and fully automated, but may take a few minutes.
Building Nimbus from source ensures that all hardware-specific optimizations are turned on. The build process itself is simple and fully automated, but may take a few minutes.
!!! note
!!! note "Nim"
Nimbus is written in the [Nim](https://nim-lang.org) programming language - the correct version will automatically be downloaded as part of the build process!
## Prerequisites
@ -13,58 +13,57 @@ Building the beacon node from source ensures that all hardware-specific optimiza
When building from source, you will need additional build dependencies to be installed:
- Developer tools (C compiler, Make, Bash, Git)
- [CMake](https://cmake.org/)
Nimbus will build Nim as part of its build process - you do not need to have the Nim compiler installed.
=== "Linux"
### Linux
On common Linux distributions the dependencies can be installed with
On common Linux distributions the dependencies can be installed with
```sh
# Debian and Ubuntu
sudo apt-get install build-essential git cmake
```sh
# Debian and Ubuntu
sudo apt-get install build-essential git
# Fedora
dnf install @development-tools cmake
# Fedora
dnf install @development-tools
# Archlinux, using an AUR manager
yourAURmanager -S base-devel cmake
```
# Archlinux, using an AUR manager
yourAURmanager -S base-devel
```
=== "macOS"
### macOS
With [Homebrew](https://brew.sh/):
Assuming you use [Homebrew](https://brew.sh/) to manage packages
```sh
brew install cmake
```
```sh
brew install cmake
```
=== "Windows"
### Windows
To build Nimbus on Windows, the MinGW-w64 build environment is recommended.
To build Nimbus on windows, the Mingw-w64 build environment is recommended.
Install Mingw-w64 for your architecture using the "[MinGW-W64 Online Installer](https://sourceforge.net/projects/mingw-w64/files/)":
Install Mingw-w64 for your architecture using the "[MinGW-W64 Online Installer](https://sourceforge.net/projects/mingw-w64/files/)":
1. Select your architecture in the setup menu (`i686` on 32-bit, `x86_64` on 64-bit)
2. Set threads to `win32`
3. Set exceptions to "dwarf" on 32-bit and "seh" on 64-bit.
4. Change the installation directory to `C:\mingw-w64` and add it to your system PATH in `"My Computer"/"This PC" -> Properties -> Advanced system settings -> Environment Variables -> Path -> Edit -> New -> C:\mingw-w64\mingw64\bin` (`C:\mingw-w64\mingw32\bin` on 32-bit)
1. Select your architecture in the setup menu (`i686` on 32-bit, `x86_64` on 64-bit)
2. Set threads to `win32`
3. Set exceptions to "dwarf" on 32-bit and "seh" on 64-bit.
4. Change the installation directory to `C:\mingw-w64` and add it to your system PATH in `"My Computer"/"This PC" -> Properties -> Advanced system settings -> Environment Variables -> Path -> Edit -> New -> C:\mingw-w64\mingw64\bin` (`C:\mingw-w64\mingw32\bin` on 32-bit)
Install [Git for Windows](https://gitforwindows.org/) and use a "Git Bash" shell to clone and build `nimbus-eth2`.
Install [Git for Windows](https://gitforwindows.org/) and use a "Git Bash" shell to clone and build `nimbus-eth2`.
> **Note:** If the online installer isn't working you can try installing `mingw-w64` through [MSYS2](https://www.msys2.org/).
> **Note:** If the online installer isn't working you can try installing `Mingw-w64` through [MSYS2](https://www.msys2.org/).
=== "Android"
### Android
- Install the [Termux](https://termux.com) app from FDroid or the Google Play store
- Install a [PRoot](https://wiki.termux.com/wiki/PRoot) of your choice following the instructions for your preferred distribution.
Note, the Ubuntu PRoot is known to contain all Nimbus prerequisites compiled on Arm64 architecture (the most common architecture for Android devices).
- Install the [Termux](https://termux.com) app from FDroid or the Google Play store
- Install a [PRoot](https://wiki.termux.com/wiki/PRoot) of your choice following the instructions for your preferred distribution.
Note, the Ubuntu PRoot is known to contain all Nimbus prerequisites compiled on Arm64 architecture (the most common architecture for Android devices).
Assuming you use Ubuntu PRoot
Assuming you use Ubuntu PRoot
```sh
apt install build-essential git
```
```sh
apt install build-essential git
```
## Building the node

2
docs/the_nimbus_book/src/checksums.md
View File

@ -1,4 +1,4 @@
# Verify the integrity of Nimbus
# Checksums
Checksums for each build are included in the [release notes](https://github.com/status-im/nimbus-eth2/releases/). Please make sure you get into the habit of verifying these 🙏

12
docs/the_nimbus_book/src/connect-eth2.md
View File

@ -7,14 +7,14 @@ Once your keys have been [imported](./keys.md), it is time to restart the beacon
Press `Ctrl-c` to stop the beacon node if it's running, then use the same command as before to run it again:
=== "Mainnet"
```sh
./run-mainnet-beacon-node.sh
```
```sh
./run-mainnet-beacon-node.sh
```
=== "Prater"
```sh
./run-prater-beacon-node.sh
```
```sh
./run-prater-beacon-node.sh
```
## Check the logs

29
docs/the_nimbus_book/src/contribute.md
View File

@ -1,36 +1,39 @@
# Contribute
# Updating this book
Follow these steps to contribute to this book!
We use an utility tool called mdBook to create online books from Markdown files.
We use [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) to produce our documentation.
## Before You Start
1. Install mdBook from [here](https://github.com/rust-lang/mdBook).
2. Clone the repository by `git clone https://github.com/status-im/nimbus-eth2.git`.
3. Go to where the Markdown files are located by `cd docs/the_nimbus_book/`.
1. Clone the repository by `git clone https://github.com/status-im/nimbus-eth2.git`.
2. Go to the `docs` folder and type `make` to install `mkdocs`
3. Activate mkdocs: `. mkdocs/bin/activate`
3. Go to where the Markdown files are located by `cd the_nimbus_book/`.
## Real-Time Update and Preview Changes
1. Run `mdbook serve` in the terminal.
2. Preview the book at [http://localhost:3000](http://localhost:3000).
1. Run `mkdocs serve` in the terminal.
2. Preview the book at [http://localhost:8000](http://localhost:8000).
## Build and Deploy
The first step is to submit a pull request to the [unstable branch](https://github.com/status-im/nimbus-eth2/tree/unstable).
Then, after it is merged, do the following under our main repository:
1. `cd nimbus-eth2`
2. `git checkout unstable`
3. `git pull`
4. `make update` (This is to update the submodules to the latest version)
5. `make publish-book`
```sh
cd nimbus-eth2
git checkout unstable
git pull
make update # (This is to update the submodules to the latest version)
make publish-book
```
## Troubleshooting
If you see file conflicts in the pull request, this may due to that you have created your new branch from an old version of the `unstable` branch. Update your new branch using the following commands:
```
```sh
git checkout unstable
git pull
make update

2
docs/the_nimbus_book/src/data-dir.md
View File

@ -4,7 +4,7 @@ Nimbus stores all the information it needs to run in a data directory. In this d
When following the installation guide, the chain data will be stored in `build/data` with separate directories for each chain (mainnet, prater, etc).
!!! tip
!!! tip "The `--data-dir` option"
The `--data-dir=/path/to/data` allows picking a specific data directory to store the chain - make sure you use the same `--data-dir` option for all beacon node commands!
## Contents

2
docs/the_nimbus_book/src/deposit.md
View File

@ -33,7 +33,7 @@ tar xvf staking_deposit-cli-9ab0b05-linux-amd64.tar.gz --strip-components 2
The deposit tool generates a seed phrase, and uses this to create validator and withdrawal keys.
!!! warn
!!! danger
If you lose you seed phrase and your withdrawal key, your funds will be lost forever!
=== "Mainnet"

25
docs/the_nimbus_book/src/docker.md
View File

@ -1,6 +1,6 @@
# Docker images
Docker images for end-users are generated and published automatically to [Docker Hub](https://hub.docker.com/r/statusim/nimbus-eth2) from the Nimbus-eth2 CI, by a GitHub action, whenever a new release is tagged in Git.
Docker images are available from [Docker Hub](https://hub.docker.com/r/statusim/nimbus-eth2) .
We have version-specific Docker tags (`statusim/nimbus-eth2:amd64-v1.2.3`) and a tag for the latest image (`statusim/nimbus-eth2:amd64-latest`).
@ -10,34 +10,41 @@ The unpacked archive is in `/home/user/nimbus-eth2` which is also the default *W
## Usage
Before running nimbus via docker, you need to prepare a data directory and mount it in docker.
Before running Nimbus via docker, you need to prepare a data directory and mount it in docker.
It is recommended that you mount the directory at `/home/user/nimbus-eth2/build/data` and pass `--data-dir=build/data/shared_mainnet_0` to all `nimbus_becaon_node` commands.
The wrapper script outlined below will set the data directory automatically.
```text
```sh
mkdir data
docker run -it --rm -v ${PWD}/data:/home/user/nimbus-eth2/build/data statusim/nimbus-eth2:amd64-latest --data-dir=build/data/shared_mainnet_0 --network=mainnet [other options]
docker run -it --rm \
-v ${PWD}/data:/home/user/nimbus-eth2/build/data \
statusim/nimbus-eth2:amd64-latest \
--data-dir=build/data/shared_mainnet_0
--network=mainnet [other options]
```
### Wrapper script
If you wish, you can choose to use a wrapper script instead:
```text
```sh
mkdir data
docker run -it --rm -v ${PWD}/data:/home/user/nimbus-eth2/build/data -e WEB3_URL="wss://mainnet.infura.io/ws/v3/YOUR_TOKEN" --entrypoint /home/user/nimbus-eth2/run-mainnet-beacon-node.sh statusim/nimbus-eth2:amd64-latest [nimbus_beacon_node args here]
docker run -it --rm \
-v ${PWD}/data:/home/user/nimbus-eth2/build/data \
--entrypoint /home/user/nimbus-eth2/run-mainnet-beacon-node.sh \
statusim/nimbus-eth2:amd64-latest [other options]
```
### Docker compose
Our preferred setup is using `docker-compose`. You can use one of our [example configuration files](https://github.com/status-im/nimbus-eth2/tree/stable/docker/dist/binaries) as a base for your own custom configuration:
```text
```sh
mkdir data
docker-compose -f docker-compose-example1.yml up --quiet-pull --no-color --detach
```
> **Note:** The rather voluminous logging is done on `stdout`, so you might want to change the system-wide Docker logging defaults (which dumps everything in `/var/lib/docker/containers/CONTAINER_ID/CONTAINER_ID-json.log`) to something like `syslog`. We recommend using a log rotation system with appropriate intervals for logs of this size.
!!! note
The rather voluminous logging is done on `stdout`, so you might want to change the system-wide Docker logging defaults (which dumps everything in `/var/lib/docker/containers/CONTAINER_ID/CONTAINER_ID-json.log`) to something like `syslog`. We recommend using a log rotation system with appropriate intervals for logs of this size.

94
docs/the_nimbus_book/src/eth1.md
View File

@ -9,75 +9,77 @@ The `--web3-url` option informs the beacon node how to connect to the execution
You can pass one or more `--web3-url` parameters to the node. Any additional web3 url:s will be used for backup, should the first client become unavailable:
```sh
./run-mainnet-beacon-node.sh --web3-url=ws://127.0.0.1:8546 --web3-url=http://other:8545
./run-mainnet-beacon-node.sh \
--web3-url=ws://127.0.0.1:8546 \
--web3-url=http://other:8545
```
!!! warn
You need to run your own execution client after [the merge](./merge.md) - relying on third-party services such as Infura, Alchemy and Pocket will not be possible.
!!! note
!!! info
Syncing an execution client may take hours or even days, depending on your hardware!
## Nimbus
=== "Nimbus"
In parallel to `nimbus-eth2`, we are working hard on the [Nimbus execution client](https://github.com/status-im/nimbus-eth1). While this is very much a project in development (i.e. not yet ready for public consumption), we welcome you to experiment with it.
In parallel to `nimbus-eth2`, we are working hard on the [Nimbus execution client](https://github.com/status-im/nimbus-eth1). While this is very much a project in development (i.e. not yet ready for public consumption), we welcome you to experiment with it.
## Geth
=== "Geth"
### 1. Install Geth
### 1. Install Geth
See the [Installing Geth](https://geth.ethereum.org/docs/install-and-build/installing-geth) for instructions on installing Geth.
See the [Installing Geth](https://geth.ethereum.org/docs/install-and-build/installing-geth) for instructions on installing Geth.
### 2. Start Geth
### 2. Start Geth
Once you have geth installed, make sure to enable the JSON-RPC WebSocket interface when running geth:
Once you have geth installed, make sure to enable the JSON-RPC WebSocket interface when running geth:
=== "Mainnet"
```
geth --ws
```
=== "Goerli"
```
geth --goerli --ws
```
!!! note
The `--ws` flag is needed to enable the websocket RPC API. This allows Nimbus to query the eth1 chain using Web3 API calls.
### 3. Leave Geth running
Let it sync - Geth uses snap sync by default. It may take anywhere between a few hours and a couple of days.
!!! note
It is safe to run Nimbus and start validating even if Geth hasn't fully synced yet
You'll know Geth has finished syncing, when you start seeing logs that look like the following:
=== "Mainnet"
```
geth --ws
INFO [05-29|01:16:05] Imported new chain segment blocks=1 txs=3 mgas=0.065 elapsed=5.885ms mgasps=11.038 number=3785445 hash=553d9e…fc4547
INFO [05-29|01:16:10] Imported new chain segment blocks=1 txs=0 mgas=0.000 elapsed=5.447ms mgasps=0.000 number=3785446 hash=5e3e7d…bd4afd
INFO [05-29|01:16:10] Imported new chain segment blocks=1 txs=1 mgas=0.021 elapsed=7.382ms mgasps=2.845 number=3785447 hash=39986c…dd2a01
INFO [05-29|01:16:14] Imported new chain segment blocks=1 txs=11 mgas=1.135 elapsed=22.281ms mgasps=50.943 number=3785444 hash=277bb9…623d8c
```
=== "Goerli"
```
geth --goerli --ws
```
Geth accepts connections from the loopback interface (`127.0.0.1`), with default WebSocket port `8546`. This means that your default Web3 provider URL should be: `ws://127.0.0.1:8546`
!!! note
The `--ws` flag is needed to enable the websocket RPC API. This allows Nimbus to query the eth1 chain using Web3 API calls.
=== "Nethermind"
See the [Getting started](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/getting-started) guide to set up Nethermind.
### 3. Leave Geth running
Make sure to enable the [JSON-RPC](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge#jsonrpc-configuration-module) interface over WebSockets.
Let it sync - Geth uses snap sync by default. It may take anywhere between a few hours and a couple of days.
=== "Besu"
!!! note
It is safe to run Nimbus and start validating even if Geth hasn't fully synced yet
See the [Besu documentation](https://besu.hyperledger.org/en/stable/) for instructions on setting up Besu.
You'll know Geth has finished syncing, when you start seeing logs that look like the following:
Make sure to enable the [JSON-RPC](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API/) WebSocket interface.
```
INFO [05-29|01:16:05] Imported new chain segment blocks=1 txs=3 mgas=0.065 elapsed=5.885ms mgasps=11.038 number=3785445 hash=553d9e…fc4547
INFO [05-29|01:16:10] Imported new chain segment blocks=1 txs=0 mgas=0.000 elapsed=5.447ms mgasps=0.000 number=3785446 hash=5e3e7d…bd4afd
INFO [05-29|01:16:10] Imported new chain segment blocks=1 txs=1 mgas=0.021 elapsed=7.382ms mgasps=2.845 number=3785447 hash=39986c…dd2a01
INFO [05-29|01:16:14] Imported new chain segment blocks=1 txs=11 mgas=1.135 elapsed=22.281ms mgasps=50.943 number=3785444 hash=277bb9…623d8c
```
=== "Erigon"
Geth accepts connections from the loopback interface (`127.0.0.1`), with default WebSocket port `8546`. This means that your default Web3 provider URL should be: `ws://127.0.0.1:8546`
See the [Erigon README](https://github.com/ledgerwatch/erigon#getting-started=) for instructions on setting up Erigon.
## Nethermind
See the [Getting started](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/getting-started) guide to set up Nethermind.
Make sure to enable the [JSON-RPC](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge#jsonrpc-configuration-module) interface over WebSockets.
## Besu
See the [Besu documentation](https://besu.hyperledger.org/en/stable/) for instructions on setting up Besu.
Make sure to enable the [JSON-RPC](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API/) WebSocket interface.
## Erigon
See the [Erigon README](https://github.com/ledgerwatch/erigon#getting-started=) for instructions on setting up Erigon.
Make sure to enable the [JSON-RPC](https://github.com/ledgerwatch/erigon#beacon-chain=) WebSocket interface.
Make sure to enable the [JSON-RPC](https://github.com/ledgerwatch/erigon#beacon-chain=) WebSocket interface.

12
docs/the_nimbus_book/src/graffiti.md
View File

@ -3,12 +3,12 @@
You can use your node's graffiti flag to make your mark on history and forever engrave some words of your choice into an Ethereum block. You will be able to see it using the block explorer.
=== "Mainnet"
```sh
./run-mainnet-beacon-node.sh --graffiti="<YOUR_WORDS>"
```
```sh
./run-mainnet-beacon-node.sh --graffiti="<YOUR_WORDS>"
```
=== "Prater"
```sh
./run-prater-beacon-node.sh --graffiti="<YOUR_WORDS>"
```
```sh
./run-prater-beacon-node.sh --graffiti="<YOUR_WORDS>"
```

28
docs/the_nimbus_book/src/hardware.md
View File

@ -1,22 +1,18 @@
# System requirements (recommended)
# System requirements
The recommended system requirements for running the Nimbus beacon node are:
-----------------
**Operating System:** Linux [64-bit](https://en.wikipedia.org/wiki/64-bit_computing), Windows 64-bit, macOS X 10.14+,
| What | Recommended |
| ---------- | ------ |
| Operating system | Linux [64-bit](https://en.wikipedia.org/wiki/64-bit_computing), Windows 64-bit, macOS X 10.15+ |
| Memory | 4GB |
| Disk space | 200GB |
| Network | Reliable broadband |
**Memory:** 2GB RAM
!!! note "Execution client"
In addtion to the beacon node, you will need to run an [execution client](./eth1.md) - check the documentation of the client of choice and add them to the above requirements.
**Storage:** 200GB SSD
Broadly, to run both an execution and a consensus client on the same machine, we recommend a **2 TB** SSD drive and **8** GB RAM.
**Internet:** Reliable broadband connection
----------------
In addtion to the beacon node, you will need to run an [execution client](./eth1.md) - check the documentation of the client of choice and add them to the above requirements.
Broadly, to run both an execution and a consensus client on the same machine, we recommend a **2 TB** SSD drive and **8** GB RAM.
----------------
Nimbus has been optimized to also run well on hardware significantly less powerful than the recommended system requirements - the more validators you run on the same node, the more hardware resources and network bandwidth will it will use.
!!! note "Minimal requirements"
Nimbus has been optimized to also run well on hardware significantly less powerful than the recommended system requirements - the more validators you run on the same node, the more hardware resources and network bandwidth will it will use.

2
docs/the_nimbus_book/src/health.md
View File

@ -24,7 +24,7 @@ If you're a Linux user and want to track how much network I/O your system uses o
To install, run:
```
```sh
sudo apt install vnstat
```

10
docs/the_nimbus_book/src/index.md
View File

@ -1,10 +1,9 @@
# The Nimbus Guide
!!! note
If you're eager to get started, check out our [quickstart guide](./quick-start.md).
!!! note ""
If you're eager to get started, check out our [quickstart guide](./quick-start.md). Coming from a different client? Check out the [migration guide](./migration.md).
Nimbus is client for the Ethereum `consensus layer` (eth2) and `execution layer` (eth1) that is [lightweight](https://our.status.im/ethereum-is-green/), [secure](./audit.md) and easy to use.
Nimbus is a client for the Ethereum `consensus layer` (eth2) and `execution layer` (eth1) that is [lightweight](https://our.status.im/ethereum-is-green/), [secure](./audit.md) and [easy to use](./run-a-validator.md).
This book describes the consensus layer client, `nimbus-eth2`, in particular.
@ -26,8 +25,7 @@ This book explains the ways in which you can use Nimbus to either monitor the be
## Helpful resources
- [nimbus-eth2 repository](https://github.com/status-im/nimbus-eth2)
- [eth2 specification](https://github.com/ethereum/consensus-specs/tree/v1.2.0-rc.1#phase-0)
- [Ethereum consensus spec](https://github.com/ethereum/consensus-specs/)
- [Ben Edgington's annotated spec](https://benjaminion.xyz/eth2-annotated-spec/phase0/beacon-chain/)
- [Vitalik's annotated spec](https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md)
- [Danny Ryan's annotated spec](https://notes.ethereum.org/@djrtwo/Bkn3zpwxB)

2
docs/the_nimbus_book/src/infura-guide.md
View File

@ -1,4 +1,4 @@
# Supplying your own Infura endpoint
# Setting up an Infura account
> ⚠️ After The Merge, you will need to run your own [execution client](./eth1.md).

34
docs/the_nimbus_book/src/install.md
View File

@ -10,31 +10,25 @@ Check that your machine matches the [minimal system requirements](./hardware.md)
The beacon chain relies on your computer having the correct time set (±0.5 seconds). It is important that you periodically synchronize the time with an NTP server.
If the above sounds like latin to you, don't worry. You should be fine as long as you haven't messed around with the time and date settings on your computer (they should be set automatically).
If the above sounds like latin to you, don't worry. You should be fine as long as you haven't changed the time and date settings on your computer (they should be set automatically).
### Windows and macOS
=== "Linux"
Make sure that the options for setting time automatically are enabled.
On Linux, it is recommended to install [chrony](https://chrony.tuxfamily.org/).
### Linux
To install it:
On Linux, it is recommended to install [chrony](https://chrony.tuxfamily.org/).
```sh
# Debian and Ubuntu
sudo apt-get install -y chrony
To install it:
# Fedora
sudo dnf install chrony
```sh
# Debian and Ubuntu
sudo apt-get install -y chrony
# Archlinux, using an AUR manager
yourAURmanager chrony
```
# Fedora
sudo dnf install chrony
=== "Windows, macOS"
# Archlinux, using an AUR manager
yourAURmanager chrony
```
## Execution client
To run a beacon node, you need to have access to an execution client exposing the web3 API - throughout, we'll assume an execution client is running on the same machine as the beacon node, but this is not required.
See the [execution client](./eth1.md) guide for further instructions!
Make sure that the options for setting time automatically are enabled.

8
docs/the_nimbus_book/src/keep-an-eye.md
View File

@ -2,10 +2,10 @@
The best way to keep track of your validator's status is using the `beaconcha.in` explorer (click on the orange magnifying glass at the very top and paste in your validator's public key):
- **Testnet:** [prater.beaconcha.in](https://prater.beaconcha.in)
- **Mainnet:** [beaconcha.in](https://beaconcha.in/)
- **Prater:** [prater.beaconcha.in](https://prater.beaconcha.in)
If you deposit after the [genesis](https://hackmd.io/@benjaminion/genesis) state was decided, your validator(s) will be put in a queue based on deposit time, and will slowly be inducted into the validator set after genesis. Getting through the queue may take a few hours or a day or so.
When you make a deposit, your validator(s) will be put in a queue based on deposit time, and will slowly be inducted into the validator set. Getting through the queue may take up to a few days, depending on the length of the deposit queue.
You can even create an account ([testnet link](https://prater.beaconcha.in/register), [mainnet link](https://beaconcha.in/register)) to add alerts and keep track of your validator's performance ([testnet link](https://prater.beaconcha.in/dashboard), [mainnet link](https://beaconcha.in/dashboard)).
@ -32,6 +32,7 @@ INF 2022-06-16 13:23:11.008+02:00 Slot start
```
Where:
- `slot` is the current time on the beacon chain, measured in "slots"
- `epoch` shows the current epoch - each epoch has 32 slots, and each validator performs one attestation per epoch
- `peers` tells you how many peers you're currently connected to - depending on the number of attached validators, you may need anywhere from 10 to 60 peers connected
@ -51,4 +52,5 @@ The string of letters -- what we call the `sync worker map` (in the above case r
U - updating peer's status information
```
> **Note:** You can also use you calls outlined in the [REST API page](./rest-api.md) to retrieve similar information.
!!! tip
You can also use you calls outlined in the [REST API page](./rest-api.md) to retrieve similar information.

2
docs/the_nimbus_book/src/keep-updated.md
View File

@ -1,4 +1,4 @@
# Upgrade / downgrade Nimbus
# Upgrade / downgrade
Make sure you stay on the lookout for any critical updates to Nimbus. This best way to do so is through the **announcements** channel on our [discord](https://discord.com/invite/XRxWahP). The release page can be found [here](https://github.com/status-im/nimbus-eth2/releases/).

13
docs/the_nimbus_book/src/keys.md
View File

@ -1,11 +1,10 @@
# Import your validator keys into Nimbus
# Import your validator keys
!!! tip
`systemd` service file users will want to follow the [service file guide](./beacon-node-systemd.md#import-validator-keys) instead!
Having followed the [deposit](./deposit.md) guide, you will have a `validator_keys` folder containing several `.json` files in the `nimbus-eth2` directory.
We'll import the signing key of each validator to the [data directory](./data-dir.md) using the `deposits import` command:
=== "Mainnet"
@ -18,7 +17,7 @@ We'll import the signing key of each validator to the [data directory](./data-di
build/nimbus_beacon_node deposits import --data-dir=build/data/shared_prater_0
```
!!! note
!!! warning ""
You'll be asked to enter the password you created to encrypt your keystore(s).
If your `validator_keys` folder is stored elsewhere, you can pass its location to the import command:
@ -56,9 +55,9 @@ After importing keys, it's time to [restart](./connect-eth2.md) the node and che
If you come across an error, make sure that:
* You are using the correct data directory
* for `systemd` users, look for the `--data-dir` option in the `.service` file
* You are using the correct [data directory](./data-dir.md)
* for `systemd` users, look for the `--data-dir` option in the `.service` file
* You are running the command as the correct user
* for `systemd` users, look for the `User=` option in the `.service`. Assuming the user is called `nimbus`, prefix all commands with: `sudo -u nimbus`
* for `systemd` users, look for the `User=` option in the `.service`. Assuming the user is called `nimbus`, prefix all commands with: `sudo -u nimbus`
* Permissions for the data directory are wrong
* See [folder permissions](./data-dir.md#permissions) for how to fix this.
* See [folder permissions](./data-dir.md#permissions) for how to fix this.

2
docs/the_nimbus_book/src/logging.md
View File

@ -1,4 +1,4 @@
# Logging
# Logging options
> :warning: The logging options outlined here are based on a preview feature, and are subject to change

16
docs/the_nimbus_book/src/migration-options.md
View File

@ -1,4 +1,4 @@
# Migration options (advanced)
# Client migration (advanced)
The main migration guide is located [here](./migration.md). Here we document a couple of advanced options you can use if you wish to have more fine-grained control.
@ -6,7 +6,7 @@ The main migration guide is located [here](./migration.md). Here we document a c
The default command for exporting your slashing protection history is:
```
```sh
build/nimbus_beacon_node slashingdb export database.json
```
@ -23,7 +23,7 @@ Export finished: '$HOME/.cache/nimbus/BeaconNode/validators/slashing_protection.
The validator directory contains your validator's setup.
```
```sh
build/nimbus_beacon_node slashingdb export database.json --validators-dir=path/to/validatorsdir/
```
@ -31,7 +31,7 @@ build/nimbus_beacon_node slashingdb export database.json --validators-dir=path/t
The data directory (`data-dir`) contains your beacon node setup.
```
```sh
build/nimbus_beacon_node slashingdb export database.json --data-dir=path/to/datadir/
```
@ -39,7 +39,7 @@ build/nimbus_beacon_node slashingdb export database.json --data-dir=path/to/data
You can perform a partial export by specifying the public key of the relevant validator you wish to export.
```
```sh
build/nimbus_beacon_node slashingdb export database.json --validator=0xb5da853a51d935da6f3bd46934c719fcca1bbf0b493264d3d9e7c35a1023b73c703b56d598edf0239663820af36ec615
```
@ -50,7 +50,7 @@ If you wish to export multiple validators, you must specify the `--validator` op
The default command for importing your validator's slashing protection history into the database is:
```
```sh
build/nimbus_beacon_node slashingdb import database.json
```
@ -58,7 +58,7 @@ build/nimbus_beacon_node slashingdb import database.json
The validator directory contains your validator's setup.
```
```sh
build/nimbus_beacon_node slashingdb import database.json --validators-dir=path/to/validatorsdir/
```
@ -66,7 +66,7 @@ build/nimbus_beacon_node slashingdb import database.json --validators-dir=path/t
The data directory contains your beacon node's setup.
```
```sh
build/nimbus_beacon_node slashingdb import database.json --data-dir=path/to/datadir/
```

206
docs/the_nimbus_book/src/migration.md
View File

@ -1,3 +1,8 @@
---
hide:
- toc
---
# Migrate from another client
This guide will take you through the basics of how to migrate to Nimbus from another client. *See [here](./migration-options.md) for advanced options*.
@ -10,6 +15,7 @@ The main pain point involves the exporting and importing of the [slashing protec
> **Please take your time to get this right.** Don't hesitate to reach out to us in the `#helpdesk` channel of [our discord](https://discord.gg/j3nYBUeEad) if you come across a stumbling block. We are more than happy to help guide you through the migration process. Given what's at stake, there is no such thing as a stupid question.
## Step 1 - Sync the Nimbus beacon node
No matter which client you are migrating over from, the first step is to sync the Nimbus beacon node.
The easiest way to do this is to follow the [beacon node quick start guide](./quick-start.md). Syncing the beacon node might take up to 30 hours depending on your hardware - you should keep validating using your current setup until it completes.
@ -28,125 +34,127 @@ Once your Nimbus beacon node has synced and you're satisfied that it's working,
## Step 2 - Stop your existing client and export your slashing protection history
=== "Prysm"
### From Prysm
#### 1. Disable the Prysm validator client
#### 1. Disable the Prysm validator client
Stop and disable the Prysm validator client (you can also stop the Prysm beacon node if you wish).
Stop and disable the Prysm validator client (you can also stop the Prysm beacon node if you wish).
If you're using systemd and your service is called `prysmvalidator`, run the following commands to stop and disable the service:
```sh
sudo systemctl stop prysmvalidator.service
sudo systemctl disable prysmvalidator.service
```
It's important that you disable the Prysm validator as well as stopping it, to prevent it from starting up again on reboot.
#### 2. Export slashing protection history
Run the following to export your Prysm validator's [slashing protection](https://eips.ethereum.org/EIPS/eip-3076) history:
```sh
prysm.sh validator slashing-protection-history export \
--datadir=/your/prysm/wallet \
--slashing-protection-export-dir=/path/to/export_dir
```
You will then find the `slashing-protection.json` file in your specified `/path/to/export_dir` folder.
!!! tip
To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check it's recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
=== "Lighthouse"
#### 1. Disable the Lighthouse validator client
The validator client needs to be stopped in order to export, to guarantee that the data exported is up to date.
If you're using systemd and your service is called `lighthousevalidator`, run the following command to stop and disable the service:
```sh
sudo systemctl stop lighthousevalidator
sudo systemctl disable lighthousevalidator
```
You may also wish to stop the beacon node:
```sh
sudo systemctl stop lighthousebeacon
sudo systemctl disable lighthousebeacon
```
*It's important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.*
#### 2. Export slashing protection history
You can export Lighthouse's database with this command:
```sh
lighthouse account validator slashing-protection export slashing-protection.json
```
This will export your history in the correct format to `slashing-protection.json`.
!!! tip
To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check it's recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
=== "Teku"
#### 1. Disable Teku
If you're using systemd and your service is called `teku`, run the following command to stop and disable the service:
```sh
sudo systemctl stop teku
sudo systemctl disable teku
```
*It's important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.*
If you're using systemd and your service is called `prysmvalidator`, run the following commands to stop and disable the service:
#### 2. Export slashing protection history
```
sudo systemctl stop prysmvalidator.service
sudo systemctl disable prysmvalidator.service
```
You can export Teku's database with this command:
It's important that you disable the Prysm validator as well as stopping it, to prevent it from starting up again on reboot.
```sh
teku slashing-protection export --data-path=/home/me/me_node --to=/home/slash/slashing-protection.json
```
#### 2. Export slashing protection history
Where:
Run the following to export your Prysm validator's [slashing protection](https://eips.ethereum.org/EIPS/eip-3076) history:
- `--data-path` specifies the location of the Teku data directory.
- `--to` specifies the file to export the slashing-protection data to (in this case `/home/slash/slashing-protection.json`).
```
prysm.sh validator slashing-protection-history export \
--datadir=/your/prysm/wallet \
--slashing-protection-export-dir=/path/to/export_dir
```
!!! tip
To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check it's recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
You will then find the `slashing-protection.json` file in your specified `/path/to/export_dir` folder.
=== "Nimbus"
> **Tip:** To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check it's recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
#### 1. Disable the Nimbus validator client
### From Lighthouse
Once your Nimbus beacon node on your new setup has synced and you're satisfied that it's working, stop and disable the Nimbus validator client on your current setup.
#### 1. Disable the Lighthouse validator client
If you're using systemd and your service is called `nimbus-eth2-mainnet`, run the following commands to stop and disable the service:
The validator client needs to be stopped in order to export, to guarantee that the data exported is up to date.
```
sudo systemctl stop nimbus-eth2-mainnet.service
sudo systemctl disable nimbus-eth2-mainnet.service
```
If you're using systemd and your service is called `lighthousevalidator`, run the following command to stop and disable the service:
*It's important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.*
#### 2. Export slashing protection history
```
sudo systemctl stop lighthousevalidator
sudo systemctl disable lighthousevalidator
```
Run the following to export your Nimbus validator's [slashing protection](https://eips.ethereum.org/EIPS/eip-3076) history:
You may also wish to stop the beacon node:
```
sudo systemctl stop lighthousebeacon
sudo systemctl disable lighthousebeacon
```
```
build/nimbus_beacon_node slashingdb export slashing-protection.json
```
*It's important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.*
This will export your history in the correct format to `slashing-protection.json`.
#### 2. Export slashing protection history
You can export Lighthouse's database with this command:
```
lighthouse account validator slashing-protection export slashing-protection.json
```
This will export your history in the correct format to `slashing-protection.json`.
> **Tip:** To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check it's recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
### From Teku
#### 1. Disable Teku
If you're using systemd and your service is called `teku`, run the following command to stop and disable the service:
```
sudo systemctl stop teku
sudo systemctl disable teku
```
*It's important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.*
#### 2. Export slashing protection history
You can export Teku's database with this command:
```
teku slashing-protection export --data-path=/home/me/me_node --to=/home/slash/slashing-protection.json
```
Where:
- `--data-path` specifies the location of the Teku data directory.
- `--to` specifies the file to export the slashing-protection data to (in this case `/home/slash/slashing-protection.json`).
> **Tip:** To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check it's recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
### From Nimbus
#### 1. Disable the Nimbus validator client
Once your Nimbus beacon node on your new setup has synced and you're satisfied that it's working, stop and disable the Nimbus validator client on your current setup.
If you're using systemd and your service is called `nimbus-eth2-mainnet`, run the following commands to stop and disable the service:
```
sudo systemctl stop nimbus-eth2-mainnet.service
sudo systemctl disable nimbus-eth2-mainnet.service
```
*It's important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.*
#### 2. Export slashing protection history
Run the following to export your Nimbus validator's [slashing protection](https://eips.ethereum.org/EIPS/eip-3076) history:
```
build/nimbus_beacon_node slashingdb export slashing-protection.json
```
This will export your history in the correct format to `slashing-protection.json`.
> **Tip:** To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check it's recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
> **Tip:** To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check it's recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
## Step 3 - Import your validator key(s) into Nimbus
@ -161,7 +169,7 @@ To import you validator key(s), follow the instructions [outlined here](./keys.m
To import the slashing protection history you exported in **step 2**, from the `nimbus-eth2` directory run:
```
```sh
build/nimbus_beacon_node slashingdb import path/to/export_dir/slashing-protection.json
```

4
docs/the_nimbus_book/src/more-keys.md
View File

@ -23,7 +23,7 @@ Specifically, we'll be using the `existing-mnemonic` command. Here's a descripti
Run the following command from the directory which contains the `deposit` executable:
=== "Mainnet"
```
```sh
./deposit existing-mnemonic \
--validator_start_index 0 \
--num_validators 1 \
@ -31,7 +31,7 @@ Run the following command from the directory which contains the `deposit` execut
```
=== "Prater"
```
```sh
./deposit existing-mnemonic \
--validator_start_index 0 \
--num_validators 1 \

2
docs/the_nimbus_book/src/networking.md
View File

@ -1,4 +1,4 @@
# Network setup
# Networking options
Nimbus will automatically connect to peers based on the health and quality of peers that it's already connected to. Depending on the network and the number of validators attached to the node, Nimbus may need anywhere from 10 to 60 peers connected to operate well.

21
docs/the_nimbus_book/src/quick-start.md
View File

@ -16,12 +16,17 @@ The guide assumes [Ubuntu Linux](https://ubuntu.com/download/server) is being us
!!! tip
You can practice running the node safely on the [Prater testnet](./prater.md) - throughout, we'll provide instructions for both Prater and Mainnet.
## 1. Prepare
Prepare your machine by installing [Nimbus' dependencies](./install.md). In particular, this step will show how to set up an [execution client](./eth1.md).
Prepare your machine by installing [Nimbus' dependencies](./install.md).
## 2. Install
## 2. Set up an execution client
To run a beacon node, you need to have access to an execution client exposing the web3 API - throughout, we'll assume an execution client is running on the same machine as the beacon node, but this is not required.
See the [execution client](./eth1.md) guide for instructions on how to pick and install an execution client!
## 3. Install Nimbus
Next, download the [latest release](./binaries.md) and install it by unpacking the archive. Using a command line terminal:
@ -39,7 +44,7 @@ tar xvf nimbus-eth2_Linux_amd64_22.6.1_2444e994.tar.gz --strip-components 1 -C n
!!! tip
Advanced users looking to take advantage of hardware-specific features and optimization may wish to [build from source](./build.md) instead!
## 3. Start the node
## 4. Start the node
Once you've installed the binaries, you can [start the node](./start-syncing.md) which will initiate the sync process.
@ -69,8 +74,8 @@ INF 2022-07-19 15:42:58.145+02:00 Launching beacon node top
Congratulations! Your beacon node is up and running, and syncing the network!
## Where to go from here
!!! success "What next?"
* If you will be running the node on a regular basis, it is recommended you set up a [systemd service](./beacon-node-systemd.md) that automatically restarts your node if the computer reboots.
* If you wish to stake, continue your journey by following the [validator quick start](./run-a-validator.md).
* The [monitoring](./health.md) page contains information about how to keep your node healthy
* If you will be running the node on a regular basis, it is recommended you set up a [systemd service](./beacon-node-systemd.md) that automatically restarts your node if the computer reboots.
* If you wish to stake, continue your journey by following the [validator quick start](./run-a-validator.md).
* The [monitoring](./health.md) page contains information about how to keep your node healthy

6
docs/the_nimbus_book/src/run-a-validator.md
View File

@ -2,7 +2,7 @@
Once your beacon node is [running and synced](./quick-start.md), the next step is to set up a validator.
!!! note
!!! tip "No validator client needed"
Unlike other beacon chain clients, Nimbus does not require setting up a separate validator client process - the beacon node can itself perform validator duties.
This is a simple, safe and efficient way to get started.
@ -21,5 +21,7 @@ Once your beacon node is [running and synced](./quick-start.md), the next step i
[Start performing duties](./connect-eth2.md) by restarting the node
!!! tip
Congratulations - you're now set up to be earning a small amount of ETH every 6.4 minutes in return for keeping the Ethereum network secure!
!!! success "What next?"
While that's all there is to it, it is essential that you both [keep an eye on your validator](keep-an-eye.md) and [keep Nimbus updated](keep-updated.md) regularly 💫

2
docs/the_nimbus_book/src/web3-backup.md
View File

@ -1,4 +1,4 @@
# Add a backup web3 provider
# Backup web3 provider
It's a good idea to add a backup web3 provider in case your main one goes down. You can do this by simply repeating the `--web3-url` parameter on launch.