Crate hotstuff_rs
source ·Expand description
A Rust Programming Language library for Byzantine Fault Tolerant state machine replication, intended for production systems.
HotStuff-rs implements a variant of the HotStuff consensus protocol, but with extensions like block-sync and dynamic validator sets that makes this library suited for real-world use-cases (and not just research systems). Some desirable properties that HotStuff-rs has are:
- Provable Safety in the face of up to 1/3rd of voting power being Byzantine at any given moment.
- Optimal Performance: consensus in (amortized) 1 round trip time.
- Simplicity: A small API app for plugging in arbitrary stateful applications.
- Modularity: pluggable networking, state persistence, and view-synchronization mechanism.
- Dynamic Validator Sets that can update without any downtime based on state updates: a must for PoS blockchain applications.
- Batteries included: comes with a block-sync protocol and (coming soon) default implementations for networking, state, and pacemaker: you write the app, we handle the replication.
- Custom event handlers: includes a simple API for registering user-defined event handlers, triggered in response to HotStuff-rs protocol event notifications.
Terminology
- App: user code which implements the app trait. This can be any business logic that can be expressed
as a deterministic state machine, i.e., a pure function of kind:
(Blockchain, App State, Validator Set, Block) -> (Next Blockchain, Next App State, Next Validator Set)
. - Replica: a public-key-identified process that hosts an implementation of the HotStuff-rs protocol, e.g., this library. There are two kinds of Replicas: validators, and listeners, and each replica contains an instance of an app.
- Blockchain: a growing sequence of Blocks, which can be thought of as instructions to update a replica’s App State and Validator Set.
- App State: a key-value store that applications can use to store anything; two replicas with the same Blockchain are guaranteed to have the same app state.
- Validator Set: the set of replicas who can vote in a consensus decision.
- Progress protocol: the protocol replicas use to create new blocks through consensus and grow the blockchain.
- Sync protocol: the protocol new or previously offline replicas use to quickly catch up to the head of the blockchain.
Getting started
To replicate your application using HotStuff-rs, you need to represent it as a type and then have the type implement the app trait.
Then, initialize a replica’s storage, build the replica’s specification, and then start it.
An example of how to start a replica can be found here.
Modules
- Functions that implement the progress protocol and sync protocol.
- The App trait, HotStuff-rs’ interface into the business logic of users’ applications.
- A thread that receives events emitted from the algorithm and sync_server threads and calls registered event handlers.
- Notifications that are emitted when significant things happen in the local HotStuff-rs replica.
- Functions that log out events.
- Definitions for structured messages that are sent between replicas.
- Trait definition for pluggable peer-to-peer networking, as well as the internal types and functions that replicas use to interact with the network.
- Trait definition for pacemakers: user-provided types that determine the ‘liveness’ behavior of replicas.
- Methods to build, run, and initialize the storage of a replica.
- Types and methods used to access and mutate the persistent state that a replica keeps track for the operation of the protocol, and for its application.
- The server side of the block sync protocol.
- Definitions for ‘inert’ types, i.e., those that are sent around and inspected, but have no active behavior.