diff --git a/README.md b/README.md index a3e82b1622..ef3052c206 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,245 @@ -# Lighthouse: a (future) Ethereum 2.0 client +# Lighthouse: an Ethereum 2.0 client [![Build Status](https://travis-ci.org/sigp/lighthouse.svg?branch=master)](https://travis-ci.org/sigp/lighthouse) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](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 -$ 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).