mirror of https://github.com/poanetwork/hbbft.git
Fix unused error in test and fix markdown format error
This commit is contained in:
parent
51e4809260
commit
7078387115
64
README.md
64
README.md
|
@ -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.
|
||||
|
@ -62,7 +63,6 @@ Please see the following posts for more details:
|
|||
|
||||
- **[Threshold Crypto](https://github.com/poanetwork/threshold_crypto):** A threshold cryptosystem for collaborative message decryption and signature creation.
|
||||
|
||||
|
||||
## Getting Started
|
||||
|
||||
This library requires a distributed network environment to function. Details on network requirements TBD.
|
||||
|
@ -73,31 +73,24 @@ _**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
|
||||
| ----------- | -------------------------------------------------------------------------- |
|
||||
| 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. |
|
||||
|
@ -105,17 +98,16 @@ $ cargo run --example simulation --release
|
|||
| 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]|
|
||||
| `-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] |
|
||||
|
@ -123,7 +115,6 @@ Set different parameters to simulate different transaction and network condition
|
|||
| `--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:**
|
||||
|
||||
```bash
|
||||
|
@ -135,17 +126,17 @@ $ 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
|
||||
|
||||
|
@ -158,30 +149,27 @@ We have simplified algorithm naming conventions from the original paper.
|
|||
| 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.
|
||||
|
||||
|
||||
|
|
|
@ -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 {
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -49,9 +49,9 @@ 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.
|
||||
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.
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
|
Loading…
Reference in New Issue