From bb18757d17fb2b6d2775d00497393dc308c85dfb Mon Sep 17 00:00:00 2001 From: Andrew Gross Date: Mon, 18 Jun 2018 12:02:00 -0600 Subject: [PATCH 1/6] Updated README, added CONTRIBUTING.md file --- CONTRIBUTING.md | 22 +++++++++++++ README.md | 85 ++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 95 insertions(+), 12 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..ec07befd --- /dev/null +++ b/CONTRIBUTING.md @@ -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. \ No newline at end of file diff --git a/README.md b/README.md index ec6b0d34..8167f7ea 100644 --- a/README.md +++ b/README.md @@ -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) From 5855c4ffe741401e42451166fffc7557cb332037 Mon Sep 17 00:00:00 2001 From: Andrew Gross Date: Mon, 18 Jun 2018 12:53:50 -0600 Subject: [PATCH 2/6] updated links --- README.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 8167f7ea..5b9ba577 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ [![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) +# Honey Badger Byzantine Fault Tolerant (BFT) consensus 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. 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. @@ -21,15 +23,18 @@ In an optimal networking environment, output includes data sent from each node. ## Algorithms -- [ ] **Honey Badger:** The top level protocol proceeds in epochs using the protocols below. Encrpytion to provide censorship resistance is in process. +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. + +- [ ] **[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] **Subset:** 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] **Broadcast:** 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] **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](https://github.com/poanetwork/hbbft/blob/master/src/common_coin.rs):** A pseudorandom binary value used by the Binary Agreement protocol. -- [x] **Coin:** A pseudorandom binary value used by the Binary Agreement protocol. ## Current TODOs @@ -62,7 +67,7 @@ $ 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. +Please look at [current issues](https://github.com/poanetwork/hbbft/issues) and read [CONTRIBUTING.md](CONTRIBUTING.md) for contribution and pull request protocol. # License From 307c94ca9521eb3cb0c9b140576d5c3574d7ff0e Mon Sep 17 00:00:00 2001 From: Andrew Gross Date: Mon, 18 Jun 2018 13:34:21 -0600 Subject: [PATCH 3/6] Header reorganization and spacing considerations --- README.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 5b9ba577..d9b7391c 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,27 @@ +# Honey Badger Byzantine Fault Tolerant (BFT) consensus algorithm + [![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) -# Honey Badger Byzantine Fault Tolerant (BFT) consensus 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. +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. 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. **Note:** This library is a work in progress and parts of the algorithm are still in development. -# What is Honey Badger? +## 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. 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. 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. -# How does it work? +## 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 +### 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. @@ -36,7 +36,7 @@ All algorithms in the protocol are modular and usable. Encryption to provide cen - [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 +### Current TODOs - [ ] Honey Badger encryption @@ -44,20 +44,20 @@ All algorithms in the protocol are modular and usable. Encryption to provide cen - [ ] Networking example to detail Honey Badger implementation -# Getting Started +## 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 +### Build ``` $ cargo build [--release] ``` -## Example Network Simulation +### 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. @@ -65,17 +65,17 @@ An example is included to run a simulation of a network using serialization-serd $ cargo run --example simulation --features=serialization-serde -- -h ``` -# Contributing +## 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 [![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 +## References * [The Honey Badger of BFT Protocols](https://eprint.iacr.org/2016/199.pdf) @@ -83,6 +83,6 @@ This project is licensed under the GNU Lesser General Public License v3.0. See t * Other language implementations - * [Go ](https://github.com/anthdm/hbbft) + * [Go](https://github.com/anthdm/hbbft) * [Erlang](https://github.com/helium/erlang-hbbft) From aef7ceed0a87ee57679e56573d96fd80eac6775b Mon Sep 17 00:00:00 2001 From: Andrew Gross Date: Mon, 18 Jun 2018 13:37:53 -0600 Subject: [PATCH 4/6] added rust and cargo installation instruction --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index d9b7391c..b3aaeb59 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,8 @@ This Rust library requires a distributed network environment to function. Detail ### Build +Requires `rust` and `cargo`: [installation instructions.](https://www.rust-lang.org/en-US/install.html) + ``` $ cargo build [--release] ``` From 830d48b95c48277d0e716b55d45ab718a2464a35 Mon Sep 17 00:00:00 2001 From: Andrew Gross Date: Wed, 20 Jun 2018 11:36:01 -0600 Subject: [PATCH 5/6] Updated README --- CONTRIBUTING.md | 22 ------------------- README.md | 58 +++++++++++++++++++++++++++++++++---------------- 2 files changed, 39 insertions(+), 41 deletions(-) delete mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index ec07befd..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,22 +0,0 @@ -# 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. \ No newline at end of file diff --git a/README.md b/README.md index b3aaeb59..8e66b655 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,21 @@ [![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) -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. +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., 2016. -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. +Our implementation modifies the protocols described in the paper in several ways: +* We use a [pairing elliptic curve library](https://github.com/ebfull/pairing) to implement pairing-based cryptography rather than Gap Diffie-Hellman groups. +* We add a `Terminate` message to the Binary Agreement algorithm. Termination occurs following output, preventing the algorithm from running (or staying in memory) indefinitely. ([#53](https://github.com/poanetwork/hbbft/issues/55)) +* We add a `Conf` message to the Binary Agreement algorithm. An additional message phase prevents an attack if an adversary controls a network scheduler and a node. ([#37](https://github.com/poanetwork/hbbft/issues/37)) +* We return additional information from the Subset and Honey Badger algorithms that specifies which node input which data. This allows for identification of potentially malicious nodes. +* We run a Distributed Key Generation (DKG) protocol which does not require a trusted dealer; nodes collectively generate a secret key. This addresses the problem of single point of failure. See [Distributed Key Generation in the Wild](https://eprint.iacr.org/2012/377.pdf). -**Note:** This library is a work in progress and parts of the algorithm are still in development. +Following is an overview of HoneyBadger BFT and [basic instructions for getting started](#getting-started). + +_**Note:** This library is a work in progress and parts of the algorithm are still in development._ ## 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. +The Honey Badger consensus algorithm allows nodes in a distributed, potentially asynchronous environment to achieve agreement on transactions. The agreement process does not require a leader node, tolerates corrupted nodes, and makes progress in adverse network conditions. Example use cases are decentralized databases and blockchains. 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. @@ -21,9 +28,23 @@ Honey Badger is a modular library composed of several independent algorithms. T 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 +## Algorithms + +All algorithms in the protocol are modular. Encryption to provide censorship resistance is currently in process for the top level Honey Badger algorithm. + +### Algorithm naming conventions + +We have simplified algorithm naming conventions from the original paper. + +| Algorithm Name | Original Name | +| ---------------- | -------------------------------- | +| Honey Badger | HoneyBadgerBFT | +| Subset | Asynchronous Common Subset (ACS) | +| Broadcast | Reliable Broadcast (RBC) | +| Binary Agreement | Binary Byzantine Agreement (BBA) | +| Coin | Common Coin | -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. +### Algorithm short descriptions - [ ] **[Honey Badger](https://github.com/poanetwork/hbbft/blob/master/src/honey_badger.rs):** The top level protocol proceeds in epochs using the protocols below. @@ -36,20 +57,19 @@ All algorithms in the protocol are modular and usable. Encryption to provide cen - [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 +### Current TODOs -- [ ] Honey Badger encryption +- [ ] Honey Badger encryption ([#41](https://github.com/poanetwork/hbbft/issues/41)) -- [ ] Dynamic Honey Badger (adding and removing nodes in a live network environment) +- [ ] Dynamic Honey Badger (adding and removing nodes in a live network environment) ([#47](https://github.com/poanetwork/hbbft/issues/47#issuecomment-394640406)) - [ ] 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.** +This Rust library requires a distributed network environment to function. Details on network requirements TBD. +_**Note:** Additional examples are currently in progress._ ### Build @@ -61,19 +81,15 @@ $ 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. +A basic example is included to run a network simulation. ``` -$ cargo run --example simulation --features=serialization-serde -- -h +$ cargo run --example simulation -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)) +[![License: LGPL v3.0](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](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. @@ -85,6 +101,10 @@ This project is licensed under the GNU Lesser General Public License v3.0. See t * Other language implementations + * [Python](https://github.com/amiller/HoneyBadgerBFT) + * [Go](https://github.com/anthdm/hbbft) * [Erlang](https://github.com/helium/erlang-hbbft) + + * [Rust](https://github.com/rphmeier/honeybadger) - unfinished implementation From ace6e6e420b0a7a0e75ddcd435b97c229120234f Mon Sep 17 00:00:00 2001 From: Andrew Gross Date: Wed, 20 Jun 2018 11:53:09 -0600 Subject: [PATCH 6/6] modified example simulation --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8e66b655..12d75c38 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ $ cargo build [--release] A basic example is included to run a network simulation. ``` -$ cargo run --example simulation -h +$ cargo run --example simulation -- -h ``` ## License