Crate guts_consensus 

Guts Consensus Engine

This crate provides the BFT consensus layer for Guts, transforming it from a replicated multi-node system into a truly decentralized network.

Architecture

The consensus engine is built on top of commonware primitives and provides:

• Simplex BFT Consensus: 2 network hops for proposals, 3 for finalization
• Transaction Ordering: Total ordering of all state-changing operations
• Byzantine Fault Tolerance: Tolerates f < n/3 Byzantine nodes
• Validator Management: Dynamic validator sets with epoch transitions

Components

• Transaction: All state-changing operations (git push, PRs, issues, etc.)
• Block: Ordered container of transactions
• Mempool: Pending transaction pool
• ValidatorSet: Set of validators participating in consensus
• Genesis: Initial network configuration
• simplex: Real Simplex BFT consensus engine (production)

Real Simplex BFT Consensus

The simplex module provides a production-ready BFT consensus implementation using the commonware-consensus library. This is the recommended way to run Guts in a multi-validator network.

use guts_consensus::simplex::{Engine, Config};
use commonware_p2p::authenticated::discovery;

// Create configuration
let config = Config::new(
    blocker,
    my_public_key,
    my_private_key,
    validator_public_keys,
);

// Create and start engine with P2P channels
let engine = Engine::new(context, config).await;
engine.start(pending, recovered, resolver, broadcast, marshal);

Transaction Flow

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Client     │────▶│   API Layer  │────▶│   Mempool    │
│  (git push)  │     │  (validate)  │     │  (pending)   │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                     ┌────────────────────────────┘
                     ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Broadcast   │◀────│   Leader     │◀────│  Consensus   │
│  to Peers    │     │  Proposes    │     │   Selects    │
└──────────────┘     │   Block      │     │    Leader    │
                     └──────┬───────┘     └──────────────┘
                            │
                            ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Validators  │────▶│  Notarize    │────▶│   Finalize   │
│    Vote      │     │  (2f+1)      │     │   (2f+1)     │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                                                  ▼
                     ┌──────────────────────────────────┐
                     │         Apply to State           │
                     │  (git refs, PRs, issues, etc.)   │
                     └──────────────────────────────────┘

Modules

simplex

Simplex BFT consensus implementation for Guts.

Structs

Block

A full block containing header and transactions.

BlockHeader

A block header containing metadata.

BlockId

A unique block identifier (SHA-256 hash of the block header).

BranchProtectionSpec

Serializable branch protection rules for consensus.

ConsensusEngine

The consensus engine.

ConsensusParams

Consensus parameters from genesis.

EngineConfig

Configuration for the consensus engine.

FinalizeMessage

Vote to finalize a block.

FinalizedBlock

Block with consensus metadata (votes, signatures).

Genesis

Complete genesis configuration.

GenesisRepository

Genesis repository (for testnet seeding).

GenesisValidator

Genesis configuration for a validator.

IssueUpdate

Update to an issue.

Mempool

The transaction mempool.

MempoolConfig

Configuration for the mempool.

MempoolStats

Statistics about the mempool.

NoOpApplication

A no-op application for testing.

NotarizeMessage

Vote to notarize a block.

NullifyMessage

Nullify vote when leader is unresponsive.

OrgUpdate

Update to an organization.

ProposeMessage

Block proposal message from the leader.

PullRequestUpdate

Update to a pull request.

SerializablePublicKey

Serializable public key (hex-encoded Ed25519 public key).

SerializableSignature

Serializable signature (hex-encoded Ed25519 signature).

SyncRequestMessage

Request missing blocks from a peer.

SyncResponseMessage

Response with requested blocks.

TeamSpec

Serializable team specification for consensus.

TransactionId

A unique transaction identifier (SHA-256 hash of the transaction).

TransactionMessage

Broadcast a new transaction to the network.

Validator

A validator in the consensus network.

ValidatorConfig

Configuration for validator set behavior.

ValidatorSet

The validator set for a given epoch.

VoteCollector

Vote collection for tracking quorum.

Enums

CommentTargetSpec

Comment target specification.

ConsensusError

Errors that can occur during consensus operations.

ConsensusEvent

Events emitted by the consensus engine.

ConsensusMessage

Consensus message types exchanged between validators.

EngineState

State of the consensus engine.

Transaction

Transactions that require consensus ordering.

Constants

CONSENSUS_CHANNEL

Channel ID for consensus messages (high priority).

SYNC_CHANNEL

Channel ID for block sync requests.

TRANSACTION_CHANNEL

Channel ID for transaction broadcast.

Traits

ConsensusApplication

Application interface for the consensus engine.

Functions

generate_devnet_genesis

Helper to generate a devnet genesis with test validators.

Type Aliases

Result

Result type for consensus operations.