Cosmos HotStuff

A production-quality HotStuff consensus engine in Go, integrated with Cosmos SDK.

Overview

This project implements the Chained HotStuff consensus protocol and provides an adapter for integration with Cosmos SDK as the consensus layer.

Design Decisions

Decision	Choice	Rationale
HotStuff Variant	Chained HotStuff	Simplified 3-phase pipelining, clear reference implementation
Signatures	ed25519	Go standard library, fast, simple
Serialization	Protocol Buffers	Deterministic, Cosmos ecosystem compatible

Project Structure

/hotstuff           # Pure consensus core (no external dependencies)
  /types            # Block, Proposal, Vote, QC, Timeout, View
  /consensus        # Safety rules, QC validation
  /pacemaker        # View management, timeouts, leader election
  /crypto           # Signature abstraction (ed25519)
  /sim              # Network simulator for testing

/adapter/cosmos     # Cosmos SDK / CometBFT integration layer

/cmd/node           # Node binary

/scripts            # Local cluster scripts

/docs               # Design notes and assumptions

Quick Start

Prerequisites

• Go 1.21+
• Make

Build

make build

Test

make test

Run Local Cluster (4 validators)

make run-local

Milestones

• M0: Repo scaffolding + module layout + basic CI commands
• M1: HotStuff data structures + QC verification + deterministic tests
• M2: Basic pacemaker (view/timeout) + leader selection + tests
• M3: In-memory network simulator for 4 nodes + integration tests
• M4: Persistence/WAL minimal + crash recovery test
• M5: Cosmos adapter skeleton + compile/run
• M6: End-to-end Cosmos app commits blocks finalized by HotStuff (MVP)

License

MIT