getting started updates (#82)

source/docs/building.md

@@ -3,7 +3,7 @@ id: building
 title: Getting Started with Nimbus
 ---
 
-This document will explain how to install, test, and run Nimbus on your local machine. To learn about what Nimbus is, see the [intro post](https://our.status.im/nimbus-for-newbies/). To dig deeper, see the Nimbus [Ethereum 1.0](https://github.com/status-im/nimbus) and [Ethereum 2.0](https://github.com/status-im/nim-beacon-chain) repositories.
+This document explains how to install, test, and run Nimbus on your local machine. To learn about what Nimbus is, see our original [intro post](https://our.status.im/nimbus-for-newbies/). To dig deeper, see the Nimbus [Ethereum 1.0](https://github.com/status-im/nimbus) and [Ethereum 2.0](https://github.com/status-im/nim-beacon-chain) repositories.
 
 ### Building and running Nimbus
 
@@ -30,9 +30,9 @@ Nimbus will now run and attempt to synchronize with the Ethereum 1.0 blockchain.
 
 The beacon chain simulation runs several beacon nodes on the local machine, attaches several local validators to each, and builds a beacon chain between them. 
 
-Prerequisites: Follow the instructions outlined [here](https://github.com/status-im/nim-beacon-chain#prerequisites-for-everyone).
+**Prerequisites:** At the moment, Nimbus has to be built from source, and has the following external dependencies -- developer tools (C compiler, Make, Bash, Git), [PCRE](https://www.pcre.org/); follow the instructions outlined [here](https://github.com/status-im/nim-beacon-chain#prerequisites-for-everyone) to install them.
 
-Now, enter the Ethereum 2.0 realm of Nimbus:
+Once you've installed the prerequisites, you're ready to enter the Ethereum 2.0 realm of Nimbus:
 
 ```bash
 git clone https://github.com/status-im/nim-beacon-chain
@@ -61,21 +61,49 @@ To change the number of validators and nodes:
 make VALIDATORS=192 NODES=6 USER_NODES=1 eth2_network_simulation
 ```
 
-Find out more about the simulation [here](https://our.status.im/nimbus-development-update-03/).
+If you’d like to see the nodes running on separated sub-terminals inside one big window, install [Multitail](https://www.vanheusden.com/multitail/index.php) (if you're on a Mac, follow the instructions [here](https://brewinstall.org/Install-multitail-on-Mac-with-Brew/)), then:
+
+
+```
+USE_MULTITAIL="yes" make eth2_network_simulation
+```
+
+You’ll get something like this (click for full size):
+
+[![](https://i.imgur.com/Pc99VDO.png)](https://i.imgur.com/Pc99VDO.png)
+
+
+You can find out more about the beacon node simulation [here](https://our.status.im/nimbus-development-update-03/#beaconsimulation).
 
 ### Building and running the Ethereum 2.0 local state transition simulation
 
-The state transition simulation quickly runs the Beacon chain state transition function in isolation and outputs JSON snapshots of the state. It runs without networking and blocks are processed without slot time delays.
+This simulation is primarily designed for researchers, but we'll cover it briefly here in case you're curious :)
+
+The [state transition](https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md#beacon-chain-state-transition-function) simulation quickly runs the beacon chain state transition function in isolation and outputs JSON snapshots of the state (directly to the `nim-beacon-chain` directory). It runs without networking and blocks are processed without slot time delays.
 
 ```bash
-# build and run the state simulator, then display its help ("-d:release" speeds it
+# build the state simulator, then display its help ("-d:release" speeds it
 # up substantially, allowing the simulation of longer runs in reasonable time)
 make NIMFLAGS="-d:release" state_sim
 build/state_sim --help
 ```
 
-Use the output of the help command to pass desired values to the sim - change number of validators, nodes, etc. to get different results.
+Use the output of the `help` command to pass desired values to the simulator - experiment with changing the number of slots, validators, , etc. to get different results.
+
+The most important options are:
+
+- `slots` : the number of slots to run the simulation for (default 192)
+- `validators`: the number of validators (default 6400)
+- `attesterRatio`: the expected fraction of attesters that actually do their work for every slot (default 0.73)
+- `json_interval`: how often JSON snapshots of the state are outputted (default every 32 slots -- or once per epoch)
+
+For example, to run the state simulator for 384 slots, with 20,000 validators, and an average of 66% of attesters doing their work every slot, while outputting snapshots of the state twice per epoch, run:
+
+```
+build/state_sim --slots=384 --validators=20000 --attesterRatio=0.66 --json_interval=16
+```
+
 
 ### Medalla Ethereum 2.0 Testnet
 
-There is a publicly available [Ethereum 2.0](https://our.status.im/tag/two-point-oh) multi-client testnet running until at least October. Read all about it [here](https://blog.ethereum.org/2020/08/03/eth2-quick-update-no-14/), and learn how you can join it in [the Nimbus beacon chain book](https://status-im.github.io/nim-beacon-chain/medalla.html).
+There is a publicly available [Ethereum 2.0](https://our.status.im/tag/two-point-oh) multi-client testnet running until at least October. Read all about it [here](https://blog.ethereum.org/2020/08/03/eth2-quick-update-no-14/), and learn how you can join it in [the Nimbus beacon chain book](https://status-im.github.io/nim-beacon-chain/medalla.html) 💛