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: migration guide update (#3316) 

* rest api: first draft

* minor edit

* add lighthouse export

* add teku

* cp

* cp

* fix merge conflict"

* fix typo

* incorporate feedback

* correct path mistake
This commit is contained in:
sacha 2022-01-25 15:16:50 +01:00 committed by GitHub
parent efbd939108
commit ed38b187cc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 101 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,23 +1,39 @@
# Migrate 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*.
## Step 1 - Sync the beacon node
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.
**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.
## Step 1 - Sync the Nimbus beacon node
No matter which client you are migrating over from, the first step is to sync the Nimbus beacon node.
The easiest way to do this is to follow the [beacon node quick start guide](./quick-start.md). Syncing the beacon node might take up to 30h 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). 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.
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.
## Step 2 - Stop your existing client and export your slashing protection history
## Step 2 - Export your slashing protection history
> Hat tip to Michael Sproul for his [wonderful guide](https://lighthouse.sigmaprime.io/switch-to-lighthouse.html) on how to migrate from Prysm to Lighthouse.
### From Prysm
#### 1. Disable the Prysm validator client
### Export from Prysm
**1. Disable the Prysm validator client**
Once your Nimbus beacon node has synced and you're satisfied that it's working, stop and disable the Prysm validator client (you can also stop the Prysm beacon node if you wish).
Stop and disable the Prysm validator client (you can also stop the Prysm beacon node if you wish).
If you're using systemd and your service is called `prysmvalidator`, run the following commands to stop and disable the service:
@ -29,9 +45,7 @@ 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.
</br>
**2. Export slashing protection history**
#### 2. Export slashing protection history
Run the following to export your Prysm validator's [slashing protection](https://eips.ethereum.org/EIPS/eip-3076) history:
@ -41,13 +55,75 @@ prysm.sh validator slashing-protection export \
--slashing-protection-export-dir=/path/to/export_dir
```
To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator have stopped attesting (check [beaconcha.in](https://beaconcha.in/)).
You will then find the `slashing-protection.json` file in your specified `/path/to/export_dir` folder.
</br>
> **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).
### Export from Nimbus
### From Lighthouse
**1. Disable the Nimbus validator client**
#### 1. Disable the Lighthouse validator client
The validator client needs to be stopped in order to export, to guarantee that the data exported is up to date.
If you're using systemd and your service is called `lighthousevalidator`, run the following command to stop and disable the service:
```
sudo systemctl stop lighthousevalidator
sudo systemctl disable lighthousevalidator
```
You may also wish to stop the beacon node:
```
sudo systemctl stop lighthousebeacon
sudo systemctl disable lighthousebeacon
```
*It's important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.*
#### 2. Export slashing protection history
You can export Lighthouse's database with this command:
```
lighthouse account validator slashing-protection export slashing-protection.json
```
This will export your history in the correct format to `slashing-protection.json`.
> **Tip:** To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check it's recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
### From Teku
#### 1. Disable Teku
If you're using systemd and your service is called `teku`, run the following command to stop and disable the service:
```
sudo systemctl stop teku
sudo systemctl disable teku
```
*It's important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.*
#### 2. Export slashing protection history
You can export Teku's database with this command:
```
teku slashing-protection export --data-path=/home/me/me_node --to=/home/slash/slashing-protection.json
```
Where:
- `--data-path` specifies the location of the Teku data directory.
- `--to` specifies the file to export the slashing-protection data to (in this case `/home/slash/slashing-protection.json`).
> **Tip:** To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check it's recent history on [beaconcha.in](https://beaconcha.in/)). Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
### From Nimbus
#### 1. Disable the Nimbus validator client
Once your Nimbus beacon node on your new setup has synced and you're satisfied that it's working, stop and disable the Nimbus validator client on your current setup.
@ -58,27 +134,19 @@ sudo systemctl stop nimbus-eth2-mainnet.service
sudo systemctl disable nimbus-eth2-mainnet.service
```
It's important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.
*It's important that you disable the service as well as stopping it, to prevent it from starting up again on reboot.*
</br>
**2. Export slashing protection history**
#### 2. Export slashing protection history
Run the following to export your Nimbus validator's [slashing protection](https://eips.ethereum.org/EIPS/eip-3076) history:
```
build/nimbus_beacon_node slashingdb export database.json
build/nimbus_beacon_node slashingdb export slashing-protection.json
```
This will export your history in the correct format to `database.json`.
This will export your history in the correct format to `slashing-protection.json`.
To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator have stopped attesting (check `beaconcha.in`).
### Export from Lighthouse
*coming soon*
### Export from Teku
*coming soon*
> **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
@ -94,7 +162,7 @@ To import you validator key(s), follow the instructions [outlined here](./keys.m
To import the slashing protection history you exported in **step 3**, from the `nimbus-eth2` directory run:
```
build/nimbus_beacon_node slashingdb import path/to/export_dir/database.json
build/nimbus_beacon_node slashingdb import path/to/export_dir/slashing-protection.json
```
Replacing `/path/to/export_dir` with the file/directory you specified when you exported your slashing protection history.
@ -115,3 +183,5 @@ If you are unsure of the safety of a step, please get in touch with us directly