diff --git a/README.md b/README.md
index 8816794d3..780fe2858 100644
--- a/README.md
+++ b/README.md
@@ -7,53 +7,52 @@
[](https://discord.gg/XRxWahP)
-[](https://gitter.im/status-im/nimbus)
[](https://join.status.im/nimbus-general)
-Welcome to Nimbus for Ethereum 2.0.
-
Nimbus beacon chain is a research implementation of the beacon chain component of the upcoming Ethereum Serenity upgrade, aka Eth2.
-
-## Manual
-
-Please see the complete documentation at [The nim-beacon-chain Book](https://status-im.github.io/nim-beacon-chain/).
+
+
-## Related
+- [Documentation](#documentation)
+- [Related](#related)
+- [Prerequisites for everyone](#prerequisites-for-everyone)
+ - [Linux](#linux)
+ - [MacOS](#macos)
+ - [Windows](#windows)
+ - [Android](#android)
+- [For users](#for-users)
+ - [Connecting to testnets](#connecting-to-testnets)
+ - [Getting metrics from a local testnet client](#getting-metrics-from-a-local-testnet-client)
+- [Interop (for other Eth2 clients)](#interop-for-other-eth2-clients)
+- [For researchers](#for-researchers)
+ - [State transition simulation](#state-transition-simulation)
+ - [Local network simulation](#local-network-simulation)
+ - [Visualising simulation metrics](#visualising-simulation-metrics)
+ - [Network inspection](#network-inspection)
+- [For developers](#for-developers)
+ - [Windows dev environment](#windows-dev-environment)
+ - [Linux, MacOS](#linux-macos)
+ - [Raspberry Pi](#raspberry-pi)
+ - [Makefile tips and tricks for developers](#makefile-tips-and-tricks-for-developers)
+ - [CI setup](#ci-setup)
+- [License](#license)
+
+
+
+
+## Documentation
+
+You can find complete information about running a beacon node and operating as a validator in [The Book](https://status-im.github.io/nim-beacon-chain/).
+
+## Related projects
* [status-im/nimbus](https://github.com/status-im/nimbus/): Nimbus for Ethereum 1
* [ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs/tree/v0.12.1#phase-0): Serenity specification that this project implements
You can check where the beacon chain fits in the Ethereum ecosystem our Two-Point-Oh series: https://our.status.im/tag/two-point-oh/
-## Table of Contents
-
-- [Nimbus Eth2 (Beacon Chain)](#nimbus-eth2-beacon-chain)
- - [Manual](#manual)
- - [Related](#related)
- - [Table of Contents](#table-of-contents)
- - [Prerequisites for everyone](#prerequisites-for-everyone)
- - [Linux](#linux)
- - [MacOS](#macos)
- - [Windows](#windows)
- - [For users](#for-users)
- - [Connecting to testnets](#connecting-to-testnets)
- - [Getting metrics from a local testnet client](#getting-metrics-from-a-local-testnet-client)
- - [Interop (for other Eth2 clients)](#interop-for-other-eth2-clients)
- - [For researchers](#for-researchers)
- - [State transition simulation](#state-transition-simulation)
- - [Local network simulation](#local-network-simulation)
- - [Visualising simulation metrics](#visualising-simulation-metrics)
- - [Network inspection](#network-inspection)
- - [For developers](#for-developers)
- - [Windows dev environment](#windows-dev-environment)
- - [Linux, MacOS](#linux-macos)
- - [Raspberry Pi](#raspberry-pi)
- - [Makefile tips and tricks for developers](#makefile-tips-and-tricks-for-developers)
- - [CI setup](#ci-setup)
- - [License](#license)
-
## Prerequisites for everyone
At the moment, Nimbus has to be built from source.
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 66da30047..6cee647bf 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -1,8 +1,8 @@
# Summary
- [Introduction](./intro.md)
-- [Become a Validator](./validator.md)
- [Installation](./install.md)
+- [Become a Validator](./validator.md)
- [Command-line Options](./cli.md)
- [API](./api.md)
- [Advanced Usage for Developers](./advanced.md)
diff --git a/docs/src/install.md b/docs/src/install.md
index 4c1262b63..a347d8eff 100644
--- a/docs/src/install.md
+++ b/docs/src/install.md
@@ -48,3 +48,7 @@ _Assuming Ubuntu PRoot is used_
```sh
apt install build-essential git libpcre3-dev
```
+
+## Next steps
+
+Once you've installed build tools, you're ready to move on to launching the beacon node and becoming a [validator](./validator.md)
diff --git a/docs/src/intro.md b/docs/src/intro.md
index e95e03f7c..52cfe1a4d 100644
--- a/docs/src/intro.md
+++ b/docs/src/intro.md
@@ -5,15 +5,15 @@ _Documentation for Nimbus Beacon Chain users and developers._
Nimbus beacon chain is a research implementation of the beacon chain component of the upcoming Ethereum Serenity upgrade, aka Eth2.
- Open sourced at [github.com/status-im/nim-beacon-chain](https://github.com/status-im/nim-beacon-chain/tree/master).
-- Specification of our implementation can be found at [ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs/tree/v0.11.1#phase-0).
+- Specification of our implementation can be found at [ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs/tree/v0.12.1#phase-0).
## Overview
In this book, we will cover:
1. [What is beacon chain](./faq.md#1-what-is-beacon-chain) and [what is Nimbus](./faq.md#4-what-is-nimbus) to equip you with some basic knowledge.
-2. How to [become a validator](./validator.md) in Ethereum 2.0 as a user.
-3. [Installation steps](./install.md) for nimbus beacon chain.
+2. [Installation steps](./install.md) outline the prerequisites to get started.
+3. How to [become a validator](./validator.md) in Ethereum 2.0 as a user, for example on the Altona testnet.
4. [CLI](./cli.md) for running your customized nimbus beacon node.
5. [API](./api.md) for monitoring your node through `http`.
6. [Advanced usage](./advanced.md) for developers.
diff --git a/docs/src/validator.md b/docs/src/validator.md
index ca3a49ec8..403bb6953 100644
--- a/docs/src/validator.md
+++ b/docs/src/validator.md
@@ -1,17 +1,21 @@
# Become a Validator
-To become a validator, you have to first connect to a testnet, deposit your Ethers, and sync with the network.
+To become a validator, you need to install the beacon chain software, acquire 32 ETH, set up your validator account and register with the deposit contract on Ethereum.
+
+There is currently no Eth2 mainnet - all networks are testnets.
## Recommended Testnets
Though Nimbus can connect to any of the testnets published in the [eth2-clients/eth2-testnets repo](https://github.com/eth2-clients/eth2-testnets/tree/master/nimbus), below are the recommended ones:
-- Public Testnet: [altona](https://github.com/goerli/altona) ([explorer](https://altona.beaconcha.in))
-- Local Testnet: testnet0 (currently not available)
+- Multi-client Testnet: [altona](https://github.com/goerli/altona) ([explorer](https://altona.beaconcha.in))
+- Nimbus Testnet: testnet0 (experimental, not always active)
-## Connecting to Testnets
+## Altona
-Before we start, we have to obtain 32 Ethers on the Goerli testnet. Then, we can deposit 32 Ethers to the registration smart contract to become a validator.
+### Initial setup
+
+Before we start, we have to obtain 32 ETH on the Goerli testnet. Then, we can deposit 32 Ethers to the registration smart contract to become a validator.
1. Open your [MetaMask](https://metamask.io/) wallet, switch to the `Goerli Test Network` option from the top right corner.
2. Copy your account address by clicking on one of your accounts.
@@ -20,7 +24,6 @@ Before we start, we have to obtain 32 Ethers on the Goerli testnet. Then, we can
5. Wait for a few seconds and return to your MetaMask wallet to check if you have successfully received.
6. Once the [prerequisites](./install.md) are installed, you can connect to the altona testnet with the following commands:
-- Change `altona` to `testnet0` to connect to testnet0.
- **_Remember to replace `make` with `mingw32-make` if using Windows._**
```bash
@@ -35,7 +38,7 @@ make altona # This will build Nimbus and all other dependencies
-7. The testnet should now be up and running. Then, you will be prompted to enter your private key of the account you want to deposit the 32 Ether from. Find your private key from MetaMask as below:
+7. You will be prompted to enter your private key of the account you want to deposit the 32 Ether from. Find your private key from MetaMask as below:
@@ -45,12 +48,41 @@ make altona # This will build Nimbus and all other dependencies
-9. Now you should be syncing with the network. It may take a while (may be quite a few hours). You can know that you are synced if you see the following output.
+9. The beacon chain client will start syncing the network while your deposit is being processed. As soon as the deposit has been added, the client will start performing validation duties.
You can also get a brief estimate of the time remaining until your network gets synced by comparing the output `epoch` value and the one in the blockchain explorer (the [altona explorer](https://altona.beaconcha.in) for example).
+### Upgrading
+
+When restarting 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 altona # 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 to keep these folders backed up.
+
+## Metrics
+
+Metrics are not included in the binary by default - to enable them, use the following options when starting the client:
+
+```
+make NIMFLAGS="-d:insecure" altona
+```
+
+You can now browse the metrics using a browser and connecting to:
+
+http://localhost:8008/metrics
+
+Make sure to protect this port as the http server used is not considered secure and should not be used by untrusted peers.
+
## Troubleshooting
1. The directory that stores the blockchain data of the testnet is `build/data/shared_altona_0` (replace `altona` with other testnet names). Delete this folder if you want to start over. For example, you can start over with a fresh storage if you entered a wrong private key.