Skip to main content

System Overview

Welcome to the documentation for the ouroboros-consensus repository, which houses the Haskell implementation of the consensus layer used by the Cardano node.

What is ouroboros-consensus and why does it exist?​

In a blockchain network, nodes must independently agree on which chain of blocks is the current one — this is the consensus problem. The consensus layer solves this by implementing the Ouroboros family of proof-of-stake protocols.

The consensus layer interacts with two other major components:

  • the network layer, which handles peer-to-peer communication, and
  • the ledger layer, which defines the rules for validating blocks and transactions.

The consensus layer:

  • receives blocks and transactions from the network layer,
  • determines when the node should produce a new block,
  • uses the ledger layer to validate blocks and transactions, and
  • decides which chain to follow among competing alternatives.

To support these operations, the consensus layer also maintains a storage layer (ChainDB) for efficient access to blockchain data, and a mempool that buffers pending transactions until they can be included in a block.

Cardano has evolved through multiple ledger eras — Byron, Shelley, Allegra, Mary, Alonzo, Babbage, and Conway — each with its own consensus protocol and ledger rules (see this table for the transition history). The consensus layer is designed to support these transitions seamlessly — the same node can validate the entire chain history across all eras.

Where consensus sits​

The following diagram shows the consensus layer in the context of the Cardano node and its external interactions.

The consensus layer does not communicate directly with peers or clients — all external communication goes through the network layer. The ledger layer provides pure functions for validating blocks and transactions, while the consensus layer is responsible for storing the blockchain and deciding which chain to follow.

Code organization​

A core design principle is the abstraction from specific ledger and protocol implementations. The polymorphic core (in ouroboros-consensus) defines the consensus logic independently of any particular ledger or protocol, while Cardano-specific instantiations provide the concrete implementations:

  • byron — Byron era: PBFT protocol, Byron-specific block/ledger types, EBBs
  • shelley — Shelley-based eras (Shelley through Conway): Praos protocol, shared ledger integration
  • ouroboros-consensus-cardano — the Cardano block type combining all eras, hard fork transitions, and node configuration

Components' Data Flow explains how ChainDB, the mempool, and the mini-protocols interact.

Further reading​

  • Design Goals — the design principles behind the system; start here to understand why the system is the way it is
  • Components' Data Flow — how ChainDB, the mempool, and the mini-protocols interact
  • Ledger Interaction — how the consensus layer interfaces with the ledger and network layers
  • Queries — how consensus exposes information to clients
  • Node Tasks — a practical view of what a running node does