ouroboros-consensus
Safe HaskellNone
LanguageHaskell2010

Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements

Description

The Leios node must relay EbAnnouncements promptly. CIP-0164 is designed around the idea that an EbAnnouncement at an honest stake pool will have propagated to all other honest stake pools within L_hdr, and suggests a value of 1 second. On a network that spans the globe, that's a very tight window. But each EbAnnouncement is slightly less than 1 kB, so it does seem plausible.

In the current design of CIP-0164, the existing Praos header (aka RbHeader) was extended with new fields. One of those fields is an optional tuple: EbBody hash and EbBody size. That's the announcement. As part of the RbHeader, it is adjacent to the election proof that justifies the EbAnnouncement and it is signed by the electee. Because that election proof necessarily includes the slot of the election, every EbAnnouncement has an age. In particular, that age is used to evict too-old announcements so that the existing stochastic bound on the number of elections younger than some age also bounds the number of in-memory EbAnnouncements: zero (no announcement), one (unequivocal announcement), or two (equivocal announcements) per sufficiently-young election.

The LeiosNotify mini protocol in CIP-0164 already includes a notification MsgLeiosAnnouncement, whose payload is the RbHeader. It is sent as one of the possible responses to the generic MsgLeiosNotificationRequestNext message. The healthy honest node tries to maintain ~hundreds of those requests outstanding at all times, so that the upstream peer can always enqueue a notification immediately. The intended timeline one a single connection from an honest node X to an honest node Y is as follows.

  • X either receives or itself issues a new valid EbAnnouncement.
  • If that's the first or second announcement X has seen for that election, then X tries to relay that announcement to its downstream peers, including Y.
  • X will be able to send to Y, because X should have received at least one more MsgLeiosNotificationRequestNext message from Y than X has already replied to.

TO BE IMPORTED QUALIFIED

Synopsis

Documentation

inSlot ∷ SlotNo → State anc → [anc] Source #

Everything this peer has announced for elections in the given slot.

ElectionId orders slot-first, so those elections are a contiguous range. An endorser block's own slot is its election's slot, so this is what an offer of that endorser block has to be backed by.

insert ∷ Eq anc ⇒ ElectionId → anc → State anc → Either (Error invalidity) (State anc) Source #

Fails if this election was already TwoAnnouncements or if this announcement was already received

prune ∷ SlotNo → State anc → ([anc], State anc) Source #

Called whenever the ChainDB's immutable tip advances to a new slot. Also returns the announcements it forgets.

NOTE this pruning should happen ~60 s after the immutable tip advances. That accommodates clock skew, transmission time, etc with only an insignificant increase in the stochastic bound on election count

data Error invalidity Source #

Behaviors of a LeiosNotify upstream peer's announcement stream that an honest node rejects

Constructors

ErrRepeat

The peer had already sent this same announcement before

ErrThird

The peer had already sent two announcements for this election

ErrInvalid !invalidity

This announcement is invalid

ErrTooOld

This announcement's election is too old (its wall-clock age exceeds what a client tolerates from an upstream peer). Unlike ErrInvalid, this verdict depends on the wall clock rather than on the announcement itself.

Instances

Instances details
Show invalidity ⇒ Show (Error invalidity) Source # 
Instance details

Defined in Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements

Methods

showsPrec ∷ Int → Error invalidity → ShowS #

show ∷ Error invalidity → String #

showList ∷ [Error invalidity] → ShowS #

data SeenAnnouncements anc Source #

The announcements the peer has sent for one election

Constructors

OneAnnouncement !anc

The peer has sent one announcement

INVARIANT: has valid signature and election proof

TwoAnnouncements !anc !anc

The peer has sent two announcements

INVARIANT: the left announcement was received first

INVARIANT: both have valid signature and election proof

INVARIANT: they are different announcements

Instances

Instances details
Foldable SeenAnnouncements Source # 
Instance details

Defined in Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements

Methods

fold ∷ Monoid m ⇒ SeenAnnouncements m → m #

foldMap ∷ Monoid m ⇒ (a → m) → SeenAnnouncements a → m #

foldMap' ∷ Monoid m ⇒ (a → m) → SeenAnnouncements a → m #

foldr ∷ (a → b → b) → b → SeenAnnouncements a → b #

foldr' ∷ (a → b → b) → b → SeenAnnouncements a → b #

foldl ∷ (b → a → b) → b → SeenAnnouncements a → b #

foldl' ∷ (b → a → b) → b → SeenAnnouncements a → b #

foldr1 ∷ (a → a → a) → SeenAnnouncements a → a #

foldl1 ∷ (a → a → a) → SeenAnnouncements a → a #

toList ∷ SeenAnnouncements a → [a] #

null ∷ SeenAnnouncements a → Bool #

length ∷ SeenAnnouncements a → Int #

elem ∷ Eq a ⇒ a → SeenAnnouncements a → Bool #

maximum ∷ Ord a ⇒ SeenAnnouncements a → a #

minimum ∷ Ord a ⇒ SeenAnnouncements a → a #

sum ∷ Num a ⇒ SeenAnnouncements a → a #

product ∷ Num a ⇒ SeenAnnouncements a → a #

Generic (SeenAnnouncements anc) Source # 
Instance details

Defined in Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements

Associated Types

type Rep (SeenAnnouncements anc) 
Instance details

Defined in Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements

type Rep (SeenAnnouncements anc) = D1 ('MetaData "SeenAnnouncements" "Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements" "ouroboros-consensus-5.0.0.0-inplace" 'False) (C1 ('MetaCons "OneAnnouncement" 'PrefixI 'False) (S1 ('MetaSel ('Nothing ∷ Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 anc)) :+: C1 ('MetaCons "TwoAnnouncements" 'PrefixI 'False) (S1 ('MetaSel ('Nothing ∷ Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 anc) :*: S1 ('MetaSel ('Nothing ∷ Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 anc)))

Methods

from ∷ SeenAnnouncements anc → Rep (SeenAnnouncements anc) x #

to ∷ Rep (SeenAnnouncements anc) x → SeenAnnouncements anc #

NoThunks anc ⇒ NoThunks (SeenAnnouncements anc) Source # 
Instance details

Defined in Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements

type Rep (SeenAnnouncements anc) Source # 
Instance details

Defined in Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements

type Rep (SeenAnnouncements anc) = D1 ('MetaData "SeenAnnouncements" "Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements" "ouroboros-consensus-5.0.0.0-inplace" 'False) (C1 ('MetaCons "OneAnnouncement" 'PrefixI 'False) (S1 ('MetaSel ('Nothing ∷ Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 anc)) :+: C1 ('MetaCons "TwoAnnouncements" 'PrefixI 'False) (S1 ('MetaSel ('Nothing ∷ Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 anc) :*: S1 ('MetaSel ('Nothing ∷ Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 anc)))

newtype State anc Source #

What a single LeiosNotify upstream peer has announced, per election: the announcements part of the client's per-peer state

Constructors

MkState 

Instances

Instances details
Generic (State anc) Source # 
Instance details

Defined in Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements

Associated Types

type Rep (State anc) 
Instance details

Defined in Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements

type Rep (State anc) = D1 ('MetaData "State" "Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements" "ouroboros-consensus-5.0.0.0-inplace" 'True) (C1 ('MetaCons "MkState" 'PrefixI 'True) (S1 ('MetaSel ('Just "live") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Map ElectionId (SeenAnnouncements anc)))))

Methods

from ∷ State anc → Rep (State anc) x #

to ∷ Rep (State anc) x → State anc #

NoThunks anc ⇒ NoThunks (State anc) Source # 
Instance details

Defined in Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements

type Rep (State anc) Source # 
Instance details

Defined in Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements

type Rep (State anc) = D1 ('MetaData "State" "Ouroboros.Consensus.MiniProtocol.LeiosNotify.Client.Announcements" "ouroboros-consensus-5.0.0.0-inplace" 'True) (C1 ('MetaCons "MkState" 'PrefixI 'True) (S1 ('MetaSel ('Just "live") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Map ElectionId (SeenAnnouncements anc)))))