hotmint-consensus 0.1.1

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

# 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 | `ChannelNetwork` |

## Usage

```rust
use hotmint_consensus::engine::ConsensusEngine;
use hotmint_consensus::state::ConsensusState;
use hotmint_consensus::store::MemoryBlockStore;
use hotmint_consensus::network::ChannelNetwork;
use hotmint_consensus::application::NoopApplication;

let engine = ConsensusEngine::new(
    ConsensusState::new(vid, validator_set),
    Box::new(MemoryBlockStore::new()),
    Box::new(ChannelNetwork::new(vid, senders)),
    Box::new(NoopApplication),
    Box::new(signer),
    msg_rx,
);

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

### Implement Application

Only `on_commit` is required. Lifecycle: `begin_block` → `deliver_tx` (×N) → `end_block` → `on_commit`.

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

struct MyApp;

impl Application for MyApp {
    fn on_commit(&self, block: &Block) -> 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