ouroboros-network

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`

Network

ouroboros-network-framework - our instantiations and implementation of servers, clients, abstractions for working with named pipes and unix sockets. These are higher level components, which don't dependent on ouroboros protocols, but build a solid foundation for the networking library
ouroboros-network - networking library which supports /Ouroboros family of protocols/. It includes:
- Implementations, type level specifications, and APIs of all the protocols:
  - ChainSync
  - BlockFetch
  - TxSubmission
  - TxSubmission2
  - LocalTxSubmission
  - LocalStateQuery
  - LocalTxMonitor
  - Handshake
- /Block chain related data structures that the networking code needs to be aware of:/
  - Block
  - AnchoredFragment
- Network applications:
  - Block Fetch Application
  - Tx Submission Applications:
    - inbound
    - outbound
  - Peer Selection
  - Data Diffusion which combines all the pieces for supporting a node
  - NodeToNode API
  - NodeToClient API

Ouroboros Consensus

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

Consensus packages dependencies

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
- ThreadNet Simulator: Simulates a network of nodes
ouroboros-consensus-byron : Byron-era consensus logic
ouroboros-consensus-byron-test : Byron specific tests
- Examples
ouroboros-consensus-shelley-test : Shelley specific tests
- Examples
ouroboros-consensus-mock : Integration of consensus with a mock ledger, for testing and experimentation purpose
- Mock Ledger
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.

test-infra/Main.hs provides tests for the infrastructure used for running consensus-related tests.
test-storage/Main.hs provides tests for the storage layer used by Consensus.
- The file system abstraction tests can be found in Test.Ouroboros.Storage.FS.StateMachine.
- The immutable DB tests can be found in Test.Ouroboros.Storage.ImmutableDB.
  - The primary index test can be found in Test.Ouroboros.Storage.ImmutableDB.Primary.
  - The model-based tests for the immutable DB can be found in Test.Ouroboros.Storage.ImmutableDB.StateMachine.
- The tests for the volatile DB can be found in Test.Ouroboros.Storage.VolatileDB.StateMachine.
- The ledger DB tests can be found in Test.Ouroboros.Storage.LedgerDB:
  - The in-memory ledger DB tests can be found in Test.Ouroboros.Storage.LedgerDB.InMemory.
  - The on-disk ledger DB tests can be found in Test.Ouroboros.Storage.LedgerDB.OnDisk.
- The tests for the chain DB can be found in Test.Ouroboros.Storage.ChainDB. The tests include:
  - The tests for the garbage collection schedule can be found in Test.Ouroboros.Storage.ChainDB.GcSchedule.
  - The tests for the chain DB iterator can be found in Test.Ouroboros.Storage.ChainDB.Iterator.
  - The tests of properties of the chain DB model can be found in Test.Ouroboros.Storage.ChainDB.Model.Test.
  - The main tests for the chain DB can be found in Test.Ouroboros.Storage.ChainDB.StateMachine.
Golden tests: our golden tests infrastructure lives in Test.Util.Serialisation.Golden. Golden tests are specific to each era:
Miscellanous tests (test-consensus test suite)
- The tests for the resource registry can be found in Test.Consensus.ResourceRegistry.
- The tests for the RAW lock mechanism we use can be found in Test.Consensus.Util.MonadSTM.RAWLock.
- The tests for the computation of blockchain time can be found in Test.Consensus.BlockchainTime.Simple.
- The tests for the mempool can be found in Test.Consensus.Mempool.
- The tests for the chain sync client can be found in Test.Consensus.MiniProtocol.ChainSync.Client.
- The tests for the local state query server can be found in Test.Consensus.MiniProtocol.LocalStateQuery.Server.
- The tests for versioned serialisation can be found in Test.Consensus.Util.Versioned.
- The tests for the DB marker and DB lock can be found in Test.Consensus.Node.
The hard fork combinator, time infrastructure: One of the responsibilities of the HFC is to offer time conversions (slot to epoch, wall clock to slot, etc.) across era transitions (which might change parameters such as the slot length and the epoch size). It does this by constructing a "summary" of the current state of the chain, basically recording what the various slot lengths and epoch sizes have been so far, and how far ahead we can look (the so-called "safe zone": if the transition to the next era is not yet known, there must exist a limited period after the ledger tip in which we can still time conversions).
- The tests for the hard fork summary can be found in Test.Consensus.HardFork.Summary.
- The tests for the hard fork history can be found in Test.Consensus.HardFork.History.

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.

Modules