ouroboros-consensus
Ouroboros-Consensus Repository Hackage Documentation
This graph depicts the relationship between the various Consensus packages:
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.
Databases:
- Mempool: Ouroboros.Consensus.Mempool.API
Protocol:
HardFork combinator:
- Chain selection: Ouroboros.Consensus.Storage.ChainDB.Impl.ChainSel
Miniprotocols:
Utilities:
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 ledgerB
; these mock ledgers are absolutely minimal ledgers: the only transaction supported on theA
ledger is "initiate transition toB
", and theB
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, runningPBFT
before the transition andTPraos
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.
- Bench
- Consensus
- ChainSyncClient
- Consensus
- Main
- Main
- Test
- DBAnalyser
- Main
- DBSynthesizer
- Main
- DBAnalyser
- DBTruncater
- Main
- Main
- Test
- Ouroboros
- Test
- Ouroboros
- Consensus
- ByronSpec
- Ouroboros.Consensus.ByronSpec.Ledger
- Ouroboros.Consensus.ByronSpec.Ledger.Accessors
- Ouroboros.Consensus.ByronSpec.Ledger.Block
- Ouroboros.Consensus.ByronSpec.Ledger.Conversions
- Ouroboros.Consensus.ByronSpec.Ledger.Forge
- Ouroboros.Consensus.ByronSpec.Ledger.GenTx
- Ouroboros.Consensus.ByronSpec.Ledger.Genesis
- Ouroboros.Consensus.ByronSpec.Ledger.Ledger
- Ouroboros.Consensus.ByronSpec.Ledger.Mempool
- Ouroboros.Consensus.ByronSpec.Ledger.Orphans
- Ouroboros.Consensus.ByronSpec.Ledger.Rules
- Ouroboros.Consensus.ByronSpec.Ledger
- ByronSpec
- Consensus
- Test
- Consensus
- ThreadNet
- Cardano
- Api
- Node
- Tools
- DBAnalyser
- DBImmutaliser
- DBSynthesizer
- DBTruncater
- Cardano.Tools.GitRev
- ImmDBServer
- DBAnalyser
- Test
- Ouroboros
- Consensus
- Byron
- Crypto
- Ouroboros.Consensus.Byron.EBBs
- Ouroboros.Consensus.Byron.Ledger
- Ouroboros.Consensus.Byron.Ledger.Block
- Ouroboros.Consensus.Byron.Ledger.Config
- Ouroboros.Consensus.Byron.Ledger.Conversions
- Ouroboros.Consensus.Byron.Ledger.Forge
- Ouroboros.Consensus.Byron.Ledger.HeaderValidation
- Ouroboros.Consensus.Byron.Ledger.Inspect
- Ouroboros.Consensus.Byron.Ledger.Integrity
- Ouroboros.Consensus.Byron.Ledger.Ledger
- Ouroboros.Consensus.Byron.Ledger.Mempool
- Ouroboros.Consensus.Byron.Ledger.NetworkProtocolVersion
- Ouroboros.Consensus.Byron.Ledger.Orphans
- Ouroboros.Consensus.Byron.Ledger.PBFT
- Ouroboros.Consensus.Byron.Ledger.Serialisation
- Ouroboros.Consensus.Byron.Node
- Ouroboros.Consensus.Byron.Protocol
- Ouroboros.Consensus.Cardano
- Shelley
- Ouroboros.Consensus.Shelley.Crypto
- Ouroboros.Consensus.Shelley.Eras
- Ouroboros.Consensus.Shelley.HFEras
- Ouroboros.Consensus.Shelley.Ledger
- Ouroboros.Consensus.Shelley.Ledger.Block
- Ouroboros.Consensus.Shelley.Ledger.Config
- Ouroboros.Consensus.Shelley.Ledger.Forge
- Ouroboros.Consensus.Shelley.Ledger.Inspect
- Ouroboros.Consensus.Shelley.Ledger.Integrity
- Ouroboros.Consensus.Shelley.Ledger.Ledger
- Ouroboros.Consensus.Shelley.Ledger.Mempool
- Ouroboros.Consensus.Shelley.Ledger.NetworkProtocolVersion
- Ouroboros.Consensus.Shelley.Ledger.PeerSelection
- Ouroboros.Consensus.Shelley.Ledger.Protocol
- Ouroboros.Consensus.Shelley.Ledger.Query
- Ouroboros.Consensus.Shelley.Ledger.SupportsProtocol
- Ouroboros.Consensus.Shelley.Node
- Protocol
- Ouroboros.Consensus.Shelley.ShelleyHFC
- Byron
- Consensus
- Main
- Test
- Consensus
- BlockchainTime
- HardFork
- Test.Consensus.HeaderValidation
- Test.Consensus.Mempool
- MiniProtocol
- Test.Consensus.ResourceRegistry
- Util
- Consensus
- Main
- Test
- Consensus
- Test.Consensus.BlockTree
- Test.Consensus.GSM
- Genesis
- HardFork
- IOSimQSM
- Test
- Network
- AnchoredFragment
- Test.Consensus.Node
- PeerSimulator
- Test.Consensus.PeerSimulator.BlockFetch
- Test.Consensus.PeerSimulator.CSJInvariants
- Test.Consensus.PeerSimulator.ChainSync
- Test.Consensus.PeerSimulator.Config
- Test.Consensus.PeerSimulator.Handlers
- Test.Consensus.PeerSimulator.NodeLifecycle
- Test.Consensus.PeerSimulator.Resources
- Test.Consensus.PeerSimulator.Run
- Test.Consensus.PeerSimulator.ScheduledBlockFetchServer
- Test.Consensus.PeerSimulator.ScheduledChainSyncServer
- Test.Consensus.PeerSimulator.ScheduledServer
- Test.Consensus.PeerSimulator.StateDiagram
- Test.Consensus.PeerSimulator.StateView
- Test.Consensus.PeerSimulator.Tests
- Test.Consensus.PeerSimulator.Trace
- Test.Consensus.PointSchedule
- Util
- Consensus
- Main
- Test
- ThreadNet
- Main
- Test
- Test
- Consensus
- Ledger
- ThreadNet
- Consensus
- Ouroboros
- Consensus
- Network
- Ouroboros.Consensus.Node
- Ouroboros.Consensus.Node.DbLock
- Ouroboros.Consensus.Node.DbMarker
- Ouroboros.Consensus.Node.ErrorPolicy
- Ouroboros.Consensus.Node.Exit
- Ouroboros.Consensus.Node.ExitPolicy
- Ouroboros.Consensus.Node.GSM
- Ouroboros.Consensus.Node.Genesis
- Ouroboros.Consensus.Node.Recovery
- Ouroboros.Consensus.Node.RethrowPolicy
- Ouroboros.Consensus.Node.Tracers
- Ouroboros.Consensus.NodeKernel
- Consensus
- Main
- Ouroboros
- Consensus
- Test
- Ouroboros
- Consensus
- ChainGenerator
- Util
- Consensus
- Util
- ChainUpdates
- Schedule
- Split
- Ouroboros
- Bench
- Main
- Main
- Test
- Consensus
- Protocol
- Consensus
- Test
- Consensus
- Protocol
- Serialisation
- Protocol
- Consensus
- Ouroboros
- Consensus
- Consensus
- Main
- Test
- Test
- Ouroboros
- Consensus
- ChainGenerator
- Test.Ouroboros.Consensus.ChainGenerator.Adversarial
- Test.Ouroboros.Consensus.ChainGenerator.BitVector
- Test.Ouroboros.Consensus.ChainGenerator.Counting
- Test.Ouroboros.Consensus.ChainGenerator.Honest
- Test.Ouroboros.Consensus.ChainGenerator.Params
- Test.Ouroboros.Consensus.ChainGenerator.RaceIterator
- Test.Ouroboros.Consensus.ChainGenerator.Slot
- Test.Ouroboros.Consensus.ChainGenerator.Some
- Test.Ouroboros.Consensus.DiffusionPipelining
- Test.Ouroboros.Consensus.Protocol
- ChainGenerator
- Consensus
- QuickCheck
- Util
- Test.Util.BoolProps
- Test.Util.ChainDB
- Test.Util.ChainUpdates
- Test.Util.ChunkInfo
- Test.Util.Corruption
- Test.Util.FileLock
- HardFork
- Test.Util.InvertedMap
- Test.Util.LogicalClock
- Test.Util.MockChain
- Orphans
- Test.Util.Paths
- Test.Util.QSM
- Test.Util.QuickCheck
- Test.Util.Range
- Test.Util.RefEnv
- Test.Util.SOP
- Test.Util.SanityCheck
- Test.Util.Schedule
- Serialisation
- Test.Util.Shrink
- Test.Util.Slots
- Test.Util.Split
- Test.Util.Stream
- Test.Util.SupportedNetworkProtocolVersion
- Test.Util.TestBlock
- Test.Util.TestEnv
- Test.Util.Time
- Test.Util.ToExpr
- Test.Util.Tracer
- Test.Util.WithEq
- Ouroboros
- Test
- Consensus
- Ouroboros
- Consensus
- Consensus
- Ouroboros
- Ouroboros
- Consensus
- Ouroboros.Consensus.Block
- Ouroboros.Consensus.Block.Abstract
- Ouroboros.Consensus.Block.EBB
- Ouroboros.Consensus.Block.Forging
- Ouroboros.Consensus.Block.NestedContent
- Ouroboros.Consensus.Block.RealPoint
- Ouroboros.Consensus.Block.SupportsDiffusionPipelining
- Ouroboros.Consensus.Block.SupportsMetrics
- Ouroboros.Consensus.Block.SupportsProtocol
- Ouroboros.Consensus.Block.SupportsSanityCheck
- Ouroboros.Consensus.BlockchainTime
- Ouroboros.Consensus.Config
- Ouroboros.Consensus.Forecast
- Fragment
- Genesis
- HardFork
- Ouroboros.Consensus.HardFork.Abstract
- Ouroboros.Consensus.HardFork.Combinator
- Ouroboros.Consensus.HardFork.Combinator.Abstract
- Ouroboros.Consensus.HardFork.Combinator.AcrossEras
- Ouroboros.Consensus.HardFork.Combinator.Basics
- Ouroboros.Consensus.HardFork.Combinator.Block
- Ouroboros.Consensus.HardFork.Combinator.Compat
- Ouroboros.Consensus.HardFork.Combinator.Condense
- Ouroboros.Consensus.HardFork.Combinator.Degenerate
- Embed
- Ouroboros.Consensus.HardFork.Combinator.Forging
- Ouroboros.Consensus.HardFork.Combinator.Info
- Ouroboros.Consensus.HardFork.Combinator.InjectTxs
- Ouroboros.Consensus.HardFork.Combinator.Ledger
- Ouroboros.Consensus.HardFork.Combinator.Lifting
- Ouroboros.Consensus.HardFork.Combinator.Mempool
- Ouroboros.Consensus.HardFork.Combinator.Node
- Ouroboros.Consensus.HardFork.Combinator.PartialConfig
- Ouroboros.Consensus.HardFork.Combinator.Protocol
- Ouroboros.Consensus.HardFork.Combinator.Serialisation
- Ouroboros.Consensus.HardFork.Combinator.State
- Ouroboros.Consensus.HardFork.Combinator.Translation
- Ouroboros.Consensus.HardFork.History
- Ouroboros.Consensus.HardFork.Simple
- Ouroboros.Consensus.HeaderStateHistory
- Ouroboros.Consensus.HeaderValidation
- Ledger
- Ouroboros.Consensus.Ledger.Abstract
- Ouroboros.Consensus.Ledger.Basics
- Ouroboros.Consensus.Ledger.CommonProtocolParams
- Ouroboros.Consensus.Ledger.Dual
- Ouroboros.Consensus.Ledger.Extended
- Ouroboros.Consensus.Ledger.Inspect
- Ouroboros.Consensus.Ledger.Query
- Ouroboros.Consensus.Ledger.SupportsMempool
- Ouroboros.Consensus.Ledger.SupportsPeerSelection
- Ouroboros.Consensus.Ledger.SupportsProtocol
- Ouroboros.Consensus.Mempool
- MiniProtocol
- BlockFetch
- ChainSync
- LocalStateQuery
- LocalTxMonitor
- LocalTxSubmission
- Node
- Ouroboros.Consensus.NodeId
- Protocol
- Storage
- Ouroboros.Consensus.Storage.ChainDB
- Ouroboros.Consensus.Storage.ChainDB.API
- Ouroboros.Consensus.Storage.ChainDB.Impl
- Ouroboros.Consensus.Storage.ChainDB.Impl.Args
- Ouroboros.Consensus.Storage.ChainDB.Impl.Background
- Ouroboros.Consensus.Storage.ChainDB.Impl.BlockCache
- Ouroboros.Consensus.Storage.ChainDB.Impl.ChainSel
- Ouroboros.Consensus.Storage.ChainDB.Impl.Follower
- Ouroboros.Consensus.Storage.ChainDB.Impl.Iterator
- Ouroboros.Consensus.Storage.ChainDB.Impl.LgrDB
- Ouroboros.Consensus.Storage.ChainDB.Impl.Paths
- Ouroboros.Consensus.Storage.ChainDB.Impl.Query
- Ouroboros.Consensus.Storage.ChainDB.Impl.Types
- Ouroboros.Consensus.Storage.ChainDB.Init
- Ouroboros.Consensus.Storage.Common
- Ouroboros.Consensus.Storage.ImmutableDB
- Ouroboros.Consensus.Storage.ImmutableDB.API
- Ouroboros.Consensus.Storage.ImmutableDB.Chunks
- Ouroboros.Consensus.Storage.ImmutableDB.Impl
- Ouroboros.Consensus.Storage.ImmutableDB.Impl.Index
- Ouroboros.Consensus.Storage.ImmutableDB.Impl.Iterator
- Ouroboros.Consensus.Storage.ImmutableDB.Impl.Parser
- Ouroboros.Consensus.Storage.ImmutableDB.Impl.State
- Ouroboros.Consensus.Storage.ImmutableDB.Impl.Types
- Ouroboros.Consensus.Storage.ImmutableDB.Impl.Util
- Ouroboros.Consensus.Storage.ImmutableDB.Impl.Validation
- Ouroboros.Consensus.Storage.ImmutableDB.Stream
- Ouroboros.Consensus.Storage.LedgerDB
- Ouroboros.Consensus.Storage.Serialisation
- Ouroboros.Consensus.Storage.VolatileDB
- Ouroboros.Consensus.Storage.ChainDB
- Ouroboros.Consensus.Ticked
- Ouroboros.Consensus.TypeFamilyWrappers
- Ouroboros.Consensus.Util
- Ouroboros.Consensus.Util.AnchoredFragment
- Ouroboros.Consensus.Util.Args
- Ouroboros.Consensus.Util.Assert
- Ouroboros.Consensus.Util.CBOR
- Ouroboros.Consensus.Util.CallStack
- Ouroboros.Consensus.Util.Condense
- Ouroboros.Consensus.Util.DepPair
- Ouroboros.Consensus.Util.EarlyExit
- Ouroboros.Consensus.Util.Enclose
- Ouroboros.Consensus.Util.FileLock
- Ouroboros.Consensus.Util.HList
- Ouroboros.Consensus.Util.IOLike
- Ouroboros.Consensus.Util.LeakyBucket
- MonadSTM
- NormalForm
- Ouroboros.Consensus.Util.Orphans
- Ouroboros.Consensus.Util.RedundantConstraints
- Ouroboros.Consensus.Util.ResourceRegistry
- Ouroboros.Consensus.Util.STM
- Ouroboros.Consensus.Util.Time
- Ouroboros.Consensus.Util.Versioned
- Ouroboros.Consensus.Block
- Consensus
- Data