Readme updates #64

andogro · 2018-06-18T19:07:20Z

I made changes according to recommendations and removed serde from example. I envision the order of items changing (getting started section will move up) in the future.

vkomenda · 2018-06-18T19:14:13Z

README.md

+
+* Other language implementations
+
+  * [Go ](https://github.com/anthdm/hbbft)


[Go ] -> [Go]

vkomenda · 2018-06-18T19:15:38Z

README.md

-["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.


Move the space outside [Rust ].

afck · 2018-06-19T08:00:36Z

CONTRIBUTING.md

+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)


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".

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.

afck · 2018-06-19T08:20:12Z

CONTRIBUTING.md

+* 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.


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

afck · 2018-06-19T08:24:15Z

README.md

+**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. 


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."

afck · 2018-06-19T08:27:34Z

README.md

+
+### 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.


Maybe "and usable independently"?

afck · 2018-06-19T08:31:55Z

README.md

+
+## 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 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.

afck · 2018-06-19T08:33:50Z

README.md


-    $ cargo build [--release]
+  * [Erlang](https://github.com/helium/erlang-hbbft)


There's also Andrew Miller's original implementation:

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

An unfinished one:

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

afck · 2018-06-19T08:35:35Z

README.md

-# 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.
+
+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. 


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

afck · 2018-06-19T08:40:20Z

README.md

+
+- [ ] Dynamic Honey Badger (adding and removing nodes in a live network environment)
+
+- [ ] Networking example to detail Honey Badger implementation


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.

afck · 2018-06-19T09:01:24Z

README.md

 [![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.


Maybe we should add a list of points in which we deviate from the paper. Currently those would be, I think:

We use pairing-based cryptography instead of Gap Diffie-Hellman groups. But the principles are the same, and I think even Andrew Miller's Python implementation does that.

We added a Terminate message to Binary Agreement; otherwise the algorithm would have to run (or at least stay in memory) forever: Add a Terminate message to ABA? #55

We added a Conf message to Binary Agreement: Fix Common Coin use in Agreement. #37. (The Python implementation will probably also do that.)

We return some additional information from Subset and Honey Badger, namely which node had input which item/transaction.

Later, we'll implement the dynamic variant that can add and remove nodes (that's not in the paper), and maybe change the "coin schedule" (output fixed 0, fixed 1, then flip the coin, if it actually improves efficiency), and others.

(@vkomenda: Can you think of other points in which we differ from the paper?)

@afck also removed the requirement to have a trusted dealer in Distributed Key Generation (DKG) and, consequently, in the Common Coin algorithm. In hbbft, DKG is decentralized and runs without a trusted dealer.

This is a good idea. @afck can your provide a little more context to explain the reasoning behind the modifications? These may be obvious but I want to convey why the choices were made and what improvements result from these changes. Thanks!

Was pairing-based cryptography chosen to increase security, efficiency and/or implementation ease (Rust elliptic curve library)? Or other reasons?

What are potential uses for returned data from Subset & HB?

Are there any performance or other potential tradeoffs to run DKG without a trusted dealer? Was this choice made to enhance security/mitigate a potential single point of attack?

I may also add a table which shows the paper's naming conventions compared to this implementation for easy reference.

Rust elliptic curve library

Yes, that was the main reason. If we'd want to switch to e.g. the same elliptic curves that the Python implementation uses, we'd first have to create Rust bindings for some cryptography C library.

What are potential uses for returned data from Subset & HB?

E.g. you could detect malicious behavior: If a node inputs invalid transactions it may be useful to be able to identify and block or disconnect from that node.

DKG without a trusted dealer?

Requiring a trusted dealer severely limits its usefulness: In a distributed network you usually don't want a single person to know everyone's secret keys. The paper itself even mentions dealerless DKG, it just doesn't go into details because it goes a bit beyond its scope. The Python implementation has an open issue for it. The Erlang implementation has dealerless DKG, too.

vkomenda · 2018-06-19T09:17:04Z

CONTRIBUTING.md

+https://github.com/poanetwork/hbbft
+2. Create a feature branch
+3. Write tests to cover the work 
+4. Commit changes


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.

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.

Thanks I will be sure to add.

andogro · 2018-06-20T17:42:08Z

README.md


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


I removed serialization-serde - unsure if any other flags are used at this point.

That's correct. The flag serialization-serde has been removed. Wherever you see --features=serialization-serde, please remove it.

vkomenda

Looks fine to me.

afck · 2018-06-20T20:04:25Z

Looks good to me, too, but there seems to be a merge conflict.

andogro added 2 commits June 18, 2018 12:02

Updated README, added CONTRIBUTING.md file

bb18757

updated links

5855c4f

andogro requested a review from afck June 18, 2018 19:07

vkomenda reviewed Jun 18, 2018

View reviewed changes

README.md Outdated

* Other language implementations

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

Copy link

Contributor

vkomenda Jun 18, 2018

Choose a reason for hiding this comment

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

[Go ] -> [Go]

vkomenda reviewed Jun 18, 2018

View reviewed changes

andogro added 2 commits June 18, 2018 13:34

Header reorganization and spacing considerations

307c94c

added rust and cargo installation instruction

aef7cee

afck reviewed Jun 19, 2018

View reviewed changes

vkomenda reviewed Jun 19, 2018

View reviewed changes

Updated README

830d48b

andogro commented Jun 20, 2018

View reviewed changes

vkomenda approved these changes Jun 20, 2018

View reviewed changes

modified example simulation

ace6e6e

Resolved merge conflict

6cb8197

vkomenda merged commit 92381e4 into poanetwork:master Jun 21, 2018

andogro deleted the README_updates branch June 21, 2018 15:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Readme updates #64

Readme updates #64

andogro commented Jun 18, 2018 •

edited

Loading

vkomenda Jun 18, 2018

vkomenda Jun 18, 2018

afck Jun 19, 2018

andogro Jun 20, 2018

afck Jun 19, 2018

afck Jun 19, 2018

afck Jun 19, 2018

afck Jun 19, 2018

afck Jun 19, 2018

vkomenda Jun 19, 2018 •

edited

Loading

afck Jun 19, 2018

afck Jun 19, 2018

afck Jun 19, 2018

vkomenda Jun 19, 2018

andogro Jun 20, 2018 •

edited

Loading

afck Jun 20, 2018

vkomenda Jun 19, 2018

afck Jun 19, 2018

andogro Jun 20, 2018

andogro Jun 20, 2018

vkomenda Jun 20, 2018 •

edited

Loading

vkomenda left a comment

afck commented Jun 20, 2018


		* Other language implementations

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


		### 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.


		## 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.


		$ cargo build [--release]
		* [Erlang](https://github.com/helium/erlang-hbbft)


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

		- [ ] Networking example to detail Honey Badger implementation

Readme updates #64

Readme updates #64

Conversation

andogro commented Jun 18, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vkomenda Jun 19, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andogro Jun 20, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vkomenda Jun 20, 2018 • edited Loading

Choose a reason for hiding this comment

vkomenda left a comment

Choose a reason for hiding this comment

afck commented Jun 20, 2018

andogro commented Jun 18, 2018 •

edited

Loading

vkomenda Jun 19, 2018 •

edited

Loading

andogro Jun 20, 2018 •

edited

Loading

vkomenda Jun 20, 2018 •

edited

Loading