Module app

Pluggable, replicable applications.

Applications

The basic interaction between HotStuff-rs and the library user is this:

1. Library user specifies a state machine.
2. Library user provides the state machine to HotStuff-rs
3. HotStuff-rs replicates the state machine.

We refer to the state machine in this basic interaction as the “application”. In short, an application is a state machine that mutates two states, namely the App State and the Validator Set, in response to receiving a payload called a Block. In other words, an application can be thought of as a function (a “state transition function”) with the following type signature: (AppState, ValidatorSet, Block) -> (AppState, ValidatorSet).

To specify an application, the library user must implement the App trait. This entails implementing a state transition function and exposing this function to HotStuff-rs through three different required methods, namely produce_block, validate_block, and validate_block_for_sync.

Each of the above three methods correspond to a distinct context in which HotStuff-rs will call the application’s state transition function. For example, HotStuff-rs will call produce_block when the local replica is a leader and needs to produce a new block to propose it. The context in which each function is called is documented in their respective Rustdocs.

Two app-mutable states: App State and Validator Set

The two states that an application can mutate in response to a block are the App State, and the Validator Set. Both states are stored in the block tree, which itself is stored in the pluggable KVStore provided to HotStuff-rs by the library user.

The App State is a set of key-value mappings, in which the keys and values are be arbitrary byte strings. The library user is completely free to decide the structure and contents of this mapping in whichever way supports their use-case. HotStuff-rs itself does not assume anything about the app state, nor does it insert anything into the app state when a replica is initialized besides what the library user configures as the initial_app_state.

For more information about the Validator Set, read the rustdocs in the validator_set module.

App code tells HotStuff-rs to make changes to the app state and the validator set by listing the changes that should be made in an AppStateUpdates or ValidatorSetUpdates (respectively) and returning these changes from calls to its three methods.

Structs

• ProduceBlockRequest
  Request for an App to produce a new block extending a specific parent_block.
• ProduceBlockResponse
  Response from an App to a ProduceBlockRequest.
• ValidateBlockRequest
  Request for the app to validate a proposed block. Contains information about the proposed block, and the relevant state of the Block Tree.

Enums

• ValidateBlockResponse
  Response from an App upon receiving a ValidateBlockRequest.

Traits

• App
  Trait implemented by applications that are to be replicated by HotStuff-rs.