Re-write readme
This commit is contained in:
Paul Hauner
parent
6a75aa3246
commit
95213609e8
274
README.md
274
README.md
@ -1,59 +1,245 @@
|
||||
# Lighthouse: a (future) Ethereum 2.0 client
|
||||
# Lighthouse: an Ethereum 2.0 client
|
||||
|
||||
[](https://travis-ci.org/sigp/lighthouse) [](https://gitter.im/sigp/lighthouse?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
||||
|
||||
A **work-in-progress** implementation of the Ethereum 2.0 Beacon Chain in Rust.
|
||||
A work-in-progress, open-source implementation of the Ethereum 2.0 Beacon Chain, maintained
|
||||
by Sigma Prime.
|
||||
|
||||
It is an implementation of the [Full PoS Casper chain
|
||||
v2](https://notes.ethereum.org/SCIg8AH5SA-O4C1G1LYZHQ?view) spec and is also
|
||||
largely based upon the
|
||||
[ethereum/beacon_chain](https://github.com/ethereum/beacon_chain) repo.
|
||||
## Introduction
|
||||
|
||||
**NOTE: the cryptography libraries used in this implementation are very
|
||||
Lighthouse is an open-source Ethereum 2.0 client, in development. It is an
|
||||
Ethereum 2.0-_only_ client, meaning it won't re-implement the present
|
||||
proof-of-work protocol. This will help it stay focussed on 2.0 without
|
||||
reproducing the work that other clients are already doing very well.
|
||||
|
||||
This readme is split into two major sections:
|
||||
|
||||
- [Lighthouse Client](#lighthouse-client): information about this
|
||||
implemenation.
|
||||
- [What is Ethereum 2.0](#what-is-ethereum-20): an introduction to Ethereum 2.0.
|
||||
|
||||
If you'd like some background on Sigma Prime, please see the [Lighthouse Update
|
||||
\#00](https://lighthouse.sigmaprime.io/update-00.html) blog post.
|
||||
|
||||
## Lighthouse Client
|
||||
|
||||
|
||||
### Goals
|
||||
|
||||
We aim to contribute to the research and development of a secure, efficient and
|
||||
decentralised Ethereum protocol through the development of an open-source
|
||||
Ethereum 2.0 client.
|
||||
|
||||
We aim to provide a secure and efficient open-source client. As well as
|
||||
building an implementation, we seek to help maintain and improve the protocol
|
||||
wherever possible.
|
||||
|
||||
### Components
|
||||
|
||||
Lighthouse is presently focussed on the Beacon Chain implementation. Here are
|
||||
some of the components actively under development by the team:
|
||||
|
||||
- **BLS cryptography**: we presently use the [Apache
|
||||
Milagro](https://milagro.apache.org/) cryptography library to create and
|
||||
verify BLS aggregate signatures. These signatures are core to Eth 2.0 and allow
|
||||
the signatures of many validators to be compressed into a constant 96 bytes and
|
||||
verified efficiently. We're presently maintaining our own [BLS aggregates
|
||||
library](https://github.com/sigp/signature-schemes), gratefully forked from
|
||||
@lovesh.
|
||||
- **DoS-resistant block pre-processing**: processing blocks in proof-of-stake
|
||||
is more resource intensive than proof-of-work. As such, clients need to
|
||||
ensure that bad blocks can be rejected as efficiently as possible. We can
|
||||
presently process a block with 10 million ETH staked in 0.006 seconds and
|
||||
reject valid blocks even quicker. See the
|
||||
[issue](https://github.com/ethereum/beacon_chain/issues/103) on
|
||||
[ethereum/beacon_chain](https://github.com/ethereum/beacon_chain)
|
||||
.
|
||||
- **P2P networking**: Eth 2.0 is likely use the [libp2p
|
||||
framework](https://libp2p.io/), lighthouse hopes to work alongside
|
||||
[Parity](https://www.parity.io/) to get
|
||||
[libp2p-rust](https://github.com/libp2p/rust-libp2p) fit-for-purpose.
|
||||
- **Validator duties** : providing "validator" services to users who wish to
|
||||
stake ETH. This involves maintaining a consistent view of the chain and
|
||||
voting upon shard and beacon chain blocks.
|
||||
- **New serialization formats**: lighthouse is working alongside the EF
|
||||
researchers to develop "simpleserialize" a purpose-built serialization format
|
||||
for sending information across the network. Check our our [SSZ
|
||||
implementation](https://github.com/sigp/lighthouse/tree/master/beacon_chain/utils/ssz)
|
||||
and our
|
||||
[research](https://github.com/sigp/serialization_sandbox/blob/report/report/serialization_report.md)
|
||||
on serialization formats.
|
||||
- **Casper FFG fork-choice**: the [Casper
|
||||
FFG](https://arxiv.org/abs/1710.09437) fork-choice rules allow the chain to
|
||||
select a canonical chain in the case of a fork.
|
||||
- **Efficient state transition logic**: "state transition" logic deals with
|
||||
updating the validator set as valiators log in/out, penalising/rewarding
|
||||
validators, rotating validators across shards, and many other core tasks.
|
||||
- **Fuzzing and testing environments**: we preparing to implement lab
|
||||
environments with CI work-flows to provide automated security analysis.
|
||||
|
||||
On top of these components we're also working on database schemas,
|
||||
RPC frameworks, specification development, database optimizations (e.g.,
|
||||
bloom-filters) and tons of other interesting stuff (at least we think so).
|
||||
|
||||
### Contributing
|
||||
|
||||
**Lighthouse welcomes contributors with open-arms.**
|
||||
|
||||
Layer-1 infrastructure is a critical component of the ecosystem and relies
|
||||
heavily on community contribution. Building Ethereum 2.0 is a huge task and we
|
||||
refuse to "do an ICO" or charge licensing fees. Instead, we fund development
|
||||
through grants and support from Sigma Prime.
|
||||
|
||||
If you would like to learn more about Ethereum 2.0 and/or
|
||||
[Rust](https://www.rust-lang.org/), we would be more than happy to on-board you
|
||||
and assign you to some tasks. We aim to be as accepting and understanding as
|
||||
possible; we are more than happy to up-skill contributors in exchange for their
|
||||
help on the project.
|
||||
|
||||
Alternatively, if you an ETH/Rust veteran we'd love to have your input. We're
|
||||
always looking for the best way to do things and will always consider any
|
||||
respectfully presented criticism.
|
||||
|
||||
If you'd like to contribute, try having a look through the [open
|
||||
issues](https://github.com/sigp/lighthouse/issues) (tip: look for the [good
|
||||
first
|
||||
issue](https://github.com/sigp/lighthouse/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
|
||||
tag) and ping us on the [gitter](https://gitter.im/sigp/lighthouse). We need
|
||||
your support!
|
||||
|
||||
### Running
|
||||
|
||||
**NOTE: the cryptography libraries used in this implementation are
|
||||
experimental and as such all cryptography should be assumed to be insecure.**
|
||||
|
||||
## Motivation
|
||||
The code-base is still under-development and does not provide any user-facing
|
||||
functionality. However, there are a lot of tests and some benchmarks if that
|
||||
sort of thing interests you.
|
||||
|
||||
The objective of this project is to build a purely Ethereum 2.0 client from
|
||||
the ground up.
|
||||
|
||||
As such, the early days of Lighthouse will be very much a research effort -- it
|
||||
will be evolving on the bleeding-edge of specification without requiring to
|
||||
maintain prod-grade stability or backwards-compatibility for the existing PoW
|
||||
chain.
|
||||
|
||||
Whilst the Beacon Chain relies upon the PoW chain for block hashes, Lighthouse
|
||||
will need to run alongside an existing client (e.g., Geth, Parity Ethereum),
|
||||
only being able to stand by itself once the PoW chain has been deprecated.
|
||||
|
||||
Lighthouse aims to assist in advancing the progress of the following Ethereum
|
||||
technologies:
|
||||
|
||||
- Proof-of-Stake
|
||||
- Sharding
|
||||
- EVM alternatives (e.g., WASM)
|
||||
- Scalable, topic-based P2P networks (e.g., libp2p-gossipsub)
|
||||
- Scalable signature schemes (e.g, BLS aggregates)
|
||||
|
||||
## Progress
|
||||
|
||||
As of 02/08/2018, there is a basic libp2p implementation alongside a series of
|
||||
state objects and state transition functions. There are no syncing capabilities.
|
||||
|
||||
## Usage
|
||||
|
||||
You can run the tests like this:
|
||||
To run the tests, use
|
||||
|
||||
```
|
||||
$ git clone <url>
|
||||
$ cd rust_beacon_chain
|
||||
$ cargo test
|
||||
$ cargo test --all
|
||||
```
|
||||
|
||||
To run benchmarks, use
|
||||
|
||||
```
|
||||
$ cargo bench --all
|
||||
```
|
||||
|
||||
Lighthouse presently runs on Rust `stable`, however benchmarks require the
|
||||
`nightly` version.
|
||||
|
||||
### Engineering Ethos
|
||||
|
||||
Lighthouse aims to produce many small, easily-tested components, each separated
|
||||
into individual crates wherever possible.
|
||||
|
||||
Generally, tests can be kept in the same file, as is typical in Rust.
|
||||
Integration tests should be placed in the `tests` directory in the crates root.
|
||||
Particularity large (line-count) tests should be separated into another file.
|
||||
|
||||
A function is not complete until it is tested. We produce tests to help
|
||||
ourselves and others understand others code and to provide protection from
|
||||
regression (breaking stuff accidentally).
|
||||
|
||||
Each PR is to be reviewed by at-least one "core developer" (i.e., someone with
|
||||
write-access to the repository). This helps to detect bugs, improve consistency
|
||||
and relieves any one individual of the responsibility of an error.
|
||||
|
||||
Discussion should be respectful and intellectual. Have fun, make jokes but
|
||||
respect other peoples limits.
|
||||
|
||||
### Directory Structure
|
||||
|
||||
Here we provide an overview of the directory structure:
|
||||
|
||||
- `\beacon_chain`: contains logic derived directly from the specification.
|
||||
E.g., shuffling algorithms, state transition logic and structs, block
|
||||
validation, BLS crypto, etc.
|
||||
- `\lighthouse`: contains logic specific to this client implementation. E.g.,
|
||||
CLI parsing, RPC end-points, databases, etc.
|
||||
- `\network-libp2p`: contains a proof-of-concept libp2p implementation. Will be
|
||||
replaced once research around p2p has been finalized.
|
||||
|
||||
## Contact
|
||||
|
||||
This repo is presently authored by Paul Hauner as a
|
||||
[Sigma Prime](https://github.com/sigp) project.
|
||||
The best place for discussion is the [sigp/lighthouse](https://gitter.im/sigp/lighthouse) gitter.
|
||||
Ping @paulhauner or @AgeManning to get the quickest response.
|
||||
|
||||
|
||||
# What is Ethereum 2.0
|
||||
|
||||
Ethereum 2.0 is the name that has been given to a new blockchain being
|
||||
developed by the Ethereum Foundation and the Ethereum community. Ethereum 2.0
|
||||
consists of 1,025 proof-of-stake blockchains; the "beacon chain" and 1,024
|
||||
"shard chains".
|
||||
|
||||
## Beacon Chain
|
||||
|
||||
The Beacon Chain is a little different to more common blockchains like Bitcoin
|
||||
and present-Ethereum in that it doesn't process "transactions", per say.
|
||||
Instead, it maintains a set of bonded (staked) validators and co-ordinates them
|
||||
to provide services to a static set of "sub-blockchains" (shards). These shards
|
||||
then process the normal "5 ETH from A to B" transactions in _parallel_ whilst
|
||||
deferring consensus to the Beacon Chain.
|
||||
|
||||
Here are some of the major services that the beacon chain provides to its
|
||||
shards:
|
||||
|
||||
- A source of entropy, likely using a [RANDAO + VDF
|
||||
scheme](https://ethresear.ch/t/minimal-vdf-randomness-beacon/3566).
|
||||
- Valdidator management, including:
|
||||
- Inducting and ejecting validators.
|
||||
- Delegating randomly-shuffled subsets of validators to validate shards.
|
||||
- Penalising and rewarding validators.
|
||||
- Proof-of-stake consensus for shard chain blocks.
|
||||
|
||||
## Shard Chains
|
||||
|
||||
Shards can be thought of like CPU cores, they're a lane where transactions can
|
||||
execute in series (one-after-another). Presently, Ethereum is single-core and
|
||||
can only _fully_ process one transaction at a time. Sharding allows multiple
|
||||
transactions to happen in parallel, greatly increasing the per-second
|
||||
transaction capacity of Ethereum.
|
||||
|
||||
Each shard is proof-of-stake and shares its validators (stakers) with the other
|
||||
shards as the beacon chain rotates validators pseudo-randomly across shards.
|
||||
Shards will likely be the basis of very interesting layer-2 transaction
|
||||
processing schemes, however we won't get into that here.
|
||||
|
||||
## The Proof-of-Work Chain
|
||||
|
||||
The proof-of-work chain will hold a contract to allow addresses to deposit 32
|
||||
ETH, a BLS public key and some [other
|
||||
parameters](https://github.com/ethereum/eth2.0-specs/blob/master/specs/casper_sharding_v2.1.md#pow-chain-changes)
|
||||
to allow them to become Beacon Chain validators. Each Beacon Chain will
|
||||
reference a PoW block hash allowing PoW clients to use the Beacon Chain as a
|
||||
source of [Casper FFG finality](https://arxiv.org/abs/1710.09437), if they
|
||||
desire.
|
||||
|
||||
## Ethereum 2.0 Progress
|
||||
|
||||
Ethereum 2.0 is not fully specified and there's no working implementation. Some
|
||||
teams have demos available, however these demos indicate _progress_, not
|
||||
completion. We look forward to providing user functionality once we are ready
|
||||
to provide a minimum-viable user experience.
|
||||
|
||||
The work-in-progress specification lives
|
||||
[here](https://github.com/ethereum/eth2.0-specs/blob/master/specs/casper_sharding_v2.1.md)
|
||||
in the [ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs)
|
||||
repository. It is still in a draft phase, however there are several teams
|
||||
already implementing it. This spec is being developed by Ethereum Foundation
|
||||
researchers, most notably Vitalik Buterin. There is active discussion about the
|
||||
spec in the [ethereum/sharding](https://gitter.im/ethereum/sharding) gitter
|
||||
channel. There is a proof-of-concept implementation in Python at
|
||||
[ethereum/beacon_chain](https://github.com/ethereum/beacon_chain).
|
||||
|
||||
Presently, the spec almost exclusively defines the Beacon Chain as it
|
||||
is the focus of present development efforts. Progress on shard chain
|
||||
specification will soon follow.
|
||||
|
||||
|
||||
|
||||
|
||||
The best place for discussion is probably the [ethereum/sharding
|
||||
gitter](https://gitter.im/ethereum/sharding).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user