Skip to content

Commit 6d21026

Browse files
sbellemamiller
sbellem
authored and
amiller
committed
Roadmap and update to Readme (#45)
* Update README * Add ROADMAP
1 parent 4e64d73 commit 6d21026

File tree

4 files changed

+179
-112
lines changed

4 files changed

+179
-112
lines changed

‎README.md‎

Lines changed: 40 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -6,133 +6,61 @@ The Honey Badger of BFT Protocols
66
[![Travis branch](https://img.shields.io/travis/amiller/HoneyBadgerBFT/dev.svg)](https://travis-ci.org/amiller/HoneyBadgerBFT)
77
[![Codecov branch](https://img.shields.io/codecov/c/github/amiller/honeybadgerbft/dev.svg)](https://codecov.io/github/amiller/honeybadgerbft?branch=dev)
88

9-
Most fault tolerant protocols (including RAFT, PBFT, Zyzzyva, Q/U) don't guarantee good performance when there are Byzantine faults.
10-
Even the so-called "robust" BFT protocols (like UpRight, RBFT, Prime, Spinning, and Stellar) have various hard-coded timeout parameters, and can only guarantee performance when the network behaves approximately as expected - hence they are best suited to well-controlled settings like corporate data centers.
9+
Most fault tolerant protocols (including RAFT, PBFT, Zyzzyva, Q/U) don't
10+
guarantee good performance when there are Byzantine faults. Even the so-called
11+
"robust" BFT protocols (like UpRight, RBFT, Prime, Spinning, and Stellar) have
12+
various hard-coded timeout parameters, and can only guarantee performance when
13+
the network behaves approximately as expected - hence they are best suited to
14+
well-controlled settings like corporate data centers.
1115

12-
HoneyBadgerBFT is fault tolerance for the wild wild wide-area-network. HoneyBadger nodes can even stay hidden behind anonymizing relays like Tor, and the purely-asynchronous protocol will make progress at whatever rate the network supports.
13-
14-
### License
15-
This is released under the CRAPL academic license. See ./CRAPL-LICENSE.txt
16-
Other licenses may be issued at the authors' discretion.
17-
18-
### Docker
19-
20-
Build the docker image first.
21-
22-
docker build -t honeybadgerbft .
23-
24-
By default, the Dockerfile will run the test suite:
25-
26-
docker run -it honeybadgerbft
27-
28-
### Installation && How to run the code
29-
30-
Working directory is usually the **parent directory** of HoneyBadgerBFT. All the bold vars are experiment parameters:
31-
32-
+ **N** means the total number of parties;
33-
+ **t** means the tolerance, usually N/4 in our experiments;
34-
+ **B** means the maximum number of transactions committed in a block (by default N log N). And therefore each party proposes B/N transactions.
35-
36-
#### Install dependencies (maybe it is faster to do a snapshot on EC2 for these dependencies)
37-
pbc
38-
39-
40-
wget https://crypto.stanford.edu/pbc/files/pbc-0.5.14.tar.gz
41-
tar -xvf pbc-0.5.14.tar.gz
42-
cd pbc-0.5.14
43-
./configure ; make ; sudo make install
44-
export LIBRARY_PATH=$LIBRARY_PATH:/usr/local/lib
45-
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
46-
47-
charm
48-
49-
50-
sudo apt-get install python3-dev
51-
git clone https://github.com/JHUISI/charm.git
52-
cd charm
53-
git checkout 2.7-dev
54-
sudo python setup.py install
55-
56-
57-
58-
pycrypt
16+
HoneyBadgerBFT is fault tolerance for the wild wild wide-area-network.
17+
HoneyBadger nodes can even stay hidden behind anonymizing relays like Tor, and
18+
the purely-asynchronous protocol will make progress at whatever rate the
19+
network supports.
5920

6021

61-
sudo python -m pip install pycrypto
22+
## Development Activities
23+
Since its initial implementation, the project has gone through a substantial
24+
refactoring, and is currently under active development.
6225

63-
Clone the code:
26+
At the moment, the following three milestones are being focused on:
6427

65-
git clone https://github.com/amiller/HoneyBadgerBFT.git
66-
git checkout dev
28+
* [Bounded Badger](https://github.com/initc3/HoneyBadgerBFT-Python/milestone/3)
29+
* [Test Network](https://github.com/initc3/HoneyBadgerBFT-Python/milestone/2<Paste>)
30+
* [Release 1.0](https://github.com/initc3/HoneyBadgerBFT-Python/milestone/1)
6731

68-
Generate the keys
69-
+ Threshold Signature Keys
32+
A roadmap of the project can be found in [ROADMAP.rst](./ROADMAP.rst).
7033

71-
python -m honeybadgerbft.crypto.threshsig.generate_keys N (t+1) > thsigN_t.keys
7234

73-
+ ECDSA Keys
35+
### Contributing
36+
Contributions are welcomed! To quickly get setup for development:
7437

75-
python -m honeybadgerbft.crypto.ecdsa.generate_keys_ecdsa N > ecdsa.keys
38+
1. Fork the repository and clone your fork. (See the Github Guide
39+
[Forking Projects](https://guides.github.com/activities/forking/) if
40+
needed.)
7641

77-
Threshold Encryption Keys
42+
2. Install [`Docker`](https://docs.docker.com/install/). (For Linux, see
43+
[Manage Docker as a non-root user](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user)
44+
to run `docker` without `sudo`.)
7845

79-
python -m honeybadgerbft.crypto.threshenc.generate_keys N (N-2t) > thencN_t.keys
46+
3. Install [`docker-compose`](https://docs.docker.com/compose/install/).
8047

81-
Usually, we run ecdsa key generation with large N just once because it can be re-used for different N/t.
82-
And we can store threshold signature keys and threshold encryption keys into different files for convenience.
48+
4. Run the tests (the first time will take longer as the image will be built):
8349

84-
##### Launch the code
85-
python -m experiments.honest_party_test -k thsigN_t.keys -e ecdsa.keys -b B -n N -t t -c thencN_t.keys
50+
```bash
51+
$ docker-compose run --rm honeybadger
52+
```
8653

87-
Notice that each party will expect at least NlgN many transactions. And usually there is a key exception after they finish the consensus. Please just ignore it.
54+
The tests should pass, and you should also see a small code coverage report
55+
output to the terminal.
8856

89-
### How to deploy the Amazon EC2 experiment
57+
If the above went all well, you should be setup for developing
58+
**HoneyBadgerBFT-Python**!
9059

91-
At HoneyBadger/ec2/ folder, run
92-
93-
python utility.py [ec2_access_key] [ec2_secret_key]
94-
95-
In this interactive ipython environment, run the following:
96-
97-
+ Prepare the all the keys files and put them in your local directory (namely ec2 folder)
98-
99-
(See the instructions above)
100-
101-
+ Launch new machines
102-
103-
launch_new_instances(region, number_of_machine)
104-
105-
+ Query IPs
106-
107-
ipAll()
108-
109-
+ Synchronize keys
110-
111-
c(getIP(), 'syncKeys')
112-
113-
+ Install Dependencies
114-
115-
c(getIP(), 'install_dependencies')
116-
117-
+ Clone and repo
118-
119-
c(getIP(), 'git_pull')
120-
121-
+ Launch the experiment
122-
123-
c(getIP(), 'runProtocol:N,t,B')
124-
where N, t, B are experiment parameters (replace them with numbers).
125-
126-
### Roadmap and TODO
127-
128-
- Implement distributed key generation
129-
130-
- Investigate better parameterization and add support for larger key sizes
131-
132-
- Replace plain TCP sockets with reliable/authenticated channels
133-
134-
- Integration with Hyperledger, Open Blockchain, etc.
135-
136-
Interested in contributing to HoneyBadgerBFT? Developers wanted. Contact [email protected] for more info.
60+
Interested in contributing to HoneyBadgerBFT? Developers wanted. Contact
61+
[email protected] for more info.
13762

13863

64+
## License
65+
This is released under the CRAPL academic license. See ./CRAPL-LICENSE.txt
66+
Other licenses may be issued at the authors' discretion.

‎ROADMAP.rst‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
*******
2+
Roadmap
3+
*******
4+
The project is currently focusing on three milestones:
5+
6+
* `Bounded Badger`_: A more secure HoneyBadgerBFT that no longer requires
7+
unbounded buffers for protocol messages.
8+
* `Test Network`_: HoneyBadgerBFT in action with a long-running test network.
9+
* `Release 1.0`_: Towards a better and more stable HoneyBadgerBFT Python
10+
implementation.
11+
12+
An overview of each milestone is given below.
13+
14+
15+
`Bounded Badger`_
16+
=================
17+
The main goal of this milestone is to implement a CHECKPOINT mechanism that
18+
will allow the HoneyBadgerBFT protocol to only require bounded storage. Please
19+
see `amiller/honeybadgerbft#57`_ for a detailed description of the issue, its
20+
motivation, and benefits.
21+
22+
Overall, this should make HoneyBadgerBFT more secure, (e.g.: resilient to DoS
23+
attacks), and provide a way for nodes to catch up when they fall out of sync.
24+
25+
The completion of this milestone will involve the following implementations:
26+
27+
* Tests that reproduce problems stemming from the unbounded-buffers approach
28+
(`#17`_).
29+
* Threshold signature upon the finalization of a block of transactions (
30+
`#15`_).
31+
* Broadcasting and reception of CHECKPOINT messages along with a "message
32+
bounding" behavior (`#16`_).
33+
* Message bounding of ABA (`#22`_).
34+
* Recovery mechanism aka "speedybadger" (`#18`_, `#21`_, `#33`_).
35+
* Garbage collection of "outdated" outgoing protocol messages (`#19`_, `#7`_).
36+
37+
To stay up-to-date with the issues the milestone comprises, see the milestone
38+
on Github at https://github.com/initc3/HoneyBadgerBFT-Python/milestone/3.
39+
40+
41+
`Test Network`_
42+
===============
43+
At a minimum this milestone wishes to have a long running test network
44+
deployed of approximately 10+ nodes.
45+
46+
The network will be administered by a trusted party to start with, and
47+
will consist of nodes running the Python implementation. In the near future,
48+
we would like to have an heteregenous network such that some nodes also run
49+
implementations written in other languages (e.g.: Go, Rust, Erlang, Haskell).
50+
51+
In order to support the delpoyment and operation of the test network, the
52+
following tasks are planned:
53+
54+
* Persistence layer for transactions, blocks, and "system state" (`#20`_,
55+
`#21`_).
56+
* Update and fix the relevant legacy experiments, including benchmark tests
57+
(`#23`_).
58+
* Provide authenticated communications, with persistent connections (`#25`_,
59+
`#26`_).
60+
* Setup minimal logging infrastructure to help monitoring and troubleshooting
61+
(`#24`_).
62+
* Provide a basic dashboard to view the network's state and activity (`#27`_,
63+
`#35`_).
64+
65+
To stay up-to-date with the issues the milestone comprises, see the milestone
66+
on Github at https://github.com/initc3/HoneyBadgerBFT-Python/milestone/2.
67+
68+
69+
`Release 1.0`_
70+
==============
71+
Release planned to appear after the completion of the bounded badger and
72+
test network milestones.
73+
74+
This milestone aims to make the implementation of better quality by addressing
75+
most of the opened issues, meaning:
76+
77+
* Resolving opened bugs (`#31`_, `#46`_).
78+
* Making sure the subprotocols are well tested (`#34`_).
79+
* Implementing the proposed batch size to be floor(B/N) (`#28`_).
80+
* Implementing a coin schedule for ABA (`#38`_).
81+
* Properly handling redundant messages in ABA (`#10`_).
82+
* Providing an overall good documentation of the project (`#30`_, `#43`_).
83+
* Implementing general best software engineering practices (`#13`_, `#14`_,
84+
`#29`_, `#32`_, `#40`_, `#41`_, `#42`_, `#44`_).
85+
86+
To stay up-to-date with the issues the milestone comprises, see the milestone
87+
on Github at https://github.com/initc3/HoneyBadgerBFT-Python/milestone/1.
88+
89+
90+
For Future Milestones
91+
=====================
92+
93+
Message Formats
94+
---------------
95+
Serialization/deserialization of messages using protocol buffers.
96+
97+
Distributed Key Generation
98+
--------------------------
99+
Dynamic addition and removal of nodes.
100+
101+
102+
.. _Bounded Badger: https://github.com/initc3/HoneyBadgerBFT-Python/milestone/3
103+
.. _Test Network: https://github.com/initc3/HoneyBadgerBFT-Python/milestone/2
104+
.. _Release 1.0: https://github.com/initc3/HoneyBadgerBFT-Python/milestone/1
105+
.. _amiller/honeybadgerbft#57: https://github.com/amiller/HoneyBadgerBFT/issues/57
106+
.. _#7: https://github.com/initc3/HoneyBadgerBFT-Python/issues/7
107+
.. _#10: https://github.com/initc3/HoneyBadgerBFT-Python/issues/10
108+
.. _#13: https://github.com/initc3/HoneyBadgerBFT-Python/issues/13
109+
.. _#14: https://github.com/initc3/HoneyBadgerBFT-Python/issues/14
110+
.. _#15: https://github.com/initc3/HoneyBadgerBFT-Python/issues/15
111+
.. _#16: https://github.com/initc3/HoneyBadgerBFT-Python/issues/16
112+
.. _#17: https://github.com/initc3/HoneyBadgerBFT-Python/issues/17
113+
.. _#18: https://github.com/initc3/HoneyBadgerBFT-Python/issues/18
114+
.. _#19: https://github.com/initc3/HoneyBadgerBFT-Python/issues/19
115+
.. _#20: https://github.com/initc3/HoneyBadgerBFT-Python/issues/20
116+
.. _#21: https://github.com/initc3/HoneyBadgerBFT-Python/issues/21
117+
.. _#22: https://github.com/initc3/HoneyBadgerBFT-Python/issues/22
118+
.. _#23: https://github.com/initc3/HoneyBadgerBFT-Python/issues/23
119+
.. _#24: https://github.com/initc3/HoneyBadgerBFT-Python/issues/24
120+
.. _#25: https://github.com/initc3/HoneyBadgerBFT-Python/issues/25
121+
.. _#26: https://github.com/initc3/HoneyBadgerBFT-Python/issues/26
122+
.. _#27: https://github.com/initc3/HoneyBadgerBFT-Python/issues/27
123+
.. _#28: https://github.com/initc3/HoneyBadgerBFT-Python/issues/28
124+
.. _#29: https://github.com/initc3/HoneyBadgerBFT-Python/issues/29
125+
.. _#30: https://github.com/initc3/HoneyBadgerBFT-Python/issues/30
126+
.. _#31: https://github.com/initc3/HoneyBadgerBFT-Python/issues/31
127+
.. _#32: https://github.com/initc3/HoneyBadgerBFT-Python/issues/32
128+
.. _#33: https://github.com/initc3/HoneyBadgerBFT-Python/issues/33
129+
.. _#34: https://github.com/initc3/HoneyBadgerBFT-Python/issues/34
130+
.. _#35: https://github.com/initc3/HoneyBadgerBFT-Python/issues/35
131+
.. _#38: https://github.com/initc3/HoneyBadgerBFT-Python/issues/38
132+
.. _#40: https://github.com/initc3/HoneyBadgerBFT-Python/issues/40
133+
.. _#41: https://github.com/initc3/HoneyBadgerBFT-Python/issues/41
134+
.. _#42: https://github.com/initc3/HoneyBadgerBFT-Python/issues/42
135+
.. _#43: https://github.com/initc3/HoneyBadgerBFT-Python/issues/43
136+
.. _#44: https://github.com/initc3/HoneyBadgerBFT-Python/issues/44
137+
.. _#46: https://github.com/initc3/HoneyBadgerBFT-Python/issues/46

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Welcome to HoneyBadgerBFT's documentation!
1111
:caption: Contents:
1212

1313
libref
14+
roadmap
1415

1516

1617
Indices and tables

‎docs/roadmap.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. include:: ../ROADMAP.rst

0 commit comments

Comments
 (0)