status-im
/
nimbus-eth2
mirror of https://github.com/status-im/nimbus-eth2.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Various docs fixes (#4789) 

- spelling fixes
- use the correct sintax for notes
- em-dashes should be em-dashes (`—`): double dashes (`--`) are not
  rendered properly
- fix a link (was to a .html, should be to .md)
- add missing dots
- every sentence should be on a separate line: it makes future diffs
  much nicer and easier to spot the changes
This commit is contained in:
Miran 2023-04-05 15:58:58 +02:00 committed by GitHub
parent 3bfff6f219
commit 05d99185c9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 176 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/the_nimbus_book/src/el-light-client.md
View File

@ -5,7 +5,8 @@
The Nimbus Light Client is a light-weight alternative to running a full beacon node, when you're not planning on becoming a validator but still want to run an Ethereum execution layer client.
Execution layer (EL) clients provide the [Web3 API](https://ethereum.github.io/execution-apis/api-documentation/) to expose information stored on the Ethereum blockchain. Since the merge 🐼, execution clients can no longer run standalone.
Execution layer (EL) clients provide the [Web3 API](https://ethereum.github.io/execution-apis/api-documentation/) to expose information stored on the Ethereum blockchain.
Since the merge 🐼, execution clients can no longer run standalone.
## Comparison
@ -19,10 +20,12 @@ Compared to a full beacon node, a light client has several advantages and disadv
| Head delay | 4/3 slot (15 s) | **None** |
| Security | Light | **Full** |
Light clients delegate full validation to other network participants and operate under a honest supermajority (> 2/3) assumption among elected participants. Due to this delegation, light clients are typically behind by ~4/3 slots (~15 seconds on Ethereum mainnet).
Light clients delegate full validation to other network participants and operate under a honest supermajority (> 2/3) assumption among elected participants.
Due to this delegation, light clients are typically behind by ~4/3 slots (~15 seconds on Ethereum mainnet).
!!! note
If you are validating, you must run a full beacon node. To use Nimbus, follow the [installation instructions](./install.md).
If you are validating, you must run a full beacon node.
To use Nimbus, follow the [installation instructions](./install.md).
## Building from source
@ -46,24 +49,29 @@ make -j4 nimbus_light_client
!!! tip
Omit `-j4` on systems with 4GB of memory or less.
This may take a few minutes. When the process finishes, the `nimbus_light_client` executable can be found in the `build` subdirectory.
This may take a few minutes.
When the process finishes, the `nimbus_light_client` executable can be found in the `build` subdirectory.
## Pairing with the EL client
To ensure that only the light client can control the EL client, a file with random content (JWT secret) must be created. The format is 64 hexadecimal (0-9, a-f) characters. To create one, the following command may be used:
To ensure that only the light client can control the EL client, a file with random content (JWT secret) must be created.
The format is 64 hexadecimal (0-9, a-f) characters.
To create one, the following command may be used:
```sh
openssl rand -hex 32 | tr -d "\n" > "$HOME/jwtsecret"
```
!!! tip
To adjust where the file is created, adjust the `$HOME/jwtsecret` portion in the command above. Also adjust other commands in this guide accordingly.
To adjust where the file is created, adjust the `$HOME/jwtsecret` portion in the command above.
Also adjust other commands in this guide accordingly.
The JWT secret must be passed to both the EL client and the light client to complete the pairing.
## Running the EL client
In addition to the [regular instructions](./eth1.md) to run an EL client, the JWT secret must be configured. The following sections explain how to do this for certain EL clients.
In addition to the [regular instructions](./eth1.md) to run an EL client, the JWT secret must be configured.
The following sections explain how to do this for certain EL clients.
=== "Geth"
@ -95,9 +103,10 @@ In addition to the [regular instructions](./eth1.md) to run an EL client, the JW
## Running the light client
The light client starts syncing from a trusted block. This trusted block should be somewhat recent ([~1-2 weeks](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/weak-subjectivity.md)) and needs to be configured each time when starting the light client.
The light client starts syncing from a trusted block.
This trusted block should be somewhat recent ([~1-2 weeks](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/weak-subjectivity.md)) and needs to be configured each time when starting the light client.
1. Obtaining a trusted block root
### 1. Obtaining a trusted block root
A block root may be obtained from another trusted beacon node, or from a trusted provider.
@ -110,12 +119,17 @@ A block root may be obtained from another trusted beacon node, or from a trusted
```
=== "Beaconcha.in"
On the [beaconcha.in](https://beaconcha.in) website ([Goerli](https://prater.beaconcha.in)), navigate to the `Epochs` section and select a recent `Finalized` epoch. Then, scroll down to the bottom of the page. If the bottom-most slot has a `Proposed` status, copy its `Root Hash`. Otherwise, for example if the bottom-most slot was `Missed`, go back and pick a different epoch.
On the [beaconcha.in](https://beaconcha.in) website ([Goerli](https://prater.beaconcha.in)), navigate to the `Epochs` section and select a recent `Finalized` epoch.
Then, scroll down to the bottom of the page.
If the bottom-most slot has a `Proposed` status, copy its `Root Hash`.
Otherwise, for example if the bottom-most slot was `Missed`, go back and pick a different epoch.
!!! warning
Selecting a block root from an untrusted source or using an outdated block root may lead to the light client syncing to an unexpected state. If that happens, stop the light client and restart it with a new trusted block root. Depending on the EL client, its database must be deleted and sync restarted from scratch.
Selecting a block root from an untrusted source or using an outdated block root may lead to the light client syncing to an unexpected state.
If that happens, stop the light client and restart it with a new trusted block root.
Depending on the EL client, its database must be deleted and sync restarted from scratch.
2. Starting the light client
### 2. Starting the light client
To start the light client, run the following commands (inserting your own trusted block root):
@ -136,11 +150,13 @@ To start the light client, run the following commands (inserting your own truste
```
!!! tip
The light client can be left running in the background. Note that a new trusted block root is required when restarting.
The light client can be left running in the background.
Note that a new trusted block root is required when restarting.
## Observing the sync process
After a while, the light client will pick up beacon block headers from the Ethereum network and start informing the EL client about the latest data. You should see logs similar to the following:
After a while, the light client will pick up beacon block headers from the Ethereum network and start informing the EL client about the latest data.
You should see logs similar to the following:
### Nimbus
@ -172,7 +188,9 @@ NOT 2022-11-21 18:04:03.982+01:00 New LC optimistic block opt
```
!!! note
The [light client protocol](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.5/specs/altair/light-client/sync-protocol.md) depends on consensus layer (CL) full nodes to serve additional data. As this is a new protocol, not all implementations are supporting it yet. Therefore, it may take several minutes to discover supporting peers, during which no log messages may be produced.
The [light client protocol](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.5/specs/altair/light-client/sync-protocol.md) depends on consensus layer (CL) full nodes to serve additional data.
As this is a new protocol, not all implementations are supporting it yet.
Therefore, it may take several minutes to discover supporting peers, during which no log messages may be produced.
=== "Geth"

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

@ -5,7 +5,8 @@ In order to perform validation duties, you need to also be running an execution
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. Sharing the same execution client between multiple beacon nodes is not supported.
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
Syncing an execution client may take hours or even days, depending on your hardware!
@ -18,7 +19,8 @@ Select an execution client and install it, configuring it such that that the aut
=== "Nimbus"
In parallel to `nimbus-eth2`, we are working hard on the [Nimbus execution client](https://github.com/status-im/nimbus-eth1). While this is very much a project in development (i.e. not yet ready for public consumption), we welcome you to experiment with it.
In parallel to `nimbus-eth2`, we are working hard on the [Nimbus execution client](https://github.com/status-im/nimbus-eth1).
While this is very much a project in development (i.e. not yet ready for public consumption), we welcome you to experiment with it.
=== "Geth"
@ -60,7 +62,9 @@ Select an execution client and install it, configuring it such that that the aut
### 2. Leave the execution client running
The execution client needs to be running at all times in order for the beacon node to be able to support validators. 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.
The execution client needs to be running at all times in order for the beacon node to be able to support validators.
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.
@ -69,9 +73,12 @@ It is safe to start the beacon node even if the execution client is not yet full
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`. When the `--el` option is not explicitly specified, Nimbus will assume that the execution client is running on the same machine with such default settings.
By default, the execution client accepts connections on the localhost interface (`127.0.0.1`), with default authenticated RPC port `8551`.
When the `--el` option is not explicitly specified, Nimbus will assume that the execution client is running on the same machine with such default settings.
Once started, the execution client will create a file containing a JWT secret token. The token file is needed for Nimbus to authenticate itself with the execution client and perform trusted operations. You will need to pass the path to the token file to Nimbus together with the web3 URL.
Once started, the execution client will create a file containing a JWT secret token.
The token file is needed for Nimbus to authenticate itself with the execution client and perform trusted operations.
You will need to pass the path to the token file to Nimbus together with the web3 URL.
=== "Mainnet"
```sh
@ -88,13 +95,15 @@ Once started, the execution client will create a file containing a JWT secret to
```
!!! info
When the `--jwt-secret` option is not specified and the execution client is running on the same machine under default setting, Nimbus may be able to connect successfully to it by using the default secret value `0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3`. This is a [proposed standard protocol](https://github.com/ethereum/execution-apis/pull/302) that aims to simplify the required user configuration, but it's not yet adopted by all execution clients.
When the `--jwt-secret` option is not specified and the execution client is running on the same machine under default setting, Nimbus may be able to connect successfully to it by using the default secret value `0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3`.
This is a [proposed standard protocol](https://github.com/ethereum/execution-apis/pull/302) that aims to simplify the required user configuration, but it's not yet adopted by all execution clients.
## Advanced setups
### Running multiple execution clients
You can increase the resilience of your setup and eliminate any downtime during upgrade procedure of the execution client software by allowing your beacon node to manage multiple execution clients. To enable this mode, just specify multiple URLs through the `--el` option when starting your beacon node:
You can increase the resilience of your setup and eliminate any downtime during upgrade procedure of the execution client software by allowing your beacon node to manage multiple execution clients.
To enable this mode, just specify multiple URLs through the `--el` option when starting your beacon node:
```sh
./run-mainnet-beacon-node.sh \
@ -104,7 +113,8 @@ You can increase the resilience of your setup and eliminate any downtime during
```
!!! 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.html#configuration-files), you can also use the following more natural syntax:
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:
```toml
data-dir = "my-data-dir"

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

@ -7,9 +7,10 @@
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).
Its efficiency and low resource consumption allows it to perform well on all kinds of systems, ranging from Raspberry Pi's and mobile devices where it contributes to low power consumption and security -- to powerful servers where it leaves resources free to perform other tasks, such as running an [execution node](./eth1.md).
Its efficiency and low resource consumption allows it to perform well on all kinds of systems: ranging from Raspberry Pi's and mobile devices — where it contributes to low power consumption and security — to powerful servers where it leaves resources free to perform other tasks, such as running an [execution node](./eth1.md).
This book describes the consensus layer client, [`nimbus-eth2`](https://github.com/status-im/nimbus-eth2). A execution client, [nimbus-eth1](https://github.com/status-im/nimbus-eth2), is also under development.
This book describes the consensus layer client, [`nimbus-eth2`](https://github.com/status-im/nimbus-eth2).
An execution client, [nimbus-eth1](https://github.com/status-im/nimbus-eth2), is also under development.
## Feature highlights
@ -38,4 +39,6 @@ Subscribe to our newsletter [here](https://subscribe.nimbus.guide/).
## Disclaimer
This documentation assumes Nimbus is in its ideal state. The project is still under active development. Please submit a [Github issue](https://github.com/status-im/nimbus-eth2/issues) if you come across a problem.
This documentation assumes Nimbus is in its ideal state.
The project is still under active development.
Please submit a [Github issue](https://github.com/status-im/nimbus-eth2/issues) if you come across a problem.

46
docs/the_nimbus_book/src/metrics-pretty-pictures.md
View File

@ -2,9 +2,12 @@
In this page we'll cover how to use Grafana and Prometheus to help you visualise important real-time metrics concerning your validator and/or beacon node.
Prometheus is an open-source systems monitoring and alerting toolkit. It runs as a service on your computer and its job is to capture metrics. You can find more information about Prometheus [here](https://prometheus.io/docs/introduction/overview/).
Prometheus is an open-source systems monitoring and alerting toolkit.
It runs as a service on your computer and its job is to capture metrics.
You can find more information about Prometheus [here](https://prometheus.io/docs/introduction/overview/).
Grafana is a tool for beautiful dashboard monitoring that works well with Prometheus. You can learn more about Grafana [here](https://github.com/grafana/grafana).
Grafana is a tool for beautiful dashboard monitoring that works well with Prometheus.
You can learn more about Grafana [here](https://github.com/grafana/grafana).
## Simple metrics
@ -14,7 +17,8 @@ To enable the metrics server, run the beacon node with the `--metrics` flag:
./run-prater-beacon-node.sh --metrics
```
Visit [http://127.0.0.1:8008/metrics](http://127.0.0.1:8008/metrics) with a browser or `curl`. You should see a plaintext page that looks something like this:
Visit [http://127.0.0.1:8008/metrics](http://127.0.0.1:8008/metrics) with a browser or `curl`.
You should see a plaintext page that looks something like this:
```
# HELP nim_runtime_info Nim runtime info
@ -35,9 +39,12 @@ nim_gc_heap_instance_occupied_bytes{type_name="seq[TrustedAttestation]"} 29728.0
...
```
> **Note:** Metrics are by default only accessible from the same machine as the beacon node is running on - to fetch metrics from a remote machine, an SSH tunnel is recommended.
!!! note
Metrics are by default only accessible from the same machine as the beacon node is running on.
To fetch metrics from a remote machine, an SSH tunnel is recommended.
The metrics server offers one snapshot in time of the state of the beacon node -- metrics however are at their most useful when collected over time -- for this, we'll need to set up two more pieces of software -- Prometheus and Grafana.
The metrics server offers one snapshot in time of the state of the beacon node.
Metrics, however, are at their most useful when collected over time — for this, we'll need to set up two more pieces of software: Prometheus and Grafana.
## Prometheus and Grafana
@ -47,7 +54,7 @@ The following steps will take you through how to use Prometheus and Grafana to s
#### 1. Download Prometheus
Use your favourite package manager to download Prometheus -- for example `apt-get install prometheus` on Ubuntu, or `brew install prometheus` on MacOS, should do the trick.
Use your favourite package manager to download Prometheus: for example `apt-get install prometheus` on Ubuntu, or `brew install prometheus` on MacOS, should do the trick.
> If you don't use a package manager, you can download the [latest release](https://prometheus.io/download/) of directly from Prometheus website. To extract it, run:
>
@ -59,7 +66,8 @@ Use your favourite package manager to download Prometheus -- for example `apt-ge
#### 2. Copy the binary
The Prometheus server is a single binary called prometheus (or prometheus.exe on Microsoft Windows). Copy it over to [`/usr/local/bin`](https://unix.stackexchange.com/questions/4186/what-is-usr-local-bin)
The Prometheus server is a single binary called prometheus (or prometheus.exe on Microsoft Windows).
Copy it over to [`/usr/local/bin`](https://unix.stackexchange.com/questions/4186/what-is-usr-local-bin):
```
cp prometheus-2.20.1.linux-amd64/prometheus /usr/local/bin/
@ -98,9 +106,11 @@ level=info ts=2021-01-22T14:52:10.604Z caller=main.go:673 msg="Server is ready t
#### 4. Download Grafana
[Download the latest release]((https://grafana.com/grafana/download?platform=linux)) of Grafana for your platform. You need version 7.2 or newer.
[Download the latest release]((https://grafana.com/grafana/download?platform=linux)) of Grafana for your platform.
You need version 7.2 or newer.
>**Note:** If you use a package manager, you can also download Grafana that way -- for example `apt-get install grafana` on Ubuntu, or `brew install grafana` on MacOS, should do the trick.
!!! note
If you use a package manager, you can also download Grafana that way -- for example `apt-get install grafana` on Ubuntu, or `brew install grafana` on MacOS, should do the trick.
#### 5. Install and start Grafana
@ -108,12 +118,13 @@ Follow [the instructions for your platform](https://grafana.com/docs/grafana/lat
#### 6. Configure login
Go to [http://localhost:3000/](http://localhost:3000/), you should see a Grafana login screen that looks like this
Go to [http://localhost:3000/](http://localhost:3000/), you should see a Grafana login screen that looks like this:
![](https://i.imgur.com/jcP1qWl.png)
Type in `admin` for both the username and password. You'll be asked to change the password (we recommend you do so).
Type in `admin` for both the username and password.
You'll be asked to change the password (and we recommend you do so).
#### 7. Add a data source
@ -134,7 +145,7 @@ Enter `http://localhost:9090` in the URL field
![](https://i.imgur.com/PtVOnur.png)
Set the "Scrape interval" field to the same value you used in the Prometheus config ("12" in our example above).
Set the "Scrape interval" field to the same value you used in the Prometheus config ("15s" in our example below).
Scroll to the bottom and click on `Save and Test`
@ -163,10 +174,13 @@ You'll be directed to the dashboard where you'll be able to gain insights into t
![](https://i.imgur.com/aIfJ1iT.png)
> **Note:** the dashboard is very much a work in progress. Some of the highlights right now include received and proposed blocks, received and sent attestations, peers, memory and cpu usage stats. But keep an eye out for additional metrics in the near future.
!!! note
The dashboard is very much a work in progress.
Some of the highlights right now include received and proposed blocks, received and sent attestations, peers, memory and cpu usage stats.
But keep an eye out for additional metrics in the near future.
And voila! That's all there is to it :)
And voilà! That's all there is to it :)
## Community dashboards
@ -175,13 +189,13 @@ And voila! That's all there is to it :)
![](https://i.imgur.com/05eJeBr.png)
Joe – who’s done some brilliant work [integrating Nimbus with Rocket Pool](https://our.status.im/rocket-pool-integration/) – has created a [wonderful guide](https://github.com/jclapis/rp-pi-guide/blob/main/Grafana.md) where he takes you through how to set up a Grafana server on your Pi – using his dashboard as an example.
Joe — who’s done some brilliant work [integrating Nimbus with Rocket Pool](https://our.status.im/rocket-pool-integration/) — has created a [wonderful guide](https://github.com/jclapis/rp-pi-guide/blob/main/Grafana.md) where he takes you through how to set up a Grafana server on your Pi, using his dashboard as an example.
In his words:
> This captures just about every metric I think I’d like to see at a glance.
Whether or not you're running a Pi, we recommend you check out his guide [here]( https://github.com/jclapis/rp-pi-guide/blob/main/Grafana.md).
Whether or not you're running a Pi, we recommend you check out [his guide]( https://github.com/jclapis/rp-pi-guide/blob/main/Grafana.md).
### Metanull

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

@ -1,14 +1,20 @@
# Migrate from another client
This guide will take you through the basics of how to migrate to Nimbus from another client. *See [here](./migration-options.md) for advanced options*.
This guide will take you through the basics of how to migrate to Nimbus from another client.
See [here](./migration-options.md) for advanced options.
**Please take your time to get this right.** Don't hesitate to reach out to us in the `#helpdesk` channel of [our discord](https://discord.gg/j3nYBUeEad) if you come across a stumbling block. We are more than happy to help guide you through the migration process. Given what's at stake, there is no such thing as a stupid question.
**Please take your time to get this right.**
Don't hesitate to reach out to us in the `#helpdesk` channel of [our discord](https://discord.gg/j3nYBUeEad) if you come across a stumbling block.
We are more than happy to help guide you through the migration process.
Given what's at stake, there is no such thing as a stupid question.
!!! info ""
Unlike other clients, Nimbus does not require a separate validator client - instead, validators run in the beacon node process.
Unlike other clients, Nimbus does not require a separate validator client.
Instead, validators run in the beacon node process.
!!! warning
**The most important takeaway is that you ensure that two clients will never validate with the same keys at the same time.** In other words, you must ensure that your original client is stopped, and no longer validating, before importing your keys into Nimbus.
**The most important takeaway is that you ensure that two clients will never validate with the same keys at the same time.**
In other words, you must ensure that your original client is stopped, and no longer validating, before importing your keys into Nimbus.
## Steps
@ -28,7 +34,7 @@ Once your Nimbus beacon node has synced and you're satisfied that it's working,
```
Look for an `"is_syncing":false` in the response to confirm that your node has synced.
### Step 2 - Stop your existing client and export your slashing protection history
### 2. Stop your existing client and export your slashing protection history
As part of the migration process, you need to stop your existing client and export its [slashing protection database](https://eips.ethereum.org/EIPS/eip-3076).
@ -45,7 +51,7 @@ As part of the migration process, you need to stop your existing client and expo
sudo systemctl disable prysmvalidator.service
```
It's important that you disable the Prysm validator as well as stopping it, to prevent it from starting up again on reboot.
It is important that you disable the Prysm validator as well as stopping it, to prevent it from starting up again on reboot.
#### 2. Export slashing protection history
@ -60,7 +66,8 @@ As part of the migration process, you need to stop your existing client and expo
You will then find the `slashing-protection.json` file in your specified `/path/to/export_dir` folder.
!!! tip
To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check its recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check its recent history on [beaconcha.in](https://beaconcha.in/)).
Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
=== "Lighthouse"
@ -82,7 +89,7 @@ As part of the migration process, you need to stop your existing client and expo
sudo systemctl disable lighthousebeacon
```
*It's important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.*
It is important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.
#### 2. Export slashing protection history
@ -95,7 +102,8 @@ As part of the migration process, you need to stop your existing client and expo
This will export your history in the correct format to `slashing-protection.json`.
!!! tip
To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check its recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check its recent history on [beaconcha.in](https://beaconcha.in/)).
Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
=== "Teku"
@ -108,7 +116,7 @@ As part of the migration process, you need to stop your existing client and expo
sudo systemctl disable teku
```
*It's important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.*
It is important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.
#### 2. Export slashing protection history
@ -125,7 +133,8 @@ As part of the migration process, you need to stop your existing client and expo
- `--to` specifies the file to export the slashing-protection data to (in this case `/home/slash/slashing-protection.json`).
!!! tip
To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check its recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check its recent history on [beaconcha.in](https://beaconcha.in/)).
Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
=== "Nimbus"
@ -140,7 +149,7 @@ As part of the migration process, you need to stop your existing client and expo
sudo systemctl disable nimbus-eth2-mainnet.service
```
*It's important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.*
It is important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.
#### 2. Export slashing protection history
@ -152,16 +161,20 @@ As part of the migration process, you need to stop your existing client and expo
This will export your history in the correct format to `slashing-protection.json`.
> **Tip:** To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check its recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
!!! tip
To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check its recent history on [beaconcha.in](https://beaconcha.in/)).
Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
### 3. Import your validator key(s) into Nimbus
To import your validator key(s), follow the instructions [outlined here](./keys.md).
!!! tip
To check that your key(s) has been successfully imported, look for a file named after your public key in `build/data/shared_mainet_0/secrets/`.
If you run into an error at this stage, it's probably because the wrong permissions have been set on either a folder or file. See [here](faq.md#folder-permissions) for how to fix this.
If you run into an error at this stage, it's probably because the wrong permissions have been set on either a folder or file.
See [here](faq.md#folder-permissions) for how to fix this.
### 4. Import your slashing protection history
@ -184,7 +197,8 @@ For a quick guide on how to set up a systemd service, see [here](./beacon-node-s
## Final thoughts
If you are unsure of the safety of a step, please get in touch with us directly on [discord](https://discord.gg/nnNEBvHu3m). Additionally, we recommend testing the migration works correctly on a testnet before going ahead on mainnet.
If you are unsure of the safety of a step, please get in touch with us directly on [discord](https://discord.gg/nnNEBvHu3m).
Additionally, we recommend testing the migration works correctly on a testnet before going ahead on mainnet.

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

@ -2,9 +2,9 @@
One of our most important design goals is an application architecture that makes it **simple to embed Nimbus into other software.**
Another is to **minimize reliance on third-party software.**
Another goal is to **minimize reliance on third-party software.**
A third is for the application binary to be as **lightweight as possible in terms of resources used.**
A third one is for the application binary to be as **lightweight as possible in terms of resources used.**
### Integration with Status

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

@ -8,7 +8,8 @@
This page will take you through how to use your laptop to program your Raspberry Pi.
One of the most important aspects of the Raspberry Pi experience is trying to make it as easy as possible to get started. As such, we try our best to explain things from first-principles.
One of the most important aspects of the Raspberry Pi experience is trying to make it as easy as possible to get started.
As such, we try our best to explain things from first-principles.
## Prerequisites
@ -16,21 +17,24 @@ One of the most important aspects of the Raspberry Pi experience is trying to ma
- 64GB microSD Card
- microSD USB adapter
- 5V 3A USB-C charger
- Reliable Wifi connection
- Reliable Wi-Fi connection
- Laptop
- Basic understanding of the [command line](https://www.learnenough.com/command-line-tutorial/basics)
- 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. For example, [Ethereum on Arm](https://twitter.com/EthereumOnARM) use an Inateck 2.5 Hard Drive Enclosure FE2011. Make sure to buy a case with an UASP compliant chip, particularly, one of these: JMicron (JMS567 or JMS578) or ASMedia (ASM1153E).
2. Use an USB 3.0 External Hard Drive Case with a SSD Disk.
For example, [Ethereum on Arm](https://twitter.com/EthereumOnARM) use an Inateck 2.5 Hard Drive Enclosure FE2011.
Make sure to buy a case with an UASP compliant chip, particularly, one of these: JMicron (JMS567 or JMS578) or ASMedia (ASM1153E).
In both cases, avoid low quality SSD disks (the SSD is a key component of your node and can drastically affect both the performance and sync time). Keep in mind that you need to plug the disk to an USB 3.0 port (the blue port).
In both cases, avoid low quality SSD disks (the SSD is a key component of your node and can drastically affect both the performance and sync time).
Keep in mind that you need to plug the disk to an USB 3.0 port (the blue port).
!!! note
If you have a Raspberry Pi 4 and are getting bad speeds transferring data to/from USB3.0 SSDs, please [read this recommended fix.](https://www.raspberrypi.org/forums/viewtopic.php?t=245931#p1501426)
If you have a Raspberry Pi 4 and are getting bad speeds transferring data to/from USB3.0 SSDs, please [read this recommended fix](https://www.raspberrypi.org/forums/viewtopic.php?t=245931#p1501426).
## Steps
@ -64,7 +68,8 @@ Find the OS you downloaded in step 2
### 4b. Write to SD card
Click on **CHOOSE SD CARD**. You should see a menu pop-up with your SD card listed -- Select it
Click on **CHOOSE SD CARD**.
You should see a menu pop-up with your SD card listed -- Select it
![](https://storage.googleapis.com/ethereum-hackmd/upload_f90713c1ef782a94b5fce9eb8249c206.png)
@ -80,7 +85,8 @@ Make a cup of coffee :)
### 5. Set up wireless LAN
Since you have loaded Raspberry Pi OS onto a blank SD card, you will have two partitions. The first one, which is the smaller one, is the `boot` partition.
Since you have loaded Raspberry Pi OS onto a blank SD card, you will have two partitions.
The first one, which is the smaller one, is the `boot` partition.
Create a `wpa_supplicant` configuration file in the `boot` partition with the following content:
@ -98,7 +104,8 @@ network={
```
!!! note
Don't forget to replace the placeholder `country`, `ssid`, and `psk` values. See [Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1) for a list of 2 letter `ISO 3166-1` country codes.
Don't forget to replace the placeholder `country`, `ssid`, and `psk` values.
See [Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1) for a list of 2 letter `ISO 3166-1` country codes.
### 6. Enable SSH (using Linux or macOS)
@ -106,7 +113,9 @@ You can [access the command line](https://www.raspberrypi.org/documentation/remo
While SSH is not enabled by default, you can enable it by placing a file named `ssh`, without any extension, onto the boot partition of the SD card.
When the Pi boots, it will look for the `ssh` file. If it is found, SSH is enabled and the file is deleted. The content of the file does not matter; it can contain text, or nothing at all.
When the Pi boots, it will look for the `ssh` file.
If it is found, SSH is enabled and the file is deleted.
The content of the file does not matter; it can contain text, or nothing at all.
To create an empty `ssh` file, from the home directory of the `boot` partition file, run:
@ -134,7 +143,8 @@ PING raspberrypi.local (195.177.101.93): 56 data bytes
...
```
Keep note of your Pi's IP address. In the above case, that's `195.177.101.93`
Keep note of your Pi's IP address.
In the above case, that's `195.177.101.93`
### 8. SSH (using Linux or macOS)
@ -178,7 +188,8 @@ pi@raspberrypi:~ $
The first step is to increase the [swap size](https://itsfoss.com/swap-size/) to 2GB (2048MB).
!!! note
Swap acts as a breather to your system when the RAM is exhausted. When the RAM is exhausted, your Linux system uses part of the hard disk memory and allocates it to the running application.
Swap acts as a breather to your system when the RAM is exhausted.
When the RAM is exhausted, your Linux system uses part of the hard disk memory and allocates it to the running application.
Use the Pi's built-in text editor [nano](https://www.nano-editor.org/dist/latest/cheatsheet.html) to open up the swap file:
@ -212,7 +223,8 @@ Reboot your Pi to have the above changes take effect:
sudo reboot
```
This will cause your connection to close. So you'll need to `ssh` into your Pi again:
This will cause your connection to close.
So you'll need to `ssh` into your Pi again:
```sh
ssh pi@195.177.101.93
@ -266,7 +278,8 @@ Now you can find the software in the nimbus-eth2 directory.
!!! note
If you haven't generated your validator key(s) and/or made your deposit yet, follow the instructions on [this page](./deposit.md) before carrying on.
We'll use the `scp` command to send files over SSH. It allows you to copy files between computers, say from your Raspberry Pi to your desktop/laptop, or vice-versa.
We'll use the `scp` command to send files over SSH.
It allows you to copy files between computers, say from your Raspberry Pi to your desktop/laptop, or vice-versa.
Copy the folder containing your validator key(s) from your computer to your `pi`'s homefolder by opening up a new terminal window and running the following command:
@ -292,7 +305,9 @@ To import your signing key into Nimbus, from the `nimbus-eth2` directory run:
build/nimbus_beacon_node deposits import --data-dir=build/data/shared_prater_0 ../validator_keys
```
You'll be asked to enter the password you created to encrypt your keystore(s). Don't worry, this is entirely normal. Your validator client needs both your signing keystore(s) and the password encrypting it to import your [key](https://blog.ethereum.org/2020/05/21/keys/) (since it needs to decrypt the keystore in order to be able to use it to sign on your behalf).
You'll be asked to enter the password you created to encrypt your keystore(s).
Don't worry, this is entirely normal.
Your validator client needs both your signing keystore(s) and the password encrypting it to import your [key](https://blog.ethereum.org/2020/05/21/keys/) (since it needs to decrypt the keystore in order to be able to use it to sign on your behalf).
### 14. Connect to Prater
@ -300,7 +315,8 @@ build/nimbus_beacon_node deposits import --data-dir=build/data/shared_prater_0
We're finally ready to connect to the Prater testnet!
!!! note
If you haven't already, we recommend registering for, and running, your own eth1 node in parallel. For instructions on how to do so, see [this page](./eth1.md).
If you haven't already, we recommend registering for, and running, your own eth1 node in parallel.
For instructions on how to do so, see [this page](./eth1.md).
To connect to Prater, run:
```
@ -327,7 +343,8 @@ INF 2020-12-01 11:26:31.000+00:00 Slot start top
INF 2020-12-01 11:26:36.285+00:00 Slot end topics="beacnde" tid=21815 file=nimbus_beacon_node.nim:593 slot=96567 nextSlot=96568 head=b54486c4:96563 headEpoch=3017 finalizedHead=2f5d12e4:96479 finalizedEpoch=3014
```
To keep track of your syncing progress, have a look at the output at the very bottom of the terminal window in which your validator is running. You should see something like:
To keep track of your syncing progress, have a look at the output at the very bottom of the terminal window in which your validator is running.
You should see something like:
```
peers: 15 ❯ finalized: ada7228a:8765 ❯ head: b2fe11cd:8767:2 ❯ time: 9900:7 (316807) ❯ sync: wPwwwwwDwwDPwPPPwwww:7:1.2313:1.0627:12h01m(280512)
@ -335,12 +352,16 @@ peers: 15 ❯ finalized: ada7228a:8765 ❯ head: b2fe11cd:8767:2 ❯ time: 9900:
Keep an eye on the number of peers you're currently connected to (in the above case that's `15`), as well as your [sync progress](./keep-an-eye.md#syncing-progress).
> **Note:** 15 - 20 peers and an average sync speed of **0.5 - 1.0** blocks per second is normal on `Prater` with a Pi. If your sync speed is much slower than this, the root of the problem may be your USB3.0 to SSD adapter. See [this post](https://www.raspberrypi.org/forums/viewtopic.php?f=28&t=245931) for a recommended workaround.
!!! note
15 - 20 peers and an average sync speed of **0.5 - 1.0** blocks per second is normal on `Prater` with a Pi.
If your sync speed is much slower than this, the root of the problem may be your USB3.0 to SSD adapter.
See [this post](https://www.raspberrypi.org/forums/viewtopic.php?f=28&t=245931) for a recommended workaround.
## Mainnet advice
Whether or not your Pi is up to the task will depend on a number of factors such as SSD speed, network connectivity, etc. As such, it's best to verify performance on a testnet first.
Whether or not your Pi is up to the task will depend on a number of factors such as SSD speed, network connectivity, etc.
As such, it's best to verify performance on a testnet first.
The best thing you can do is to set your Pi to run Prater. **If you have no trouble syncing and attesting on Prater, your setup should be more than good enough for mainnet** as well (Mainnet is expected to use fewer resources).
@ -364,5 +385,6 @@ For the details on how to do this, see [this page](./beacon-node-systemd.md).
While you shouldn't need to, if you're feeling adventurous and want to try and squeeze out some extra performance out of your Pi's CPU, see [this guide](https://docs.rocketpool.net/guides/node/local/prepare-pi.html#overclocking-the-pi) by Joe Clapis.
!!! note
We have since improved performance in several ways which should make a vanilla Pi perform well. However, overclocking may still give some benefits, in particular you have more performance to deal with anomalies (like spamming etc).
We have since improved performance in several ways which should make a vanilla Pi perform well.
However, overclocking may still give some benefits, in particular you have more performance to deal with anomalies (like spamming etc).

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

@ -2,13 +2,13 @@
This page takes you through the steps of getting a standard installation of the Nimbus beacon node running.
The quickstart setup involves running two nodes: an [execution client](./eth1.md) and a beacon node - both are needed to run a full Ethereum setup.
The quickstart setup involves running two nodes: an [execution client](./eth1.md) and a beacon node — both are needed to run a full Ethereum setup.
The beacon node connects to the beacon chain network, syncs historical data and provides [API's](./rest-api.md) to monitor and interact with the beacon chain.
The beacon node connects to the beacon chain network, syncs historical data, and provides [API's](./rest-api.md) to monitor and interact with the beacon chain.
Running a beacon node is a [worthwhile endeavor](https://vitalik.ca/general/2021/05/23/scaling.html#its-crucial-for-blockchain-decentralization-for-regular-users-to-be-able-to-run-a-node) even if you are not planning on validating yourself!
The guide assumes [Ubuntu Linux](https://ubuntu.com/download/server) is being used, and therefore some familiarity with [the linux command line](https://ubuntu.com/tutorials/command-line-for-beginners) is needed.
The guide assumes [Ubuntu Linux](https://ubuntu.com/download/server) is being used, and therefore some familiarity with [the Linux command line](https://ubuntu.com/tutorials/command-line-for-beginners) is needed.
!!! note
To become a validator, you first need to set up a beacon node.
@ -24,13 +24,15 @@ Prepare your machine by installing [Nimbus' dependencies](./install.md).
### 2. Set up an execution client
To run a beacon node, you need to have access to an execution client exposing the web3 API - throughout, we'll assume an execution client is running on the same machine as the beacon node, but this is not required.
To run a beacon node, you need to have access to an execution client exposing the web3 API.
Throughout, we'll assume an execution client is running on the same machine as the beacon node, but this is not required.
See the [execution client](./eth1.md) guide for instructions on how to pick and install an execution client!
See the [execution client guide](./eth1.md) for instructions on how to pick and install an execution client!
### 3. Install Nimbus
Next, download the [latest release](./binaries.md) and install it by unpacking the archive. Using a command line terminal:
Next, download the [latest release](./binaries.md) and install it by unpacking the archive.
Using a command line terminal:
```sh
# Create a directory that can hold the beacon chain data and applications - this should be a fast SSD
@ -80,6 +82,6 @@ Congratulations! Your beacon node is up and running, and syncing the network!
!!! success "What next?"
* If you will be running the node on a regular basis, it is recommended you set up a [systemd service](./beacon-node-systemd.md) that automatically restarts your node if the computer reboots.
* If you will be running the node on a regular basis, it is recommended that you [set up a systemd service](./beacon-node-systemd.md) that automatically restarts your node if the computer reboots.
* If you wish to stake, continue your journey by following the [validator quick start](./run-a-validator.md).
* The [monitoring](./health.md) page contains information about how to keep your node healthy
* The [monitoring](./health.md) page contains information about how to keep your node healthy.

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

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