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

Doc fixes, part 2 (#4806)

Browse Source 
* part 2 of the initial doc fixes

- spelling fixes
- grammar fixes
- em-dashes should be em-dashes (`—`): double dashes (`--`) are not rendered properly
- reduce overusage of em-dashes, some of those should be separate sentences
- use the correct syntax for notes, tips and warnings
- every sentence is in a separate line (helps with future diffs)
- add missing dots at the end of list items
- fix some lists

* sentences on separate lines in the remaining files
This commit is contained in:
Miran 2023-04-11 17:42:35 +02:00 committed by GitHub
parent eed34e740a
commit d1318fbe96
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
57 changed files with 772 additions and 535 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,7 +1,8 @@
# 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).
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).
The JSON-RPC API pre-dated the REST API and was based on early designs of the beacon chain.
@ -337,7 +338,7 @@ Equivalent call in the official REST API:
curl http://localhost:5052/eth/v1/node/health -s -w "%{http_code}"
```
## Valdiator API
## Validator API
### [`get_v1_validator_duties_attester`](https://ethereum.github.io/eth2.0-APIs/#/ValidatorRequiredApi/getAttesterDuties)
@ -583,8 +584,8 @@ curl -X POST http://localhost:5052/nimbus/v1/chronicles/settings -d "DEBUG; TRAC
### setGraffiti
Set the graffiti bytes that will be included in proposed blocks. The graffiti bytes can be
specified as an UTF-8 encoded string or as an 0x-prefixed hex string specifying raw bytes.
Set the graffiti bytes that will be included in proposed blocks.
The graffiti bytes can be specified as an UTF-8 encoded string or as an 0x-prefixed hex string specifying raw bytes.
```
curl -d '{"jsonrpc":"2.0","id":"id","method":"setGraffiti","params":["Mr F was here"] }' -H 'Content-Type: application/json' localhost:9190 -s | jq

22
docs/the_nimbus_book/src/attestation-performance.md
View File

@ -2,7 +2,7 @@
`ncli_db validatorPerf` is an advanced tool that helps you analyze the performance of your validator over time.
The tool requires that you [built nimbus from source](./build.md).
The tool requires that you [build nimbus from source](./build.md).
## Steps
@ -21,7 +21,7 @@ To view the options available to you, run:
build/ncli_db --help
```
At the top you should see
At the top you should see:
```
ncli_db [OPTIONS]... command
@ -39,7 +39,7 @@ Where:
- The default location of the `db` is `build/data/shared_mainnet_0/db` for `mainnet`, `build/data/shared_prater_0/db` for `prater`, etc.
Near the bottom, you should see
Near the bottom, you should see:
```
ncli_db validatorPerf [OPTIONS]...
@ -84,21 +84,21 @@ build/ncli_db validatorPerf \
### 5. Compare my validators to the global average
We'll use [Paul Hauner's wonderful workbook](https://docs.google.com/spreadsheets/d/1SNFf4LsDOK91SWuQZm9DYBoX9JNQNMKHw66Rv0l5EGo/) as a template. This workbook consists of three inter-related spreadsheets - `Summary`, `My Validators`, and `datasource`.
We'll use [Paul Hauner's wonderful workbook](https://docs.google.com/spreadsheets/d/1SNFf4LsDOK91SWuQZm9DYBoX9JNQNMKHw66Rv0l5EGo/) as a template.
This workbook consists of three inter-related spreadsheets: `Summary`, `My Validators`, and `datasource`.
1. Make a copy of the document
1. Make a copy of the document.
2. Remove the table entries in `My Validators` and delete everything in the `datasource` sheet
2. Remove the table entries in `My Validators` and delete everything in the `datasource` sheet.
3. Import the output from `validatorPerf` to `datasource` - the easiest way to do this is to pipe the output to a `csv`, remove the first few lines, and import the `csv` into `datasource`
3. Import the output from `validatorPerf` to `datasource` - the easiest way to do this is to pipe the output to a `csv`, remove the first few lines, and import the `csv` into `datasource`.
4. Manually copy over your validator(s) to the `My Validators` sheet - the easiest way to find your validator's `validator_index` is to search for it by its public key on [beaconcha.in](https://beaconcha.in/) (for example, [this validator's](https://beaconcha.in/validator/115733) index is 115733)
4. Manually copy over your validator(s) to the `My Validators` sheet - the easiest way to find your validator's `validator_index` is to search for it by its public key on [beaconcha.in](https://beaconcha.in/) (for example, [this validator's](https://beaconcha.in/validator/115733) index is 115733).
5. Go to the `Summary` page and view your results
5. Go to the `Summary` page and view your results.
## Resources
The workbook's method is explained [here](https://hackmd.io/xQfi83kHQpm05-aAFVV0DA?view).
The workbook's method is explained [here](https://hackmd.io/xQfi83kHQpm05-aAFVV0DA?view).

17
docs/the_nimbus_book/src/audit.md
View File

@ -2,7 +2,9 @@
## Summary
Nimbus has undergone an extensive, multi-vendor ([ConsenSys Diligence](https://consensys.net/diligence/), [NCC Group](https://www.nccgroup.com/uk/), and [Trail of Bits](https://www.trailofbits.com/)) security assessment over a period of several months. During that process, we were notified of several issues within the codebase. These issues have been addressed contributing significantly to the overall security of Nimbus and other applications that use its libraries.
Nimbus has undergone an extensive multi-vendor ([ConsenSys Diligence](https://consensys.net/diligence/), [NCC Group](https://www.nccgroup.com/uk/), and [Trail of Bits](https://www.trailofbits.com/)) security assessment over a period of several months.
During that process, we were notified of several issues within the codebase.
These issues have been addressed, contributing significantly to the overall security of Nimbus and other applications that use its libraries.
Additionally, as a result of the work done from our security vendors, we have incoroprated many new security processes and tooling to improve our ability to find security issues in the future.
@ -10,15 +12,18 @@ For more information on the issues and how they were addressed, the interested r
## History
Back in May of last year (2020), Status and the Nimbus Team posted a [Request for Proposal](https://our.status.im/nimbus-eth2-0-security-audit-request-for-proposal/) document regarding the [security assessment](https://our.status.im/what-is-a-security-audit-when-you-should-get-one-and-how-to-prepare/) of the [nimbus-eth2](https://github.com/status-im/nimbus-eth2) repository (formerly `nim-beacon-chain`) and its software dependencies.
Back in May of 2020, Status and the Nimbus Team posted a [Request for Proposal document](https://our.status.im/nimbus-eth2-0-security-audit-request-for-proposal/) regarding the [security assessment](https://our.status.im/what-is-a-security-audit-when-you-should-get-one-and-how-to-prepare/) of the [nimbus-eth2](https://github.com/status-im/nimbus-eth2) repository (formerly `nim-beacon-chain`) and its software dependencies.
After thoroughly vetting and weighing the submitted proposals, 3 security vendors were chosen to review the codebase for a timeline of approximately [3 months](https://notes.status.im/7D73zDPyQxOUWw4ejEn6oQ?view#).
After thoroughly vetting and weighing the submitted proposals, three security vendors were chosen to review the codebase for a timeline of approximately [three months](https://notes.status.im/7D73zDPyQxOUWw4ejEn6oQ?view#).
The kickoff announcement can be read [here](https://our.status.im/nimbus-beacon-chain-assessment-kickoff/).
We separated the codebase into sub-topics with various tasks. These tasks were then broken up and assigned to the vendor(s) with the required expertise.
We separated the codebase into sub-topics with various tasks.
These tasks were then broken up and assigned to the vendor(s) with the required expertise.
The desired deliverable outcome was GitHub issues in the repositories under review, which is a shift from the standard “assessment report” provided by most security assessments in the space. You can view the issues [here](https://github.com/status-im/nimbus-eth2/labels?q=audit).
The desired deliverable outcome was GitHub issues in the repositories under review, which is a shift from the standard “assessment report” provided by most security assessments in the space.
You can view the issues [here](https://github.com/status-im/nimbus-eth2/labels?q=audit).
To be very clear, we did not engage in this security assessment to get a stamp of approval from the security community. All of the effort put into creating this process and engaging the community was in the service of increasing the level of security and code quality of the Nimbus software.
To be very clear, we did not engage in this security assessment to get a stamp of approval from the security community.
All of the effort put into creating this process and engaging the community was in the service of increasing the level of security and code quality of the Nimbus software.

36
docs/the_nimbus_book/src/beacon-node-systemd.md
View File

@ -2,17 +2,20 @@
This page will take you through how to set up a `systemd` service for your beacon node.
`systemd` is used in order to have a command or program run when your device boots (i.e. add it as a service). Once this is done, you can start/stop enable/disable from the linux prompt.
`systemd` is used in order to have a command or a program run when your device boots (i.e. add it as a service).
Once this is done, you can start/stop enable/disable from the linux prompt.
!!! abstract "`systemd`"
[`systemd`](https://systemd.io/) is a service manager designed specifically for Linux - it cannot be used on Windows / Mac. You can find out more about `systemd` [here](https://fedoramagazine.org/what-is-an-init-system/)
[`systemd`](https://systemd.io/) is a service manager designed specifically for Linux - it cannot be used on Windows / Mac.
You can find out more about `systemd` [here](https://fedoramagazine.org/what-is-an-init-system/)
!!! note "Package manager installations"
When installing Nimbus via your [package manager](./binaries.md), a user and service will already have been created for you and you can skip straight to the configuration section.
### 1. Create a dedicated user
We will start by creating a dedicated user and [data directory](./data-dir.md) for Nimbus. The same user can also be used for the execution client.
We will start by creating a dedicated user and [data directory](./data-dir.md) for Nimbus.
The same user can also be used for the execution client.
```sh
# Create the `nimbus` group
@ -50,16 +53,18 @@ sudo vi /etc/systemd/system/nimbus_beacon_node.service
sudo systemctl edit nimbus_beacon_node.service
```
The service file contains several options for controlling Nimbus. Important options include:
The service file contains several options for controlling Nimbus.
Important options include:
* `Environment=NETWORK`: set this to `mainnet`, `prater` or `sepolia`, depending on which network you want to connect to
* `Environment=WEB3_URL`: point this to your execution client - see the [Execution Client](./eth1.md) setup guide
* `Environment=REST_ENABLED`: REST is used to interact with the beacon node, in particular when setting up a separate Validator Client - see the [REST API](./rest-api.md) guide
* `Environment=METRICS_ENABLED`: Metrics are used for monitoring the node - see the [metrics](./metrics-pretty-pictures.md) setup guide
* `ExecStart=`: Custom options - see the [options](./options.md) guide
* `Environment=WEB3_URL`: point this to your execution client, see the [Execution Client](./eth1.md) setup guide
* `Environment=REST_ENABLED`: REST is used to interact with the beacon node, in particular when setting up a separate Validator Client, see the [REST API](./rest-api.md) guide
* `Environment=METRICS_ENABLED`: metrics are used for monitoring the node, see the [metrics](./metrics-pretty-pictures.md) setup guide
* `ExecStart=`: custom options, see the [options](./options.md) guide
!!! note
The example assumes Nimbus was installed in `/usr/bin/nimbus_beacon_node` - if you installed Nimbus elsewhere, make sure to update this path.
The example assumes Nimbus was installed in `/usr/bin/nimbus_beacon_node`.
If you installed Nimbus elsewhere, make sure to update this path.
### 4. Notify systemd of the newly added service
@ -93,9 +98,10 @@ You can also follow the logs using the following command:
sudo journalctl -uf nimbus_beacon_node.service
```
This will show you the Nimbus logs at the default setting -- it should include regular "slot start" messages which will show your [sync progress](./keep-an-eye.md#keep-track-of-your-syncing-progress). Press `ctrl-c` to stop following the logs.
This will show you the Nimbus logs at the default setting — it should include regular "slot start" messages which will show your [sync progress](./keep-an-eye.md#keep-track-of-your-syncing-progress).
Press `ctrl-c` to stop following the logs.
To rewind logs - by one day, say - run:
To rewind logs — by one day, say — run:
```sh
sudo journalctl -u nimbus_beacon_node.service --since yesterday
@ -103,7 +109,8 @@ sudo journalctl -u nimbus_beacon_node.service --since yesterday
## Import validator keys
When using a service, the beacon node is running as a different user - key import must be performed as this user in order for the key files to have the correct permission:
When using a service, the beacon node is running as a different user.
The key import must be performed as this user in order for the key files to have the correct permission:
```
# Run import command as the `nimbus` user
@ -111,7 +118,8 @@ sudo -u nimbus /usr/bin/nimbus_beacon_node deposit import --data-dir=/var/lib/ni
```
!!! note
Make sure to use the same `--data-dir` option as is used in the service file! Some guides use `--data-dir=/var/lib/nimbus` instead.
Make sure to use the same `--data-dir` option as is used in the service file!
Some guides use `--data-dir=/var/lib/nimbus` instead.
## Running multiple beacon nodes
@ -125,5 +133,5 @@ When running multiple beacon nodes, make sure that each service:
## Further examples
- A [service template file](https://github.com/chfast/ethereum-node/blob/main/nimbus%40.service) by Pawel Bylica which allows you to start two services at the same time: e.g. `nimbus@prater.service` and `nimbus@mainnet.service`.
- A [service template file](https://github.com/chfast/ethereum-node/blob/main/nimbus%40.service) by Pawel Bylica which allows you to start two services at the same time, e.g. `nimbus@prater.service` and `nimbus@mainnet.service`.
- The [EthereumOnARM](https://github.com/diglos/ethereumonarm/blob/main/fpm-package-builder/nimbus/extras/nimbus.service) project maintains a service file as part of their Ethereum installation package repository.

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

@ -8,7 +8,7 @@ We currently have binaries available for Linux `AMD64`, `ARM` and `ARM64`, Windo
The latest release is always available from [Github](https://github.com/status-im/nimbus-eth2/releases/latest) under the **Assets** header at the bottom of the page.
To install or upgrade a binary release, simply unpack the archive appropriate for your operating system and architecture in a directory of your choice, and run the binary.
To install or upgrade a binary release, unpack the archive appropriate for your operating system and architecture in a directory of your choice, and run the binary.
```sh
# Create a directory that can hold the beacon chain data and applications - this should be a fast SSD
@ -19,7 +19,7 @@ We currently have binaries available for Linux `AMD64`, `ARM` and `ARM64`, Windo
After unpacking, you may wish to [verify the checksum](./checksums.md).
=== "Debain / Ubuntu"
=== "Debian / Ubuntu"
Install Nimbus from our [APT repository](https://apt.status.im/):
@ -35,13 +35,16 @@ We currently have binaries available for Linux `AMD64`, `ARM` and `ARM64`, Windo
```
!!! note "Helper scripts"
When installing via package manager, replace `run-mainnet-beacon-node.sh` and similar helper scripts used in this guide with `nimbus_beacon_node` - blockchain data will be written to the default [data directory](./data-dir.md) unless changed with `--data-dir`.
When installing via package manager, replace `run-mainnet-beacon-node.sh` and similar helper scripts used in this guide with `nimbus_beacon_node`: blockchain data will be written to the default [data directory](./data-dir.md) unless changed with `--data-dir`.
!!! tip "`systemd`"
Packages include `systemd` service unit files - see the [systemd guide](./beacon-node-systemd.md) for usage instructions - the `nimbus` user is created as part of the installation process!
Packages include `systemd` service unit files: see the [systemd guide](./beacon-node-systemd.md) for usage instructions.
The `nimbus` user is created as part of the installation process!
## 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/).
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/).
For instructions on how to reproduce those binaries, see "README.md" inside the archive, as well as the [in-depth guide](./distribution_internals.md).

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

@ -1,9 +1,11 @@
# Build from source
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.
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 "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!
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
@ -44,14 +46,15 @@ When building from source, you will need additional build dependencies to be ins
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`
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)
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`.
> **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"

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

@ -2,7 +2,9 @@
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 🙏
For those of you who are unfamiliar, a [checksum](https://en.wikipedia.org/wiki/Checksum) is a special type of [hash](https://en.wikipedia.org/wiki/Hash_function) used to verify the integrity of a file. Verifying a checksum ensures there was no corruption or manipulation during the download and that the file was downloaded completely and correctly. For a short and simple guide on how to do so, [see here](https://www.devdungeon.com/content/how-verify-checksum).
For those of you who are unfamiliar, a [checksum](https://en.wikipedia.org/wiki/Checksum) is a special type of [hash](https://en.wikipedia.org/wiki/Hash_function) used to verify the integrity of a file.
Verifying a checksum ensures there was no corruption or manipulation during the download and that the file was downloaded completely and correctly.
For a short and simple guide on how to do so, [see here](https://www.devdungeon.com/content/how-verify-checksum).
In the case of the [v1.1.0](https://github.com/status-im/nimbus-eth2/releases/tag/v1.1.0) release for example, the SHA512 checksums are:

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

@ -1,12 +1,13 @@
# Start validating
Once your keys have been [imported](./keys.md), it is time to configure a [fee recipient](./suggested-fee-recipient.md) and restart the beacon node to start validating!
Once your keys have been [imported](./keys.md), it is time to configure a [fee recipient](./suggested-fee-recipient.md) and restart the beacon node to start validating.
## Steps
### 1. Choose a fee recipient
The [fee recipient](./suggested-fee-recipient.md) is an Ethereum address that receives transaction fees from the blocks that your validators produce. You can set up a separate address or reuse the address from which you funded your deposits.
The [fee recipient](./suggested-fee-recipient.md) is an Ethereum address that receives transaction fees from the blocks that your validators produce.
You can set up a separate address or reuse the address from which you funded your deposits.
### 2. (Re)start the node
@ -24,7 +25,8 @@ Press `Ctrl-c` to stop the beacon node if it's running, then use the same comman
### 3. Check the logs
Your beacon node will launch and connect your validator to the beacon chain network. To check that keys were imported correctly, look for `Local validator attached` in the logs:
Your beacon node will launch and connect your validator to the beacon chain network.
To check that keys were imported correctly, look for `Local validator attached` in the logs:
```
INF 2020-11-18 11:20:00.181+01:00 Launching beacon node
@ -32,4 +34,6 @@ INF 2020-11-18 11:20:00.181+01:00 Launching beacon node
NOT 2020-11-18 11:20:02.091+01:00 Local validator attached
```
Congratulations! Your node is now ready to perform validator duties. Depending on when the deposit was made, it may take a while before the first attestation is sent - this is normal.
Congratulations!
Your node is now ready to perform validator duties.
Depending on when the deposit was made, it may take a while before the first attestation is sent — this is normal.

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

@ -29,7 +29,8 @@ 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:
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

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

@ -1,11 +1,13 @@
# The data directory
Nimbus stores all the information it needs to run in a data directory. In this directory, you'll find a database, your validator keys and secrets and several other items.
Nimbus stores all the information it needs to run in a data directory.
In this directory, you'll find a database, your validator keys and secrets, and several other items.
When following the installation guide, the chain data will be stored in `build/data` with separate directories for each chain (mainnet, prater, etc).
!!! 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!
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
@ -26,16 +28,19 @@ drwx------ 1 nimbus nimbus 250 Jul 19 18:18 validators
### `db`
The `db` folder contains historical chain data and information about the latest observed state of the chain. If you remove the `db` folder, the beacon node will have to resync.
The `db` folder contains historical chain data and information about the latest observed state of the chain.
If you remove the `db` folder, the beacon node will have to resync.
The growth of the database depends on the [history mode](./history.md).
### `secrets` and `validators`
These two folders contain your validator keys as well as the passwords needed to unlock them when starting the beacon node.
These two folders contain your validator keys, as well as the passwords needed to unlock them when starting the beacon node.
!!! warning
Be careful not to copy the `secrets` and `validator` folders, leaving them in two locations - instead, always move them to the new location! Using the same validators with two nodes poses a significant slashing risk!
Be careful not to copy the `secrets` and `validator` folders, leaving them in two locations!
Instead, always _move_ them to the new location.
Using the same validators with two nodes poses a significant slashing risk!
## Moving the data directory
@ -43,7 +48,8 @@ You can move the data directory to another location or computer simply by moving
## Permissions
To protect against key loss, Nimbus requires that files and directories be owned by the user running the application. Furthermore, they should not be readable by others.
To protect against key loss, Nimbus requires that files and directories be owned by the user running the application.
Furthermore, they should not be readable by others.
It may happen that the wrong permissions are applied, particularly when creating the directories manually.
@ -55,50 +61,52 @@ The following errors are a sign of this:
Here is how to fix them.
### Linux/ BSD / MacOS
=== "Linux / BSD / MacOS"
Run:
Run:
```sh
# Changing ownership to `user:group` for all files/directories in <data-dir>.
chown user:group -R <data-dir>
# Set permissions to (rwx------ 0700) for all directories starting from <data-dir>
find <data-dir> -type d -exec chmod 700 {} \;
```sh
# Changing ownership to `user:group` for all files/directories in <data-dir>.
chown user:group -R <data-dir>
# Set permissions to (rwx------ 0700) for all directories starting from <data-dir>
find <data-dir> -type d -exec chmod 700 {} \;
# Set permissions to (rw------- 0600) for all files inside <data-dir>/validators
find <data-dir>/validators -type f -exec chmod 0600 {} \;
# Set permissions to (rw------- 0600) for all files inside <data-dir>/validators
find <data-dir>/validators -type f -exec chmod 0600 {} \;
# Set permissions to (rw------- 0600) for all files inside <data-dir>/secrets
find <data-dir>/secrets -type f -exec chmod 0600 {} \;
# Set permissions to (rw------- 0600) for all files inside <data-dir>/secrets
find <data-dir>/secrets -type f -exec chmod 0600 {} \;
```
```
In sum:
In sum:
- Directories `<data-dir>`, `<data-dir>/validators`, `<data-dir>/secrets` **must** be owned by user and have `rwx------` or `0700`permissions set.
- Directories `<data-dir>`, `<data-dir>/validators`, `<data-dir>/secrets` MUST be owned by user and have `rwx------` or `0700`permissions set.
- Files stored inside `<data-dir>`, `<data-dir>/validators`, `/secrets` **must** be owned by user and have `rw------` or `0600` permission set.
- Files stored inside `<data-dir>`, `<data-dir>/validators`, `/secrets` MUST be owned by user and have `rw------` or `0600` permission set.
=== "Windows"
### Windows
From inside `Git Bash`, run:
From inside `Git Bash`, run:
```sh
# Set permissions for all the directories starting from <data-dir>
find <data-dir> -type d -exec icacls {} /inheritance:r /grant:r $USERDOMAIN\\$USERNAME:\(OI\)\(CI\)\(F\) \;
```sh
# Set permissions for all the directories starting from <data-dir>
find <data-dir> -type d -exec icacls {} /inheritance:r /grant:r $USERDOMAIN\\$USERNAME:\(OI\)\(CI\)\(F\) \;
# Set permissions for all the files inside <data-dir>/validators
find <data-dir>/validators -type f -exec icacls {} /inheritance:r /grant:r $USERDOMAIN\\$USERNAME:\(F\) \;
# Set permissions for all the files inside <data-dir>/validators
find <data-dir>/validators -type f -exec icacls {} /inheritance:r /grant:r $USERDOMAIN\\$USERNAME:\(F\) \;
# Set permissions for all the files inside <data-dir>/secrets
find <data-dir>/secrets -type f -exec icacls {} /inheritance:r /grant:r $USERDOMAIN\\$USERNAME:\(F\) \;
```
# Set permissions for all the files inside <data-dir>/secrets
find <data-dir>/secrets -type f -exec icacls {} /inheritance:r /grant:r $USERDOMAIN\\$USERNAME:\(F\) \;
```
!!! note
Make sure you run the above from inside `Git Bash`, these commands will not work from inside the standard Windows Command Prompt.
If you don't already have a `Git Bash` shell, you'll need to install [Git for Windows](https://gitforwindows.org/).
!!! note
Make sure you run the above from inside `Git Bash`, these commands will not work from inside the standard Windows Command Prompt. If you don't already have a `Git Bash` shell, you'll need to install [Git for Windows](https://gitforwindows.org/).
In sum:
In sum:
- Directories `<data-dir>`, `<data-dir>/validators`, `<data-dir>/secrets` **must** be owned by user and have permissions set for the user only (OI)(CI)(F).
All inherited permissions should be removed.
- Directories `<data-dir>`, `<data-dir>/validators`, `<data-dir>/secrets` MUST be owned by user and have permissions set for the user only (OI)(CI)(F). All inherited permissions should be removed.
- Files which are stored inside <data-dir>, <data-dir>/validators, <data-dir>/secrets MUST be owned by user and have permissions set for the user only (F). All inherited permissions should be removed.
- Files which are stored inside <data-dir>, <data-dir>/validators, <data-dir>/secrets **must** be owned by user and have permissions set for the user only (F).
All inherited permissions should be removed.

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

@ -1,3 +1,3 @@
# Back up your database
The best way to do this is to simply copy it over: you'll find it either in `build/data/shared_mainnet_0/db/` (if you're running Prater, `shared_prater_0`) or the directory you supplied to the `--data-dir` argument when you launched Nimbus).
The best way to do this is to simply copy it over: you'll find it either in `build/data/shared_mainnet_0/db/` (if you're running Prater, `shared_prater_0`) or the directory you supplied to the `--data-dir` argument when you launched Nimbus.

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

@ -9,7 +9,8 @@ To make a deposit, you will need to generate keys then submit a deposit transact
* [Goerli/Prater EthStaker Launchpad](https://goerli.launchpad.ethstaker.cc/en/) or [Goerli/Prater EF Launchpad](https://prater.launchpad.ethereum.org/)
!!! tip
Use Prater to stress test / future proof your set up against peak mainnet load. See [here](./prater.md) for all you need to know
Use Prater to stress test and future proof your set up against peak mainnet load.
See [here](./prater.md) for all you need to know.
## Steps
@ -31,7 +32,8 @@ tar xvf staking_deposit-cli-9ab0b05-linux-amd64.tar.gz --strip-components 2
### 2. Generate keys
!!! tip "Live image"
You can increase the security of this process by downloading a [Live linux image](https://ubuntu.com/tutorials/try-ubuntu-before-you-install). To do so, copy `deposit` to a USB stick, boot into the live image, and run the tool from inside the image. Make sure you **don't** enable Wifi and unplug any Ethernet cables when using this process.
You can increase the security of this process by downloading a [Live linux image](https://ubuntu.com/tutorials/try-ubuntu-before-you-install). To do so, copy `deposit` to a USB stick, boot into the live image, and run the tool from inside the image.
Make sure you **don't** enable Wifi and unplug any Ethernet cables when using this process.
The deposit tool generates a seed phrase, and uses this to create validator and withdrawal keys.
@ -52,7 +54,8 @@ The deposit tool generates a seed phrase, and uses this to create validator and
### 3. Make the deposit
Once created, the keys are used to create a deposit transaction on the Ethereum execution chain. Follow the instructions at https://launchpad.ethereum.org/en/upload-deposit-data to upload the deposit data.
Once created, the keys are used to create a deposit transaction on the Ethereum execution chain.
Follow the instructions [here](https://launchpad.ethereum.org/en/upload-deposit-data) to upload the deposit data.
!!! warning
If you are making a mainnet deposit make sure you verify that the deposit contract you are interacting with is the correct one.
@ -60,6 +63,9 @@ Once created, the keys are used to create a deposit transaction on the Ethereum
You should verify that the address is indeed: [0x00000000219ab540356cBB839Cbe05303d7705Fa](https://etherscan.io/address/0x00000000219ab540356cBB839Cbe05303d7705Fa)
!!! info
Once you send off your transaction(s), your validator will be put in a queue based on deposit time. Getting through the queue may take a few hours or days (assuming the chain is finalising). No validators are accepted into the validator set while the chain isn't finalising. The `Pending Validators` metric on the [beaconcha.in](https://beaconcha.in/) will give you the size of the queue.
Once you send off your transaction(s), your validator will be put in a queue based on deposit time.
Getting through the queue may take a few hours or days (assuming the chain is finalizing).
No validators are accepted into the validator set while the chain isn't finalizing.
The `Pending Validators` metric on the [beaconcha.in](https://beaconcha.in/) will give you the size of the queue.
With the keys created, you're ready to perform the [key import](./keys.md).

127
docs/the_nimbus_book/src/developers.md
View File

@ -7,7 +7,7 @@ Before building Nimbus for the first time, make sure to install the [prerequisit
## Helpful resources
* [Ethereum consensus spec](https://github.com/ethereum/consensus-specs/)
* [Ben Edgington's annotated spec](hhttps://eth2book.info/bellatrix/)
* [Ben Edgington's annotated spec](https://eth2book.info/bellatrix/)
* [Vitalik's annotated spec](https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md)
## Code style
@ -70,7 +70,8 @@ make update
## Environment
Nimbus comes with a build environment similar to Python venv - this helps ensure that the correct version of Nim is used and that all dependencies can be found.
Nimbus comes with a build environment similar to Python venv.
This helps ensure that the correct version of Nim is used and that all dependencies can be found.
```bash
./env.sh bash # start a new interactive shell with the right env vars set
@ -89,95 +90,82 @@ nim --version # Nimbus is tested and supported on 1.2.12 at the moment
## Makefile tips and tricks for developers
- build all those tools known to the Makefile:
```bash
# $(nproc) corresponds to the number of cores you have
make -j $(nproc)
```
```bash
# $(nproc) corresponds to the number of cores you have
make -j $(nproc)
```
- build a specific tool:
```bash
make state_sim
```
```bash
make state_sim
```
- you can control the Makefile's verbosity with the V variable (defaults to 0):
```bash
make V=1 # verbose
make V=2 test # even more verbose
```
```bash
make V=1 # verbose
make V=2 test # even more verbose
```
- same for the [Chronicles log level](https://github.com/status-im/nim-chronicles#chronicles_log_level):
```bash
make LOG_LEVEL=DEBUG bench_bls_sig_agggregation # this is the default
make LOG_LEVEL=TRACE nimbus_beacon_node # log everything
```
```bash
make LOG_LEVEL=DEBUG bench_bls_sig_aggregation # this is the default
make LOG_LEVEL=TRACE nimbus_beacon_node # log everything
```
- pass arbitrary parameters to the Nim compiler:
```bash
make NIMFLAGS="-d:release"
```
```bash
make NIMFLAGS="-d:release"
```
- you can freely combine those variables on the `make` command line:
```bash
make -j$(nproc) NIMFLAGS="-d:release" USE_MULTITAIL=yes eth2_network_simulation
```
```bash
make -j$(nproc) NIMFLAGS="-d:release" USE_MULTITAIL=yes eth2_network_simulation
```
- don't use the [lightweight stack tracing implementation from nim-libbacktrace](https://github.com/status-im/nimbus-eth2/pull/745):
```bash
make USE_LIBBACKTRACE=0 # expect the resulting binaries to be 2-3 times slower
```
```bash
make USE_LIBBACKTRACE=0 # expect the resulting binaries to be 2-3 times slower
```
- disable `-march=native` because you want to run the binary on a different machine than the one you're building it on:
```bash
make NIMFLAGS="-d:disableMarchNative" nimbus_beacon_node
```
```bash
make NIMFLAGS="-d:disableMarchNative" nimbus_beacon_node
```
- disable link-time optimisation (LTO):
```bash
make NIMFLAGS="-d:disableLTO" nimbus_beacon_node
```
- disable link-time optimization (LTO):
```bash
make NIMFLAGS="-d:disableLTO" nimbus_beacon_node
```
- show C compiler warnings:
```bash
make NIMFLAGS="-d:cwarnings" nimbus_beacon_node
```
```bash
make NIMFLAGS="-d:cwarnings" nimbus_beacon_node
```
- limit stack usage to 1 MiB per C function (static analysis - see the [GCC docs](https://gcc.gnu.org/onlinedocs/gnat_ugn/Static-Stack-Usage-Analysis.html); if LTO is enabled, it works without `-d:cwarnings`):
```bash
make NIMFLAGS="-d:limitStackUsage" nimbus_beacon_node
```
```bash
make NIMFLAGS="-d:limitStackUsage" nimbus_beacon_node
```
- build a static binary:
```bash
make NIMFLAGS="--passL:-static" nimbus_beacon_node
```
```bash
make NIMFLAGS="--passL:-static" nimbus_beacon_node
```
- publish a book using [mdBook](https://github.com/rust-lang/mdBook) from sources in "docs/" to GitHub pages:
```bash
make publish-book
```
```bash
make publish-book
```
- create a binary distribution:
```bash
make dist
```
```bash
make dist
```
## Multi-client interop scripts
[This repository](https://github.com/eth2-clients/multinet) contains a set of scripts used by the client implementation teams to test interop between the clients (in certain simplified scenarios). It mostly helps us find and debug issues.
[This repository](https://github.com/eth2-clients/multinet) contains a set of scripts used by the client implementation teams to test interop between the clients (in certain simplified scenarios).
It mostly helps us find and debug issues.
## Stress-testing the client by limiting the CPU power
@ -185,8 +173,9 @@ make dist
make prater CPU_LIMIT=20
```
The limiting is provided by the cpulimit utility, available on Linux and macOS.
The specified value is a percentage of a single CPU core. Usually 1 - 100, but can be higher on multi-core CPUs.
The limiting is provided by the `cpulimit` utility, available on Linux and macOS.
The specified value is a percentage of a single CPU core.
Usually 1 - 100, but can be higher on multi-core CPUs.
## Build and run the local beacon chain simulation
@ -230,7 +219,8 @@ You can find out more about the beacon node simulation [here](https://our.status
This simulation is primarily designed for researchers, but we'll cover it briefly here in case you're curious :)
The [state transition](https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md#beacon-chain-state-transition-function) simulation quickly runs the beacon chain state transition function in isolation and outputs JSON snapshots of the state (directly to the `nimbus-eth2` directory). It runs without networking and blocks are processed without slot time delays.
The [state transition](https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md#beacon-chain-state-transition-function) simulation quickly runs the beacon chain state transition function in isolation and outputs JSON snapshots of the state (directly to the `nimbus-eth2` directory).
It runs without networking and blocks are processed without slot time delays.
```bash
# build the state simulator, then display its help ("-d:release" speeds it
@ -239,11 +229,12 @@ make NIMFLAGS="-d:release" state_sim
build/state_sim --help
```
Use the output of the `help` command to pass desired values to the simulator - experiment with changing the number of slots, validators, , etc. to get different results.
Use the output of the `help` command to pass desired values to the simulator.
Experiment with changing the number of slots, validators, etc. to get different results.
The most important options are:
- `slots` : the number of slots to run the simulation for (default 192)
- `slots`: the number of slots to run the simulation for (default 192)
- `validators`: the number of validators (default 6400)
- `attesterRatio`: the expected fraction of attesters that actually do their work for every slot (default 0.73)
- `json_interval`: how often JSON snapshots of the state are outputted (default every 32 slots -- or once per epoch)

21
docs/the_nimbus_book/src/distribution_internals.md
View File

@ -27,17 +27,18 @@ binaries, etc); they get access to the source code through the use of external v
## Build process
It all starts from the GitHub actions in `.github/workflows/release.yml`. There
is a different job for each supported OS-architecture combination and they all
It all starts from the GitHub actions in `.github/workflows/release.yml`.
There is a different job for each supported OS-architecture combination and they all
run in parallel (ideally).
Once all those CI jobs complete successfully, a GitHub release draft is created
and all the distributable archives are uploaded to it. A list of checksums for
the main binaries is inserted in the release description. That draft needs to
be manually published.
Once all those CI jobs are completed successfully, a GitHub release draft is created
and all the distributable archives are uploaded to it.
A list of checksums for
the main binaries is inserted in the release description.
That draft needs to be manually published.
The build itself is triggered by a Make target. E.g.: `make dist-amd64`. This invokes
`scripts/make_dist.sh` which builds the corresponding Docker container from
The build itself is triggered by a Make target, e.g. `make dist-amd64`.
This invokes `scripts/make_dist.sh` which builds the corresponding Docker container from
`docker/dist/` and runs it with the Git repository's top directory as an external
volume.
@ -48,8 +49,8 @@ create distributable tarballs.
## Docker images for end users
Configured in `.github/workflows/release.yml` (only for Linux AMD64, ARM and
ARM64): we unpack the distribution tarball and copy its content into a third
type of Docker image - meant for end users and defined by
ARM64), we unpack the distribution tarball and copy its content into a third
type of Docker image — meant for end users and defined by
`docker/dist/binaries/Dockerfile.amd64` (and related).
We then publish that to [Docker Hub](https://hub.docker.com/r/statusim/nimbus-eth2).

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

@ -6,7 +6,8 @@ We have version-specific Docker tags (e.g. `statusim/nimbus-eth2:amd64-v1.2.3`)
These images contain the same binaries as the [release tarballs](./binaries.md) inside a `debian:bullseye-slim` image, running under a user imaginatively named `user`, with UID:GID of 1000:1000.
The binaries are placed under the `/home/user/` directory which is also the default *WORKDIR*. The *ENTRYPOINT* of the image is configured to directly launch the respective binary without any extra arguments.
The binaries are placed under the `/home/user/` directory which is also the default *WORKDIR*.
The *ENTRYPOINT* of the image is configured to directly launch the respective binary without any extra arguments.
## Usage
@ -36,11 +37,13 @@ docker run -it --rm \
```
!!! warning
Do not use the same data directory for beacon node and validator client - they will both try to load the same keys which may result in slashing!
Do not use the same data directory for beacon node and validator client!
They will both try to load the same keys which may result in slashing.
### 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:
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:
```sh
mkdir data
@ -48,4 +51,5 @@ docker-compose -f docker-compose-example1.yml up --quiet-pull --no-color --detac
```
!!! 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.
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.

3
docs/the_nimbus_book/src/doppelganger-detection.md
View File

@ -6,7 +6,8 @@ Doppelganger detection works by monitoring network activity for a short period f
If any activity is detected, the node shuts down with exit code 129.
Because detection depends on network detection, there are cases where it may fail to find duplicate validators even though they are live - you should never use it as a mechanism for running redundant setups!
Because detection depends on network detection, there are cases where it may fail to find duplicate validators even though they are live.
You should never use it as a mechanism for running redundant setups!
## Command line

4
docs/the_nimbus_book/src/email-notifications.md
View File

@ -2,7 +2,9 @@
You can create an account on [beaconcha.in](https://beaconcha.in/) to set up email notifications in case your validator loses balance (goes offline), or gets slashed.
>**Tip:** If your validator loses balance for two epochs in a row, you may want to investigate. It's a strong signal that it may be offline.
!!! tip
If your validator loses balance for two epochs in a row, you may want to investigate.
It's a strong signal that it may be offline.
### 1. Sign up at [beaconcha.in/register](https://beaconcha.in/register)

24
docs/the_nimbus_book/src/era-store.md
View File

@ -1,14 +1,18 @@
# Era store
!!! warning
This feature is currently in BETA - nodes using era files may need to be resynced as the data format is not yet considered stable.
This feature is currently in BETA!
Nodes using era files may need to be resynced as the data format is not yet considered stable.
Era files are a long-term archival format for Ethereum data. They are used to provide an easy interchange medium that clients interested in deep ethereum history can use to recreate past states.
Era files are a long-term archival format for Ethereum data.
They are used to provide an easy interchange medium that clients interested in deep ethereum history can use to recreate past states.
!!! tip
For more information about era files, see [this post](https://ethresear.ch/t/era-archival-files-for-block-and-consensus-data/13526).
Each era file contains the blocks of 8192 slots (~27 hours). Blocks in era files are considered finalized - since the history no longer is subject to change, the files are suitable to be archived for long-term storage, history recreation and other uses and can be shared using traditional mediums such as `http` and `bittorrent`.
Each era file contains the blocks of 8192 slots (~27 hours).
Blocks in era files are considered finalized.
Since the history no longer is subject to change, the files are suitable to be archived for long-term storage, history recreation and other uses, and can be shared using traditional mediums such as `http` and `bittorrent`.
Nimbus can both create and use era files as a starting point to regenerate past history as well as to serve blocks.
@ -31,7 +35,8 @@ With the era files present, perform a [trusted node sync](./trusted-node-sync.md
## Generating era files
To generate era files, you need to first [build](./build.md) Nimbus from source and [sync](./start-syncing.md) the node using full sync. A checkpoint-synced node can be used to generate era files from the checkpoint onwards.
To generate era files, you need to first [build](./build.md) Nimbus from source and [sync](./start-syncing.md) the node using full sync.
A checkpoint-synced node can be used to generate era files from the checkpoint onwards.
After that, build the additional `ncli_db` tool:
@ -39,7 +44,8 @@ After that, build the additional `ncli_db` tool:
make ncli_db
```
The era export tool works by reading an existing Nimbus database and creating an era store. Every time the tool is run, it will check the existing store and export any new data to it.
The era export tool works by reading an existing Nimbus database and creating an era store.
Every time the tool is run, it will check the existing store and export any new data to it.
```sh
# Go to the data directory of nimbus (the directory passed to --data-dir)
@ -53,12 +59,14 @@ cd era
../../../ncli_db exportEra --db:../db
```
The first time the export is run, full history is exported which may take some time. Subsequent runs will top up the era store with new blocks.
The first time the export is run, full history is exported which may take some time.
Subsequent runs will top up the era store with new blocks.
It is recommended to set up a cron job or a timer, and run the export command every hour - doing so will ensure that era files are created on a timely basis.
!!! tip
You do not need to stop Nimbus to generate era files - it is however not recommended to run era file generation on a node that is also serving validators.
You do not need to stop Nimbus to generate era files.
It is however not recommended to run era file generation on a node that is also serving validators.
## Sharing era files
@ -73,4 +81,4 @@ nimbus_beacon_node --era-dir:/path/to/era
```
!!! tip
Multiple nimbus beacon node instances can share the same era store
Multiple nimbus beacon node instances can share the same era store.

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

@ -1,11 +1,12 @@
# Run an execution client
In order to perform validation duties, you need to also be running an execution client - at least one for each beacon node.
In order to perform validation duties, you need to also be running an execution client — at least one for each beacon node.
Nimbus has been tested all major execution clients - see the [execution client comparison](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) for more information.
Nimbus has been tested all major execution clients, see the [execution client comparison](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) for more information.
!!! warning
You need to run your own execution client - relying on third-party services such as Infura, Alchemy and Pocket is no longer possible.
You need to run your own execution client.
Relying on third-party services such as Infura, Alchemy and Pocket is no longer possible.
Sharing the same execution client between multiple beacon nodes is not supported.
!!! info
@ -66,11 +67,11 @@ The execution client needs to be running at all times in order for the beacon no
It will start its syncing process as soon as the beacon node connects to it.
Once both are synced, they will continue to work in tandem to validate the latest Ethereum state.
It is safe to start the beacon node even if the execution client is not yet fully synced and vice versa.
It is safe to start the beacon node even if the execution client is not yet fully synced, and vice versa.
### 3. Pass the URL and JWT secret to Nimbus
The `--el` option informs the beacon node how to connect to the execution client - both `http://` and `ws://` URLs are supported.
The `--el` option informs the beacon node how to connect to the execution client — both `http://` and `ws://` URLs are supported.
!!! info
By default, the execution client accepts connections on the localhost interface (`127.0.0.1`), with default authenticated RPC port `8551`.
@ -114,7 +115,7 @@ To enable this mode, just specify multiple URLs through the `--el` option when s
!!! tip
You can use a different secret for each connection by specifying `jwt-secret` or `jwt-secret-file` as a query parameter in the anchor section of the URL (e.g. `http://127.0.0.1:8551/#jwt-secret=0x12345...` or `http://127.0.0.1:8551/#jwt-secret-file=/tmp/jwtsecret`).
If you use a [TOML config file](./options.md#configuration-files), you can also use the following more natural syntax:
If you use a [TOML config file](./options.md#configuration-files), you can also use the following, more natural, syntax:
```toml
data-dir = "my-data-dir"

5
docs/the_nimbus_book/src/external-block-builder.md
View File

@ -9,12 +9,13 @@ Setting up external block building typically involves running an additional serv
!!! warning
External block builders introduce additional risk to the block building process which may cause loss of rewards.
In particular, once Nimbus has signed the block header proposed by the external builder, the execution client can no longer be used as fallback and the external builder is trusted to complete the building process.
In particular, once Nimbus has signed the block header proposed by the external builder, the execution client can no longer be used as fallback, and the external builder is trusted to complete the building process.
!!! note
By default, [priority and maximum gas fees](https://eips.ethereum.org/EIPS/eip-1559#abstract) determine transaction inclusion in blocks.
External block builders may use other strategies for transaction selection, including regulatory constraints and extracted value. For further information, check the documentation of the block builder.
External block builders may use other strategies for transaction selection, including regulatory constraints and extracted value.
For further information, check the documentation of the block builder.
## Command line

120
docs/the_nimbus_book/src/faq.md
View File

@ -19,7 +19,8 @@ curl -s http://localhost:9100/eth/v1/node/version
### Why are metrics not working?
The metrics server is disabled by default: enable it by passing `--metrics` to the run command:
The metrics server is disabled by default
Enable it by passing `--metrics` to the run command:
```sh
build/nimbus_beacon_node --metrics ...
@ -27,7 +28,8 @@ build/nimbus_beacon_node --metrics ...
### Why is the REST server not working?
The REST server is disabled by default: enable it by passing `--rest` to the run command:
The REST server is disabled by default.
Enable it by passing `--rest` to the run command:
```sh
build/nimbus_beacon_node --rest ...
@ -37,30 +39,37 @@ build/nimbus_beacon_node --rest ...
When a validator is started (or restarted) it prudently listens for 2 epochs for attestations from a validator with the same index (a doppelganger), before sending an attestation itself.
In sum, it's a simple way of handling the case where one validator comes online with the same key as another validator that's already online (i.e one device was started without switching the other off).
In sum, it's a simple way of handling the case where one validator comes online with the same key as another validator that's already online (i.e. one device was started without switching the other off).
While this strategy requires the client to wait two whole epochs on restart before attesting, a couple of missed attestations is a very minor price to pay in exchange for significantly reducing the risk of an accidental slashing.
You can think of it as a small penalty that you pay only on first launch and restarts. When you take into account the total runtime of your validator, the impact should be minimal.
You can think of it as a small penalty that you pay only on first launch and restarts.
When you take into account the total runtime of your validator, the impact should be minimal.
While we strongly recommend it, you can disable it with an explicit flag (`--doppelganger-detection=false`) if you don't plan on moving your setup.
### What's the best way to stress test my execution + consensus setup before committing with real ETH?
We recommend running [a Nimbus beacon node](./quick-start.md) on [Prater](./prater.md) and a mainnet [execution client](./eth1.md) on the same machine - this will simulate the load of running a mainnet validator.
We recommend running [a Nimbus beacon node](./quick-start.md) on [Prater](./prater.md) and a mainnet [execution client](./eth1.md) on the same machine.
This will simulate the load of running a mainnet validator.
To stress test it, add `--subscribe-all-subnets` to the [beacon node options](./options.md). This simulates the maximum load that the consensus layer will put on the machine should you run 64 validators or more on it.
To stress test it, add `--subscribe-all-subnets` to the [beacon node options](./options.md).
This simulates the maximum load that the consensus layer will put on the machine should you run 64 validators or more on it.
### How do I add an additional validator?
To add an additional validator, follow [the same steps](./keys.md) as you did when you added your first. You'll have to restart the beacon node for the changes to take effect.
To add an additional validator, follow [the same steps](./keys.md) as you did when you added your first.
You'll have to restart the beacon node for the changes to take effect.
!!! note
Note that a single Nimbus instance is able to handle multiple validators.
A single Nimbus instance is able to handle multiple validators.
### What does `synced/opt` mean, in the "Slot start" message?
When `/opt` is present in the "Slot start" message, it means the node is [optimistically synced](./optimistic-sync.md) and is waiting for the execution client to finish its syncing process - until that happens, validator duties are disabled.
When `/opt` is present in the "Slot start" message, it means the node is [optimistically synced](./optimistic-sync.md) and is waiting for the execution client to finish its syncing process.
Until that happens, validator duties are disabled.
## Networking
@ -78,13 +87,15 @@ It's possible that your ISP has changed your dynamic IP address without you know
The first thing to do it to try relaunching the beacon node with `--enr-auto-update` (pass it as an option in the command line).
If this doesn't fix the problem, the next thing to do is to check your external (public) IP address and detect open ports on your connection - you can use [https://www.yougetsignal.com/tools/open-ports/](https://www.yougetsignal.com/tools/open-ports/ ). Note that Nimbus `TCP` and `UDP` ports are both set to `9000` by default.
If this doesn't fix the problem, the next thing to do is to check your external (public) IP address and detect open ports on your connection: you can use [https://www.yougetsignal.com/tools/open-ports/](https://www.yougetsignal.com/tools/open-ports/).
Note that Nimbus `TCP` and `UDP` ports are both set to `9000` by default.
See [here](./health.md#set-up-port-forwarding), for how to set up port forwarding.
See [here](./health.md#set-up-port-forwarding) for how to set up port forwarding.
## Folder Permissions
To protect against key loss, Nimbus requires that files and directories be owned by the user running the application. Furthermore, they should not be readable by others.
To protect against key loss, Nimbus requires that files and directories be owned by the user running the application.
Furthermore, they should not be readable by others.
It may happen that the wrong permissions are applied, particularly when creating the directories manually.
@ -102,7 +113,8 @@ See the [data directory](./data-dir.md#permissions) page for instructions on how
A validator is an entity that participates in the consensus of the Ethereum protocol, and has staked 32 ETH to do so.
Or in plain english, a human running a computer process. This process proposes and vouches for new blocks to be added to the blockchain.
Or, in plain English, a human running a computer process.
This process proposes and vouches for new blocks to be added to the blockchain.
In other words, **you can think of a validator as a voter for new blocks.** The more votes a block gets, the more likely it is to be added to the chain.
@ -123,19 +135,23 @@ In other words, to keep them honest, their actions need to have financial conseq
### How much ETH does a validator need to stake?
Before a validator can start to secure the network, they need to stake **32 ETH**. This forms the validator's initial balance.
Before a validator can start to secure the network, they need to stake **32 ETH**.
This forms the validator's initial balance.
### Is there any advantage to having more than 32 ETH at stake?
No. There is no advantage to having more than 32 ETH staked.
No.
There is no advantage to having more than 32 ETH staked.
Limiting the maximum stake to 32 ETH encourages decentralization of power as it prevents any single validator from having an excessively large vote on the state of the chain.
> Remember that a validator’s vote is weighted by the amount it has at stake.
!!! note ""
Remember that a validator’s vote is weighted by the amount it has at stake.
### Can I stop my validator for a few days and then start it back up again?
Yes but, under normal conditions, you will lose an amount of ETH roughly equivalent to the amount of ETH you would have gained in that period. In other words, if you stood to earn ≈0.01 ETH, you would instead be penalised ≈0.01 ETH.
Yes but, under normal conditions, you will lose an amount of ETH roughly equivalent to the amount of ETH you would have gained in that period.
In other words, if you stood to earn ≈0.01 ETH, you would instead be penalized ≈0.01 ETH.
### I want to switch my validator keys to another machine, how long do I need to wait to avoid getting slashed?
@ -151,26 +167,27 @@ At the other end of the spectrum, if your balance is closer to 31 ETH, it's prob
### When can I withdraw my funds, and what's the difference between exiting and withdrawing?
After the Capella hard-fork, activated on 12th of April 2023, all exited validators that use 0x01 withdrawal credentials will have their funds automatically withdrawn. Please see our dedicated [guide for withdrawals](./withdrawals.md) for further information.
After the Capella hard-fork, activated on 12th of April 2023, all exited validators that use 0x01 withdrawal credentials will have their funds automatically withdrawn.
Please see our dedicated [guide for withdrawals](./withdrawals.md) for further information.
### How are validators incentivized to stay active and honest?
In addition to being penalized for being offline, validators are penalized for behaving maliciously – for example attesting to invalid or contradicting blocks.
In addition to being penalized for being offline, validators are penalized for behaving maliciously.
For example, attesting to invalid or contradicting blocks.
On the other hand, they are rewarded for proposing / attesting to blocks that are included in the chain.
The key concept is the following:
- Rewards are given for actions that help the network reach consensus
- Minor penalties are given for inadvertant actions (or inactions) that hinder consensus
- And major penalities -- or **slashings** -- are given for malicious actions
- Rewards are given for actions that help the network reach consensus.
- Minor penalties are given for inadvertent actions (or inactions) that hinder consensus.
- And major penalties — or **slashings** — are given for malicious actions.
In other words, validators that maximize their rewards also provide the greatest benefit to the network as a whole.
### How are rewards/penalties issued?
Remember that each validator has its own balance -- with the initial balance outlined in the deposit contract.
Remember that each validator has its own balance, with the initial balance outlined in the deposit contract.
This balance is updated periodically by the Ethereum network rules as the validator carries (or fails to carry) out his or her responsibilities.
Put another way, rewards and penalties are reflected in the validator's balance over time.
@ -178,7 +195,7 @@ Put another way, rewards and penalties are reflected in the validator's balance
### How often are rewards/penalties issued?
Approximately every six and a half minutes -- a period of time known as an epoch.
Approximately every six and a half minutes — a period of time known as an epoch.
Every epoch, the network measures the actions of each validator and issues rewards or penalties appropriately.
@ -187,11 +204,15 @@ Every epoch, the network measures the actions of each validator and issues rewar
There is no easy answer to this question as there are many factors that go into this calculation.
Arguably the most impactful factor on rewards earned for validating transactions is the total amount of stake in the network. In other words, the total amount of validators. Depending on this figure the max annual return rate for a validator can be anywhere between 2 and 20%.
Arguably the most impactful factor on rewards earned for validating transactions is the total amount of stake in the network.
In other words, the total amount of validators.
Depending on this figure the max annual return rate for a validator can be anywhere between 2 and 20%.
Given a fixed total number of validators, the rewards/penalties predominantly scale with the balance of the validator -- attesting with a higher balance results in larger rewards/penalties whereas attesting with a lower balance results in lower rewards/penalties.
Given a fixed total number of validators, the rewards/penalties predominantly scale with the balance of the validator: attesting with a higher balance results in larger rewards/penalties whereas attesting with a lower balance results in lower rewards/penalties.
>Note however that this scaling mechanism works in a non-obvious way. To understand the precise details of how it works requires understanding a concept called **effective balance**. If you're not yet familiar with this concept, we recommend you read through this [excellent post](https://www.attestant.io/posts/understanding-validator-effective-balance/).
Note however that this scaling mechanism works in a non-obvious way.
To understand the precise details of how it works requires understanding a concept called **effective balance**.
If you're not yet familiar with this concept, we recommend you read through this [excellent post](https://www.attestant.io/posts/understanding-validator-effective-balance/).
### Why do rewards depend on the total number of validators in the network?
@ -200,19 +221,24 @@ Block rewards are calculated using a sliding scale based on the total amount of
In plain english: if the total amount of ETH staked is low, the reward (interest rate) is high, but as the total stake rises, the reward (interest) paid out to each validator starts to fall.
Why a sliding scale? While we won't get into the gory details here, the basic intution is that there needs to be a minimum number of validators (and hence a minimum amount of ETH staked) for the network to function properly. So, to incentivize more validators to join, it's important that the interest rate remains high until this minimum number is reached.
Why a sliding scale?
While we won't get into the gory details here, the basic intuition is that there needs to be a minimum number of validators (and hence a minimum amount of ETH staked) for the network to function properly.
So, to incentivize more validators to join, it's important that the interest rate remains high until this minimum number is reached.
Afterwards, validators are still encouraged to join (the more validators the more decentralized the network), but it's not absolutely essential that they do so (so the interest rate can fall).
### How badly will a validator be penalized for being offline?
It depends. In addition to [the impact of effective balance](https://www.attestant.io/posts/understanding-validator-effective-balance/#the-impact-of-effective-balance-on-validating) there are two important scenarios to be aware of:
It depends.
In addition to [the impact of effective balance](https://www.attestant.io/posts/understanding-validator-effective-balance/#the-impact-of-effective-balance-on-validating), there are two important scenarios to be aware of:
1. Being offline while a supermajority (2/3) of validators is still online leads to relatively small penalties as there are still enough validators online for the chain to finalize. **This is the expected scenario.**
2. Being offline at the same time as more than 1/3 of the total number of validators leads to harsher penalties, since blocks do not finalize anymore. **This scenario is very extreme and unlikely to happen.**
> Note that in the second (unlikely) scenario, validators stand to progressively lose up to 50% (16 ETH) of their stake over 21 days. After 21 days they are ejected out of the validator pool. This ensures that blocks start finalizing again at some point.
Note that in the second (unlikely) scenario, validators stand to progressively lose up to 50% (16 ETH) of their stake over 21 days.
After 21 days they are ejected out of the validator pool.
This ensures that blocks start finalizing again at some point.
### How great does an honest validator's uptime need to be for it to be net profitable?
@ -222,15 +248,21 @@ This means that validators need not go to extreme lengths with backup clients or
### How much will a validator be penalized for acting maliciously?
Again, it depends. Behaving maliciously – for example attesting to invalid or contradicting blocks, will lead to a validator's stake being slashed.
Again, it depends.
Behaving maliciously, e.g. attesting to invalid or contradicting blocks, will lead to a validator's stake being slashed.
The minimum amount that can be slashed is 1 ETH, but **this number increases if other validators are slashed at the same time.**
The idea behind this is to minimize the losses from honest mistakes, but strongly disincentivize coordinated attacks.
The idea behind this is to minimize the losses from honest mistakes, but strongly discouraging coordinated attacks.
### What exactly is slashing?
Slashing has two purposes: (1) to make it prohibitively expensive to attack eth2, and (2) to stop validators from being lazy by checking that they actually perform their duties. Slashing a validator is to destroy (a portion of) the validator’s stake if they act in a provably destructive manner.
Slashing has two purposes:
1. to make it prohibitively expensive to attack eth2, and
2. to stop validators from being lazy by checking that they actually perform their duties.
Slashing a validator is to destroy (a portion of) the validator’s stake if they act in a provably destructive manner.
Validators that are slashed are prevented from participating in the protocol further and are forcibly exited.
@ -239,19 +271,22 @@ Validators that are slashed are prevented from participating in the protocol fur
If the signing key is lost, the validator can no longer propose or attest.
Over time, the validator's balance will decrease as he or she is punished for not participating in the consensus process. When the validator's balance reaches 16 Eth, he or she will be automatically exited from the validator pool.
Over time, the validator's balance will decrease as he or she is punished for not participating in the consensus process.
When the validator's balance reaches 16 ETH, he or she will be automatically exited from the validator pool.
> However, all is not lost. Assuming validators derive their keys using [EIP2334](https://eips.ethereum.org/EIPS/eip-2334) (as per the default onboarding flow)then **validators can always recalculate their signing key from their withdrawal key**.
However, all is not lost.
Assuming validators derive their keys using [EIP2334](https://eips.ethereum.org/EIPS/eip-2334) (as per the default onboarding flow) then **validators can always recalculate their signing key from their withdrawal key**.
The 16 Eth can then be withdrawn -- with the withdrawal key -- after a delay of around a day.
The 16 ETH can then be withdrawn, with the withdrawal key, after a delay of around a day.
> Note that this delay can be longer if many others are exiting or being kicked out at the same time.
Note that this delay can be longer if many others are exiting or being kicked out at the same time.
### What happens if I lose my withdrawal key?
If the withdrawal key is lost, there is no way to obtain access to the funds held by the validator.
As such, it's a good idea to create your keys from mnemonics which act as another backup. This will be the default for validators who join via this site's onboarding process.
As such, it's a good idea to create your keys from mnemonics which act as another backup.
This will be the default for validators who join via this site's onboarding process.
### What happens if my withdrawal key is stolen?
@ -259,9 +294,12 @@ If the withdrawal key is stolen, the thief can transfer the validator’s balanc
If the signing key is not under the thief’s control, the thief cannot exit the validator.
The user with the signing key could attempt to quickly exit the validator and then transfer the funds -- with the withdrawal key -- before the thief.
The user with the signing key could attempt to quickly exit the validator and then transfer the funds — with the withdrawal key — before the thief.
### Why two keys instead of one?
In a nutshell, security. The signing key must be available at all times. As such, it will need to be held online. Since anything online is vulnerable to being hacked, it's not a good idea to use the same key for withdrawals.
In a nutshell, security.
The signing key must be available at all times.
As such, it will need to be held online.
Since anything online is vulnerable to being hacked, it's not a good idea to use the same key for withdrawals.

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

@ -1,6 +1,7 @@
# Set up Graffiti
You can use your node's graffiti flag to include a short text in the blocks that your node creates. You will be able to see it using the block explorer.
You can use your node's graffiti flag to include a short text in the blocks that your node creates.
You will be able to see it using the block explorer.
## Command line

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

@ -10,9 +10,10 @@ The recommended system requirements for running the Nimbus beacon node are:
| Network | Reliable broadband |
!!! 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.
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.
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**.
!!! 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.
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.

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

@ -6,17 +6,21 @@ See [here](./networking.md) for our networking related tips and tricks.
## Keep track of your attestation effectiveness
Attestation effectiveness is a metric that directly affects your validator rewards. In simple terms, an attestation is more valuable the sooner it is put into a block and included in the chain.
Attestation effectiveness is a metric that directly affects your validator rewards.
In simple terms, an attestation is more valuable the sooner it is put into a block and included in the chain.
This interval is called the *inclusion distance* of an attestation. The smaller it is, the more profitable your validator will be. For a deeper understanding we highly recommend reading [Attestant's wonderful blog post](https://www.attestant.io/posts/defining-attestation-effectiveness/#:~:text=Stakers%20looking%20to%20maximize%20their,provide%20clear%20metrics%20for%20performance.) on the matter.
This interval is called the *inclusion distance* of an attestation.
The smaller it is, the more profitable your validator will be.
For a deeper understanding we highly recommend reading [Attestant's wonderful blog post](https://www.attestant.io/posts/defining-attestation-effectiveness/#:~:text=Stakers%20looking%20to%20maximize%20their,provide%20clear%20metrics%20for%20performance.) on the matter.
You can verify your validator's effectiveness on the [beaconcha.in](https://beaconcha.in/) website.
![](https://i.imgur.com/u80Ub2j.png)
Ideally you want to see a value above 80%.
Ideally you want to see a value above 95%.
While attestation effectiveness depends on a variety of factors - attestation network propagation, your network connectivity, and the peers you are connected to - your network connectivity is likely the most important factors you can control to improve this metric. Apart from the tips outlined on this guide, you could also experiment with [subscribing to all subnets](./profits.md#subscribe-to-all-subnets).
While attestation effectiveness depends on a variety of factors - attestation network propagation, your network connectivity, and the peers you are connected to - your network connectivity is likely the most important factors you can control to improve this metric.
Apart from the tips outlined on this guide, you could also experiment with [subscribing to all subnets](./profits.md#subscribe-to-all-subnets).
## Monitor your system's network I/O usage
@ -30,5 +34,5 @@ sudo apt install vnstat
To run it:
*TBC -See [here](https://docs.rocketpool.net/guides/node/performance.html#beaconcha-in-website-using-the-beacon-chain-as-a-metric-source) for more*
*TBC - See [here](https://docs.rocketpool.net/guides/node/performance.html#beaconcha-in-website-using-the-beacon-chain-as-a-metric-source) for more info*

21
docs/the_nimbus_book/src/history.md
View File

@ -1,38 +1,43 @@
# Historical data
!!! note ""
This feature is available from `v23.1.0` onwards
This feature is available from `v23.1.0` onwards.
In order for the network to remain healthy, each node must keep a minimum of 5 months of historical block data.
Nimbus can be configured to either retain or remove historical data past that point using the `--history` option.
!!! note "Default mode"
Nimbus currently retains full history by default - after the `Capella` hard fork, this will change to pruning.
Nimbus currently retains full history by default.
After the `Capella` hard fork, this will change to pruning.
## History modes
The history mode controls how far back Nimbus supports answering historical queries in the [REST API](./rest-api.md) - it does not affect the ability to perform validator duties.
The history mode controls how far back Nimbus supports answering historical queries in the [REST API](./rest-api.md).
It does not affect the ability to perform validator duties.
In `prune` mode, blocks and states past that point are removed from the database continuously and the freed space is reused for more recent data.
!!! info
Although blocks and states are pruned, the database will not shrink in size - instead, the freed space is reused for new data
Although blocks and states are pruned, the database will not shrink in size: instead, the freed space is reused for new data.
In `archive` mode, queries can be as far back as the state that the database was created with - the checkpoint state in the case of trusted node sync or genesis.
In `archive` mode, queries can be as far back as the state that the database was created with — the checkpoint state in the case of trusted node sync or genesis.
## Switching between modes
It is possible to switch between `prune` and `archive` modes.
When switching to `prune` mode, deep history will be removed from the database and the prune point will be updated continuously as usual. As noted above, the database will not shrink in size - to reclaim space, perform a [trusted node sync](./trusted-node-sync.md) on a fresh database instead.
When switching to `prune` mode, deep history will be removed from the database and the prune point will be updated continuously as usual.
As noted above, the database will not shrink in size.
To reclaim space, perform a [trusted node sync](./trusted-node-sync.md) on a fresh database instead.
!!! warning "Backwards compatiblity"
Versions prior to v23.1.0 do not fully support pruned databases - to downgrade, you may need to perform a [trusted node sync](./trusted-node-sync.md).
Versions prior to v23.1.0 do not fully support pruned databases!
To downgrade, you may need to perform a [trusted node sync](./trusted-node-sync.md).
When switching to `archive` mode, the node will start keeping history from the most recent prune point, but will not recreate deep history.
In order to recreate deep history in a pruned node, downloading the [era archive of deep history](./era-store.md) and reindexing the database using [trusted node sync](./trusted-node-sync.md) with the `--reindex` option is necessary - this is a lengthy operation.
In order to recreate deep history in a pruned node, downloading the [era archive of deep history](./era-store.md) and reindexing the database using [trusted node sync](./trusted-node-sync.md) with the `--reindex` option is necessary — this is a lengthy operation.
## Command line

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

@ -1,9 +1,11 @@
# The Nimbus Guide
!!! note ""
Eager to get started? The [quickstart guide](./quick-start.md) is for you.
Eager to get started?
The [quickstart guide](./quick-start.md) is for you.
Coming from a different client? Check out the [migration guide](./migration.md).
Coming from a different client?
Check out the [migration guide](./migration.md).
Nimbus is a client for the Ethereum network that is [lightweight](https://our.status.im/ethereum-is-green/), [secure](./audit.md) and [easy to use](./run-a-validator.md).
@ -24,7 +26,8 @@ An execution client, [nimbus-eth1](https://github.com/status-im/nimbus-eth2), is
## Get in touch
Need help with anything? Join us on [Status](https://join.status.im/nimbus-general) and [Discord](https://discord.gg/9dWwPnG).
Need help with anything?
Join us on [Status](https://join.status.im/nimbus-general) and [Discord](https://discord.gg/9dWwPnG).
## Donate

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

@ -8,9 +8,11 @@ Check that your machine matches the [minimal system requirements](./hardware.md)
## Time
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.
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 changed 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).
=== "Linux"

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

@ -2,7 +2,7 @@
Once your validator has been activated, you can set up [validator monitoring](./validator-monitor.md) together with a [dashboard](./metrics-pretty-pictures.md) to keep track of its performance.
Another way of keeping track is using an online service such as beaconcha.in - [Mainnet](https://beaconcha.in/) or [Prater](https://prater.beaconcha.in).
Another way of keeping track is using an online service such as beaconcha.in: [Mainnet](https://beaconcha.in/) or [Prater](https://prater.beaconcha.in).
Both online services and dashboards allow setting up alerts for when the validator is offline.
@ -10,7 +10,8 @@ Both online services and dashboards allow setting up alerts for when the validat
### Make sure your validator is attached
On startup, you should see a log message that reads `Local validator attached`. This has a `pubkey` field which should the public key of your validator.
On startup, you should see a log message that reads `Local validator attached`.
This has a `pubkey` field which should be the public key of your validator.
### Keep track of your syncing progress
@ -31,10 +32,10 @@ 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
- `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
- `sync` tells you if your client is synced and can perform duties, or how long it will take to get there
- `/opt` means that the node is [optimistically synced](./optimistic-sync.md) - it is waiting for the execution client to finish syncing
- `/opt` means that the node is [optimistically synced](./optimistic-sync.md): it is waiting for the execution client to finish syncing
- in the case of [trusted node sync](./trusted-node-sync.md) it may also show `backfill` in which case duties are being performed but more bandwidth than usual is being used to download historical blocks
- `head` tells you the most recent block you've synced to so far (`5d59aba3` is the first part of the block hash, `4021234` is the slot number)
- `finalized` tells you the most recent finalized epoch you've synced to so far (`125661` is the epoch, `82616f78` is the checkpoint hash)

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

@ -1,6 +1,8 @@
# Upgrade / downgrade
Make sure you stay on the lookout for any critical updates to Nimbus. The 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/).
Make sure you stay on the lookout for any critical updates to Nimbus.
The 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/).
!!! note
If your beacon node is already running, you'll need to restart it for the changes to take effect.
@ -46,7 +48,7 @@ To update to the latest version, either download the binary or compile the beaco
```
!!! tip
If you want to minimise downtime, you can build Nimbus while the node is running!
If you want to minimize downtime, you can build Nimbus while the node is running!
Complete the upgrade by restarting the node!
@ -54,16 +56,16 @@ Complete the upgrade by restarting the node!
As of `v1.4.0`, releases are marked with the following tags:
`low-urgency`: update at your own convenience, sometime within our normal update cycle of two weeks
- `low-urgency`: update at your own convenience, sometime within our normal update cycle of two weeks
`medium-urgency`: may contain an important stability fix, it is better to update sooner rather than later
- `medium-urgency`: may contain an important stability fix, it is better to update sooner rather than later
`high-urgency`: update as soon as you can, this is a critical update required for Nimbus to function correctly
- `high-urgency`: update as soon as you can, this is a critical update required for Nimbus to function correctly
## Install a specific version
*Occassionally you may need to either upgrade or downgrade to a specific version of Nimbus.*
Occasionally, you may need to either upgrade or downgrade to a specific version of Nimbus.
Nimbus can safely be downgraded to any version targeting the current hard fork of the chain, unless otherwise noted among the release notes.

13
docs/the_nimbus_book/src/keymanager-api.md
View File

@ -6,23 +6,28 @@ As of `v1.7.0` it supports `web3signer` keystores.
## Configuration
By default, we disable the Keymanager API. To enable it, start the beacon node with the `--keymanager` option enabled:
By default, we disable the Keymanager API.
To enable it, start the beacon node with the `--keymanager` option enabled:
```
./run-prater-beacon-node.sh --keymanager
```
Once the node is running, you'll be able to access the API from [http://localhost:5052/](http://localhost:5052/)
Once the node is running, you'll be able to access the API from [http://localhost:5052/](http://localhost:5052/).
### Authorization: Bearer scheme
All requests must be authorized through the `Authorization: Bearer` scheme with a token matching the contents of a file provided at the start of the node through the `--keymanager-token-file` parameter.
### Enabling connections from outside machines
By default, only connections from the same machine are entertained. If you wish to change this you can configure the port and listening address with the `--keymanager-port` and `--keymanager-address` options respectively.
By default, only connections from the same machine are entertained.
If you wish to change this you can configure the port and listening address with the `--keymanager-port` and `--keymanager-address` options respectively.
!!! warning
The Keymanager API port should only be exposed through a secure channel (e.g. HTTPS, an SSH tunnel, a VPN, etc.)
## Specification
The specification is documented [here](https://ethereum.github.io/keymanager-APIs/). The README is also extremely useful and is documented [here](https://github.com/ethereum/keymanager-APIs/).
The specification is documented [here](https://ethereum.github.io/keymanager-APIs/).
The README is also extremely useful and is documented [here](https://github.com/ethereum/keymanager-APIs/).

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

@ -3,7 +3,7 @@
!!! 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.
Having followed the [deposit guide](./deposit.md), 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:
@ -28,10 +28,10 @@ NOT 2022-07-19 17:36:37.578+02:00 Keystore imported
!!! note ""
`NOT` is short for `NOTICE` and not not :)
After importing keys, it's time to [restart](./connect-eth2.md) the node and check that the keys have been picked up by the beacon node.
After importing keys, it's time to [restart the node](./connect-eth2.md) and check that the keys have been picked up by the beacon node.
!!! info "All the keys"
You can read more about the different types of keys [here](https://blog.ethereum.org/2020/05/21/keys/) - the `deposit import` command will import the **signing key** only.
You can read more about the different types of keys [here](https://blog.ethereum.org/2020/05/21/keys/) — the `deposit import` command will import the **signing key** only.
## Command line
@ -53,17 +53,20 @@ If your `validator_keys` folder is stored elsewhere, you can pass its location t
Replacing `/path/to/keys` with the full pathname of where the `validator_keys` directory is found.
## Optimised import for a large number of validators
## Optimized import for a large number of validators
If you plan to use a large number of validators (e.g. more than 100) on a single beacon node or a validator client, you might benefit from running the `deposits import` command with the option `--method=single-salt`. This will force Nimbus to use the same password and random salt value when encrypting all of the imported keystores which will later enable it to load the large number of validator keys almost instantly. The theoretical downside of using this approach is that it makes the brute-force cracking of all imported keystores computationally equivalent to cracking just one of them. Nevertheless, the security parameters used by Ethereum are such that cracking even a single keystore is considered computationally infeasible with current hardware.
If you plan to use a large number of validators (e.g. more than 100) on a single beacon node or a validator client, you might benefit from running the `deposits import` command with the option `--method=single-salt`.
This will force Nimbus to use the same password and random salt value when encrypting all of the imported keystores which will later enable it to load the large number of validator keys almost instantly.
The theoretical downside of using this approach is that it makes the brute-force cracking of all imported keystores computationally equivalent to cracking just one of them.
Nevertheless, the security parameters used by Ethereum are such that cracking even a single keystore is considered computationally infeasible with current hardware.
## Troubleshooting
If you come across an error, make sure that:
* 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`
* Permissions for the data directory are wrong
* 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`.
* Permissions for the data directory are wrong.
* See [folder permissions](./data-dir.md#permissions) for how to fix this.

7
docs/the_nimbus_book/src/light-client-data.md
View File

@ -1,6 +1,8 @@
# Light client data
Nimbus is configured by default to serve data that allows light clients to stay in sync with the Ethereum network. Light client data is imported incrementally and does not affect validator performance. Information about the light client sync protocol can be found in the [Ethereum consensus specs](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.3/specs/altair/light-client/sync-protocol.md).
Nimbus is configured by default to serve data that allows light clients to stay in sync with the Ethereum network.
Light client data is imported incrementally and does not affect validator performance.
Information about the light client sync protocol can be found in the [Ethereum consensus specs](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.3/specs/altair/light-client/sync-protocol.md).
!!! note
Nimbus also implements a [standalone light client](./el-light-client.md) that may be used to sync an execution layer (EL) client.
@ -16,4 +18,5 @@ The following [configuration options](./options.md) adjust the import and servin
| <nobr>`--light-client-data-max-periods`</nobr> | <ul><li>Controls the maximum number of sync committee periods to retain light client data</li><li>When unspecified (default), light client data is never pruned</li></ul> |
!!! warning
Setting `--light-client-data-import-mode` to `full` or `on-demand` imports historic light client data which is computationally expensive. While importing historic light client data, validator duties may be missed.
Setting `--light-client-data-import-mode` to `full` or `on-demand` imports historic light client data which is computationally expensive.
While importing historic light client data, validator duties may be missed.

21
docs/the_nimbus_book/src/log-rotate.md
View File

@ -1,10 +1,14 @@
# Set up log rotation
Nimbus logs are written to `stdout`, and can be redirected to a file. Writing to a file for a long-running process may lead to difficulties when the file grows large. This is typically solved with a *log rotator*. A log rotator is responsible for switching the written-to file, as well as compressing and removing old logs.
Nimbus logs are written to `stdout`, and can be redirected to a file.
Writing to a file for a long-running process may lead to difficulties when the file grows large.
This is typically solved with a *log rotator*.
A log rotator is responsible for switching the written-to file, as well as compressing and removing old logs.
## Using `logrotate`
[logrotate](https://github.com/logrotate/logrotate) provides log rotation and compression. The corresponding package will install its Cron hooks (or Systemd timer) -- all you have to do is add a configuration file for Nimbus in "/etc/logrotate.d/nimbus-eth2":
[logrotate](https://github.com/logrotate/logrotate) provides log rotation and compression.
The corresponding package will install its Cron hooks (or Systemd timer) -- all you have to do is add a configuration file for Nimbus in `/etc/logrotate.d/nimbus-eth2`:
```text
/var/log/nimbus-eth2/*.log {
@ -14,11 +18,13 @@ Nimbus logs are written to `stdout`, and can be redirected to a file. Writing to
}
```
The above assumes you've configured Nimbus to write its logs to "/var/log/nimbus-eth2/" (usually by redirecting `stdout` and `stderr` from your init script).
The above assumes you've configured Nimbus to write its logs to `/var/log/nimbus-eth2/` (usually by redirecting `stdout` and `stderr` from your init script).
"copytruncate" is required because, when it comes to moving the log file, `logrotate`'s default behaviour requires application support for re-opening that log file at runtime (something which is currently lacking). So, instead of a move, we tell `logrotate` to do a copy and a truncation of the existing file. A few log lines may be lost in the process.
`copytruncate` is required because, when it comes to moving the log file, `logrotate`'s default behaviour requires application support for re-opening that log file at runtime (something which is currently lacking).
So, instead of a move, we tell `logrotate` to do a copy and a truncation of the existing file.
A few log lines may be lost in the process.
You can control rotation frequency and the maximum number of log files kept by using the global configuration file - "/etc/logrotate.conf":
You can control rotation frequency and the maximum number of log files kept by using the global configuration file, `/etc/logrotate.conf`:
```text
# rotate daily
@ -37,7 +43,10 @@ In particular, when `systemd` and its accompanying `journald` log daemon are use
### Compression
`rotatelogs` works by reading `stdin` and redirecting it to a file based on a name pattern. Whenever the log is about to be rotated, the application invokes a shell script with the old and new log files. Our aim is to compress the log file to save space. The [Nimbus-eth2 repo](https://github.com/status-im/nimbus-eth2/tree/unstable/scripts/rotatelogs-compress.sh) provides a helper script that does this:
`rotatelogs` works by reading `stdin` and redirecting it to a file based on a name pattern.
Whenever the log is about to be rotated, the application invokes a shell script with the old and new log files.
Our aim is to compress the log file to save space.
The [Nimbus-eth2 repo](https://github.com/status-im/nimbus-eth2/tree/unstable/scripts/rotatelogs-compress.sh) provides a helper script that does this:
```bash
# Create a rotation script for rotatelogs

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

@ -1,12 +1,10 @@
# Logging
!!! warning
The logging options outlined here are based on a preview feature, and are subject to change
Nimbus offers several options for logging - by default, logs are written to stdout using the [chronicles](https://github.com/status-im/nim-chronicles#introduction) `textlines` format which is convenient to read and can be used with tooling for [heroku/logfmt](https://brandur.org/logfmt).
Nimbus offers several options for logging.
By default, logs are written to stdout using the [chronicles](https://github.com/status-im/nim-chronicles#introduction) `textlines` format which is convenient to read and can be used with tooling for [heroku/logfmt](https://brandur.org/logfmt).
!!! tip
`NOT` at the beginning of a log line means 'NOTICE`
`NOT` at the beginning of a log line means `NOTICE`.
## Change log level
@ -35,7 +33,8 @@ NONE
## Change logging style
Nimbus supports three log formats: `colors`, `nocolors` and `json`. In `auto` mode, logs will be printed using either `colors` or `nocolors`.
Nimbus supports three log formats: `colors`, `nocolors` and `json`.
In `auto` mode, logs will be printed using either `colors` or `nocolors`.
You can choose a log format with the `--log-format` option, which also understands `auto` and `none`:
@ -53,5 +52,6 @@ To send logs to a file, you can redirect the stdout logs:
./run-mainnet-beacon-node.sh --log-format=json > filename.jsonl
```
We recommend keeping an eye on the growth of this file with a [log rotator](./log-rotate.md). Logs are written in the "JSON Lines" format - one `json` entry per line.
We recommend keeping an eye on the growth of this file with a [log rotator](./log-rotate.md).
Logs are written in the "JSON Lines" format - one `json` entry per line.

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

@ -1,6 +1,7 @@
# 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.
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.
## Export validators

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

@ -1,21 +1,28 @@
# Recover lost keys and generate new ones
When generating your [first deposit](./deposit.md) you will be asked to save a mnemonic in a safe location.
When generating your [first deposit](./deposit.md), you will be asked to save a mnemonic in a safe location.
This mnemonic can be used to recover lost keys and generate new ones.
Every time you generate a keystore from your mnemomic, that keystore is assigned an index. The first keystore you generate has index 0, the second index 1, etc. You can recover any key using your mnemonic and that key's index. For more on how keys are derived, see this [excellent post](https://blog.ethereum.org/2020/05/21/keys/).
Every time you generate a keystore from your mnemonic, that keystore is assigned an index.
The first keystore you generate has index 0, the second index 1, etc.
You can recover any key using your mnemonic and that key's index.
For more on how keys are derived, see this [excellent post](https://blog.ethereum.org/2020/05/21/keys/).
To stay consistent with the rest of the book, we'll take you though how to do this using the [deposit-cli's](https://github.com/ethereum/eth2.0-deposit-cli) [binary executable](https://github.com/ethereum/eth2.0-deposit-cli/releases).
Specifically, we'll be using the `existing-mnemonic` command. Here's a description of the command from the deposit-cli's [README](https://github.com/ethereum/eth2.0-deposit-cli#step-2-create-keys-and-deposit_data-json):
Specifically, we'll be using the `existing-mnemonic` command.
Here's a description of the command from the deposit-cli's [README](https://github.com/ethereum/eth2.0-deposit-cli#step-2-create-keys-and-deposit_data-json):
> This command is used to re-generate or derive new keys from your existing mnemonic. Use this command, if (i) you have already generated keys with this CLI before, (ii) you want to reuse your mnemonic that you know is secure that you generated elsewhere (reusing your eth1 mnemonic .etc), or (iii) you lost your keystores and need to recover your keys.
> This command is used to re-generate or derive new keys from your existing mnemonic.
Use this command, if (i) you have already generated keys with this CLI before, (ii) you want to reuse your mnemonic that you know is secure that you generated elsewhere (reusing your eth1 mnemonic .etc), or (iii) you lost your keystores and need to recover your keys.
## Recover existing key
!!! warning
Recovering validator keys from a mnemonic should only be used as a last resort. Exposing your mnemonic to a computer at any time puts it at risk of being compromised. Your mnemonic is not encrypted and if leaked, can be used to steal your funds.
Recovering validator keys from a mnemonic should only be used as a last resort.
Exposing your mnemonic to a computer at any time puts it at risk of being compromised.
Your mnemonic is not encrypted and if leaked, can be used to steal your funds.
!!! note
The commands below assume you are trying to recover the first key you created, hence `--validator_start_index` has been set to `0`.
@ -42,12 +49,13 @@ You'll be prompted to enter your mnemonic, and a new password for your keystore.
Check that the `validator_keys` directory contains your keystore.
Copy the `validator_keys` directory to `nimbus-eth2` and then follow the instructions [here](./keys.md). Your key will be added to your node on next restart.
Copy the `validator_keys` directory to `nimbus-eth2` and then follow the instructions [here](./keys.md).
Your key will be added to your node on next restart.
## Generate another key
!!! warning
If you wish to use your new key with a separate client instance, make sure not to include your first key in the second setup - doing so will lead to it being slashed!
If you wish to use your new key with a separate client instance, make sure not to include your first key in the second setup — doing so will lead to it being slashed!
!!! note
The commands below assume you already have one key and wish to generate a second, hence `--validator_start_index` has been set to `1` (as `0` would be the original key)
@ -70,10 +78,11 @@ Run the following command from the directory which contains the `deposit` execut
--chain prater
```
You'll be prompted to enter your mnemonic, and a new password for your keystore.
You'll be prompted to enter your mnemonic and a new password for your keystore.
Check that the `validator_keys` directory contains an extra keystore.
Copy the `validator_keys` directory to `nimbus-eth2`.
Make sure you've made a [deposit](./deposit.md) for your new keystore, and then follow the instructions [here](./keys.md). Your key will be added to your node on next restart.
Make sure you've made a [deposit](./deposit.md) for your new keystore, and then follow the instructions [here](./keys.md).
Your key will be added to your node on the next restart.

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

@ -1,23 +1,25 @@
# Networking
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.
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.
In addition to making outgoing connections, the beacon node node works best when others can connect to it - this speeds up the process of finding good peers.
In addition to making outgoing connections, the beacon node node works best when others can connect to it — this speeds up the process of finding good peers.
To allow incoming connections, the node must be reachable via a public IP address. It must also be aware of this address, so that it can advertise it to its peers.
To allow incoming connections, the node must be reachable via a public IP address.
It must also be aware of this address, so that it can advertise it to its peers.
## UPnP
By default, Nimbus uses [UPnP](https://en.wikipedia.org/wiki/Universal_Plug_and_Play) to set up port forwarding and detect your external IP address. If you do not have UPnP enabled, you may need to pass additional command-line options to the node, as explained in subsequent sections.
By default, Nimbus uses [UPnP](https://en.wikipedia.org/wiki/Universal_Plug_and_Play) to set up port forwarding and detect your external IP address.
If you do not have UPnP enabled, you may need to pass additional command-line options to the node, as explained in the subsequent sections.
Enabling UPnP is usually as simple as checking a box in your router's configuration. Unless it's a FRITZ!Box router, that is.
With this brand, you will also need to edit individual connections - in "Home Network" -> "Network" -> edit icon -> "Permit independent port sharing for this device". You might also want to enable "Always assign this network device the same IPv4 address", in case the setting is associated with IPs instead of MACs.
Enabling UPnP is usually as simple as checking a box in your router's configuration.
## Monitor your Peer count
!!! note
As of `v1.7.0`, peer scoring has been fine-tuned. As such `--max-peers` should not be set below 70. Note that Lowering `max-peers` does not significantly improve bandwidth usage, but does increase the risk of missed attestations.
As of `v1.7.0`, peer scoring has been fine-tuned.
As such `--max-peers` should not be set below 70. Note that Lowering `max-peers` does not significantly improve bandwidth usage, but does increase the risk of missed attestations.
If your Peer count is low (less than `15`) and/or you repeatedly see either of the following warnings:
@ -49,20 +51,23 @@ In the output, look for a line that looks like:
libp2p_open_streams{type="ChronosStream",dir="in"}
```
If there are no `dir=in` ChronosStreams , incoming connections are not working.
If there are no `dir=in` ChronosStreams, incoming connections are not working.
> **N.B** you need to run the client with the `--metrics` option enabled in order for this to work
!!! note
You need to run the client with the `--metrics` option enabled in order for this to work
## Set an explicit external IP
If you have a static public IP address, use the `--nat:extip:$EXT_IP_ADDRESS` option to pass it to the client, where `$EXT_IP_ADDRESS` is your public IP (see [here](./networking.md#determine-your-public-ip-address) for how to determine your public IP address). For example, if your public IP address is `1.2.3.4`, you'd run:
If you have a static public IP address, use the `--nat:extip:$EXT_IP_ADDRESS` option to pass it to the client, where `$EXT_IP_ADDRESS` is your public IP.
See [here](./networking.md#determine-your-public-ip-address) for how to determine your public IP address.
!!! note
If you have a dynamic IP, you can use `extip` the initial setting, but should also enable `--enr-auto-update` to keep it up-to-date.
## Set ENR auto update
The `--enr-auto-update` feature keeps your external IP address up to date based on information received from other peers on the network. This option is useful with ISPs that assign IP addresses dynamically.
The `--enr-auto-update` feature keeps your external IP address up to date based on information received from other peers on the network.
This option is useful with ISPs that assign IP addresses dynamically.
In practice this means relaunching the beacon node with `--enr-auto-update:true` (pass it as an option in the command line).
@ -77,19 +82,19 @@ While the specific steps required vary based on your router, they can be summari
1. Determine your [public IP address](./networking.md#determine-your-public-ip-address)
2. Determine your [private IP address](./networking.md#determine-your-private-ip-address)
3. Browse to the management website for your home router ([http://192.168.1.1](http://192.168.1.1) for most routers, [https://192.168.178.1](https://192.168.178.1) for FRITZ!Box)
3. Browse to the management website for your home router ([http://192.168.1.1](http://192.168.1.1) for most routers)
4. Log in as admin
5. Find the section to configure port forwarding
6. Configure a port forwarding rule with the following values:
- External port: `9000`
- Internal port: `9000`
- Protocol: `TCP`
- IP Address: Private IP address of the computer running Nimbus
- External port: `9000`
- Internal port: `9000`
- Protocol: `TCP`
- IP Address: Private IP address of the computer running Nimbus
7. Configure a second port forwarding rule with the following values:
- External port: `9000`
- Internal port: `9000`
- Protocol: `UDP`
- IP Address: Private IP address of the computer running Nimbus
- External port: `9000`
- Internal port: `9000`
- Protocol: `UDP`
- IP Address: Private IP address of the computer running Nimbus
### Determine your public IP address
@ -124,21 +129,25 @@ Use [this tool](https://www.yougetsignal.com/tools/open-ports/) to check your ex
## Reading the logs
`No peers for topic, skipping publish...`
- `No peers for topic, skipping publish...`
This is printed when the client lacks quality peers to publish attestations to - this is the most important indication that the node is having trouble keeping up. If you see this, you are missing attestations.
This is printed when the client lacks quality peers to publish attestations to - this is the most important indication that the node is having trouble keeping up.
If you see this, you are missing attestations.
`Peer count low, no new peers discovered...`
- `Peer count low, no new peers discovered...`
This is a sign that you may be missing attestations.
This is a sign that you may be missing attestations.
`No external IP provided for the ENR...`
- `No external IP provided for the ENR...`
This message basically means that the software did not manage to find a public IP address (by either looking at your routed interface IP address, and/or by attempting to get it from your gateway through UPnP or NAT-PMP).
This message basically means that the software did not manage to find a public IP address (by either looking at your routed interface IP address, and/or by attempting to get it from your gateway through UPnP or NAT-PMP).
`Discovered new external address but ENR auto update is off...`
- `Discovered new external address but ENR auto update is off...`
It's possible that your ISP has changed your IP address without you knowing. The first thing to do it to try relaunching the beacon node with with `--enr-auto-update:true` (pass it as an option in the command line).
It's possible that your ISP has changed your IP address without you knowing.
The first thing to do it to try relaunching the beacon node with with `--enr-auto-update:true` (pass it as an option in the command line).
If this doesn't fix the problem, the next thing to do is to check your external (public) IP address and detect open ports on your connection - you can use [this site](https://www.yougetsignal.com/tools/open-ports/ ). Note that Nimbus `TCP` and `UDP` ports are both set to `9000` by default. See above for how to set up port forwarding.
If this doesn't fix the problem, the next thing to do is to check your external (public) IP address and detect open ports on your connection - you can use [this site](https://www.yougetsignal.com/tools/open-ports/ ).
Note that Nimbus `TCP` and `UDP` ports are both set to `9000` by default.
See above for how to set up port forwarding.

15
docs/the_nimbus_book/src/optimistic-sync.md
View File

@ -1,20 +1,23 @@
# Optimistic sync
Optimistic sync is the process of syncing an execution and consensus client concurrently, without having the consensus client wait for the execution client. During optimistic sync, the consensus client quickly syncs up to the latest conesensus but delays verifying block execution payloads - it continuously informs the execution client of the latest consensus head, allowing the execution client to perform a snapshot sync directly to the latest state.
Optimistic sync is the process of syncing an execution and consensus client concurrently, without having the consensus client wait for the execution client.
During optimistic sync, the consensus client quickly syncs up to the latest consensus but delays verifying block execution payloads: it continuously informs the execution client of the latest consensus head, allowing the execution client to perform a snapshot sync directly to the latest state.
Once the execution client has caught up, the consensus and execution clients work in lock-step each validating the block.
Both execution and consensus clients must be fully synced to perform validation duties - while optimistically synced, validator duties (attestation, sync committee and block production work) are skipped.
Both execution and consensus clients must be fully synced to perform validation duties: while optimistically synced, validator duties (attestation, sync committee and block production work) are skipped.
!!! info "Running without execution client"
Nimbus continues to sync optimistically when the exection client is not available thanks to its built-in execution payload verifier.
Nimbus continues to sync optimistically when the execution client is not available thanks to its built-in execution payload verifier.
This feature is available from `v23.1.0` onwards. A preview of the feature could be enabled with `--optimstic` in earlier versions - this flag is no longer needed.
This feature is available from `v23.1.0` onwards.
A preview of the feature could be enabled with `--optimistic` in earlier versions - this flag is no longer needed.
## Identifying optimistic sync
An optimistically synced node can be identified by examining the "Slot start" log message - when optimistically synced, the `sync` key will have a `/opt` suffix, indicating that it's waiting for the execution client to catch up:
An optimistically synced node can be identified by examining the "Slot start" log message.
When optimistically synced, the `sync` key will have a `/opt` suffix, indicating that it's waiting for the execution client to catch up:
```
INF 2022-10-26 18:57:35.000+02:00 Slot start topics="beacnde" slot=4998286 epoch=156196 sync=synced/opt peers=29 head=f21d399e:4998285 finalized=156194:91e2ebaf delay=467us953ns
INF 2022-10-26 18:57:35.000+02:00 Slot start topics="beacnde" slot=4998286 epoch=156196 sync=synced/opt peers=29 head=f21d399e:4998285 finalized=156194:91e2ebaf delay=467us953ns
```

19
docs/the_nimbus_book/src/options.md
View File

@ -2,7 +2,8 @@
Command line options allow you to customize the way your beacon node operates.
You pass options to the beacon node by adding them to the command line. For example, if you want to launch Nimbus on mainnet with different base ports than the default `9000/udp` and `9000/tcp`, say `9100/udp` and `9100/tcp`, run:
You pass options to the beacon node by adding them to the command line.
For example, if you want to launch Nimbus on mainnet with different base ports than the default `9000/udp` and `9000/tcp`, say `9100/udp` and `9100/tcp`, run:
```sh
./run-mainnet-beacon-node.sh --tcp-port=9100 --udp-port=9100
@ -10,7 +11,7 @@ You pass options to the beacon node by adding them to the command line. For exam
## Available options
To see the full list of command line options availabe to you, with descriptions, run:
To see the full list of command line options available to you, with descriptions, run:
```sh
build/nimbus_beacon_node --help
@ -127,13 +128,17 @@ The following options are available:
## Configuration files
All command line options can also be provided in a [TOML](https://toml.io/en/)
config file specified through the `--config-file` flag. Within the config file,
you need to use the long names of all options. Please note that certain options
config file specified through the `--config-file` flag.
Within the config file, you need to use the long names of all options.
Please note that certain options
such as `web3-url`, `bootstrap-node`, `direct-peer`, and `validator-monitor-pubkey`
can be supplied more than once on the command line - in the TOML file, you need
to supply them as arrays. There are also some minor differences in the parsing
can be supplied more than once on the command line: in the TOML file, you need
to supply them as arrays.
There are also some minor differences in the parsing
of certain option values in the TOML files in order to conform more closely to
existing TOML standards. For example, you can freely use keywords such as `on`,
existing TOML standards.
For example, you can freely use keywords such as `on`,
`off`, `yes` and `no` on the command-line as synonyms for the canonical values
`true` and `false` which are mandatory to use in TOML. Options affecting Nimbus
sub-commands should appear in a section of the file matching the sub-command name.

3
docs/the_nimbus_book/src/pi-guide.md
View File

@ -23,7 +23,8 @@ As such, we try our best to explain things from first-principles.
- 200GB SSD (2TB recommended if also running execution client)
!!! note
You will need an SSD to run the Nimbus: mechanical hard drives are typically too slow to run an Ethereum node. You have two options:
You will need an SSD to run the Nimbus: mechanical hard drives are typically too slow to run an Ethereum node.
You have two options:
1. Use an USB portable SSD disk such as the Samsung T5 Portable SSD.
2. Use an USB 3.0 External Hard Drive Case with a SSD Disk.

20
docs/the_nimbus_book/src/prater.md
View File

@ -1,19 +1,23 @@
# Prater testnet
`prater`, also known as `goerli`, is the current long-running merge testnet. It provides an opportunity to verify your setup works as expected through the proof-of-stake transition and in a post-merge context as well as to safely practise node operations such as adding and removing validators, migrating between clients, and performing upgrades and backups. If you come across any issues, please [report them here](https://github.com/status-im/nimbus-eth2/issues).
`prater`, also known as `goerli`, is the current long-running merge testnet.
It provides an opportunity to verify your setup works as expected through the proof-of-stake transition and in a post-merge context as well as to safely practice node operations such as adding and removing validators, migrating between clients, and performing upgrades and backups.
If you come across any issues, please [report them here](https://github.com/status-im/nimbus-eth2/issues).
!!! note
Post-merge, node runners will need to run both a consensus and execution layer client.
# General Preparation
## General Preparation
1. Generate the JWT secret with `openssl rand -hex 32 | tr -d "\n" > "/opt/jwtsecret"`. This file needs to be passed to both the execution client and the consensus client.
2. Choose an Ethereum address to receive transaction fees. This ETH will be immediately available, not part of the staking contract.
2. Choose an Ethereum address to receive transaction fees.
This ETH will be immediately available, not part of the staking contract.
3. Download the [latest release](./binaries.md) and install it by unpacking the archive.
4. Choose one of Nethermind, Besu, Erigon, or Geth as an execution client, using one of the [compatible versions](https://blog.ethereum.org/2022/07/27/goerli-prater-merge-announcement/#execution-layer). Download, install, and [run it](https://notes.ethereum.org/@launchpad/goerli#Run-an-Execution-Layer-Client).
4. Choose one of Nethermind, Besu, Erigon, or Geth as an execution client, using one of the [compatible versions](https://blog.ethereum.org/2022/07/27/goerli-prater-merge-announcement/#execution-layer).
Download, install, and [run it](https://notes.ethereum.org/@launchpad/goerli#Run-an-Execution-Layer-Client).
For example, Nethermind on Goerli can run via:
```sh
@ -49,7 +53,7 @@ build/install/besu/bin/besu \
--engine-jwt-secret=/opt/jwtsecret
```
# Sync the beacon node and execution client
## Sync the beacon node and execution client
5. [Start syncing](./start-syncing.md) the node consisting of Nimbus and chosen execution client, for example by running:
```sh
@ -64,9 +68,11 @@ nimbus-eth2/build/nimbus_beacon_node \
One might consider here to [set up a systemd service](./beacon-node-systemd.md) to ensure this runs automatically, including after restarts.
# Begin validating
## Begin validating
6. Once this Goerli/Prater node is [completely synced](./keep-an-eye.md#keep-track-of-your-syncing-progress), use the [Prater launchpad](https://prater.launchpad.ethereum.org/en/) to obtain Goerli/Prater validators with [Goerli ETH](./goerli-eth.md). It might require some time before these enter and are activated on the beacon chain. If one does this before the node which will attest and propose using those validators has synced, one might miss attestations and block proposals.
6. Once this Goerli/Prater node is [completely synced](./keep-an-eye.md#keep-track-of-your-syncing-progress), use the [Prater launchpad](https://prater.launchpad.ethereum.org/en/) to obtain Goerli/Prater validators with [Goerli ETH](./goerli-eth.md).
It might require some time before these enter and are activated on the beacon chain.
If one does this before the node which will attest and propose using those validators has synced, one might miss attestations and block proposals.
7. [Import the validator keys](./keys.md) you receive into Nimbus.

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

@ -4,11 +4,14 @@
Please check that you are running the latest stable [Nimbus software release](https://github.com/status-im/nimbus-eth2/releases).
> In order to stay on top of new releases you should subscribe to [our mailing list](https://subscribe.nimbus.team/).
!!! tip
In order to stay on top of new releases you should subscribe to [our mailing list](https://subscribe.nimbus.team/).
## More than 15 peers
Please check that your node has at least 15 peers. To monitor your peer count, pay attention to the [`Slot start` messages in your logs](keep-an-eye.md#keep-track-of-your-syncing-progress). See the [networking page](networking.md) for more tips.
Please check that your node has at least 15 peers.
To monitor your peer count, pay attention to the [`Slot start` messages in your logs](keep-an-eye.md#keep-track-of-your-syncing-progress).
See the [networking page](networking.md) for more tips.
## Validator attached
@ -16,7 +19,8 @@ Please check that your [validator is attached](keep-an-eye.md#make-sure-your-val
## Systemd
We recommend [setting up a systemd service](beacon-node-systemd.md) with an autorestart on boot (should you experience an unexpected power outage, this will ensure your validator restarts correctly).
We recommend [setting up a systemd service](beacon-node-systemd.md) with an autorestart on boot.
Should you experience an unexpected power outage, this will ensure your validator restarts correctly.
Systemd will also ensure your validator keeps running when you exit your ssh session (`Ctrl-C`) and/or switch off your laptop.

19
docs/the_nimbus_book/src/profits.md
View File

@ -1,8 +1,9 @@
# Optimise for profitability
# Optimize for profitability
Key insights:
- Profitability depends heavily on the network and peer quality
- While block proposals are more lucrative than attestations, they are much rarer
- Profitability depends heavily on the network and peer quality.
- While block proposals are more lucrative than attestations, they are much rarer.
@ -31,7 +32,8 @@ Specifically, have a look at `nextActionWait` time.
If you're concerned about missing an attestation or proposal, wait until `nextActionWait` is greater than 4 minutes or so before restarting Nimbus.
You can also use the `nimbus-eth2` [API](./api.md). For example, to check if your validator has a next Proposal slot assigned, run:
You can also use the `nimbus-eth2` [API](./api.md).
For example, to check if your validator has a next Proposal slot assigned, run:
```
curl -d '{"jsonrpc":"2.0","method":"get_v1_validator_duties_proposer","params":[${HEAD_EPOCH_NUMBER}],"id":1}' -H 'Content-Type: application/json' localhost:9190 -s | jq ".result[]" | grep ${PATTERN_WHICH_MATCHES_VALIDATOR_PUBLIC_KEYS}
@ -39,11 +41,14 @@ curl -d '{"jsonrpc":"2.0","method":"get_v1_validator_duties_proposer","params":[
## Subscribe to all subnets
Launching the beacon node with the `--subscribe-all-subnets` option increases bandwidth and cpu usage, but helps the network and makes the block production algorithm perform slightly better.
To elaborate a little, without this option enabled Nimbus only listens to a subset of the attestation traffic - in particular, Nimbus doesn't listen to all unaggregated traffic but instead relies on peers to aggregate attestations on the subnets it doesn't subscribe to.
To elaborate a little, without this option enabled Nimbus only listens to a subset of the attestation traffic: in particular, Nimbus doesn't listen to all unaggregated traffic but instead relies on peers to aggregate attestations on the subnets it doesn't subscribe to.
With this option enabled, Nimbus listens to all unaggregated channels (subscribes to all subnets). Practically speaking, this means that when producing a block, Nimbus can "top up" the aggregates that other peers have made with it's own unaggregated attestations. This can lead to better packing in some cases, which can lead to slightly greater rewards.
With this option enabled, Nimbus listens to all unaggregated channels (subscribes to all subnets).
Practically speaking, this means that when producing a block, Nimbus can "top up" the aggregates that other peers have made with it's own unaggregated attestations.
This can lead to better packing in some cases, which can lead to slightly greater rewards.
## Useful resources
@ -51,5 +56,3 @@ With this option enabled, Nimbus listens to all unaggregated channels (subscribe
- [Validator rewards in practice](https://pintail.xyz/posts/validator-rewards-in-practice/)

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

@ -78,7 +78,8 @@ Once the beacon node starts, you'll see it logging information to the console, l
INF 2022-07-19 15:42:58.145+02:00 Launching beacon node topics="beacnde" version=v22.10.1-97a1cdc4-stateofus ...
```
Congratulations! Your beacon node is up and running, and syncing the network!
Congratulations!
Your beacon node is up and running, and syncing the network!
!!! success "What next?"

6
docs/the_nimbus_book/src/resources.md
View File

@ -4,9 +4,9 @@
- [Validator launchpad](https://launchpad.ethereum.org): to send deposits
- [Beacon chain explorer](https://beaconcha.in/) : to monitor network health
- [Beacon chain explorer](https://beaconcha.in/): to monitor network health
- [Nimbus discord](https://discord.com/invite/XRxWahP) : best place to ask questions and to stay up-to-date with critical updates
- [Nimbus discord](https://discord.com/invite/XRxWahP): best place to ask questions and to stay up-to-date with critical updates
- [Ethereum on ARM: Raspberry Pi 4 image + tutorial](https://www.reddit.com/r/ethereum/comments/gf3nhg/ethereum_on_arm_raspberry_pi_4_images_release/) : turn your Raspberry Pi 4 into an eth1 or eth2 node just by flashing the MicroSD card
- [Ethereum on ARM: Raspberry Pi 4 image + tutorial](https://www.reddit.com/r/ethereum/comments/gf3nhg/ethereum_on_arm_raspberry_pi_4_images_release/): turn your Raspberry Pi 4 into an eth1 or eth2 node just by flashing the MicroSD card

159
docs/the_nimbus_book/src/rest-api.md
View File

@ -1,11 +1,13 @@
# Beacon API
Nimbus exposes an **extremely fast** implementation of the standard [Beacon API](https://ethereum.github.io/beacon-APIs/). The API allows you to use Nimbus together with third-party tooling such as validator clients, block explorers as well as your own monitoring infrastructure.
Nimbus exposes an **extremely fast** implementation of the standard [Beacon API](https://ethereum.github.io/beacon-APIs/).
The API allows you to use Nimbus together with third-party tooling such as validator clients, block explorers, as well as your own monitoring infrastructure.
The Beacon API is a `REST` interface accessed via `http`. If you wish to expose the beacon node to the public internet, it is recommended to use a proxy such as `nginx` to provide caching and SSL support.
The Beacon API is a `REST` interface accessed via `http`.
If you wish to expose the beacon node to the public internet, it is recommended to use a proxy such as `nginx` to provide caching and SSL support.
!!! warning
If you are running validators with your beacon node, do not expose the REST API to the public internet or use the same beacon node for deep historical queries - doing so may negatively affect validator performance.
If you are running validators with your beacon node, do not expose the REST API to the public internet or use the same beacon node for deep historical queries: doing so may negatively affect validator performance.
## Test your tooling against our servers
@ -17,121 +19,127 @@ The Beacon API is a `REST` interface accessed via `http`. If you wish to expose
You can make requests as follows (here we are requesting the version the Nimbus software version of the node in question):
#### Mainnet testing branch
```
curl -X GET http://testing.mainnet.beacon-api.nimbus.team/eth/v1/node/version
```
=== "Mainnet testing branch"
```
curl -X GET http://testing.mainnet.beacon-api.nimbus.team/eth/v1/node/version
```
#### Mainnet unstable branch
```
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/node/version
```
=== "Mainnet unstable branch"
```
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/node/version
```
#### Prater unstable branch
```
curl -X GET http://unstable.prater.beacon-api.nimbus.team/eth/v1/node/version
```
=== "Prater unstable branch"
```
curl -X GET http://unstable.prater.beacon-api.nimbus.team/eth/v1/node/version
```
The test endpoints are part of pre-release testing and run an unstable version of Nimbus - we welcome reports about any problems you might have with them.
The test endpoints are part of pre-release testing and run an unstable version of Nimbus.
We welcome reports about any problems you might have with them.
They may also be unresponsive at times - so **please do not rely on them for validation**. We may also disable them at any time without warning.
They may also be unresponsive at times: **please do not rely on them for validation**.
We may also disable them at any time without warning.
## Configure your node to run a local REST server
By default, the REST interface is disabled. To enable it, start the beacon node with the `--rest` option:
By default, the REST interface is disabled.
To enable it, start the beacon node with the `--rest` option:
```
./run-mainnet-beacon-node.sh --rest
```
Then access the API from `http://localhost:5052/`. For example, to get the version of the Nimbus software your node is running:
Then access the API from `http://localhost:5052/`.
For example, to get the version of the Nimbus software your node is running:
```
curl -X GET http://localhost:5052/eth/v1/node/version
```
By default, only connections from the same machine are entertained. The port and listening address can be further configured through the options `--rest-port` and `--rest-address`.
By default, only connections from the same machine are entertained.
The port and listening address can be further configured through the options `--rest-port` and `--rest-address`.
> **Warning:** If you are using a validator client with a Nimbus beacon node, and running a Nimbus version prior to `v1.5.5`, then you will need to launch the node with the `--subscribe-all-subnets` option enabled (in addition to the `--rest` option).
!!! warning
If you are using a validator client with a Nimbus beacon node, and running a Nimbus version prior to `v1.5.5`, then you will need to launch the node with the `--subscribe-all-subnets` option enabled (in addition to the `--rest` option).
## Some useful commands
### Standard endpoints
While these are all well documented in the [official docs](https://ethereum.github.io/beacon-APIs/) here are a handful of simple examples to get you started:
While these are all well documented in the [official docs](https://ethereum.github.io/beacon-APIs/), here are a handful of simple examples to get you started:
#### Genesis
Retrieve details of the chain's genesis which can be used to identify chain.
*With our mainnet testing server*
```
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/beacon/genesis
```
=== "With our mainnet testing server"
```
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/beacon/genesis
```
*With your own local server*
```
curl -X GET http://localhost:5052/eth/v1/beacon/genesis
```
=== "With your own local server"
```
curl -X GET http://localhost:5052/eth/v1/beacon/genesis
```
#### Deposit contract
Get deposit contract address (retrieve Eth1 deposit contract address and chain ID).
*With our mainnet testing server*
```
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/config/deposit_contract
```
=== "With our mainnet testing server"
```
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/config/deposit_contract
```
*With your own local server*
```
curl -X GET http://localhost:5052/eth/v1/config/deposit_contract
```
=== "With your own local server"
```
curl -X GET http://localhost:5052/eth/v1/config/deposit_contract
```
#### Peer count
Get peer count
Get peer count:
*With our mainnet testing server*
```
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/node/peer_count
```
=== "With our mainnet testing server"
```
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/node/peer_count
```
*With your own local server*
```
curl -X GET http://localhost:5052/eth/v1/node/peer_count
```
=== "With your own local server"
```
curl -X GET http://localhost:5052/eth/v1/node/peer_count
```
#### Syncing status
Get node syncing status (requests the beacon node to describe if it's currently syncing or not, and if it is, what block it is up to)
*With our mainnet testing server*
```
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/node/syncing
```
=== "With our mainnet testing server"
```
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/node/syncing
```
*With your own local server*
```
curl -X GET http://localhost:5052/eth/v1/node/syncing
```
=== "With your own local server"
```
curl -X GET http://localhost:5052/eth/v1/node/syncing
```
#### Fork schedule
Get scheduled upcoming forks (retrieve all forks, past present and future, of which this node is aware)
*With our mainnet testing server*
```
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/config/fork_schedule
```
=== "With our mainnet testing server"
```
curl -X GET http://unstable.mainnet.beacon-api.nimbus.team/eth/v1/config/fork_schedule
```
*With your own local server*
```
curl -X GET http://localhost:5052/eth/v1/config/fork_schedule
```
=== "With your own local server"
```
curl -X GET http://localhost:5052/eth/v1/config/fork_schedule
```
### Nimbus specific endpoints
@ -142,23 +150,22 @@ In addition to supporting the standard endpoints, Nimbus has a set of specific e
#### Check Graffiti String
*With our mainnet testing server*
=== "With our mainnet testing server"
```
curl -X GET http://testing.mainnet.beacon-api.nimbus.team/nimbus/v1/graffiti
```
```
curl -X GET http://testing.mainnet.beacon-api.nimbus.team/nimbus/v1/graffiti
```
*With your own local server*
```
curl -X GET http://localhost:5052/nimbus/v1/graffiti
```
=== "With your own local server"
```
curl -X GET http://localhost:5052/nimbus/v1/graffiti
```
#### Set Graffiti String
*With your own local server*
```
curl -X POST http://localhost:5052/nimbus/v1/graffiti -H "Content-Type: text/plain" -d "new graffiti"
```
=== "With your own local server"
```
curl -X POST http://localhost:5052/nimbus/v1/graffiti -H "Content-Type: text/plain" -d "new graffiti"
```
#### Set Log Level

11
docs/the_nimbus_book/src/security_issues.md
View File

@ -1,14 +1,13 @@
## Security related issues
**For any security related issues, follow responsible disclosure standards. Do not file public issues.**
**For any security related issues, follow responsible disclosure standards.
Do not file public issues.**
*Please file a report at the ethereum [bug bounty program](https://ethereum.org/en/bug-bounty/) in order to receive a reward for your findings.*
Please file a report at the [Ethereum bug bounty program](https://ethereum.org/en/bug-bounty/) in order to receive a reward for your findings.
When in doubt, please send an encrypted email to security@status.im and ask ([gpg key](https://github.com/status-im/status-security/blob/master/pgp-keys/security%40status.im.asc)).
*When in doubt, please send an encrypted email to security@status.im and ask ([gpg key](https://github.com/status-im/status-security/blob/master/pgp-keys/security%40status.im.asc)).*
*Security related issues are (sufficient but not necessary criteria):*
Security related issues are (sufficient but not necessary criteria):
- Soundness of protocols (consensus model, p2p protocols): consensus liveness and integrity.
- Errors and failures in the cryptographic primitives

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

@ -1,6 +1,7 @@
# Sync your node
Before you can use your node, it needs to sync with the network. Syncing starts automatically when you start your node, and may take several days depending on the performance of your hardware.
Before you can use your node, it needs to sync with the network.
Syncing starts automatically when you start your node, and may take several days depending on the performance of your hardware.
If you are planning to become a validator, you should ensure that your beacon node is [completely synced](./keep-an-eye.md#keep-track-of-your-syncing-progress) before submitting your deposit, or you might miss attestations and proposal duties until it has finished syncing.
@ -8,18 +9,21 @@ If you are planning to become a validator, you should ensure that your beacon no
To get started more quickly, you can perform a [trusted node sync](./trusted-node-sync.md) instead - this requires access to a synced node or a third-party service.
!!! note
You need need to run an execution client (**web3 provider**) together with the beacon node. See [here](./eth1.md) for instructions on how to do so.
You need need to run an execution client (**web3 provider**) together with the beacon node.
See [here](./eth1.md) for instructions on how to do so.
## Networks
Using Nimbus, you can connect either to a testnet, or mainnet. Mainnet is the main ethereum network where real assets are at stake, while testnets are used by users and developers alike to test their node and setup before committing real assets.
Using Nimbus, you can connect either to a testnet or mainnet.
Mainnet is the main Ethereum network where real assets are at stake, while testnets are used by users and developers alike to test their node and setup before committing real assets.
!!! tip
If this is the first time you're setting up your node, it is recommended you run it on a testnet first. Later, when everything is working, you can easily switch to mainned.
If this is the first time you're setting up your node, it is recommended you run it on a testnet first.
Later, when everything is working, you can easily switch to mainnet.
### Testnet
To start syncing the `prater` testnet , from the `nimbus-eth2` repository, run:
To start syncing the `prater` testnet from the `nimbus-eth2` repository, run:
```
./run-prater-beacon-node.sh
@ -27,7 +31,6 @@ To start syncing the `prater` testnet , from the `nimbus-eth2` repository, run:
### Mainnet
To start syncing the Ethereum beacon chain mainnet, run:
```
@ -55,11 +58,13 @@ INF 2020-12-01 11:26:36.285+00:00 Slot end top
## Data directory
While running, the beacon node will store chain data and other information its data directory, which by default is found in `build/data` - for more information, see the [data directory](./data-dir.md) guide.
While running, the beacon node will store chain data and other information its data directory, which by default is found in `build/data`.
For more information, see the [data directory](./data-dir.md) guide.
## Command line options
You can add command line options to the startup command - for example, to change the port to 9100, use:
You can add command line options to the startup command.
For example, to change the port to 9100, use:
```sh
./run-prater-beacon-node.sh --tcp-port=9100 --udp-port=9100

11
docs/the_nimbus_book/src/suggested-fee-recipient.md
View File

@ -2,10 +2,11 @@
The fee recipient is an Ethereum address that receives transaction fees from block production, separately from the proposer reward that accrues on the beacon chain.
The fee recipient is forwarded to the execution client during block production - each validator can have its own fee recipient set or a single recipient may be used.
The fee recipient is forwarded to the execution client during block production.
Each validator can have its own fee recipient set or a single recipient may be used.
!!! warning
The execution client is not required to follow the fee recipient suggestion and may instead send the fees to a different address - only use execution clients you trust!
The execution client is not required to follow the fee recipient suggestion and may instead send the fees to a different address — only use execution clients you trust!
If no fee recipient is set up, the transaction fees are sent to the zero address, effectively causing them to be lost.
@ -15,13 +16,15 @@ Nimbus supports setting fee recipient per validator, or using defaults in both t
Per-validator fee recipients are set using the [keymanager API](./keymanager-api.md).
Any validator without a per-validator recipient set will fall back to the `--suggested-fee-recipient` option if configured. In order, it selects from the first available, for each validator, of:
Any validator without a per-validator recipient set will fall back to the `--suggested-fee-recipient` option if configured.
For each validator, it selects from the first available, in the following order:
1. the keymanager API per-validator suggested fee recipient
2. `--suggested-fee-recipient` in the validator client
3. `--suggested-fee-recipient` in the beacon node
For example, `nimbus_beacon_node --suggested-fee-recipient=0x70E47C843E0F6ab0991A3189c28F2957eb6d3842` suggests to the execution client that `0x70E47C843E0F6ab0991A3189c28F2957eb6d3842` might be the coinbase. If this Nimbus node has two validators, one of which has its own suggested fee recipient via the keymanager API and the other does not, the former would use its own per-validator suggested fee cipient while the latter would fall back to `0x70E47C843E0F6ab0991A3189c28F2957eb6d3842`.
For example, `nimbus_beacon_node --suggested-fee-recipient=0x70E47C843E0F6ab0991A3189c28F2957eb6d3842` suggests to the execution client that `0x70E47C843E0F6ab0991A3189c28F2957eb6d3842` might be the coinbase.
If this Nimbus node has two validators, one of which has its own suggested fee recipient via the keymanager API and the other does not, the former would use its own per-validator suggested fee recipient, while the latter would fall back to `0x70E47C843E0F6ab0991A3189c28F2957eb6d3842`.
## Command line

56
docs/the_nimbus_book/src/troubleshooting.md
View File

@ -1,20 +1,24 @@
# Troubleshooting
!!! note
The commands on this page refer to mainnet. If you're running on `prater` or another testnet, replace `mainnet` accordingly
The commands on this page refer to mainnet.
If you're running on `prater` or another testnet, replace `mainnet` accordingly.
We are continuously making improvements to both stability and resource usage. If you run into any problem with Nimbus and are not running the latest version, chances are they have already been fixed - see the [update guide](./keep-updated.md) for instructions of how to upgrade.
We are continuously making improvements to both stability and resource usage.
If you run into any problem with Nimbus and are not running the latest version, chances are they have already been fixed.
See the [update guide](./keep-updated.md) for instructions of how to upgrade.
If you can't find a solution to your problem here, get in touch with us on our [discord](https://discord.com/invite/XRxWahP)!
If you can't find a solution to your problem here, get in touch with us on our [discord](https://discord.com/invite/XRxWahP).
!!! note
When installing Nimbus, you will typically be using the latest `stable` release.
However, the latest changes happen in the `unstable` branch - if you're looking to test the chaings coming to the _next_ Nimbus release, consider building Nimbus from [source](./keep-updated.md#build-from-source) using the `unstable` branch.
However, the latest changes happen in the `unstable` branch.
If you're looking to test the changes coming to the _next_ Nimbus release, consider building Nimbus from [source](./keep-updated.md#build-from-source) using the `unstable` branch.
## Networking
A correctly configured network is key to getting good performance - the [networking guide](./networking.md) details everything you need to know!
A correctly configured network is key to getting good performance: the [networking guide](./networking.md) details everything you need to know!
### Low peer count
@ -24,7 +28,9 @@ If you see a message that looks like the following in your logs:
Peer count low, no new peers discovered...
```
Your node is finding it hard to find peers. It's possible that you may be behind a firewall. Try restarting your client and passing `--nat:extip:$EXT_IP_ADDRESS` as an option to `./run-mainnet-beacon-node.sh`, where `$EXT_IP_ADDRESS` is your real IP. For example, if your real IP address is `1.2.3.4`, you'd run:
Your node is finding it hard to find peers.
It's possible that you may be behind a firewall.
Try restarting your client and passing `--nat:extip:$EXT_IP_ADDRESS` as an option to `./run-mainnet-beacon-node.sh`, where `$EXT_IP_ADDRESS` is your real IP. For example, if your real IP address is `1.2.3.4`, you'd run:
```
./run-mainnet-beacon-node.sh --nat:extip:1.2.3.4
@ -42,9 +48,13 @@ No peers for topic, skipping publish...
This means you've missed an attestation because either your peer count is too low, or the quality of your peers is lacking.
There can be several reasons behind why this is the case. The first thing to check is that your max peer count (`--max-peers`) hasn't been set too low. In order to ensure your attestations are published correctly, `--max-peers` should be set to 70, at the *very least*.
There can be several reasons behind why this is the case.
The first thing to check is that your max peer count (`--max-peers`) hasn't been set too low.
In order to ensure your attestations are published correctly, `--max-peers` should be set to 70, at the *very least*.
> Note that Nimbus manages peers slightly differently to other clients (we automatically connect to more peers than we actually use, in order not to have to do costly reconnects). As such, `--max-peers` is set to 160 by default.
!!! note
Nimbus manages peers slightly differently to other clients (we automatically connect to more peers than we actually use, in order not to have to do costly reconnects).
As such, `--max-peers` is set to 160 by default.
If this doesn't fix the problem, please double check your node is able to [receive incoming connections](./networking.md#check-for-incoming-connections).
@ -64,23 +74,27 @@ make nimbus_beacon_node # Rebuild beacon node
If you find that `make update` causes the console to hang for too long, try running `make update V=1` or `make update V=2` instead (these will print a more verbose output to the console which may make it easier to diagnose the problem).
>**Note:** rest assured that when you restart the beacon node, the software will resume from where it left off, using the validator keys you have already imported.
!!! note
Rest assured that when you restart the beacon node, the software will resume from where it left off, using the validator keys you have already imported.
### Starting over after importing wrong keys
Your keys and secrets are stored in the [data directory](./data-dir.md) (usually `build/data/shared_mainnet_0`). If you imported the wrong keys, simply remove them from `validators` and `secrets` found in the data directory.
Your keys and secrets are stored in the [data directory](./data-dir.md) (usually `build/data/shared_mainnet_0`).
If you imported the wrong keys, simply remove them from `validators` and `secrets` found in the data directory.
### Sync problems
If you’re experiencing sync problems, make sure that your network is healthy and that you have a recent version installed.
In rare cases, such as after an unclean shutdown, it may happen that the database has been corrupted and you need to restart the sync - to do so, remove the `db` folder from the [data directory](./data-dir.md) and restart the node. You can get re-synced faster using [trusted node sync](./trusted-node-sync.md).
In rare cases, such as after an unclean shutdown, it may happen that the database has been corrupted and you need to restart the sync.
To do so, remove the `db` folder from the [data directory](./data-dir.md) and restart the node.
You can get re-synced faster using [trusted node sync](./trusted-node-sync.md).
### noCommand does not accept arguments
If, on start, you see `The command 'noCommand' does not accept arguments`
If, on start, you see `The command 'noCommand' does not accept arguments`.
Double check to see if your command line flags are in the correct format, i.e. `--foo=bar`, `--baz`, or `--foo-bar=qux`.
Double check to see if your command line flags are in the correct format, e.g. `--foo=bar`, `--baz`, or `--foo-bar=qux`.
!!! tip
All options accepting values need a `=` between the option name and the value!
@ -93,7 +107,7 @@ If you're seeing an error that looks like:
Error: unhandled exception: (98) Address already in use [TransportOsError]
```
It means that you're running another node that is using the same port as the one you're trying to start (or that you're trying to start a second instance of the same node).
It means that you're running another node that is using the same port as the one you're trying to start or that you're trying to start a second instance of the same node.
To change the base port, run:
@ -101,11 +115,12 @@ To change the base port, run:
./run-mainnet-beacon-node.sh --tcp-port=9100 --udp-port=9100
```
(You can replace `9100` with a port of your choosing)
You can replace `9100` with a port of your choosing.
### Catching up on validator duties
If you're being flooded with `Catching up on validator duties` messages, your CPU is probably too slow to run Nimbus. Please check that your setup matches our [system requirements](./hardware.md).
If you're being flooded with `Catching up on validator duties` messages, your CPU is probably too slow to run Nimbus.
Please check that your setup matches our [system requirements](./hardware.md).
### Eth1 chain monitor failure
@ -115,7 +130,10 @@ If you see an error that looks like the following:
{"lvl":"ERR","ts":"2021-05-11 09:05:53.547+00:00","msg":"Eth1 chain monitoring failure, restarting","topics":"eth1","tid":1,"err":"Trying to access value with err: Failed to setup web3 connection"}
```
It's because your node can't connect to the web3 provider you have specified. Please double check that you've correctly specified your provider. If you haven't done so already, we recommend [adding a backup](web3-backup.md).
It is because your node can't connect to the web3 provider you have specified.
Please double check that you've correctly specified your provider.
If you haven't done so already, we recommend [adding a backup](web3-backup.md).
### Discovered new external address warning log
@ -125,7 +143,9 @@ Discovered new external address but ENR auto update is off
topics="discv5" tid=77655 file=protocol.nim:940 majority=Some("myIPaddressHere":9000) previous=None[Address]
```
This message is displayed regularly when Nimbus canot detect your correct IP address. It may be a sign that you have a dynamic IP address that keeps changing. Or that Nimbus is unable to get your IP from the [UPnP](https://en.wikipedia.org/wiki/Universal_Plug_and_Play).
This message is displayed regularly when Nimbus cannot detect your correct IP address.
It may be a sign that you have a dynamic IP address that keeps changing.
Or that Nimbus is unable to get your IP from the [UPnP](https://en.wikipedia.org/wiki/Universal_Plug_and_Play).
The first step is to try relaunching the beacon node with the `--enr-auto-update` option.

46
docs/the_nimbus_book/src/trusted-node-sync.md
View File

@ -1,27 +1,28 @@
# Sync from a trusted node
!!! note ""
This feature is available from `v1.7.0` onwards
This feature is available from `v1.7.0` onwards.
When you [start the beacon node](./quick-start.md) for the first time, it connects to the beacon chain network and starts syncing automatically - a process that can take several days.
When you [start the beacon node](./quick-start.md) for the first time, it connects to the beacon chain network and starts syncing automatically — a process that can take several days.
Trusted node sync allows you to get started more quickly by fetching a recent checkpoint from a trusted node - you can get started in minutes instead of days.
To use trusted node sync, you must have access to a node that you trust and that exposes the [Beacon API](./rest-api.md) (for example a locally running backup node).
Trusted node sync allows you to get started more quickly by fetching a recent checkpoint from a trusted node — you can get started in minutes instead of days.
To use trusted node sync, you must have access to a node that you trust and that exposes the [Beacon API](./rest-api.md) (for example, a locally running backup node).
Should this node, or your connection to it, be compromised, your node will not be able to detect whether or not it is being served false information.
It is possible to use trusted node sync with a third-party API provider -- see [here](trusted-node-sync.md#verify-you-synced-the-correct-chain) for how to verify that the chain you are given corresponds to the canonical chain at the time.
It is possible to use trusted node sync with a third-party API provider — see [here](trusted-node-sync.md#verify-you-synced-the-correct-chain) for how to verify that the chain you are given corresponds to the canonical chain at the time.
!!! tip
A list of community-operated checkpoint sync nodes can be found [here](https://eth-clients.github.io/checkpoint-sync-endpoints/) - always verify after after a checkpoint sync that the right chain was provided by the node.
A list of community-operated checkpoint sync nodes can be found [here](https://eth-clients.github.io/checkpoint-sync-endpoints/).
Always verify after after a checkpoint sync that the right chain was provided by the node.
## Perform a trusted node sync
!!! tip
Make sure to replace `http://localhost:5052` in the commands below with the appropriate endpoint of the trusted beacon node. `http://localhost:5052` is the default endpoint exposed by Nimbus, but this is not consistent across all clients.
For example, if your trusted node is a [Prysm node](https://docs.prylabs.network/docs/how-prysm-works/ethereum-public-api#performing-requests-against-a-local-prysm-node), it exposes `127.0.0.1:3500` by default. Which means you would run the commands below with `--trusted-node-url=http://127.0.0.1:3500`
For example, if your trusted node is a [Prysm node](https://docs.prylabs.network/docs/how-prysm-works/ethereum-public-api#performing-requests-against-a-local-prysm-node), it exposes `127.0.0.1:3500` by default.
Which means you would run the commands below with `--trusted-node-url=http://127.0.0.1:3500`
!!! note
The path specified for `--data-dir` must be an empty directory as trusted node sync needs to be started from a fresh database.
@ -43,7 +44,7 @@ To start trusted node sync, run:
--trusted-node-url=http://localhost:5052
```
If the command was executed succesfully, following log lines will be visible:
If the command was executed successfully, following log lines will be visible:
```
Writing checkpoint state
@ -51,13 +52,15 @@ Writing checkpoint block
```
And eventually:
```
Done, your beacon node is ready to serve you! Don't forget to check that you're on the canonical chain by comparing the checkpoint root with other online sources. See https://nimbus.guide/trusted-node-sync.html for more information.
Done, your beacon node is ready to serve you! Don't forget to check that you're on the canonical chain by comparing the checkpoint root with other online sources.
See https://nimbus.guide/trusted-node-sync.html for more information.
```
After this the application will terminate and you can now [start the beacon node](./quick-start.md) as usual.
!!! note
Because trusted node sync by default copies blocks via REST, you may hit API limits if you are using a third-party provider. If this happens to you, you may need to use the `--backfill` option to [delay the backfill of the block history](./trusted-node-sync.md#delay-block-history-backfill).
Because trusted node sync by default copies blocks via REST, you may hit API limits if you are using a third-party provider.
If this happens to you, you may need to use the `--backfill` option to [delay the backfill of the block history](./trusted-node-sync.md#delay-block-history-backfill).
## Verify you synced the correct chain
@ -83,30 +86,36 @@ The `head` root is also printed in the log output at regular intervals.
### Sync deposit history
!!! note ""
This feature is available from `v22.12.0` onwards
This feature is available from `v22.12.0` onwards.
The `--with-deposit-snapshot` allows syncing deposit history via REST, avoiding the need to search the execution client for this information and thus allowing the client to more quickly start producing blocks.
!!! note
The API endpoint for downloading this information was recently added to the Beacon API specification and is available on nodes running Nimbus v22.12.0 and later. For other checkpoint sources, consult their documentation with regards to the `/eth/v1/beacon/deposit_snapshot` endpoint.
The API endpoint for downloading this information was recently added to the Beacon API specification and is available on nodes running Nimbus v22.12.0 and later.
For other checkpoint sources, consult their documentation with regards to the `/eth/v1/beacon/deposit_snapshot` endpoint.
!!! tip
It's safe to always specify this option. Nimbus will produce a warning if the specified beacon node doesn't support the required endpoint. Future versions of Nimbus will enable the option by default.
It's safe to always specify this option.
Nimbus will produce a warning if the specified beacon node doesn't support the required endpoint.
Future versions of Nimbus will enable the option by default.
### Delay block history backfill
By default, both state and block history will be downloaded from the trusted node.
It is possible to get started more quickly by delaying the backfill of the block history using the `--backfill=false` parameter. In this case, the beacon node will first sync to the current head so that it can start performing its duties, then backfill the blocks from the network.
It is possible to get started more quickly by delaying the backfill of the block history using the `--backfill=false` parameter.
In this case, the beacon node will first sync to the current head so that it can start performing its duties, then backfill the blocks from the network.
You can also resume the trusted node backfill at any time by simply running the trusted node sync command again.
!!! note
While backfilling blocks, your node will not be able to answer historical requests or sync requests. This might lead to you being de-scored, and eventually disconnected, by your peers.
While backfilling blocks, your node will not be able to answer historical requests or sync requests.
This might lead to you being de-scored, and eventually disconnected, by your peers.
### Modify sync point
By default, the node will sync up to the latest finalized checkpoint of the node that you're syncing with. While you can choose a different sync point using a state hash or a slot number, this state must fall on an epoch boundary:
By default, the node will sync up to the latest finalized checkpoint of the node that you're syncing with.
While you can choose a different sync point using a state hash or a slot number, this state must fall on an epoch boundary:
```sh
build/nimbus_beacon_node trustedNodeSync \
@ -132,7 +141,8 @@ curl -o state.32000.ssz \
## Recreate historical state access indices
When performing trusted node sync, the historical state data from the time before the trusted is not available. To recreate the indices and caches necessary for historical state access, run trusted node sync with the `--reindex` flag - this can be done on an already-synced node as well, in which case the process will simply resume where it left off:
When performing trusted node sync, the historical state data from the time before the trusted is not available.
To recreate the indices and caches necessary for historical state access, run trusted node sync with the `--reindex` flag — this can be done on an already-synced node as well, in which case the process will simply resume where it left off:
To recreate a historical index from before the checkpoint, it is necessary to first download an [era archive](./era-store.md) containing the deep block history.

22
docs/the_nimbus_book/src/validator-client-options.md
View File

@ -4,7 +4,7 @@ In the most simple setup, a single beacon node paired with an execution client i
Nimbus however also provides options for running advanded setups that provide additional security and redundancy.
See the [validator client](./validator-client.md) page to get started!
See the [validator client page](./validator-client.md) to get started!
## Multiple beacon nodes
@ -34,7 +34,7 @@ When configuring multiple beacon nodes, each beacon node can be assigned to perf
| sync-publish | [publishContributionAndProofs()](https://ethereum.github.io/beacon-APIs/#/Validator/publishContributionAndProofs) <br/> [submitPoolSyncCommitteeSignatures()](https://ethereum.github.io/beacon-APIs/#/Beacon/submitPoolSyncCommitteeSignatures) |
| duties | [getGenesis()](https://ethereum.github.io/beacon-APIs/#/Beacon/getGenesis)<br/>[getSpec()](https://ethereum.github.io/beacon-APIs/#/Config/getSpec)<br/> [getSyncingStatus()](https://ethereum.github.io/beacon-APIs/#/Node/getSyncingStatus)<br/>getValidatorsActivity()<br/>[getForkSchedule()](https://ethereum.github.io/beacon-APIs/#/Config/getForkSchedule)<br/>[getAttesterDuties()](https://ethereum.github.io/beacon-APIs/#/Validator/getAttesterDuties)<br/>[getProposerDuties()](https://ethereum.github.io/beacon-APIs/#/Validator/getProposerDuties)<br/>[getSyncCommitteeDuties()](https://ethereum.github.io/beacon-APIs/#/Validator/getSyncCommitteeDuties)<br/> [getStateValidators()](https://ethereum.github.io/beacon-APIs/#/Beacon/getStateValidators)<br/>[prepareSyncCommitteeSubnets()](https://ethereum.github.io/beacon-APIs/#/Validator/prepareSyncCommitteeSubnets)<br/>[prepareBeaconCommitteeSubnet()](https://ethereum.github.io/beacon-APIs/#/Validator/prepareBeaconCommitteeSubnet) |
Also there could be combinations
Also, there could be combinations:
| Name | Roles |
| ----------- |:-------------------------------------------------------------------- |
@ -48,13 +48,15 @@ Also there could be combinations
### Configuration
Roles are configured using the `#roles=` URL anchor - the default is `all`:
Roles are configured using the `#roles=` URL anchor.
The default is `all`:
Examples:
`http://127.0.0.1:5052/#roles=attestation-data,attestation-publish`
`http://127.0.0.1:5053/#roles=block-proposal-data,block-proposal-publish`
`http://127.0.0.1:5054/#roles=all`
`http://127.0.0.1:5055/` also means `all` roles.
- `http://127.0.0.1:5052/#roles=attestation-data,attestation-publish`
- `http://127.0.0.1:5053/#roles=block-proposal-data,block-proposal-publish`
- `http://127.0.0.1:5054/#roles=all`
- `http://127.0.0.1:5055/` also means `all` roles.
Before usage all the roles are got stripped from BN URLs.
@ -68,9 +70,11 @@ These setups are resilient against any single beacon node getting disconnected a
### Sentry node setup
In the Ethereum network, the block proposer is known up to 12 minutes before they propose the block. Because each validator sends attestations every 6 minutes, it is also possible to map the validator key to the beacon node IP address that serves it.
In the Ethereum network, the block proposer is known up to 12 minutes before they propose the block.
Because each validator sends attestations every 6 minutes, it is also possible to map the validator key to the beacon node IP address that serves it.
Sentry nodes setups allow separating block production traffic from attestations and sync committee messages, making sure that a separate public IP address is used when proposing blocks. In this setup, there are two beacon nodes:
Sentry nodes setups allow separating block production traffic from attestations and sync committee messages, making sure that a separate public IP address is used when proposing blocks.
In this setup, there are two beacon nodes:
* One beacon node has all roles except `block`
* The other beacon node has the `block` role

12
docs/the_nimbus_book/src/validator-client.md
View File

@ -1,14 +1,17 @@
# Run a separate validator client
!!! warning
Some features of the validator client, such as the metrics server, are currently in BETA and details may change in response to community feedback. Please consult the `--help` screen for more details.
Some features of the validator client, such as the metrics server, are currently in BETA and details may change in response to community feedback.
Please consult the `--help` screen for more details.
By default, Nimbus integrates the validator client into the main beacon node process - this is a simple, safe and efficient way to run a validator.
Advanced users may wish to run validators in a separate process, allowing more flexible deployment strategies. The Nimbus beacon node supports both its own and third-party validator clients via the built-in [REST API](./rest-api.md).
Advanced users may wish to run validators in a separate process, allowing more flexible deployment strategies.
The Nimbus beacon node supports both its own and third-party validator clients via the built-in [REST API](./rest-api.md).
!!! warning
So far, all slashings with known causes have been linked to overly complex setups involving separation between beacon node and validator client! Only use this setup if you've taken steps to mitigate the increased risk.
So far, all slashings with known causes have been linked to overly complex setups involving separation between beacon node and validator client!
Only use this setup if you've taken steps to mitigate the increased risk.
## Setup
@ -22,7 +25,8 @@ build/nimbus_beacon_node deposits import \
```
!!! warning
Do not use the same data directory for beacon node and validator client - they will both try to load the same keys which may result in slashing!
Do not use the same data directory for beacon node and validator client!
They will both try to load the same keys which may result in slashing!
!!! warning
If you are migrating your keys from the beacon node to the validator client, simply move the `secrets` and `validators` folders in the beacon node data directory to the data directory of the validator client

35
docs/the_nimbus_book/src/validator-monitor.md
View File

@ -1,13 +1,14 @@
# Validator monitoring
!!! note ""
This feature is available from `v23.1.0` onwards - earlier Nimbus versions included a preview version this feature behind a feature flag without enabling it by default.
!!! note
This feature is available from `v23.1.0` onwards.
Earlier Nimbus versions included a preview version this feature behind a feature flag without enabling it by default.
The validator monitoring feature allows for tracking the life cycle and performance of one or more validators in detail.
Monitoring can be carried out for any validator, with slightly more detail for validators that are running in the same beacon node.
Every time the validator performs a duty, the duty is recorded and the monitor keeps track of the reward-related events for having performed it. For example:
Every time the validator performs a duty, the duty is recorded and the monitor keeps track of the reward-related events for having performed it.
For example:
* When attesting, the attestation is added to an aggregate, then a block, before a reward is applied to the state
* When performing sync committee duties, likewise
@ -18,12 +19,15 @@ The metrics are broadly compatible with [Lighthouse](https://lighthouse-book.sig
## Command line options
The monitor is by default enabled for all keys that are validating via the beacon node. It can also be configured to monitor a specific list of validators, or be disabled entirely with `--validator-monitor-auto=false`.
The monitor is by default enabled for all keys that are validating via the beacon node.
It can also be configured to monitor a specific list of validators, or be disabled entirely with `--validator-monitor-auto=false`.
The `--validator-monitor-details` flag can be used to enable the detailed monitor mode - in this mode, the performance of each validator is monitored individually in metrics leading to a more detailed view of performance.
The `--validator-monitor-details` flag can be used to enable the detailed monitor mode.
In this mode, the performance of each validator is monitored individually in metrics leading to a more detailed view of performance.
!!! tip
The detailed mode significantly increases the total number of published metrics for each monitored validator - when used with more than 10 validators, it may adversely impact performance of metrics collection and display
The detailed mode significantly increases the total number of published metrics for each monitored validator.
When used with more than 10 validators, it may adversely impact performance of metrics collection and display.
```sh
# Disable automatic monitoring of all validators used with this beacon node beacon node
@ -40,9 +44,12 @@ The `--validator-monitor-details` flag can be used to enable the detailed monito
## Understanding monitoring
When a validator performs a duty, such as signing an attestation or a sync committee message, this is broadcast to the network. Other nodes pick it up and package the message into an aggregate and later a block. The block is included in the canonical chain and a reward is given two epochs (~13 minutes) later.
When a validator performs a duty, such as signing an attestation or a sync committee message, this is broadcast to the network.
Other nodes pick it up and package the message into an aggregate and later a block.
The block is included in the canonical chain and a reward is given two epochs (~13 minutes) later.
The monitor tracks each of these actions and will in detailed mode log each step at the `INF` level. If any step is missed (irrespective of detail mode), a `NOT` log is shown instead.
The monitor tracks each of these actions and will in detailed mode log each step at the `INF` level.
If any step is missed (irrespective of detail mode), a `NOT` log is shown instead.
The typical life cycle of an attestation might look something like the following:
@ -60,12 +67,16 @@ Failures at any point are recorded at a higher logging level, such as `NOT`(ice)
NOT 2021-11-17 20:53:42.108+01:00 Attestation failed to match head topics="chaindag" epoch=81972 validator=...
```
Failures are reported with a lag of two epochs (~13 minutes) - to examine the log for potential root causes, the logs from the epoch in the failure message should be looked at.
Failures are reported with a lag of two epochs (~13 minutes).
To examine the log for potential root causes, the logs from the epoch in the failure message should be looked at.
!!! warning
It should be noted that metrics are tracked for the current history - in the case of a reorg on the chain - in particular a deep reorg - no attempt is made to revisit previously reported values. In the case that finality is delayed, the risk of stale metrics increases.
It should be noted that metrics are tracked for the current history.
In the case of a reorg on the chain — in particular a deep reorg — no attempt is made to revisit previously reported values.
In the case that finality is delayed, the risk of stale metrics increases.
Likewise, many metrics, such as aggregation inclusion, reflect conditions on the network - it may happen that the same message is counted more than once under certain conditions.
Likewise, many metrics, such as aggregation inclusion, reflect conditions on the network.
It may happen that the same message is counted more than once under certain conditions.
## Monitoring metrics

8
docs/the_nimbus_book/src/voluntary-exit.md
View File

@ -2,13 +2,15 @@
Voluntary exits allow validators to permanently stop performing their duties, and eventually recover the deposit.
Exits are subject to a wait period that depends on the length of the exit queue. While a validator is exiting, it still must perform its duties in order not to lose funds to inactivity penalities.
Exits are subject to a wait period that depends on the length of the exit queue.
While a validator is exiting, it still must perform its duties in order not to lose funds to inactivity penalities.
!!! warning
Voluntary exits are **irreversible**. You won't be able to validate again with the same key.
Voluntary exits are **irreversible**.
You won't be able to validate again with the same key.
!!! note
Voluntary exits won't be processed if the chain isn't finalising.
Voluntary exits won't be processed if the chain isn't finalizing.
To perform a voluntary exit, make sure your beacon node is running with the `--rest` option enabled (e.g. `./run-mainnet-beacon-node.sh --rest`), then run:

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

@ -1,11 +1,14 @@
# Backup web3 provider
Nimbus supports using multiple web3 providers, in case one breaks or goes down. These web3 providers must share JWT secret and will be used in a fallback manner, meaning that when the first one fails, the second one will be used instead until the first one is back up.
Nimbus supports using multiple web3 providers, in case one breaks or goes down.
These web3 providers must share JWT secret and will be used in a fallback manner, meaning that when the first one fails, the second one will be used instead until the first one is back up.
Each beacon node requires at least one dedicated web3 provider.
!!! note
The backup web3 provider must use the same JWT secret as the main provider, and will not be used until the main provider has failed. This may result in a gap in duties as the backup provider syncs. This gap will be addressed in future releases.
The backup web3 provider must use the same JWT secret as the main provider, and will not be used until the main provider has failed.
This may result in a gap in duties as the backup provider syncs.
This gap will be addressed in future releases.
```sh
./run-mainnet-beacon-node.sh \

4
docs/the_nimbus_book/src/withdrawals.md
View File

@ -24,7 +24,7 @@ If you have used other software for generating your BLS withdrawal credentials,
Nimbus will allow you to broadcast the `BLS-to-Execution-Change` message only after the Capella hard-fork is activated on 12th of April 2023.
!!! tip
The specified withdrawal address doesn't need to match the [fee recipient address](./suggested-fee-recipient.md) used by your validator
The specified withdrawal address doesn't need to match the [fee recipient address](./suggested-fee-recipient.md) used by your validator.
!!! tip
It's recommended that you prepare your `BLS-to-Execution-Change` message on a secure device, disconnected from the internet.
@ -46,7 +46,7 @@ No user action is required.
## Full withdrawals
To withdrwal the entire staked balance of your validator, you must perform a voluntary validator exit.
To withdrawal the entire staked balance of your validator, you must perform a voluntary validator exit.
!!! warning
Voluntary exits are **irreversible**.