[Ready] README polish (#602)

* README polish

* Update README.md

Co-Authored-By: Jacek Sieka <jacek@status.im>

* Update README.md

Co-Authored-By: Jacek Sieka <jacek@status.im>

* Update README.md

Co-Authored-By: kdeme <kim.demey@gmail.com>

* Address comments
This commit is contained in:
Mamy Ratsimbazafy 2019-11-29 16:39:46 +01:00 committed by Dustin Brody
parent 84c189fd1b
commit e7b0c8d8dd
2 changed files with 147 additions and 140 deletions

287
README.md
View File

@ -1,4 +1,4 @@
# Ethereum Beacon Chain # Nimbus Eth2 (Beacon Chain)
[![Build Status (Travis)](https://img.shields.io/travis/status-im/nim-beacon-chain/master.svg?label=Linux%20/%20macOS "Linux/macOS build status (Travis)")](https://travis-ci.org/status-im/nim-beacon-chain) [![Build Status (Travis)](https://img.shields.io/travis/status-im/nim-beacon-chain/master.svg?label=Linux%20/%20macOS "Linux/macOS build status (Travis)")](https://travis-ci.org/status-im/nim-beacon-chain)
[![Build Status (Azure)](https://dev.azure.com/nimbus-dev/nim-beacon-chain/_apis/build/status/status-im.nim-beacon-chain?branchName=master)](https://dev.azure.com/nimbus-dev/nim-beacon-chain/_build/latest?definitionId=3&branchName=master) [![Build Status (Azure)](https://dev.azure.com/nimbus-dev/nim-beacon-chain/_apis/build/status/status-im.nim-beacon-chain?branchName=master)](https://dev.azure.com/nimbus-dev/nim-beacon-chain/_build/latest?definitionId=3&branchName=master)
[![License: Apache](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![License: Apache](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
@ -9,27 +9,38 @@
[![Gitter: #status-im/nimbus](https://img.shields.io/badge/gitter-status--im%2Fnimbus-orange.svg)](https://gitter.im/status-im/nimbus) [![Gitter: #status-im/nimbus](https://img.shields.io/badge/gitter-status--im%2Fnimbus-orange.svg)](https://gitter.im/status-im/nimbus)
[![Status: #nimbus-general](https://img.shields.io/badge/status-nimbus--general-orange.svg)](https://get.status.im/chat/public/nimbus-general) [![Status: #nimbus-general](https://img.shields.io/badge/status-nimbus--general-orange.svg)](https://get.status.im/chat/public/nimbus-general)
Nimbus beacon chain is a research implementation of the beacon chain component of the upcoming Ethereum Serenity upgrade, aka Eth2. See the main [Nimbus](https://github.com/status-im/nimbus/) project for the bigger picture. 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.
## Interop (for other Eth2 clients)
Nimbus is currently going through interoperability testing with several other beacon chain implementations - several tools are available to make this testing easier:
* [multinet](https://github.com/status-im/nim-beacon-chain/tree/master/multinet) - a set of scripts to build and run several Eth2 clients locally
* [ncli](https://github.com/status-im/nim-beacon-chain/tree/master/multinet) - command line tools for working with SSZ files and state transitions
## Related ## Related
* [status-im/nimbus](https://github.com/status-im/nimbus/): main Nimbus repository - start here to learn more about the Nimbus eco-system * [status-im/nimbus](https://github.com/status-im/nimbus/): Nimbus for Ethereum 1
* [ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs/blob/v0.9.2/specs/core/0_beacon-chain.md): Serenity specification that this project implements * [ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs/blob/v0.9.2/specs/core/0_beacon-chain.md): Serenity specification that this project implements
* [ethereum/beacon\_chain](https://github.com/ethereum/beacon_chain): reference implementation from the Ethereum foundation
You can check where the beacon chain fits in the Ethereum research ecosystem in the [Status Athenaeum](https://github.com/status-im/athenaeum/blob/b465626cc551e361492e56d32517b2cdadd7493f/ethereum_research_records.json#L38). 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/
## Building and Testing ## Table of Contents
### Prerequisites - [Nimbus Eth2 (Beacon Chain)](#nimbus-eth2-beacon-chain)
- [Related](#related)
- [Table of Contents](#table-of-contents)
- [Prerequisites for everyone](#prerequisites-for-everyone)
- [For users](#for-users)
- [Connecting to testnets](#connecting-to-testnets)
- [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)
- [For developers](#for-developers)
- [Windows](#windows)
- [Linux, MacOS](#linux-macos)
- [Raspberry Pi](#raspberry-pi)
- [Makefile tips and tricks for developers](#makefile-tips-and-tricks-for-developers)
- [License](#license)
## Prerequisites for everyone
* [RocksDB](https://github.com/facebook/rocksdb/) * [RocksDB](https://github.com/facebook/rocksdb/)
* PCRE * PCRE
@ -52,39 +63,109 @@ sudo apt-get install librocksdb-dev libpcre3-dev
pakku -S rocksdb pcre-static pakku -S rocksdb pcre-static
``` ```
`rocksdb` can also be installed by following [their instructions](https://github.com/facebook/rocksdb/blob/master/INSTALL.md). `rocksdb` can also be installed by following the [official instructions](https://github.com/facebook/rocksdb/blob/master/INSTALL.md).
### Build & Develop ## For users
#### POSIX-compatible OS ### Connecting to testnets
Nimbus connects to any of the testnets published in the [eth2-clients/eth2-testnets repo](https://github.com/eth2-clients/eth2-testnets/tree/master/nimbus).
Once the [prerequisites](#prerequisites) are installed you can connect to testnet0 with the following commands:
```bash ```bash
make # The first `make` invocation will update all Git submodules and prompt you to run `make` again. git clone https://github.com/status-im/nim-beacon-chain
# It's only required once per Git clone. You'll run `make update` after each `git pull`, in the future, cd nim-beacon-chain
# to keep those submodules up to date. source env.sh
nim scripts/connect_to_testnet.nims nimbus/testnet0
# Run tests
make test
# Update to latest version
git pull
make update
``` ```
To run a command that might use binaries from the Status Nim fork: The testnets are restarted once per week, usually on Monday evenings (UTC)) and integrate the changes for the past week.
## Interop (for other Eth2 clients)
After installing the [prerequisites](#prerequisites)
To run the Nimbus state transition, we provide the `ncli` tool:
* [ncli](ncli)
The interop scripts have been moved in a common repo, the interop relied on 0.8.3 specs which had seen significant changes. The interop branch still exist but is unmaintained.
* [multinet](https://github.com/status-im/nim-beacon-chain/tree/master/multinet) - a set of scripts to build and run several Eth2 clients locally
* [interop branch](https://github.com/status-im/nim-beacon-chain/tree/interop) (unmaintained)
## For researchers
### State transition simulation
The state transition simulator can quickly run the Beacon chain state transition function in isolation and output JSON snapshots of the state. The simulation runs without networking and blocks are processed without slot time delays.
```bash ```bash
./env.sh bash # start a new interactive shell with the right env vars set # build and run the state simulator, then display its help ("-d:release" speeds it
which nim # up substantially, allowing the simulation of longer runs in reasonable time)
nim --version make NIMFLAGS="-d:release" state_sim
build/state_sim --help
# or without starting a new interactive shell:
./env.sh which nim
./env.sh nim --version
``` ```
#### Windows ### Local network simulation
_(Experimental support!)_ The local network simulation will create a full peer-to-peer network of beacon nodes and validators on a single machine, and run the beacon chain in real time.
Parameters such as shard, validator counts, and data folders are configured [vars.sh](tests/simulation/vars.sh). They can be set in as environment variables before launching the simulation.
```bash
# Clear data files from your last run and start the simulation with a new genesis block:
make VALIDATORS=192 NODES=6 USER_NODES=1 eth2_network_simulation
# In another terminal, get a shell with the right environment variables set:
./env.sh bash
# In the above example, the network is prepared for 7 beacon nodes but one of
# them is not started by default (`USER_NODES`) - this is useful to test
# catching up to the consensus. The following command will start the missing node.
./tests/simulation/run_node.sh 0 # (or the index (0-based) of the missing node)
# Running a separate node allows you to test sync as well as see what the action
# looks like from a single nodes' perspective.
```
You can also separate the output from each beacon node in its own panel, using [multitail](http://www.vanheusden.com/multitail/):
```bash
make USE_MULTITAIL="yes" eth2_network_simulation
```
You can find out more about it in the [development update](https://our.status.im/nimbus-development-update-2018-12-2/).
_Alternatively, fire up our [experimental Vagrant instance with Nim pre-installed](https://our.status.im/setting-up-a-local-vagrant-environment-for-nim-development/) and give us yout feedback about the process!_
### Visualising simulation metrics
The [generic instructions from the Nimbus repo](https://github.com/status-im/nimbus/#metric-visualisation) apply here as well.
Specific steps:
```bash
# This will generate the Prometheus config and the Grafana dashboard on the fly,
# based on the number of nodes (which you can control by passing something like NODES=6 to `make`).
make VALIDATORS=192 NODES=6 USER_NODES=0 eth2_network_simulation
# In another terminal tab, after the sim started:
cd tests/simulation/prometheus
prometheus
```
The dashboard you need to import in Grafana is "tests/simulation/beacon-chain-sim-all-nodes-Grafana-dashboard.json".
![monitoring dashboard](./media/monitoring.png)
## For developers
Latest updates happen in the `devel` branch which is merged into `master` every week on Tuesday before deploying a new testnets
The following sections explain how to setup your build environment on your platform.
### Windows
Install Mingw-w64 for your architecture using the "[MinGW-W64 Online Install Mingw-w64 for your architecture using the "[MinGW-W64 Online
Installer](https://sourceforge.net/projects/mingw-w64/files/)" (first link Installer](https://sourceforge.net/projects/mingw-w64/files/)" (first link
@ -109,10 +190,33 @@ You can now follow those instructions in the previous section by replacing `make
mingw32-make test # run the test suite mingw32-make test # run the test suite
``` ```
### Linux, MacOS
#### Raspberry PI ```bash
make # The first `make` invocation will update all Git submodules and prompt you to run `make` again.
# It's only required once per Git clone. You'll run `make update` after each `git pull`, in the future,
# to keep those submodules up to date.
Raspberry Pi support is experimental. # Run tests
make test
# Update to latest version
git pull
make update
```
To run a command that might use binaries from the Status Nim fork:
```bash
./env.sh bash # start a new interactive shell with the right env vars set
which nim
nim --version # Nimbus is tested and supported on 1.0.2 at the moment
# or without starting a new interactive shell:
./env.sh which nim
./env.sh nim --version
```
### Raspberry Pi
We recommend you remove any cover or use a fan; the Raspberry Pi will get hot (85°C) and throttle. We recommend you remove any cover or use a fan; the Raspberry Pi will get hot (85°C) and throttle.
@ -163,77 +267,16 @@ source ~/.profile
git clone https://github.com/status-im/nim-beacon-chain.git git clone https://github.com/status-im/nim-beacon-chain.git
cd nim-beacon-chain cd nim-beacon-chain
# Follow instructions above! # Then you can follow instructions for Linux.
``` ```
## Connecting to testnets
Nimbus should be able to connect to any of the testnets published in the [eth2-testnets repo](https://github.com/zah/eth2-testnets).
For example, connecting to our testnet0 is done with the following commands:
```bash
cd nim-beacon-chain
source env.sh
nim scripts/connect_to_testnet.nims nimbus/testnet0
```
## Beacon node simulation
The beacon node simulation will create a full peer-to-peer network of beacon nodes and validators, and run the beacon chain in real time. To change network parameters such as shard and validator counts, see [start.sh](tests/simulation/start.sh).
```bash
# Clear data files from your last run and start the simulation with a new genesis block:
make VALIDATORS=192 NODES=6 USER_NODES=1 eth2_network_simulation
# In another terminal, get a shell with the right environment variables set:
./env.sh bash
# In the above example, the network is prepared for 7 beacon nodes but one of
# them is not started by default (`USER_NODES`) - you can start it separately
# by running:
./tests/simulation/run_node.sh 0 # (or the 0-based node number of the missing node)
# Running a separate node allows you to test sync as well as see what the action
# looks like from a single nodes' perspective.
```
You can also separate the output from each beacon node in its own panel, using [multitail](http://www.vanheusden.com/multitail/):
```bash
make USE_MULTITAIL="yes" eth2_network_simulation
```
You can find out more about it in the [development update](https://our.status.im/nimbus-development-update-2018-12-2/).
_Alternatively, fire up our [experimental Vagrant instance with Nim pre-installed](https://our.status.im/setting-up-a-local-vagrant-environment-for-nim-development/) and give us yout feedback about the process!_
### Visualising simulation metrics
Those [generic instructions from the Nimbus repo](https://github.com/status-im/nimbus/#metric-visualisation) apply here as well.
Specific steps:
```bash
# This will generate the Prometheus config and the Grafana dashboard on the fly,
# based on the number of nodes (which you can control by passing something like NODES=6 to `make`).
make VALIDATORS=192 NODES=6 USER_NODES=0 eth2_network_simulation
# In another terminal tab, after the sim started:
cd tests/simulation/prometheus
prometheus
```
The dashboard you need to import in Grafana is "tests/simulation/beacon-chain-sim-all-nodes-Grafana-dashboard.json".
[Obligatory screenshot.](https://i.imgur.com/pLvLhID.png)
### Makefile tips and tricks for developers ### Makefile tips and tricks for developers
- build all those tools known to the Makefile: - build all those tools known to the Makefile:
```bash ```bash
# (assuming you have 4 CPU cores and want to take advantage of them): # $(nproc) corresponds to the number of cores you have
make -j4 make -j$(nproc)
``` ```
- build a specific tool: - build a specific tool:
@ -265,45 +308,9 @@ make NIMFLAGS="-d:release"
- you can freely combine those variables on the `make` command line: - you can freely combine those variables on the `make` command line:
```bash ```bash
make -j8 NIMFLAGS="-d:release" USE_MULTITAIL=yes eth2_network_simulation make -j$(nproc) NIMFLAGS="-d:release" USE_MULTITAIL=yes eth2_network_simulation
``` ```
## State transition simulation
The state transition simulator can quickly run the Beacon chain state transition function in isolation and output JSON snapshots of the state. The simulation 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
# up substantially, allowing the simulation of longer runs in reasonable time)
make NIMFLAGS="-d:release" state_sim
build/state_sim --help
```
## Testnet
The beacon chain now has a public testnet available. Connect to it with:
```bash
make testnet0
scripts/testnet0.sh # this launches the testnet0-specific node you just built
```
For more information about the testnet and to find out how to launch your own, see [this announcement](https://our.status.im/the-nimbus-mvp-testnet-is-here/) and the [official docs on launching the testnets](https://nimbus.status.im/docs/t0.html).
## Convention
Ethereum Foundation uses:
- snake_case for fields and procedure names
- MACRO_CASE for constants
- PascalCase for types
Nim NEP-1 recommends:
- camelCase for fields and procedure names
- PascalCase for constants
- PascalCase for types
To facilitate collaboration and comparison, nim-beacon-chain uses the Ethereum Foundation convention.
## License ## License
Licensed and distributed under either of Licensed and distributed under either of

BIN
media/monitoring.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 99 KiB