Fields

• addBlockAsync ∷ InvalidBlockPunishment m → blk → m (AddBlockPromise m blk)

  Add a block to the heap of blocks

  We do not assume that the block is valid (under the legder rules); it is the responsibility of the Chain DB itself to only select chains that are valid.

  Conversely, the caller cannot assume that the new block will be added to the current chain; even if the block is valid, it will not become part of the chain if there are other chains available that are preferred by the consensus algorithm (typically, longer chains).

  This function typically returns immediately, yielding a AddBlockPromise which can be used to wait for the result. You can use addBlock to add the block synchronously.

  NOTE: back pressure can be applied when overloaded.

  PRECONDITON: the block to be added must not be from the future.

  The current code ensures that the two sources of blocks (ChainSync and forging) do not allow blocks from the future, however this is not guaranteed when during initialization if the VolatileDB contains blocks from the future. See: https://github.com/IntersectMBO/ouroboros-consensus/blob/main/docs/website/contents/for-developers/HandlingBlocksFromTheFuture.md#handling-blocks-from-the-future

• chainSelAsync ∷ m (ChainSelectionPromise m)

  Trigger reprocessing of blocks postponed by the LoE.

• getCurrentChain ∷ STM m (AnchoredFragment (Header blk))

  Get the current chain fragment

  Suppose the current chain is

  a -> b -> c -> d -> e -> f

  and suppose k = 2; this means that the most distant fork we can switch to is something like

  a -> b -> c -> d -> e' -> f'

  The fragment we return will be [e, f], anchored at d. In other words, the length of the fragment will under normal circumstances be exactly k blocks long. It may be shorter if

  • We are near genesis The anchor will be the genesis point (which does not correspond to an actual block)
  • The volatile DB suffered some data loss Typically (but not necessarily) the volatile DB will not be empty and the anchor will be pointing to the tip of the immutable DB.

  POSTCONDITION: The Chain DB will be able to switch to any fork starting from the anchor of the returned fragment or any subsequent block (provided the new fork is at least of the same length as the old).

  NOTE: A direct consequence of this guarantee is that the anchor of the fragment will move as the chain grows.

• getLedgerDB ∷ STM m (LedgerDB' blk)

  Return the LedgerDB containing the last k ledger states.

• getHeaderStateHistory ∷ STM m (HeaderStateHistory blk)

  Get a HeaderStateHistory populated with the HeaderStates and slot times of the last k blocks of the current chain.

• getTipBlock ∷ m (Maybe blk)

  Get block at the tip of the chain, if one exists

  Returns Nothing if the database is empty.

• getTipHeader ∷ m (Maybe (Header blk))

  Get header at the tip of the chain

  NOTE: Calling getTipHeader is cheaper than getTipBlock and then extracting the header: most of the time the header at the tip is actually in memory, whereas the block never is.

  Returns Nothing if the database is empty.

• getTipPoint ∷ STM m (Point blk)

  Get point of the tip of the chain

  Will return genesisPoint if the database is empty; if the current chain fragment is empty due to data loss in the volatile DB, getTipPoint will return the tip of the immutable DB.

• getBlockComponent ∷ ∀ b. BlockComponent blk b → RealPoint blk → m (Maybe b)

  Get the given component(s) of the block at the specified point. If there is no block at the given point, Nothing is returned.

• getIsFetched ∷ STM m (Point blk → Bool)

  Return membership check function for recent blocks

  This check is only reliable for blocks up to k away from the tip. For blocks older than that the results should be regarded as non-deterministic.

• getIsValid ∷ STM m (RealPoint blk → Maybe Bool)

  Return a function that tells whether a block is known to be valid or invalid.

  The function will return:

  • Just True: for blocks in the volatile DB that have been validated and were found to be valid. All blocks in the current chain fragment (i.e., getCurrentChain) are valid.
  • Just False: for blocks in the volatile DB that have been validated and were found to be invalid.
  • Nothing: for blocks not or no longer in the volatile DB, whether they are valid or not, including blocks in the immutable DB. Also for blocks in the volatile DB that haven't been validated (yet), e.g., because they are disconnected from the current chain or they are part of a shorter fork.
• getMaxSlotNo ∷ STM m MaxSlotNo

  Get the highest slot number stored in the ChainDB.

  Note that the corresponding block doesn't have to be part of the current chain, it could be part of some fork, or even be a disconnected block.

• stream ∷ ∀ b. ResourceRegistry m → BlockComponent blk b → StreamFrom blk → StreamTo blk → m (Either (UnknownRange blk) (Iterator m blk b))

  Stream blocks

  Streaming is not restricted to the current fork, but there must be an unbroken path from the starting point to the end point /at the time of initialization/ of the iterator. Once the iterator has been initialized, it will not be affected by subsequent calls to addBlock. To track the current chain, use a Follower instead.

  Streaming blocks older than k is permitted, but only when they are part of the current fork (at the time of initialization). Streaming a fork that forks off more than k blocks in the past is not permitted and an UnknownRange error will be returned in that case.

  The iterator does have a limited lifetime, however. The chain DB internally partitions the chain into an " immutable " part and a " volatile " part, moving blocks from the volatile DB to the immutable DB when they become more than k deep into the chain. When a block with slot number n is added to the immutble DB, a time delay t kicks in; after that time delay expires, all blocks older than n may be removed from the volatile DB, /including any blocks that happen to live on other forks/ (since those forks must now, by definition, be too distant). This time delay t also provides a worst-case bound for the lifetime of the iterator: if the iterator traverses a chain that forks off from our current chain at the tip of the immutable DB, then the first block on that fork will become unavailable as soon as another block is pushed to the current chain and the subsequent time delay expires.

  Note: although blocks are moved from the volatile DB to the immutable DB after they have become k deep into the chain, due to data corruption the suffix of the chain in the volatile DB might be shorter than k. The immutable DB always determines the maximum rollback, which may therefore be shorter than k under such circumstances. In addition, streaming blocks which aren't on the current fork is permitted, but the oldest volatile block must fit on to the tip of the immutable DB.

  When the given bounds are nonsensical, an InvalidIteratorRange is thrown.

  When the given bounds are not part of the chain DB, an UnknownRange error is returned.

  To stream all blocks from the current chain, use streamAll, as it correctly handles an empty ChainDB.

• newFollower ∷ ∀ b. ResourceRegistry m → ChainType → BlockComponent blk b → m (Follower m blk b)

  Chain follower

  A chain follower is an iterator that tracks the state of the current chain: calling next on the iterator will either give you the next block header, or (if we have switched to a fork) the instruction to rollback.

  The tracking iterator starts at genesis (see also trackForward).

  This is intended for use by chain consumers to reliably follow a chain, desipite the chain being volatile.

  Examples of users: * The server side of the chain sync mini-protocol for the node-to-node protocol using headers and the block size. * The server side of the chain sync mini-protocol for the node-to-client protocol using blocks.

• getIsInvalidBlock ∷ STM m (WithFingerprint (HeaderHash blk → Maybe (ExtValidationError blk)))

  Function to check whether a block is known to be invalid.

  Blocks unknown to the ChainDB will result in Nothing.

  If the hash corresponds to a block that is known to be invalid, but is now older than k, this function may return Nothing.

  Whenever a new invalid block is added, the Fingerprint will be changed. This is useful when "watching" this function in a transaction.

  Note that when invalid blocks are garbage collected and thus no longer detected by this function, the Fingerprint doesn't have to change, since the function will not detect new invalid blocks.

  It might seem natural to have this function also return whether the ChainDB knows that a block is valid, thereby subsuming the getIsValid function and simplifying the API. However, this adds the overhead of checking whether the block is valid for blocks that are not known to be invalid that does not give useful information to current clients (ChainSync), since they are only interested in whether a block is known to be invalid. The extra information of whether a block is valid is only used for testing.

  In particular, this affects the watcher in bracketChainSyncClient, which rechecks the blocks in all candidate chains whenever a new invalid block is detected. These blocks are likely to be valid.

• closeDB ∷ m ()
   
• isOpen ∷ STM m Bool

  Return True when the database is open.

  False when the database is closed.

Fields

• blockWrittenToDisk ∷ STM m Bool

  Use this STM transaction to wait until the block has been written to disk.

  Returns True when the block was written to disk or False when it was ignored, e.g., because it was older than k.

  If the STM transaction has returned True then getIsFetched will return True for the added block.

  NOTE: Even when the result is False, getIsFetched might still return True, e.g., the block was older than k, but it has been downloaded and stored on disk before.

• blockProcessed ∷ STM m (AddBlockResult blk)

  Use this STM transaction to wait until the block has been processed: the block has been written to disk and chain selection has been performed for the block, unless the block is from the future.

  The ChainDB's tip after chain selection is returned. When this tip doesn't match the added block, it doesn't necessarily mean the block wasn't adopted. We might have adopted a longer chain of which the added block is a part, but not the tip.

  It returns FailedToAddBlock if the thread adding the block died.

  NOTE: When the block is from the future, chain selection for the block won't be performed until the block is no longer in the future, which might take some time. For that reason, this transaction will not wait for chain selection of a block from the future. It will return the current tip of the ChainDB after writing the block to disk.

Fields

• waitChainSelectionPromise ∷ m ()
   

Fields

• withoutPoint ∷ !b
   
• point ∷ !(Point blk)
   

Fields

• iteratorNext ∷ m (IteratorResult blk b)
   
• iteratorClose ∷ m ()

  When fmap-ing or traverse-ing (or using traverseIterator) an Iterator, the resulting iterator will still refer to and use the original one. This means that when either of them is closed, both will be closed in practice.

Fields

• followerInstruction ∷ m (Maybe (ChainUpdate blk a))

  The next chain update (if one exists)

  The AddBlock instruction (see ChainUpdate) indicates that, to follow the current chain, the follower should extend its chain with the given block component (which will be a value of type a).

  The RollBack instruction indicates that the follower should perform a rollback by first backtracking to a certain point.

  If a follower should switch to a fork, then it will first receive a RollBack instruction followed by as many AddBlock as necessary to reach the tip of the new chain.

  When the follower's (implicit) position is in the immutable part of the chain, no rollback instructions will be encountered.

  Not in STM because might have to read the blocks or headers from disk.

  We may roll back more than k, but only in case of data loss.

• followerInstructionBlocking ∷ m (ChainUpdate blk a)

  Blocking version of followerInstruction

• followerForward ∷ [Point blk] → m (Maybe (Point blk))

  Move the follower forward

  Must be given a list of points in order of preference; the iterator will move forward to the first point on the list that is on the current chain. Returns Nothing if the iterator did not move, or the new point otherwise.

  When successful, the first call to followerInstruction after followerForward will be a RollBack to the point returned by followerForward.

  Cannot live in STM because the points specified might live in the immutable DB.

• followerClose ∷ m ()

  Close the follower.

  Idempotent.

  After closing, all other operations on the follower will throw ClosedFollowerError.