Add newly created mdbook

This commit is contained in:
Paul Hauner 2019-09-01 11:31:18 +10:00
parent 5f0509be50
commit 14ea6f7710
No known key found for this signature in database
GPG Key ID: 303E4494BB28068C
7 changed files with 260 additions and 0 deletions

1
book/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
book

6
book/book.toml Normal file
View File

@ -0,0 +1,6 @@
[book]
authors = ["Paul Hauner"]
language = "en"
multilingual = false
src = "src"
title = "Lighthouse"

7
book/src/SUMMARY.md Normal file
View File

@ -0,0 +1,7 @@
# Summary
* [Introduction](./intro.md)
* [Development Environment](./setup.md)
* [Testnets](./testnets.md)
* [Simple local testnet](./testnets.md)
* [Interop](./interop.md)

70
book/src/interop.md Normal file
View File

@ -0,0 +1,70 @@
# Lighthouse Interop Guide
This guide is intended for other Ethereum 2.0 client developers performing
inter-operability testing with Lighthouse.
To allow for faster iteration cycles without the "merging to master" overhead,
we will use the [`interop`](https://github.com/sigp/lighthouse/tree/interop)
branch of [sigp/lighthouse](https://github.com/sigp/lighthouse/tree/interop)
for September 2019 interop. **Please use ensure you `git checkout interop`
after cloning the repo.**
## Environment
All that is required for inter-op is a built and tested [development
environment](setup). When lighthouse boots, it will create the following
directories:
- `~/.lighthouse`: database and configuration for the beacon node.
- `~/.lighthouse-validator`: database and configuration for the validator
client.
After building the binaries with `cargo build --release --all`, there will be a
`target/release` directory in the root of the Lighthouse repository. This is
where the `beacon_node` and `validator_client` binaries are located.
## Interop Procedure
The following scenarios are documented:
- [Starting a "quick-start" beacon node](#quick-start-beacon-node) from a
`(validator_count, genesis)` tuple.
- [Starting a validator client](#validator-client) with `n` interop keypairs.
- [Starting a node from a genesis state file](#starting-from-a-genesis-file).
- [Exporting a genesis state file](#exporting-a-genesis-file) from a running Lighthouse
node.
First, setup a Lighthouse development environment and navigate to the
`target/release` directory (this is where the binaries are located).
#### Quick-start Beacon Node
To start the node (each time creating a fresh database and configuration in
`~/.lighthouse`), use:
```
$ ./beacon_node testnet -f quick 8 1567222226
```
>This method conforms the ["Quick-start
genesis"](https://github.com/ethereum/eth2.0-pm/tree/6e41fcf383ebeb5125938850d8e9b4e9888389b4/interop/mocked_start#quick-start-genesis)
method in the `ethereum/eth2.0-pm` repository.
>
> The `-f` flag ignores any existing database or configuration, backing them up
before re-initializing. `8` is the validator count and `1567222226` is the
genesis time.
>
> See `$ ./beacon_node testnet quick --help` for more configuration options.
#### Validator Client
**TODO**
#### Starting from a genesis file
**TODO**
#### Exporting a genesis file
**TODO**

47
book/src/intro.md Normal file
View File

@ -0,0 +1,47 @@
# Lighthouse Documentation
[![Build Status]][Build Link] [![Doc Status]][Doc Link] [![Chat Badge]][Chat Link]
[Build Status]: https://gitlab.sigmaprime.io/sigp/lighthouse/badges/master/build.svg
[Build Link]: https://gitlab.sigmaprime.io/sigp/lighthouse/pipelines
[Chat Badge]: https://img.shields.io/badge/chat-discord-%237289da
[Chat Link]: https://discord.gg/cyAszAh
[Doc Status]:https://img.shields.io/badge/rust--docs-master-orange
[Doc Link]: http://lighthouse-docs.sigmaprime.io/
Lighthouse is an **Ethereum 2.0 client** that connects to other Ethereum 2.0
clients to form a resilient and decentralized proof-of-stake blockchain.
It is written in Rust, maintained by Sigma Prime and funded by the Ethereum
Foundation, Consensys and other individuals and organisations.
## Developer Resources
Documentation is provided for **researchers and developers** working on
Ethereum 2.0 and assumes prior knowledge on the topic.
- Get started with [development environment setup](setup.html).
- [Run a simple testnet](testnets.html) in Only Three CLI Commands™.
- Read about our interop workflow.
- API?
## Release
Ethereum 2.0 is not fully specified or implemented and as such, Lighthouse is
still **under development**.
We are on-track to provide a public, multi-client testnet in late-2019 and an
initial production-grade blockchain in 2020.
## Features
Lighthouse has been in development since mid-2018 and has an extensive feature
set:
- Libp2p networking stack, featuring Discovery v5.
- Optimized `BeaconChain` state machine, up-to-date and
passing all tests.
- RESTful HTTP API.
- Documented and feature-rich CLI interface.
- Capable of running small, local testnets with 250ms slot times.
- Detailed metrics exposed in the Prometheus format.

65
book/src/setup.md Normal file
View File

@ -0,0 +1,65 @@
# Development Environment Setup
Follow this guide to get a Lighthouse development environment up-and-running.
See the [Quick instructions](#quick-instructions) for a summary or the
[Detailed instructions](#detailed-instructions) for clarification.
## Quick instructions
1. Install Rust + Cargo with [rustup](https://rustup.rs/).
1. Install build dependencies using your package manager.
- `$ <package-manager> clang protobuf libssl-dev cmake git-lfs`
- Ensure [git-lfs](https://git-lfs.github.com/) is installed with `git lfs
install`.
1. Clone the [sigp/lighthouse](https://github.com/sigp/lighthouse), ensuring to
**initialize submodules**.
1. In the root of the repo, run the tests with `cargo test --all --release`.
1. Then, build the binaries with `cargo build --all --release`.
1. Lighthouse is now fully built and tested.
_Note: first-time compilation may take several minutes._
## Detailed instructions
A fully-featured development environment can be achieved with the following
steps:
1. Install [rustup](https://rustup.rs/).
1. Use the command `rustup show` to get information about the Rust
installation. You should see that the active tool-chain is the stable
version.
- Updates can be performed using` rustup update`, Lighthouse generally
requires a recent version of Rust.
1. Install build dependencies (Arch packages are listed here, your
distribution will likely be similar):
- `clang`: required by RocksDB.
- `protobuf`: required for protobuf serialization (gRPC)
- `libssl-dev`: also gRPC
- `cmake`: required for building protobuf
- `git-lfs`: The Git extension for [Large File
Support](https://git-lfs.github.com/) (required for Ethereum Foundation
test vectors).
1. Clone the repository with submodules: `git clone --recursive
https://github.com/sigp/lighthouse`. If you're already cloned the repo,
ensure testing submodules are present: `$ git submodule init; git
submodule update`
1. Change directory to the root of the repository.
1. Run the test suite with `cargo test --all --release`. The build and test
process can take several minutes. If you experience any failures on
`master`, please raise an
[issue](https://github.com/sigp/lighthouse/issues).
### Notes:
Lighthouse targets Rust `stable` but generally runs on `nightly` too.
#### Note for Windows users:
Perl may also be required to build lighthouse. You can install [Strawberry
Perl](http://strawberryperl.com/), or alternatively use a choco install command
`choco install strawberryperl`.
Additionally, the dependency `protoc-grpcio v0.3.1` is reported to have issues
compiling in Windows. You can specify a known working version by editing
version in `protos/Cargo.toml` section to `protoc-grpcio = "<=0.3.0"`.

64
book/src/testnets.md Normal file
View File

@ -0,0 +1,64 @@
# Simple Local Testnet
You can setup a local, two-node testnet in **Only Three CLI Commands™**.
Follow the [Quick instructions](#tldr) version if you're confident, or see
[Detailed instructions](#detail) for more.
## Quick instructions
Setup a development environment, build the project and navigate to the
`target/release` directory.
1. Start the first node: `$ ./beacon_node testnet -f recent 8`
1. Start a validator client: **TODO**
1. Start another node `$ ./beacon_node -b 10 testnet -f bootstrap http://localhost:5052`
_Repeat #3 to add more nodes._
## Detailed instructions
First, setup a Lighthouse development environment and navigate to the
`target/release` directory (this is where the binaries are located).
## Starting the Beacon Node
Start a new node (creating a fresh database and configuration in `~/.lighthouse`), using:
```
$ ./beacon_node testnet -f recent 8
```
> The `-f` flag ignores any existing database or configuration, backing them up
before re-initializing. `8` is number of validators with deposits in the
genesis state.
>
> See `$ ./beacon_node testnet recent --help` for more configuration options,
including `minimal`/`mainnet` specification.
## Starting the Validator Client
**TODO**
## Adding another Beacon Node
You may connect another (non-validating) node to your local network using the
lighthouse `bootstrap` command.
In a new terminal terminal, run:
```
$ ./beacon_node -b 10 testnet -r bootstrap http://localhost:5052
```
> The `-b` (or `--port-bump`) increases all the listening TCP/UDP ports of the
new node to `10` higher. Your first node's HTTP server was at TCP `5052` but
this one will be at `5062`.
>
> The `-r` flag creates a new data directory in your home with a random string
appended, to avoid conflicting with any other running node.
>
> The HTTP address is the API of the first node. The new node will download
configuration via HTTP before starting sync via libp2p.