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

book edits (#3955) 

* reorganise navigation menus
* update light client guide with comparison table
* add suggested fee recipient and JWT secrets to the merge guide
* add some background info to book readme
* add JWT docs

also limit toc to make it displayable with substeps.
This commit is contained in:
Jacek Sieka 2022-08-13 20:17:20 +02:00 committed by GitHub
parent 052f9edfd4
commit 4adf849d09
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
22 changed files with 299 additions and 491 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/README.md
View File

@ -1,6 +1,12 @@
The books in this folder were produced using [mdBook](https://github.com/rust-lang/mdBook) - see installation guide.
# Documentation
Some books also use [mdbook-toc](https://github.com/badboy/mdbook-toc) for tables of contents.
## material for mkdocs
The Nimbus guide is generated using [Material for mkdocs](https://squidfunk.github.io/mkdocs-material/), and installed using a python VENV (see Makefile).
## mdbook
Some books in this folder were produced using [mdBook](https://github.com/rust-lang/mdBook) - see installation guide.
```bash
# Install or update tooling (make sure you add "~/.cargo/bin" to PATH):

15
docs/the_nimbus_book/README.md Normal file
View File

@ -0,0 +1,15 @@
The Nimbus Guide is written using markdown and [material for mkdocs](https://squidfunk.github.io/mkdocs-material/).
See the `Makefile` for setup.
The guide is divided into several sections - broadly:
* Guides - walk-throughs that allow the user to get started with a specific area of the client
* How-to:s - short pages that show the user how to solve a specific problem or perform a specific task
* Reference - pages describing how specific parts of Nimbus work, reference-style
* "Other" - explanations of concepts, background etc.
## Resources
* [material for mkdocs](https://squidfunk.github.io/mkdocs-material/) - doc generator
* [divio](https://documentation.divio.com/introduction/) - useful resource diving into the above section structure

42
docs/the_nimbus_book/mkdocs.yml
View File

@ -32,22 +32,23 @@ markdown_extensions:
- pymdownx.tabbed:
alternate_style: true
- tables
- toc:
toc_depth: 3
nav:
- About:
- 'philosophy.md'
- 'hardware.md'
- 'preparation.md'
- 'index.md'
- 'merge.md'
- 'philosophy.md'
- 'preparation.md'
- Quickstart:
- Getting started:
- 'quick-start.md'
- 'run-a-validator.md'
- Downloads:
- 'binaries.md'
- 'docker.md'
- 'checksums.md'
- 'migration.md'
- 'metrics-pretty-pictures.md'
- 'pi-guide.md'
- 'el-light-client.md'
- How-to:
- Beacon node:
@ -55,7 +56,6 @@ nav:
- 'build.md'
- 'start-syncing.md'
- 'trusted-node-sync.md'
- 'networking.md'
- 'web3-backup.md'
- Validator:
@ -66,7 +66,6 @@ nav:
- 'suggested-fee-recipient.md'
- 'keep-an-eye.md'
- 'voluntary-exit.md'
- 'validator-monitor.md'
- 'more-keys.md'
- 'additional-validator.md'
- 'validator-client.md'
@ -74,10 +73,8 @@ nav:
- General:
- 'keep-updated.md'
- 'eth1.md'
- 'el-light-client.md'
- 'goerli-eth.md'
- 'beacon-node-systemd.md'
- 'logging.md'
- 'log-rotate.md'
- 'database-backup.md'
- 'email-notifications.md'
@ -85,20 +82,18 @@ nav:
- 'health.md'
- 'prater.md'
- Guides:
- 'migration.md'
- 'metrics-pretty-pictures.md'
- 'pi-guide.md'
- 'attestation-performance.md'
- 'infura-guide.md'
- Security:
- 'security_issues.md'
- 'audit.md'
- 'distribution_internals.md'
- Reference:
- 'hardware.md'
- 'options.md'
- 'networking.md'
- 'logging.md'
- 'validator-monitor.md'
- 'attestation-performance.md'
- 'rest-api.md'
- 'keymanager-api.md'
- 'data-dir.md'
@ -106,7 +101,12 @@ nav:
- 'light-client-data.md'
- 'troubleshooting.md'
- 'developers.md'
- 'contribute.md'
- 'resources.md'
- 'faq.md'
- 'api.md'
- 'contribute.md'
- Downloads:
- 'binaries.md'
- 'docker.md'
- 'checksums.md'

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

@ -1,4 +1,4 @@
# Analyze attestation performance
# Attestation performance analysis
`ncli_db validatorPerf` is an advanced tool that helps you analyze the performance of your validator over time.

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

@ -1,6 +1,4 @@
# Updating this book
Follow these steps to contribute to this book!
# Updating this guide
We use [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) to produce our documentation.

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

@ -16,7 +16,7 @@ To make a deposit, you will need to generate keys then submit a deposit transact
Start by downloading and unpacking the [deposit tool](https://github.com/ethereum/staking-deposit-cli/releases/latest) provided by the Ethereum Foundation:
```sh
# Enter the nimbus folder we previously created
# Enter the nimbus folder
cd nimbus-eth2
# Make sure to get the latest version from the download page

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

@ -1,11 +1,28 @@
# Light client based EL sync
# Run the light client
!!! warning
The light client is currently in BETA and details around running it may change.
The Nimbus Light Client is a light-weight alternative to running a full beacon node, when setting up an Ethereum execution client for read-only use cases after the merge.
Execution layer (EL) clients provide the [web3 API](https://ethereum.github.io/execution-apis/api-documentation/) to expose information stored on the Ethereum blockchain. With [the merge 🐼](./merge.md), EL clients can no longer run standalone and require an external component to determine the latest state to sync to.
!!! warning
It is recommended to pair the EL client with a consensus layer (CL) full node. To use Nimbus, follow the [installation instructions](./install.md).
## Comparison
In environments where running a full node is not feasible, a light client may be used instead. 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). On the other hand, light clients do not require storing a big database and need much less bandwith and compute power to stay in sync with the Ethereum network.
Compared to a full beacon node, a light client has several advantages and disadvantages.
| Feature | Light Client | Beacon Node |
| -- | -- | -- |
| Disk usage | **<1MB** | ~70GB |
| Bandwidth | **TBD (low)** | *TBD* |
| Sync time | **Seconds** | Days |
| 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).
!!! note
If you are validating, you must run a full beacon node. To use Nimbus, follow the [installation instructions](./install.md).
## Building from source
@ -48,33 +65,33 @@ The JWT secret must be passed to both the EL client and the light client to comp
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
=== "Geth"
=== "Mainnet"
```sh
geth --ws --authrpc.jwtsecret="$HOME/jwtsecret"
```
=== "Mainnet"
```sh
geth --ws --authrpc.jwtsecret="$HOME/jwtsecret"
```
=== "Goerli"
```sh
geth --goerli --ws --authrpc.jwtsecret="$HOME/jwtsecret"
```
=== "Goerli"
```sh
geth --goerli --ws --authrpc.jwtsecret="$HOME/jwtsecret"
```
### Nethermind
=== "Nethermind"
=== "Mainnet"
```sh
nethermind --JsonRpc.JwtSecretFile="$HOME/jwtsecret"
```
=== "Mainnet"
```sh
nethermind --JsonRpc.JwtSecretFile="$HOME/jwtsecret"
```
=== "Goerli"
```sh
nethermind --config goerli --JsonRpc.JwtSecretFile="$HOME/jwtsecret"
```
=== "Goerli"
```sh
nethermind --config goerli --JsonRpc.JwtSecretFile="$HOME/jwtsecret"
```
### Others
=== "Others"
Please consult your EL client's documentation for instructions on how to configure the JWT secret and running the EL client.
Please consult your EL client's documentation for instructions on how to configure the JWT secret and running the EL client.
## Running the light client
@ -147,21 +164,21 @@ NOT 2022-07-24 22:09:05.069+02:00 New LC optimistic block opt
!!! note
The [light client protocol](https://github.com/ethereum/consensus-specs/blob/dev/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
=== "Geth"
```
WARN [07-24|22:19:16.777] Ignoring payload with missing parent number=12,658,012 hash=306fad..bdfd44 parent=a22dc7..093bea
INFO [07-24|22:19:16.778] Forkchoice requested sync to new head number=12,658,012 hash=306fad..bdfd44
INFO [07-24|22:19:17.232] Syncing beacon headers downloaded=7168 left=12,650,843 eta=13m21.441s
INFO [07-24|22:19:21.626] Syncing beacon headers downloaded=75201 left=0 eta=0s
INFO [07-24|22:19:21.627] Block synchronisation started
```
```
WARN [07-24|22:19:16.777] Ignoring payload with missing parent number=12,658,012 hash=306fad..bdfd44 parent=a22dc7..093bea
INFO [07-24|22:19:16.778] Forkchoice requested sync to new head number=12,658,012 hash=306fad..bdfd44
INFO [07-24|22:19:17.232] Syncing beacon headers downloaded=7168 left=12,650,843 eta=13m21.441s
INFO [07-24|22:19:21.626] Syncing beacon headers downloaded=75201 left=0 eta=0s
INFO [07-24|22:19:21.627] Block synchronisation started
```
### Nethermind
=== "Nethermind"
```
2022-07-24 22:09:05.0853|Received a new payload: 12657968 (0xa5eedb4e4e4b0f84238464d563b82d7dddadfc68f21cfa2bfcbbbcdb944c4b63)
2022-07-24 22:09:05.1018|Insert block into cache without parent 12657968 (0xa5eedb...4c4b63)
2022-07-24 22:09:05.1141|Received: ForkchoiceState: (HeadBlockHash: 0xa5eedb4e4e4b0f84238464d563b82d7dddadfc68f21cfa2bfcbbbcdb944c4b63, SafeBlockHash: 0xa5eedb4e4e4b0f84238464d563b82d7dddadfc68f21cfa2bfcbbbcdb944c4b63, FinalizedBlockHash: 0x0000000000000000000000000000000000000000000000000000000000000000) .
2022-07-24 22:09:05.1141|Syncing... Block 0xa5eedb4e4e4b0f84238464d563b82d7dddadfc68f21cfa2bfcbbbcdb944c4b63 not found.
```
```
2022-07-24 22:09:05.0853|Received a new payload: 12657968 (0xa5eedb4e4e4b0f84238464d563b82d7dddadfc68f21cfa2bfcbbbcdb944c4b63)
2022-07-24 22:09:05.1018|Insert block into cache without parent 12657968 (0xa5eedb...4c4b63)
2022-07-24 22:09:05.1141|Received: ForkchoiceState: (HeadBlockHash: 0xa5eedb4e4e4b0f84238464d563b82d7dddadfc68f21cfa2bfcbbbcdb944c4b63, SafeBlockHash: 0xa5eedb4e4e4b0f84238464d563b82d7dddadfc68f21cfa2bfcbbbcdb944c4b63, FinalizedBlockHash: 0x0000000000000000000000000000000000000000000000000000000000000000) .
2022-07-24 22:09:05.1141|Syncing... Block 0xa5eedb4e4e4b0f84238464d563b82d7dddadfc68f21cfa2bfcbbbcdb944c4b63 not found.
```

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

@ -1,24 +1,33 @@
# Run an execution client
In order to be able to produce blocks and process incoming validator deposits, you'll need to run an execution client in together with the beacon node.
In order to run a beacon node, you need to also be running an execution client - 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.
The `--web3-url` option informs the beacon node how to connect to the execution client - both `http://` and `ws://` URL:s are supported.
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.
You can pass one or more `--web3-url` parameters to the node. Any additional web3 url:s will be used for backup, should the first client become unavailable:
```sh
./run-mainnet-beacon-node.sh \
--web3-url=ws://127.0.0.1:8546 \
--web3-url=http://other:8545
--web3-url=http://other:8545 \
--jwt-secret=/tmp/jwtsecret
```
!!! warning
You need to run your own execution client after [the merge](./merge.md) - relying on third-party services such as Infura, Alchemy and Pocket will not be possible.
!!! info
Syncing an execution client may take hours or even days, depending on your hardware!
Syncing an execution client may take hours or even days, depending on your hardware! The backup providers will be synced only when the primary becomes unavailable, which may lead to a small gap in validation duties - this limitation may be lifted in future versions.
## Steps
### 1. Install execution client
Select an execution client and install it, configuring it such that that WebSockets are enabled and a JWT secret file is created.
=== "Nimbus"
@ -26,34 +35,30 @@ You can pass one or more `--web3-url` parameters to the node. Any additional web
=== "Geth"
### 1. Install Geth
#### 1. Install Geth
See the [Installing Geth](https://geth.ethereum.org/docs/install-and-build/installing-geth) for instructions on installing Geth.
### 2. Start Geth
#### 2. Start Geth
Once you have geth installed, make sure to enable the JSON-RPC WebSocket interface when running geth:
Once you have geth installed, make sure to enable the JSON-RPC WebSocket interface when running geth, along with the options for creating an [autheticated RPC endpoint](https://geth.ethereum.org/docs/interface/consensus-clients):
=== "Mainnet"
```
geth --ws
geth --ws --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret /tmp/jwtsecret
```
=== "Goerli"
```
geth --goerli --ws
geth --goerli --ws --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret /tmp/jwtsecret
```
!!! note
The `--ws` flag is needed to enable the websocket RPC API. This allows Nimbus to query the eth1 chain using Web3 API calls.
The `--ws` flag allows Nimbus to connect using WebSockets.
#### 3. Leave Geth running
### 3. Leave Geth running
Let it sync - Geth uses snap sync by default. It may take anywhere between a few hours and a couple of days.
!!! note
It is safe to run Nimbus and start validating even if Geth hasn't fully synced yet
Let it syns - it may take anywhere between a few hours and a couple of days.
You'll know Geth has finished syncing, when you start seeing logs that look like the following:
@ -64,22 +69,30 @@ You can pass one or more `--web3-url` parameters to the node. Any additional web
INFO [05-29|01:16:14] Imported new chain segment blocks=1 txs=11 mgas=1.135 elapsed=22.281ms mgasps=50.943 number=3785444 hash=277bb9…623d8c
```
Geth accepts connections from the loopback interface (`127.0.0.1`), with default WebSocket port `8546`. This means that your default Web3 provider URL should be: `ws://127.0.0.1:8546`
Geth accepts connections from the localhost interface (`127.0.0.1`), with default authenticated RPC port `8551`. This means that your default Web3 provider URL should be: `ws://127.0.0.1:8551`
=== "Nethermind"
See the [Getting started](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/getting-started) guide to set up Nethermind.
Make sure to enable the [JSON-RPC](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge#jsonrpc-configuration-module) interface over WebSockets.
Make sure to enable the [JSON-RPC](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge#jsonrpc-configuration-module) interface over WebSockets, and pass `--JsonRpc.JwtSecretFile=/tmp/jwtsecret` to select a JWT secret file location.
=== "Besu"
See the [Besu documentation](https://besu.hyperledger.org/en/stable/) for instructions on setting up Besu.
Make sure to enable the [JSON-RPC](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API/) WebSocket interface.
Make sure to enable the [JSON-RPC](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API/) WebSocket interface and store the JWT token in `/tmp/jwtsecret`.
=== "Erigon"
See the [Erigon README](https://github.com/ledgerwatch/erigon#getting-started=) for instructions on setting up Erigon.
See the [Erigon README](https://github.com/ledgerwatch/erigon#getting-started) for instructions on setting up Erigon.
Make sure to enable the [JSON-RPC](https://github.com/ledgerwatch/erigon#beacon-chain=) WebSocket interface.
Make sure to enable the [JSON-RPC](https://github.com/ledgerwatch/erigon#beacon-chain-consensus-layer) WebSocket interface and use `--authrpc.jwtsecret=/tmp/jwtsecret` to set a path to the JWT token file.
### 2. Leave the execution client running
When the execution client starts, it will create a JWT authentication token file - you will need to pass this file to Nimbus to allow it to perform authenticated requrests.
It will then start syncing the chain, up to [the merge](./merge.md). Once it reaches this point, it will wait for the beacon node to provide further sync instructions.
It is safe to start the beacon node even if the execution client is not yet fully synced.

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

@ -1,6 +1,6 @@
# Graffiti
# Set up Graffiti
You can use your node's graffiti flag to make your mark on history and forever engrave some words of your choice into an Ethereum block. You will be able to see it using the block explorer.
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.
=== "Mainnet"
```sh

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

@ -1,7 +1,9 @@
# The Nimbus Guide
!!! note ""
If you're eager to get started, check out our [quickstart guide](./quick-start.md). Coming from a different client? Check out the [migration guide](./migration.md).
If you're eager to get started, check out our [quickstart guide](./quick-start.md).
Coming from a different client? Check out the [migration guide](./migration.md).
Nimbus is a client for the Ethereum `consensus layer` (eth2) and `execution layer` (eth1) that is [lightweight](https://our.status.im/ethereum-is-green/), [secure](./audit.md) and [easy to use](./run-a-validator.md).
@ -30,21 +32,21 @@ This book explains the ways in which you can use Nimbus to either monitor the be
- [Vitalik's annotated spec](https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md)
- [Danny Ryan's annotated spec](https://notes.ethereum.org/@djrtwo/Bkn3zpwxB)
### Get in touch
## Get in touch
Need help with anything? Join us on [Status](https://join.status.im/nimbus-general) and [Discord](https://discord.gg/9dWwPnG).
### Donate
## Donate
If you'd like to contribute to Nimbus development:
* Our donation address is [`0x70E47C843E0F6ab0991A3189c28F2957eb6d3842`](https://etherscan.io/address/0x70E47C843E0F6ab0991A3189c28F2957eb6d3842)
* We're also listed on [GitCoin](https://gitcoin.co/grants/137/nimbus-2)
### Stay updated
## Stay updated
Subscribe to our newsletter [here](https://subscribe.nimbus.guide/).
### Disclaimer
## 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.

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

@ -1,80 +1 @@
# Setting up an Infura account
> ⚠️ After The Merge, you will need to run your own [execution client](./eth1.md).
In a nutshell, Infura is a hosted ethereum node cluster that lets you make requests to the eth1 blockchain without requiring you to set up your own eth1 node.
While we do support Infura to process incoming validator deposits, we recommend running your own eth1 node to avoid relying on a third-party-service.
> **Note:** Nimbus currently supports remote Infura nodes and [local execution nodes](./eth1.md). In the future, we plan on having our own eth1 client -- [Nimbus 1](https://github.com/status-im/nimbus) -- be the recommended default.
### 1. Visit Infura.io
Go to:
[https://infura.io/](https://infura.io/)
and click on `Get Started For Free`
![](https://i.imgur.com/BtStgup.png)
### 2. Sign up
Enter your email address and create a password
![](https://i.imgur.com/al1OsdR.png)
### 3. Verify email address
You should have received an email from Infura in your inbox. Open up it up and click on `Confirm Email Address`
![](https://i.imgur.com/EAD8ZhV.png)
### 4. Go to dashboard
This will take you to your Infura dashboard (https://infura.io/dashboard/)
![](https://i.imgur.com/LuNcoYr.png)
### 5. Create your first project
Click on the first option (`create your first project`) under `Let's Get Started`
![](https://i.imgur.com/wBAGhcs.png)
Choose a name for your project
![](https://i.imgur.com/yr5vnSo.png)
You'll be directed to the settings page of your newly created project
![](https://i.imgur.com/kx3R8XS.png)
### 6. Select endpoint
> ⚠️ If you're connecting to mainnet, you should skip this step
If you're connecting to a testnet, in the `KEYS` section, click on the dropdown menu to the right of `ENDPOINTS`, and select `GÖRLI`
![](https://i.imgur.com/MKZ6rVc.png)
### 7. Copy one of the endpoints
You can use either endpoint but we recommend you copy the `wss`
![](https://i.imgur.com/fZ6Bcjy.png)
### 8. Run the beacon node
[Launch the beacon node](./start-syncing.md) on your favourite testnet, passing in your websocket endpoint as the [Web3 provider URL](./start-syncing.md#web3-provider-url).
### 9. Check stats
Visit your project's stats page to see a summary of your eth1 related activity and method calls
![](https://i.imgur.com/MZVTHHV.png)
That's all there is to it :)
This page has been removed - following [the merge](./merge.md) it is no longer possible to use Infura for validation duties.

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

@ -1,4 +1,4 @@
# Log rotation
# 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.

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

@ -1,6 +1,7 @@
# Logging options
> :warning: The logging options outlined here are based on a preview feature, and are subject to change
!!! 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).

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

@ -1,6 +1,8 @@
# The merge
# The Merge
The Ethereum network is preparing for a major upgrade to merge the beacon chain with the existing proof-of-work execution network, thus transitioning to proof-of-stake. To read more about the merge, see https://ethereum.org/en/upgrades/merge/.
The Ethereum network is preparing for a major upgrade to merge the beacon chain with the existing proof-of-work execution network, thus transitioning to proof-of-stake.
Read more about [here](https://ethereum.org/en/upgrades/merge/).
## Preparing for the merge
@ -14,10 +16,14 @@ As the merge draws near, we will continue to update this page with the latest in
Leading up to the merge, it is important to [keep Nimbus up to date](./keep-updated.md). Before the merge, the exact version of Nimbus required to participate will be announced, but stakers should be prepared to upgrade their nodes on short notice.
### Run an execution client
### Set up your Execution Client
As a node operator, you will need to run both an execution client and a consensus client after the merge. If you were previously using a third-party web3 provider (such as Infura or Pocket), you will need to [set up an execution client](./eth1.md).
If you were running an execution client before, make sure to update its configuration to include an option for JWT secrets and engine API.
### Prepare a suggested fee recipient
After the merge, validators that propose blocks are eligible to recieve transaction fees - read more about fee recipients [here](https://launchpad.ethereum.org/en/merge-readiness#fee-recipient).
See the [suggested fee recipent page](./suggested-fee-recipient.md) for information about the changes needed to Nimbus.

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

@ -1,38 +1,36 @@
---
hide:
- toc
---
# Migrate from another client
This guide will take you through the basics of how to migrate to Nimbus from another client. *See [here](./migration-options.md) for advanced options*.
The main pain point involves the exporting and importing of the [slashing protection database](https://eips.ethereum.org/EIPS/eip-3076), since each client takes a slightly different approach here.
**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.
!!! 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.
> **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.
## Steps
## Step 1 - Sync the Nimbus beacon node
### 1. Sync the Nimbus beacon node
No matter which client you are migrating over from, the first step is to sync the Nimbus beacon node.
The easiest way to do this is to follow the [beacon node quick start guide](./quick-start.md). Syncing the beacon node might take up to 30 hours depending on your hardware - you should keep validating using your current setup until it completes.
The easiest way to do this is to follow the [beacon node quick start guide](./quick-start.md).
Once your Nimbus beacon node has synced and you're satisfied that it's working, move to **Step 2**.
> **Tip:** See here for how to [keep track of your syncing progress](keep-an-eye.md#keep-track-of-your-syncing-progress).
>
> Alternatively, If you run the Nimbus beacon node with the `--rest` option enabled (e.g. `./run-mainnet-beacon-node.sh --rest`), you can obtain your node's syncing status by running:
>
> ```
> curl -X GET http://localhost:5052/eth/v1/node/syncing
> ```
>
> Look for an `"is_syncing":false` in the response to confirm that your node has synced.
!!! tip
You can keep track of your [syncing progress](keep-an-eye.md#keep-track-of-your-syncing-progress) with the following command:
## Step 2 - Stop your existing client and export your slashing protection history
```
curl -X GET http://localhost:5052/eth/v1/node/syncing
```
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
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).
=== "Prysm"
@ -157,15 +155,16 @@ Once your Nimbus beacon node has synced and you're satisfied that it's working,
> **Tip:** To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check it's recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
## Step 3 - Import your validator key(s) into Nimbus
### 3. Import your validator key(s) into Nimbus
To import you validator key(s), follow the instructions [outlined here](./keys.md).
> 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.
!!! 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.
## Step 4 - Import your slashing protection history
### 4. Import your slashing protection history
To import the slashing protection history you exported in **step 2**, from the `nimbus-eth2` directory run:
@ -175,7 +174,7 @@ build/nimbus_beacon_node slashingdb import path/to/export_dir/slashing-protectio
Replacing `/path/to/export_dir` with the file/directory you specified when you exported your slashing protection history.
## Step 5 - Start the Nimbus validator
### 5. Start the Nimbus validator
Follow the instructions [here](./connect-eth2.md) to start your validator using our pre-built [binaries](./binaries.md).
@ -183,7 +182,6 @@ If you prefer to use Docker, see [here](./docker.md)
For a quick guide on how to set up a systemd service, see [here](./beacon-node-systemd.md)
## 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.

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

@ -1,4 +1,4 @@
# Networking options
# 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.
@ -16,7 +16,8 @@ With this brand, you will also need to edit individual connections - in "Home Ne
## 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.
!!! 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.
If your Peer count is low (less than `15`) and/or you repeatedly see either of the following warnings:
@ -52,14 +53,12 @@ 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
## Pass the extip option
## 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:
```
./run-prater-beacon-node.sh --nat:extip:1.2.3.4
```
> Note that this should also work with a dynamic IP address. But you will probably also need to pass `enr-auto-update` as an option to the client.
!!! 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
@ -71,8 +70,8 @@ In practice this means relaunching the beacon node with `--enr-auto-update:true`
If you're running on a home network and want to ensure you are able to receive incoming connections you may need to set up port forwarding (though some routers automagically set this up for you).
> **Note:** If you are running your node on a virtual public server (VPS) instance, you can safely ignore this section.
!!! note
If you are running your node on a virtual public server (VPS) instance, you can safely ignore this section.
While the specific steps required vary based on your router, they can be summarised as follows:
@ -104,23 +103,20 @@ curl v4.ident.me
To determine your private IP address, run the appropriate command for your OS:
**Linux:**
=== "Linux"
```sh
ip addr show | grep "inet " | grep -v 127.0.0.1
```
```
ip addr show | grep "inet " | grep -v 127.0.0.1
```
=== "Windows"
```sh
ipconfig | findstr /i "IPv4 Address"
```
**Windows:**
```
ipconfig | findstr /i "IPv4 Address"
```
**macOS:**
```
ifconfig | grep "inet " | grep -v 127.0.0.1
```
=== "macOS"
```sh
ifconfig | grep "inet " | grep -v 127.0.0.1
```
## Check open ports on your connection

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

@ -1,17 +1,17 @@
# Validate with a Raspberry Pi: Guide
# Running on a Raspberry Pi
<blockquote class="twitter-tweet"><p lang="en" dir="ltr">I expect the new Raspberry Pi 4 (4GB RAM option, external SSD) to handle an Eth2 validator node without breaking a sweat. That&#39;s $100 of hardware running at 10 Watts to support a 32 ETH node (currently ~$10K stake).</p>&mdash; Justin Ðrake (@drakefjustin) <a href="https://twitter.com/drakefjustin/status/1143091047058366465?ref_src=twsrc%5Etfw">June 24, 2019</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
> In addition to this guide, we highly recommend this [wonderful and complementary resource](https://docs.rocketpool.net/guides/node/local/prepare-pi.html#preliminary-setup) by community member Joe Clapis.
## Introduction
This page will take you through how to use your laptop to program your Raspberry Pi, get Nimbus running, and connect to the **Prater testnet**.
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.
## Prerequisites
- Raspberry Pi 4 4GB (8GB recommended if also running execution client)
- 64GB microSD Card
- microSD USB adapter
@ -32,18 +32,21 @@ One of the most important aspects of the Raspberry Pi experience is trying to ma
!!! 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)
## Steps
### 1. Download Raspberry Pi Imager
[Raspberry Pi Imager](https://www.raspberrypi.org/blog/raspberry-pi-imager-imaging-utility/) is a new imaging utility that makes it simple to manage your microSD card with Raspbian (the free Pi operating system based on Debian).
[Raspberry Pi Imager](https://www.raspberrypi.org/blog/raspberry-pi-imager-imaging-utility/) is an imaging utility that makes it simple to manage your microSD card with Raspbian (the free Pi operating system based on Debian).
You can find the [download](https://www.learnenough.com/command-line-tutorial/basics) link for your operating system here: [Windows](https://downloads.raspberrypi.org/imager/imager_1.4.exe), [macOS](https://downloads.raspberrypi.org/imager/imager_1.4.dmg), [Ubuntu](https://downloads.raspberrypi.org/imager/imager_1.4_amd64.deb).
### 2. Download Raspian 64-bit OS (Beta)
### 2. Download Raspian 64-bit OS
You can find the latest version, [here](https://downloads.raspberrypi.org/raspios_arm64/images/).
### 3. Plug in SD card
Use your microSD to USB adapter to plug the SD card into your computer.
Use your microSD to USB adapter to plug the SD card into your computer.
### 4. Download Raspberry Pi OS
@ -61,7 +64,6 @@ 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
![](https://storage.googleapis.com/ethereum-hackmd/upload_f90713c1ef782a94b5fce9eb8249c206.png)
@ -95,10 +97,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.
!!! 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.
### 6. Enable SSH (using Linux or macOS)
@ -110,7 +110,7 @@ When the Pi boots, it will look for the `ssh` file. If it is found, SSH is enabl
To create an empty `ssh` file, from the home directory of the `boot` partition file, run:
```
```sh
touch ssh
```
@ -120,14 +120,13 @@ Since Raspberry Pi OS supports [Multicast_DNS](https://en.wikipedia.org/wiki/Mul
The default hostname on a fresh Raspberry Pi OS install is `raspberrypi`, so any Raspberry Pi running Raspberry Pi OS should respond to:
```
```sh
ping raspberrypi.local
```
The output should look more or less as follows:
```
```sh
PING raspberrypi.local (195.177.101.93): 56 data bytes
64 bytes from 195.177.101.93: icmp_seq=0 ttl=64 time=13.272 ms
64 bytes from 195.177.101.93: icmp_seq=1 ttl=64 time=16.773 ms
@ -137,12 +136,11 @@ 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`
### 8. SSH (using Linux or macOS)
Connect to your Pi by running:
```
```sh
ssh pi@195.177.101.93
```
@ -171,7 +169,7 @@ This is a security risk - please login as the 'pi' user and type 'passwd' to set
Followed by a command-line prompt indicating a successful connection:
```
```sh
pi@raspberrypi:~ $
```
@ -179,16 +177,17 @@ 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.
!!! 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.
Use the Pi's built-in text editor [nano](https://www.nano-editor.org/dist/latest/cheatsheet.html) to open up the swap file:
```
```sh
sudo nano /etc/dphys-swapfile
```
Change the value assigned to `CONF_SWAPSIZE` from `100` to `2048`:
```
@ -206,41 +205,44 @@ Save (`Ctrl+S`) and exit (`Ctrl+X`).
### 10. Reboot
Reboot your Pi to have the above changes take effect:
```
```sh
sudo reboot
```
This will cause your connection to close. So you'll need to `ssh` into your Pi again:
```
```sh
ssh pi@195.177.101.93
```
> **Note:** Remember to replace `195.177.101.93` with the IP address of your Pi.
!!! note
Remember to replace `195.177.101.93` with the IP address of your Pi.
### 10b. Boot from external SSD
Follow [this guide](https://www.tomshardware.com/how-to/boot-raspberry-pi-4-usb) to copy the contents of your SD card over to your SSD, and boot your Pi from your SSD.
> **Tips:**
>
> Make sure you connect your SSD the Pi's USB 3 port (the blue port).
>
> If your Pi is headless (no monitor attached) you can use the [`rpi-clone`](https://github.com/billw2/rpi-clone) repository to copy the contents of the SD over to the SSD; in a nutshell, replace steps 14 and 15 of the above guide with the following commands (which you should run from the Pi's `home` directory):
> ```bash
> git clone https://github.com/billw2/rpi-clone.git
> cd rpi-clone
> sudo cp rpi-clone rpi-clone-setup /usr/local/sbin
> sudo rpi-clone-setup -t testhostname
> rpi-clone sda
> ```
>
>For more on `raspi-config`, see [here](https://www.raspberrypi.org/documentation/configuration/raspi-config.md).
>
> To shutdown your Pi safely, run `sudo shutdown -h now`
!!! tip
Make sure you connect your SSD the Pi's USB 3 port (the blue port).
If your Pi is headless (no monitor attached) you can use the [`rpi-clone`](https://github.com/billw2/rpi-clone) repository to copy the contents of the SD over to the SSD; in a nutshell, replace steps 14 and 15 of the above guide with the following commands (which you should run from the Pi's `home` directory):
```sh
git clone https://github.com/billw2/rpi-clone.git
cd rpi-clone
sudo cp rpi-clone rpi-clone-setup /usr/local/sbin
sudo rpi-clone-setup -t testhostname
rpi-clone sda
```
For more on `raspi-config`, see [here](https://www.raspberrypi.org/documentation/configuration/raspi-config.md).
!!! tip
To shutdown your Pi safely, run `sudo shutdown -h now`
Once you're done, `ssh` back into your Pi.
@ -250,7 +252,7 @@ Open the [Nimbus eth2 releases page](https://github.com/status-im/nimbus-eth2/re
Run this in your home directory to download nimbus-eth2:
```
```sh
mkdir nimbus-eth2
wget <insert download link here>
tar -xzf nimbus-eth2_Linux_arm64v8*.tar.gz -C nimbus-eth2
@ -261,29 +263,32 @@ Now you can find the software in the nimbus-eth2 directory.
### 12. Copy signing key over to Pi
>**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.
!!! 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.
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:
```
```sh
scp -r <VALIDATOR_KEYS_DIRECTORY> pi@195.177.101.93:
```
> **Note:** Don't forget the colon (:) at the end of the command!
!!! note
Don't forget the colon (:) at the end of the command!
As usual, replace `195.177.101.93` with your Pi's IP address, and `<VALIDATOR_KEYS_DIRECTORY>` with the full pathname of your `validator_keys` directory (if you used the Launchpad [command line app](https://github.com/ethereum/eth2.0-deposit-cli/releases/) this would have been created for you when you generated your keys).
> **Tip:** run `pwd` in your `validator_keys` directory to print the full pathname to the console.
!!! tip
Run `pwd` in your `validator_keys` directory to print the full pathname to the console.
### 13. Import signing key into Nimbus
To import your signing key into Nimbus, from the `nimbus-eth2` directory run:
```
```sh
build/nimbus_beacon_node deposits import --data-dir=build/data/shared_prater_0 ../validator_keys
```
@ -294,29 +299,14 @@ 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 instruction on how to do so, see [this page](./eth1.md).
!!! note
If you haven't already, we recommend registering for, and running, your own eth1 node in parallel. For instruction on how to do so, see [this page](./eth1.md).
To connect to Prater, run:
```
./run-prater-beacon-node.sh
```
You'll be prompted to enter a web3-provider url:
```
To monitor the Eth1 validator deposit contract, you'll need to pair
the Nimbus beacon node with a Web3 provider capable of serving Eth1
event logs. This could be a locally running Eth1 client such as Geth
or a cloud service such as Infura. For more information please see
our setup guide:
https://status-im.github.io/nimbus-eth2/eth1.html
Please enter a Web3 provider URL:
```
Enter your web3 [endpoint](eth1.md).
### 15. Check for successful connection
If you look near the top of the logs printed to your console, you should see confirmation that your beacon node has started, with your local validator attached:
@ -348,8 +338,7 @@ Keep an eye on the number of peers your currently connected to (in the above cas
> **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 you're 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
## 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.
@ -360,7 +349,7 @@ The best thing you can do is to set your Pi to run Prater. **If you have no trou
Although we don't expect a modern Pi to fail, we recommend buying a spare Pi, and enterprise grade SSD, on the off-chance it does; keep your original SD around, to make it easy for you to copy the image over.
#### Systemd
### Systemd
Now that you have Nimbus up and running, we recommend [setting up a systemd service](https://www.raspberrypi.org/documentation/linux/usage/systemd.md) with an autorestart on boot (should you experience an unexpected power outage, this will ensure your validator restarts correctly).
@ -370,11 +359,10 @@ Systemd will also ensure your validator keeps running when you exit your ssh ses
For the details on how to do this, see [this page](./beacon-node-systemd.md).
#### Overclocking
### Overclocking
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).
!!! 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).

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

@ -1,6 +1,6 @@
# Run the beacon node
This page takes you through the steps of getting a standard setup the Nimbus beacon node up and running.
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.
@ -11,22 +11,24 @@ Running a beacon node is a [worthwhile endeavor](https://vitalik.ca/general/2021
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 will first need to be running a beacon node.
To become a validator, you first need to set up a beacon node.
!!! tip
You can practice running the node safely on the [Prater testnet](./prater.md) - throughout, we'll provide instructions for both Prater and Mainnet.
## 1. Prepare
## Steps
### 1. Prepare
Prepare your machine by installing [Nimbus' dependencies](./install.md).
## 2. Set up an execution client
### 2. Set up an execution client
To run a beacon node, you need to have access to an execution client exposing the web3 API - throughout, we'll assume an execution client is running on the same machine as the beacon node, but this is not required.
See the [execution client](./eth1.md) guide for instructions on how to pick and install an execution client!
## 3. Install Nimbus
### 3. Install Nimbus
Next, download the [latest release](./binaries.md) and install it by unpacking the archive. Using a command line terminal:
@ -44,7 +46,7 @@ tar xvf nimbus-eth2_Linux_amd64_22.6.1_2444e994.tar.gz --strip-components 1 -C n
!!! tip
Advanced users looking to take advantage of hardware-specific features and optimization may wish to [build from source](./build.md) instead!
## 4. Start the node
### 4. Start the node
Once you've installed the binaries, you can [start the node](./start-syncing.md) which will initiate the sync process.

172
docs/the_nimbus_book/src/rp-quick-start.md
View File

@ -1,172 +0,0 @@
# Rocket Pool: Introductory guide
<blockquote class="twitter-tweet"><p lang="en" dir="ltr">We believe decentralised staking pools like <a href="https://twitter.com/Rocket_Pool?ref_src=twsrc%5Etfw">@Rocket_Pool</a> and <a href="https://twitter.com/DAppNode?ref_src=twsrc%5Etfw">@DAppNode</a> DAO are essential to ensuring <a href="https://twitter.com/ethereum?ref_src=twsrc%5Etfw">@ethereum</a>&#39;s future as an unbreakable and censorship-resistant system.<a href="https://t.co/FXQQICZsfL">https://t.co/FXQQICZsfL</a></p>&mdash; Nimbus (@ethnimbus) <a href="https://twitter.com/ethnimbus/status/1367841160081907717?ref_src=twsrc%5Etfw">March 5, 2021</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
This guide offers a bare-bones introduction to getting up and running with Nimbus and [Rocket Pool](https://www.rocketpool.net/) -- a trustless staking pool which matches those who wish to stake some ETH with those who wish to operate a node.
> **Nota Bene:** Rocket Pool is not only for node operators. Staking in Rocket Pool as a regular user is as easy as navigating to the [Rocket Pool website](https://beta.rocketpool.net/), entering an amount of ETH to stake, and clicking Start! When you stake, you will immediately receive an amount of rETH with equivalent value to the ETH you deposit. This allows anyone, no matter how technical or wealthy, to help contribute to the decentralisation of the network.
It assumes you are familiar with the basics of how Rocket Pool works. If that's not the case, we recommend reading through the following resources first:
- Our [introductory post](https://our.status.im/rocket-pool-integration/)
- Rocket Pool explainer series: [part 1](https://medium.com/rocket-pool/rocket-pool-staking-protocol-part-1-8be4859e5fbd)
- Rocket Pool explainer series: [part 2](https://medium.com/rocket-pool/rocket-pool-staking-protocol-part-2-e0d346911fe1)
- [Beta Finale](https://medium.com/rocket-pool/rocket-pool-3-0-beta-finale-fb35c4f8e003) announcement
If you're a Raspberry Pi user, we highly recommend [this wonderful and complementary resouce](https://github.com/jclapis/rp-pi-guide/blob/main/Overview.md) by community member Joe Clapis.
> **Note:** Rocket Pool is currently running their [Beta Finale](https://medium.com/rocket-pool/rocket-pool-3-0-beta-finale-fb35c4f8e003) on Pyrmont testnet, so this is the perfect time to get up to speed and play around with their stack.
## 1. Install Docker + Compose
> If you're using Ubuntu, Debian, CentOS or Fedora, please skip this step.
To install Docker and Compose follow the instructions [here](https://docs.docker.com/get-docker/) and [here](https://docs.docker.com/compose/install/).
> Note that Docker Desktop for Mac and Windows already include Compose, which means that if you're using a Mac or Windows device you can ignore the second link.
## 2. Install smart node client
> **Background:** The Rocket Pool smart node software stack provides all of the necessary infrastructure for running a node in the Rocket Pool network: it contains a smart node client, which provides a command-line interface for managing a smart node either locally or remotely (over SSH) and a smart node service; which provides an API for client communication and performs background node tasks (such as validator duties).
You can install the smart node client with either `curl` or `wget`.
To see which tool you have available, run:
```
curl --version
wget --version
```
Once you know whether you have `curl` or `wget` available, you can find the relevant command for your operating system [here](https://rocket-pool.readthedocs.io/en/latest/smart-node/getting-started.html#installation).
> For example, if you're running MacOS with `curl` installed, you should run:
>
> ```
>curl -L https://github.com/rocket-pool/smartnode-install/releases/latest/download/rocketpool-cli-darwin-amd64 -o /usr/local/bin/rocketpool && chmod +x /usr/local/bin/rocketpool
>```
## 3. Install smart node service
To install the smart node service, run:
```
rocketpool service install
```
> **Note:** If you’re using Ubuntu, Debian, CentOS or Fedora, the above will automatically install docker engine and docker-compose on your system. If automatic dependency installation is not supported on your platform (this is the case for MacOS for example), run `rocketpool service install -d` instead.
## 4. Configure smart node client
Now you're ready to configure the smart node client:
```
rocketpool service config
```
You’ll be prompted to select an eth1 and eth2 client to run. If you like, you can use Infura instead of running an eth1 client.
*The default is to select a random client for you, so make sure you select Nimbus!*
## 5. Start Rocket Pool
To start Rocket Pool, open a new shell session and run:
```
rocketpool service start
```
You should see the following:
```
Starting rocketpool_eth1 ... done
Starting rocketpool_api ... done
Starting rocketpool_eth2 ... done
Starting rocketpool_watchtower ... done
Starting rocketpool_node ... done
Starting rocketpool_validator ... done
```
> **Note:** Docker will make sure that Rocket Pool keeps running, even if Nimbus crashes or you restart your computer.
## 6. Check Nimbus is running correctly
To ensure Nimbus is running correctly, run:
```
rocketpool service logs eth2
```
Nimbus will print lines that look like this:
```
eth2_1 | INF 2021-02-21 06:35:43.302+00:00 Slot start topics="beacnde" tid=1 file=nimbus_beacon_node.nim:940 lastSlot=682377 scheduledSlot=682378 delay=302ms641us581ns peers=47 head=f752f69a:745 headEpoch=23 finalized=2717f624:672 finalizedEpoch=21 sync="PPUPPPDDDD:10:2.0208:1.5333:01d20h29m (736)"
eth2_1 | INF 2021-02-21 06:35:43.568+00:00 Slot end
```
The time towards the end (`01d20h29m`) tells you how long Nimbus thinks it will be until you're fully synced.
## 7. Create a Rocket Pool wallet
Now that Nimbus is syncing, you're ready to create a Rocket Pool wallet to create and hold your validator keys:
```
rocketpool wallet init
```
## 8. Find your node address
You'll need to find your node address in order to be able to request Goerli ETH:
```
rocketpool node status
```
## 9. Request Goerli ETH
Request **35** Goerli ETH from [the faucet](https://faucet.goerli.mudit.blog/) to the address you found in the previous step.
> **Note:** you'll need slightly more than 32 ETH since you'll also need to interact with the Rocket Pool smart contracts to request RPL.
## 10. Request Goerli RPL
You'll also need some RPL. To request RPL directly from the Rocket Pool faucet, run:
```
rocketpool faucet withdraw-rpl
```
## 11. Register your node
Now you're finally ready to register your node with Rocket Pool:
```
rocketpool node register
```
## 12. Make a deposit
The final step is to deposit 32 ETH to initialise your validator (don't worry you'll get half of it back):
```
rocketpool node deposit
```
> **Note:** You’ll see a prompt that will ask you to select the amount of ETH you wish to deposit. Select 32 ETH to ensure you can start staking ASAP. At some point (shouldn't take more than 24 hours) you'll be assigned an additional 16 ETH to manage from Rocket Pool stakers: at this stage you'll be able to ask for a 16 ETH refund using `rocketpool minipool refund`.
That’s it! You’re officially part of the Rocket Pool network!
> **Tip:** Once Nimbus is synced, you'll be able to check on the status of your minipool by running:
> ```
> rocketpool minipool status
> ```
## Key resources / further reading
- Node Operator’s Guide: [https://medium.com/rocket-pool/rocket-pool-v2-5-beta-node-operators-guide-77859891766b](https://medium.com/rocket-pool/rocket-pool-v2-5-beta-node-operators-guide-77859891766b)
- Smart node docs (for all things documentation related): [https://rocket-pool.readthedocs.io/en/latest/smart-node/introduction.html](https://rocket-pool.readthedocs.io/en/latest/smart-node/introduction.html)
- Joe Clapis' guide (Excellent resource for Pi users): [https://github.com/jclapis/rp-pi-guide/blob/main/Overview.md](https://github.com/jclapis/rp-pi-guide/blob/main/Overview.md)
- Rocket Pool's [discord](https://discord.gg/a5zVQd66gr)

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

@ -9,15 +9,17 @@ Once your beacon node is [running and synced](./quick-start.md), the next step i
Advanced users may want to use a separate [validator client](./validator-client.md) process instead.
## 1. Deposit
## Steps
### 1. Deposit
[Make a deposit](./deposit.md) for your validator
## 2. Import
### 2. Import
[Import your validator keys](./keys.md) into Nimbus
## 3. Validate
### 3. Validate
[Start performing duties](./connect-eth2.md) by restarting the node

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

@ -1,10 +1,25 @@
# Suggested Fee Recipient
# Set up suggested fee recipient
A suggested fee recipient offers an execution client, in a merged Ethereum network, a coinbase it might use. The execution client might not use this offered coinbase, unless one ensures that by running, controlling, and similarly configuring this execution client oneself.
A suggested fee recipient offers an execution client, in a merged Ethereum network, a coinbase it might use, based on the validator that is proposing the block.
Nimbus offers two ways to a suggested fee recipient, the `--suggested-fee-recipient` option and a per-validator recipient set using the keymanager API. Any validator without a per-validator recipient set will fall back to a `--suggested-fee-recipient` if configured. In order, it selects from the first available, for each validator, of:
!!! warning
The execution client is not required to follow the suggestion and may instead send the fees to a different address - only use execution clients you trust!
Nimbus offers two ways to a suggested fee recipient, the `--suggested-fee-recipient` option and a per-validator recipient set using the [keymanager API](./keymanager-api.md). Any validator without a per-validator recipient set will fall back to a `--suggested-fee-recipient` if configured. In order, it selects from the first available, for each validator, of:
1. the keymanager API per-validator suggested fee recipient
2. `--suggested-fee-recipient`
For example, `nimbus_beacon_node --suggested-fee-recipient=0x79b53bc7a89347d3ab90789e99a0a9c58f2fea57` suggests to the execution client that `0x79b53bc7a89347d3ab90789e99a0a9c58f2fea57` 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 `0x79b53bc7a89347d3ab90789e99a0a9c58f2fea57`.
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`.
## Command line option
=== "Mainnet"
```sh
./run-mainnet-beacon-node.sh --suggested-fee-recipient=0x70E47C843E0F6ab0991A3189c28F2957eb6d3842
```
=== "Prater"
```sh
./run-mainnet-beacon-node.sh --suggested-fee-recipient=0x70E47C843E0F6ab0991A3189c28F2957eb6d3842
```

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

@ -1,14 +1,14 @@
# Backup web3 provider
It's a good idea to add a backup web3 provider in case your main one goes down. You can do this by simply repeating the `--web3-url` parameter on launch.
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.
For example, if your primary execution client is a [local Geth](./eth1.md#geth), but you want to use [Infura](./infura-guide.md) as a backup you would run:
Each beacon node requires at least one dedicated web3 provider.
!!! warning
After [the merge](./merge.md), it will no longer be possible to rely on third-party services like Infura to run a beacon node!
!!! 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.
```sh
./run-mainnet-beacon-node.sh \
--web3-url="ws://127.0.0.1:8546" \
--web3-url="wss://mainnet.infura.io/ws/v3/..."
--web3-url="ws://127.0.0.1:8546" \
--web3-url="http://backup:4444"
```