hashgraph_like_consensus/
lib.rs

1//! A lightweight consensus library for making binary decisions in P2P networks.
2//!
3//! This library implements the [Hashgraph-like Consensus Protocol](https://github.com/vacp2p/rfc-index/blob/main/vac/raw/consensus-hashgraphlike.md),
4//! which lets groups of peers vote on proposals and reach agreement even when some peers are
5//! unreliable or malicious. It's designed to be fast (O(log n) rounds), secure (Byzantine fault
6//! tolerant), and easy to embed in your application.
7//!
8//! # How it works
9//!
10//! 1. Someone creates a [`types::CreateProposalRequest`] within a [`scope`].
11//! 2. Peers cast votes (yes/no), each cryptographically signed and linked into a hashgraph.
12//! 3. Once enough votes are collected the session transitions to
13//!    [`session::ConsensusState::ConsensusReached`] and a [`types::ConsensusEvent`] is emitted.
14//!
15//! # Getting started
16//!
17//! The main entry point is [`service::DefaultConsensusService`] (a type alias for
18//! [`service::ConsensusService`] with in-memory storage and broadcast events).
19//!
20//! ```rust,no_run
21//! use hashgraph_like_consensus::{
22//!     api::ConsensusServiceAPI,
23//!     scope::ScopeID,
24//!     service::DefaultConsensusService,
25//!     types::CreateProposalRequest,
26//! };
27//! use alloy::signers::local::PrivateKeySigner;
28//!
29//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
30//! let service = DefaultConsensusService::default();
31//! let scope = ScopeID::from("my-scope");
32//! let signer = PrivateKeySigner::random();
33//!
34//! let proposal = service
35//!     .create_proposal(
36//!         &scope,
37//!         CreateProposalRequest::new(
38//!             "Upgrade contract".into(),
39//!             b"Switch to v2".to_vec(),
40//!             signer.address().as_slice().to_vec(),
41//!             3,    // expected voters
42//!             60,   // expiration (seconds from now)
43//!             true, // tie-breaker: YES wins on equality
44//!         )?,
45//!     )
46//!     .await?;
47//!
48//! let vote = service
49//!     .cast_vote(&scope, proposal.proposal_id, true, signer)
50//!     .await?;
51//! # Ok(())
52//! # }
53//! ```
54//!
55//! # Modules
56//!
57//! | Module | Purpose |
58//! |--------|---------|
59//! | [`service`] | Main [`ConsensusService`](service::ConsensusService) and [`DefaultConsensusService`](service::DefaultConsensusService) |
60//! | [`api`] | [`ConsensusServiceAPI`](api::ConsensusServiceAPI) trait defining the public contract |
61//! | [`session`] | [`ConsensusSession`](session::ConsensusSession), [`ConsensusConfig`](session::ConsensusConfig), and [`ConsensusState`](session::ConsensusState) |
62//! | [`scope`] | [`ConsensusScope`](scope::ConsensusScope) trait and [`ScopeID`](scope::ScopeID) alias |
63//! | [`scope_config`] | Per-scope defaults ([`ScopeConfig`](scope_config::ScopeConfig), [`NetworkType`](scope_config::NetworkType)) |
64//! | [`types`] | Request/event types ([`CreateProposalRequest`](types::CreateProposalRequest), [`ConsensusEvent`](types::ConsensusEvent)) |
65//! | [`storage`] | [`ConsensusStorage`](storage::ConsensusStorage) trait and [`InMemoryConsensusStorage`](storage::InMemoryConsensusStorage) |
66//! | [`events`] | [`ConsensusEventBus`](events::ConsensusEventBus) trait and [`BroadcastEventBus`](events::BroadcastEventBus) |
67//! | [`error`] | [`ConsensusError`](error::ConsensusError) enum |
68//! | [`utils`] | Low-level validation and hashing helpers |
69
70pub mod protos {
71    pub mod consensus {
72        pub mod v1 {
73            include!(concat!(env!("OUT_DIR"), "/consensus.v1.rs"));
74        }
75    }
76}
77
78pub mod api;
79pub mod error;
80pub mod events;
81pub mod scope;
82pub mod scope_config;
83pub mod service;
84pub mod service_consensus;
85pub mod service_stats;
86pub mod session;
87pub mod storage;
88pub mod types;
89pub mod utils;
hashgraph_like_consensus/lib.rs

hashgraph_like_consensus/
lib.rs
