book edits (#1500)

Co-authored-by: Jacek Sieka <jacek@status.im>
Co-authored-by: zah <zahary@gmail.com>

docs/the_nimbus_book/src/SUMMARY.md

@@ -4,6 +4,7 @@
 - [Installation](./install.md)
 - [Become a Medalla validator](./medalla.md)
 - [Run the beacon node](./beacon_node.md)
+- [Wallet and deposit tools](./create_wallet_and_deposit.md)
 - [Become a validator (custom)](./validator.md)
 - [API](./api.md)
 - [Advanced usage for developers](./advanced.md)

docs/the_nimbus_book/src/advanced.md

@@ -130,3 +130,7 @@ make -j$(nproc) NIMFLAGS="-d:release" USE_MULTITAIL=yes eth2_network_simulation
 ```bash
 make USE_LIBBACKTRACE=0 # expect the resulting binaries to be 2-3 times slower
 ```
+
+### Multi-client interop scripts
+
+[This repository](https://github.com/eth2-clients/multinet) contains a set of scripts used by the client implementation teams to test interop between the clients (in certain simplified scenarios). It mostly helps us find and debug issues.

docs/the_nimbus_book/src/beacon_node.md

@@ -64,7 +64,6 @@ Time is shown as `epoch:subslot`, starting from the block chain genesis time - o
 The status bar content may be updated using command line flags.
 
 ### Metrics
-
 Nimbus includes metrics support using the Prometheus format. To enable it, you need to enable insecure feature when compiling the application. The http server that exports Prometheus metrics should not be exposed to external parties.
 
 ```
@@ -72,12 +71,16 @@ Nimbus includes metrics support using the Prometheus format. To enable it, you n
 make NIMFLAGS="-d:insecure" medalla
 ```
 
-## Command line options
+## Help
+To see a list of command line options with descriptions, navigate to the `build` directory and run:
 
 ```
-$ ./beacon_node --help
-Nimbus beacon node v0.3.0 (877a358)
+./beacon_node --help
+```
 
+You should see the following output:
+
+```
 Usage:
 
 beacon_node [OPTIONS]... command

docs/the_nimbus_book/src/create_wallet_and_deposit.md

@@ -0,0 +1,46 @@
+# Create a walletstore and make a deposit
+
+In this page we'll take you through how to create a walletstore and make a deposit (from now on we'll use the terms wallet and walletstore interchangeably)
+
+First, we'll create a wallet.
+
+> For our purposes, a wallet is the [EIP-2386](https://github.com/ethereum/EIPs/blob/4494da0966afa7318ec0157948821b19c4248805/EIPS/eip-2386.md) JSON file which contains an encrypted seed, a name, and a counter (`nextaccount`) that allows for creating validators (generating keystores) incrementally as outlined in [EIP-2334](https://eips.ethereum.org/EIPS/eip-2334) (Deterministic Account Hierarchy).
+
+The wallet we'll create will be [hierarchical deterministic](https://github.com/ethereum/EIPs/blob/4494da0966afa7318ec0157948821b19c4248805/EIPS/eip-2386.md).
+
+An HD wallet can create keys from a *seed* and a *path*. The encrypted seed is stored in the wallet (it needs to be accessible to create new keys). Further, HD wallets also have a mechanism (a `nextaccount` index) for maintaining state about which keys have been generated (to ensure keys are not duplicated).
+
+## When do I need to use a walletstore?
+
+If you're asking yourself this question then you probably don't need to use one :)
+
+To be clear, the purpose of a walletstore is to generate new validators. But you don't need a walletstore to do this.
+
+You can use the Ethereum Foundation's [launchpad](https://medalla.launchpad.ethereum.org/) or [deposit-cli](https://github.com/ethereum/eth2.0-deposit-cli) to do this without a walletstore.
+
+## Create  a wallet
+```
+build/beacon_node wallets create
+```
+
+*TO BE FILLED*
+
+## Create a deposit
+```
+build/beacon_node deposits create
+```
+
+*TO BE FILLED*
+
+*Creates a deposits_data file that should be compatible with the new Ethereum Launchpad.*
+
+- creates wallet
+- generates deposits
+- writes to deposit_data file
+
+> Note: when you create deposits with `deposits create`, you can reference an existing wallet or you can create a new one which will guide through the standard wallets create procedure.
+
+## Which keys do i pass to my validator client?
+
+Importantly, to run a validator you only need to pass the voting keystore which leaks nothing about the withdrawal key (except perhaps the path that it can be derived with).
+

docs/the_nimbus_book/src/intro.md

@@ -1,6 +1,4 @@
-# The nim-beacon-chain book
-
-_Documentation for Nimbus beacon chain users and developers._
+# The Nimbus beacon chain book
 
 The Nimbus beacon chain is a research implementation of the Beacon Chain – the core system level chain at the heart of Ethereum 2.0.
 

docs/the_nimbus_book/src/medalla.md

@@ -4,7 +4,9 @@ This page will take you through how to become a validator on the eth2 testnet [M
 
 If you generated your signing key using the [eth2 launchpad](https://medalla.launchpad.ethereum.org/), and wish to import it into the Nimbus client, this page is for you.
 
-> If you haven't created your validator key yet, we recommend you go through the [launchpad first](https://medalla.launchpad.ethereum.org/). If you're not sure what the eth2 launchpad is, we recommend reading this [introductory post](https://blog.ethereum.org/2020/07/27/eth2-validator-launchpad/).
+> If you haven't created your validator key yet, we recommend you do so using the [launchpad](https://medalla.launchpad.ethereum.org/). If you're not sure what the eth2 launchpad is, we recommend reading this [introductory post](https://blog.ethereum.org/2020/07/27/eth2-validator-launchpad/) first.
+
+For advanced users, [this page](./create_wallet_and_deposit.md)  explains how to use Nimbus to create a walletstore to generate your keys.
 
 ## Prerequisites
 
@@ -52,14 +54,13 @@ make medalla
 ```
 
 This will build Nimbus and its dependencies, and connect you to Medalla.
-You should see that the beacon node has launched with your validator attached and is waiting for [genesis](https://hackmd.io/@benjaminion/genesis) to start:
+You should see that the beacon node has launched with your validator attached:
 
 ```
 WRN 2020-08-03 16:24:17.950+02:00 Validator not in registry (yet?)           topics="beacval" tid=11677993 file=validator_duties.nim:53 pubKey=a9c4df36
 INF 2020-08-03 16:24:17.951+02:00 Local validator attached                   tid=11677993 file=validator_pool.nim:21 pubKey=a9c4df36 validator=a9c4df36
 INF 2020-08-03 16:24:17.951+02:00 Local validators attached                  topics="beacval" tid=11677993 file=validator_duties.nim:61 count=1
 INF 2020-08-03 16:24:17.958+02:00 Starting beacon node                       topics="beacnde" tid=11677993 file=beacon_node.nim:875 version="0.5.0 (31b33907)" nim="Nim Compiler Version 1.2.6 [MacOSX: amd64] (bf320ed1)" timeSinceFinalization=81350 head=ebe49843:0 finalizedHead=ebe49843:0 SLOTS_PER_EPOCH=32 SECONDS_PER_SLOT=12 SPEC_VERSION=0.12.2 dataDir=build/data/shared_medalla_0 pcs=start_beacon_node
-NOT 2020-08-03 16:24:17.958+02:00 Waiting for genesis                        topics="beacnde" tid=11677993 file=beacon_node.nim:890 genesisIn=22h35m50s0ns
 ```
 <details>
 
@@ -77,13 +78,18 @@ NOT 2020-08-03 16:24:17.958+02:00 Waiting for genesis                        top
 
 </details>
 
+> Tip: to 🎨 on the [graffitwall](https://medalla.beaconcha.in/graffitiwall), pass the graffiti parameter like this:
+>```
+>make NODE_PARAMS="--graffiti='<YOUR_GRAFFITI>'" medalla
+
+
 #### 5. Keep an eye on your validator
 
 If you deposited after the [genesis](https://hackmd.io/@benjaminion/genesis) state was decided (August 2nd 1300 UTC), your validators will have been put in a queue based on deposit time, and will slowly be inducted into the validator set after genesis. Getting through the queue may take a few hours or days.
 
 The best way to keep track of your validator's status is [medalla.beaconcha.in](https://medalla.beaconcha.in) (click on the orange magnifying glass at the very top and paste in its public key). 
 
-You can even [create an account](https://medalla.beaconcha.in/register) to add alerts and keep track it its [performance](https://medalla.beaconcha.in/dashboard).
+You can even [create an account](https://medalla.beaconcha.in/register) to add alerts and keep track of your validator's [performance](https://medalla.beaconcha.in/dashboard).
 
 #### 6. Keep your validator updated
 
@@ -101,8 +107,39 @@ 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 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
+
+### Start multiple nodes
+
+You can start multiple local nodes, in different terminal windows/tabs, by specifying numeric IDs:
+
+```
+make medalla NODE_ID=0 # the default
+make medalla NODE_ID=1
+make medalla NODE_ID=2
+```
+
+### Change the TCP and UDP ports
+
+To change the TCP and UDP ports from their default value of 9000 to 9100, say, run:
+
+```
+make BASE_PORT=9100 medalla
+```
+
+You may need to do this if you are running another client.
+
+
+### Make a deposit directly using Nimbus
+
+```
+make medalla-deposit VALIDATORS=2 # default is just 1
+```