hotmint-consensus 0.8.2

HotStuff-2 consensus state machine and engine for Hotmint
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# hotmint-consensus

[![crates.io](https://img.shields.io/crates/v/hotmint-consensus.svg)](https://crates.io/crates/hotmint-consensus)
[![docs.rs](https://docs.rs/hotmint-consensus/badge.svg)](https://docs.rs/hotmint-consensus)

HotStuff-2 consensus state machine and engine for the [Hotmint](https://github.com/rust-util-collections/hotmint) BFT framework.

This is the core crate of Hotmint. It implements the full HotStuff-2 protocol — two-chain commit, five-step view protocol, pacemaker with exponential backoff — and is completely decoupled from I/O through pluggable trait interfaces.

## Architecture

```
ConsensusEngine
  ├── ConsensusState      mutable state (view, locks, role)
  ├── view_protocol       steady-state protocol (Paper Figure 1)
  ├── pacemaker           timeout & view change (Paper Figure 2)
  ├── vote_collector      vote aggregation & QC formation
  ├── commit              two-chain commit rule
  └── leader              round-robin leader election
```

## Pluggable Traits

| Trait | Purpose | Built-in Stub |
|:------|:--------|:--------------|
| `Application` | ABCI-like app lifecycle | `NoopApplication` |
| `BlockStore` | Block persistence | `MemoryBlockStore` |
| `NetworkSink` | Message transport | `Litep2pNetworkSink` |

## Usage

```rust
use hotmint_consensus::engine::ConsensusEngineBuilder;
use hotmint_consensus::state::ConsensusState;
use hotmint_consensus::store::MemoryBlockStore;
use hotmint_consensus::application::NoopApplication;

let engine = ConsensusEngineBuilder::new()
    .state(ConsensusState::new(vid, validator_set))
    .store(MemoryBlockStore::new_shared())
    .network(network_sink)           // Box<dyn NetworkSink>
    .app(Box::new(NoopApplication))
    .signer(Box::new(signer))
    .messages(msg_rx)
    .verifier(Box::new(verifier))
    .build()
    .unwrap();

tokio::spawn(async move { engine.run().await });
```

### Implement Application

All methods have default no-op implementations. Lifecycle: `execute_block(txs, ctx)` → `on_commit(block, ctx)`.

```rust
use ruc::*;
use hotmint_types::Block;
use hotmint_consensus::application::Application;

struct MyApp;

impl Application for MyApp {
    fn on_commit(&self, block: &Block, _ctx: &hotmint_types::context::BlockContext) -> Result<()> {
        println!("committed height {}", block.height.as_u64());
        Ok(())
    }
}
```

### Prometheus Metrics

```rust
use prometheus_client::registry::Registry;
use hotmint_consensus::metrics::ConsensusMetrics;

let mut registry = Registry::default();
let metrics = ConsensusMetrics::new(&mut registry);
// Exposes: hotmint_blocks_committed, hotmint_votes_sent,
//          hotmint_view_timeouts, hotmint_view_duration_seconds, ...
```

## License

GPL-3.0-only