Safe Haskell	None
Language	Haskell2010

Ouroboros.Consensus.Peras.Cert.Inclusion

Description

This module defines the logic needed to evaluate when a Peras certificate must be included in a block.

NOTE: in this file, we use uncommon variable names such as _A because that is their name in the CIP-0140, and we can't have variable names starting with capital letters. Contrary to typical Haskell conventions, those do not denote ignored variables.

Synopsis

data LatestCertSeenView cert = LatestCertSeenView {
- lcsCert ∷ !cert
- lcsCertRound ∷ !PerasRoundNo
}
data LatestCertOnChainView cert = LatestCertOnChainView {
- lcocRoundNo ∷ !PerasRoundNo
}
data PerasCertInclusionView cert blk = PerasCertInclusionView {
- perasParams ∷ !PerasParams
- currRoundNo ∷ !PerasRoundNo
- latestCertSeen ∷ !(LatestCertSeenView cert)
- latestCertOnChain ∷ !(WithOrigin (LatestCertOnChainView cert))
- certSnapshot ∷ !(PerasCertSnapshot blk)
}
mkPerasCertInclusionView ∷ HasPerasCertRound cert ⇒ PerasParams → PerasRoundNo → WithOrigin cert → WithOrigin PerasRoundNo → PerasCertSnapshot blk → Maybe (PerasCertInclusionView cert blk)
data PerasCertInclusionRule
data PerasCertInclusionRulesDecision cert
- = IncludeCert (Evidence 'True PerasCertInclusionRule) cert
- | DoNotIncludeCert (Evidence 'False PerasCertInclusionRule)
needCert ∷ PerasCertInclusionView cert blk → PerasCertInclusionRulesDecision cert
noCertsFromTwoRoundsAgo ∷ PerasCertInclusionView cert blk → Pred PerasCertInclusionRule
needCertRules ∷ PerasCertInclusionView cert blk → Pred PerasCertInclusionRule

Documentation

data LatestCertSeenView cert Source #

View of the latest certificate seen by the voter

Constructors

LatestCertSeenView
Fields lcsCert ∷ !cert Latest certificate seen by the voter lcsCertRound ∷ !PerasRoundNo Round number of the latest certificate seen by the voter

Instances

Instances details

Show cert ⇒ Show (LatestCertSeenView cert) Source #
Instance details Defined in Ouroboros.Consensus.Peras.Cert.Inclusion Methods showsPrec ∷ Int → LatestCertSeenView cert → ShowS # show ∷ LatestCertSeenView cert → String # showList ∷ [LatestCertSeenView cert] → ShowS #

data LatestCertOnChainView cert Source #

View of the latest certificate present in our preferred chain

Constructors

LatestCertOnChainView
Fields lcocRoundNo ∷ !PerasRoundNo Round number of the latest certificate present in our preferred chain

Instances

Instances details

Show (LatestCertOnChainView cert) Source #
Instance details Defined in Ouroboros.Consensus.Peras.Cert.Inclusion Methods showsPrec ∷ Int → LatestCertOnChainView cert → ShowS # show ∷ LatestCertOnChainView cert → String # showList ∷ [LatestCertOnChainView cert] → ShowS #

data PerasCertInclusionView cert blk Source #

Interface needed to evaluate the Peras cert inclusion rules

Constructors

PerasCertInclusionView

Fields

perasParams ∷ !PerasParams
Peras protocol parameters
currRoundNo ∷ !PerasRoundNo
The current Peras round number
latestCertSeen ∷ !(LatestCertSeenView cert)
The latest certificate seen by the voter
latestCertOnChain ∷ !(WithOrigin (LatestCertOnChainView cert))
The most recent certificate present in our preferred chain
certSnapshot ∷ !(PerasCertSnapshot blk)
A snapshot of the certificates we have in our database

Instances

Instances details

Show cert ⇒ Show (PerasCertInclusionView cert blk) Source #
Instance details Defined in Ouroboros.Consensus.Peras.Cert.Inclusion Methods showsPrec ∷ Int → PerasCertInclusionView cert blk → ShowS # show ∷ PerasCertInclusionView cert blk → String # showList ∷ [PerasCertInclusionView cert blk] → ShowS #

mkPerasCertInclusionView Source #

Arguments

∷ HasPerasCertRound cert
⇒ PerasParams	Peras protocol parameters
→ PerasRoundNo	Current Peras round number
→ WithOrigin cert	Most recent certificate seen by the voter
→ WithOrigin PerasRoundNo	Round number of the latest certificate present in our preferred chain
→ PerasCertSnapshot blk	Snapshot of the certificates we have in our database
→ Maybe (PerasCertInclusionView cert blk)	Constructed certificate inclusion view

Construct a PerasCertInclusionView from the given inputs.

Returns Nothing if we are trying to construct the view without having a latest certificate seen, which is a precondition to being able to include it in the block we are building.

NOTE: this assumes that the client code computes all the needed inputs within the same STM transaction, or the results may be inconsistent.

data PerasCertInclusionRule Source #

Certificate inclusion rules.

Each constructor corresponds to one of the members in the conjunction defined in needCert per CIP-0140.

Constructors

NoCertsFromTwoRoundsAgo
Fields PerasRoundNo The current round number
LatestCertSeenIsNotExpired
Fields PerasRoundNo The round number of the latest certificate seen by the voter
LatestCertSeenIsNewerThanLatestCertOnChain
Fields PerasRoundNo The round number of the latest certificate seen by the voter (WithOrigin PerasRoundNo) The round number of the latest certificate present in our preferred chain, if it exists

Instances

Instances details

Show PerasCertInclusionRule Source #
Instance details Defined in Ouroboros.Consensus.Peras.Cert.Inclusion Methods showsPrec ∷ Int → PerasCertInclusionRule → ShowS # show ∷ PerasCertInclusionRule → String # showList ∷ [PerasCertInclusionRule] → ShowS #
Eq PerasCertInclusionRule Source #
Instance details Defined in Ouroboros.Consensus.Peras.Cert.Inclusion Methods (==) ∷ PerasCertInclusionRule → PerasCertInclusionRule → Bool # (/=) ∷ PerasCertInclusionRule → PerasCertInclusionRule → Bool #
Explainable PerasCertInclusionRule Source #
Instance details Defined in Ouroboros.Consensus.Peras.Cert.Inclusion Methods explain ∷ ExplanationMode → PerasCertInclusionRule → String Source # explainPrec ∷ Int → ExplanationMode → PerasCertInclusionRule → String Source #

data PerasCertInclusionRulesDecision cert Source #

Whether we are expected to add a certificate to the block we are building according to the inclusion rules.

These rules are taken as verbatim as possible from the Peras CIP-0140: https://github.com/cardano-foundation/CIPs/blob/master/CIP-0140/README.md#block-creation

This type additionally carries the evidence for the decision taken.

Constructors

IncludeCert (Evidence 'True PerasCertInclusionRule) cert
DoNotIncludeCert (Evidence 'False PerasCertInclusionRule)

Instances

Instances details

Show cert ⇒ Show (PerasCertInclusionRulesDecision cert) Source #
Instance details Defined in Ouroboros.Consensus.Peras.Cert.Inclusion Methods showsPrec ∷ Int → PerasCertInclusionRulesDecision cert → ShowS # show ∷ PerasCertInclusionRulesDecision cert → String # showList ∷ [PerasCertInclusionRulesDecision cert] → ShowS #
HasPerasCertRound cert ⇒ Explainable (PerasCertInclusionRulesDecision cert) Source #
Instance details Defined in Ouroboros.Consensus.Peras.Cert.Inclusion Methods explain ∷ ExplanationMode → PerasCertInclusionRulesDecision cert → String Source # explainPrec ∷ Int → ExplanationMode → PerasCertInclusionRulesDecision cert → String Source #

needCert ∷ PerasCertInclusionView cert blk → PerasCertInclusionRulesDecision cert Source #

Evaluate whether we need to include a certificate in the block we are building.

noCertsFromTwoRoundsAgo ∷ PerasCertInclusionView cert blk → Pred PerasCertInclusionRule Source #

noCertsFromTwoRoundsAgo: we haven't seen a certificate from two rounds ago

needCertRules ∷ PerasCertInclusionView cert blk → Pred PerasCertInclusionRule Source #

We need to include a certificate in the block we are building if all the rules in this conjunction are satisfied.