scoring

Documentation

Index

• Constants
• func HasValidFlowIdentity(idProvider module.IdentityProvider, pid peer.ID) (*flow.Identity, error)
• func IsInvalidPeerIDError(this error) bool
• func IsInvalidSubscriptionError(this error) bool
• func NewInvalidPeerIDError(peerId peer.ID, status peerIdStatus) error
• func NewInvalidSubscriptionError(topic string) error
• type InvalidPeerIDError
  • func (e InvalidPeerIDError) Error() string
• type InvalidSubscriptionError
  • func (e InvalidSubscriptionError) Error() string
• type PeerScoreParamsOption
  • func WithAppSpecificScoreFunction(appSpecificScoreFunction func(peer.ID) float64) PeerScoreParamsOption
• type ScoreOption
  • func NewScoreOption(logger zerolog.Logger, idProvider module.IdentityProvider, ...) *ScoreOption
  • func (s *ScoreOption) BuildFlowPubSubScoreOption() pubsub.Option
  • func (s *ScoreOption) BuildGossipSubScoreOption() pubsub.Option
  • func (s *ScoreOption) SetSubscriptionProvider(provider *SubscriptionProvider)
• type SubscriptionProvider
  • func NewSubscriptionProvider(logger zerolog.Logger, tp p2p.TopicProvider) *SubscriptionProvider
  • func (s *SubscriptionProvider) GetSubscribedTopics(pid peer.ID) []string
• type SubscriptionValidator
  • func NewSubscriptionValidator() *SubscriptionValidator
  • func (v *SubscriptionValidator) CheckSubscribedToAllowedTopics(pid peer.ID, role flow.Role) error
  • func (v *SubscriptionValidator) RegisterSubscriptionProvider(provider p2p.SubscriptionProvider)

Constants

const (
	// PeerIdStatusUnknown indicates that the peer id is unknown.
	PeerIdStatusUnknown peerIdStatus = "unknown identity"
	// PeerIdStatusEjected indicates that the peer id belongs to an identity that has been ejected.
	PeerIdStatusEjected peerIdStatus = "ejected identity"
)

const (
	DefaultPeerScoringEnabled = true // enable peer scoring by default on node builder

	DefaultAppSpecificScoreWeight = 1
	MaxAppSpecificPenalty         = -100
	MinAppSpecificPenalty         = -1
	MaxAppSpecificReward          = 100

	// DefaultGossipThreshold when a peer's score drops below this threshold,
	// no gossip is emitted towards that peer and gossip from that peer is ignored.
	//
	// Validation Constraint: GossipThreshold >= PublishThreshold && GossipThreshold < 0
	//
	// How we use it:
	// As current max penalty is -100, we set the threshold to -99 so that all gossips
	// to and from peers with score -100 are ignored.
	DefaultGossipThreshold = -99

	// DefaultPublishThreshold when a peer's score drops below this threshold,
	// self-published messages are not propagated towards this peer.
	//
	// Validation Constraint:
	// PublishThreshold >= GraylistThreshold && PublishThreshold <= GossipThreshold && PublishThreshold < 0.
	//
	// How we use it:
	// As current max penalty is -100, we set the threshold to -99 so that all penalized peers are deprived of
	// receiving any published messages.
	DefaultPublishThreshold = -99

	// DefaultGraylistThreshold when a peer's score drops below this threshold, the peer is graylisted, i.e.,
	// incoming RPCs from the peer are ignored.
	//
	// Validation Constraint:
	// GraylistThreshold =< PublishThreshold && GraylistThreshold =< GossipThreshold && GraylistThreshold < 0
	//
	// How we use it:
	// As current max penalty is -100, we set the threshold to -99 so that all penalized peers are graylisted.
	DefaultGraylistThreshold = -99

	// DefaultAcceptPXThreshold when a peer sends us PX information with a prune, we only accept it and connect to the supplied
	// peers if the originating peer's score exceeds this threshold.
	//
	// Validation Constraint: must be non-negative.
	//
	// How we use it:
	// As current max reward is 100, we set the threshold to 99 so that we only receive supplied peers from
	// well-behaved peers.
	DefaultAcceptPXThreshold = 99

	// DefaultOpportunisticGraftThreshold when the median peer score in the mesh drops below this value,
	// the peer may select more peers with score above the median to opportunistically graft on the mesh.
	//
	// Validation Constraint: must be non-negative.
	//
	// How we use it:
	// We set it to the MaxAppSpecificReward + 1 so that we only opportunistically graft peers that are not access nodes (i.e., with MinAppSpecificPenalty),
	// or penalized peers (i.e., with MaxAppSpecificPenalty).
	DefaultOpportunisticGraftThreshold = MaxAppSpecificReward + 1

	// MaxDebugLogs sets the max number of debug/trace log events per second. Logs emitted above
	// this threshold are dropped.
	MaxDebugLogs = 50
)

Functions

func HasValidFlowIdentity

func HasValidFlowIdentity(idProvider module.IdentityProvider, pid peer.ID) (*flow.Identity, error)

HasValidFlowIdentity checks if the peer has a valid Flow identity.

func IsInvalidPeerIDError

func IsInvalidPeerIDError(this error) bool

func IsInvalidSubscriptionError

func IsInvalidSubscriptionError(this error) bool

func NewInvalidPeerIDError

func NewInvalidPeerIDError(peerId peer.ID, status peerIdStatus) error

func NewInvalidSubscriptionError

func NewInvalidSubscriptionError(topic string) error

Types

type InvalidPeerIDError

type InvalidPeerIDError struct {
	// contains filtered or unexported fields
}

InvalidPeerIDError indicates that a peer has an invalid peer id, i.e., it is not held by an authorized Flow identity.

func (InvalidPeerIDError) Error

func (e InvalidPeerIDError) Error() string

type InvalidSubscriptionError

type InvalidSubscriptionError struct {
	// contains filtered or unexported fields
}

InvalidSubscriptionError indicates that a peer has subscribed to a topic that is not allowed for its role.

func (InvalidSubscriptionError) Error

func (e InvalidSubscriptionError) Error() string

type PeerScoreParamsOption

type PeerScoreParamsOption func(option *ScoreOption)

func WithAppSpecificScoreFunction

func WithAppSpecificScoreFunction(appSpecificScoreFunction func(peer.ID) float64) PeerScoreParamsOption

type ScoreOption

type ScoreOption struct {
	// contains filtered or unexported fields
}

ScoreOption is a functional option for configuring the peer scoring system.

func NewScoreOption

func NewScoreOption(logger zerolog.Logger, idProvider module.IdentityProvider, opts ...PeerScoreParamsOption) *ScoreOption

func (*ScoreOption) BuildFlowPubSubScoreOption

func (s *ScoreOption) BuildFlowPubSubScoreOption() pubsub.Option

func (*ScoreOption) BuildGossipSubScoreOption

func (s *ScoreOption) BuildGossipSubScoreOption() pubsub.Option

func (*ScoreOption) SetSubscriptionProvider

func (s *ScoreOption) SetSubscriptionProvider(provider *SubscriptionProvider)

type SubscriptionProvider

type SubscriptionProvider struct {
	// contains filtered or unexported fields
}

SubscriptionProvider provides a list of topics a peer is subscribed to.

func NewSubscriptionProvider

func NewSubscriptionProvider(logger zerolog.Logger, tp p2p.TopicProvider) *SubscriptionProvider

func (*SubscriptionProvider) GetSubscribedTopics

func (s *SubscriptionProvider) GetSubscribedTopics(pid peer.ID) []string

GetSubscribedTopics returns all the subscriptions of a peer within the pubsub network. Note that the current node can only see peer subscriptions to topics that it has also subscribed to e.g., if current node has subscribed to topics A and B, and peer1 has subscribed to topics A, B, and C, then GetSubscribedTopics(peer1) will return A and B. Since this node has not subscribed to topic C, it will not be able to query for other peers subscribed to topic C.

type SubscriptionValidator

type SubscriptionValidator struct {
	// contains filtered or unexported fields
}

func NewSubscriptionValidator

func NewSubscriptionValidator() *SubscriptionValidator

func (*SubscriptionValidator) CheckSubscribedToAllowedTopics

func (v *SubscriptionValidator) CheckSubscribedToAllowedTopics(pid peer.ID, role flow.Role) error

CheckSubscribedToAllowedTopics validates all subscriptions a peer has with respect to all Flow topics. All errors returned by this method are benign: - InvalidSubscriptionError: the peer is subscribed to a topic that is not allowed for its role.

func (*SubscriptionValidator) RegisterSubscriptionProvider

func (v *SubscriptionValidator) RegisterSubscriptionProvider(provider p2p.SubscriptionProvider)