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

Make the validating guide self-contained (#5076) 

* make the validating guide self-contained

Instead of having links to the three separate how-to guides,
now everything is under one umbrella.

* fix all now-broken links

* Apply suggestions from code review

Co-authored-by: tersec <tersec@users.noreply.github.com>

* address review comments

---------

Co-authored-by: tersec <tersec@users.noreply.github.com>
This commit is contained in:
Miran 2023-06-20 16:38:10 +02:00 committed by GitHub
parent bb63f8e0ec
commit cabb2779b4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 221 additions and 200 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/the_nimbus_book/mkdocs.yml
View File

@ -61,9 +61,6 @@ nav:
- 'migration.md' - 'migration.md'
- Validator: - Validator:
- 'deposit.md'
- 'keys.md'
- 'connect-eth2.md'
- 'graffiti.md' - 'graffiti.md'
- 'suggested-fee-recipient.md' - 'suggested-fee-recipient.md'
- 'external-block-builder.md' - 'external-block-builder.md'

4
docs/the_nimbus_book/src/additional-validator.md
View File

@ -2,9 +2,9 @@
<!-- TODO: We should work on a new recommended way to add validators based on the Keymanager API (this doesn't require a node restart) --> <!-- TODO: We should work on a new recommended way to add validators based on the Keymanager API (this doesn't require a node restart) -->
To add an additional validator, [generate a new key](./more-keys.md) then follow [the same steps](./keys.md) as you did when adding your other keys. To add an additional validator, [generate a new key](./more-keys.md) then follow [the same steps](./run-a-validator.md#2-import-your-validator-keys) as you did when adding your other keys.
You'll have to [restart](./connect-eth2.md) the beacon node for the changes to take effect. You'll have to [restart](./run-a-validator.md#3-start-validating) the beacon node for the changes to take effect.
!!! tip !!! tip
A single Nimbus instance is able to handle multiple validators. A single Nimbus instance is able to handle multiple validators.

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

@ -109,7 +109,7 @@ sudo journalctl -u nimbus_beacon_node.service --since yesterday
## Import validator keys ## Import validator keys
Before you start, familiarize yourself with the [standard way of importing validators](./keys.md). Before you start, familiarize yourself with the [standard way of importing validators](./run-a-validator.md#2-import-your-validator-keys).
Make sure you use the correct [data directory](./data-dir.md). Make sure you use the correct [data directory](./data-dir.md).
Look for the `--data-dir` option in the `.service` file. Look for the `--data-dir` option in the `.service` file.

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

@ -1,39 +1,3 @@
# Start validating This page has been removed.
Once your keys have been [imported](./keys.md), it is time to configure a [fee recipient](./suggested-fee-recipient.md) and restart the beacon node to start validating. Follow our [validating guide](./run-a-validator.md).
## Steps
### 1. Choose a fee recipient
The [fee recipient](./suggested-fee-recipient.md) is an Ethereum address that receives transaction fees from the blocks that your validators produce.
You can set up a separate address or reuse the address from which you funded your deposits.
### 2. (Re)start the node
Press `Ctrl-c` to stop the beacon node if it's running, then use the same command as before to run it again, this time adding the `--suggested-fee-recipient` option in addition to `--web3-url`:
=== "Mainnet"
```sh
./run-mainnet-beacon-node.sh --web3-url=http://127.0.0.1:8551 --suggested-fee-recipient=0x...
```
=== "Prater"
```sh
./run-prater-beacon-node.sh --web3-url=http://127.0.0.1:8551 --suggested-fee-recipient=0x...
```
### 3. Check the logs
Your beacon node will launch and connect your validator to the beacon chain network.
To check that keys were imported correctly, look for `Local validator attached` in the logs:
```
INF 2020-11-18 11:20:00.181+01:00 Launching beacon node
...
NOT 2020-11-18 11:20:02.091+01:00 Local validator attached
```
Congratulations!
Your node is now ready to perform validator duties.
Depending on when the deposit was made, it may take a while before the first attestation is sent — this is normal.

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

@ -1,71 +1,3 @@
# Make a deposit for your validator This page has been removed.
To make a deposit, you will need to generate keys then submit a deposit transaction to the execution chain. Follow our [validating guide](./run-a-validator.md).
!!! tip "Launchpad"
The process of setting up a validator is also documented at the Ethereum launchpad site:
* [Mainnet](https://launchpad.ethereum.org/)
* [Goerli/Prater EthStaker Launchpad](https://goerli.launchpad.ethstaker.cc/en/) or [Goerli/Prater EF Launchpad](https://prater.launchpad.ethereum.org/)
!!! tip
Use Prater to stress test and future proof your set up against peak mainnet load.
See [here](./prater.md) for all you need to know.
## Steps
### 1. Download the deposit tool
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
cd nimbus-eth2
# Make sure to get the latest version from the download page
wget https://github.com/ethereum/staking-deposit-cli/releases/download/v2.2.0/staking_deposit-cli-9ab0b05-linux-amd64.tar.gz
# Unpack the archive
tar xvf staking_deposit-cli-9ab0b05-linux-amd64.tar.gz --strip-components 2
```
### 2. Generate keys
!!! tip "Live image"
You can increase the security of this process by downloading a [Live linux image](https://ubuntu.com/tutorials/try-ubuntu-before-you-install). To do so, copy `deposit` to a USB stick, boot into the live image, and run the tool from inside the image.
Make sure you **don't** enable Wifi and unplug any Ethernet cables when using this process.
The deposit tool generates a seed phrase, and uses this to create validator and withdrawal keys.
!!! danger "Seed phrase"
If you lose you seed phrase and your withdrawal key, your funds will be lost forever!
=== "Mainnet"
```sh
# Run the deposit tool and follow the instructions on screen
./deposit new-mnemonic --chain mainnet
```
=== "Prater"
```sh
# Run the deposit tool and follow the instructions on screen
./deposit new-mnemonic --chain prater
```
### 3. Make the deposit
Once created, the keys are used to create a deposit transaction on the Ethereum execution chain.
Follow the instructions [here](https://launchpad.ethereum.org/en/upload-deposit-data) to upload the deposit data.
!!! warning
If you are making a mainnet deposit make sure you verify that the deposit contract you are interacting with is the correct one.
You should verify that the address is indeed: [0x00000000219ab540356cBB839Cbe05303d7705Fa](https://etherscan.io/address/0x00000000219ab540356cBB839Cbe05303d7705Fa)
!!! info
Once you send off your transaction(s), your validator will be put in a queue based on deposit time.
Getting through the queue may take a few hours or days (assuming the chain is finalizing).
No validators are accepted into the validator set while the chain isn't finalizing.
The `Pending Validators` metric on the [beaconcha.in](https://beaconcha.in/) will give you the size of the queue.
With the keys created, you're ready to perform the [key import](./keys.md).

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

@ -1,72 +1,3 @@
# Import your validator keys This page has been removed.
!!! tip Follow our [validating guide](./run-a-validator.md).
`systemd` service file users will want to follow the [service file guide](./beacon-node-systemd.md#import-validator-keys) instead!
Having followed the [deposit guide](./deposit.md), you will have a `validator_keys` folder containing several `.json` files in the `nimbus-eth2` directory.
We'll import the signing key of each validator to the [data directory](./data-dir.md) using the `deposits import` command:
!!! note ""
You'll be asked to enter the password you used when creating your keystore(s).
=== "Mainnet"
```sh
build/nimbus_beacon_node deposits import --data-dir=build/data/shared_mainnet_0
```
=== "Prater"
```sh
build/nimbus_beacon_node deposits import --data-dir=build/data/shared_prater_0
```
On success, a message will be printed that your keys have been imported:
```
NOT 2022-07-19 17:36:37.578+02:00 Keystore imported
```
!!! note ""
`NOT` is short for `NOTICE` and not not :)
After importing keys, it's time to [restart the node](./connect-eth2.md) and check that the keys have been picked up by the beacon node.
!!! info "All the keys"
You can read more about the different types of keys [here](https://blog.ethereum.org/2020/05/21/keys/) — the `deposits import` command will import the **signing key** only.
## Command line
If your `validator_keys` folder is stored elsewhere, you can pass its location to the import command:
=== "Mainnet"
```sh
build/nimbus_beacon_node deposits import \
--data-dir=build/data/shared_mainnet_0 \
/path/to/keys
```
=== "Prater"
```sh
build/nimbus_beacon_node deposits import \
--data-dir=build/data/shared_prater_0 \
/path/to/keys
```
Replacing `/path/to/keys` with the full pathname of where the `validator_keys` directory is found.
## Optimized import for a large number of validators
If you plan to use a large number of validators (e.g. more than 100) on a single beacon node or a validator client, you might benefit from running the `deposits import` command with the option `--method=single-salt`.
This will force Nimbus to use the same password and random salt value when encrypting all of the imported keystores which will later enable it to load the large number of validator keys almost instantly.
The theoretical downside of using this approach is that it makes the brute-force cracking of all imported keystores computationally equivalent to cracking just one of them.
Nevertheless, the security parameters used by Ethereum are such that cracking even a single keystore is considered computationally infeasible with current hardware.
## Troubleshooting
If you come across an error, make sure that:
* You are using the correct [data directory](./data-dir.md).
* For `systemd` users, look for the `--data-dir` option in the `.service` file.
* You are running the command as the correct user.
* For `systemd` users, look for the `User=` option in the `.service`. Assuming the user is called `nimbus`, prefix all commands with: `sudo -u nimbus`.
* Permissions for the data directory are wrong.
* See [folder permissions](./data-dir.md#permissions) for how to fix this.

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

@ -168,7 +168,7 @@ As part of the migration process, you need to stop your existing client and expo
### 3. Import your validator key(s) into Nimbus ### 3. Import your validator key(s) into Nimbus
To import your validator key(s), follow the instructions [outlined here](./keys.md). To import your validator key(s), follow the instructions [in our validator guide](./run-a-validator.md#2-import-your-validator-keys).
!!! tip !!! 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/`. 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/`.
@ -192,11 +192,11 @@ Replacing `/path/to/export_dir` with the file/directory you specified when you e
### 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). Follow the instructions [in our validator guide](./run-a-validator.md#3-start-validating) to start your validator using our pre-built [binaries](./binaries.md).
If you prefer to use Docker, see [here](./docker.md) If you prefer to use Docker, see [our Docker guide](./docker.md).
For a quick guide on how to set up a systemd service, see [here](./beacon-node-systemd.md) For a quick guide on how to set up a systemd service, see [our systemd guide](./beacon-node-systemd.md).
## Final thoughts ## Final thoughts

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

@ -1,6 +1,6 @@
# Recover lost keys and generate new ones # Recover lost keys and generate new ones
When generating your [first deposit](./deposit.md), you will be asked to save a mnemonic in a safe location. When generating your [first deposit](./run-a-validator.md#1-make-a-deposit-for-your-validator), you will be asked to save a mnemonic in a safe location.
This mnemonic can be used to recover lost keys and generate new ones. This mnemonic can be used to recover lost keys and generate new ones.
@ -49,7 +49,7 @@ You'll be prompted to enter your mnemonic, and a new password for your keystore.
Check that the `validator_keys` directory contains your keystore. Check that the `validator_keys` directory contains your keystore.
Copy the `validator_keys` directory to `nimbus-eth2` and then follow the instructions [here](./keys.md). Copy the `validator_keys` directory to `nimbus-eth2` and then follow the [key import instructions](./run-a-validator.md#2-import-your-validator-keys) of our validator guide.
Your key will be added to your node on next restart. Your key will be added to your node on next restart.
## Generate another key ## Generate another key
@ -84,5 +84,5 @@ Check that the `validator_keys` directory contains an extra keystore.
Copy the `validator_keys` directory to `nimbus-eth2`. Copy the `validator_keys` directory to `nimbus-eth2`.
Make sure you've made a [deposit](./deposit.md) for your new keystore, and then follow the instructions [here](./keys.md). Make sure you've [made a deposit](./run-a-validator.md#1-make-a-deposit-for-your-validator) for your new keystore, and then follow the [key import instructions](./run-a-validator.md#2-import-your-validator-keys) of our validator guide.
Your key will be added to your node on the next restart. Your key will be added to your node on the next restart.

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

@ -293,7 +293,7 @@ Once you're done, `ssh` back into your Pi.
### 12. Copy signing key over to Pi ### 12. Copy signing key over to Pi
!!! note !!! note
If you haven't generated your validator key(s) and/or made your deposit yet, follow the instructions on the [deposit page](./deposit.md) before carrying on. If you haven't generated your validator key(s) and/or made your deposit yet, follow the [deposit instructions](./run-a-validator.md#1-make-a-deposit-for-your-validator) of our validator guide before carrying on.
We'll use the `scp` command to send files over SSH. 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. It allows you to copy files between computers, say from your Raspberry Pi to your desktop/laptop, or vice-versa.

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

@ -74,9 +74,8 @@ One might consider here to [set up a systemd service](./beacon-node-systemd.md)
It might require some time before these enter and are activated on the beacon chain. It might require some time before these enter and are activated on the beacon chain.
If one does this before the node which will attest and propose using those validators has synced, one might miss attestations and block proposals. If one does this before the node which will attest and propose using those validators has synced, one might miss attestations and block proposals.
7. [Import the validator keys](./keys.md) you receive into Nimbus. 7. Follow our validating guide from [step 2 (import the validator keys) onward](./run-a-validator.md#2-import-your-validator-keys).
8. [Start validating](./connect-eth2.md) with the imported keys.
## Useful resources ## Useful resources

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

@ -10,16 +10,214 @@ This is a simple, safe and efficient way to get started.
While not needed, advanced users may want to use a [separate validator client](./validator-client.md) instead. While not needed, advanced users may want to use a [separate validator client](./validator-client.md) instead.
## Steps
1. [Make a deposit](./deposit.md) for your validator. ## Overview
2. [Import your validator keys](./keys.md) into Nimbus. To start validating, you need to do these three steps, explained in more detail below:
3. [Start performing validator duties](./connect-eth2.md) by restarting the node. 1. [Make a deposit](./run-a-validator.md#1-make-a-deposit-for-your-validator) for your validator.
2. [Import your validator keys](./run-a-validator.md#2-import-your-validator-keys) into Nimbus.
3. [Start performing validator duties](./run-a-validator.md#3-start-validating) by restarting the node.
## 1. Make a deposit for your validator
To make a deposit, you will need to generate keys then submit a deposit transaction to the execution chain.
!!! tip "Launchpad"
The process of setting up a validator is also documented at the Ethereum launchpad site:
* [Mainnet](https://launchpad.ethereum.org/)
* [Goerli/Prater EthStaker Launchpad](https://goerli.launchpad.ethstaker.cc/en/) or [Goerli/Prater EF Launchpad](https://prater.launchpad.ethereum.org/)
!!! tip
Before running your validator on Mainnet, you can (and should) verify that your setup works as expected by running it on the [Prater testnet](./prater.md).
### 1. Download the deposit tool
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
cd nimbus-eth2
# Make sure to get the latest version from the download page
wget https://github.com/ethereum/staking-deposit-cli/releases/download/v2.2.0/staking_deposit-cli-9ab0b05-linux-amd64.tar.gz
# Unpack the archive
tar xvf staking_deposit-cli-9ab0b05-linux-amd64.tar.gz --strip-components 2
```
### 2. Generate keys
!!! tip "Live image"
You can increase the security of this process by downloading a [Live Linux image](https://ubuntu.com/tutorials/try-ubuntu-before-you-install). To do so, copy `deposit` to a USB stick, boot into the live image, and run the tool from inside the image.
Make sure you **don't** enable Wi-Fi and unplug any Ethernet cables when using this process.
The deposit tool generates a seed phrase, and uses this to create validator and withdrawal keys.
!!! danger "Seed phrase"
If you lose you seed phrase and your withdrawal key, your funds will be lost forever!
=== "Mainnet"
```sh
# Run the deposit tool and follow the instructions on screen
./deposit new-mnemonic --chain mainnet
```
=== "Prater"
```sh
# Run the deposit tool and follow the instructions on screen
./deposit new-mnemonic --chain prater
```
### 3. Make the deposit
Once created, the keys are used to create a deposit transaction on the Ethereum execution chain.
Follow the instructions [here](https://launchpad.ethereum.org/en/upload-deposit-data) to upload the deposit data.
!!! warning
If you are making a mainnet deposit make sure you verify that the deposit contract you are interacting with is the correct one.
You should verify that the address is indeed: [0x00000000219ab540356cBB839Cbe05303d7705Fa](https://etherscan.io/address/0x00000000219ab540356cBB839Cbe05303d7705Fa)
Once you send off your transaction(s), before your validator starts producing blocks and attestations, there are two waiting periods.
First, you wait for the beacon chain to recognize the block containing the deposit.
This usually takes around 13 hours.
Then, you wait in the queue for validator activation.
Getting through the queue may take a few hours or days (assuming the chain is finalizing).
No validators are accepted into the validator set while the chain isn't finalizing.
The `Pending Validators` metric on the [beaconcha.in](https://beaconcha.in/) will give you the size of the queue.
With the keys created, you're ready for the next step: importing your validator keys.
## 2. Import your validator keys
!!! tip
`systemd` service file users will want to follow the [service file guide](./beacon-node-systemd.md#import-validator-keys) instead!
By finishing the first step, you will have a `validator_keys` folder containing several `.json` files in the `nimbus-eth2` directory.
We'll import the signing key of each validator to the [data directory](./data-dir.md) using the `deposits import` command:
!!! note ""
You'll be asked to enter the password you used when creating your keystore(s).
=== "Mainnet"
```sh
build/nimbus_beacon_node deposits import --data-dir=build/data/shared_mainnet_0
```
=== "Prater"
```sh
build/nimbus_beacon_node deposits import --data-dir=build/data/shared_prater_0
```
On success, a message will be printed that your keys have been imported:
```
NOT 2022-07-19 17:36:37.578+02:00 Keystore imported
```
!!! note ""
`NOT` is short for `NOTICE` and not not :)
After importing keys, it is time to [restart the node](./run-a-validator.md#3-start-validating) and check that the keys have been picked up by the beacon node.
!!! info "All the keys"
You can read more about the different types of keys [here](https://blog.ethereum.org/2020/05/21/keys/) — the `deposits import` command will import the **signing key** only.
### Command line
If your `validator_keys` folder is stored elsewhere, you can pass its location to the import command:
=== "Mainnet"
```sh
build/nimbus_beacon_node deposits import \
--data-dir=build/data/shared_mainnet_0 \
/path/to/keys
```
=== "Prater"
```sh
build/nimbus_beacon_node deposits import \
--data-dir=build/data/shared_prater_0 \
/path/to/keys
```
Replacing `/path/to/keys` with the full pathname of where the `validator_keys` directory is found.
### Optimized import for a large number of validators
If you plan to use a large number of validators (e.g. more than 100) on a single beacon node or a validator client, you might benefit from running the `deposits import` command with the option `--method=single-salt`.
This will force Nimbus to use the same password and random salt value when encrypting all of the imported keystores which will later enable it to load the large number of validator keys almost instantly.
The theoretical downside of using this approach is that it makes the brute-force cracking of all imported keystores computationally equivalent to cracking just one of them.
Nevertheless, the security parameters used by Ethereum are such that cracking even a single keystore is considered computationally infeasible with current hardware.
### Troubleshooting
If you come across an error, make sure that:
* You are using the correct [data directory](./data-dir.md).
For `systemd` users, look for the `--data-dir` option in the `.service` file.
* You are running the command as the correct user.
For `systemd` users, look for the `User=` option in the `.service`. Assuming the user is called `nimbus`, prefix all commands with: `sudo -u nimbus`.
* Permissions for the data directory are wrong.
See [folder permissions](./data-dir.md#permissions) for how to fix this.
## 3. Start validating
Once your keys have been imported, it is time to configure a [fee recipient](./suggested-fee-recipient.md) and restart the beacon node to start validating.
### 1. Choose a fee recipient
The [fee recipient](./suggested-fee-recipient.md) is an Ethereum address that receives transaction fees from the blocks that your validators produce.
You can set up a separate address or reuse the address from which you funded your deposits.
### 2. (Re)start the node
Press `Ctrl-c` to stop the beacon node if it's running, then use the same command as before to run it again, this time adding the `--suggested-fee-recipient` option in addition to `--web3-url`:
=== "Mainnet"
```sh
./run-mainnet-beacon-node.sh --web3-url=http://127.0.0.1:8551 --suggested-fee-recipient=0x...
```
=== "Prater"
```sh
./run-prater-beacon-node.sh --web3-url=http://127.0.0.1:8551 --suggested-fee-recipient=0x...
```
### 3. Check the logs
Your beacon node will launch and connect your validator to the beacon chain network.
To check that keys were imported correctly, look for `Local validator attached` in the logs:
```
INF 2020-11-18 11:20:00.181+01:00 Launching beacon node
...
NOT 2020-11-18 11:20:02.091+01:00 Local validator attached
```
Congratulations! 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! Your node is now ready to perform validator duties and earning a small amount of ETH every 6.4 minutes in return for keeping the Ethereum network secure!
Depending on when the deposit was made, it may take a while before the first attestation is sent — this is normal.
!!! success "What next?" !!! 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. 💫 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. 💫