Ouroboros-Network Repository Hackage Documentation

skip to module list

This site contains Haskell documentation of

  • Ouroboros-Network - networking component of the Haskell implementation of Ouroboros protocols
  • Ouroboros-Consensus - Ouroboros Consensus family of protocols which integrate with `Ouroboros-Network`


Ouroboros Consensus

This graph depicts the relationship between the various `xxx-consensus-yyy` packages:

  • ouroboros-consensus : Main package for Cardano consensus implementation, aka. Ouroboros.

    • The Ouroboros Consensus Modules Map represents the dependencies between various Consensus modules and is a map to navigate the (large) codebase. Clicking on a module should bring you to the corresponding haddock page from which you can later navigate to the source code. Note: The image needs to be enlarged to be useful hence why it's an external link.
  • ouroboros-consensus-test : Property and model-based tests for consensus, using io-sim

  • ouroboros-consensus-byron : Byron-era consensus logic
  • ouroboros-consensus-byron-test : Byron specific tests

  • ouroboros-consensus-shelley-test : Shelley specific tests

  • ouroboros-consensus-mock : Integration of consensus with a mock ledger, for testing and experimentation purpose

  • ouroboros-consensus-mock-test : Tests for consensus with mock ledger

    • Generators provides various orphan Arbitrary instances
  • db-analyser: A command-line tool for offline analysis of the consensus database

Consensus implementation

The comments in modules listed below provide important information on the implementation of consensus.

Consensus Components

The following C4 Component Diagram provides a high-level overview of the main components involved in Consensus. Note that clicking on a box should link to the corresponding documentation:

Testing in the consensus layer

The vast majority of the tests in the consensus layer are QuickCheck property tests, and many of these are model based. There are only a handful of unit tests. The consensus layer is an intricate piece of software with lots of components, which we set at virtually every level of granularity. Below we give an overview of the tests that we do per component. For the detailed listing, please refer to the various test suites within the repository.

Consensus tests

The main consensus tests are the consensus layer's sophisticated tests. They are "system level" tests, in which we set up a mock network of nodes, where we can simulate things like nodes joining late, network message delay, etc. We then have these nodes run the full protocol, exchanging blocks, doing chain selection, etc. Finally we verify that the nodes can reach consensus. We have some generic infrastructure for doing all of this, and then have specific tests for each of the protocols/ledgers we support.

In a way, these are the most important tests we have, as they are testing properties of the system as a whole. Of course, that also means that if something goes wrong, debugging these tests can be difficult, and it would be better to have such problems caught by the other, more fine-grained, tests.

We run these tests for

  • A mock ledger (containing bare bones UTxO style transactions) using a variety of consensus protocols: BFT, PBFT, Praos, and a version of Praos where we override the leader schedule. See this directory.
  • Byron/PBFT. See Test.ThreadNet.Byron.
  • DualByron. See Test.ThreadNet.DualByron.
  • Shelley/TPraos. See Test.ThreadNet.Shelley.
  • The hard fork combinator transitioning from a mock ledger A to a mock ledger B; these mock ledgers are absolutely minimal ledgers: the only transaction supported on the A ledger is "initiate transition to B", and the B ledger can only contain blocks with a header only, no body at all.
  • HardForkBlock '[Byron, Shelley]: the hard fork combinator instantiated with the Byron and Shelley ledgers, running PBFT before the transition and TPraos after.