diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index e5b34f083f..0000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -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. diff --git a/README.md b/README.md index 7759c11665..b6ed6e22fe 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/lighthouse.md b/docs/LIGHTHOUSE.md similarity index 100% rename from docs/lighthouse.md rename to docs/LIGHTHOUSE.md diff --git a/docs/onboarding.md b/docs/ONBOARDING.md similarity index 100% rename from docs/onboarding.md rename to docs/ONBOARDING.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..484f6a5185 --- /dev/null +++ b/docs/README.md @@ -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. diff --git a/docs/RUNNING.md b/docs/RUNNING.md new file mode 100644 index 0000000000..1b00bc11a4 --- /dev/null +++ b/docs/RUNNING.md @@ -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"`. diff --git a/docs/serenity.md b/docs/SERENITY.md similarity index 100% rename from docs/serenity.md rename to docs/SERENITY.md