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. This includes ledger, 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, ledger peers and big ledger peers.

• targetNumberOfActivePeers ∷ !Int

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

  The

• 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 → 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

• readPeerSelectionTargets ∷ STM m PeerSelectionTargets
   
• readLocalRootPeers ∷ STM m (Config 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.

• requestPublicRootPeers ∷ LedgerPeersKind → Int → m (PublicRootPeers 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.

• readUseBootstrapPeers ∷ STM m UseBootstrapPeers

  Read the current bootstrap peers flag

• readLedgerStateJudgement ∷ STM m LedgerStateJudgement

  Read the current ledger state judgement

• updateOutboundConnectionsState ∷ OutboundConnectionsState → STM m ()

  Callback provided by consensus to inform it if the node is connected to only local roots or also some external peers.

  This is useful in order for the Bootstrap State Machine to simply refuse to transition from TooOld to YoungEnough while it only has local peers.

Fields

• countersVar ∷ StrictTVar m PeerSelectionCounters

  PeerSelectionCounters are shared with churn through a StrictTVar.

• publicStateVar ∷ StrictTVar m (PublicPeerSelectionState peeraddr)

  PublicPeerSelectionState var.

• debugStateVar ∷ StrictTVar m (PeerSelectionState 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

• targets ∷ !PeerSelectionTargets
   
• localRootPeers ∷ !(LocalRootPeers 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 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.

• ledgerStateJudgement ∷ !LedgerStateJudgement

  Current ledger state judgement

• bootstrapPeersFlag ∷ !UseBootstrapPeers

  Current value of UseBootstrapPeers.

• hasOnlyBootstrapPeers ∷ !Bool

  Has the governor fully reset its state

• bootstrapPeersTimeout ∷ !(Maybe Time)

  Has the governor fully reset its state

• inboundPeersRetryTime ∷ !Time

  Time to query of inbound peers time.

Fields

• dpssTargets ∷ !PeerSelectionTargets
   
• dpssLocalRootPeers ∷ !(LocalRootPeers peeraddr)
   
• dpssPublicRootPeers ∷ !(PublicRootPeers 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)
   
• dpssLedgerStateJudgement ∷ !LedgerStateJudgement
   
• dpssAssociationMode ∷ !AssociationMode
   

Fields

• availableToShare ∷ Set peeraddr
   

Fields

• decisionTrace ∷ [TracePeerSelection peeraddr]

  A trace event to classify the decision and action

• decisionState ∷ PeerSelectionState peeraddr peerconn

  An updated state to use immediately

• decisionJobs ∷ [Job () m (Completion m 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
   
• viewKnownBootstrapPeers ∷ a
   
• viewColdBootstrapPeersPromotions ∷ a
   
• viewEstablishedBootstrapPeers ∷ a
   
• viewWarmBootstrapPeersDemotions ∷ a
   
• viewWarmBootstrapPeersPromotions ∷ a
   
• viewActiveBootstrapPeers ∷ a
   
• viewActiveBootstrapPeersDemotions ∷ a
   

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.