mirror of
https://github.com/OffchainLabs/prysm.git
synced 2026-01-09 15:37:56 -05:00
remark beautify markdown
Former-commit-id: b92827f722ffbce34a5f8a141875a49e53d2e2a1 [formerly fba2c4a8a32646a1657e8f483eef4183fe41077d] Former-commit-id: f69fefc72d43bd51ffc766ad3fe5f399311d1b4e
This commit is contained in:
Raul Jordan
126
README.md
126
README.md
@@ -1,5 +1,5 @@
|
||||
Prysmatic Labs Sharding Implementation
|
||||
==========================
|
||||
# Prysmatic Labs Sharding Implementation
|
||||
|
||||
This is the main repository for the sharding implementation of the go-ethereum client by [Prysmatic Labs](https://prysmaticlabs.com). For the original, go-ethereum project, refer to the following [link](https://github.com/ethereum/go-ethereum).
|
||||
|
||||
Before you begin, check out our [Sharding Reference Implementation Doc](https://github.com/prysmaticlabs/geth-sharding/blob/master/sharding/README.md). This doc serves as the single source of truth for our team, our milestones, and details on the different components of our architecture.
|
||||
@@ -8,32 +8,30 @@ Interested in contributing? Check out our [Contribution Guidelines](#contributio
|
||||
|
||||
[](https://gitter.im/prysmaticlabs/geth-sharding?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
||||
|
||||
Table of Contents
|
||||
=================
|
||||
# Table of Contents
|
||||
|
||||
- [Installation](#installation)
|
||||
- [Sharding Instructions](#sharding)
|
||||
- [Running a Local Geth Node](#running-a-local-geth-node)
|
||||
- [Transaction Generator](#transaction-generator)
|
||||
- [Becoming a Validator](#becoming-a-validator)
|
||||
- [Becoming a Proposer](#becoming-a-proposer)
|
||||
- [Testing](#testing)
|
||||
- [Contribution Guidelines](#contribution-guidelines)
|
||||
- [License](#license)
|
||||
- [Installation](#installation)
|
||||
- [Sharding Instructions](#sharding)
|
||||
- [Running a Local Geth Node](#running-a-local-geth-node)
|
||||
- [Transaction Generator](#transaction-generator)
|
||||
- [Becoming a Validator](#becoming-a-validator)
|
||||
- [Becoming a Proposer](#becoming-a-proposer)
|
||||
- [Testing](#testing)
|
||||
- [Contribution Guidelines](#contribution-guidelines)
|
||||
- [License](#license)
|
||||
|
||||
Installation
|
||||
============
|
||||
# Installation
|
||||
|
||||
Create a folder in your `$GOPATH` and navigate to it
|
||||
|
||||
```
|
||||
mkdir -p $GOPATH/src/github.com/ethereum && cd $GOPATH/src/github.com/ethereum
|
||||
$ mkdir -p $GOPATH/src/github.com/ethereum && cd $GOPATH/src/github.com/ethereum
|
||||
```
|
||||
|
||||
Clone our repository as `go-ethereum`
|
||||
|
||||
```
|
||||
git clone https://github.com/prysmaticlabs/geth-sharding ./go-ethereum
|
||||
$ git clone https://github.com/prysmaticlabs/geth-sharding ./go-ethereum
|
||||
```
|
||||
|
||||
For prerequisites and detailed build instructions please read the
|
||||
@@ -45,22 +43,20 @@ You can install them using your favourite package manager.
|
||||
Once the dependencies are installed, run
|
||||
|
||||
```
|
||||
make geth
|
||||
$ make geth
|
||||
```
|
||||
|
||||
or, to build the full suite of utilities:
|
||||
|
||||
```
|
||||
make all
|
||||
$ make all
|
||||
```
|
||||
|
||||
Sharding Instructions
|
||||
==============
|
||||
# Sharding Instructions
|
||||
|
||||
To get started with running the project, follow the instructions to initialize your own private Ethereum blockchain and geth node, as they will be required to run before you can become a validator or a proposer.
|
||||
|
||||
Running a Local Geth Node
|
||||
------------------------------
|
||||
## Running a Local Geth Node
|
||||
|
||||
To start a local Geth node, you can create your own `genesis.json` file similar to:
|
||||
|
||||
@@ -79,51 +75,41 @@ To start a local Geth node, you can create your own `genesis.json` file similar
|
||||
|
||||
Then, you can build `geth` and init a new instance of a local, Ethereum blockchain as follows:
|
||||
|
||||
```
|
||||
$ make geth
|
||||
$ ./build/bin/geth init ./sharding/genesis.json -datadir /path/to/your/datadir
|
||||
$ ./build/bin/geth --nodiscover console --datadir /path/to/your/datadir --networkid 12345
|
||||
```
|
||||
$ make geth
|
||||
$ ./build/bin/geth init ./sharding/genesis.json -datadir /path/to/your/datadir
|
||||
$ ./build/bin/geth --nodiscover console --datadir /path/to/your/datadir --networkid 12345
|
||||
|
||||
Then, the geth console can start up and you can start a miner as follows:
|
||||
|
||||
```
|
||||
> personal.newAccount()
|
||||
> miner.setEtherbase(eth.accounts[0])
|
||||
> miner.start()
|
||||
```
|
||||
> personal.newAccount()
|
||||
> miner.setEtherbase(eth.accounts[0])
|
||||
> miner.start()
|
||||
|
||||
Then, once you are satisfied with mining for a few seconds, stop the miner with
|
||||
|
||||
```
|
||||
> miner.stop()
|
||||
```
|
||||
> miner.stop()
|
||||
|
||||
Now, save the passphrase you used in the geth node into a text file called password.txt. Then, once you have this private geth node running on your local network, we will need to generate fake, pending transactions that can then be processed into shards by validators and proposers. For this, we have created an in-house transaction generator CLI tool.
|
||||
|
||||
Transaction Generator
|
||||
---------------------
|
||||
## Transaction Generator
|
||||
|
||||
Work in Progress. To track our current draft of the tx generator cli spec, visit this [link](https://docs.google.com/document/d/1YohsW4R9dIRo0u5RqfNOYjCkYKVCmzjgoBDBYDdu5m0/edit?usp=drive_web&ouid=105756662967435769870).
|
||||
|
||||
Once we have fake transactions broadcast to our local node, we can start a validator and proposer client in separate terminal windows to begin the sharding process.
|
||||
|
||||
Becoming a Validator
|
||||
-----------------------
|
||||
## Becoming a Validator
|
||||
|
||||
To deposit ETH and join as a validator in the Validator Manager Contract, run the following command:
|
||||
|
||||
```
|
||||
geth sharding-validator --deposit 100eth --password /path/to/your/password.txt
|
||||
```
|
||||
geth sharding-validator --deposit 100eth --password /path/to/your/password.txt
|
||||
|
||||
This will extract 100ETH from your account balance and insert you into the VMC's validator set. Then, the program will listen for incoming block headers and notify you when you have been selected as an eligible proposer for a certain shard in a given period. Once you are selected, the validator will request collations from a "collation proposals pool" that is created by a proposer node. We will need to run a proposal node concurrently in a separate terminal window as follows:
|
||||
|
||||
Becoming a Proposer
|
||||
-----------------------
|
||||
## Becoming a Proposer
|
||||
|
||||
The proposer node can be started with the following command:
|
||||
|
||||
```
|
||||
geth sharding-proposer --password /path/to/your/password.txt
|
||||
```
|
||||
geth sharding-proposer --password /path/to/your/password.txt
|
||||
|
||||
Proposers are tasked with state execution, so they will process and validate pending transactions in the Geth node and create collations with headers that are then broadcast to a proposals pool along with an ETH deposit.
|
||||
|
||||
@@ -131,31 +117,23 @@ Validators then subscribe to changes in the proposals pool and fetch the collati
|
||||
|
||||
Once this is done, the full, end-to-end sharding example is complete and another iteration can occur.
|
||||
|
||||
# Making Changes
|
||||
|
||||
Making Changes
|
||||
==============
|
||||
## Rebuilding the Validator Manager Contract Bindings
|
||||
|
||||
Rebuilding the Validator Manager Contract Bindings
|
||||
---------------------------------------------------------
|
||||
The Validator Manager Contract is built in Solidity and deployed to the geth node upon launch of the client if it does not exist in the network at a specified address. If there are any changes to the VMC's code, the Golang bindigs must be rebuilt with the following command.
|
||||
|
||||
```
|
||||
go generate abigen --sol contracts/validator_manager.sol --pkg contracts --out contracts/validator_manager.go
|
||||
```
|
||||
go generate abigen --sol contracts/validator_manager.sol --pkg contracts --out contracts/validator_manager.go
|
||||
|
||||
Testing
|
||||
=======
|
||||
# Testing
|
||||
|
||||
To run the unit tests of our system do:
|
||||
|
||||
```
|
||||
go test ./sharding
|
||||
```
|
||||
go test ./sharding
|
||||
|
||||
We will require more complex testing scenarios (fuzz tests) to measure the full integrity of the system as it evolves.
|
||||
|
||||
Contribution Guidelines
|
||||
===============
|
||||
# Contribution Guidelines
|
||||
|
||||
Excited by our work and want to get involved in building out our sharding releases? Our [Sharding Reference Implementation Doc](https://github.com/prysmaticlabs/geth-sharding/blob/master/sharding/README.md) has all you need to know in order to begin helping us make this happen. We created this document as a single source of reference for all things related to sharding Ethereum, and we need as much help as we can get!
|
||||
|
||||
@@ -163,22 +141,22 @@ You can explore our [Current Projects](https://github.com/prysmaticlabs/geth-sha
|
||||
|
||||
**Contribution Steps**
|
||||
|
||||
- Create a folder in your `$GOPATH` and navigate to it `mkdir -p $GOPATH/src/github.com/ethereum && cd $GOPATH/src/github.com/ethereum`
|
||||
- Clone our repository as `go-ethereum`, `git clone https://github.com/prysmaticlabs/geth-sharding ./go-ethereum`
|
||||
- Fork the `go-ethereum` repository on Github: https://github.com/ethereum/go-ethereum
|
||||
- Add a remote to your fork
|
||||
`git remote add YOURNAME https://github.com/YOURNAME/go-ethereum
|
||||
- Create a folder in your `$GOPATH` and navigate to it `mkdir -p $GOPATH/src/github.com/ethereum && cd $GOPATH/src/github.com/ethereum`
|
||||
- Clone our repository as `go-ethereum`, `git clone https://github.com/prysmaticlabs/geth-sharding ./go-ethereum`
|
||||
- Fork the `go-ethereum` repository on Github: <https://github.com/ethereum/go-ethereum>
|
||||
- Add a remote to your fork
|
||||
\`git remote add YOURNAME <https://github.com/YOURNAME/go-ethereum>
|
||||
|
||||
Now you should have a remote pointing to the `origin` repo (geth-sharding) and to your forked, go-ethereum repo on Github. To commit changes and start a Pull Request, our workflow is as follows:
|
||||
|
||||
- Create a new branch with a clear feature name such as `git checkout -b collations-pool`
|
||||
- Issue changes with clear commit messages
|
||||
- Push to your remote `git push YOURNAME collations-pool`
|
||||
- Go to the [geth-sharding](https://github.com/prysmaticlabs/geth-sharding) repository on Github and start a PR comparing `geth-sharding:master` with `go-ethereum:collations-pool` (your fork on your profile).
|
||||
- Add a clear PR title along with a description of what this PR encompasses, when it can be closed, and what you are currently working on. Github markdown checklists work great for this.
|
||||
- Create a new branch with a clear feature name such as `git checkout -b collations-pool`
|
||||
- Issue changes with clear commit messages
|
||||
- Push to your remote `git push YOURNAME collations-pool`
|
||||
- Go to the [geth-sharding](https://github.com/prysmaticlabs/geth-sharding) repository on Github and start a PR comparing `geth-sharding:master` with `go-ethereum:collations-pool` (your fork on your profile).
|
||||
- Add a clear PR title along with a description of what this PR encompasses, when it can be closed, and what you are currently working on. Github markdown checklists work great for this.
|
||||
|
||||
# License
|
||||
|
||||
License
|
||||
=====
|
||||
The go-ethereum library (i.e. all code outside of the `cmd` directory) is licensed under the
|
||||
[GNU Lesser General Public License v3.0](https://www.gnu.org/licenses/lgpl-3.0.en.html), also
|
||||
included in our repository in the `COPYING.LESSER` file.
|
||||
|
||||
Reference in New Issue
Block a user