mirror of
https://github.com/sigp/lighthouse.git
synced 2026-05-09 03:17:55 +00:00
Add 'lighthouse.md'; Update structure; Move info into relevant files.
This commit is contained in:
Chris Natoli
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
|
||||
|
||||
[](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**.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user