ouroboros-network- A networking layer for the Ouroboros blockchain protocol
Safe HaskellNone



Let's start with the big picture...

Key:  ┏━━━━━━━━━━━━┓  ╔═════════════╗  ┏━━━━━━━━━━━━━━┓   ╔════════════╗
      ┃ STM-based  ┃  ║active thread║  ┃state instance┃┓  ║ one thread ║╗
      ┃shared state┃  ║             ║  ┃   per peer   ┃┃  ║  per peer  ║║
      ┗━━━━━━━━━━━━┛  ╚═════════════╝  ┗━━━━━━━━━━━━━━┛┃  ╚════════════╝║
                                        ┗━━━━━━━━━━━━━━┛   ╚════════════╝
  ╔═════════════╗     ┏━━━━━━━━━━━━━┓
  ║ Chain sync  ║╗    ┃   Ledger    ┃
  ║  protocol   ║║◀───┨   state     ┃◀───────────╮
  ║(client side)║║    ┃             ┃            │
  ╚══════╤══════╝║    ┗━━━━━━━━━━━━━┛            │
   ╚═════╪═══════╝                               │
         ▼                                       │
  ┏━━━━━━━━━━━━━┓     ┏━━━━━━━━━━━━━┓     ╔══════╧══════╗
  ┃  Candidate  ┃     ┃   Set of    ┃     ║  Chain and  ║
  ┃  chains     ┃     ┃  downloaded ┠────▶║   ledger    ║
  ┃  (headers)  ┃     ┃   blocks    ┃     ║  validation ║
  ┗━━━━━┯━━━━━━━┛     ┗━━━━━┯━━━━━━━┛     ╚══════╤══════╝
        │                   │ ▲                  │
        │ ╭─────────────────╯ │                  │
░░░░░░░░▼░▼░░░░░░░░           │                  ▼
░░╔═════════════╗░░           │           ┏━━━━━━━━━━━━━┓     ╔═════════════╗
░░║    Block    ║░░           │           ┃   Current   ┃     ║ Block fetch ║╗
░░╢    fetch    ║◀────────────┼───────────┨    chain    ┠────▶║ protocol    ║║
░░║    logic    ║░░           │           ┃  (blocks)   ┃     ║(server side)║║
░░╚═════════════╝░░           │           ┠─────────────┨     ╚═════════════╝║
░░░░░░░░░▲░░░░░░░░░           │           ┃  Tentative  ┃      ╚═════════════╝
░░░░░░░░░▼░░░░░░░░░░░░░░░░░░░░│░░░░░░░░   ┃    chain    ┠──╮
░░┏━━━━━━━━━━━━━┓░░░░░╔═══════╧═════╗░░   ┃  (headers)  ┃  │  ╔═════════════╗
░░┃ Block fetch ┃┓░░░░║ block fetch ║╗░   ┗━━━━━━━━━━━━━┛  │  ║ Chain sync  ║╗
░░┃  state and  ┃┃◀──▶║  protocol   ║║░                    ╰─▶║ protocol    ║║
░░┃  requests   ┃┃░░░░║(client side)║║░                       ║(server side)║║
░░┗━━━━━━━━━━━━━┛┃░░░░╚═════════════╝║░                       ╚═════════════╝║
░░░┗━━━━━━━━━━━━━┛░░░░░╚═════════════╝░                        ╚═════════════╝


  • Thread communication is via STM based state.
  • Outbound: threads update STM state.
  • Inbound: threads wait on STM state changing (using retry).
  • These are no queues: there is only the current state, not all change events.

We consider the block fetch logic and the policy for the block fetch protocol client together as one unit of functionality. This is the shaded area in the diagram.

Looking at the diagram we see that these two threads interact with each other and other threads via the following shared state

Candidate chains (headers)ReadExternal
Current chain (blocks)ReadExternal
Set of downloaded blocksRead & WriteExternal
Block fetch requestsRead & WriteInternal

The block fetch requests state is private between the block fetch logic and the block fetch protocol client, so it is implemented here.

The other state is managed by the consensus layer and is considered external here. So here we define interfaces for interacting with the external state. These have to be provided when instantiating the block fetch logic.



blockFetchLogic ∷ ∀ peer header block m. (HasHeader header, HasHeader block, HeaderHash header ~ HeaderHash block, MonadDelay m, MonadMonotonicTime m, MonadSTM m, Ord peer, Hashable peer) ⇒ Tracer m [TraceLabelPeer peer (FetchDecision [Point header])] → Tracer m (TraceLabelPeer peer (TraceFetchClientState header)) → BlockFetchConsensusInterface peer header block m → FetchClientRegistry peer header block m → BlockFetchConfiguration → m Void Source #

Execute the block fetch logic. It monitors the current chain and candidate chains. It decided which block bodies to fetch and manages the process of fetching them, including making alternative decisions based on timeouts and failures.

This runs forever and should be shut down using mechanisms such as async.

data BlockFetchConfiguration Source #

Configuration for FetchDecisionPolicy. Should be determined by external local node config.




data BlockFetchConsensusInterface peer header block m Source #

The consensus layer functionality that the block fetch logic requires.

These are provided as input to the block fetch by the consensus layer.




  • readCandidateChains ∷ STM m (Map peer (AnchoredFragment header))

    Read the K-suffixes of the candidate chains.

    Assumptions: * They must be already validated. * They may contain fewer than K blocks. * Their anchor does not have to intersect with the current chain.

  • readCurrentChain ∷ STM m (AnchoredFragment header)

    Read the K-suffix of the current chain.

    This must contain info on the last K blocks (unless we're near the chain genesis of course).

  • readFetchMode ∷ STM m FetchMode

    Read the current fetch mode that the block fetch logic should use.

    The fetch mode is a dynamic part of the block fetch policy. In FetchModeBulkSync it follows a policy that optimises for expected bandwidth over latency to fetch any particular block, whereas in FetchModeDeadline it follows a policy optimises for the latency to fetch blocks, at the expense of wasting bandwidth.

    This mode should be set so that when the node's current chain is near to "now" it uses the deadline mode, and when it is far away it uses the bulk sync mode.

  • readFetchedBlocks ∷ STM m (Point block → Bool)

    Recent, only within last K

  • mkAddFetchedBlockWhetherReceivingTentativeBlocks → STM m (Point block → block → m ())

    This method allocates an addFetchedBlock function per client. That function and readFetchedBlocks are required to be linked. Upon successful completion of addFetchedBlock it must be the case that readFetchedBlocks reports the block.

  • readFetchedMaxSlotNo ∷ STM m MaxSlotNo

    The highest stored/downloaded slot number.

    This is used to optimise the filtering of fragments in the block fetch logic: when removing already downloaded blocks from a fragment, the filtering (with a linear cost) is stopped as soon as a block has a slot number higher than this slot number, as it cannot have been downloaded anyway.

  • plausibleCandidateChainHasCallStackAnchoredFragment header → AnchoredFragment header → Bool

    Given the current chain, is the given chain plausible as a candidate chain. Classically for Ouroboros this would simply check if the candidate is strictly longer, but for Ouroboros with operational key certificates there are also cases where we would consider a chain of equal length to the current chain.

  • compareCandidateChainsHasCallStackAnchoredFragment header → AnchoredFragment header → Ordering

    Compare two candidate chains and return a preference ordering. This is used as part of selecting which chains to prioritise for downloading block bodies.

  • blockFetchSize ∷ header → SizeInBytes

    Much of the logic for deciding which blocks to download from which peer depends on making estimates based on recent performance metrics. These estimates of course depend on the amount of data we will be downloading.

  • blockMatchesHeader ∷ header → block → Bool

    Given a block header, validate the supposed corresponding block body.

  • headerForgeUTCTimeFromConsensus header → STM m UTCTime

    Calculate when a header's block was forged.

    PRECONDITION: This function will succeed and give a _correct_ result when applied to headers obtained via this interface (ie via Consensus, ie via readCurrentChain or readCandidateChains).

    WARNING: This function may fail or, worse, __give an incorrect result (!!)__ if applied to headers obtained from sources outside of this interface. The FromConsensus newtype wrapper is intended to make it difficult to make that mistake, so please pay that syntactic price and consider its meaning at each call to this function. Relatedly, preserve that argument wrapper as much as possible when deriving ancillary functions/interfaces from this function.

  • blockForgeUTCTimeFromConsensus block → STM m UTCTime

    Calculate when a block was forged.

    PRECONDITION: Same as headerForgeUTCTime.

    WARNING: Same as headerForgeUTCTime.

Tracer types

type FetchDecision result = Either FetchDecline result Source #

Throughout the decision making process we accumulate reasons to decline to fetch any blocks. This type is used to wrap intermediate and final results.

data TraceFetchClientState header Source #

Tracing types for the various events that change the state (i.e. FetchClientStateVars) for a block fetch client.

Note that while these are all state changes, the AddedFetchRequest occurs in the decision thread while the other state changes occur in the block fetch client threads.


AddedFetchRequest (FetchRequest header) (PeerFetchInFlight header) PeerFetchInFlightLimits (PeerFetchStatus header)

The block fetch decision thread has added a new fetch instruction consisting of one or more individual request ranges.

AcknowledgedFetchRequest (FetchRequest header)

Mark the point when the fetch client picks up the request added by the block fetch decision thread. Note that this event can happen fewer times than the AddedFetchRequest due to fetch request merging.

SendFetchRequest (AnchoredFragment header)

Mark the point when fetch request for a fragment is actually sent over the wire.

StartedFetchBatch (ChainRange (Point header)) (PeerFetchInFlight header) PeerFetchInFlightLimits (PeerFetchStatus header)

Mark the start of receiving a streaming batch of blocks. This will be followed by one or more CompletedBlockFetch and a final CompletedFetchBatch.

CompletedBlockFetch (Point header) (PeerFetchInFlight header) PeerFetchInFlightLimits (PeerFetchStatus header) NominalDiffTime SizeInBytes

Mark the completion of of receiving a single block within a streaming batch of blocks.

CompletedFetchBatch (ChainRange (Point header)) (PeerFetchInFlight header) PeerFetchInFlightLimits (PeerFetchStatus header)

Mark the successful end of receiving a streaming batch of blocks

RejectedFetchBatch (ChainRange (Point header)) (PeerFetchInFlight header) PeerFetchInFlightLimits (PeerFetchStatus header)

If the other peer rejects our request then we have this event instead of StartedFetchBatch and CompletedFetchBatch.

ClientTerminating Int

The client is terminating. Log the number of outstanding requests.


Instances details
(StandardHash header, Show header) ⇒ Show (TraceFetchClientState header) Source # 
Instance details

Defined in Ouroboros.Network.BlockFetch.ClientState

data TraceLabelPeer peerid a Source #

A peer label for use in Tracers. This annotates tracer output as being associated with a given peer identifier.


TraceLabelPeer peerid a 


Instances details
Functor (TraceLabelPeer peerid) 
Instance details

Defined in Network.Mux.Trace


fmap ∷ (a → b) → TraceLabelPeer peerid a → TraceLabelPeer peerid b Source #

(<$) ∷ a → TraceLabelPeer peerid b → TraceLabelPeer peerid a Source #

(Eq peerid, Eq a) ⇒ Eq (TraceLabelPeer peerid a) 
Instance details

Defined in Network.Mux.Trace


(==)TraceLabelPeer peerid a → TraceLabelPeer peerid a → Bool Source #

(/=)TraceLabelPeer peerid a → TraceLabelPeer peerid a → Bool Source #

(Show peerid, Show a) ⇒ Show (TraceLabelPeer peerid a) 
Instance details

Defined in Network.Mux.Trace


showsPrecIntTraceLabelPeer peerid a → ShowS Source #

showTraceLabelPeer peerid a → String Source #

showList ∷ [TraceLabelPeer peerid a] → ShowS Source #

The FetchClientRegistry

data FetchClientRegistry peer header block m Source #

A registry for the threads that are executing the client side of the BlockFetch protocol to communicate with our peers.

The registry contains the shared variables we use to communicate with these threads, both to track their status and to provide instructions.

The threads add/remove themselves to/from this registry when they start up and shut down.

newFetchClientRegistry ∷ MonadSTM m ⇒ m (FetchClientRegistry peer header block m) Source #

bracketFetchClient ∷ ∀ m a peer header block. (MonadThrow m, MonadSTM m, MonadFork m, MonadMask m, Ord peer) ⇒ FetchClientRegistry peer header block m → NodeToNodeVersion → peer → (FetchClientContext header block m → m a) → m a Source #

This is needed to start a block fetch client. It provides the required FetchClientContext. It registers and unregisters the fetch client on start and end.

It also manages synchronisation with the corresponding chain sync client.

bracketSyncWithFetchClient ∷ ∀ m a peer header block. (MonadThrow m, MonadSTM m, MonadFork m, Ord peer) ⇒ FetchClientRegistry peer header block m → peer → m a → m a Source #

The block fetch and chain sync clients for each peer need to synchronise their startup and shutdown. This bracket operation provides that synchronisation for the chain sync client.

This must be used for the chain sync client outside of its own state registration and deregistration.

bracketKeepAliveClient ∷ ∀ m a peer header block. (MonadThrow m, MonadSTM m, MonadFork m, MonadMask m, Ord peer) ⇒ FetchClientRegistry peer header block m → peer → (StrictTVar m (Map peer PeerGSV) → m a) → m a Source #

Re-export types used by BlockFetchConsensusInterface

data FetchMode Source #



Use this mode when we are catching up on the chain but are stil well behind. In this mode the fetch logic will optimise for throughput rather than latency.


Use this mode for block-producing nodes that have a known deadline to produce a block and need to get the best chain before that. In this mode the fetch logic will optimise for picking the best chain within the given deadline.


Instances details
Eq FetchMode Source # 
Instance details

Defined in Ouroboros.Network.BlockFetch.Decision

Show FetchMode Source # 
Instance details

Defined in Ouroboros.Network.BlockFetch.Decision

newtype FromConsensus a Source #

A new type used to emphasize the precondition of headerForgeUTCTime and blockForgeUTCTime at each call site.

At time of writing, the a is either a header or a block. The headers are literally from Consensus (ie provided by ChainSync). Blocks, on the other hand, are indirectly from Consensus: they were fetched only because we favored the corresponding header that Consensus provided.

NOTE: We define it here so that it can be used consistently throughout the implementation; definiting it only in BlockFetchConsensusInterface would be too late.





Instances details
Functor FromConsensus Source # 
Instance details

Defined in Ouroboros.Network.BlockFetch.ClientState


fmap ∷ (a → b) → FromConsensus a → FromConsensus b Source #

(<$) ∷ a → FromConsensus b → FromConsensus a Source #

Applicative FromConsensus Source # 
Instance details

Defined in Ouroboros.Network.BlockFetch.ClientState

data WhetherReceivingTentativeBlocks Source #

Whether the block fetch peer is sending tentative blocks, which are understood to possibly be invalid