Medalla guide updates + troubleshooting page (#1571)

* book updates

* troubleshooting: introduce devel branch, and link to discord

* add disclaimer and recommendation to fall back to master

* minor edits

docs/the_nimbus_book/src/.medalla-troubleshooting.md

@@ -0,0 +1 @@
+# Troubleshooting Medalla

docs/the_nimbus_book/src/SUMMARY.md

@@ -2,12 +2,13 @@
 - [Introduction](./intro.md)
 - [Installation](./install.md)
 - [Become a Medalla validator](./medalla.md)
-- [Run the beacon node](./beacon_node.md)
+- [Troubleshooting Medalla](./medalla-troubleshooting.md)
+- [Running the beacon node](./beacon_node.md)
 - [API](./api.md)
 # Advanced
 - [For developers](./advanced.md)
-- [Set up a systemd service](./beacon_node_systemd.md)
+- [Setting up a systemd service](./beacon_node_systemd.md)
-- [Generate your keys with Nimbus](./create_wallet_and_deposit.md)
+- [Generating your keys with NBC](./create_wallet_and_deposit.md)
 # Misc
 - [Windows users]()
 - [FAQ](./faq.md)

docs/the_nimbus_book/src/create_wallet_and_deposit.md

@@ -1,4 +1,4 @@
-# Generate your keys with NBC
+# Generating your keys with NBC
 
 In this chapter, we'll take you through how to create an [EIP-2386](https://github.com/ethereum/EIPs/blob/4494da0966afa7318ec0157948821b19c4248805/EIPS/eip-2386.md) wallet to help you generate your validator keys (keystores), create a `deposits_data` file compatible with the Ethereum Foundation's [Validator Launchpad](https://medalla.launchpad.ethereum.org/), and use the launchpad to send this data to the eth1 network so that your validator can be registered.
 

docs/the_nimbus_book/src/medalla-troubleshooting.md

@@ -0,0 +1,49 @@
+# Troubleshooting Medalla
+
+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 `devel` branch (we recommend doing this at least once a day). 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 `master` branch of the `nim-beacon-chain` repository is more stable, the latest updates happen in the `devel` branch which is (usually) merged into master every week on Tuesday.
+
+To update and restart, run `git pull`, `make update`, followed by `make medalla`:
+
+```
+cd nim-beacon-chain
+git checkout devel
+git pull
+make update # Update dependencies
+make medalla # Restart using same keys as last run
+```
+
+If you find that `make update` causes the console to hang for too long, try running `make update V=1` or `make update V=2` instead (these will print a more verbose output to the console which may make it easier to diagnose the problem).
+
+If, after updating to the latest `devel`, you feel like your node is functioning significantly worse than before, we recommend you report the problem on [discord](https://discord.com/invite/XRxWahP), switch to `master`, and rebuild.
+
+>**Note:** rest assured that when you restart the beacon node, the software will resume from where it left off, using the validator keys you have already imported.
+
+
+### Starting over
+
+The directory that stores the blockchain data of the testnet is `build/data/shared_medalla_0` (if you're connecting to another testnet, replace `medalla` with that testnet's name). Delete this folder to start over (for example, if you started building medalla with the wrong private keys).
+
+### Syncing
+If you’re experiencing sync problems, or have been running an old version of medalla, we recommend running `make clean-medalla` to restart your sync (make sure you’ve updated to the latest `devel` branch first though).
+
+### Keeping up with the head of the chain
+
+As it stands, logging seems to be slowing down the client,  and quite a few users are experiencing trouble either catching up or keeping up with the head of the chain. You can use the `LOG_LEVEL=INFO` option to reduce verbosity and speed up the client.
+
+```
+make LOG_LEVEL=INFO medalla
+```
+
+### Low peer counts
+
+If you're experiencing a low peer count, you may be behind a firewall. Try restarting your client and passing `NODE_PARAMS="--nat:\"extip:$EXT_IP_ADDRESS\"` as an option to `make medalla`, where `$EXT_IP_ADDRESS` is your real IP. For example, if your real IP address is `35.124.65.104`, you'd run:
+
+```
+make NODE_PARAMS="--nat:\"extip:35.124.65.104\" medalla
+```
+
+### Resource leaks
+
+If you're experiencing RAM related resource leaks, try restarting your client (**we recommend restarting every 6 hours** until we get to the bottom of this issue). If you have a [local Grafana setup](https://github.com/status-im/nim-beacon-chain#getting-metrics-from-a-local-testnet-client), you can try monitoring the severity of these leaks and playing around with the restart interval.

docs/the_nimbus_book/src/medalla.md

@@ -104,15 +104,6 @@ Once the update is complete, run `make medalla` to reconnect to the network.
 
 Looking forward to seeing you on Medalla! 💛
 
-### A note on keys
-
-The Nimbus client will only ever import your signing key -- in any case, if you used the deposit launchpad, this is the only key you should have (you can generate the withdrawal key from your mnemonic when you wish to withdraw).
-
-The keys your Nimbus client has access to are stored in the `build/data/shared_medalla_0/` folder, under `secrets` and `validators`.
-
-The `secrets` folder contains the common secret that gives you access to all your validator keys. And the `validators` folder contains your keystores.
-
-For more on keys in eth2, see [here](https://blog.ethereum.org/2020/05/21/keys/).
 
 ## Advanced options
 
@@ -126,6 +117,12 @@ make medalla NODE_ID=1
 make medalla NODE_ID=2
 ```
 
+### Attach multiple validators to the same beacon node
+
+Simply [import as many keystores as you wish](./medalla.md#3-import-keystores) before running `make medalla`. Nimbus will automagically find your keys and attach your validators. See [key management](./medalla.md#key-management) for more information on where we store your keys.
+
+To give you some context, we (the Nimbus team) are currently running 170 validators per beacon node on our AWS instances.
+
 ### Change the TCP and UDP ports
 
 To change the TCP and UDP ports from their default value of 9000 to 9100, say, run:
@@ -143,27 +140,16 @@ You may need to do this if you are running another client.
 make medalla-deposit VALIDATORS=2 # default is just 1
 ```
 
-### Upgrading
-
-When you restart the beacon node, the software will resume from where it left off, using your previous deposits.
-
-```
-cd nim-beacon-chain
-git pull
-make update # Update dependencies
-make medalla # Restart using same keys as last run
-```
 
 ## Key management
 
-Keys are stored in the `build/data/[testnet_name]/` folder, under `secrets` and `validators` - make sure you keep these folders backed up.
+Keys are stored in the `build/data/shared_medalla_0/` folder, under `secrets` and `validators` - make sure you keep these folders backed up.
 
 The `secrets` folder contains the common secret that gives you access to all your validator keys.
 
-The `validators` folder contains your keystores. Keystores are used by validators as a method for exchanging keys. 
+The `validators` folder contains your keystores (encrypted keys). Keystores are used by validators as a method for exchanging keys. For more on keys and keystores, see [here](https://blog.ethereum.org/2020/05/21/keys/).
-
-For more on keys in eth2, see [here](https://blog.ethereum.org/2020/05/21/keys/).
 
+>**Note:** The Nimbus client will only ever import your signing key -- in any case, if you used the deposit launchpad, this is the only key you should have (you can generate the withdrawal key from your mnemonic when you wish to withdraw).
 
 
 
@@ -181,14 +167,3 @@ http://localhost:8008/metrics
 
 Make sure this port is protected as the http server used is not considered secure (it should not be used by untrusted peers).
 
-## Troubleshooting
-
-1. The directory that stores the blockchain data of the testnet is `build/data/shared_medalla_0` (if you're connecting to another testnet, replace `medalla` with that testnet's name). Delete this folder if you want to start over (for example, if you entered a wrong private key).
-
-2. Currently, you have to switch to the `devel` branch in order to run the validator node successfully.
-
-3. Everytime you want to update your node to the latest version, run `git pull`, `make update`, and then `make medalla`.
-
-4. If `make update` causes the console to hang for too long, try running `make update V=1` or `make update V=2` instead (these will print a more verbose output to the console which may make it easier to diagnose the problem).
-
-5. If you’re experiencing sync problems, or have been running an old version of medalla, we recommend running `make clean-medalla` to restart your sync (make sure you’ve updated to the latest `devel` branch first though).