| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Ouroboros.Consensus.Peras.Voting.View
Description
Pure Peras voting rules
This module implements some machinery to abstract away the impure inputs needed to evaluate the Peras voting rules in a pure fashion.
NOTE: most of the code in this module returns values over PerasEnabled to
reflect the fact that some of the computations performed here require
querying a hard fork summary to map timestamps and slot numbers to their
corresponding Peras round numbers. This may not be possible if Peras was not
enabled at the relevant points in time, and such a case should be handled
appropriately by the caller.
Synopsis
- data PerasQryException
- data PerasQry (xs ∷ [Type]) a
- runPerasQry ∷ ∀ (xs ∷ [Type]) a. Summary xs → PerasQry xs a → Either PerasQryException a
- perasRoundStart ∷ ∀ (xs ∷ [Type]). PerasRoundNo → PerasQry xs SlotNo
- perasChainAtCandidateBlock ∷ ∀ blk (xs ∷ [Type]). GetHeader blk ⇒ PerasBlockMinSlots → PerasRoundNo → AnchoredFragment (Header blk) → PerasQry xs (AnchoredFragment (Header blk))
- data LatestCertSeenView cert = LatestCertSeenView {}
- data PerasVotingView cert blk = PerasVotingView {
- perasParams ∷ !(PerasParams blk)
- currRoundNo ∷ !PerasRoundNo
- latestCertSeen ∷ !(WithOrigin (LatestCertSeenView cert))
- latestCertOnChainRound ∷ !(WithOrigin PerasRoundNo)
- candidateBlock ∷ Point blk
- data WithBoostedBlockStatus cert
- mkPerasVotingView ∷ ∀ cert blk (xs ∷ [Type]). (cert ~ WithArrivalTime (ValidatedPerasCert blk), GetHeader blk, IsPerasCert (PerasCert blk) blk) ⇒ PerasParams blk → PerasRoundNo → WithOrigin (WithBoostedBlockStatus cert) → WithOrigin PerasRoundNo → AnchoredFragment (Header blk) → PerasQry xs (PerasVotingView cert blk)
- newtype PerasVotingViewHandle (m ∷ Type → Type) blk = PerasVotingViewHandle (PerasRoundNo → STM m (PerasVotingView (WithArrivalTime (ValidatedPerasCert blk)) blk))
Documentation
data PerasQryException Source #
Exceptions thrown when querying Peras-related historical information
Constructors
| PerasQryExceptionPastHorizon PastHorizonException | The hard fork summary does not cover the needed point in time. |
| PerasQryExceptionPerasDisabled | Peras is not enabled at the needed point in time. |
Instances
| Exception PerasQryException Source # | |
| Show PerasQryException Source # | |
Defined in Ouroboros.Consensus.Peras.Voting.View Methods showsPrec ∷ Int → PerasQryException → ShowS # show ∷ PerasQryException → String # showList ∷ [PerasQryException] → ShowS # | |
data PerasQry (xs ∷ [Type]) a Source #
Monad for querying Peras-related information from a hard fork summary.
This covers two possible error cases: 1. the hard fork summary does not cover the needed point in time, or 2. Peras is not enabled at the needed point in time.
runPerasQry ∷ ∀ (xs ∷ [Type]) a. Summary xs → PerasQry xs a → Either PerasQryException a Source #
Run a PerasQry against a hard fork summary
perasRoundStart ∷ ∀ (xs ∷ [Type]). PerasRoundNo → PerasQry xs SlotNo Source #
Slot number at the start of a Peras round
perasChainAtCandidateBlock ∷ ∀ blk (xs ∷ [Type]). GetHeader blk ⇒ PerasBlockMinSlots → PerasRoundNo → AnchoredFragment (Header blk) → PerasQry xs (AnchoredFragment (Header blk)) Source #
Chain prefix leading to the candidate block.
This corresponds to the last block before the candidate slot horizon,
defined as the slot that is at least blockMinSlots (L) old from the start
of the current round.
NOTE: this is where the candidate is determined according to CIP-0140. This function may evolve in the future if the candidate block selection becomes more complex.
data LatestCertSeenView cert Source #
View of the latest certificate seen by the voter.
NOTE: the voting rules depend on the candidate block indirectly. This is
reflected in the fact that the voting view does not contain the candidate
block or its point, but only whether the candidate block extends the block
boosted by the most recent certificate seen by the voter, which is provided
to the rules via lcsCandidateBlockExtendsCert here.
Constructors
| LatestCertSeenView | |
Fields
| |
Instances
| Show cert ⇒ Show (LatestCertSeenView cert) Source # | |
Defined in Ouroboros.Consensus.Peras.Voting.View Methods showsPrec ∷ Int → LatestCertSeenView cert → ShowS # show ∷ LatestCertSeenView cert → String # showList ∷ [LatestCertSeenView cert] → ShowS # | |
data PerasVotingView cert blk Source #
Interface needed to evaluate the Peras voting rules
NOTE: the voting rules depend on the candidate block only indirectly. The
only reason to include the point of the block being voted for
(candidateBlock) here is to be able to return it as part of the result of
isPerasVotingAllowed in the positive case.
Constructors
| PerasVotingView | |
Fields
| |
Instances
| (StandardHash blk, Show cert) ⇒ Show (PerasVotingView cert blk) Source # | |
Defined in Ouroboros.Consensus.Peras.Voting.View Methods showsPrec ∷ Int → PerasVotingView cert blk → ShowS # show ∷ PerasVotingView cert blk → String # showList ∷ [PerasVotingView cert blk] → ShowS # | |
data WithBoostedBlockStatus cert Source #
Indicate whether the block being boosted by a certificate is expected to still be part of the volatile chain suffix or not.
This is relevant for Peras voting because we need to know if a candidate block extends the chain that contains the block being boosted by the latest certificate seen. For this purpose, we want to limit the voting rules to only look within the volatile chain suffix, and assume that, if the boosted block is no longer in the volatile suffix, then it trivially extends the candidate block (because it must have been copied into the immutable chain prefix). For this reason, we need to manually keep track of whether the boosted block of this certificate has already been garbage collected from the volatile suffix or not.
Constructors
| CertBoostingBlockInVolatileDB cert | Certificate boosting a block within the volatile chain suffix |
| CertBoostingBlockNoLongerInVolatileDB cert | Certificate boosting a block that no longer belongs to the volatile chain suffix. This typically means that the block has been copied to the immutable prefix, and then garbage collected from the volatile suffix. |
Instances
Arguments
| ∷ ∀ cert blk (xs ∷ [Type]). (cert ~ WithArrivalTime (ValidatedPerasCert blk), GetHeader blk, IsPerasCert (PerasCert blk) blk) | |
| ⇒ PerasParams blk | Peras protocol parameters |
| → PerasRoundNo | Current Peras round number |
| → WithOrigin (WithBoostedBlockStatus cert) | Most recent certificate seen by the voter |
| → WithOrigin PerasRoundNo |
|
| → AnchoredFragment (Header blk) | Prefix leading to the candidate block in the volatile suffix of our preferred chain |
| → PerasQry xs (PerasVotingView cert blk) | Constructed voting view |
Construct a PerasVotingView.
NOTE: this assumes that the client code computes all the needed inputs within the same STM transaction, or the results may be inconsistent.
newtype PerasVotingViewHandle (m ∷ Type → Type) blk Source #
Handle for querying the Peras voting view via STM.
Constructors
| PerasVotingViewHandle (PerasRoundNo → STM m (PerasVotingView (WithArrivalTime (ValidatedPerasCert blk)) blk)) |