Malachite BFT Consensus Engine

The Malachite Quint Specification is a formal specification of the Malachite consensus engine. It is organized into three distinct layers to facilitate both implementation and verification:

1. Functional Layer: Captures the core logic of the consensus engine, including consensus logic, the vote keeper, and the driver.
2. State Machine Layer: Captures the execution of Tendermint consensus within a distributed setting. This layer is designed for both simulation and the generation of random traces used in model-based testing.
3. Runs and Tests: Provides documentation for interesting consensus scenarios and serves as the testing suite for the functional layer.

Developers can use the domain-specific language (DSL) provided in the specification to compose complex runs and scenarios.

Malachite is a flexible, high-performance Byzantine-fault tolerant (BFT) consensus engine implemented in Rust. It provides a state-of-the-art implementation of the Tendermint BFT consensus algorithm, designed to be used as a library for building decentralized systems such as sequencers, social networks, and Layer-1 blockchains.

Note: Malachite is currently in alpha and has not been externally audited. Use at your own risk.

Malachite implements its node-to-node communication primitives using the libp2p networking library. The network layer is primarily composed of two functional components:

1. Peer Discovery Protocol: Handles how nodes find each other within the network.
2. Gossip Communication Protocol: Handles the propagation of messages and data across the network using a gossip pattern.

For specific implementation details and usage of these protocols, refer to the discovery and gossip documentation sections.

ValueSync is a synchronization protocol designed to ensure long-term stability in Malachite nodes. It addresses the problem of nodes falling behind the consensus height due to extended downtime or network disconnections.

Without ValueSync, if too many nodes fall behind and cannot catch up, the network may lack sufficient synchronized validators to make progress. ValueSync allows nodes to quickly obtain missing data (certificates and values) from other nodes to catch up to the current consensus height.

The Proof-of-Validator (PoV) protocol is an independent module that allows validator nodes to cryptographically prove their status to other peers in the network. This enables nodes to distinguish between validators and non-validator peers, which is critical for consensus-related operations.

Key use cases for the PoV protocol include:

• Debugging and Observability: Classifying peers to improve operational visibility.
• Connection Prioritization: Prioritizing connections with validators to ensure reliable delivery of consensus messages.
• Mesh Formation Optimization: Prioritizing validators when constructing gossipsub's mesh overlay.

Accountable Tendermint is a variation of the Tendermint consensus algorithm designed to ensure the detection of amnesia attacks in scenarios where agreement is violated (i.e., two correct processes decide on different values).

While standard Tendermint can detect double votes, it cannot always identify who misbehaved during amnesia attacks. Accountable Tendermint provides an [Accountability] guarantee: if there are fewer than 2f + 1 Byzantine faulty processes out of 3f + 1 total processes, and agreement is violated, a correct node can collect sufficient data to identify at least f + 1 Byzantine processes.

The Middleware trait (found in malachitebft-test) allows you to intercept and modify consensus behavior at key points. This is primarily used for fault injection and testing different network conditions.

Available hooks in the Middleware trait include:

• get_validator_set(): Override the validator set for a specific height.
• get_timeouts(): Override consensus timeouts.
• on_propose_value(): Intercept or modify incoming proposals.
• get_validity(): Control decisions regarding proposal validity.
• on_commit(): Hook into the commit process.

Built-in middleware variants include DefaultMiddleware, RotateValidators, EpochValidators, and RotateEpochValidators.

The precommit step determines if a round has succeeded:

• Commitment: If a process observed an agreement on value $v$ during the prevote step, it broadcasts a PRECOMMIT message for id(v). Otherwise, it broadcasts nil.
• Success: If a super-majority of processes broadcast PRECOMMIT for the same value $v$, the height is finalized with that value.
• Failure: If conflicting information is received or a timeout occurs, the round fails and the process moves to the next round.