Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Readme updates #64

Merged
merged 7 commits into from
Jun 21, 2018
Merged

Readme updates #64

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
bb18757
Updated README, added CONTRIBUTING.md file
andogro Jun 18, 2018
5855c4f
updated links
andogro Jun 18, 2018
307c94c
Header reorganization and spacing considerations
andogro Jun 18, 2018
aef7cee
added rust and cargo installation instruction
andogro Jun 18, 2018
830d48b
Updated README
andogro Jun 20, 2018
ace6e6e
modified example simulation
andogro Jun 20, 2018
6cb8197
Resolved merge conflict
andogro Jun 20, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# POA Network

## To Contribute
1. Fork the repository
https://github.com/poanetwork/hbbft
2. Create a feature branch
3. Write tests to cover the work
4. Commit changes
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Before committing changes the contributor has to ensure the CI rules are satisfied, in particular, formatting is correct and all CI tests pass:

hbbft/.travis.yml

Line 21 in 1436d85

script:

Otherwise they may be waiting for acceptance of a PR that doesn't pass CI tests.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point! We should definitely link to the .travis.yml here, and explain that you have to use the same Rust, Clippy and Rustfmt versions as configured in the file.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks I will be sure to add.

5. Push to the branch
6. Create a new pull request following the PR protocol below

## Pull Request (PR) Protocol

All pull requests must include:
* A clear, readable description of the purpose of the PR
* A clear, readable description of changes
* A title that includes (Fix), (Feature), or (Refactor)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You already broke the rule in this very PR. 😛
I'm still skeptical about it, and my experience with mandatory PR/commit title formats was never great:

  • The only projects I found that follow this one are poa-test-setup and poa-dapps-validators, and even they have already extended the list of allowed keywords ("Update").
  • The RFC itself is still a draft. Also, it refers only to DApps; hbbft is not a DApp.
  • The only way to get a whole team to follow these rules is to check them in CI. But then it's even worse when you have something that doesn't quite fit one of the three categories. This PR here, for example, should really be in a "Docs" category if anything. Although I don't find "(Docs) Readme updates" much more readable than just "Readme updates".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the feedback. At this stage in the project I think it's appropriate to remove the Contributing section until it is more fleshed out. Once I explore options and get feedback I will create a centralized Contributing file.

**example:** (Fix) price of 1 token in Wei > 18 decimals
* A single commit message for one specific fix or feature. A separate PR should be made for each specific change.
* Any additional concerns or comments (optional)

All accepted and completed PRs are updated in the Wiki documentation.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we already have a Wiki entry for hbbft? I'd only add this sentence once we do.

(Also: Should we have one? If we start duplicating the documentation, it will start to go out of sync.)

90 changes: 78 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,88 @@
[![Build Status](https://travis-ci.com/poanetwork/hbbft.svg?branch=master)](https://travis-ci.com/poanetwork/hbbft)
[![Gitter](https://badges.gitter.im/poanetwork/hbbft.svg)](https://gitter.im/poanetwork/hbbft?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)

# About
# Honey Badger Byzantine Fault Tolerant (BFT) consensus algorithm

An implementation of the paper
["Honey Badger of BFT Protocols"](https://eprint.iacr.org/2016/199.pdf)
in Rust. This is a modular library of consensus. There are
[examples](./examples/README.md) illustrating the use of this algorithm.
Welcome to a [Rust ](https://www.rust-lang.org/en-US/)library of the Honey Badger Byzantine Fault Tolerant (BFT) consensus algorithm. The research and protocols for this algorithm are explained in detail in "[The Honey Badger of BFT Protocols](https://eprint.iacr.org/2016/199.pdf)" by Miller et al.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move the space outside [Rust ].


**This is work in progress.** Parts of the algorithm are still missing
or incomplete.
This documentation is designed for Rust developers looking to use a resilient consensus algorithm on a distributed network. Following is an overview of HoneyBadger BFT and basic instructions for getting started.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'd omit this sentence. It already says above that it's a Rust library, and use cases are listed below.


An example is included to run a simulation of a network:
**Note:** This library is a work in progress and parts of the algorithm are still in development.

$ cargo run --example simulation --features=serialization-serde -- -h
# What is Honey Badger?
The Honey Badger consensus algorithm allows nodes in a distributed, potentially asynchronous environment (decentralized databases and blockchains) to achieve agreement on transactions. The agreement process does not require a leader node, tolerates corrupted nodes, and makes progress in adverse network conditions.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could be misunderstood as "decentralized databases and blockchains" being the environment — if you're inside the blockchain, e.g. you're writing a DApp, you actually have a perfectly synchronous environment to work with —; the reader should understand that this can be used to build those kinds of systems on top of an asynchronous environment, e.g. nodes on the internet that can have connection problems.

We could just move it to the end of the paragraph: "Example use cases are decentralized databases and blockchains."


# Building
Honey Badger is **Byzantine Fault Tolerant**. The protocol can reach consensus with a number of failed nodes f (including complete takeover by an attacker), as long as the total number N of nodes is greater than 3 * f.

You can build `hbbft` using cargo:
Honey Badger is **asynchronous**. It does not make timing assumptions about message delivery. An adversary can control network scheduling and delay messages without impacting consensus.

$ cargo build [--release]
# How does it work?
Honey Badger is a modular library composed of several independent algorithms. To reach consensus, Honey Badger proceeds in epochs. In each epoch, participating nodes broadcast a set of encrypted data transactions to one another and agree on the contents of those transactions.

In an optimal networking environment, output includes data sent from each node. In an adverse environment, the output is an agreed upon subset of data. Either way, the resulting output contains a batch of transactions which is guaranteed to be consistent across all nodes.

## Algorithms

All algorithms in the protocol are modular and usable. Encryption to provide censorship resistance is currently in process for the top level Honey Badger algorithm.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe "and usable independently"?


- [ ] **[Honey Badger](https://github.com/poanetwork/hbbft/blob/master/src/honey_badger.rs):** The top level protocol proceeds in epochs using the protocols below.

- [x] **[Subset](https://github.com/poanetwork/hbbft/blob/master/src/common_subset.rs):** Each node inputs data. The nodes agree on a subset of suggested data.

- [x] **[Broadcast](https://github.com/poanetwork/hbbft/blob/master/src/broadcast.rs):** A proposer node inputs data and every node receives this output.

- [x] **[Binary Agreement](https://github.com/poanetwork/hbbft/blob/master/src/agreement/mod.rs):** Each node inputs a binary value. The nodes agree on a value that was input by at least one correct node.

- [x] **[Coin](https://github.com/poanetwork/hbbft/blob/master/src/common_coin.rs):** A pseudorandom binary value used by the Binary Agreement protocol.


## Current TODOs

- [ ] Honey Badger encryption

- [ ] Dynamic Honey Badger (adding and removing nodes in a live network environment)

- [ ] Networking example to detail Honey Badger implementation
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These could link to #41 (first one) and #47 (comment) (second one); once we've agreed on what the example should do, we'll also open an issue for the third one.


# Getting Started

This Rust library requires a distributed network environment to function. Details on network requirements will be published in the [Rust package registry](https://crates.io/) once core algorithms are complete.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that crates.io displays exactly the contents of the README.md. And there's no need to wait until we publish it there; I'd just put a "TBD" here for now. I'll try to come up with a very minimal usage example soon.


**Note: Additional examples are currently in progress.**


## Build

```
$ cargo build [--release]
```

## Example Network Simulation

An example is included to run a simulation of a network using serialization-serde ([https://serde.rs/](https://serde.rs/)) to efficiently serialize and deserialize Rust data structures.

```
$ cargo run --example simulation --features=serialization-serde -- -h
```

# Contributing

Please look at [current issues](https://github.com/poanetwork/hbbft/issues) and read [CONTRIBUTING.md](CONTRIBUTING.md) for contribution and pull request protocol.

# License

[![License: LGPL v3]([https://img.shields.io/badge/License-LGPL%20v3-blue.svg](https://img.shields.io/badge/License-LGPL%20v3-blue.svg))]([https://www.gnu.org/licenses/lgpl-3.0](https://www.gnu.org/licenses/lgpl-3.0))

This project is licensed under the GNU Lesser General Public License v3.0. See the [LICENSE](LICENSE) file for details.

# References

* [The Honey Badger of BFT Protocols](https://eprint.iacr.org/2016/199.pdf)

* [Honey Badger Video](https://www.youtube.com/watch?v=Qone4j1hCt8)

* Other language implementations

* [Go ](https://github.com/anthdm/hbbft)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Go ] -> [Go]


* [Erlang](https://github.com/helium/erlang-hbbft)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's also Andrew Miller's original implementation:

  * [Python](https://github.com/amiller/HoneyBadgerBFT)

Copy link
Contributor

@vkomenda vkomenda Jun 19, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An unfinished one:

* [Rust](https://github.com/rphmeier/honeybadger)