287 lines
11 KiB
Markdown
287 lines
11 KiB
Markdown
# Contributing to Lighthouse
|
|
|
|
Lighthouse is an open-source Ethereum Serenity client built in
|
|
[Rust](https://www.rust-lang.org/).
|
|
|
|
Lighthouse welcomes all contributions with open arms. If you are interested in
|
|
contributing to the Ethereum ecosystem, and you want to learn Rust, Lighthouse
|
|
is a great project to work on.
|
|
|
|
This documentation aims to provide a smooth on-boarding for all who wish to
|
|
help contribute to Lighthouse. Whether it is helping with the mountain of
|
|
documentation, writing extra tests or developing components, all help is
|
|
appreciated and your contributions will help not only the community but all
|
|
the contributors.
|
|
|
|
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.
|
|
|
|
(*If you don't know what that is, don't `panic`, that's what this documentation
|
|
is for!* :smile:)
|
|
|
|
### Ethereum
|
|
|
|
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)
|
|
|
|
## Development Onboarding
|
|
|
|
If you would like to contribute and develop Lighthouse, there are only a few
|
|
things to go through (and then you're on your way!).
|
|
|
|
### Understanding Rust
|
|
|
|
Rust is an extremely powerful, low-level programming language that provides
|
|
freedom and performance to create powerful projects. The [Rust
|
|
Book](https://doc.rust-lang.org/stable/book/) provides insight into the Rust
|
|
language and some of the coding style to follow (As well as acting as a great
|
|
introduction and tutorial for the language.)
|
|
|
|
Rust has a steep learning curve, but there are many resources to help you!
|
|
|
|
* [Rust Book](https://doc.rust-lang.org/stable/book/)
|
|
* [Rust by example](https://doc.rust-lang.org/stable/rust-by-example/)
|
|
* [Learning Rust With Entirely Too Many Linked Lists](http://cglab.ca/~abeinges/blah/too-many-lists/book/)
|
|
* [Rustlings](https://github.com/rustlings/rustlings)
|
|
* [Rust Exercism](https://exercism.io/tracks/rust)
|
|
* [Learn X in Y minutes - Rust](https://learnxinyminutes.com/docs/rust/)
|
|
|
|
|
|
#### Getting Started and installing Rust
|
|
|
|
We recommend installing Rust using [**rustup**](https://rustup.rs/). Rustup
|
|
allows you to easily install versions of rust.
|
|
|
|
**Linux/Unix/Mac:**
|
|
|
|
```
|
|
$ curl https://sh.rustup.rs -sSf | sh
|
|
```
|
|
|
|
**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:
|
|
|
|
```
|
|
rustup default stable-x86-64-pc-windows-msvc
|
|
```
|
|
|
|
#### Getting ready with Cargo
|
|
|
|
[Cargo](https://doc.rust-lang.org/cargo/) is the package manager for Rust, and
|
|
allows to extend to a number of packages and external libraries. It's also extremely
|
|
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
|
|
other programming languages you may have used.
|
|
|
|
* **Trait**: A trait is a collection of methods defined for a type, they can be
|
|
implemented for any data type.
|
|
* **Struct**: A custom data type that lets us name and package together
|
|
multiple related values that make a meaninguful group.
|
|
* **Crate**: A crate is synonymous with a *library* or *package* in other
|
|
languages. They can produce an executable or library depending on the
|
|
project.
|
|
* **Module**: A collection of items: functions, structs, traits, and even other
|
|
modules. Modules allow you to hierarchically split code into logical units
|
|
and manage visibility.
|
|
* **Attribute**: Metadaata applied to some module, crate or item.
|
|
* **Macros**: Macros are powerful meta-programming statements that get expanded
|
|
into source code that gets compiled with the rest of the code (Unlike `C`
|
|
macros that are pre-processed, Rust macros form an Abstract Syntax Tree).
|
|
|
|
|
|
Other good appendix resources:
|
|
|
|
* [Keywords](https://doc.rust-lang.org/book/appendix-01-keywords.html)
|
|
* [Operators/Symbols](https://doc.rust-lang.org/book/appendix-02-operators.html)
|
|
* [Traits](https://doc.rust-lang.org/book/appendix-03-derivable-traits.html)
|
|
|
|
|
|
### Understanding the Git Workflow
|
|
|
|
Lighthouse utilises git as the primary open-source development tool. To help
|
|
with your contributions, it is great to understand the processes used to ensure
|
|
everything remains in sync and there's as little conflict as possible when
|
|
working on similar files.
|
|
|
|
Lighthouse uses the **feature branch** workflow, where each issue, or each
|
|
feature, is developed on its own branch and then merged in via a pull-request.
|
|
|
|
* [Feature Branch Tutorial](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow)
|
|
|
|
## Code Conventions/Styleguide and Ethos
|
|
|
|
### Ethos
|
|
|
|
**Pull Requests**
|
|
|
|
Pull requests should be reviewed by **at least** one "*core developer*"
|
|
(someone with write-access to the repo). This should ensure bugs are caught and
|
|
the code is kept in a consistent state that follows all conventions and style.
|
|
|
|
All discussion (whether in PRs or Issues or in the Gitter) should be respectful
|
|
and intellectual. Have fun, but always respect the limits of other people.
|
|
|
|
**Testing**
|
|
|
|
Generally, tests can be self-contained in the same file. Integration tests
|
|
should be added into the ``tests/`` directory in the crate's **root**.
|
|
|
|
Large line-count tests should be in a separate file.
|
|
|
|
### Rust StyleGuide
|
|
|
|
Lighthouse adheres to Rust code conventions as outlined in the [**Rust
|
|
Styleguide**](https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/guide.md).
|
|
|
|
Ensure you use [Clippy](https://github.com/rust-lang/rust-clippy) to lint and
|
|
check your code.
|
|
|
|
| Code Aspect | Guideline Format |
|
|
|:--------------------|:-------------------------------|
|
|
| Types | ``UpperCamelCase`` |
|
|
| Enums/Enum Variants | ``UpperCamelCase`` |
|
|
| Struct Fields | ``snake_case`` |
|
|
| Function / Method | ``snake_case`` |
|
|
| Macro Names | ``snake_case`` |
|
|
| Constants | ``SCREAMING_SNAKE_CASE`` |
|
|
| Forbidden name | Trialing Underscore: ``name_`` |
|
|
|
|
Other general rust docs:
|
|
|
|
* [Rust Other Style Advice](https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/advice.md)
|
|
* [Cargo.toml Conventions](https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/cargo.md)
|
|
|
|
### TODOs
|
|
|
|
All `TODO` statements should be accompanied by a GitHub issue.
|
|
|
|
```rust
|
|
pub fn my_function(&mut self, _something &[u8]) -> Result<String, Error> {
|
|
// TODO: something_here
|
|
// https://github.com/sigp/lighthouse/issues/XX
|
|
}
|
|
```
|
|
|
|
### Comments
|
|
|
|
**General Comments**
|
|
|
|
* Prefer line (``//``) comments to block comments (``/* ... */``)
|
|
* Comments can appear on the line prior to the item or after a trailing space.
|
|
```rust
|
|
// Comment for this struct
|
|
struct Lighthouse {}
|
|
|
|
fn make_blockchain() {} // A comment on the same line after a space
|
|
```
|
|
|
|
**Doc Comments**
|
|
|
|
* The ``///`` is used to generate comments for Docs.
|
|
* The comments should come before attributes.
|
|
|
|
```rust
|
|
/// Stores the core configuration for this Lighthouse instance.
|
|
/// This struct is general, other components may implement more
|
|
/// specialized config structs.
|
|
#[derive(Clone)]
|
|
pub struct LighthouseConfig {
|
|
pub data_dir: PathBuf,
|
|
pub p2p_listen_port: u16,
|
|
}
|
|
```
|