Fields

• policyPickKnownPeersForPeerShare :: PickPolicy peeraddr (STM m)
   
• policyPickColdPeersToPromote :: PickPolicy peeraddr (STM m)
   
• policyPickWarmPeersToPromote :: PickPolicy peeraddr (STM m)
   
• policyPickHotPeersToDemote :: PickPolicy peeraddr (STM m)
   
• policyPickWarmPeersToDemote :: PickPolicy peeraddr (STM m)
   
• policyPickColdPeersToForget :: PickPolicy peeraddr (STM m)
   
• policyPickInboundPeers :: PickPolicy peeraddr (STM m)
   
• policyFindPublicRootTimeout :: !DiffTime
   
• policyMaxInProgressPeerShareReqs :: !Int

  Maximum number of peer sharing requests that can be in progress

• policyPeerShareRetryTime :: !DiffTime

  Amount of time a node has to wait before issuing a new peer sharing request

• policyPeerShareBatchWaitTime :: !DiffTime

  Amount of time a batch of peer sharing requests is allowed to take

• policyPeerShareOverallTimeout :: !DiffTime

  Amount of time the overall batches of peer sharing requests are allowed to take

• policyPeerShareActivationDelay :: !DiffTime

  Delay until we consider a peer suitable for peer sharing

• policyErrorDelay :: !DiffTime

  Re-promote delay, passed from ExitPolicy.

Fields

• targetNumberOfRootPeers :: !Int
   
• targetNumberOfKnownPeers :: !Int

  The target number of all known peers. Doesn't include big ledger peers |

• targetNumberOfEstablishedPeers :: !Int

  The target number of established peers (does not include big ledger peers).

  The target includes root peers, local root peers, and ledger peers

• targetNumberOfActivePeers :: !Int

  The target number of active peers (does not include big ledger peers).

• targetNumberOfKnownBigLedgerPeers :: !Int

  Target number of known big ledger peers.

  This target is independent of targetNumberOfKnownPeers. The total number of known peers will be sum of the two targets.

• targetNumberOfEstablishedBigLedgerPeers :: !Int

  Target number of established big ledger peers.

  This target is independent of targetNumberOfEstablishedPeers. The total number of established peers will be sum of the two targets and local root peers.

• targetNumberOfActiveBigLedgerPeers :: !Int

  Target number of active big ledger peers.

  This target is independent of targetNumberOfActivePeers. The total number of active peers will be sum of the two targets and active local root peers.

Fields

• monitorPeerConnection :: peerconn -> STM m (PeerStatus, Maybe RepromoteDelay)

  Monitor peer state. Must be non-blocking.

• establishPeerConnection :: IsBigLedgerPeer -> DiffusionMode -> peeraddr -> m peerconn

  Establish new connection: cold to warm.

  IsBigLedgerPeer is passed from the outbound governor to the mini-protocol callbacks.

• activatePeerConnection :: IsBigLedgerPeer -> peerconn -> m ()

  Activate a connection: warm to hot promotion.

  IsBigLedgerPeer is passed from the outbound governor to the mini-protocol callbacks.

• deactivatePeerConnection :: peerconn -> m ()

  Deactive a peer: hot to warm demotion.

• closePeerConnection :: peerconn -> m ()

  Close a connection: warm to cold transition.

Fields

• peerSelectionTargets :: PeerSelectionTargets

  These are the targets as seen in the static configuration

• readPeerSelectionTargets :: STM m PeerSelectionTargets

  Read current Peer Selection Targets these can be changed by Churn Governor

• readLocalRootPeersFromFile :: STM m (Config extraFlags RelayAccessPoint)

  Read the original set of locally configured root peers.

  This should come from ArgumentsExtra when initializing Diffusion

• readLocalRootPeers :: STM m (Config extraFlags peeraddr)

  Read the current set of locally or privately known root peers.

  In general this is expected to be updated asynchronously by some other thread. It is intended to cover the use case of peers from local configuration. It could be dynamic due to DNS resolution, or due to dynamic configuration updates.

  It is structured as a collection of (non-overlapping) groups of peers where we are supposed to select n from each group.

• readInboundPeers :: m (Map peeraddr PeerSharing)

  Read inbound peers which negotiated duplex connection.

• peerSharing :: PeerSharing

  Read the current Peer Sharing willingness value

  This value comes from the Node's configuration file.

• peerConnToPeerSharing :: peerconn -> PeerSharing

  Get the remote's side PeerSharing value from peerconn

  peerconn ideally comes from a call to establishPeerConnection. This will establish a connection and perform handshake. The returned peerconn has all the versionData negotiated in the handshake, including the remote peer's PeerSharing willingness information.

• extraPeersAPI :: PublicExtraPeersAPI extraPeers peeraddr

  Public Extra Peers Actions

• extraStateToExtraCounters :: PeerSelectionState extraState extraFlags extraPeers peeraddr peerconn -> extraCounters

  Compute extraCounters from PeerSelectionState

• requestPublicRootPeers :: LedgerPeersKind -> Int -> m (PublicRootPeers extraPeers peeraddr, DiffTime)

  Request a sample of public root peers.

  It is intended to cover use cases including:

  • federated relays from a DNS pool
  • Official bootstrap peers from a trusted source
  • stake pool relays published in the blockchain
  • a pre-distributed snapshot of stake pool relays from the blockchain

  It also makes a distinction between normal and big ledger peers to be fetched.

• requestPeerShare :: PeerSharingAmount -> peeraddr -> m (PeerSharingResult peeraddr)

  The action to contact a known peer and request a sample of its known peers.

• peerStateActions :: PeerStateActions peeraddr peerconn m

  Core actions run by the governor to change PeerStatus.

• getLedgerStateCtx :: LedgerPeersConsensusInterface extraAPI m

  Read the current ledger state

• readLedgerPeerSnapshot :: STM m (Maybe LedgerPeerSnapshot)

  Read the current state of ledger peer snapshot

Fields

• countersVar :: StrictTVar m (PeerSelectionCounters extraCounters)

  PeerSelectionCounters are shared with churn through a StrictTVar.

• publicStateVar :: StrictTVar m (PublicPeerSelectionState peeraddr)

  PublicPeerSelectionState var.

• debugStateVar :: StrictTVar m (PeerSelectionState extraState extraFlags extraPeers peeraddr peerconn)

  PeerSelectionState shared for debugging purposes (to support SIGUSR1 debug event tracing)

• readUseLedgerPeers :: STM m UseLedgerPeers

  UseLedgerPeers used by peerSelectionGovernor to support HiddenRelayOrBP

Fields

• preBlocking :: MonitoringAction extraState extraDebugState extraFlags extraPeers extraAPI extraCounters peeraddr peerconn m

  This guarded decision will come before all default possibly blocking decisions. The order matters; first decisions have priority over the later ones.

  Note that this action should be blocking.

• postBlocking :: MonitoringAction extraState extraDebugState extraFlags extraPeers extraAPI extraCounters peeraddr peerconn m

  This guarded decision will come after all possibly preBlocking and default blocking decisions. The order matters; first decisions have priority over the later ones.

  Note that these actions can be either blocking or non-blocking.

• postNonBlocking :: MonitoringAction extraState extraDebugState extraFlags extraPeers extraAPI extraCounters peeraddr peerconn m

  This guarded decision will come before all default non-blocking decisions. The order matters; first decisions have priority over the later ones.

  Note that these actions should not be blocking.

• customTargetsAction :: Maybe (MonitoringAction extraState extraDebugState extraFlags extraPeers extraAPI extraCounters peeraddr peerconn m)

  This action is necessary to the well functioning of the Outbound Governor. In particular this action should monitor PeerSelectionTargets, if they change, update PeerSelectionState accordingly.

  Customization of this monitoring action is allowed since a 3rd party user might require more granular control over the targets of its Outbound Governor.

  If no custom action is required (i.e. Nothing) a default will be provided by targetPeers

• customLocalRootsAction :: Maybe (MonitoringAction extraState extraDebugState extraFlags extraPeers extraAPI extraCounters peeraddr peerconn m)

  This action is necessary to the well functioning of the Outbound Governor. In particular this action should monitor Monitor local roots using readLocalRootPeers STM action.

  Customization of this monitoring action is allowed since a 3rd party user might require more granular control over the local roots of its Outbound Governor, according to extraFlags for example.

  If no custom action is required (i.e. Nothing) a default provided by localRoots

• enableProgressMakingActions :: extraState -> Bool

  This enables third party users to add extra guards to the following monitoring actions that make progress towards targets:

  • BigLedgerPeers.belowTarget
  • KnownPeers.belowTarget
  • EstablishedPeers.belowTargetBigLedgerPeers
  • ActivePeers.belowTargetBigLedgerPeers

  This might be useful if the user requires its diffusion layer to stop making progress during a sensitive/vulnerable situation and quarantine it and make sure it is only connected to trusted peers.

• ledgerPeerSnapshotExtraStateChange :: extraState -> extraState

  This can safely be left as id. This parameter is an artifact of the process of making the diffusion layer reusable. This function allows a constant extraState change after a successfull ledger peer snapshot change.

  TODO: Come up with a better solution (Issue #5065)

Fields

• abortGovernor :: Time -> PeerSelectionState extraState extraFlags extraPeers peeraddr peerconn -> Maybe exception
   
• updateWithState :: PeerSelectionInterfaces extraState extraFlags extraPeers extraCounters peeraddr peerconn m -> PeerSelectionActions extraState extraFlags extraPeers extraAPI extraCounters peeraddr peerconn m -> PeerSelectionSetsWithSizes extraCounters peeraddr -> PeerSelectionState extraState extraFlags extraPeers peeraddr peerconn -> STM m ()
   
• extraDecisions :: ExtraGuardedDecisions extraState extraDebugState extraFlags extraPeers extraAPI extraCounters peeraddr peerconn m
   

Fields

• targets :: !PeerSelectionTargets
   
• localRootPeers :: !(LocalRootPeers extraFlags peeraddr)

  The current set of local root peers. This is structured as a bunch of groups, with a target for each group. This gives us a set of n-of-m choices, e.g. "pick 2 from this group and 1 from this group".

  The targets must of course be achievable, and to keep things simple, the groups must be disjoint.

• publicRootPeers :: !(PublicRootPeers extraPeers peeraddr)

  This set holds the public root peers (i.e. Ledger (small and big), Bootstrap peers and locally configured public root peers).

• knownPeers :: !(KnownPeers peeraddr)

  Known peers.

• establishedPeers :: !(EstablishedPeers peeraddr peerconn)

  Established peers.

• activePeers :: !(Set peeraddr)

  Active peers.

• publicRootBackoffs :: !Int

  A counter to manage the exponential backoff strategy for when to retry querying for more public root peers. It is negative for retry counts after failure, and positive for retry counts that are successful but make no progress.

• publicRootRetryTime :: !Time

  The earliest time we would be prepared to request more public root peers. This is used with the publicRootBackoffs to manage the exponential backoff.

• inProgressPublicRootsReq :: !Bool

  Whether a request for more public root peers is in progress.

• bigLedgerPeerBackoffs :: !Int

  A counter to manage the exponential backoff strategy for when to retry querying for more public root peers. It is negative for retry counts after failure, and positive for retry counts that are successful but make no progress.

• bigLedgerPeerRetryTime :: !Time

  The earliest time we would be prepared to request more big ledger peers. This is used with the bigLedgerPeerBackoffs to manage the exponential backoff.

• inProgressBigLedgerPeersReq :: !Bool

  Whether a request for more big ledger peers is in progress.

• inProgressPeerShareReqs :: !Int
   
• inProgressPromoteCold :: !(Set peeraddr)
   
• inProgressPromoteWarm :: !(Set peeraddr)
   
• inProgressDemoteWarm :: !(Set peeraddr)
   
• inProgressDemoteHot :: !(Set peeraddr)
   
• inProgressDemoteToCold :: !(Set peeraddr)

  Peers that had an async demotion and their connections are still being closed

• stdGen :: !StdGen

  Rng for fuzzy delays and random choices.

• inboundPeersRetryTime :: !Time

  Time to query of inbound peers time.

• ledgerPeerSnapshot :: Maybe LedgerPeerSnapshot

  Internal state of ledger peer snapshot

• extraState :: extraState

  Extension point so that 3rd party users can plug their own peer selection state if needed

Fields

• dpssTargets :: !PeerSelectionTargets
   
• dpssLocalRootPeers :: !(LocalRootPeers extraFlags peeraddr)
   
• dpssPublicRootPeers :: !(PublicRootPeers extraPeers peeraddr)
   
• dpssKnownPeers :: !(KnownPeers peeraddr)
   
• dpssEstablishedPeers :: !(Set peeraddr)
   
• dpssActivePeers :: !(Set peeraddr)
   
• dpssPublicRootBackoffs :: !Int
   
• dpssPublicRootRetryTime :: !Time
   
• dpssInProgressPublicRootsReq :: !Bool
   
• dpssBigLedgerPeerBackoffs :: !Int
   
• dpssBigLedgerPeerRetryTime :: !Time
   
• dpssInProgressBigLedgerPeersReq :: !Bool
   
• dpssInProgressPeerShareReqs :: !Int
   
• dpssInProgressPromoteCold :: !(Set peeraddr)
   
• dpssInProgressPromoteWarm :: !(Set peeraddr)
   
• dpssInProgressDemoteWarm :: !(Set peeraddr)
   
• dpssInProgressDemoteHot :: !(Set peeraddr)
   
• dpssInProgressDemoteToCold :: !(Set peeraddr)
   
• dpssUpstreamyness :: !(Map peeraddr Int)
   
• dpssFetchynessBlocks :: !(Map peeraddr Int)
   
• dpssAssociationMode :: !AssociationMode
   
• dpssExtraState :: !extraState
   

Fields

• availableToShare :: Set peeraddr
   

Fields

• decisionTrace :: [TracePeerSelection extraDebugState extraFlags extraPeers peeraddr]

  A trace event to classify the decision and action

• decisionState :: PeerSelectionState extraState extraFlags extraPeers peeraddr peerconn

  An updated state to use immediately

• decisionJobs :: [Job () m (Completion m extraState extraDebugState extraFlags extraPeers peeraddr peerconn)]

  An optional Job to execute asynchronously. This job leads to a further Decision. This gives a state update to apply upon completion, but also allows chaining further job actions.

Fields

• viewRootPeers :: a
   
• viewKnownPeers :: a

  number of known peers excluding big ledger peers

• viewAvailableToConnectPeers :: a

  number of known peers available to connect

• viewColdPeersPromotions :: a

  number of known peers (excluding big ledger peers) being promoted to warm

• viewEstablishedPeers :: a

  number of established peers excluding big ledger peers

• viewWarmPeersDemotions :: a

  number of warm peers (excluding big ledger peers) being demoted to cold

• viewWarmPeersPromotions :: a

  number of warm peers (excluding big ledger peers) being promote to hot

• viewActivePeers :: a

  number of active peers excluding big ledger peers

• viewActivePeersDemotions :: a

  number of active peers (excluding big ledger peers) being demoted to warm

• viewKnownBigLedgerPeers :: a

  number of known big ledger peers

• viewAvailableToConnectBigLedgerPeers :: a

  number of known big ledger peers available to connect

• viewColdBigLedgerPeersPromotions :: a

  number of cold big ledger peers being promoted to warm

• viewEstablishedBigLedgerPeers :: a

  number of established big ledger peers

• viewWarmBigLedgerPeersDemotions :: a

  number of warm big ledger peers being demoted to cold

• viewWarmBigLedgerPeersPromotions :: a

  number of warm big ledger peers being promote to hot

• viewActiveBigLedgerPeers :: a

  number of active big ledger peers

• viewActiveBigLedgerPeersDemotions :: a

  number of active big ledger peers being demoted to warm

• viewKnownLocalRootPeers :: a

  number of known local root peers should always be equal to the sum of established & active local roots.

• viewAvailableToConnectLocalRootPeers :: a
   
• viewColdLocalRootPeersPromotions :: a
   
• viewEstablishedLocalRootPeers :: a
   
• viewWarmLocalRootPeersPromotions :: a
   
• viewActiveLocalRootPeers :: a
   
• viewActiveLocalRootPeersDemotions :: a
   
• viewKnownNonRootPeers :: a

  number of known non root peers. These are mostly peers received through peer sharing (or light peer sharing); but also will contains peers which used to be local roots after a reconfiguration.

• viewColdNonRootPeersPromotions :: a
   
• viewEstablishedNonRootPeers :: a
   
• viewWarmNonRootPeersDemotions :: a
   
• viewWarmNonRootPeersPromotions :: a
   
• viewActiveNonRootPeers :: a
   
• viewActiveNonRootPeersDemotions :: a
   
• viewExtraViews :: extraViews
   

Fields

• [(HotValency, Int)]

  local per-group `(target active, actual active)`, only limited to groups which are below their target.

• (Set peeraddr)

  selected peers | target active, actual active, peer, reason

Fields

• DiffTime

  duration of the churn action

• ChurnAction

  churn action type

• Int

  how many peers were removed or added within the duration of the action.

Fields

• DiffTime

  duration of the churn action

• ChurnAction

  churn action type

• Int

  how many peers were removed or added within the duration of the action; note that if the action timeouts the governor will still look to remove or add peers as required.