Sacha book updates (ready for review) (#2552)

* add doppelganger detection explanation to FAQ and link to Joe's guide from our Pi guide

* Edit CLI options page

* cp

* merge with ith unstable

* prysm migration guide: add steps until import slashing db

* update systemd

* update troubleshooting

* update pi guide

* metrics: replace winners with community

* update migration guide

* cp

* progress with guides, various edits

docs/the_nimbus_book/src/SUMMARY.md

@@ -29,7 +29,6 @@
 - [Graffiti the blockchain](./graffiti.md)
 - [Download binaries](./binaries.md)
 - [Download Docker images](./docker.md)
-- [Troubleshoot](./troubleshooting.md)
 - [Recover / generate keys](./more-keys.md)
 - [Perform a voluntary exit](./voluntary-exit.md)
 - [Set up a systemd service](./beacon-node-systemd.md)
@@ -38,6 +37,7 @@
 - [Back up your database](./database-backup.md)
 - [Add a backup web3 provider](./web3-backup.md)
 - [Add an additional validator](./additional-validator.md)
+- [Migrate from another client](./migration.md)
 
 # Tutorials
 - [Grafana and Prometheus](./metrics-pretty-pictures.md)
@@ -46,7 +46,9 @@
 
 # Reference
 - [API](./api.md)
-- [Command line options](./options.md)
+- [Help / Command line options](./options.md)
+- [Advanced migration options](./migration-options.md)
+- [Troubleshooting](./troubleshooting.md)
 - [For developers](./developers.md)
 - [FAQ](./faq.md)
 - [Contribute](./contribute.md)

docs/the_nimbus_book/src/beacon-node-systemd.md

@@ -12,6 +12,8 @@ Systemd is used in order to have a command or program run when your device boots
 
 Create a `systemd` service unit file -- `nimbus-eth2-pyrmont.service` -- and save it in `/etc/systemd/system/`.
 
+The contents of the file should look like this:
+
 ```txt
 [Unit]
 Description=Nimbus beacon node
@@ -33,13 +35,15 @@ Restart=always
 WantedBy=default.target
 ```
 
-Replace:
+Where you should replace:
 
-`<BASE-DIRECTORY>` with the location of the repository in which you performed the `git clone` command in step 1.
+`<BASE-DIRECTORY>` with the location of the `nimbus-eth2` repository on your device.
 
 `<USERNAME>` with the username of the system user responsible for running the launched processes.
 
-`<WEB3-URL>` with the WebSocket JSON-RPC URL that you are planning to use.
+`<WEB3-URL>` with the WebSocket JSON-RPC URL you are planning to use.
+
+> **N.B.** If you're running Nimbus on a Pi, your `<BASE-DIRECTORY>` is `/home/pi/nimbus-eth2/` and your `<USERNAME>` is `pi`
 
 
 ### 2. Notify systemd of the newly added service
@@ -53,3 +57,13 @@ sudo systemctl daemon-reload
 ```console
 sudo systemctl enable nimbus-eth2-pyrmont --now
 ```
+
+### 4. Monitor the service
+
+```console
+sudo journalctl -u nimbus-eth2-pyrmont.service
+```
+
+This will show you the Nimbus logs at the default setting -- it should include regular "slot start" messages which will show your sync progress.
+
+For more options, see [here](https://www.raspberrypi.org/documentation/linux/usage/systemd.md).

docs/the_nimbus_book/src/faq.md

@@ -10,6 +10,25 @@ The metrics server is disabled by default, enable it by passing `--metrics` to t
 ./run-mainnet-beacon-node.sh --metrics ...
 ```
 
+### Why does my validator miss two epochs of attestations after restarting?
+
+When a validator is started (or restarted) it prudently listens for 2 epochs for attestations from a validator with the same index (a doppelganger), before sending an attestation itself.
+
+In sum, it's a simple way of handling the case where one validator comes online with the same key as another validator that's already online (i.e one device was started without switching the other off).
+
+While this strategy requires the client to wait two whole epochs on restart before attesting, a couple of missed attestations is a very minor price to pay in exchange for significantly reducing the risk of an accidental slashing.
+
+You can think of it as a small penalty that you pay only on first launch and restarts. When you take into account the total runtime of your validator, the impact should be minimal.
+
+While we strongly recommend it, you can disable it with an explicit flag (`--doppelganger-detection=false`) if you don't plan on moving your setup.
+
+### What's the best way to stress test my eth1 + eth2 setup before committing with real ETH?
+
+We recommend [running a Nimbus beacon node](./quick-start.md) on [Prater](./prater.md) and a mainnet [eth1 client](./eth1.md) on the same machine.
+
+To stress test it, `add--subscribe-all-subnets` to the [beacon node options](./options.md). This represents more or less the maximum load you could have on eth2.
+
+
 ## Validating
 
 ### What exactly is a validator?

docs/the_nimbus_book/src/intro.md

@@ -1,6 +1,6 @@
 # The Nimbus book
 
-*If you're eager to get started, check out our [quickstart guide](./quick-start.md).*
+*If you're eager to get started, check out our [quickstart guide](./quick-start.md)*
 
 Nimbus is a client implementation for both Ethereum 2.0 and Ethereum 1.0 that strives to be as lightweight as possible in terms of resources used. This allows it to perform well on embedded systems, resource-restricted devices -- including Raspberry Pis and mobile devices.
 

docs/the_nimbus_book/src/metrics-pretty-pictures.md

@@ -171,7 +171,7 @@ You'll be directed to the dashboard where you'll be able to gain insights into t
 And voila! That's all there is to it :)
 
 
-## Recommended setups (Nimbus dashboard challenge winners)
+## Community dashboards
 
 ### Joe Clapis
 

docs/the_nimbus_book/src/migration-options.md

@@ -0,0 +1,73 @@
+# Advanced migration options
+
+
+## Import validators
+
+The default command for importing your validator's slashing protection history into the database is:
+
+```
+build/nimbus_beacon_node slashingdb import database.json
+```
+
+However, there are a couple of advanced options you can also use -- for example if you wish to import a validator to a specific validator directory.
+
+### Import to a specific validators directory
+
+The validator directory contains your validator's setup.
+
+```
+build/nimbus_beacon_node slashingdb import database.json --validators-dir=path/to/validatorsdir/
+```
+
+### Import to a specific data directory
+
+The data directory contains your beacon node's setup.
+
+```
+build/nimbus_beacon_node slashingdb import database.json --data-dir=path/to/datadir/
+```
+
+## Export validators
+
+The default command for exporting your slashing protection history is:
+
+```
+build/nimbus_beacon_node slashingdb export database.json
+```
+
+This will export your history in the correct format to `database.json`.
+
+On success you will have a message similar to:
+
+```
+Exported slashing protection DB to 'database.json'
+Export finished: '$HOME/.cache/nimbus/BeaconNode/validators/slashing_protection.sqlite3' into 'interchange.json'
+```
+
+### Export from a specific validators directory
+
+The validator directory contains your validator's setup.
+
+```
+build/nimbus_beacon_node slashingdb export database.json --validators-dir=path/to/validatorsdir/
+```
+
+### With the data-dir folder
+
+The data-dir contains your beacon node setup.
+
+```
+build/nimbus_beacon_node slashingdb export database.json --data-dir=path/to/datadir/
+```
+
+## Partial exports
+
+You can perform a partial export by specifying the public key of the relevant validator you wish to export.
+
+```
+build/nimbus_beacon_node slashingdb export database.json --validator=0xb5da853a51d935da6f3bd46934c719fcca1bbf0b493264d3d9e7c35a1023b73c703b56d598edf0239663820af36ec615
+```
+
+If you wish to export multiple validators, you must specify the `--validator` option multiple times.
+
+

docs/the_nimbus_book/src/migration.md

@@ -0,0 +1,112 @@
+# Migrate from another client
+
+
+*See [here](./migration-options.md) for advanced options*
+
+## Step 1 - Sync the Nimbus beacon node
+No matter which client you are migrating over from, the first step is to sync the beacon node.
+
+The easiest way to do this is to follow the [Nimbus quickstart guide](./quick-start.md).  Syncing the beacon node might take up to 30h depending on your hardware, so you should keep validating using your current setup until it completes.
+
+
+## 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.
+
+
+### 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).
+
+
+If you're using systemd and your service is called `prysmvalidator`, run the following commands to stop and disable the service:
+
+```
+sudo systemctl stop prysmvalidator.service
+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**
+
+Run the following to export your Prysm validator's [slashing protection](https://eips.ethereum.org/EIPS/eip-3076) history:
+
+```
+prysm.sh validator slashing-protection export --datadir=/your/prysm/wallet --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/)).
+
+</br>
+
+### Export 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. 
+
+If you're using systemd and your service is called `nimbus-eth2-mainnet`, run the following commands to stop and disable the service:
+
+```
+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.
+
+</br>
+
+**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
+```
+
+This will export your history in the correct format to `database.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*
+
+
+## Step 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/`.
+
+## Step 4 - Import your slashing protection history
+
+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
+```
+
+Replacing `/path/to/export_dir` with the file/directory you specified when you exported your slashing protection history.
+
+## Step 5 - Start the Nimbus validator
+
+Follow the instructions [here](./connect-eth2.html) to start your validator using our pre-built [binaries](./binaries.md).
+
+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.
+
+
+
+

docs/the_nimbus_book/src/options.md

@@ -6,10 +6,10 @@ You can pass any `nimbus_beacon_node` options to the `pyrmont` and `mainnet` scr
 ./run-mainnet-beacon-node.sh --tcp-port=9100 --udp-port=9100
 ```
 
-To see a list of the command line options availabe to you, with descriptions, navigate to the `build` directory and run:
+To see a list of the command line options availabe to you, with descriptions, run:
 
 ```
-./nimbus_beacon_node --help
+build/./nimbus_beacon_node --help
 ```
 
 You should see the following output:

docs/the_nimbus_book/src/pi-guide-mainnet.md

@@ -8,5 +8,16 @@ The best thing you can do is to set your Pi to run Pyrmont. **If you have no tro
 
 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.
 
-Finally in order to make sure your Pi autorestarts on boot, we recommend [setting up a systemd service](https://www.raspberrypi.org/documentation/linux/usage/systemd.md). For the details on how to do this, see [this page](./beacon-node-systemd.md)
+
+### Systemd
+
+In order to make sure your Pi autorestarts on boot, we recommend [setting up a systemd service](https://www.raspberrypi.org/documentation/linux/usage/systemd.md). For the details on how to do this, see [this page](./beacon-node-systemd.md).
+
+
+### 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://github.com/jclapis/rp-pi-guide/blob/main/Overclocking.md) 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).
+
 

docs/the_nimbus_book/src/pi-guide.md

@@ -2,6 +2,9 @@
 
 <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://github.com/jclapis/rp-pi-guide/blob/main/Overview.md) 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 **Pyrmont testnet**.
 
@@ -26,6 +29,9 @@ One of the most important aspects of the Raspberry Pi experience is trying to ma
 > 2. Use an USB 3.0 External Hard Drive Case with a SSD Disk. For example, [Ethereum on Arm](https://twitter.com/EthereumOnARM) use an Inateck 2.5 Hard Drive Enclosure FE2011. Make sure to buy a case with an UASP compliant chip, particularly, one of these: JMicron (JMS567 or JMS578) or ASMedia (ASM1153E).
 >
 > In both cases, avoid low quality SSD disks (the SSD is a key component of your node and can drastically affect both the performance and sync time). Keep in mind that you need to plug the disk to an USB 3.0 port (the blue port).
+>
+> **N.B**
+> *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)*
 
 ### 1. Download Raspberry Pi Imager
 
@@ -249,16 +255,8 @@ To do so, run:
 sudo apt-get install git
 
 ```
-### 12. Install Screen
 
-`screen` is a tool that lets you safely detach from the SSH session without exiting the remote job. In other words `screen` allows the commands you run on your Pi from your laptop to keep running after you've logged out.
-
-Run the following command to install `screen`:
-```
-sudo apt-get install screen
-```
-
-### 13. Clone the Nimbus repository
+### 12. Clone the Nimbus repository
 
 Run the following command to clone the [nimbus-eth2 repository](https://github.com/status-im/nimbus-eth2):
 
@@ -266,7 +264,7 @@ Run the following command to clone the [nimbus-eth2 repository](https://github.c
 git clone https://github.com/status-im/nimbus-eth2
 ```
 
-### 14. Build the beacon node
+### 13. Build the beacon node
 
 Change into the directory and build the beacon node.
 ```
@@ -276,7 +274,7 @@ make nimbus_beacon_node
 
 *Patience... this may take a few minutes.*
 
-### 15. Copy signing key over to Pi
+### 14. 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.
 
@@ -296,7 +294,7 @@ As usual, replace `195.177.101.93` with your Pi's IP address, and `<VALIDATOR_KE
  > **Tip:** run `pwd` in your `validator_keys` directory to print the full pathname to the console.
 
 
-### 16. Import signing key into Nimbus
+### 15. Import signing key into Nimbus
 
 To import your signing key into Nimbus, from the `nimbus-eth2` directory run:
 
@@ -306,46 +304,8 @@ build/nimbus_beacon_node deposits import  --data-dir=build/data/shared_pyrmont_0
 
  You'll be asked to enter the password you created to encrypt your keystore(s). Don't worry, this is entirely normal. Your validator client needs both your signing keystore(s) and the password encrypting it to import your [key](https://blog.ethereum.org/2020/05/21/keys/) (since it needs to decrypt the keystore in order to be able to use it to sign on your behalf).
 
-### 17. Run Screen
 
-From the `nimbus-eth2` directory, run:
-```
-screen
-```
-
-You should see output that looks like the following:
-```
-GNU Screen version 4.06.02 (GNU) 23-Oct-17
-
-Copyright (c) 2015-2017 Juergen Weigert, Alexander Naumov, Amadeusz Slawinski
-Copyright (c) 2010-2014 Juergen Weigert, Sadrul Habib Chowdhury
-Copyright (c) 2008-2009 Juergen Weigert, Michael Schroeder, Micah Cowan, Sadrul Habib Chowdhury
-Copyright (c) 1993-2007 Juergen Weigert, Michael Schroeder
-Copyright (c) 1987 Oliver Laumann
-
-This program is free software; you can redistribute it and/or modify it under the terms of the GNU
-General Public License as published by the Free Software Foundation; either version 3, or (at your
-option) any later version.
-
-This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
-the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
-License for more details.
-
-You should have received a copy of the GNU General Public License along with this program (see the file
-COPYING); if not, see http://www.gnu.org/licenses/, or contact Free Software Foundation, Inc., 51
-Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA.
-
-Send bugreports, fixes, enhancements, t-shirts, money, beer & pizza to screen-devel@gnu.org
-
-
-Capabilities:
-+copy +remote-detach +power-detach +multi-attach +multi-user +font +color-256 +utf8 +rxvt
-+builtin-telnet
-```
-
-Press `Enter` or `Space`.
-
-### 18. Connect to Pyrmont
+### 16. Connect to Pyrmont
 
 We're finally ready to connect to Pyrmont!
 
@@ -372,7 +332,7 @@ Please enter a Web3 provider URL:
 
 Enter your own secure websocket (`wss`) [endpoint](eth1.md).
 
-### 19. Check for successful connection
+### 17. 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:
 
@@ -402,15 +362,12 @@ 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 `Pyrmont` 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.
 
-### 20. End ssh session and logout
-
-To detach your `screen` session but leave your processes running, press `Ctrl-A` followed by `Ctrl-D`. You can now exit your `ssh` session (`Ctrl-C`) and switch off your laptop.
-
-Verifying your progress is as simple as `ssh`ing back into your Pi and typing `screen -r`. This will resume your screen session (and you will be able to see your node's entire output since you logged out).
 
 ### Professional setup advice
 
-While `screen` is a nice tool for testing, it's not really a good idea to rely on it for serious use. For a more professional setup, 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). 
+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). 
 
-For the details on how to do this, see [this page](./beacon-node-systemd.md).
+Systemd will also ensure your validator keeps running when you exit your ssh session (`Ctrl-C`) and/or switch off your laptop.
+
+For the details on how to set up a systemd service, see [this page](./beacon-node-systemd.md).
 

docs/the_nimbus_book/src/troubleshooting.md

@@ -3,7 +3,7 @@
 > ⚠️  The commands on this page refer to the Pyrmont testnet. If you're running mainnet, replace `pyrmont` with `mainnet` in the commands below.
 
 
-As it stands, we are continuously making improvements to both stability and memory usage. So please make sure you keep your client up to date! This means restarting your node and updating your software regularly from the `master` branch. If you can't find a solution to your problem here, feel free to hit us up on our [discord](https://discord.com/invite/XRxWahP)!
+As it stands, we are continuously making improvements to both stability and memory usage. So please make sure you keep your client up to date! This means restarting your node and updating your software regularly from the `stable` branch. If you can't find a solution to your problem here, feel free to hit us up on our [discord](https://discord.com/invite/XRxWahP)!
 
 > **Note:** While the `stable` branch of the `nimbus-eth2` repository is more stable, the latest updates happen in the `unstable` branch which is (usually) merged into master every week on Tuesday. If you choose to run Nimbus directly from the `unstable` branch, be prepared for instabilities!
 
@@ -91,6 +91,19 @@ The first line in the output will give you internet time. And the second line wi
 
 ### Eth1 chain monitor failure
 
-*todo*
+If you see an error that looks like the following:
+
+```
+{"lvl":"ERR","ts":"2021-05-11 09:05:53.547+00:00","msg":"Eth1 chain monitoring failure, restarting","topics":"eth1","tid":1,"file":"eth1_monitor.nim:1158","err":"Trying to access value with err: Failed to setup web3 connection"}
+```
+
+It's because your node can't connect to the web3 provider you have specified. Please double check that you've correctly specified your provider. If you haven't done so already, we recommend [adding a backup](web3-backup.md).
+
+## Raspberry Pi
+
+### Trouble transferring data to/from USB3.0 SSDs
+
+We have seen reports of extremely degraded performance when using several types of USB3.0 to SSD adapter or when using native USB3.0 disk drives. [This post](https://www.raspberrypi.org/forums/viewtopic.php?t=245931#p1501426) details why there is a difference in behaviour from models prior to Pi 4 and the recommended workaround.
+