From 55f977902151b6a56260dc63bbad54421716d8ee Mon Sep 17 00:00:00 2001 From: Chris Natoli Date: Mon, 7 Jan 2019 11:52:55 +1100 Subject: [PATCH 1/8] Rewrite goals --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e28855504..669d26a8b 100644 --- a/README.md +++ b/README.md @@ -33,9 +33,10 @@ present-Ethereum functionality. ### Goals -The purpose of this project is to further research and development towards a -secure, efficient, and decentralized Ethereum protocol, facilitated by a new -open-source Ethereum Serenity client. +The purpose of this project is to work alongside the Ethereum community and +implement a secure, open-source Ethereum Serenity client in Rust. With the +focus on security, the goal for Lighthouse is to provide a trustworthy, well +tested, secure client that is resilient to any errors. In addition to implementing a new client, the project seeks to maintain and improve the Ethereum protocol wherever possible. From 0343cd1cbfa61961d43a67e5df6172e709a3129f Mon Sep 17 00:00:00 2001 From: Chris Natoli Date: Mon, 7 Jan 2019 11:52:15 +1100 Subject: [PATCH 2/8] Rework goals; Add categories and more content --- README.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 669d26a8b..d4ad0957a 100644 --- a/README.md +++ b/README.md @@ -33,10 +33,28 @@ present-Ethereum functionality. ### Goals -The purpose of this project is to work alongside the Ethereum community and -implement a secure, open-source Ethereum Serenity client in Rust. With the -focus on security, the goal for Lighthouse is to provide a trustworthy, well -tested, secure client that is resilient to any errors. +The purpose of this project is to work alongside the Ethereum community to +implement a secure, trustworthy, open-source Ethereum Serenity client in Rust. + +* **Security**: Lighthouse's main goal is to implement everything with a +security-first mindset. The goal is to ensure that all components of lighthouse +are thoroughly tested, checked and secure. + +* **Trust** : As Ethereum Serenity is a Proof-of-Stake system, which +involves the interaction of the Ethereum protocol and user funds. Thus, a goal +of Lighthouse is to provide a client that is trustworthy. + + All code can be tested and verified the goal of Lighthouse is to provide code +that is trusted. + +* **Transparency**: Lighthouse aims at being as transparent as possible. This goal is for +Lighthouse to embrace the open-source community and allow for all to understand +the decisions, direction and changes in all aspects. + +* **Error Resilience**: As Lighthouse embraces the "never `panic`" mindset, the +goal is to be resilient to errors that may occur. Providing a client that has +tolerance against errors provides further properties for a secure, trustworthy +client that Lighthouse aims to provide. In addition to implementing a new client, the project seeks to maintain and improve the Ethereum protocol wherever possible. From 450ac2b7f9a0d2efc1317ee81389165a836b7d71 Mon Sep 17 00:00:00 2001 From: Chris Natoli Date: Mon, 7 Jan 2019 13:56:07 +1100 Subject: [PATCH 3/8] Minor structure change; Nitpicks; --- README.md | 69 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 35 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index d4ad0957a..8e85c9cf4 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ If you'd like some background on Sigma Prime, please see the [Lighthouse Update ## Lighthouse Client Lighthouse is an open-source Ethereum Serenity client that is currently under -development. Designed as a Serenity-only client, Lighthouse will not +development. Designed as a Serenity-only client, Lighthouse will not re-implement the existing proof-of-work protocol. Maintaining a forward-focus on Ethereum Serenity ensures that Lighthouse avoids reproducing the high-quality work already undertaken by existing projects. As such, Lighthouse will connect @@ -76,12 +76,11 @@ by the team: is more resource intensive than proof-of-work. As such, clients need to ensure that bad blocks can be rejected as efficiently as possible. At present, blocks having 10 million ETH staked can be processed in 0.006 - seconds, and invalid blocks are rejected even more quickly. See [issue - #103](https://github.com/ethereum/beacon_chain/issues/103) on + seconds, and invalid blocks are rejected even more quickly. See + [issue #103](https://github.com/ethereum/beacon_chain/issues/103) on [ethereum/beacon_chain](https://github.com/ethereum/beacon_chain). -. - **P2P networking**: Serenity will likely use the [libp2p - framework](https://libp2p.io/). Lighthouse aims to work alongside + framework](https://libp2p.io/). Lighthouse is working alongside [Parity](https://www.parity.io/) to ensure [libp2p-rust](https://github.com/libp2p/rust-libp2p) is fit-for-purpose. - **Validator duties** : The project involves development of "validator @@ -96,9 +95,10 @@ implementation](https://github.com/sigp/lighthouse/tree/master/beacon_chain/util and this [research](https://github.com/sigp/serialization_sandbox/blob/report/report/serialization_report.md) on serialization formats for more information. -- **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. +- **Fork-choice**: The current fork choice rule is +[*LMD Ghost*](https://vitalik.ca/general/2018/12/05/cbc_casper.html#lmd-ghost), +which effectively takes the latest messages and forms the canonical chain using +the [GHOST](https://eprint.iacr.org/2013/881.pdf) mechanism. - **Efficient state transition logic**: State transition logic governs updates to the validator set as validators log in/out, penalizes/rewards validators, rotates validators across shards, and implements other core tasks. @@ -109,32 +109,6 @@ In addition to these components we are 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 for the ecosystem and relies -heavily on contributions from the community. Building Ethereum Serenity is a huge -task and we refuse to conduct an inappropriate 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 Serenity and/or -[Rust](https://www.rust-lang.org/), we are more than happy to on-board you -and assign you 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 -assistance with the project. - -Alternatively, if you are an ETH/Rust veteran, we'd love your input. We're -always looking for the best way to implement things and welcome all -respectful criticisms. - -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) channel. We need -your support! - ### Running **NOTE: The cryptography libraries used in this implementation are @@ -167,6 +141,33 @@ A few basic steps are needed to get set up: Lighthouse presently runs on Rust `stable`, however, benchmarks currently require the `nightly` version. + +### Contributing + +**Lighthouse welcomes contributors with open-arms.** + +Layer-1 infrastructure is a critical component for the ecosystem and relies +heavily on contributions from the community. Building Ethereum Serenity is a huge +task and we refuse to conduct an inappropriate 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 Serenity and/or +[Rust](https://www.rust-lang.org/), we are more than happy to on-board you +and assign you 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 +assistance with the project. + +Alternatively, if you are an ETH/Rust veteran, we'd love your input. We're +always looking for the best way to implement things and welcome all +respectful criticisms. + +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) channel. We need +your support! + ### Engineering Ethos Lighthouse aims to produce many small easily-tested components, each separated From 27c6d14a612a7865a35191aabada54868424380b Mon Sep 17 00:00:00 2001 From: Chris Natoli Date: Mon, 7 Jan 2019 15:14:48 +1100 Subject: [PATCH 4/8] Add serenity doc; Move info from readme/onboarding into serenity doc; --- docs/Serenity.md | 161 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/Serenity.md diff --git a/docs/Serenity.md b/docs/Serenity.md new file mode 100644 index 000000000..9a190449f --- /dev/null +++ b/docs/Serenity.md @@ -0,0 +1,161 @@ +# Ethereum Serenity + +This document aims at providing a high level understanding of Ethereum and the +Serenity phase of the Ethereum roadmap. + +## The Blockchain + +A blockchain can be seen as a decentralized, distributed ledger. The ledger of +transactions is replicated onto all nodes in the network. When a transaction +occurs, it is first propagated to the nodes. Once the nodes receive the +transaction, and verifies the correctness, the nodes attempt to batch the +transactions into a block and append the block to the ledger. Once the ledger +has been successfully appended onto, they propagate the block to the network. +If accepted, this block now becomes the latest block in the chain. If two people +propose a block at the same time, the one canonical blockchain forks. At this +point it must be resolved, and each system has it's own way of resolving these +forks. + +![Blockchain](http://yuml.me/b0d6b30a.jpg) +
Figure 1. Example blockchain with a resolved fork.
+ +
+ +The idea of the blockchain was first proposed in the seminal [Bitcoin +whitepaper](https://bitcoin.org/bitcoin.pdf) by Satoshi Nakamoto. Since then, a +vast number of updates and blockchains have taken shape providing different +functionality or properties to the original blockchain. + +## What is Ethereum? + +Ethereum is an open blockchain protocol, allowing for the building and use of +decentralized applications that run on blockchain technology. Ethereum was one +of the initial platforms providing turing-complete code to be run on the +blockchain, allowing for conditional payments to occur through the use of this +code. Since then, Ethereum has advanced to allow for a number of Decentralized +Applications (DApps) to be developed and run completely with the blockchain as +the backbone. + +General Ethereum Introduction: + +* [What is Ethereum](http://ethdocs.org/en/latest/introduction/what-is-ethereum.html) +* [Ethereum Introduction](https://github.com/ethereum/wiki/wiki/Ethereum-introduction) + + +### Proof-of-Work and the current state of Ethereum. + +Currently, Ethereum is based on the Proof-of-Work model, a Sybil resilient +mechanism to allow nodes to propose blocks to the network. Although it provides +properties that allow the blockchain to operate in an open, public +(permissionless) network, it faces it's challenges and as a result impacts +the operation of the blockchain. + +The main goals to advance Ethereum is to (1) increase the scalability and +overall transaction processing power of the Ethereum world computer and (2) +find a suitable replacement for Proof-of-Work that still provides the necessary +properties that we need. + +* [Proof-of-Work in Cryptocurrencies: an accessible introduction](https://blog.sigmaprime.io/what-is-proof-of-work.html) + +## Serenity + +Ethereum Serenity refers to a new blockchain system currently under development +by the Ethereum Foundation and the Ethereum community. + +As part of the original Ethereum roadmap +[\[1\]](https://blog.ethereum.org/2015/03/03/ethereum-launch-process/) +[\[2\]](http://ethdocs.org/en/latest/introduction/the-homestead-release.html), +the Proof-of-Stake integration falls under **Release Step 4: *Serenity***. With +this, a number of changes are to be made to the current Ethereum protocol to +incorporate some of the new Proof-of-Stake mechanisms as well as improve on +some of the hindrances faced by the current Proof-of-Work chain. + +To now advance the current Ethereum, the decision is made to move to a sharded +Beacon chain structure where multiple shard-chains will be operating and +interacting with a central beacon chain.The Serenity blockchain consists of +1,025 proof-of-stake blockchains. This includes the "beacon chain" and 1,024 +"shard chains". + +Ethereum Serenity is also known as "Ethereum 2.0" and "Shasper". We prefer +Serenity as it more accurately reflects the established Ethereum roadmap (plus +we think it's a nice name). + +(Be mindful, the specifications change occasionally, so check these to keep up +to date) + +* Current Specifications: + * [Danny Ryan's "State of the Spec"](https://notes.ethereum.org/s/BJEZWNoyE) (A nice summary of the current specifications) + * [Ethereum Serenity - Phase 0: Beacon Chain Spec](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md) + * [Ethereum Serenity - Phase 1: Sharded Data Chains](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/1_shard-data-chains.md) + * [Beacon Chain - Vitalik Buterin and Justin Drake explain](https://www.youtube.com/watch?v=GAywmwGToUI) +* Understanding Sharding: + * [Prysmatic Labs: Sharding Explained](https://medium.com/prysmatic-labs/how-to-scale-ethereum-sharding-explained-ba2e283b7fce) +* Other relevant resources + * [Proof of Stake - Casper FFG](https://www.youtube.com/watch?v=uQ3IqLDf-oo) + * [Justin Drake VDF Devcon4 Talk](https://www.youtube.com/watch?v=zqL_cMlPjOI) + + +### Beacon Chain + +The concept of a beacon chain differs from existing blockchains, such as +Bitcoin and Ethereum, in that it doesn't process transactions per se. Instead, +it maintains a set of bonded (staked) validators and coordinates these to +provide services to a static set of *sub-blockchains* (i.e. shards). Each of +these shard blockchains processes normal transactions (e.g. "Transfer 5 ETH +from A to B") in parallel whilst deferring consensus mechanisms to the beacon +chain. + +Major services provided by the beacon chain to its shards include the following: + +- A source of entropy, likely using a [RANDAO + VDF + scheme](https://ethresear.ch/t/minimal-vdf-randomness-beacon/3566). +- Validator management, including: + - Inducting and ejecting validators. + - Assigning randomly-shuffled subsets of validators to particular shards. + - Penalizing and rewarding validators. +- Proof-of-stake consensus for shard chain blocks. + +### Shard Chains + +Shards are analogous to CPU cores - they're a resource 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 processing +of multiple transactions simultaneously, greatly increasing the per-second +transaction capacity of Ethereum. + +Each shard uses a proof-of-stake consensus mechanism and shares its validators +(stakers) with other shards. The beacon chain rotates validators +pseudo-randomly between different shards. Shards will likely be the basis of +layer-2 transaction processing schemes, however, that is not in scope of this +discussion. + +### The Proof-of-Work Chain + +The present-Ethereum proof-of-work (PoW) chain will host a smart contract that +enables accounts 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), +allowing 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 desired. + +It is a requirement that ETH can move freely between shard chains, as well as between +Serenity and present-Ethereum blockchains. The exact mechanics of these transfers remain +an active topic of research and their details are yet to be confirmed. + +## Serenity Progress + +Ethereum Serenity is not fully specified and a working implementation does not +yet exist. Some teams have demos available which indicate progress, but do not +constitute a complete product. We look forward to providing user functionality +once we are ready to provide a minimum-viable user experience. + +The work-in-progress specifications live in the +[ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs) repository. +There is active discussion about the specification in the +[ethereum/sharding](https://gitter.im/ethereum/sharding) gitter channel. A +proof-of-concept implementation in Python is available at +[ethereum/beacon_chain](https://github.com/ethereum/beacon_chain). + +Presently, the specification focuses almost exclusively on the beacon chain, +as it is the focus of current development efforts. Progress on shard chain +specification will soon follow. From 94a0725032136ddc32768ba2c62207929b8ab1f1 Mon Sep 17 00:00:00 2001 From: Chris Natoli Date: Mon, 7 Jan 2019 16:57:09 +1100 Subject: [PATCH 5/8] Add 'lighthouse.md'; Update structure; Move info into relevant files. --- README.md | 158 +++--------------------------- docs/lighthouse.md | 83 ++++++++++++++++ docs/onboarding.md | 102 +++---------------- docs/{Serenity.md => serenity.md} | 0 4 files changed, 112 insertions(+), 231 deletions(-) create mode 100644 docs/lighthouse.md rename docs/{Serenity.md => serenity.md} (100%) diff --git a/README.md b/README.md index 8e85c9cf4..de0193705 100644 --- a/README.md +++ b/README.md @@ -31,33 +31,6 @@ to existing clients, such as [Parity-Ethereum](https://github.com/paritytech/parity-ethereum), via RPC to enable present-Ethereum functionality. -### Goals - -The purpose of this project is to work alongside the Ethereum community to -implement a secure, trustworthy, open-source Ethereum Serenity client in Rust. - -* **Security**: Lighthouse's main goal is to implement everything with a -security-first mindset. The goal is to ensure that all components of lighthouse -are thoroughly tested, checked and secure. - -* **Trust** : As Ethereum Serenity is a Proof-of-Stake system, which -involves the interaction of the Ethereum protocol and user funds. Thus, a goal -of Lighthouse is to provide a client that is trustworthy. - - All code can be tested and verified the goal of Lighthouse is to provide code -that is trusted. - -* **Transparency**: Lighthouse aims at being as transparent as possible. This goal is for -Lighthouse to embrace the open-source community and allow for all to understand -the decisions, direction and changes in all aspects. - -* **Error Resilience**: As Lighthouse embraces the "never `panic`" mindset, the -goal is to be resilient to errors that may occur. Providing a client that has -tolerance against errors provides further properties for a secure, trustworthy -client that Lighthouse aims to provide. - -In addition to implementing a new client, the project seeks to maintain and -improve the Ethereum protocol wherever possible. ### Components @@ -109,6 +82,16 @@ In addition to these components we are 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). +### 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. + ### Running **NOTE: The cryptography libraries used in this implementation are @@ -141,16 +124,10 @@ A few basic steps are needed to get set up: Lighthouse presently runs on Rust `stable`, however, benchmarks currently require the `nightly` version. - ### Contributing **Lighthouse welcomes contributors with open-arms.** -Layer-1 infrastructure is a critical component for the ecosystem and relies -heavily on contributions from the community. Building Ethereum Serenity is a huge -task and we refuse to conduct an inappropriate 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 Serenity and/or [Rust](https://www.rust-lang.org/), we are more than happy to on-board you and assign you some tasks. We aim to be as accepting and understanding as @@ -161,6 +138,9 @@ Alternatively, if you are an ETH/Rust veteran, we'd love your input. We're always looking for the best way to implement things and welcome all respectful criticisms. +If you are looking to contribute, please head to our +[onboarding documentation](https://github.com/sigp/lighthouse/blob/master/docs/onboarding.md). + 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 @@ -168,123 +148,11 @@ issue](https://github.com/sigp/lighthouse/issues?q=is%3Aissue+is%3Aopen+label%3A tag) and ping us on the [gitter](https://gitter.im/sigp/lighthouse) channel. We need your support! -### 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 crate's -root. Particularity large (line-count) tests should be placed into a separate -file. - -A function is not considered complete until a test exists for it. We produce -tests to protect against regression (accidentally breaking things) and to -provide examples that help readers of the code base understand how functions -should (or should not) be used. - -Each pull request is to be reviewed by at least one "core developer" (i.e., -someone with write-access to the repository). This helps to ensure bugs are -detected, consistency is maintained, and responsibility of errors is dispersed. - -Discussion must be respectful and intellectual. Have fun and make jokes, but -always respect the limits of other people. - -### 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. - ## Contact The best place for discussion is the [sigp/lighthouse gitter](https://gitter.im/sigp/lighthouse). Ping @paulhauner or @AgeManning to get the quickest response. - -# What is Ethereum Serenity - -Ethereum Serenity refers to a new blockchain system currently under development by -the Ethereum Foundation and the Ethereum community. The Serenity blockchain -consists of 1,025 proof-of-stake blockchains. This includes the "beacon chain" -and 1,024 "shard chains". - -Ethereum Serenity is also known as "Ethereum 2.0" and "Shasper". We prefer -Serenity as it more accurately reflects the established Ethereum roadmap (plus -we think it's a nice name). - -## Beacon Chain - -The concept of a beacon chain differs from existing blockchains, such as -Bitcoin and Ethereum, in that it doesn't process transactions per se. Instead, -it maintains a set of bonded (staked) validators and coordinates these to -provide services to a static set of *sub-blockchains* (i.e. shards). Each of -these shard blockchains processes normal transactions (e.g. "Transfer 5 ETH -from A to B") in parallel whilst deferring consensus mechanisms to the beacon -chain. - -Major services provided by the beacon chain to its shards include the following: - -- A source of entropy, likely using a [RANDAO + VDF - scheme](https://ethresear.ch/t/minimal-vdf-randomness-beacon/3566). -- Validator management, including: - - Inducting and ejecting validators. - - Assigning randomly-shuffled subsets of validators to particular shards. - - Penalizing and rewarding validators. -- Proof-of-stake consensus for shard chain blocks. - -## Shard Chains - -Shards are analogous to CPU cores - they're a resource 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 processing -of multiple transactions simultaneously, greatly increasing the per-second -transaction capacity of Ethereum. - -Each shard uses a proof-of-stake consensus mechanism and shares its validators -(stakers) with other shards. The beacon chain rotates validators -pseudo-randomly between different shards. Shards will likely be the basis of -layer-2 transaction processing schemes, however, that is not in scope of this -discussion. - -## The Proof-of-Work Chain - -The present-Ethereum proof-of-work (PoW) chain will host a smart contract that -enables accounts 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), -allowing 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 desired. - -It is a requirement that ETH can move freely between shard chains, as well as between -Serenity and present-Ethereum blockchains. The exact mechanics of these transfers remain -an active topic of research and their details are yet to be confirmed. - -## Ethereum Serenity Progress - -Ethereum Serenity is not fully specified and a working implementation does not yet -exist. Some teams have demos available which indicate progress, but do not -constitute a complete product. We look forward to providing user functionality -once we are ready to provide a minimum-viable user experience. - -The work-in-progress Serenity 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. The spec is still in a draft phase, however there are several teams -basing their Serenity implementations upon it while the Ethereum Foundation research -team continue to fill in the gaps. There is active discussion about the specification in the -[ethereum/sharding](https://gitter.im/ethereum/sharding) gitter channel. A -proof-of-concept implementation in Python is available at -[ethereum/beacon_chain](https://github.com/ethereum/beacon_chain). - -Presently, the specification focuses almost exclusively on the beacon chain, -as it is the focus of current development efforts. Progress on shard chain -specification will soon follow. - # Donations If you support the cause, we could certainly use donations to help fund development: diff --git a/docs/lighthouse.md b/docs/lighthouse.md new file mode 100644 index 000000000..8ca2387f8 --- /dev/null +++ b/docs/lighthouse.md @@ -0,0 +1,83 @@ +# About Lighthouse + +## Goals + +The purpose of this project is to work alongside the Ethereum community to +implement a secure, trustworthy, open-source Ethereum Serenity client in Rust. + +* **Security**: Lighthouse's main goal is to implement everything with a +security-first mindset. The goal is to ensure that all components of lighthouse +are thoroughly tested, checked and secure. + +* **Trust** : As Ethereum Serenity is a Proof-of-Stake system, which +involves the interaction of the Ethereum protocol and user funds. Thus, a goal +of Lighthouse is to provide a client that is trustworthy. + + All code can be tested and verified the goal of Lighthouse is to provide code +that is trusted. + +* **Transparency**: Lighthouse aims at being as transparent as possible. This +goal is for Lighthouse to embrace the open-source community and allow for all +to understand the decisions, direction and changes in all aspects. + +* **Error Resilience**: As Lighthouse embraces the "never `panic`" mindset, the +goal is to be resilient to errors that may occur. Providing a client that has +tolerance against errors provides further properties for a secure, trustworthy +client that Lighthouse aims to provide. + +In addition to implementing a new client, the project seeks to maintain and +improve the Ethereum protocol wherever possible. + +## Ideology + +### Never Panic + +Lighthouse will be the gateway interacting with the Proof-of-Stake system +employed by Ethereum. This requires the validation and proposal of blocks +and extremely timely responses. As part of this, Lighthouse aims to ensure +the most uptime as possible, meaning minimising the amount of +exceptions and gracefully handling any issues. + +Rust's `panic` provides the ability to throw an exception and exit, this +will terminate the running processes. Thus, Lighthouse aims to use `panic` +as little as possible to minimise the possible termination cases. + +### Security First Mindset + +Lighthouse aims to provide a safe, secure Serenity client for the Ethereum +ecosystem. At each step of development, the aim is to have a security-first +mindset and always ensure you are following the safe, secure mindset. When +contributing to any part of the Lighthouse client, through any development, +always ensure you understand each aspect thoroughly and cover all potential +security considerations of your code. + +### Functions aren't completed until they are tested + +As part of the Security First mindset, we want to aim to cover as many distinct +cases. A function being developed is not considered "completed" until tests +exist for that function. The tests not only help show the correctness of the +function, but also provide a way for new developers to understand how the +function is to be called and how it works. + + +## 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 crate's +root. Particularity large (line-count) tests should be placed into a separate +file. + +A function is not considered complete until a test exists for it. We produce +tests to protect against regression (accidentally breaking things) and to +provide examples that help readers of the code base understand how functions +should (or should not) be used. + +Each pull request is to be reviewed by at least one "core developer" (i.e., +someone with write-access to the repository). This helps to ensure bugs are +detected, consistency is maintained, and responsibility of errors is dispersed. + +Discussion must be respectful and intellectual. Have fun and make jokes, but +always respect the limits of other people. diff --git a/docs/onboarding.md b/docs/onboarding.md index 90b38df97..1d0557f29 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -1,5 +1,7 @@ # Contributing to Lighthouse +[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/sigp/lighthouse?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) + Lighthouse is an open-source Ethereum Serenity client built in [Rust](https://www.rust-lang.org/). @@ -13,40 +15,15 @@ documentation, writing extra tests or developing components, all help is appreciated and your contributions will help not only the community but all the contributors. +Layer-1 infrastructure is a critical component for the ecosystem and relies +heavily on contributions from the community. Building Ethereum Serenity is a +huge task and we refuse to conduct an inappropriate ICO or charge licensing +fees. Instead, we fund development through grants and support from Sigma +Prime. + If you have any additional questions, please feel free to jump on the [gitter](https://gitter.im/sigp/lighthouse) and have a chat with all of us. -## Ideology - -### Never Panic - -Lighthouse will be the gateway interacting with the Proof-of-Stake system -employed by Ethereum. This requires the validation and proposal of blocks -and extremely timely responses. As part of this, Lighthouse aims to ensure -the most uptime as possible, meaning minimising the amount of -exceptions and gracefully handling any issues. - -Rust's `panic` provides the ability to throw an exception and exit, this -will terminate the running processes. Thus, Lighthouse aims to use `panic` -as little as possible to minimise the possible termination cases. - -### Security First Mindset - -Lighthouse aims to provide a safe, secure Serenity client for the Ethereum -ecosystem. At each step of development, the aim is to have a security-first -mindset and always ensure you are following the safe, secure mindset. When -contributing to any part of the Lighthouse client, through any development, -always ensure you understand each aspect thoroughly and cover all potential -security considerations of your code. - -### Functions aren't completed until they are tested - -As part of the Security First mindset, we want to aim to cover as many distinct -cases. A function being developed is not considered "completed" until tests -exist for that function. The tests not only help show the correctness of the -function, but also provide a way for new developers to understand how the -function is to be called and how it works. - ## Understanding Serenity Ethereum's Serenity is based on a Proof-of-Stake based sharded beacon chain. @@ -54,59 +31,12 @@ Ethereum's Serenity is based on a Proof-of-Stake based sharded beacon chain. (*If you don't know what that is, don't `panic`, that's what this documentation is for!* :smile:) -### Ethereum +Read through our [Understanding +Serenity](https://github.com/sigp/lighthouse/blob/master/docs/serenity.md) docs +to learn more! :smile: -Ethereum is an open blockchain protocol, allowing for the building and use of -decentralized applications that run on blockchain technology. The blockchain can -be seen as a decentralized, distributed ledger of transactions. - -General Ethereum Introduction: - -* [What is Ethereum](http://ethdocs.org/en/latest/introduction/what-is-ethereum.html) -* [Ethereum Introduction](https://github.com/ethereum/wiki/wiki/Ethereum-introduction) - - -### Proof-of-Work and the current state of Ethereum. - -Currently, Ethereum is based on the Proof-of-Work model, a Sybil resilient -mechanism to allow nodes to propose blocks to the network. Although it provides -properties that allow the blockchain to operate in an open, public -(permissionless) network, it faces it's challenges and as a result impacts -the operation of the blockchain. - -The main goals to advance Ethereum is to (1) increase the scalability and -overall transaction processing power of the Ethereum world computer and (2) -find a suitable replacement for Proof-of-Work that still provides the necessary -properties that we need. - -* [Proof-of-Work in Cryptocurrencies: an accessible introduction](https://blog.sigmaprime.io/what-is-proof-of-work.html) - -### Serenity - -As part of the original Ethereum roadmap -[\[1\]](https://blog.ethereum.org/2015/03/03/ethereum-launch-process/) -[\[2\]](http://ethdocs.org/en/latest/introduction/the-homestead-release.html), -the Proof-of-Stake integration falls under **Release Step 4:*Serenity***. With -this, a number of changes are to be made to the current Ethereum protocol to -incorporate some of the new Proof-of-Stake mechanisms as well as improve on -some of the hindrances faced by the current Proof-of-Work chain. - -To now advance the current Ethereum, the decision is made to move to a sharded -Beacon chain structure where multiple shard-chains will be operating and -interacting with a central beacon chain. - -(Be mindful, the specifications change occasionally, so check these to keep up -to date) - -* Current Specifications: - * [Danny Ryan's "State of the Spec"](https://notes.ethereum.org/s/BJEZWNoyE) (A nice summary of the current specifications) - * [Ethereum Serenity - Phase 0: Beacon Chain Spec](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md) - * [Ethereum Serenity - Phase 1: Sharded Data Chains](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/1_shard-data-chains.md) - * [Beacon Chain - Vitalik Buterin and Justin Drake explain](https://www.youtube.com/watch?v=GAywmwGToUI) -* Understanding Sharding: - * [Prysmatic Labs: Sharding Explained](https://medium.com/prysmatic-labs/how-to-scale-ethereum-sharding-explained-ba2e283b7fce) -* Other relevant resources - * [Proof of Stake - Casper FFG](https://www.youtube.com/watch?v=uQ3IqLDf-oo) +The document explains the necessary fundamentals for understanding Ethereum, +Proof-of-Stake and the Serenity we are working towards. ## Development Onboarding @@ -142,8 +72,7 @@ allows you to easily install versions of rust. $ curl https://sh.rustup.rs -sSf | sh ``` -**Windows (You need a bit more):** - +**Windows (You need a bit more):**J * Install the Visual Studio 2015 with C++ support * Install Rustup using: https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe * You can then use the ``VS2015 x64 Native Tools Command Prompt`` and run: @@ -161,7 +90,6 @@ handy for handling dependencies and helping to modularise your project better. *Note: If you've installed rust through rustup, you should have ``cargo`` installed.* - #### Rust Terminology When developing rust, you'll come across some terminology that differs to @@ -217,6 +145,8 @@ and intellectual. Have fun, but always respect the limits of other people. **Testing** +*"A function is not considered complete until tests exist for it."* + Generally, tests can be self-contained in the same file. Integration tests should be added into the ``tests/`` directory in the crate's **root**. diff --git a/docs/Serenity.md b/docs/serenity.md similarity index 100% rename from docs/Serenity.md rename to docs/serenity.md From cfb9a1a3ae36b28ba0630c278a0c94866eb76fd6 Mon Sep 17 00:00:00 2001 From: Chris Natoli Date: Mon, 7 Jan 2019 17:06:07 +1100 Subject: [PATCH 6/8] Update onboarding docs to point to new docs --- docs/onboarding.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/onboarding.md b/docs/onboarding.md index 1d0557f29..8af3b0a83 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -15,6 +15,9 @@ documentation, writing extra tests or developing components, all help is appreciated and your contributions will help not only the community but all the contributors. +We've bundled up our Goals, Ethos and Ideology into one document for you to +read through, please read our [About Lighthouse](lighthouse.md) docs. :smile: + Layer-1 infrastructure is a critical component for the ecosystem and relies heavily on contributions from the community. Building Ethereum Serenity is a huge task and we refuse to conduct an inappropriate ICO or charge licensing @@ -24,6 +27,20 @@ Prime. If you have any additional questions, please feel free to jump on the [gitter](https://gitter.im/sigp/lighthouse) and have a chat with all of us. +**Pre-reading Materials:** + +* [About Lighthouse](lighthouse.md) +* [Ethereum Serenity](serenity.md) + +**Repository** + +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) channel. We need +your support! + ## Understanding Serenity Ethereum's Serenity is based on a Proof-of-Stake based sharded beacon chain. @@ -33,7 +50,7 @@ is for!* :smile:) Read through our [Understanding Serenity](https://github.com/sigp/lighthouse/blob/master/docs/serenity.md) docs -to learn more! :smile: +to learn more! :smile: (*unless you've already read it.*) The document explains the necessary fundamentals for understanding Ethereum, Proof-of-Stake and the Serenity we are working towards. @@ -72,7 +89,7 @@ allows you to easily install versions of rust. $ curl https://sh.rustup.rs -sSf | sh ``` -**Windows (You need a bit more):**J +**Windows (You need a bit more):** * Install the Visual Studio 2015 with C++ support * Install Rustup using: https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe * You can then use the ``VS2015 x64 Native Tools Command Prompt`` and run: From 973a3c1469513bd57a601285f0fe01e3427e2b2f Mon Sep 17 00:00:00 2001 From: Chris Natoli Date: Mon, 7 Jan 2019 17:13:34 +1100 Subject: [PATCH 7/8] Update readme with links to new docs; --- README.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index de0193705..bd52ef506 100644 --- a/README.md +++ b/README.md @@ -7,18 +7,6 @@ Chain, maintained by Sigma Prime. The "Serenity" project is also known as "Ethereum 2.0" or "Shasper". -## Introduction - -This readme is split into two major sections: - -- [Lighthouse Client](#lighthouse-client): information about this - implementation. -- [What is Ethereum Serenity](#what-is-ethereum-serenity): an introduction to Ethereum Serenity. - -If you'd like some background on Sigma Prime, please see the [Lighthouse Update -\#00](https://lighthouse.sigmaprime.io/update-00.html) blog post or the -[company website](https://sigmaprime.io). - ## Lighthouse Client Lighthouse is an open-source Ethereum Serenity client that is currently under @@ -31,6 +19,15 @@ to existing clients, such as [Parity-Ethereum](https://github.com/paritytech/parity-ethereum), via RPC to enable present-Ethereum functionality. +### Further Reading + +- [About Lighthouse](docs/lighthouse.md): Goals, Ideology and Ethos surrounding +this implementation. +- [What is Ethereum Serenity](docs/serenity.md): an introduction to Ethereum Serenity. + +If you'd like some background on Sigma Prime, please see the [Lighthouse Update +\#00](https://lighthouse.sigmaprime.io/update-00.html) blog post or the +[company website](https://sigmaprime.io). ### Components @@ -86,10 +83,10 @@ bloom-filters), and tons of other interesting stuff (at least we think so). Here we provide an overview of the directory structure: -- `/beacon_chain`: contains logic derived directly from the specification. +- `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., +- `lighthouse/'``: contains logic specific to this client implementation. E.g., CLI parsing, RPC end-points, databases, etc. ### Running From a4d202558f9c4f39c598b04cd5b232f85355e5f3 Mon Sep 17 00:00:00 2001 From: Chris Natoli Date: Mon, 7 Jan 2019 17:37:49 +1100 Subject: [PATCH 8/8] Fix bad syntax --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bd52ef506..01ebf6853 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ 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., +- `lighthouse/`: contains logic specific to this client implementation. E.g., CLI parsing, RPC end-points, databases, etc. ### Running