Doc updates (#3771)

* Doc updates

* initial merge guide
* mark JSON-RPC as removed
* expand on binaries
* recommend `-j4` when building
* cleanups

* style fixes

docs/the_nimbus_book/src/SUMMARY.md

@@ -3,6 +3,7 @@
 - [Design goals](./philosophy.md)
 - [System requirements](./hardware.md)
 - [Mainnet checklist](./preparation.md)
+- [Merge readiness](./merge.md)
 
 # Quickstart
 - [Run the beacon node](./quick-start.md)

docs/the_nimbus_book/src/api.md

@@ -1,32 +1,10 @@
 # JSON-RPC API
 
-> The Nimbus JSON-RPC API has been deprecated and it’s scheduled for removal in version v22.6 of Nimbus (to be released in June 2022).
+> ⚠️ As of v22.6.0, the Nimbus JSON-RPC interface has been **removed** following an extended deprecation period. You are encouraged to migrate your applications to the [REST API](./rest-api.md).
-  If you are currently relying on the JSON-RPC API, please consider switching to the [official REST API](./rest-api.md).
 
-The `JSON-RPC API` is a collection of APIs for querying the state of the application at runtime.
+The JSON-RPC API pre-dated the REST API and was based on early designs of the beacon chain.
-
-The API is based on an early version of the common [beacon APIs](https://github.com/ethereum/beacon-APIs) with the exception that `JSON-RPC` is used instead of [http `REST`](./rest-api.md) (the method names, parameters and results are all the same except for the encoding / access method).
-
-The `JSON-RPC API` should not be exposed to the public internet.
-
-## Introduction
-
-The `nimbus-eth2` API is implemented using JSON-RPC 2.0. To query it, you can use a JSON-RPC library in the language of your choice, or a tool like `curl` to access it from the command line. A tool like [jq](https://stedolan.github.io/jq/) is helpful to pretty-print the responses.
-
-```
-curl -d '{"jsonrpc":"2.0","id":"id","method":"peers","params":[] }' -H 'Content-Type: application/json' localhost:9190 -s | jq
-```
-
-Before you can access the API, make sure it's enabled using the RPC flag (`nimbus_beacon_node --rpc`):
-
-```
-     --rpc                     Enable the JSON-RPC server.
-     --rpc-port                HTTP port for the JSON-RPC service.
-     --rpc-address             Listening address of the RPC server.
-```
-
-One difference is that currently endpoints that correspond to specific ones from the [spec](https://ethereum.github.io/eth2.0-APIs/) are named weirdly - for example an endpoint such as [`getGenesis`](https://ethereum.github.io/eth2.0-APIs/#/Beacon/getGenesis) is currently named `get_v1_beacon_genesis` which would map 1:1 to the actual REST path in the future - verbose but unambiguous.
 
+This guide is kept for historical reference, as well as to aid migration.
 
 ## Beacon chain API
 

docs/the_nimbus_book/src/attestation-performance.md

@@ -1,6 +1,8 @@
 # Monitor attestation performance
 
-Use the `ncli_db validatorPerf` command to create a report for the attestation performance of your validator over time.
+`ncli_db validatorPerf` is an advanced tool that helps you monitor the performance of your validator over time.
+
+The tool requires that you [built nimbus from source](./build.md).
 
 ## Steps
 

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

@@ -12,7 +12,7 @@ When installing Nimbus via your package manager, a user and service will already
 
 It is recommended that you create a dedicated user and group for running Nimbus. The same user can also be used for the execution client.
 
-```console
+```sh
 # Create the `nimbus` group
 sudo groupadd nimbus
 
@@ -26,20 +26,20 @@ sudo useradd -g nimbus nimbus -m -d /var/lib/nimbus
 
 A good starting point is the [example service file](https://github.com/status-im/nimbus-eth2/blob/unstable/scripts/package_image/usr/lib/systemd/system/nimbus_beacon_node.service) in the Nimbus repository.
 
-```console
+```sh
 # Download example service file and save it to `/etc/systemd/system/nimbus_beacon_node.service`
 curl -s https://raw.githubusercontent.com/status-im/nimbus-eth2/stable/scripts/package_image/usr/lib/systemd/system/nimbus_beacon_node.service | sudo tee /etc/systemd/system/nimbus_beacon_node.service > /dev/null
 ```
 
 The format of service files is documented in the [systemd manual](https://www.freedesktop.org/software/systemd/man/systemd.service.html).
 
-> 🛈 Automatic restarts increase the risk that the doppelganger detection fails - set `RestartPreventExitStatus=1031` to prevent this from happening
+> ℹ️ Automatic restarts increase the risk that the doppelganger detection fails - set `RestartPreventExitStatus=1031` to prevent this from happening
 
 ### 3. Configure your service
 
 Services are configured either by editing the service file directly or using `systemctl edit` to create an override.
 
-```console
+```sh
 # Edit the systemd file to match your installation
 sudo vi /etc/systemd/system/nimbus_beacon_node.service
 
@@ -61,13 +61,13 @@ The example assumes Nimbus was installed in `/usr/bin/nimbus_beacon_node` - if y
 
 Every time you add or update a service, the `systemd` daemon must be notified of the changes:
 
-```console
+```sh
 sudo systemctl daemon-reload
 ```
 
 ### 4. Start the service
 
-```console
+```sh
 # start the beacon node
 sudo systemctl start nimbus_beacon_node
 
@@ -79,21 +79,21 @@ sudo systemctl enable nimbus_beacon_node
 
 `systemctl status` will show if your beacon node is up and running, or has stopped for some reason.
 
-```console
+```sh
 sudo systemctl status nimbus_beacon_node.service
 ```
 
-You can also inspect the logs using the following command:
+You can also follow the logs using the following command:
 
-```console
+```sh
-sudo journalctl -u nimbus_beacon_node.service
+sudo journalctl -uf nimbus_beacon_node.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](./keep-an-eye.md#keep-track-of-your-syncing-progress).
+This will show you the Nimbus logs at the default setting  -- it should include regular "slot start" messages which will show your [sync progress](./keep-an-eye.md#keep-track-of-your-syncing-progress). Press `ctrl-c` to stop following the logs.
 
 To rewind logs - by one day, say - run:
 
-```console
+```sh
 sudo journalctl -u nimbus_beacon_node.service --since yesterday
 ```
 

docs/the_nimbus_book/src/binaries.md

@@ -1,15 +1,29 @@
 # Nimbus binaries
 
+Binary releases can be downloaded from [https://github.com/status-im/nimbus-eth2/releases/latest](https://github.com/status-im/nimbus-eth2/releases/latest).
+
 We currently have binaries available for Linux `AMD64`, `ARM` and `ARM64`, Windows `AMD64` and macOS (`AMD64` and `ARM64`).
 
-You can find the latest release here: [https://github.com/status-im/nimbus-eth2/releases](https://github.com/status-im/nimbus-eth2/releases)
+## Download
 
-Scroll to the bottom of the first (non-nightly) release you see, and click on `Assets`. You should see a list that looks like the following:
+The binaries are available at the bottom of the page under `Assets`. You should see a list that looks like the following:
 
 ![](https://i.imgur.com/6wuvM2d.png)
 
-Click on the `tar.gz` file that corresponds to your OS and architecture, unpack the archive, read the README and run the binary directly (or through one of our provided wrapper scripts).
+Click on the file that corresponds to your OS and architecture, unpack the archive, read the README and run the binary directly (or through one of our provided wrapper scripts).
+
+## Installation
+
+To install or upgrade a binary release, simply unpack the downloaded archive in a directory of your choice.
+
+After unpacking, you may wish to [verify the checksum](./checksums.md).
+
+## Docker
+
+Nimbus binaries are also published via [Docker](./docker.md).
+
+## Reproducible builds
 
 We've designed the build process to be reproducible. In practice, this means that anyone can verify that these exact binaries were produced from the corresponding source code commits. For more about the philosophy and importance of this feature see [reproducible-builds.org](https://reproducible-builds.org/).
 
-For instructions on how to reproduce those binaries, see "README.md" inside the archive.
+For instructions on how to reproduce those binaries, see "README.md" inside the archive, as well as the [in-depth guide](./distribution_internals.md).

docs/the_nimbus_book/src/build.md

@@ -2,13 +2,13 @@
 
 ## Prerequisites
 
-Before building and running the application, make sure you've gone through the [installed the required dependencies](./install.md).
+Before building and running the application, make sure you've installed the [required dependencies](./install.md).
 
 ## Building the node
 
-### 1. Clone the nim beacon chain repository
+### 1. Clone the `nimbus-eth2` repository
 
-```
+```sh
 git clone https://github.com/status-im/nimbus-eth2
 cd nimbus-eth2
 ```
@@ -17,8 +17,8 @@ cd nimbus-eth2
 
 To build the Nimbus beacon node and it's dependencies, run:
 
-```
+```sh
-make nimbus_beacon_node
+make -j4 nimbus_beacon_node
 ```
 
-
+> ℹ️ Omit `-j4` on systems with 4GB of memory or less.

docs/the_nimbus_book/src/connect-eth2.md

@@ -1,32 +1,29 @@
-# Connect your validator to eth2
+# Start performing validator duties
+
+Once your keys have been [imported](./keys.md), it is time to restart the beacon node and start validating!
+
+## (Re)start the node
+
+Press `ctrl-c` to stop the beacon node if it's running, then use the same command as before to run it again:
 
 **Prater**
 
-To connect your validator to the Prater testnet, from the `nimbus-eth2` repository run:
-
 ```
  ./run-prater-beacon-node.sh
 ```
 
 **Mainnet**
 
-To connect your validator to mainnet, from the `nimbus-eth2` repository run:
-
 ```
 ./run-mainnet-beacon-node.sh
 ```
 
-In both cases, you'll be asked to enter your [Web3 provider URL](./start-syncing.md#web3-provider-url) again.
+## Check the logs
 
-> **Note:** If your beacon node is already running, you'll need to shut it down gracefully (`Ctrl+c`) and re-run the above command.
+Your beacon node will launch and connect your validator to the beacon chain network. To check that keys were imported correctly, look for `Local validator attached` in the logs:
-
-To ensure your Validator is correctly monitoring the eth1 chain, it's important you enter a valid web3 provider.
-
-Your beacon node will launch and connect your validator to the eth2 network. To check that this has happened correctly, check your logs for the following:
 
 ```
 INF 2020-11-18 11:20:00.181+01:00 Launching beacon node
 ...
 NOT 2020-11-18 11:20:02.091+01:00 Local validator attached
 ```
-

docs/the_nimbus_book/src/deposit.md

@@ -8,7 +8,7 @@ The easiest way to get your deposit in is to follow the Ethereum Foundation's la
 
 **Mainnet**: [https://launchpad.ethereum.org/](https://launchpad.ethereum.org/)
 
-> ⚠️  If you are making a mainnet deposit make sure you verify that the deposit contract you are interacting with is the correct one.
+> ⚠️ If you are making a mainnet deposit make sure you verify that the deposit contract you are interacting with is the correct one.
 >
 > You should verify that the address is indeed: [0x00000000219ab540356cBB839Cbe05303d7705Fa](https://etherscan.io/address/0x00000000219ab540356cBB839Cbe05303d7705Fa)
 
@@ -17,7 +17,7 @@ We won't elaborate on each individual step here, since they are well explained o
 ## 1. Execution client / web3 connection
 ![](https://i.imgur.com/81BgR14.png)
 
-In the `Select Client` section you'll first be asked to choose an execution client. You need to run an execution client in order to create blocks and process incoming validator deposits from the execution chain.
+In the `Select Client` section you'll first be asked to choose an execution client. You need to run an execution client in order to perform your validator duties.
 
 ![](https://i.imgur.com/l5WSGqZ.png)
 
@@ -38,4 +38,3 @@ It's a good idea to bookmark this page.
 
 ## Expected waiting time (the queue)
 Once you send off your transaction(s), your validator will be put in a queue based on deposit time. Getting through the queue may take a few hours or days (assuming the chain is finalising). No validators are accepted into the validator set while the chain isn't finalising. The `Pending Validators` metric on the [beaconcha.in](https://beaconcha.in/) will give you the size of the queue.
-

docs/the_nimbus_book/src/eth1.md

@@ -1,12 +1,12 @@
-# Run an Execution client
+# Run an execution client
 
-In order to be able to produce blocks and process incoming validator deposits from the execution layer, you'll need to run an execution client in together with the beacon node.
+In order to be able to produce blocks and process incoming validator deposits, you'll need to run an execution client in together with the beacon node.
 
-Nimbus has been tested all the major execution clients - see the [execution client comparison](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) for more information.
+Nimbus has been tested all major execution clients - see the [execution client comparison](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) for more information.
 
-By default, Nimbus uses WebSockets to communicate with the execution client, connecting to a server on the same machine using port 8546: http://localhost:8546.
+By default, Nimbus uses WebSockets to communicate with the execution client, connecting to ws://localhost:8546. You can provide a different URL with the `--web3-url` parameter.
 
-> ⚠ You need to run your own execution client after The Merge - third-party services like Infura, Alchemy and Pocket will no longer be enough.
+> ⚠️ You need to run your own execution client after [the merge](./merge.md) - relying on third-party services such as Infura, Alchemy and Pocket will not be possible.
 
 ## Nimbus
 
@@ -37,7 +37,7 @@ geth --ws
 
 ### 3. Leave Geth running
 
-Let it sync - Geth uses a fast sync mode by default. It may take anywhere between a few hours and a couple of days.
+Let it sync - Geth uses snap sync by default. It may take anywhere between a few hours and a couple of days.
 
 >**N.B.** It is safe to run Nimbus and start validating even if Geth hasn't fully synced yet
 

docs/the_nimbus_book/src/faq.md

@@ -6,7 +6,7 @@
 
 You can check the version through a number of methods:
 
-```console
+```sh
 # Run the beacon node with the --version flag:
 build/nimbus_beacon_node --version
 
@@ -21,7 +21,7 @@ curl -s http://localhost:9100/eth/v1/node/version
 
 The metrics server is disabled by default: enable it by passing `--metrics` to the run command:
 
-```
+```sh
 ./run-mainnet-beacon-node.sh --metrics ...
 ```
 
@@ -29,7 +29,7 @@ The metrics server is disabled by default: enable it by passing `--metrics` to t
 
 The REST server is disabled by default: enable it by passing `--rest` to the run command:
 
-```
+```sh
 ./run-mainnet-beacon-node.sh --metrics ...
 ```
 
@@ -95,7 +95,7 @@ Here is how to fix them.
 
 Run:
 
-```
+```sh
 # Changing ownership to `user:group` for all files/directories in <data-dir>.
 chown user:group -R <data-dir>
 # Set permissions to (rwx------ 0700) for all directories starting from <data-dir>
@@ -119,7 +119,7 @@ In sum:
 
 From inside `Git Bash`, run:
 
-```
+```sh
 # Set permissions for all the directories starting from <data-dir>
 find <data-dir> -type d -exec icacls {} /inheritance:r /grant:r $USERDOMAIN\\$USERNAME:\(OI\)\(CI\)\(F\) \;
 

docs/the_nimbus_book/src/infura-guide.md

@@ -1,6 +1,6 @@
 # Supplying your own Infura endpoint
 
-> ⚠ After The Merge, you will need to run your own [execution client](./eth1.md).
+> ⚠️ After The Merge, you will need to run your own [execution client](./eth1.md).
 
 In a nutshell, Infura is a hosted ethereum node cluster that lets you make requests to the eth1 blockchain without requiring you to set up your own eth1 node.
 
@@ -50,7 +50,7 @@ You'll be directed to the settings page of your newly created project
 
 ### 6. Select endpoint
 
-> ⚠️  **Warning:** if you're connecting to mainnet, you should skip this step
+> ⚠️ If you're connecting to mainnet, you should skip this step
 
 If you're connecting to a testnet, in the `KEYS` section, click on the dropdown menu to the right of `ENDPOINTS`, and select `GÖRLI`
 

docs/the_nimbus_book/src/install.md

@@ -1,16 +1,24 @@
-# Install dependencies
+# Prepare your machine
 
 The Nimbus beacon node runs on Linux, macOS, Windows, and Android.
 
-To get the best performance, Nimbus should be [built from source](./build.md) on the machine that it will run.
+## System requirements
 
-[Binaries](https://github.com/status-im/nimbus-eth2/releases/latest) are provided for the most common platforms.
+Check that your machine matches the [minimal system requirements](./hardware.md).
 
 ## Time
 
-The beacon chain relies on your computer having the correct time set (plus or minus 0.5 seconds).
+The beacon chain relies on your computer having the correct time set (plus or minus 0.5 seconds). It is important that you periodically synchronize the time with an NTP server.
 
-We recommended you run a high quality time service on your computer such as [chrony](https://chrony.tuxfamily.org/).
+If the above sounds like latin to you, don't worry. You should be fine as long as you haven't messed around with the time and date settings on your computer (they should be set automatically).
+
+### Windows and macOS
+
+Make sure that the options for setting time automatically are enabled.
+
+### Linux
+
+On Linux, it is recommended to install [chrony](https://chrony.tuxfamily.org/).
 
 To install it:
 
@@ -25,16 +33,14 @@ dnf install chrony
 yourAURmanager chrony
 ```
 
-It's available on most package managers.
-
 Once installed, the default configuration works well.
 
 At a minimum, you should run an NTP client (such as chrony) on the server.  Note that most operating systems (including macOS') automatically sync with NTP by default.
 
-If the above sounds like latin to you, don't worry. You should be fine as long as you haven't messed around with the time and date settings on your computer (they should be set automatically).
-
 ## Building from source
 
+> ℹ️ If you are planning to use the precompiled binaries, you can skip this section and go straight to the [binaries](./binaries.md)!
+
 When building from source, you will need additional build dependencies to be installed:
 
 - Developer tools (C compiler, Make, Bash, Git)

docs/the_nimbus_book/src/intro.md

@@ -16,6 +16,8 @@ This book explains the ways in which you can use Nimbus to either monitor the be
 
 > **N.B.** The reality is that we are very early in the eth2 validating life cycle. Validating is not for everyone yet, and it comes with both risks and responsibilities. It isn't a particularly easy way to make money. You'll need to put effort into updating your software, researching hard-forks, having a robust setup... . As such, you should only stake if you are genuinely interested in securing the protocol.
 
+> ⚠️ The Merge is happening soon! Bookmark our [merge readiness](./merge.md) page to stay on top of how you need to prepare.
+
 
 ## Helpful resources
 

docs/the_nimbus_book/src/keep-updated.md

@@ -8,9 +8,11 @@ To update to the latest version, either download the binary or compile the beaco
 
 > **Tip:** To check which version of Nimbus you're currently running, run `build/nimbus_beacon_node --version`
 
-## Download the binary
+## Binaries
 
-Open the latest [Nimbus release](https://github.com/status-im/nimbus-eth2/releases/latest) and copy the link for the file that works on your system.
+Open the latest [Nimbus release](https://github.com/status-im/nimbus-eth2/releases/latest) and download the file that corresponds to your operation system and machine.
+
+Once downloaded, unpack the binaries in the same folder as your current version, overwriting the existing files.
 
 ```
 wget <insert download link here>
@@ -18,18 +20,21 @@ tar -xzf nimbus-eth2_Linux_arm64v8*.tar.gz -C nimbus-eth2
 rm nimbus-eth2_Linux_arm64v8*.tar.gz
 ```
 
-## Compile the beacon node release
+## Build from source
+
+Upgrading Nimbus when built from source is similar to the installation process.
 
 Run:
 
-```
+```bash
+# Download the updated source code
 git pull && make update
 ```
 
 Followed by:
 
 ```
-make nimbus_beacon_node
+make -j4 nimbus_beacon_node
 ```
 
 Now, restart your node.

docs/the_nimbus_book/src/keys.md

@@ -3,12 +3,12 @@
 To import your signing key(s) into Nimbus, copy the `validator_keys` directory -- the directory that was created for you when you generated your keys using the [command line app](https://github.com/ethereum/eth2.0-deposit-cli) -- into `nimbus-eth2`. Then run:
 
 **Prater**
-```
+```sh
 build/nimbus_beacon_node deposits import --data-dir=build/data/shared_prater_0
 ```
 
 **Mainnet**
-```
+```sh
 build/nimbus_beacon_node deposits import --data-dir=build/data/shared_mainnet_0
 ```
 
@@ -38,7 +38,6 @@ build/nimbus_beacon_node deposits import --data-dir=build/data/shared_mainnet_0
  >**Note:** If you come across an error, it's probably because the wrong permissions have been set on either a folder or file. See [here](faq.md#folder-permissions) for how to fix this.
 
 
-
 ## Storage
 
 When you import your keys into Nimbus, your validator signing key(s) are stored in the `build/data/shared_<prater or mainnet>_0/` folder, under `secrets` and `validators` - **make sure you keep these folders backed up somewhere safe.**

docs/the_nimbus_book/src/logging.md

@@ -4,7 +4,7 @@
 
 Nimbus offers several options for logging - by default, logs are written to stdout using the [chronicles](https://github.com/status-im/nim-chronicles#introduction) `textlines` format which is convenient to read and can be used with tooling for [heroku/logfmt](https://brandur.org/logfmt).
 
-> 🛈 `NOT` at the beginning of a log line means 'NOTICE`
+> ℹ️ `NOT` at the beginning of a log line means 'NOTICE`
 
 ## Change log level
 

docs/the_nimbus_book/src/merge.md

@@ -0,0 +1,23 @@
+# The merge
+
+The Ethereum network is preparing for a major upgrade to merge the beacon chain with the existing proof-of-work execution network, thus transitioning to proof-of-stake. To read more about the merge, see https://ethereum.org/en/upgrades/merge/.
+
+## Preparing for the merge
+
+The merge is in its final phase of testing on testnets and is expected to happen later during the year.
+
+### Bookmark this page!
+
+As the merge draws near, we will continue to update this page with the latest information and instructions.
+
+### Keep Nimbus up to date
+
+Leading up to the merge, it is important to [keep Nimbus up to date](./keep-updated.md). Before the merge, the exact version of Nimbus required to participate will be announced, but stakers should be prepared to upgrade their nodes on short notice.
+
+### Run an execution client
+
+As a node operator, you will need to run both an execution client and a consensus client after the merge. If you were previously using a third-party web3 provider (such as Infura or Pocket), you will need to [set up an execution client](./eth1.md).
+
+### Prepare a suggested fee recipient
+
+After the merge, validators that propose blocks are eligible to recieve transaction fees - read more about fee recipients [here](https://launchpad.ethereum.org/en/merge-readiness#fee-recipient).

docs/the_nimbus_book/src/more-keys.md

@@ -12,7 +12,7 @@ Specifically, we'll be using the `existing-mnemonic` command. Here's a descripti
 
 ## Recover existing key
 
-> ⚠️  Recovering validator keys from a mnemonic should only be used as a last resort. Exposing your mnemonic to a computer at any time puts it at risk of being compromised. Your mnemonic is not encrypted and if leaked, can be used to steal your funds.
+> ⚠️ Recovering validator keys from a mnemonic should only be used as a last resort. Exposing your mnemonic to a computer at any time puts it at risk of being compromised. Your mnemonic is not encrypted and if leaked, can be used to steal your funds.
 
 ***N.B.** the commands below assume you are trying to recover your original key, hence `--validator_start_index` has been set to `0`.*
 
@@ -42,7 +42,7 @@ Copy the `validator_keys` directory to `nimbus-eth2` and then follow the instruc
 
 ## Generate another key
 
-> ⚠️  If you wish to generate another validator key,  you must take great care
+> ⚠️ If you wish to generate another validator key,  you must take great care
 to not generate a copy of your original key. Running the same key on two different validator clients will likely get you slashed.
 
 ***N.B.** the commands below assume you already have one key and wish to generate a second, hence `--validator_start_index` has been set to `1` (as `0` would be the original key).*

docs/the_nimbus_book/src/options.md

@@ -1,12 +1,16 @@
 # Command line options
 
-You can pass any `nimbus_beacon_node` options to the `run-prater-beacon-node.sh` and `run-mainnet-beacon-node.sh` scripts. For example, if you want to launch Nimbus on mainnet with different base ports than the default `9000/udp` and `9000/tcp`, say `9100/udp` and `9100/tcp`, run:
+Command line options allow you to customize the way your beacon node operates.
+
+You pass options to the beacon node by adding them to the command line. For example, if you want to launch Nimbus on mainnet with different base ports than the default `9000/udp` and `9000/tcp`, say `9100/udp` and `9100/tcp`, run:
 
 ```
 ./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, run:
+## Available options
+
+To see the full list of command line options availabe to you, with descriptions, run:
 
 ```
 build/nimbus_beacon_node --help
@@ -103,6 +107,8 @@ The following options are available:
 ...
 ```
 
+## Configuration files
+
 All command line options can also be provided in a [TOML](https://toml.io/en/)
 config file specified through the `--config-file` flag. Within the config file,
 you need to use the long names of all options. Please note that certain options
@@ -128,7 +134,7 @@ num-threads = 0
 trusted-node-url = "http://192.168.1.20:5052"
 ```
 
-# Exit Codes
+## Exit Codes
 
 | Exit code | Description |
 |-----------|---------|

docs/the_nimbus_book/src/pi-guide.md

@@ -21,7 +21,7 @@ One of the most important aspects of the Raspberry Pi experience is trying to ma
 - Basic understanding of the [command line](https://www.learnenough.com/command-line-tutorial/basics)
 - 200GB SSD (2TB recommended if also running execution client)
 
-> ⚠️  You will need an SSD to run the Nimbus (without an SSD drive you have absolutely no chance of syncing the Ethereum blockchain). You have two options:
+> ⚠️ You will need an SSD to run the Nimbus (without an SSD drive you have absolutely no chance of syncing the Ethereum blockchain). You have two options:
 >
 > 1. Use an USB portable SSD disk such as the Samsung T5 Portable SSD.
 >

docs/the_nimbus_book/src/prater.md

@@ -13,7 +13,7 @@ Connecting to `prater` and setting up a validator follows the same procedure as
 
 You can connect to any network provided that you have a configuration and genesis file, using the `network` option:
 
-```console
+```sh
 build/nimbus_beacon_node --network:path/to/network --data-dir:path/to/data
 ```
 

docs/the_nimbus_book/src/quick-start.md

@@ -2,21 +2,22 @@
 
 This page takes you through how to run just the beacon node **without a validator attached.**
 
-The beacon node connects to the beacon chain network, manages the blockchain, and provides API's to interact with the beacon chain.
+The beacon node connects to the network, syncs the chain and provides [API's](./rest-api.md) to monitor and interact with the beacon chain. To become a validator, you will need to run a beacon node.
 
-Running a beacon node without a validator attached is a [worthwhile endeavor](https://vitalik.ca/general/2021/05/23/scaling.html#its-crucial-for-blockchain-decentralization-for-regular-users-to-be-able-to-run-a-node).
+Running a beacon node is a [worthwhile endeavor](https://vitalik.ca/general/2021/05/23/scaling.html#its-crucial-for-blockchain-decentralization-for-regular-users-to-be-able-to-run-a-node) even if your are not planning on validating yourself!
-
-It's also a necessary step to running a validator (since an active validator requires a synced beacon node).
 
 ## 1. Prepare
 
-Install [Nimbus' dependencies](./install.html#external-dependencies)
+Prepare your machine by installing [Nimbus' dependencies](./install.html)
 
 
 
 ## 2. Install
 
-[Build the beacon node](./build.md) or install a precompiled release from the [release page](https://github.com/status-im/nimbus-eth2/releases/latest).
+You have two options for installing Nimbus itself:
+
+* [Install precompiled release](./binaries.md)
+* [Build from source](./build.md)
 
 
 

docs/the_nimbus_book/src/run-a-validator.md

@@ -1,4 +1,5 @@
 # Run a validator
+
 Once your beacon node is [running and synced](./quick-start.md), the next step is to run a validator.
 
 ## 1. Deposit
@@ -9,9 +10,9 @@ Once your beacon node is [running and synced](./quick-start.md), the next step i
 
 [Import your validator keys](./keys.md) into Nimbus
 
-## 3. Connect 
+## 3. Validate
 
-[Connect your validator](./connect-eth2.md) to eth2
+[Start performing duties](./connect-eth2.md) by restarting the node
 
 
 </br>

docs/the_nimbus_book/src/start-syncing.md

@@ -1,28 +1,34 @@
-# Sync from scratch
+# Sync your node
 
-To minimize the amount of downtime, you should ensure that your beacon node is [completely synced](./keep-an-eye.md#keep-track-of-your-syncing-progress) before submitting your deposit.  If it's not fully synced you will miss attestations and proposals until it has finished syncing.
+Before you can use your node, it needs to sync with the network. Syncing starts automatically when you start your node, and may take several days depending on the performance of your hardware.
 
-This is particularly important if you are joining a network that's been running for a while since the sync could take some time.
+If you are planning to become a validator, you should ensure that your beacon node is [completely synced](./keep-an-eye.md#keep-track-of-your-syncing-progress) before submitting your deposit, or you might miss attestations and proposal duties until it has finished syncing.
 
-> **Tip:** If you'd like to sync faster and start attesting immediately, we recommend taking a look at [trusted node sync](./trusted-node-sync.md)
+> **Tip:** To get started more quickly, you can perform a [trusted node sync](./trusted-node-sync.md) instead - this requires access to a synced node or a third-party service.
 
-> **N.B.** In order to process incoming validator deposits, you'll need to run an execution client (**web3 provider**) in parallel to your eth2 client. See [here](./eth1.md) for instructions on how to do so.
+> **N.B.** You need need to run an execution client (**web3 provider**) together with the beacon node. See [here](./eth1.md) for instructions on how to do so.
+
+## Networks
+
+Using Nimbus, you can connect either to a testnet, or mainnet. Mainnet is the main ethereum network where real assets are at stake, while testnets are used by users and developers alike to test their node and setup before committing real assets.
+
+> If this is the first time you're setting up your node, it is recommended you run it on a testnet first. Later, when everything is working, you can easily switch to mainned.
 
 ### Testnet
 
 To start syncing the `prater` testnet , from the `nimbus-eth2` repository, run:
 
 ```
- ./run-prater-beacon-node.sh --web3-url="<YOUR_WEB3_PROVIDER_URL>"
+ ./run-prater-beacon-node.sh
 ```
 
 ### Mainnet
 
 
-To start syncing the eth2 mainnet, run:
+To start syncing the Ethereum beacon chain mainnet, run:
 
 ```
- ./run-mainnet-beacon-node.sh --web3-url="<YOUR_WEB3_PROVIDER_URL>"
+ ./run-mainnet-beacon-node.sh
 ```
 
 You should see the following output:
@@ -41,13 +47,24 @@ INF 2020-12-01 11:26:31.000+00:00 Slot start                                 top
 INF 2020-12-01 11:26:36.285+00:00 Slot end                                   topics="beacnde" tid=21815 file=nimbus_beacon_node.nim:593 slot=96567 nextSlot=96568 head=b54486c4:96563 headEpoch=3017 finalizedHead=2f5d12e4:96479 finalizedEpoch=3014
 ...
 ```
-> If you want to put the database somewhere else, (e.g. an external ssd) pass the `--data-dir=/your/path`. ⚠️ If you do this, remember to pass this flag to **all** your nimbus calls.
 
-### Command line options
+## Data directory
 
-You can pass any `nimbus_beacon_node` options to the `prater` and `mainnet` scripts. For example, if you wanted to launch Nimbus on `prater` with a different base port, say `9100`, you would run:
+While running, the beacon node will store chain data and other information in `build/data/` in the directory where you installed Nimbus. You can change the storage location with the `--data-dir` option:
 
+```sh
+./run-mainnet-beacon-node.sh --data-dir=/data/mainnet
 ```
+
+You will need to pass `--data-dir` to all commands, including when importing your keys!
+
+> ℹ️ Don't forget to put `=` after `--data-dir`!
+
+## Command line options
+
+You can add command line options to the startup command - for example, to change the port to 9100, use:
+
+```sh
 ./run-prater-beacon-node.sh --tcp-port=9100 --udp-port=9100
 ```
 
@@ -56,6 +73,9 @@ To see a list of the command line options availabe to you, with descriptions, ru
 ```
 ./build/nimbus_beacon_node --help
 ```
-### Keep track of your sync progress
+
+More information is available from the [options](./options.md) page.
+
+## Keep track of your sync progress
 
 See [here](./keep-an-eye.html#keep-track-of-your-syncing-progress) for how to keep track of your sync progress.

docs/the_nimbus_book/src/troubleshooting.md

@@ -126,7 +126,7 @@ It's because your node can't connect to the web3 provider you have specified. Pl
 
 ### Discovered new external address warning log
 
-```console
+```
 WRN 2021-03-11 13:26:25.943-08:00
 Discovered new external address but ENR auto update is off
 topics="discv5" tid=77655 file=protocol.nim:940 majority=Some("myIPaddressHere":9000) previous=None[Address]

docs/the_nimbus_book/src/trusted-node-sync.md

@@ -22,7 +22,7 @@ It is possibly to use trusted node sync with a third-party API provider -- see [
 
 To sync Mainnet, from the `nimbus-eth2` directory run:
 
-```bash
+```sh
 build/nimbus_beacon_node trustedNodeSync --network:mainnet \
  --data-dir=build/data/shared_mainnet_0 \
  --trusted-node-url=http://localhost:5052
@@ -32,7 +32,7 @@ build/nimbus_beacon_node trustedNodeSync --network:mainnet \
 
 To sync Prater, from the `nimbus-eth2` directory run:
 
-```bash
+```sh
 build/nimbus_beacon_node trustedNodeSync --network:prater \
  --data-dir=build/data/shared_prater_0  \
  --trusted-node-url=http://localhost:5052
@@ -45,7 +45,7 @@ build/nimbus_beacon_node trustedNodeSync --network:prater \
 
 When performing a trusted node sync, you can manually verify that the correct chain was synced by comparing the head hash with other sources (e.g. your friends, forums, chats and web sites). If you're syncing using your own backup node you can retrieve the current head from the node using:
 
-```
+```sh
 # Make sure to enable the `--rest` option when running your node:
 
 curl http://localhost:5052/eth/v1/beacon/blocks/head/root
@@ -87,7 +87,7 @@ build/nimbus_beacon_node trustedNodeSync --blockId:0x239940f2537f5bbee1a3829f905
 
 If you have a state and a block file available, you can start the node using the finalized checkpoint options:
 
-```
+```sh
 # Obtain a state and a block from a Beacon API - these must be in SSZ format:
 
 curl -o state.32000.ssz -H 'Accept: application/octet-stream' http://localhost:5052/eth/v2/debug/beacon/states/32000
@@ -100,6 +100,6 @@ build/nimbus_beacon_node --data-dir:trusted --finalized-checkpoint-block=block.3
 
 When performing checkpoint sync, the historical state data from the time before the checkpoint is not available. To recreate the indices and caches necessary for historical state access, run trusted node sync with the `--reindex` flag - this can be done on an already-synced node as well, in which case the process will simply resume where it left off:
 
-```
+```sh
 build/nimbus_beacon_node trustedNodeSync --reindex=true
 ```

docs/the_nimbus_book/src/voluntary-exit.md

@@ -4,7 +4,7 @@ Voluntary exits allow validators to permanently stop performing their duties, an
 
 Exits are subject to a wait period that depends on the length of the exit queue. While a validator is exiting, it still must perform its duties in order not to lose funds to inactivity penalities.
 
-> ⚠️  Voluntary exits are **irreversible**. You won't be able to validate again with the same key. And you won't be able to withdraw your stake until the Eth1 and Eth2 merge. *Note that voluntary exits won't be processed if the chain isn't finalising.*
+> ⚠️ Voluntary exits are **irreversible**. You won't be able to validate again with the same key. And you won't be able to withdraw your stake until the Eth1 and Eth2 merge. *Note that voluntary exits won't be processed if the chain isn't finalising.*
 
 To perform a voluntary exit, make sure your beacon node is running with the `--rest`option enabled (e.g. `./run-mainnet-beacon-node.sh --rest`), then run:
 

docs/the_nimbus_book/src/web3-backup.md

@@ -2,13 +2,14 @@
 
 It's a good idea to add a backup web3 provider in case your main one goes down. You can do this by simply repeating the `--web3-url` parameter on launch.
 
-> Warning: As of `v1.7.0` Nimbus will no longer automagically rewrite HTTP(S) web3 URLs to their respective WebSocket alternatives.
+> ℹ️ As of `v1.7.0` Nimbus will no longer automagically rewrite HTTP(S) web3 URLs to their respective WebSocket alternatives.
 
-For example, if your primary EL client is a [local Geth](./eth1.md#geth), but you want to use [Infura](./infura-guide.md) as a backup you would run:
+For example, if your primary execution client is a [local Geth](./eth1.md#geth), but you want to use [Infura](./infura-guide.md) as a backup you would run:
 
-```
+> ⚠️ After [the merge](./merge.md), it will no longer be possible to rely on third-party services like Infura to run a beacon node!
+
+```sh
 ./run-mainnet-beacon-node.sh \
  --web3-url="ws://127.0.0.1:8546" \
  --web3-url="wss://mainnet.infura.io/ws/v3/..."
 ```
-