ouroboros-network-api
Safe HaskellNone
LanguageHaskell2010

Ouroboros.Network.BlockFetch.ConsensusInterface

Synopsis

Documentation

data PraosFetchMode Source #

Constructors

FetchModeBulkSync

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.

FetchModeDeadline

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.

data FetchMode Source #

The fetch mode that the block fetch logic should use.

data BlockFetchConsensusInterface peer header block (m :: Type -> Type) Source #

The consensus layer functionality that the block fetch logic requires.

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

Constructors

BlockFetchConsensusInterface 

Fields

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

    Read the K-suffixes of the candidate chains.

    Assumptions: * Their headers 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.

    FetchModeGenesis should be used when the genesis node is syncing to ensure it isn't leashed.

    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

  • mkAddFetchedBlock :: 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.

  • plausibleCandidateChain :: HasCallStack => AnchoredFragment 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.

  • compareCandidateChains :: HasCallStack => AnchoredFragment 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.

  • headerForgeUTCTime :: FromConsensus 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.

  • readChainSelStarvation :: STM m ChainSelStarvation

    Information on the ChainSel starvation status; whether it is ongoing or has ended recently. Needed by the bulk sync decision logic.

  • demoteChainSyncJumpingDynamo :: peer -> m ()

    Action to inform CSJ (ChainSync Jumping) that the given peer has not been performing adequately with respect to BlockFetch, and that it should be demoted from the dynamo role. Can be set to const (pure ()) in all other scenarios.

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.

Constructors

FromConsensus 

Fields

data ChainSelStarvation Source #

Whether ChainSel is starved or has been recently.

The bulk sync fetch decision logic needs to decide whether the current focused peer has starved ChainSel recently. This datatype is used to represent this piece of information.

Instances

Instances details
Generic ChainSelStarvation Source # 
Instance details

Defined in Ouroboros.Network.BlockFetch.ConsensusInterface

Associated Types

type Rep ChainSelStarvation 
Instance details

Defined in Ouroboros.Network.BlockFetch.ConsensusInterface

type Rep ChainSelStarvation = D1 ('MetaData "ChainSelStarvation" "Ouroboros.Network.BlockFetch.ConsensusInterface" "ouroboros-network-api-0.11.0.0-inplace" 'False) (C1 ('MetaCons "ChainSelStarvationOngoing" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "ChainSelStarvationEndedAt" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Time)))
Show ChainSelStarvation Source # 
Instance details

Defined in Ouroboros.Network.BlockFetch.ConsensusInterface

Eq ChainSelStarvation Source # 
Instance details

Defined in Ouroboros.Network.BlockFetch.ConsensusInterface

NoThunks ChainSelStarvation Source # 
Instance details

Defined in Ouroboros.Network.BlockFetch.ConsensusInterface

type Rep ChainSelStarvation Source # 
Instance details

Defined in Ouroboros.Network.BlockFetch.ConsensusInterface

type Rep ChainSelStarvation = D1 ('MetaData "ChainSelStarvation" "Ouroboros.Network.BlockFetch.ConsensusInterface" "ouroboros-network-api-0.11.0.0-inplace" 'False) (C1 ('MetaCons "ChainSelStarvationOngoing" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "ChainSelStarvationEndedAt" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Time)))

mkReadFetchMode Source #

Arguments

:: Functor m 
=> ConsensusMode 
-> m LedgerStateJudgement

Used for GenesisMode.

-> m PraosFetchMode

Used for PraosMode for backwards compatibility.

-> m FetchMode 

Construct readFetchMode for BlockFetchConsensusInterface by branching on the ConsensusMode.