Safe Haskell	Safe-Inferred
Language	Haskell2010

Ouroboros.Consensus.Node.GSM

Contents

Auxiliaries
Constructors

Description

The Genesis State Machine decides whether the node is caught-up or not.

Synopsis

data CandidateVersusSelection
- = CandidateDoesNotIntersect
- | WhetherCandidateIsBetter !Bool
data DurationFromNow
- = After !NominalDiffTime
- | Already
data GsmEntryPoints m = GsmEntryPoints {
- enterCaughtUp ∷ ∀ neverTerminates. m neverTerminates
- enterPreSyncing ∷ ∀ neverTerminates. m neverTerminates
}
data GsmNodeKernelArgs m blk = GsmNodeKernelArgs {
- gsmAntiThunderingHerd ∷ StdGen
- gsmDurationUntilTooOld ∷ Maybe (WrapDurationUntilTooOld m blk)
- gsmMarkerFileView ∷ MarkerFileView m
- gsmMinCaughtUpDuration ∷ NominalDiffTime
}
data GsmState
- = PreSyncing
- | Syncing
- | CaughtUp
data GsmView m upstreamPeer selection chainSyncState = GsmView {
- antiThunderingHerd ∷ Maybe StdGen
- candidateOverSelection ∷ selection → chainSyncState → CandidateVersusSelection
- peerIsIdle ∷ chainSyncState → Bool
- durationUntilTooOld ∷ Maybe (selection → m DurationFromNow)
- equivalent ∷ selection → selection → Bool
- getChainSyncStates ∷ STM m (Map upstreamPeer (StrictTVar m chainSyncState))
- getCurrentSelection ∷ STM m selection
- minCaughtUpDuration ∷ NominalDiffTime
- setCaughtUpPersistentMark ∷ Bool → m ()
- writeGsmState ∷ GsmState → m ()
- isHaaSatisfied ∷ STM m Bool
}
data MarkerFileView m = MarkerFileView {
- hasMarkerFile ∷ m Bool
- removeMarkerFile ∷ m ()
- touchMarkerFile ∷ m ()
}
newtype WrapDurationUntilTooOld m blk = DurationUntilTooOld {
- getDurationUntilTooOld ∷ WithOrigin SlotNo → m DurationFromNow
}
data TraceGsmEvent selection
- = GsmEventEnterCaughtUp !Int !selection
- | GsmEventLeaveCaughtUp !selection !DurationFromNow
- | GsmEventPreSyncingToSyncing
- | GsmEventSyncingToPreSyncing
gsmStateToLedgerJudgement ∷ GsmState → LedgerStateJudgement
initializationLedgerJudgement ∷ (GetTip (LedgerState blk), Monad m) ⇒ m (LedgerState blk) → Maybe (WrapDurationUntilTooOld m blk) → MarkerFileView m → m LedgerStateJudgement
realDurationUntilTooOld ∷ (HasHardForkHistory blk, MonadSTM m) ⇒ LedgerConfig blk → STM m (LedgerState blk) → NominalDiffTime → SystemTime m → m (WrapDurationUntilTooOld m blk)
realGsmEntryPoints ∷ ∀ m upstreamPeer selection tracedSelection candidate. (MonadDelay m, MonadTimer m) ⇒ (selection → tracedSelection, Tracer m (TraceGsmEvent tracedSelection)) → GsmView m upstreamPeer selection candidate → GsmEntryPoints m
realMarkerFileView ∷ MonadThrow m ⇒ ChainDB m blk → HasFS m h → MarkerFileView m

Documentation

data CandidateVersusSelection Source #

Constructors

CandidateDoesNotIntersect

The GSM assumes that this is ephemeral

For example, the ChainSync client will either disconnect from the peer or update the candidate to one that is not stale. It's also technically possible that the selection is stale, which the ChainDB would also resolve as soon as possible.

WhetherCandidateIsBetter !Bool

Whether the candidate is better than the selection

Instances

Instances details

Show CandidateVersusSelection Source #
Instance details Defined in Ouroboros.Consensus.Node.GSM Methods showsPrec ∷ Int → CandidateVersusSelection → ShowS # show ∷ CandidateVersusSelection → String # showList ∷ [CandidateVersusSelection] → ShowS #
Eq CandidateVersusSelection Source #
Instance details Defined in Ouroboros.Consensus.Node.GSM Methods (==) ∷ CandidateVersusSelection → CandidateVersusSelection → Bool # (/=) ∷ CandidateVersusSelection → CandidateVersusSelection → Bool #

data DurationFromNow Source #

Constructors

After !NominalDiffTime	INVARIANT positive
Already	This value represents all non-positive durations, ie events from the past

Instances

Instances details

Show DurationFromNow Source #
Instance details Defined in Ouroboros.Consensus.Node.GSM Methods showsPrec ∷ Int → DurationFromNow → ShowS # show ∷ DurationFromNow → String # showList ∷ [DurationFromNow] → ShowS #
Eq DurationFromNow Source #
Instance details Defined in Ouroboros.Consensus.Node.GSM Methods (==) ∷ DurationFromNow → DurationFromNow → Bool # (/=) ∷ DurationFromNow → DurationFromNow → Bool #

data GsmEntryPoints m Source #

The two proper GSM entrypoints.

See the BootstrapPeersIER.md document for documentation.

See initializationLedgerJudgement for the Initializing pseudo-state.

Constructors

GsmEntryPoints

Fields

enterCaughtUp ∷ ∀ neverTerminates. m neverTerminates
ASSUMPTION the marker file is present on disk, a la setCaughtUpPersistentMark True
Thus this can be invoked at node start up after determining the marker file is present (and the tip is still not stale)
enterPreSyncing ∷ ∀ neverTerminates. m neverTerminates
ASSUMPTION the marker file is absent on disk, a la setCaughtUpPersistentMark False
Thus this can be invoked at node start up after determining the marker file is absent.

data GsmNodeKernelArgs m blk Source #

Arguments the NodeKernel has to take because of the GSM

Constructors

GsmNodeKernelArgs
Fields gsmAntiThunderingHerd ∷ StdGen See `antiThunderingHerd` gsmDurationUntilTooOld ∷ Maybe (WrapDurationUntilTooOld m blk) See `durationUntilTooOld` gsmMarkerFileView ∷ MarkerFileView m gsmMinCaughtUpDuration ∷ NominalDiffTime See `minCaughtUpDuration`

data GsmState Source #

Current state of the Genesis State Machine

Constructors

PreSyncing	We are syncing, and the Honest Availability Assumption is not satisfied.
Syncing	We are syncing, and the Honest Availability Assumption is satisfied.
CaughtUp	We are caught-up.

Instances

Instances details

Read GsmState Source #
Instance details Defined in Ouroboros.Consensus.Node.GSM Methods readsPrec ∷ Int → ReadS GsmState # readList ∷ ReadS [GsmState] # readPrec ∷ ReadPrec GsmState # readListPrec ∷ ReadPrec [GsmState] #
Show GsmState Source #
Instance details Defined in Ouroboros.Consensus.Node.GSM Methods showsPrec ∷ Int → GsmState → ShowS # show ∷ GsmState → String # showList ∷ [GsmState] → ShowS #
Eq GsmState Source #
Instance details Defined in Ouroboros.Consensus.Node.GSM Methods (==) ∷ GsmState → GsmState → Bool # (/=) ∷ GsmState → GsmState → Bool #

data GsmView m upstreamPeer selection chainSyncState Source #

Constructors

GsmView

Fields

antiThunderingHerd ∷ Maybe StdGen
An initial seed used to randomly increase minCaughtUpDuration by up to 15% every transition from Syncing to CaughtUp, in order to avoid a thundering herd phenomenon.
Nothing should only be used for testing.
candidateOverSelection ∷ selection → chainSyncState → CandidateVersusSelection
peerIsIdle ∷ chainSyncState → Bool
durationUntilTooOld ∷ Maybe (selection → m DurationFromNow)
How long from now until the selection will be so old that the node should exit the CaughtUp state
Nothing means the selection can never become too old.
equivalent ∷ selection → selection → Bool
Whether the two selections are equivalent for the purpose of the Genesis State Machine
getChainSyncStates ∷ STM m (Map upstreamPeer (StrictTVar m chainSyncState))
The current ChainSync state with the latest candidates from the upstream peers
getCurrentSelection ∷ STM m selection
The node's current selection
minCaughtUpDuration ∷ NominalDiffTime
How long the node must stay in CaughtUp after transitioning to it from Syncing, regardless of the selection's age. This prevents the whole network from thrashing between CaughtUp and (Pre)Syncing if there's an outage in block production.
See also antiThunderingHerd.
setCaughtUpPersistentMark ∷ Bool → m ()
EG touch/delete the marker file on disk
writeGsmState ∷ GsmState → m ()
EG update the TVar that the Diffusion Layer monitors, or en-/disable certain components of Genesis
isHaaSatisfied ∷ STM m Bool
Whether the Honest Availability Assumption is currently satisfied. This is used as the trigger for transitioning from PreSyncing to Syncing and vice versa.

data MarkerFileView m Source #

A view on the GSM's Caught-Up persistent marker file

These comments constrain the result of realMarkerFile; mock views in testing are free to be different.

Constructors

MarkerFileView
Fields hasMarkerFile ∷ m Bool removeMarkerFile ∷ m () Remove the marker file Will throw an `FsResourceDoesNotExist` error when it does not exist. touchMarkerFile ∷ m () Create the marker file Idempotent.

newtype WrapDurationUntilTooOld m blk Source #

Constructors

DurationUntilTooOld
Fields getDurationUntilTooOld ∷ WithOrigin SlotNo → m DurationFromNow

Auxiliaries

data TraceGsmEvent selection Source #

Constructors

GsmEventEnterCaughtUp !Int !selection	how many peers and the current selection
GsmEventLeaveCaughtUp !selection !DurationFromNow	the current selection and its age
GsmEventPreSyncingToSyncing	the Honest Availability Assumption is now satisfied
GsmEventSyncingToPreSyncing	the Honest Availability Assumption is no longer satisfied

Instances

Instances details

Show selection ⇒ Show (TraceGsmEvent selection) Source #
Instance details Defined in Ouroboros.Consensus.Node.GSM Methods showsPrec ∷ Int → TraceGsmEvent selection → ShowS # show ∷ TraceGsmEvent selection → String # showList ∷ [TraceGsmEvent selection] → ShowS #
Eq selection ⇒ Eq (TraceGsmEvent selection) Source #
Instance details Defined in Ouroboros.Consensus.Node.GSM Methods (==) ∷ TraceGsmEvent selection → TraceGsmEvent selection → Bool # (/=) ∷ TraceGsmEvent selection → TraceGsmEvent selection → Bool #

gsmStateToLedgerJudgement ∷ GsmState → LedgerStateJudgement Source #

For LedgerStateJudgement as used in the Diffusion layer, there is no difference between PreSyncing and Syncing.

initializationLedgerJudgement Source #

Arguments

∷ (GetTip (LedgerState blk), Monad m)
⇒ m (LedgerState blk)
→ Maybe (WrapDurationUntilTooOld m blk)	`Nothing` if `blk` has no age limit
→ MarkerFileView m
→ m LedgerStateJudgement

Determine the initial LedgerStateJudgment

Also initializes the persistent marker file.

Constructors

realDurationUntilTooOld Source #

Arguments

∷ (HasHardForkHistory blk, MonadSTM m)
⇒ LedgerConfig blk
→ STM m (LedgerState blk)
→ NominalDiffTime	If the volatile tip is older than this, then the node will exit the `CaughtUp` state. Eg `llrnMaxCaughtUpAge` WARNING This function returns `Already` if the wall clock is beyond the current ledger state's translation horizon; that may be confusing if an unexpectedly large `NominalDiffTime` is given here (eg 1 one week).
→ SystemTime m
→ m (WrapDurationUntilTooOld m blk)

The real system's durationUntilTooOld

realGsmEntryPoints ∷ ∀ m upstreamPeer selection tracedSelection candidate. (MonadDelay m, MonadTimer m) ⇒ (selection → tracedSelection, Tracer m (TraceGsmEvent tracedSelection)) → GsmView m upstreamPeer selection candidate → GsmEntryPoints m Source #

The actual GSM logic for boot strap peers

See the BootstrapPeersIER.md document for the specification of most of this logic, except the transition rules between PreSyncing and Syncing, the two states OnlyBootstrap is split into:

PreSyncing ⟶ Syncing: The Honest Availability Assumption is satisfied.

realMarkerFileView Source #

Arguments

∷ MonadThrow m
⇒ ChainDB m blk
→ HasFS m h	should be independent of other filesystems, eg `gsm/`
→ MarkerFileView m

The real system's MarkerFileView

The strict ChainDB argument is unused, but its existence ensures there's only one process using this file system.