status-im
/
nimbus-eth2
mirror of https://github.com/status-im/nimbus-eth2.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

book updates (#1422)

This commit is contained in:
Sacha Saint-Leger 2020-08-04 00:15:49 +02:00 committed by GitHub
parent 7b5411a86e
commit a7b6b72c1d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 148 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/the_nimbus_book/src/SUMMARY.md
View File

@ -2,9 +2,10 @@
- [Introduction](./intro.md)
- [Installation](./install.md)
- [Running the beacon node](./beacon_node.md)
- [Becoming a Validator](./validator.md)
- [Become a Medalla validator](./medalla.md)
- [Run the beacon node](./beacon_node.md)
- [Become a validator (custom)](./validator.md)
- [API](./api.md)
- [Advanced Usage for Developers](./advanced.md)
- [Advanced usage for developers](./advanced.md)
- [FAQs](./faq.md)
- [Contribute](./contribute.md)

57
docs/the_nimbus_book/src/beacon_node.md
View File

@ -1,43 +1,52 @@
# The beacon node
The beacon node application connects to an Ethereum 2 network, manages the block chain and provides API's to interact with the beacon chain.
The beacon node application connects to the eth2 network, manages the blockchain, and provides API's to interact with the beacon chain.
You can run the beacon node without being a validator - doing so will allow you to sync the network and access its latest state.
You can run the beacon node without being a validator - doing so allows you to sync the network and access its latest state.
## Prerequisites
Before compiling and running the application, make sure you've completed the [installation guidelines](./install.md) for the prerequisites.
Before compiling and running the application, make sure you've gone through the [installation guidelines](./install.md).
## Running the node
When running the beacon node, you connect to a specific ethereum 2 network - this may be a private network or a public testnet like [altona](https://github.com/goerli/altona/tree/master/altona).
When running the beacon node, you connect to a specific ethereum 2 network - this may be a private network or a public testnet like [Medalla](https://github.com/goerli/medalla/).
When running the node for the first time, you need to specify network parameters, boot nodes and genesis information. This information can typically be found in the [eth2 testnets](https://github.com/eth2-clients/eth2-testnets) repository. This information is automatically downloaded when using the simplified startup.
Once the beacon node is running, it will first connect to the boot nodes in the network, look for more peers and start syncing the chain. Once sync is complete, it will keep following the head of the chain and can be interacted with through the [API](./api.md).
Once the beacon node is running, it will first connect to the boot nodes in the network, look for more peers and start syncing the chain. Once the sync is complete, it will keep following the head of the chain (you can interact with it through the [API](./api.md).
Before running the beacon node, it is important that computer has the correct time set - preferably from a trusted time source (this can be an NTP server you trust, GPS time or any other precise source of time).
Before running the beacon node, it's important that your computer is set to the correct time - preferably using a trusted time source (this can be an NTP server you trust, GPS time or another precise source of time) -- however don't worry if you're unsure of how to do this, it isn't essential for testnet purposes.
To start syncing the `altona` network, run the build process. When asked for a key, just press enter.
### Syncing
To start syncing the `medalla` network:
#### 1. Clone the nim beacon chain repository
```
$ make altona
git clone https://github.com/status-im/nim-beacon-chain
cd nim-beacon-chain
```
#### 2. Run the build process
```
make medalla
# Build output...
Please enter your Goerli Eth1 private key in hex form (e.g. 0x1a2...f3c) in order to become a validator (you'll need access to 32 GoETH).
Hit Enter to skip this.
>
```
Hit enter above - you will be prompted again if you want to become a validator. Beacon node will launch and start syncing.
This will build Nimbus and its dependencies, and connect you to Medalla.
You should see that the beacon node has launched and started syncing.
```
INF 2020-07-03 15:28:15+02:00 Starting beacon node topics="beacnde" tid=176865 file=beacon_node.nim:866 SECONDS_PER_SLOT=12 SLOTS_PER_EPOCH=32 SPEC_VERSION=0.12.1 cat=init dataDir=/home/arnetheduck/status/nim-beacon-chain/build/data/shared_altona_0 finalizedRoot=72e7b21c finalizedSlot=20064 headRoot=f92bf720 headSlot=20142 nim="Nim Compiler Version 1.2.2 [Linux: amd64] (be34b5ab)" pcs=start_beacon_node timeSinceFinalization=-108322 version="0.5.0 (c64737e)"
INF 2020-07-03 15:28:15+02:00 Starting beacon node topics="beacnde" tid=176865 file=beacon_node.nim:866 SECONDS_PER_SLOT=12 SLOTS_PER_EPOCH=32 SPEC_VERSION=0.12.1 cat=init dataDir=/home/arnetheduck/status/nim-beacon-chain/build/data/shared_medalla_0 finalizedRoot=72e7b21c finalizedSlot=20064 headRoot=f92bf720 headSlot=20142 nim="Nim Compiler Version 1.2.2 [Linux: amd64] (be34b5ab)" pcs=start_beacon_node timeSinceFinalization=-108322 version="0.5.0 (c64737e)"
peers: 7 ❯ finalized: 3a806c9f:634 ❯ head: b364f8e9:636:29 ❯ time: 909:7 (29095) ETH: 0.0
```
### Status bar
@ -60,7 +69,7 @@ Nimbus includes metrics support using the Prometheus format. To enable it, you n
```
# Compile with insecure features enabled
make NIMFLAGS="-d:insecure" altona
make NIMFLAGS="-d:insecure" medalla
```
## Command line options
@ -112,7 +121,7 @@ The following options are available:
Available sub-commands:
beacon_node_shared_altona_0 createTestnet [OPTIONS]...
beacon_node_shared_medalla_0 createTestnet [OPTIONS]...
The following options are available:
@ -128,7 +137,7 @@ The following options are available:
--with-genesis-root Include a genesis root in 'network.json'.
--output-bootstrap-file Output file with list of bootstrap nodes for the network.
beacon_node_shared_altona_0 deposits [OPTIONS]... command
beacon_node_shared_medalla_0 deposits [OPTIONS]... command
The following options are available:
@ -136,7 +145,7 @@ The following options are available:
Available sub-commands:
beacon_node_shared_altona_0 deposits create [OPTIONS]...
beacon_node_shared_medalla_0 deposits create [OPTIONS]...
Creates validator keystores and deposits.
@ -151,7 +160,7 @@ The following options are available:
`deposits send` command to send the deposit transactions at your convenience
later.
beacon_node_shared_altona_0 deposits send [OPTIONS]...
beacon_node_shared_medalla_0 deposits send [OPTIONS]...
Sends prepared deposits to the validator deposit contract.
@ -161,15 +170,15 @@ The following options are available:
--min-delay Minimum possible delay between making two deposits (in seconds).
--max-delay Maximum possible delay between making two deposits (in seconds).
beacon_node_shared_altona_0 deposits status
beacon_node_shared_medalla_0 deposits status
Displays status information about all deposits.
beacon_node_shared_altona_0 wallets command
beacon_node_shared_medalla_0 wallets command
Available sub-commands:
beacon_node_shared_altona_0 wallets create [OPTIONS]...
beacon_node_shared_medalla_0 wallets create [OPTIONS]...
Creates a new EIP-2386 wallet.
@ -179,7 +188,7 @@ The following options are available:
--next-account Initial value for the 'nextaccount' property of the wallet.
--out Output wallet file.
beacon_node_shared_altona_0 wallets restore [OPTIONS]...
beacon_node_shared_medalla_0 wallets restore [OPTIONS]...
Restores a wallet from cold storage.
@ -190,7 +199,7 @@ The following options are available:
guess the number by inspecting the latest beacon state.
--out Output wallet file.
beacon_node_shared_altona_0 wallets list
beacon_node_shared_medalla_0 wallets list
Lists details about all wallets.
```

10
docs/the_nimbus_book/src/install.md
View File

@ -1,18 +1,20 @@
# Installation
Beacon chain can run on Linux, macOS, Windows, and Android. At the moment, Nimbus has to be built from source.
The Beacon chain can run on Linux, macOS, Windows, and Android. At the moment, Nimbus has to be built from source.
## Time
The beacon chain relies on your computer having the correct time set, down to at most 0.5 seconds.
It is recommended that you run a high quality time service on your computer such as:
We recommended you run a high quality time service on your computer such as:
* GPS
* NTS (network time security, IETF draft)
* Roughtime (google)
As a minimum, you should run an NTP client on the server - NTP may easily be disrupted however.
As a minimum, you should run an NTP client on the server.
If that makes no sense to you, don't worry. For testnets, just making sure your computer is set at the correct time should be fine.
## External Dependencies
@ -63,4 +65,4 @@ apt install build-essential git libpcre3-dev
## Next steps
Once you've installed the prerequisites, you're ready to move on to launching the [beacon node](./beacon_node.md).
Once you've installed the prerequisites, you're ready to move on to [running a validator on Medalla](./medalla.md).

29
docs/the_nimbus_book/src/intro.md
View File

@ -1,26 +1,31 @@
# The nim-beacon-chain Book
# The nim-beacon-chain book
_Documentation for Nimbus Beacon Chain users and developers._
_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.
The Nimbus beacon chain is a research implementation of the Beacon Chain – the core system level chain at the heart of Ethereum 2.0.
- 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.12.2#phase-0).
- Open sourced at [github.com/status-im/nim-beacon-chain](https://github.com/status-im/nim-beacon-chain/tree/master)
- Specification described at [ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs/tree/v0.12.2#phase-0)
- [Annotated Specification](https://benjaminion.xyz/eth2-annotated-spec/phase0/beacon-chain/)
- [Become a Medalla validator](./medalla.md)
## 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. [Installation steps](./install.md) outline the prerequisites to get started.
3. [Running the beacon node](./beacon_node.md) describes how to run the beacon node software to sync the beacon chain.
4. How to [become a validator](./validator.md) in Ethereum 2.0 as a user, for example on the Altona testnet.
5. [API](./api.md) for monitoring your node through `http`.
1. An introduction to the [beacon chain](./faq.md#1-what-is-beacon-chain) and [Nimbus](./faq.md#4-what-is-nimbus) to equip you with some basic knowledge.
2. [Installation steps](./install.md) outlining the prerequisites to get started.
3. [Become a Medalla validator](./medalla.md): If you generated your signing key using the eth2 launchpad, and wish to import it into the Nimbus client, this page is for you.
3. How to [run the beacon node](./beacon_node.md) software to sync the beacon chain.
4. How to generate keys, deposit, and [become a validator](./validator.md) in eth2.
5. The [API](./api.md) for monitoring your node through `http`.
6. [Advanced usage](./advanced.md) for developers.
7. Common [questions and answers](./faq.md) to satisfy your curiosity.
8. How to [contribute](./contribute.md) to this book.
Feel free to give us feedback on how to improve as well as contribute to our book on github. :)
Feel free to give us feedback on how to improve :)
## Get in touch
@ -29,7 +34,7 @@ Need help with anything? Join us using [Status](https://join.status.im/nimbus-ge
## Disclaimer
This documentation is assuming Nimbus is in its ideal state. The project is still under active development. Please submit Github issues if encountered any problem.
This documentation assumes Nimbus is in its ideal state. The project is still under active development. Please submit a [Github issue](https://github.com/status-im/nim-beacon-chain/issues) if you come across a problem.
<!-- > > > TODO:

83
docs/the_nimbus_book/src/medalla.md Normal file
View File

@ -0,0 +1,83 @@
# Become a Medalla validator
This page will take you through how to become a validator on the eth2 testnet [Medalla](https://github.com/goerli/medalla).
If you generated your signing key using the [eth2 launchpad](https://medalla.launchpad.ethereum.org/), and wish to import it into the Nimbus client, this page is for you.
> If you haven't created your validator key yet, we recommend you go through the [launchpad first](https://medalla.launchpad.ethereum.org/). If you're not sure what the eth2 launchpad is, we recommend reading this [introductory post](https://blog.ethereum.org/2020/07/27/eth2-validator-launchpad/).
## Prerequisites
If this is your first time playing with Nimbus, make sure you [install our external dependencies](./install.md) first.
This tutorial assumes basic knowledge of the [command line](https://www.learnenough.com/command-line-tutorial/basics#:~:text=Learn%20Enough%20Command%20Line%20to%20Be%20Dangerous%20is%20an%20introduction,broad%20an%20audience%20as%20possible.).
## Validating
To start validating on the `medalla` network:
#### 1. Clone the nim beacon chain repository
```
git clone https://github.com/status-im/nim-beacon-chain
cd nim-beacon-chain
git checkout devel
```
#### 2. Build the beacon node
```
make beacon_node
```
*Patience... this may take a few minutes.*
#### 3. Import keystore(s)
```
build/beacon_node deposits import --data-dir=build/data/shared_medalla_0 <YOUR VALIDATOR KEYS DIRECTORY>
```
Replacing `<YOUR VALIDATOR KEYS DIRECTORY>` with the full pathname of your `validator_keys` directory.
> Tip: run `pwd` in your `validator_keys` directory to print the full pathname to the console.
You'll be asked to enter the password you created to encrypt your keystore(s) in the *Generate Keys* section of the Launchpad process. Don't worry, this is entirely normal. Your validator client needs both your keystore(s) and the password encrypting it to import your [keys](https://blog.ethereum.org/2020/05/21/keys/) (since it needs to decrypt the keystore in order to be able to use it to sign on your behalf).
#### 4. Connect to Medalla
```
make medalla
```
This will build Nimbus and its dependencies, and connect you to Medalla.
You should see that the beacon node has launched with your validator attached and is waiting for [genesis](https://hackmd.io/@benjaminion/genesis) to start:
```
WRN 2020-08-03 16:24:17.950+02:00 Validator not in registry (yet?) topics="beacval" tid=11677993 file=validator_duties.nim:53 pubKey=a9c4df36
INF 2020-08-03 16:24:17.951+02:00 Local validator attached tid=11677993 file=validator_pool.nim:21 pubKey=a9c4df36 validator=a9c4df36
INF 2020-08-03 16:24:17.951+02:00 Local validators attached topics="beacval" tid=11677993 file=validator_duties.nim:61 count=1
INF 2020-08-03 16:24:17.958+02:00 Starting beacon node topics="beacnde" tid=11677993 file=beacon_node.nim:875 version="0.5.0 (31b33907)" nim="Nim Compiler Version 1.2.6 [MacOSX: amd64] (bf320ed1)" timeSinceFinalization=81350 head=ebe49843:0 finalizedHead=ebe49843:0 SLOTS_PER_EPOCH=32 SECONDS_PER_SLOT=12 SPEC_VERSION=0.12.2 dataDir=build/data/shared_medalla_0 pcs=start_beacon_node
NOT 2020-08-03 16:24:17.958+02:00 Waiting for genesis topics="beacnde" tid=11677993 file=beacon_node.nim:890 genesisIn=22h35m50s0ns
```
#### 5. Keep an eye on your validator
If you deposited after the [genesis](https://hackmd.io/@benjaminion/genesis) state was decided (August 2nd 1300 UTC), your validators will have been put in a queue based on deposit time, and will slowly be inducted into the validator set after genesis. Getting through the queue may take a few hours or days.
The best way to keep track of your validator's status is [medalla.beaconcha.in](https://medalla.beaconcha.in) (click on the orange magnifying glass at the very top and paste in its public key).
You can even [create an account](https://medalla.beaconcha.in/register) to add alerts and keep track it its [performance](https://medalla.beaconcha.in/dashboard).
Finally, makes sure you stay on the lookout for any critical updates to Nimbus. This best way to do so is through our [discord](https://discord.com/invite/XRxWahP).
Looking forward to seeing you on Medalla! 💛
### A note on keys
The Nimbus client will only ever import your signing key -- in any case, if you used the deposit launchpad, this is the only key you should have (you can generate the withdrawal key from your mnemonic when you wish to withdraw). The keys your Nimbus client has access to are stored in the `build/data/shared_medalla_0/` folder, under `secrets` and `validators`.
The `secrets` folder contains the common secret that gives you access to all your validator keys. And the `validators` folder contains your keystores.
For more on keys in eth2, see [here](https://blog.ethereum.org/2020/05/21/keys/).

6
docs/the_nimbus_book/src/validator.md
View File

@ -1,7 +1,11 @@
# Become a Validator
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.
> Note, the instructions below currently apply to Altona. They will be updated shortly to explain how you can use Nimbus to create your validator keys and interact with the Medalla deposit contract.
>
> To become a validator on Medalla using the [eth2 launchpad](https://medalla.launchpad.ethereum.org/), see [here](./medalla.md).
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