[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
Dustin Brody
parent
84c189fd1b
commit
e7b0c8d8dd
287
README.md
287
README.md
|
|
@ -1,4 +1,4 @@
|
||||||
# Ethereum Beacon Chain
|
# Nimbus Eth2 (Beacon Chain)
|
||||||
[](https://travis-ci.org/status-im/nim-beacon-chain)
|
[](https://travis-ci.org/status-im/nim-beacon-chain)
|
||||||
[](https://dev.azure.com/nimbus-dev/nim-beacon-chain/_build/latest?definitionId=3&branchName=master)
|
[](https://dev.azure.com/nimbus-dev/nim-beacon-chain/_build/latest?definitionId=3&branchName=master)
|
||||||
[](https://opensource.org/licenses/Apache-2.0)
|
[](https://opensource.org/licenses/Apache-2.0)
|
||||||
|
|
@ -9,27 +9,38 @@
|
||||||
[](https://gitter.im/status-im/nimbus)
|
[](https://gitter.im/status-im/nimbus)
|
||||||
[](https://get.status.im/chat/public/nimbus-general)
|
[](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".
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 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
|
||||||
|
|
|
||||||
Binary file not shown.
|
After Width: | Height: | Size: 99 KiB |
Loading…
Reference in New Issue