poanetwork
/
hbbft
mirror of https://github.com/poanetwork/hbbft.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updated README, added CONTRIBUTING.md file

This commit is contained in:
Andrew Gross 2018-06-18 12:02:00 -06:00
parent 2e7fd91a1b
commit bb18757d17
2 changed files with 95 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
CONTRIBUTING.md Normal file
View File

@ -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
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)
**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.

85
README.md
View File

@ -1,22 +1,83 @@
[![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
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.
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.
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.
**This is work in progress.** Parts of the algorithm are still missing
or incomplete.
**Note:** This library is a work in progress and parts of the algorithm are still in development.
An example is included to run a simulation of a network:
# 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.
$ cargo run --example simulation --features=serialization-serde -- -h
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.
# Building
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.
You can build `hbbft` using cargo:
# 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.
$ cargo build [--release]
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
- [ ] **Honey Badger:** The top level protocol proceeds in epochs using the protocols below. Encrpytion to provide censorship resistance is in process.
- [x] **Subset:** Each node inputs data. The nodes agree on a subset of suggested data.
- [x] **Broadcast:** A proposer node inputs data and every node receives this output.
- [x] **Binary Agreement:** Each node inputs a binary value. The nodes agree on a value that was input by at least one correct node.
- [x] **Coin:** 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
# 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.
**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 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)
* [Erlang](https://github.com/helium/erlang-hbbft)