guts_consensus/lib.rs
1//! Guts Consensus Engine
2//!
3//! This crate provides the BFT consensus layer for Guts, transforming it from
4//! a replicated multi-node system into a truly decentralized network.
5//!
6//! # Architecture
7//!
8//! The consensus engine is built on top of commonware primitives and provides:
9//!
10//! - **Simplex BFT Consensus**: 2 network hops for proposals, 3 for finalization
11//! - **Transaction Ordering**: Total ordering of all state-changing operations
12//! - **Byzantine Fault Tolerance**: Tolerates f < n/3 Byzantine nodes
13//! - **Validator Management**: Dynamic validator sets with epoch transitions
14//!
15//! # Components
16//!
17//! - [`Transaction`]: All state-changing operations (git push, PRs, issues, etc.)
18//! - [`Block`]: Ordered container of transactions
19//! - [`Mempool`]: Pending transaction pool
20//! - [`ValidatorSet`]: Set of validators participating in consensus
21//! - [`Genesis`]: Initial network configuration
22//! - [`simplex`]: Real Simplex BFT consensus engine (production)
23//!
24//! # Real Simplex BFT Consensus
25//!
26//! The [`simplex`] module provides a production-ready BFT consensus implementation
27//! using the commonware-consensus library. This is the recommended way to run
28//! Guts in a multi-validator network.
29//!
30//! ```ignore
31//! use guts_consensus::simplex::{Engine, Config};
32//! use commonware_p2p::authenticated::discovery;
33//!
34//! // Create configuration
35//! let config = Config::new(
36//! blocker,
37//! my_public_key,
38//! my_private_key,
39//! validator_public_keys,
40//! );
41//!
42//! // Create and start engine with P2P channels
43//! let engine = Engine::new(context, config).await;
44//! engine.start(pending, recovered, resolver, broadcast, marshal);
45//! ```
46//!
47//! # Transaction Flow
48//!
49//! ```text
50//! ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
51//! │ Client │────▶│ API Layer │────▶│ Mempool │
52//! │ (git push) │ │ (validate) │ │ (pending) │
53//! └──────────────┘ └──────────────┘ └──────┬───────┘
54//! │
55//! ┌────────────────────────────┘
56//! ▼
57//! ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
58//! │ Broadcast │◀────│ Leader │◀────│ Consensus │
59//! │ to Peers │ │ Proposes │ │ Selects │
60//! └──────────────┘ │ Block │ │ Leader │
61//! └──────┬───────┘ └──────────────┘
62//! │
63//! ▼
64//! ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
65//! │ Validators │────▶│ Notarize │────▶│ Finalize │
66//! │ Vote │ │ (2f+1) │ │ (2f+1) │
67//! └──────────────┘ └──────────────┘ └──────┬───────┘
68//! │
69//! ▼
70//! ┌──────────────────────────────────┐
71//! │ Apply to State │
72//! │ (git refs, PRs, issues, etc.) │
73//! └──────────────────────────────────┘
74//! ```
75
76mod block;
77mod engine;
78mod error;
79mod genesis;
80mod mempool;
81mod message;
82pub mod simplex;
83mod transaction;
84mod validator;
85
86pub use block::{Block, BlockHeader, BlockId, FinalizedBlock};
87pub use engine::{
88 ConsensusApplication, ConsensusEngine, ConsensusEvent, EngineConfig, EngineState,
89 NoOpApplication,
90};
91pub use error::{ConsensusError, Result};
92pub use genesis::{
93 generate_devnet_genesis, ConsensusParams, Genesis, GenesisRepository, GenesisValidator,
94};
95pub use mempool::{Mempool, MempoolConfig, MempoolStats};
96pub use message::{
97 ConsensusMessage, FinalizeMessage, NotarizeMessage, NullifyMessage, ProposeMessage,
98 SyncRequestMessage, SyncResponseMessage, TransactionMessage, VoteCollector, CONSENSUS_CHANNEL,
99 SYNC_CHANNEL, TRANSACTION_CHANNEL,
100};
101pub use transaction::{
102 BranchProtectionSpec, CommentTargetSpec, IssueUpdate, OrgUpdate, PullRequestUpdate,
103 SerializablePublicKey, SerializableSignature, TeamSpec, Transaction, TransactionId,
104};
105pub use validator::{Validator, ValidatorConfig, ValidatorSet};
106
107#[cfg(test)]
108mod tests {
109 use super::*;
110
111 #[test]
112 fn test_crate_exports() {
113 // Verify all public types are accessible
114 let _: TransactionId;
115 let _: BlockId;
116 }
117}