Skip to content

Commit 93402ab

Browse files
Night-mkNight-mk
committed
first commit
0 parents  commit 93402ab

File tree

147 files changed

+23203
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

147 files changed

+23203
-0
lines changed

‎.gitignore

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Binaries for programs and plugins
2+
*.exe
3+
*.exe~
4+
*.dll
5+
*.so
6+
*.dylib
7+
8+
# Test binary, built with `go test -c`
9+
*.test
10+
11+
# Output of the go coverage tool, specifically when used with LiteIDE
12+
*.out
13+
14+
# Dependency directories (remove the comment below to include it)
15+
# vendor/
16+
17+
# delve debug binary
18+
__debug_bin
19+
20+
# binaries
21+
/hotstuff
22+
/plot
23+
24+
25+
# other
26+
*.in
27+
28+
rr/
29+
30+
scripts/id
31+
scripts/id.pub
32+
scripts/known_hosts
33+
34+
measurements.json
35+
*.pdf
36+
37+
twins.json
38+
39+
.vscode/
40+
.github/
41+
.golangci.yml

‎Dockerfile

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
FROM golang:alpine AS builder
2+
3+
WORKDIR /go/src/github.com/relab/hotstuff
4+
COPY . .
5+
RUN go mod download
6+
RUN go install -ldflags='-s -w' ./...
7+
8+
FROM alpine
9+
10+
RUN apk add iproute2
11+
12+
COPY --from=builder /go/bin/* /usr/bin/

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2020 John Ingve Olsen and Hans Erik Frøyland
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎Makefile

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
proto_include := $(shell go list -m -f {{.Dir}} github.com/relab/gorums):internal/proto
2+
proto_src := internal/proto/clientpb/client.proto \
3+
internal/proto/hotstuffpb/hotstuff.proto \
4+
internal/proto/orchestrationpb/orchestration.proto \
5+
internal/proto/handelpb/handel.proto \
6+
metrics/types/types.proto
7+
proto_go := $(proto_src:%.proto=%.pb.go)
8+
gorums_go := internal/proto/clientpb/client_gorums.pb.go \
9+
internal/proto/hotstuffpb/hotstuff_gorums.pb.go \
10+
internal/proto/handelpb/handel_gorums.pb.go
11+
12+
binaries := hotstuff plot
13+
14+
.PHONY: all debug clean protos download tools $(binaries)
15+
16+
all: $(binaries)
17+
18+
debug: GCFLAGS += -gcflags='all=-N -l'
19+
debug: $(binaries)
20+
21+
$(binaries): protos
22+
@go build -o ./$@ $(GCFLAGS) ./cmd/$@
23+
24+
protos: $(proto_go) $(gorums_go)
25+
26+
download:
27+
@go mod download
28+
29+
tools: download
30+
@cat tools.go | grep _ | awk -F'"' '{print $$2}' | xargs -I % go install %
31+
32+
test:
33+
@go test -v ./...
34+
35+
clean:
36+
@rm -fv $(binaries)
37+
38+
%.pb.go %_gorums.pb.go : %.proto
39+
protoc -I=.:$(proto_include) \
40+
--go_out=paths=source_relative:. \
41+
--gorums_out=paths=source_relative:. \
42+
$<

‎README-hotstuff.md

+136
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# hotstuff
2+
3+
[![Go Reference](https://pkg.go.dev/badge/github.com/relab/consensus.svg)](https://pkg.go.dev/github.com/relab/hotstuff)
4+
![Test](https://github.com/relab/hotstuff/workflows/Test/badge.svg)
5+
![golangci-lint](https://github.com/relab/hotstuff/workflows/golangci-lint/badge.svg)
6+
[![codecov](https://codecov.io/gh/relab/hotstuff/branch/master/graph/badge.svg?token=IYZ7WD6ZAH)](https://codecov.io/gh/relab/hotstuff)
7+
8+
`relab/hotstuff` is a framework for experimenting with HotStuff and similar consensus protocols.
9+
It provides a set of modules and interfaces that make it easy to test different algorithms.
10+
It also provides a tool for deploying and running experiments on multiple servers via SSH.
11+
12+
## Contents
13+
14+
- [hotstuff](#hotstuff)
15+
- [Contents](#contents)
16+
- [Build Dependencies](#build-dependencies)
17+
- [Getting Started](#getting-started)
18+
- [Linux and macOS](#linux-and-macos)
19+
- [Windows](#windows)
20+
- [Running Experiments](#running-experiments)
21+
- [Safety Testing with Twins](#safety-testing-with-twins)
22+
- [Modules](#modules)
23+
- [Consensus Interfaces](#consensus-interfaces)
24+
- [Crypto Interfaces](#crypto-interfaces)
25+
- [References](#references)
26+
27+
## Build Dependencies
28+
29+
- [Go](https://go.dev) (at least version 1.18)
30+
31+
If you modify any of the protobuf files, you will need the following to compile them:
32+
33+
- [Protobuf compiler](https://github.com/protocolbuffers/protobuf) (at least version 3.15)
34+
35+
- The gRPC and gorums plugins for protobuf.
36+
- Linux and macOS users can run `make tools` to install these.
37+
- The Windows build script downloads them automatically.
38+
- They can also be installed manually:
39+
- `go install github.com/relab/gorums/cmd/protoc-gen-gorums`
40+
- `go install google.golang.org/protobuf/cmd/protoc-gen-go`
41+
42+
## Getting Started
43+
44+
### Linux and macOS
45+
46+
- Compile command line utilities by running `make`.
47+
48+
### Windows
49+
50+
- Run `.\build.ps1` with PowerShell.
51+
52+
**NOTE**: you should use `./hotstuff.exe` instead of `./hotstuff` when running commands.
53+
54+
## Running Experiments
55+
56+
See the [experimentation documentation](docs/experimentation.md) for details.
57+
58+
The `hotstuff` command line utility can be used to run experiments locally, or on remote servers using SSH.
59+
For a list of options, run `./hotstuff help run`.
60+
61+
The `plot` command line utility can be used to create graphs from measurements.
62+
Run `./plot --help` for a list of options.
63+
64+
## Safety Testing with Twins
65+
66+
We have implemented the Twins strategy [6] for testing the safety of the consensus implementations.
67+
See the [twins documentation](docs/twins.md) for details.
68+
69+
## Modules
70+
71+
The following components are modular:
72+
73+
- Consensus
74+
- The "core" of the consensus protocol, which decides when a replica should vote for a proposal,
75+
and when a block should be committed.
76+
- 3 implementations:
77+
- `chainedhotstuff`: The three-phase pipelined HotStuff protocol presented in the HotStuff paper [1].
78+
- `fasthotstuff`: A two-chain version of HotStuff designed to prevent forking attacks [3].
79+
- `simplehotstuff`: A simplified version of chainedhotstuff [4].
80+
- Crypto
81+
- Implements the cryptographic primitives used by HotStuff, namely quorum certificates.
82+
- 2 implementations:
83+
- `ecdsa`: A very simple implementation where quorum certificates are represented by arrays of ECDSA signatures.
84+
- `bls12`: An implementation of threshold signatures based on BLS12-381 aggregated signatures.
85+
- Synchronizer
86+
- Implements a view-synchronization algorithm. It is responsible for synchronizing replicas to the same view number.
87+
- Current implementation based on [DiemBFT's RoundState](https://github.com/diem/diem/tree/main/consensus/src/liveness) [5].
88+
- Blockchain
89+
- Implements storage for the block chain. Currently we have an in-memory cache of a fixed size.
90+
- Leader rotation
91+
- Decides which replica should be the leader of a view.
92+
- Currently either a fixed leader or round-robin.
93+
- Networking/Backend
94+
- Using [Gorums](https://github.com/relab/gorums) [2]
95+
96+
These modules are designed to be interchangeable and simple to implement.
97+
It is also possible to add custom modules that can interact with the modules we listed above.
98+
99+
## Consensus Interfaces
100+
101+
There are two ways to implement a new consensus protocol, depending on the requirements of the new protocol.
102+
The `Consensus` module interface is the most general, but also the most difficult to implement.
103+
That is because it is oriented towards the other modules, and the other modules rely on it to perform certain operations,
104+
such as verifying proposals, interacting with the `BlockChain`, `Acceptor`, `Executor`, and `Synchronizer` modules,
105+
and so on. That is why we provide a simplified `Rules` interface and the optional `ProposeRuler` interface.
106+
These interfaces are only required to implement the core rules of the consensus protocol, namely deciding whether or not
107+
to vote for a proposal, whether or not it is safe to commit a block, and optionally how to create new blocks.
108+
These interfaces do not require any interaction with other modules, as that is taken care of by a
109+
[default implementation](consensus/consensus.go) of the `Consensus` interface.
110+
111+
The `Consensus` and `Rules` interfaces can also be used to override the behavior of other consensus implementations.
112+
The `consensus/byzantine` package contains some examples of byzantine behaviors that can be implemented by wrapping
113+
implementations of these interfaces.
114+
115+
## Crypto Interfaces
116+
117+
In a similar way to the `Consensus` interface, the `Crypto` interface also introduces a simplified, lower-level interface
118+
that should be used to implement new crypto algorithms.
119+
The `Crypto` interface itself provides methods for working with the high-level structures such as quorum certificates.
120+
However, to make it easy to implement new crypto algorithms, the `CryptoImpl` interface can be used instead.
121+
This interface deals with signatures and threshold signatures directly, which are used by the `Crypto` interface
122+
to implement quorum certificates.
123+
124+
## References
125+
126+
[1] M. Yin, D. Malkhi, M. K. Reiter, G. Golan Gueta, and I. Abraham, “HotStuff: BFT Consensus in the Lens of Blockchain,” Mar 2018.
127+
128+
[2] Tormod Erevik Lea, Leander Jehl, and Hein Meling. Towards New Abstractions for Implementing Quorum-based Systems. In 37th International Conference on Distributed Computing Systems (ICDCS), Jun 2017.
129+
130+
[3] Mohammad M. Jalalzai, Jianyu Niu, Chen Feng, Fangyu Gai. Fast-HotStuff: A Fast and Resilient HotStuff Protocol, Oct 2020.
131+
132+
[4] Leander Jehl. Formal Verification of HotStuff, Jun 2021.
133+
134+
[5] Baudet, Mathieu, et al. "State machine replication in the libra blockchain." The Libra Assn., Tech. Rep (2019).
135+
136+
[6]: S. Bano, A. Sonnino, A. Chursin, D. Perelman, en D. Malkhi, “Twins: White-Glove Approach for BFT Testing”, 2020.

‎README.md

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# rapidfair
2+
RapidFair is a high-performance order-fairness BFT consensus protocol.

0 commit comments

Comments
 (0)