Merge pull request #134 from sigp/readme-restructure
Readme Restructure
This commit is contained in:
commit
67a153bf4f
193
README.md
193
README.md
@ -7,18 +7,6 @@ Chain, maintained by Sigma Prime.
|
|||||||
|
|
||||||
The "Serenity" project is also known as "Ethereum 2.0" or "Shasper".
|
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 Client
|
||||||
|
|
||||||
Lighthouse is an open-source Ethereum Serenity client that is currently under
|
Lighthouse is an open-source Ethereum Serenity client that is currently under
|
||||||
@ -31,14 +19,15 @@ to existing clients, such as
|
|||||||
[Parity-Ethereum](https://github.com/paritytech/parity-ethereum), via RPC to enable
|
[Parity-Ethereum](https://github.com/paritytech/parity-ethereum), via RPC to enable
|
||||||
present-Ethereum functionality.
|
present-Ethereum functionality.
|
||||||
|
|
||||||
### Goals
|
### Further Reading
|
||||||
|
|
||||||
The purpose of this project is to further research and development towards a
|
- [About Lighthouse](docs/lighthouse.md): Goals, Ideology and Ethos surrounding
|
||||||
secure, efficient, and decentralized Ethereum protocol, facilitated by a new
|
this implementation.
|
||||||
open-source Ethereum Serenity client.
|
- [What is Ethereum Serenity](docs/serenity.md): an introduction to Ethereum Serenity.
|
||||||
|
|
||||||
In addition to implementing a new client, the project seeks to maintain and
|
If you'd like some background on Sigma Prime, please see the [Lighthouse Update
|
||||||
improve the Ethereum protocol wherever possible.
|
\#00](https://lighthouse.sigmaprime.io/update-00.html) blog post or the
|
||||||
|
[company website](https://sigmaprime.io).
|
||||||
|
|
||||||
### Components
|
### Components
|
||||||
|
|
||||||
@ -57,12 +46,11 @@ by the team:
|
|||||||
is more resource intensive than proof-of-work. As such, clients need to
|
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
|
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
|
present, blocks having 10 million ETH staked can be processed in 0.006
|
||||||
seconds, and invalid blocks are rejected even more quickly. See [issue
|
seconds, and invalid blocks are rejected even more quickly. See
|
||||||
#103](https://github.com/ethereum/beacon_chain/issues/103) on
|
[issue #103](https://github.com/ethereum/beacon_chain/issues/103) on
|
||||||
[ethereum/beacon_chain](https://github.com/ethereum/beacon_chain).
|
[ethereum/beacon_chain](https://github.com/ethereum/beacon_chain).
|
||||||
.
|
|
||||||
- **P2P networking**: Serenity will likely use the [libp2p
|
- **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
|
[Parity](https://www.parity.io/) to ensure
|
||||||
[libp2p-rust](https://github.com/libp2p/rust-libp2p) is fit-for-purpose.
|
[libp2p-rust](https://github.com/libp2p/rust-libp2p) is fit-for-purpose.
|
||||||
- **Validator duties** : The project involves development of "validator
|
- **Validator duties** : The project involves development of "validator
|
||||||
@ -77,9 +65,10 @@ implementation](https://github.com/sigp/lighthouse/tree/master/beacon_chain/util
|
|||||||
and this
|
and this
|
||||||
[research](https://github.com/sigp/serialization_sandbox/blob/report/report/serialization_report.md)
|
[research](https://github.com/sigp/serialization_sandbox/blob/report/report/serialization_report.md)
|
||||||
on serialization formats for more information.
|
on serialization formats for more information.
|
||||||
- **Casper FFG fork-choice**: The [Casper
|
- **Fork-choice**: The current fork choice rule is
|
||||||
FFG](https://arxiv.org/abs/1710.09437) fork-choice rules allow the chain to
|
[*LMD Ghost*](https://vitalik.ca/general/2018/12/05/cbc_casper.html#lmd-ghost),
|
||||||
select a canonical chain in the case of a fork.
|
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
|
- **Efficient state transition logic**: State transition logic governs
|
||||||
updates to the validator set as validators log in/out, penalizes/rewards
|
updates to the validator set as validators log in/out, penalizes/rewards
|
||||||
validators, rotates validators across shards, and implements other core tasks.
|
validators, rotates validators across shards, and implements other core tasks.
|
||||||
@ -90,31 +79,15 @@ In addition to these components we are also working on database schemas, RPC
|
|||||||
frameworks, specification development, database optimizations (e.g.,
|
frameworks, specification development, database optimizations (e.g.,
|
||||||
bloom-filters), and tons of other interesting stuff (at least we think so).
|
bloom-filters), and tons of other interesting stuff (at least we think so).
|
||||||
|
|
||||||
### Contributing
|
### Directory Structure
|
||||||
|
|
||||||
**Lighthouse welcomes contributors with open-arms.**
|
Here we provide an overview of the directory structure:
|
||||||
|
|
||||||
Layer-1 infrastructure is a critical component for the ecosystem and relies
|
- `beacon_chain/`: contains logic derived directly from the specification.
|
||||||
heavily on contributions from the community. Building Ethereum Serenity is a huge
|
E.g., shuffling algorithms, state transition logic and structs, block
|
||||||
task and we refuse to conduct an inappropriate ICO or charge licensing fees.
|
validation, BLS crypto, etc.
|
||||||
Instead, we fund development through grants and support from Sigma Prime.
|
- `lighthouse/`: contains logic specific to this client implementation. E.g.,
|
||||||
|
CLI parsing, RPC end-points, databases, etc.
|
||||||
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
|
### Running
|
||||||
|
|
||||||
@ -148,123 +121,35 @@ A few basic steps are needed to get set up:
|
|||||||
Lighthouse presently runs on Rust `stable`, however, benchmarks currently require the
|
Lighthouse presently runs on Rust `stable`, however, benchmarks currently require the
|
||||||
`nightly` version.
|
`nightly` version.
|
||||||
|
|
||||||
### Engineering Ethos
|
### Contributing
|
||||||
|
|
||||||
Lighthouse aims to produce many small easily-tested components, each separated
|
**Lighthouse welcomes contributors with open-arms.**
|
||||||
into individual crates wherever possible.
|
|
||||||
|
|
||||||
Generally, tests can be kept in the same file, as is typical in Rust.
|
If you would like to learn more about Ethereum Serenity and/or
|
||||||
Integration tests should be placed in the `tests` directory in the crate's
|
[Rust](https://www.rust-lang.org/), we are more than happy to on-board you
|
||||||
root. Particularity large (line-count) tests should be placed into a separate
|
and assign you some tasks. We aim to be as accepting and understanding as
|
||||||
file.
|
possible; we are more than happy to up-skill contributors in exchange for their
|
||||||
|
assistance with the project.
|
||||||
|
|
||||||
A function is not considered complete until a test exists for it. We produce
|
Alternatively, if you are an ETH/Rust veteran, we'd love your input. We're
|
||||||
tests to protect against regression (accidentally breaking things) and to
|
always looking for the best way to implement things and welcome all
|
||||||
provide examples that help readers of the code base understand how functions
|
respectful criticisms.
|
||||||
should (or should not) be used.
|
|
||||||
|
|
||||||
Each pull request is to be reviewed by at least one "core developer" (i.e.,
|
If you are looking to contribute, please head to our
|
||||||
someone with write-access to the repository). This helps to ensure bugs are
|
[onboarding documentation](https://github.com/sigp/lighthouse/blob/master/docs/onboarding.md).
|
||||||
detected, consistency is maintained, and responsibility of errors is dispersed.
|
|
||||||
|
|
||||||
Discussion must be respectful and intellectual. Have fun and make jokes, but
|
If you'd like to contribute, try having a look through the [open
|
||||||
always respect the limits of other people.
|
issues](https://github.com/sigp/lighthouse/issues) (tip: look for the [good
|
||||||
|
first
|
||||||
### Directory Structure
|
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
|
||||||
Here we provide an overview of the directory structure:
|
your support!
|
||||||
|
|
||||||
- `/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
|
## Contact
|
||||||
|
|
||||||
The best place for discussion is the [sigp/lighthouse gitter](https://gitter.im/sigp/lighthouse).
|
The best place for discussion is the [sigp/lighthouse gitter](https://gitter.im/sigp/lighthouse).
|
||||||
Ping @paulhauner or @AgeManning to get the quickest response.
|
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
|
# Donations
|
||||||
|
|
||||||
If you support the cause, we could certainly use donations to help fund development:
|
If you support the cause, we could certainly use donations to help fund development:
|
||||||
|
83
docs/lighthouse.md
Normal file
83
docs/lighthouse.md
Normal file
@ -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.
|
@ -1,5 +1,7 @@
|
|||||||
# Contributing to Lighthouse
|
# 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
|
Lighthouse is an open-source Ethereum Serenity client built in
|
||||||
[Rust](https://www.rust-lang.org/).
|
[Rust](https://www.rust-lang.org/).
|
||||||
|
|
||||||
@ -13,39 +15,31 @@ documentation, writing extra tests or developing components, all help is
|
|||||||
appreciated and your contributions will help not only the community but all
|
appreciated and your contributions will help not only the community but all
|
||||||
the contributors.
|
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
|
||||||
|
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
|
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.
|
[gitter](https://gitter.im/sigp/lighthouse) and have a chat with all of us.
|
||||||
|
|
||||||
## Ideology
|
**Pre-reading Materials:**
|
||||||
|
|
||||||
### Never Panic
|
* [About Lighthouse](lighthouse.md)
|
||||||
|
* [Ethereum Serenity](serenity.md)
|
||||||
|
|
||||||
Lighthouse will be the gateway interacting with the Proof-of-Stake system
|
**Repository**
|
||||||
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
|
If you'd like to contribute, try having a look through the [open
|
||||||
will terminate the running processes. Thus, Lighthouse aims to use `panic`
|
issues](https://github.com/sigp/lighthouse/issues) (tip: look for the [good
|
||||||
as little as possible to minimise the possible termination cases.
|
first
|
||||||
|
issue](https://github.com/sigp/lighthouse/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
|
||||||
### Security First Mindset
|
tag) and ping us on the [gitter](https://gitter.im/sigp/lighthouse) channel. We need
|
||||||
|
your support!
|
||||||
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
|
## Understanding Serenity
|
||||||
|
|
||||||
@ -54,59 +48,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
|
(*If you don't know what that is, don't `panic`, that's what this documentation
|
||||||
is for!* :smile:)
|
is for!* :smile:)
|
||||||
|
|
||||||
### Ethereum
|
Read through our [Understanding
|
||||||
|
Serenity](https://github.com/sigp/lighthouse/blob/master/docs/serenity.md) docs
|
||||||
|
to learn more! :smile: (*unless you've already read it.*)
|
||||||
|
|
||||||
Ethereum is an open blockchain protocol, allowing for the building and use of
|
The document explains the necessary fundamentals for understanding Ethereum,
|
||||||
decentralized applications that run on blockchain technology. The blockchain can
|
Proof-of-Stake and the Serenity we are working towards.
|
||||||
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)
|
|
||||||
|
|
||||||
## Development Onboarding
|
## Development Onboarding
|
||||||
|
|
||||||
@ -143,7 +90,6 @@ $ curl https://sh.rustup.rs -sSf | sh
|
|||||||
```
|
```
|
||||||
|
|
||||||
**Windows (You need a bit more):**
|
**Windows (You need a bit more):**
|
||||||
|
|
||||||
* Install the Visual Studio 2015 with C++ support
|
* 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
|
* 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:
|
* You can then use the ``VS2015 x64 Native Tools Command Prompt`` and run:
|
||||||
@ -161,7 +107,6 @@ handy for handling dependencies and helping to modularise your project better.
|
|||||||
*Note: If you've installed rust through rustup, you should have ``cargo``
|
*Note: If you've installed rust through rustup, you should have ``cargo``
|
||||||
installed.*
|
installed.*
|
||||||
|
|
||||||
|
|
||||||
#### Rust Terminology
|
#### Rust Terminology
|
||||||
|
|
||||||
When developing rust, you'll come across some terminology that differs to
|
When developing rust, you'll come across some terminology that differs to
|
||||||
@ -217,6 +162,8 @@ and intellectual. Have fun, but always respect the limits of other people.
|
|||||||
|
|
||||||
**Testing**
|
**Testing**
|
||||||
|
|
||||||
|
*"A function is not considered complete until tests exist for it."*
|
||||||
|
|
||||||
Generally, tests can be self-contained in the same file. Integration tests
|
Generally, tests can be self-contained in the same file. Integration tests
|
||||||
should be added into the ``tests/`` directory in the crate's **root**.
|
should be added into the ``tests/`` directory in the crate's **root**.
|
||||||
|
|
||||||
|
161
docs/serenity.md
Normal file
161
docs/serenity.md
Normal file
@ -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)
|
||||||
|
<center>Figure 1. Example blockchain with a resolved fork.</center>
|
||||||
|
|
||||||
|
<br>
|
||||||
|
|
||||||
|
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.
|
Loading…
Reference in New Issue
Block a user