cerc-io/lighthouse
16
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

First pass of docs update

Browse Source
This commit is contained in:
Paul Hauner 2019-02-13 16:04:10 +11:00
parent 1d5ff4359a
commit c1ec46ef85
No known key found for this signature in database
GPG Key ID: D362883A9218FCC6
7 changed files with 120 additions and 209 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
CONTRIBUTING.md
View File

@ -1,121 +0,0 @@
# Contributors Guide
Lighthouse is an open-source Ethereum 2.0 client. We we're community driven and
welcome all contribution. We aim to provide a constructive, respectful and fun
environment for collaboration.
We are active contributors to the [Ethereum 2.0 specification](https://github.com/ethereum/eth2.0-specs) and attend all [Eth
2.0 implementers calls](https://github.com/ethereum/eth2.0-pm).
This guide is geared towards beginners. If you're an open-source veteran feel
free to just skim this document and get straight into crushing issues.
## Why Contribute
There are many reasons you might contribute to Lighthouse. For example, you may
wish to:
- contribute to the Ethereum ecosystem.
- establish yourself as a layer-1 Ethereum developer.
- work in the amazing Rust programming language.
- learn how to participate in open-source projects.
- expand your software development skills.
- flex your skills in a public forum to expand your career
opportunities (or simply for the fun of it).
- grow your network by working with core Ethereum developers.
## How to Contribute
Regardless of the reason, the process to begin contributing is very much the
same. We operate like a typical open-source project operating on GitHub: the
repository [Issues](https://github.com/sigp/lighthouse/issues) is where we
track what needs to be done and [Pull
Requests](https://github.com/sigp/lighthouse/pulls) is where code gets
reviewed. We use [gitter](https://gitter.im/sigp/lighthouse) to chat
informally.
### General Work-Flow
We recommend the following work-flow for contributors:
1. **Find an issue** to work on, either because it's interesting or suitable to
your skill-set. Use comments to communicate your intentions and ask
questions.
2. **Work in a feature branch** of your personal fork
(github.com/YOUR_NAME/lighthouse) of the main repository
(github.com/sigp/lighthouse).
3. Once you feel you have addressed the issue, **create a pull-request** to merge
your changes in to the main repository.
4. Wait for the repository maintainers to **review your changes** to ensure the
issue is addressed satisfactorily. Optionally, mention your PR on
[gitter](https://gitter.im/sigp/lighthouse).
5. If the issue is addressed the repository maintainers will **merge your
pull-request** and you'll be an official contributor!
Generally, you find an issue you'd like to work on and announce your intentions
to start work in a comment on the issue. Then, do your work on a separate
branch (a "feature branch") in your own fork of the main repository. Once
you're happy and you think the issue has been addressed, create a pull request
into the main repository.
### First-time Set-up
First time contributors can get their git environment up and running with these
steps:
1. [Create a
fork](https://help.github.com/articles/fork-a-repo/#fork-an-example-repository)
and [clone
it](https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork)
to your local machine.
2. [Add an _"upstream"_
branch](https://help.github.com/articles/fork-a-repo/#step-3-configure-git-to-sync-your-fork-with-the-original-spoon-knife-repository)
that tracks github.com/sigp/lighthouse using `$ git remote add upstream
https://github.com/sigp/lighthouse.git` (pro-tip: [use SSH](https://help.github.com/articles/connecting-to-github-with-ssh/) instead of HTTPS).
3. Create a new feature branch with `$ git checkout -b your_feature_name`. The
name of your branch isn't critical but it should be short and instructive.
E.g., if you're fixing a bug with serialization, you could name your branch
`fix_serialization_bug`.
4. Commit your changes and push them to your fork with `$ git push origin
your_feature_name`.
5. Go to your fork on github.com and use the web interface to create a pull
request into the sigp/lighthouse repo.
From there, the repository maintainers will review the PR and either accept it
or provide some constructive feedback.
There's great
[guide](https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/)
by Rob Allen that provides much more detail on each of these steps, if you're
having trouble. As always, jump on [gitter](https://gitter.im/sigp/lighthouse)
if you get stuck.
## FAQs
### I don't think I have anything to add
There's lots to be done and there's all sorts of tasks. You can do anything
from correcting typos through to writing core consensus code. If you reach out,
we'll include you.
### I'm not sure my Rust is good enough
We're open to developers of all levels. If you create a PR and your code
doesn't meet our standards, we'll help you fix it and we'll share the reasoning
with you. Contributing to open-source is a great way to learn.
### I'm not sure I know enough about Ethereum 2.0
No problems, there's plenty of tasks that don't require extensive Ethereum
knowledge. You can learn about Ethereum as you go.
### I'm afraid of making a mistake and looking silly
Don't be. We're all about personal development and constructive feedback. If you
make a mistake and learn from it, everyone wins.
### I don't like the way you do things
Please, make an issue and explain why. We're open to constructive criticism and
will happily change our ways.

145
README.md
View File

@ -7,7 +7,51 @@ Chain, maintained by Sigma Prime.
The "Serenity" project is also known as "Ethereum 2.0" or "Shasper".
## Lighthouse Client
## Project Structure
The Lighthouse project is managed across four Github repositories:
- [sigp/lighthouse](https://github.com/sigp/lighthouse) (this repo): The
"integration" repository which provides:
- Project-wide documentation
- A sub-module for each of the following repos.
- A landing-page for users and contributors.
- A triage point for issues.
- In the future, various other integration tests and orchestration suites.
- [sigp/lighthouse-libs](https://github.com/sigp/lighthouse-libs): Contains
Rust crates common to the entire Lighthouse project, including:
- Pure specification logic (e.g., state transitions, etc)
- SSZ (SimpleSerialize)
- BLS Signature libraries
- [sigp/lighthouse-beacon](https://github.com/sigp/lighthouse-beacon): The
beacon node binary, responsible for connection to peers across the
network and maintaining a view of the Beacon Chain.
- [sigp/lighthouse-validator](https://github.com/sigp/lighthouse-validator):
The validator client binary, which connects to a beacon node and fulfils
the duties of a staked validator (producing and attesting to blocks).
## Contributing
We welcome new contributors and greatly appreciate the efforts from existing
contributors.
If you'd like to contribute to development on Lighthouse, we'd recommend
checking for [issues on the lighthouse-libs
repo](https://github.com/sigp/lighthouse-libs/issues) first, then checking the
other repositories.
If you don't find anything there, please reach out on the
[gitter](https://gitter.im/sigp/lighthouse) channel.
Additional resources:
- [ONBOARDING.md](docs/ONBOARDING.md): General on-boarding info,
including style-guide.
- [LIGHTHOUSE.md](docs/LIGHTHOUSE.md): Project goals and ethos.
- [RUNNING.md](docs/RUNNING.md): Step-by-step on getting the code running.
- [SERENITY.md](docs/SERENITY.md): Introduction to Ethereum Serenity.
## Project Summary
Lighthouse is an open-source Ethereum Serenity client that is currently under
development. Designed as a Serenity-only client, Lighthouse will not
@ -19,15 +63,6 @@ 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
@ -61,7 +96,7 @@ by the team:
from the Ethereum Foundation to develop *simpleserialize* (SSZ), a
purpose-built serialization format for sending information across a network.
Check out the [SSZ
implementation](https://github.com/sigp/lighthouse/tree/master/beacon_chain/utils/ssz)
implementation](https://github.com/sigp/lighthouse-libs/tree/master/ssz)
and this
[research](https://github.com/sigp/serialization_sandbox/blob/report/report/serialization_report.md)
on serialization formats for more information.
@ -79,89 +114,23 @@ 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
experimental. As such all cryptography is assumed to be insecure.**
This code-base is still very much under-development and does not provide any
user-facing functionality. For developers and researchers, there are several
tests and benchmarks which may be of interest.
A few basic steps are needed to get set up:
1. Install [rustup](https://rustup.rs/). It's a toolchain manager for Rust (Linux | macos | Windows). For installation run the below command in your terminal `$ curl https://sh.rustup.rs -sSf | sh`
2. (Linux & MacOS) To configure your current shell run: `$ source $HOME/.cargo/env`
3. Use the command `rustup show` to get information about the Rust installation. You should see that the
active toolchain is the stable version.
4. Run `rustc --version` to check the installation and version of rust.
- Updates can be performed using` rustup update` .
5. Install build dependencies (Arch packages are listed here, your distribution will likely be similar):
- `clang`: required by RocksDB.
- `protobuf`: required for protobuf serialization (gRPC).
6. Navigate to the working directory.
7. Run the test by using command `cargo test --all`. By running, it will pass all the required test cases.
If you are doing it for the first time, then you can grab a coffee in the meantime. Usually, it takes time
to build, compile and pass all test cases. If there is no error then it means everything is working properly
and it's time to get your hands dirty.
In case, if there is an error, then please raise the [issue](https://github.com/sigp/lighthouse/issues).
We will help you.
8. As an alternative to, or instead of the above step, you may also run benchmarks by using
the command `cargo bench --all`
##### Note:
Lighthouse presently runs on Rust `stable`, however, benchmarks currently require the
`nightly` version.
##### Note for Windows users:
Perl may also be required to build lighthouse. You can install [Strawberry Perl](http://strawberryperl.com/),
or alternatively use a choco install command `choco install strawberryperl`.
Additionally, the dependency `protoc-grpcio v0.3.1` is reported to have issues compiling in Windows. You can specify
a known working version by editing version in protos/Cargo.toml's "build-dependencies" section to
`protoc-grpcio = "<=0.3.0"`.
### Contributing
**Lighthouse welcomes contributors with open-arms.**
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 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
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!
## 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.
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).
# Donations
If you support the cause, we could certainly use donations to help fund development:
We accept donations at the following Ethereum address. All donations go towards
funding development of Ethereum 2.0.
`0x25c4a76E7d118705e7Ea2e9b7d8C59930d8aCD3b`
[`0x25c4a76E7d118705e7Ea2e9b7d8C59930d8aCD3b`](https://etherscan.io/address/0x25c4a76e7d118705e7ea2e9b7d8c59930d8acd3b)
Alternatively, you can contribute via [Gitcoin Grant](https://gitcoin.co/grants/25/lighthouse-ethereum-20-client).
We appreciate all contributions to the project.

0
docs/lighthouse.md → docs/LIGHTHOUSE.md
View File

0
docs/onboarding.md → docs/ONBOARDING.md
View File

10
docs/README.md Normal file
View File

@ -0,0 +1,10 @@
# Lighthouse Documentation
Table of Contents:
- [ONBOARDING.md](ONBOARDING.md): General on-boarding info,
including style-guide.
- [LIGHTHOUSE.md](LIGHTHOUSE.md): Project goals and ethos.
- [RUNNING.md](RUNNING.md): Step-by-step on getting the code running.
- [SERENITY.md](SERENITY.md): Introduction to Ethereum Serenity.

53
docs/RUNNING.md Normal file
View File

@ -0,0 +1,53 @@
# Running Lighthouse Code
These documents provide a guide for running code in the following repositories:
- [lighthouse-libs](https://github.com/sigp/lighthouse-libs)
- [lighthouse-beacon](https://github.com/sigp/lighthouse-beacon
- [lighthouse-validator](https://github.com/sigp/lighthouse-validator
**NOTE: The cryptography libraries used in this implementation are
experimental. As such all cryptography is assumed to be insecure.**
This code-base is still very much under-development and does not provide any
user-facing functionality. For developers and researchers, there are several
tests and benchmarks which may be of interest.
A few basic steps are needed to get set up:
1. Install [rustup](https://rustup.rs/). It's a toolchain manager for Rust
(Linux | macos | Windows). For installation run the below command in your
terminal `$ curl https://sh.rustup.rs -sSf | sh`
2. (Linux & MacOS) To configure your current shell run: `$ source
$HOME/.cargo/env`
3. Use the command `rustup show` to get information about the Rust
installation. You should see that the active toolchain is the stable
version.
4. Run `rustc --version` to check the installation and version of rust.
- Updates can be performed using` rustup update` .
5. Install build dependencies (Arch packages are listed here, your
distribution will likely be similar):
- `clang`: required by RocksDB. `protobuf`: required for protobuf
- serialization (gRPC).
6. Navigate to the working directory.
7. Run the test by using command `cargo test --all`. By running, it will
pass all the required test cases. If you are doing it for the first time,
then you can grab a coffee in the meantime. Usually, it takes time to build,
compile and pass all test cases. If there is no error then it means
everything is working properly and it's time to get your hands dirty. In
case, if there is an error, then please raise the
[issue](https://github.com/sigp/lighthouse/issues). We will help you.
8. As an alternative to, or instead of the above step, you may also run
benchmarks by using the command `cargo bench --all`. (Note: not all
repositories have benchmarking).
##### Note: Lighthouse presently runs on Rust `stable`.
##### Note for Windows users: Perl may also be required to build lighthouse.
You can install [Strawberry Perl](http://strawberryperl.com/), or alternatively
use a choco install command `choco install strawberryperl`.
Additionally, the dependency `protoc-grpcio v0.3.1` is reported to have issues
compiling in Windows. You can specify a known working version by editing
version in protos/Cargo.toml's "build-dependencies" section to `protoc-grpcio =
"<=0.3.0"`.

0
docs/serenity.md → docs/SERENITY.md
View File