ouroboros-consensus

Ouroboros-Consensus Repository Hackage Documentation

This graph depicts the relationship between the various Consensus packages:

Consensus packages dependencies

The Ouroboros Consensus Modules Map represents the dependencies between various ouroboros-consensus modules and is a map to navigate the (large) codebase. Note: The image needs to be enlarged to be useful hence why it's an external link.

Notable haddock comments

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:

ThreadNet 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 library and the corresponding tests.
Byron/PBFT. See Test.ThreadNet.Byron.
DualByron. Running Byron specification and Byron implementation at the same time. See Test.ThreadNet.DualByron.
Shelley/TPraos. See Test.ThreadNet.Shelley.
Cardano. Testing transitions between several Cardano eras. See Test.ThreadNet.Cardano.
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. See this directory.
HardForkBlock '[Byron, Shelley]: the hard fork combinator instantiated with the Byron and Shelley ledgers, running PBFT before the transition and TPraos after. See this file.

Note about the documentation

Due to limitations on how Haddock documents sublibraries, test-suites, bechmarks and executables, their documentation is named after the package name, that's why you will see multiple ouroboros-consensus sections below. This is annoying but it has to be fixed upstream in the toolchain and we can't do anything about it at the moment.

Moreover, modules with the exact same name are confused by Haddock into the same module (see that Main links always to the same module).

In general, the main libraries have as top level directory only a Ouroboros folder and are the first appearance of each package name.

Packages

ouroboros-consensus-0.17.0.0

Bench
Submodules
- Consensus
  Submodules
  - ChainSyncClient
    Submodules
    Bench.Consensus.ChainSyncClient.Driver
Main