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

Fix unused error in test and fix markdown format error

This commit is contained in:
Weiliang Li 2019-07-23 17:28:26 +09:00 committed by Andreas Fackler
parent 51e4809260
commit 7078387115
5 changed files with 68 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
README.md
View File

@ -9,19 +9,20 @@ Welcome to a [Rust](https://www.rust-lang.org/en-US/) library of the Honey Badge
An [official security audit](https://github.com/poanetwork/wiki/blob/master/assets/pdf/hbbft-audit-report.pdf) has been completed on `hbbft` by [Jean-Philippe Aumasson](https://aumasson.jp/).
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 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.
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?
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.
@ -30,38 +31,37 @@ In addition to **validators**, the algorithms support **observers**: These don't
Please see the following posts for more details:
- [POA Network: Building Honey Badger BFT](https://medium.com/poa-network/poa-network-building-honey-badger-bft-c953afa4d926)
- [POA Network: Building Honey Badger BFT](https://medium.com/poa-network/poa-network-building-honey-badger-bft-c953afa4d926)
- [POA Network: How Honey Badger BFT Consensus Works](https://medium.com/poa-network/poa-network-how-honey-badger-bft-consensus-works-4b16c0f1ff94)
- [POA Network: How Honey Badger BFT Consensus Works](https://medium.com/poa-network/poa-network-how-honey-badger-bft-consensus-works-4b16c0f1ff94)
- [POA Network: Honey Badger BFT and Threshold Cryptography](https://medium.com/poa-network/poa-network-honey-badger-bft-and-threshold-cryptography-c43e10fadd87)
- [POA Network: Honey Badger BFT and Threshold Cryptography](https://medium.com/poa-network/poa-network-honey-badger-bft-and-threshold-cryptography-c43e10fadd87)
## Algorithms
- **[Honey Badger](src/honey_badger/honey_badger.rs):** Each node inputs transactions. The protocol outputs a sequence of batches of transactions.
- **[Honey Badger](src/honey_badger/honey_badger.rs):** Each node inputs transactions. The protocol outputs a sequence of batches of transactions.
- **[Dynamic Honey Badger](src/dynamic_honey_badger/dynamic_honey_badger.rs):** A modified Honey Badger where nodes can dynamically add and remove other nodes to/from the network.
- **[Dynamic Honey Badger](src/dynamic_honey_badger/dynamic_honey_badger.rs):** A modified Honey Badger where nodes can dynamically add and remove other nodes to/from the network.
- **[Queueing Honey Badger](src/queueing_honey_badger/mod.rs):** Works exactly like Dynamic Honey Badger, but includes a built in transaction queue.
- **[Queueing Honey Badger](src/queueing_honey_badger/mod.rs):** Works exactly like Dynamic Honey Badger, but includes a built in transaction queue.
- **[Subset](src/subset/subset.rs):** Each node inputs data. The nodes agree on a subset of suggested data.
- **[Subset](src/subset/subset.rs):** Each node inputs data. The nodes agree on a subset of suggested data.
- **[Broadcast](src/broadcast/broadcast.rs):** A proposer node inputs data and every node receives this output.
- **[Broadcast](src/broadcast/broadcast.rs):** A proposer node inputs data and every node receives this output.
- **[Binary Agreement](src/binary_agreement/binary_agreement.rs):** Each node inputs a binary value. The nodes agree on a value that was input by at least one correct node.
- **[Binary Agreement](src/binary_agreement/binary_agreement.rs):** Each node inputs a binary value. The nodes agree on a value that was input by at least one correct node.
- **[Threshold Sign](src/threshold_sign.rs):**
Each node inputs the same data to be signed, and outputs the unique valid signature matching the public master key. It is used as a pseudorandom value in the Binary Agreement protocol.
- **[Threshold Sign](src/threshold_sign.rs):**
Each node inputs the same data to be signed, and outputs the unique valid signature matching the public master key. It is used as a pseudorandom value in the Binary Agreement protocol.
- **[Threshold Decryption](src/threshold_decrypt.rs):**
Each node inputs the same ciphertext, encrypted to the public master key, and outputs the decrypted data.
- **[Threshold Decryption](src/threshold_decrypt.rs):**
Each node inputs the same ciphertext, encrypted to the public master key, and outputs the decrypted data.
- **[Synchronous Key Generation](src/sync_key_gen.rs)** A dealerless algorithm that generates keys for threshold encryption and signing. Unlike the other algorithms, this one is _completely synchronous_ and should run on top of Honey Badger (or another consensus algorithm)
- **[Synchronous Key Generation](src/sync_key_gen.rs)** A dealerless algorithm that generates keys for threshold encryption and signing. Unlike the other algorithms, this one is _completely synchronous_ and should run on top of Honey Badger (or another consensus algorithm)
### External crates developed for this library
- **[Threshold Crypto](https://github.com/poanetwork/threshold_crypto):** A threshold cryptosystem for collaborative message decryption and signature creation.
- **[Threshold Crypto](https://github.com/poanetwork/threshold_crypto):** A threshold cryptosystem for collaborative message decryption and signature creation.
## Getting Started
@ -73,56 +73,47 @@ _**Note:** Additional examples are currently in progress._
Requires Rust 1.36 or higher and `cargo`: [installation instructions.](https://www.rust-lang.org/en-US/install.html) The library is tested against the `stable` release channel.
```
$ cargo build [--release]
```
$ cargo build [--release]
### Testing
```
$ cargo test --release
```
$ cargo test --release
See the [tests README](tests/README.md) for more information on our testing toolkit.
### Example Network Simulation
A basic [example](examples/README.md) is included to run a network simulation.
```
$ cargo run --example simulation --release
```
$ cargo run --example simulation --release
![Screenshot](assets/screenshot.png)
| Heading | Definition
| ----------- | -------------------------------------------------------------------------- |
| Epoch | Epoch number. In each epoch, transactions are processed in a batch by simulated nodes (default is 10 nodes) on a network. The batch is always output in one piece, with all transactions at once. |
| Min Time | Time in simulated milliseconds until the first correct (i.e. not faulty) node outputs the batch. |
| Max Time | Time in simulated milliseconds until the last correct node outputs the batch. |
| Txs | Number of transactions processed in the epoch. |
| Msgs/Node | Average number of messages handled by a node. The counter is cumulative and includes the number of messages handled in the current epoch and all previous epochs. |
| Size/Node | Average message size (in converted bytes) handled by a node. This is cumulative and includes message size for the current epoch and all previous epochs. |
| Heading | Definition |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Epoch | Epoch number. In each epoch, transactions are processed in a batch by simulated nodes (default is 10 nodes) on a network. The batch is always output in one piece, with all transactions at once. |
| Min Time | Time in simulated milliseconds until the first correct (i.e. not faulty) node outputs the batch. |
| Max Time | Time in simulated milliseconds until the last correct node outputs the batch. |
| Txs | Number of transactions processed in the epoch. |
| Msgs/Node | Average number of messages handled by a node. The counter is cumulative and includes the number of messages handled in the current epoch and all previous epochs. |
| Size/Node | Average message size (in converted bytes) handled by a node. This is cumulative and includes message size for the current epoch and all previous epochs. |
#### Options
Set different parameters to simulate different transaction and network conditions.
| Flag | Description |
| ---------------------- | -------------------------------- |
| `-h, --help` | Show help options |
| `--version` | Show the version of hbbft |
| `-n <n>, --nodes <n>` | The total number of nodes [default: 10] |
| `-f <f>, --faulty <f>` | The number of faulty nodes [default: 0]|
| `-t <txs>, --txs <txs>` | The number of transactions to process [default: 1000] |
| `-b <b>, --batch <b>` | The batch size, i.e. txs per epoch [default: 100] |
| `-l <lag>, --lag <lag>` | The network lag between sending and receiving [default: 100] |
| `--bw <bw>` | The bandwidth, in kbit/s [default: 2000] |
| `--cpu <cpu>` | The CPU speed, in percent of this machine's [default: 100] |
| `--tx-size <size>` | The size of a transaction, in bytes [default: 10] |
| Flag | Description |
| ----------------------- | ------------------------------------------------------------ |
| `-h, --help` | Show help options |
| `--version` | Show the version of hbbft |
| `-n <n>, --nodes <n>` | The total number of nodes [default: 10] |
| `-f <f>, --faulty <f>` | The number of faulty nodes [default: 0] |
| `-t <txs>, --txs <txs>` | The number of transactions to process [default: 1000] |
| `-b <b>, --batch <b>` | The batch size, i.e. txs per epoch [default: 100] |
| `-l <lag>, --lag <lag>` | The network lag between sending and receiving [default: 100] |
| `--bw <bw>` | The bandwidth, in kbit/s [default: 2000] |
| `--cpu <cpu>` | The CPU speed, in percent of this machine's [default: 100] |
| `--tx-size <size>` | The size of a transaction, in bytes [default: 10] |
**Examples:**
@ -135,53 +126,50 @@ $ cargo run --example simulation --release -- -n 12 -f 2
# increase batch size to 500 transactions per epoch
$ cargo run --example simulation --release -- -b 500
```
## Protocol Modifications
Our implementation modifies the protocols described in "[The Honey Badger of BFT Protocols](https://eprint.iacr.org/2016/199.pdf)" in several ways:
* We use a [pairing elliptic curve library](https://github.com/ebfull/pairing) to implement pairing-based cryptography using a Barrento-Lynn-Scott (BLS12-381) curve.
* 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 include 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).
- We use a [pairing elliptic curve library](https://github.com/ebfull/pairing) to implement pairing-based cryptography using a Barrento-Lynn-Scott (BLS12-381) curve.
- 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 include 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).
### Algorithm naming conventions
We have simplified algorithm naming conventions from the original paper.
| Algorithm Name | Original Name |
| Algorithm Name | Original Name |
| ---------------- | --------------------------------------------- |
| Honey Badger | HoneyBadgerBFT |
| Subset | Asynchronous Common Subset (ACS) |
| Broadcast | Reliable Broadcast (RBC) |
| Binary Agreement | Asynchronous Binary Byzantine Agreement (ABA) |
## References
* [The Honey Badger of BFT Protocols](https://eprint.iacr.org/2016/199.pdf)
- [The Honey Badger of BFT Protocols](https://eprint.iacr.org/2016/199.pdf)
* [Honey Badger Video](https://www.youtube.com/watch?v=Qone4j1hCt8)
- [Honey Badger Video](https://www.youtube.com/watch?v=Qone4j1hCt8)
* Other language implementations
- Other language implementations
* [Python](https://github.com/initc3/HoneyBadgerBFT-Python)
- [Python](https://github.com/initc3/HoneyBadgerBFT-Python)
* [Go](https://github.com/anthdm/hbbft)
- [Go](https://github.com/anthdm/hbbft)
* [Erlang](https://github.com/helium/erlang-hbbft)
* [Rust](https://github.com/rphmeier/honeybadger) - unfinished implementation
- [Erlang](https://github.com/helium/erlang-hbbft)
- [Rust](https://github.com/rphmeier/honeybadger) - unfinished implementation
### Honey Badger Visualization
![Screenshot](assets/honey_badger_diagram.svg)
## Contributing
See the [CONTRIBUTING](CONTRIBUTING.md) document for contribution, testing and pull request protocol.
@ -190,9 +178,7 @@ See the [CONTRIBUTING](CONTRIBUTING.md) document for contribution, testing and p
Licensed under either of:
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
at your option.

8
src/binary_agreement/bool_multimap.rs
View File

@ -14,13 +14,13 @@ impl<N: Ord> Default for BoolMultimap<N> {
impl<N: Ord> Index<bool> for BoolMultimap<N> {
type Output = BTreeSet<N>;
fn index(&self, index: bool) -> &BTreeSet<N> {
fn index(&self, index: bool) -> &Self::Output {
&self.0[if index { 1 } else { 0 }]
}
}
impl<N: Ord> IndexMut<bool> for BoolMultimap<N> {
fn index_mut(&mut self, index: bool) -> &mut BTreeSet<N> {
fn index_mut(&mut self, index: bool) -> &mut Self::Output {
&mut self.0[if index { 1 } else { 0 }]
}
}
@ -29,7 +29,7 @@ impl<'a, N: Ord> IntoIterator for &'a BoolMultimap<N> {
type Item = (bool, &'a N);
type IntoIter = Iter<'a, N>;
fn into_iter(self) -> Iter<'a, N> {
fn into_iter(self) -> Self::IntoIter {
Iter::new(self)
}
}
@ -53,7 +53,7 @@ impl<'a, N: 'a + Ord> Iter<'a, N> {
impl<'a, N: 'a + Ord> Iterator for Iter<'a, N> {
type Item = (bool, &'a N);
fn next(&mut self) -> Option<(bool, &'a N)> {
fn next(&mut self) -> Option<Self::Item> {
if let Some(n) = self.set_iter.next() {
Some((self.key, n))
} else if self.key {

4
src/fault_log.rs
View File

@ -1,14 +1,14 @@
//! Functionality for logging faulty node behavior encountered by each
//! algorithm.
//!
//! Each algorithm can propogate their faulty node logs upwards to a calling algorithm via
//! Each algorithm can propagate their faulty node logs upwards to a calling algorithm via
//! `ConsensusProtocol`'s `.handle_input()` and `.handle_message()` trait methods.
pub use failure::Fail;
/// A structure representing the context of a faulty node. This structure
/// describes which node is faulty (`node_id`) and which faulty behavior
/// that the node exhibited ('kind').
/// that the node exhibited (`kind`).
#[derive(Clone, Debug, PartialEq)]
pub struct Fault<N, F: Fail> {
/// The faulty node's ID.

8
tests/README.md
View File

@ -48,10 +48,10 @@ net.broadcast_input(input).expect("algorithm failed");
The network advances through the `crank()` function, on every call
1. the adversary is given a chance to re-order<sup>1</sup> the message queue,
1. the next message in the queue is delivered to its destination node (if the node is non-faulty) or the adversary (if the node is faulty),
1. all messages from the resulting step are queued,
1. and the resulting step (or error) is returned.
1. the adversary is given a chance to re-order<sup>1</sup> the message queue,
2. the next message in the queue is delivered to its destination node (if the node is non-faulty) or the adversary (if the node is faulty),
3. all messages from the resulting step are queued,
4. and the resulting step (or error) is returned.
If there were no messages to begin with, `None` is returned instead.

2
tests/binary_agreement_mitm.rs
View File

@ -476,7 +476,7 @@ fn do_reordering_attack(seed: TestRngSeed) {
}
while !net.nodes().skip(1).all(|n| n.algorithm().terminated()) {
net.crank_expect(&mut rng);
let _ = net.crank_expect(&mut rng);
}
// Verify that all instances output the same value.