p2pconfig

package
v0.35.15-crescendo-pre... Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 20, 2024 License: AGPL-3.0 Imports: 4 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	RpcInspectorKey         = "rpc-inspector"
	RpcTracerKey            = "rpc-tracer"
	PeerScoringEnabledKey   = "peer-scoring-enabled"
	ScoreParamsKey          = "scoring-parameters"
	SubscriptionProviderKey = "subscription-provider"
)

GossipSubParameters keys.

View Source 
const (
	UpdateIntervalKey = "update-interval"
	CacheSizeKey      = "cache-size"
)

SubscriptionProviderParameters keys.

View Source 
const (
	LocalMeshLogIntervalKey              = "local-mesh-logging-interval"
	ScoreTracerIntervalKey               = "score-tracer-interval"
	RPCSentTrackerCacheSizeKey           = "rpc-sent-tracker-cache-size"
	RPCSentTrackerQueueCacheSizeKey      = "rpc-sent-tracker-queue-cache-size"
	RPCSentTrackerNumOfWorkersKey        = "rpc-sent-tracker-workers"
	DuplicateMessageCacheTrackerKey      = "duplicate-message-tracker"
	DuplicateMessageCacheTrackerSizeKey  = "cache-size"
	DuplicateMessageCacheTrackerDecayKey = "decay"
)

GossipSubTracerParameters keys.

View Source 
const (
	ValidationConfigKey      = "validation"
	MetricsConfigKey         = "metrics"
	NotificationCacheSizeKey = "notification-cache-size"
)

RpcInspectorParameters keys.

View Source 
const (
	ProcessKey                      = "process"
	ClusterPrefixedMessageConfigKey = "cluster-prefixed-messages"
	IWantConfigKey                  = "iwant"
	IHaveConfigKey                  = "ihave"
	GraftPruneKey                   = "graft-and-prune"
	PublishMessagesConfigKey        = "publish-messages"
	InspectionQueueConfigKey        = "inspection-queue"
)

RpcValidationInspectorParameters keys.

View Source 
const (
	InspectionKey       = "inspection"
	TruncationKey       = "truncation"
	EnableKey           = "enable"
	DisabledKey         = "disabled"
	MessageIDKey        = "message-id"
	RejectUnstakedPeers = "reject-unstaked-peers"
)
View Source 
const (
	MaxSampleSizeKey         = "max-sample-size"
	MessageErrorThresholdKey = "error-threshold"
)
View Source 
const (
	MessageCountThreshold      = "message-count-threshold"
	MessageIdCountThreshold    = "message-id-count-threshold"
	CacheMissThresholdKey      = "cache-miss-threshold"
	DuplicateMsgIDThresholdKey = "duplicate-message-id-threshold"
	InvalidTopicIdThresholdKey = "invalid-topic-id-threshold"
)
View Source 
const (
	DuplicateTopicIdThresholdKey   = "duplicate-topic-id-threshold"
	DuplicateMessageIdThresholdKey = "duplicate-message-id-threshold"
)
View Source 
const (
	HardThresholdKey     = "hard-threshold"
	TrackerCacheSizeKey  = "tracker-cache-size"
	TrackerCacheDecayKey = "tracker-cache-decay"
)
View Source 
const (
	PeerScoringKey = "peer-scoring"
	InternalKey    = "internal"
	ProtocolKey    = "protocol"
)
View Source 
const (
	AppSpecificScoreWeightKey = "app-specific-score-weight"
	DecayToZeroKey            = "decay-to-zero"
	BehaviourKey              = "behaviour"
	TopicKey                  = "topic"
	ThresholdsKey             = "thresholds"
	ThresholdKey              = "threshold"
)
View Source 
const (
	MaxDebugLogsKey = "max-debug-logs"
	AppSpecificKey  = "application-specific"
)
View Source 
const (
	MaxAppSpecificKey      = "max-app-specific"
	MinAppSpecificKey      = "min-app-specific"
	UnknownIdentityKey     = "unknown-identity"
	InvalidSubscriptionKey = "invalid-subscription"
	StakedIdentityKey      = "staked-identity"
	DuplicateMessageKey    = "duplicate-message"
	RewardKey              = "reward"
	PenaltyKey             = "penalty"
)
View Source 
const (
	GossipThresholdKey             = "gossip"
	GraylistThresholdKey           = "graylist"
	AcceptPXThresholdKey           = "accept-px"
	OpportunisticGraftThresholdKey = "opportunistic-graft"
)
View Source 
const (
	BehaviourPenaltyThresholdKey = "penalty-threshold"
	BehaviourPenaltyWeightKey    = "penalty-weight"
	BehaviourPenaltyDecayKey     = "penalty-decay"
)
View Source 
const (
	SkipAtomicValidationKey           = "skip-atomic-validation"
	InvalidMessageDeliveriesWeightKey = "invalid-message-deliveries-weight"
	InvalidMessageDeliveriesDecayKey  = "invalid-message-deliveries-decay"
	TimeInMeshQuantumKey              = "time-in-mesh-quantum"
	TopicWeightKey                    = "topic-weight"
	MeshMessageDeliveriesDecayKey     = "mesh-message-deliveries-decay"
	MeshMessageDeliveriesCapKey       = "mesh-message-deliveries-cap"
	MeshMessageDeliveryThresholdKey   = "mesh-message-deliveries-threshold"
	MeshDeliveriesWeightKey           = "mesh-deliveries-weight"
	MeshMessageDeliveriesWindowKey    = "mesh-message-deliveries-window"
	MeshMessageDeliveryActivationKey  = "mesh-message-delivery-activation"
)
View Source 
const (
	SpamRecordCacheKey          = "spam-record-cache"
	ScoringRegistryKey          = "scoring-registry"
	AppSpecificScoreRegistryKey = "app-specific-score"
	StartupSilenceDurationKey   = "startup-silence-duration"
)
View Source 
const (
	ScoreUpdateWorkerNumKey                       = "score-update-worker-num"
	ScoreUpdateRequestQueueSizeKey                = "score-update-request-queue-size"
	ScoreTTLKey                                   = "score-ttl"
	InvalidControlMessageNotificationQueueSizeKey = "invalid-control-message-notification-queue-size"
)
View Source 
const (
	PenaltyDecaySlowdownThresholdKey = "penalty-decay-slowdown-threshold"
	DecayRateReductionFactorKey      = "penalty-decay-rate-reduction-factor"
	PenaltyDecayEvaluationPeriodKey  = "penalty-decay-evaluation-period"
	MinimumSpamPenaltyDecayFactorKey = "minimum-spam-penalty-decay-factor"
	MaximumSpamPenaltyDecayFactorKey = "maximum-spam-penalty-decay-factor"
	SkipDecayThresholdKey            = "skip-decay-threshold"
)
View Source 
const (
	MisbehaviourPenaltiesKey          = "misbehaviour-penalties"
	GraftKey                          = "graft"
	PruneKey                          = "prune"
	IWantKey                          = "iwant"
	IHaveKey                          = "ihave"
	PublishKey                        = "publish"
	ClusterPrefixedReductionFactorKey = "cluster-prefixed-reduction-factor"
)
View Source 
const (
	DecayIntervalKey = "decay-interval"
)
View Source 
const (
	DecayKey = "decay"
)
View Source 
const (
	NumberOfWorkersKey = "workers"
)
View Source 
const (
	QueueSizeKey = "queue-size"
)

Variables

This section is empty.

Functions

func IsInvalidLimitConfigError 

func IsInvalidLimitConfigError(err error) bool

IsInvalidLimitConfigError returns whether an error is ErrInvalidLimitConfig.

Types

type AppSpecificScoreParameters 

type AppSpecificScoreParameters struct {
	// ScoreUpdateWorkerNum is the number of workers in the worker pool for handling the application specific score update of peers in a non-blocking way.
	ScoreUpdateWorkerNum int `validate:"gt=0" mapstructure:"score-update-worker-num"`

	// ScoreUpdateRequestQueueSize is the size of the worker pool for handling the application specific score update of peers in a non-blocking way.
	ScoreUpdateRequestQueueSize uint32 `validate:"gt=0" mapstructure:"score-update-request-queue-size"`

	// InvalidControlMessageNotificationQueueSize is the size of the queue for handling invalid control message notifications in a non-blocking way.
	InvalidControlMessageNotificationQueueSize uint32 `validate:"gt=0" mapstructure:"invalid-control-message-notification-queue-size"`

	// ScoreTTL is the time to live of the application specific score of a peer; the registry keeps a cached copy of the
	// application specific score of a peer for this duration. When the duration expires, the application specific score
	// of the peer is updated asynchronously. As long as the update is in progress, the cached copy of the application
	// specific score of the peer is used even if it is expired.
	ScoreTTL time.Duration `validate:"required" mapstructure:"score-ttl"`
}

AppSpecificScoreParameters is the parameters for the GossipSubAppSpecificScoreRegistry. Parameters are "numerical values" that are used to compute or build components that compute or maintain the application specific score of peers.

type ApplicationSpecificScoreParameters 

type ApplicationSpecificScoreParameters struct {
	// MaxAppSpecificPenalty the maximum penalty for sever offenses that we apply to a remote node score. The score
	// mechanism of GossipSub in Flow is designed in a way that all other infractions are penalized with a fraction of
	// this value. We have also set the other parameters such as DefaultGraylistThreshold, DefaultGossipThreshold and DefaultPublishThreshold to
	// be a bit higher than this, i.e., MaxAppSpecificPenalty + 1. This ensures that a node with a score of MaxAppSpecificPenalty
	// will be graylisted (i.e., all incoming and outgoing RPCs are rejected) and will not be able to publish or gossip any messages.
	MaxAppSpecificPenalty float64 `validate:"lt=0" mapstructure:"max-app-specific-penalty"`
	// MinAppSpecificPenalty the minimum penalty for sever offenses that we apply to a remote node score.
	MinAppSpecificPenalty float64 `validate:"lt=0" mapstructure:"min-app-specific-penalty"`
	// UnknownIdentityPenalty is the  penalty for unknown identity. It is applied to the peer's score when
	// the peer is not in the identity list.
	UnknownIdentityPenalty float64 `validate:"lt=0" mapstructure:"unknown-identity-penalty"`
	// InvalidSubscriptionPenalty is the  penalty for invalid subscription. It is applied to the peer's score when
	// the peer subscribes to a topic that it is not authorized to subscribe to.
	InvalidSubscriptionPenalty float64 `validate:"lt=0" mapstructure:"invalid-subscription-penalty"`
	// DuplicateMessagePenalty is the penalty for duplicate messages detected by the gossipsub tracer for a peer.
	// The penalty is multiplied by the current duplicate message count for a peer before it is applied to the application specific score.
	DuplicateMessagePenalty float64 `validate:"lt=0" mapstructure:"duplicate-message-penalty"`
	// DuplicateMessageThreshold the threshold at which the duplicate message count for a peer will result in the peer being penalized.
	DuplicateMessageThreshold float64 `validate:"gt=0" mapstructure:"duplicate-message-threshold"`
	// MaxAppSpecificReward is the  reward for well-behaving staked peers. If a peer does not have
	// any misbehavior record, e.g., invalid subscription, invalid message, etc., it will be rewarded with this score.
	MaxAppSpecificReward float64 `validate:"gt=0" mapstructure:"max-app-specific-reward"`
	// StakedIdentityReward is the  reward for staking peers. It is applied to the peer's score when
	// the peer does not have any misbehavior record, e.g., invalid subscription, invalid message, etc.
	// The purpose is to reward the staking peers for their contribution to the network and prioritize them in neighbor selection.
	StakedIdentityReward float64 `validate:"gt=0" mapstructure:"staked-identity-reward"`
}

type ClusterPrefixedMessageInspectionParameters 

type ClusterPrefixedMessageInspectionParameters struct {
	// HardThreshold the upper bound on the amount of cluster prefixed control messages that will be processed
	// before a node starts to get penalized. This allows LN nodes to process some cluster prefixed control messages during startup
	// when the cluster ID's provider is set asynchronously. It also allows processing of some stale messages that may be sent by nodes
	// that fall behind in the protocol. After the amount of cluster prefixed control messages processed exceeds this threshold the node
	// will be pushed to the edge of the network mesh.
	HardThreshold float64 `validate:"gte=0" mapstructure:"hard-threshold"`
	// ControlMsgsReceivedCacheSize size of the cache used to track the amount of cluster prefixed topics received by peers.
	ControlMsgsReceivedCacheSize uint32 `validate:"gt=0" mapstructure:"tracker-cache-size"`
	// ControlMsgsReceivedCacheDecay decay val used for the geometric decay of cache counters used to keep track of cluster prefixed topics received by peers.
	ControlMsgsReceivedCacheDecay float64 `validate:"gt=0" mapstructure:"tracker-cache-decay"`
}

ClusterPrefixedMessageInspectionParameters contains the "numerical values" for cluster prefixed control message inspection. Each RPC has a number of "publish messages" accompanied by control messages. This struct contains the limits for the inspection of messages (publish messages and control messages) that belongs to cluster prefixed topics. Cluster-prefixed topics are topics that are prefixed with the cluster ID of the node that published the message.

type DuplicateMessageTrackerConfig added in v0.33.30 

type DuplicateMessageTrackerConfig struct {
	// CacheSize cache size of the gossipsub duplicate message tracker.
	CacheSize uint32 `validate:"gt=0" mapstructure:"cache-size"`
	// Decay rate of decay for the peer duplicate message counters.
	Decay float64 `validate:"gt=0,lt=1" mapstructure:"decay"`
	// SkipDecayThreshold the threshold for which when the counter is below this value, the decay function will not be called
	SkipDecayThreshold float64 `validate:"gt=0,lt=1" mapstructure:"skip-decay-threshold"`
}

DuplicateMessageTrackerConfig duplicate message cache config.

type GossipSubParameters 

type GossipSubParameters struct {
	// RpcInspectorParameters configuration for all gossipsub RPC control message inspectors.
	RpcInspector RpcInspectorParameters `mapstructure:"rpc-inspector"`

	// GossipSubScoringRegistryConfig is the configuration for the GossipSub score registry.
	// GossipSubTracerParameters is the configuration for the gossipsub tracer. GossipSub tracer is used to trace the local mesh events and peer scores.
	RpcTracer GossipSubTracerParameters `mapstructure:"rpc-tracer"`

	// ScoringParameters is whether to enable GossipSub peer scoring.
	PeerScoringEnabled   bool                           `mapstructure:"peer-scoring-enabled"`
	SubscriptionProvider SubscriptionProviderParameters `mapstructure:"subscription-provider"`
	ScoringParameters    ScoringParameters              `mapstructure:"scoring-parameters"`
}

GossipSubParameters is the configuration for the GossipSub pubsub implementation.

type GossipSubTracerParameters 

type GossipSubTracerParameters struct {
	DuplicateMessageTrackerConfig DuplicateMessageTrackerConfig `validate:"required" mapstructure:"duplicate-message-tracker"`
	// LocalMeshLogInterval is the interval at which the local mesh is logged.
	LocalMeshLogInterval time.Duration `validate:"gt=0s" mapstructure:"local-mesh-logging-interval"`
	// ScoreTracerInterval is the interval at which the score tracer logs the peer scores.
	ScoreTracerInterval time.Duration `validate:"gt=0s" mapstructure:"score-tracer-interval"`
	// RPCSentTrackerCacheSize cache size of the rpc sent tracker used by the gossipsub mesh tracer.
	RPCSentTrackerCacheSize uint32 `validate:"gt=0" mapstructure:"rpc-sent-tracker-cache-size"`
	// RPCSentTrackerQueueCacheSize cache size of the rpc sent tracker queue used for async tracking.
	RPCSentTrackerQueueCacheSize uint32 `validate:"gt=0" mapstructure:"rpc-sent-tracker-queue-cache-size"`
	// RpcSentTrackerNumOfWorkers number of workers for rpc sent tracker worker pool.
	RpcSentTrackerNumOfWorkers int `validate:"gt=0" mapstructure:"rpc-sent-tracker-workers"`
}

GossipSubTracerParameters is the config for the gossipsub tracer. GossipSub tracer is used to trace the local mesh events and peer scores.

type GraftPruneRpcInspectionParameters added in v0.33.7 

type GraftPruneRpcInspectionParameters struct {
	// MessageCountThreshold is the maximum number of GRAFT or PRUNE messages in a single RPC message.
	// When the total number of GRAFT or PRUNE messages in a single RPC message exceeds this threshold,
	// a random sample of GRAFT or PRUNE messages will be taken and the RPC message will be truncated to this sample size.
	MessageCountThreshold int `validate:"gte=0" mapstructure:"message-count-threshold"`

	// DuplicateTopicIdThreshold is the tolerance threshold for having duplicate topics in a single GRAFT or PRUNE message under inspection.
	// Ideally, a GRAFT or PRUNE message should not have any duplicate topics, hence a topic ID is counted as a duplicate only if it is repeated more than once.
	// When the total number of duplicate topic ids in a single GRAFT or PRUNE message exceeds this threshold, the inspection of message will fail.
	DuplicateTopicIdThreshold int `validate:"gte=0" mapstructure:"duplicate-topic-id-threshold"`

	// InvalidTopicIdThreshold Maximum number of total invalid topic ids in a single GRAFT or PRUNE message, ideally this should be 0 but we allow for some tolerance
	// to avoid penalizing peers that are not malicious but are misbehaving due to bugs or other issues.
	InvalidTopicIdThreshold int `validate:"gte=0" mapstructure:"invalid-topic-id-threshold"`
}

GraftPruneRpcInspectionParameters contains the "numerical values" for the graft and prune control message inspection. Each RPC has a number of "publish messages" accompanied by control messages. This struct contains the limits for the inspection of these graft and prune control messages.

type IHaveRpcInspectionParameters 

type IHaveRpcInspectionParameters struct {
	// MessageCountThreshold is the maximum allowed number of iHave messages in a single RPC message.
	// Each iHave message represents the list of message ids for a specific topic. When the total number of iHave messages
	// in a single RPC message exceeds this threshold, a random sample of iHave messages will be taken and the RPC message will be truncated to this sample size.
	// The sample size is equal to the configured MessageCountThreshold.
	MessageCountThreshold int `validate:"gte=0" mapstructure:"message-count-threshold"`
	// MessageIdCountThreshold is the maximum allowed number of message ids in a single iHave message.
	// Each iHave message represents the list of message ids for a specific topic, and this parameter controls the maximum number of message ids
	// that can be included in a single iHave message. When the total number of message ids in a single iHave message exceeds this threshold,
	// a random sample of message ids will be taken and the iHave message will be truncated to this sample size.
	// The sample size is equal to the configured MessageIdCountThreshold.
	MessageIdCountThreshold int `validate:"gte=0" mapstructure:"message-id-count-threshold"`

	// DuplicateTopicIdThreshold is the tolerance threshold for having duplicate topics in an iHave message under inspection.
	// When the total number of duplicate topic ids in a single iHave message exceeds this threshold, the inspection of message will fail.
	// Note that a topic ID is counted as a duplicate only if it is repeated more than DuplicateTopicIdThreshold times.
	DuplicateTopicIdThreshold int `validate:"gte=0" mapstructure:"duplicate-topic-id-threshold"`

	// DuplicateMessageIdThreshold is the threshold of tolerance for having duplicate message IDs in a single iHave message under inspection.
	// When the total number of duplicate message ids in a single iHave message exceeds this threshold, the inspection of message will fail.
	// Ideally, an iHave message should not have any duplicate message IDs, hence a message id is considered duplicate when it is repeated more than once
	// within the same iHave message. When the total number of duplicate message ids in a single iHave message exceeds this threshold, the inspection of message will fail.
	DuplicateMessageIdThreshold int `validate:"gte=0" mapstructure:"duplicate-message-id-threshold"`

	// InvalidTopicIdThreshold Maximum number of total invalid topic ids in a single IHAVE message, ideally this should be 0 but we allow for some tolerance
	// to avoid penalizing peers that are not malicious but are misbehaving due to bugs or other issues.
	InvalidTopicIdThreshold int `validate:"gte=0" mapstructure:"invalid-topic-id-threshold"`
}

IHaveRpcInspectionParameters contains the "numerical values" for ihave rpc control inspection. Each RPC has a number of "publish messages" accompanied by control messages. This struct contains the limits for the inspection of the ihave control messages.

type IWantRpcInspectionParameters added in v0.33.7 

type IWantRpcInspectionParameters struct {
	// MessageCountThreshold is the maximum allowed number of iWant messages in a single RPC message.
	// Each iWant message represents the list of message ids. When the total number of iWant messages
	// in a single RPC message exceeds this threshold, a random sample of iWant messages will be taken and the RPC message will be truncated to this sample size.
	// The sample size is equal to the configured MessageCountThreshold.
	MessageCountThreshold uint `validate:"gt=0" mapstructure:"message-count-threshold"`
	// MessageIdCountThreshold is the maximum allowed number of message ids in a single iWant message.
	// Each iWant message represents the list of message ids for a specific topic, and this parameter controls the maximum number of message ids
	// that can be included in a single iWant message. When the total number of message ids in a single iWant message exceeds this threshold,
	// a random sample of message ids will be taken and the iWant message will be truncated to this sample size.
	// The sample size is equal to the configured MessageIdCountThreshold.
	MessageIdCountThreshold int `validate:"gte=0" mapstructure:"message-id-count-threshold"`
	// CacheMissThreshold is the threshold of tolerance for the total cache misses in all iWant messages in a single RPC message.
	// When the total number of cache misses in all iWant messages in a single RPC message exceeds this threshold, the inspection of message will fail.
	// An iWant message is considered a cache miss if it contains a message id that is not present in the local cache for iHave messages, i.e., the node
	// does not have a record of an iHave message for this message id.
	// When the total number of cache misses in all iWant messages in a single RPC message exceeds this threshold, the inspection of message will fail, and
	// a single misbehavior notification will be reported.
	CacheMissThreshold int `validate:"gt=0" mapstructure:"cache-miss-threshold"`
	// DuplicateMsgIdThreshold is the maximum allowed number of duplicate message ids in a all iWant messages in a single RPC message.
	// Each iWant message represents the list of message ids, and this parameter controls the maximum number of duplicate message ids
	// that can be included in all iWant messages in a single RPC message. When the total number of duplicate message ids in a single iWant message exceeds this threshold,
	// a single misbehavior notification will be reported, and the inspection of message will fail.
	DuplicateMsgIdThreshold int `validate:"gt=0" mapstructure:"duplicate-message-id-threshold"`
}

IWantRpcInspectionParameters contains the "numerical values" for iwant rpc control inspection. Each RPC has a number of "publish messages" accompanied by control messages. This struct contains the limits for the inspection of the iwant control messages.

type Inspect added in v0.33.30 

type Inspect struct {
	// Disabled serves as a fail-safe mechanism to globally deactivate inspection logic. When this fail-safe is activated it disables all
	// aspects of the inspection logic, irrespective of individual configurations like inspection.enable-graft, inspection.enable-prune, etc.
	// Consequently, all metrics collection and logging related to the rpc and inspection will also be disabled.
	// It is important to note that activating this fail-safe results in a comprehensive deactivation inspection features.
	// Please use this setting judiciously, considering its broad impact on the behavior of control message handling.
	Disabled bool `mapstructure:"disabled"`
	// EnableGraft enable graft control message inspection.
	EnableGraft bool `mapstructure:"enable-graft"`
	// EnablePrune enable prune control message inspection.
	EnablePrune bool `mapstructure:"enable-prune"`
	// EnableIHave enable iHave control message inspection.
	EnableIHave bool `mapstructure:"enable-ihave"`
	// EnableIWant enable iWant control message inspection.
	EnableIWant bool `mapstructure:"enable-iwant"`
	// EnablePublish enable publish message inspection.
	EnablePublish bool `mapstructure:"enable-publish"`
	// RejectUnstakedPeers when set to true RPC's will be rejected from unstaked peers.
	RejectUnstakedPeers bool `mapstructure:"reject-unstaked-peers"`
}

Inspect configuration to enable/disable RPC inspection for a particular control message type.

type InspectionProcess added in v0.33.30 

type InspectionProcess struct {
	Inspect  Inspect  `validate:"required" mapstructure:"inspection"`
	Truncate Truncate `validate:"required" mapstructure:"truncation"`
}

InspectionProcess configuration that controls which aspects of rpc inspection are enabled and disabled during inspect message request processing.

type InspectionQueueParameters added in v0.33.7 

type InspectionQueueParameters struct {
	// NumberOfWorkers number of worker pool workers.
	NumberOfWorkers int `validate:"gte=1" mapstructure:"workers"`
	// Size size of the queue used by worker pool for the control message validation inspector.
	Size uint32 `validate:"gte=100" mapstructure:"queue-size"`
}

InspectionQueueParameters contains the "numerical values" for the control message validation inspector. Incoming GossipSub RPCs are queued for async inspection by a worker pool. This worker pool is configured by the parameters in this struct. Each RPC has a number of "publish messages" accompanied by control messages.

type InternalGossipSubScoreParams 

type InternalGossipSubScoreParams struct {
	// AppSpecificScoreWeight is the  weight for app-specific scores. It is used to scale the app-specific
	// scores to the same range as the other scores. At the current version, we don't distinguish between the app-specific
	// scores and the other scores, so we set it to 1.
	AppSpecificScoreWeight float64 `validate:"gt=0,lte=1" mapstructure:"app-specific-score-weight"`
	// DecayInterval is the  decay interval for the overall score of a peer at the GossipSub scoring
	// system. We set it to 1 minute so that it is not too short so that a malicious node can recover from a penalty
	// and is not too long so that a well-behaved node can't recover from a penalty.
	DecayInterval time.Duration `validate:"gte=1m" mapstructure:"decay-interval"`
	// DecayToZero is the  decay to zero for the overall score of a peer at the GossipSub scoring system.
	// It defines the maximum value below which a peer scoring counter is reset to zero.
	// This is to prevent the counter from decaying to a very small value.
	// The  value is 0.01, which means that a counter will be reset to zero if it decays to 0.01.
	// When a counter hits the DecayToZero threshold, it means that the peer did not exhibit the behavior
	// for a long time, and we can reset the counter.
	DecayToZero     float64                    `validate:"required" mapstructure:"decay-to-zero"`
	TopicParameters TopicScoringParameters     `validate:"required" mapstructure:"topic"`
	Thresholds      InternalScoringThresholds  `validate:"required" mapstructure:"thresholds"`
	Behaviour       InternalScoringBehavioural `validate:"required" mapstructure:"behaviour"`
}

type InternalScoringBehavioural 

type InternalScoringBehavioural struct {
	// PenaltyThreshold is the threshold when the behavior of a peer is considered as bad by GossipSub.
	// Currently, the misbehavior is defined as advertising an iHave without responding to the iWants (iHave broken promises), as well as attempting
	// on GRAFT when the peer is considered for a PRUNE backoff, i.e., the local peer does not allow the peer to join the local topic mesh
	// for a while, and the remote peer keep attempting on GRAFT (aka GRAFT flood).
	// When the misbehavior counter of a peer goes beyond this threshold, the peer is penalized by BehaviorPenaltyWeight (see below) for the excess misbehavior.
	//
	// An iHave broken promise means that a peer advertises an iHave for a message, but does not respond to the iWant requests for that message.
	// For iHave broken promises, the gossipsub scoring works as follows:
	// It samples ONLY A SINGLE iHave out of the entire RPC.
	// If that iHave is not followed by an actual message within the next 3 seconds, the peer misbehavior counter is incremented by 1.
	//
	// The counter is also decayed by (0.99) every decay interval (DecayInterval) i.e., every minute.
	// Note that misbehaviors are counted by GossipSub across all topics (and is different from the Application Layer Misbehaviors that we count through
	// the ALSP system).
	PenaltyThreshold float64 `validate:"gt=0" mapstructure:"penalty-threshold"`
	// PenaltyWeight is the weight for applying penalty when a peer misbehavior goes beyond the threshold.
	// Misbehavior of a peer at gossipsub layer is defined as advertising an iHave without responding to the iWants (broken promises), as well as attempting
	// on GRAFT when the peer is considered for a PRUNE backoff, i.e., the local peer does not allow the peer to join the local topic mesh
	// This is detected by the GossipSub scoring system, and the peer is penalized by BehaviorPenaltyWeight.
	//
	// An iHave broken promise means that a peer advertises an iHave for a message, but does not respond to the iWant requests for that message.
	// For iHave broken promises, the gossipsub scoring works as follows:
	// It samples ONLY A SINGLE iHave out of the entire RPC.
	// If that iHave is not followed by an actual message within the next 3 seconds, the peer misbehavior counter is incremented by 1.
	PenaltyWeight float64 `validate:"lt=0" mapstructure:"penalty-weight"`
	// PenaltyDecay is the decay interval for the misbehavior counter of a peer. The misbehavior counter is
	// incremented by GossipSub for iHave broken promises or the GRAFT flooding attacks (i.e., each GRAFT received from a remote peer while that peer is on a PRUNE backoff).
	//
	// An iHave broken promise means that a peer advertises an iHave for a message, but does not respond to the iWant requests for that message.
	// For iHave broken promises, the gossipsub scoring works as follows:
	// It samples ONLY A SINGLE iHave out of the entire RPC.
	// If that iHave is not followed by an actual message within the next 3 seconds, the peer misbehavior counter is incremented by 1.
	// This means that regardless of how many iHave broken promises an RPC contains, the misbehavior counter is incremented by 1.
	// That is why we decay the misbehavior counter very slow, as this counter indicates a severe misbehavior.
	// The misbehavior counter is decayed per decay interval (i.e., DecayInterval = 1 minute) by GossipSub.
	//
	// Note that misbehaviors are counted by GossipSub across all topics (and is different from the Application Layer Misbehaviors that we count through
	// the ALSP system that is based on the engines report).
	PenaltyDecay float64 `validate:"gt=0,lt=1" mapstructure:"penalty-decay"`
}

InternalScoringBehavioural score option behaviour configuration parameters.

type InternalScoringThresholds 

type InternalScoringThresholds struct {
	// Gossip when a peer's penalty drops below this threshold,
	// no gossip is emitted towards that peer and gossip from that peer is ignored.
	Gossip float64 `validate:"lt=0" mapstructure:"gossip"`
	// Publish when a peer's penalty drops below this threshold,
	// self-published messages are not propagated towards this peer.
	Publish float64 `validate:"lt=0" mapstructure:"publish"`
	// Graylist when a peer's penalty drops below this threshold, the peer is graylisted, i.e.,
	// incoming RPCs from the peer are ignored.
	Graylist float64 `validate:"lt=0" mapstructure:"graylist"`
	// AcceptPX 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 penalty exceeds this threshold.
	AcceptPX float64 `validate:"gt=0" mapstructure:"accept-px"`
	// OpportunisticGraft when the median peer penalty in the mesh drops below this value,
	// the peer may select more peers with penalty above the median to opportunistically graft on the mesh.
	OpportunisticGraft float64 `validate:"gt=0" mapstructure:"opportunistic-graft"`
}

InternalScoringThresholds score option threshold configuration parameters.

type InvalidLimitConfigError 

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

InvalidLimitConfigError indicates the validation limit is < 0.

func NewInvalidLimitConfigErr 

func NewInvalidLimitConfigErr(controlMsg p2pmsg.ControlMessageType, err error) InvalidLimitConfigError

NewInvalidLimitConfigErr returns a new ErrValidationLimit.

func (InvalidLimitConfigError) Error 

func (e InvalidLimitConfigError) Error() string

func (InvalidLimitConfigError) Unwrap 

func (e InvalidLimitConfigError) Unwrap() error

type MisbehaviourPenalties 

type MisbehaviourPenalties struct {
	GraftMisbehaviour              float64 `validate:"lt=0" mapstructure:"graft"`
	PruneMisbehaviour              float64 `validate:"lt=0" mapstructure:"prune"`
	IHaveMisbehaviour              float64 `validate:"lt=0" mapstructure:"ihave"`
	IWantMisbehaviour              float64 `validate:"lt=0" mapstructure:"iwant"`
	PublishMisbehaviour            float64 `validate:"lt=0" mapstructure:"publish"`
	ClusterPrefixedReductionFactor float64 `validate:"gt=0,lte=1" mapstructure:"cluster-prefixed-reduction-factor"`
}

type PeerScoringParameters 

type PeerScoringParameters struct {
	// Internal is the internal parameters of the GossipSub scoring system that are hosted by
	// the GossipSub system, and are not exposed to the Flow protocol.
	// The internal parameters are hosted by the GossipSub system.
	Internal InternalGossipSubScoreParams `validate:"required" mapstructure:"internal"`
	// Protocol is the protocol parameters of the peer scoring system that is hosted by the Flow protocol.
	Protocol ProtocolLevelGossipSubScoreParams `validate:"required" mapstructure:"protocol"`
}

PeerScoringParameters encapsulates the parameters of the GossipSub scoring system.

type ProtocolLevelGossipSubScoreParams 

type ProtocolLevelGossipSubScoreParams struct {
	MaxDebugLogs     uint32                             `validate:"lte=50" mapstructure:"max-debug-logs"`
	AppSpecificScore ApplicationSpecificScoreParameters `validate:"required" mapstructure:"application-specific"`
}

type PublishMessageInspectionParameters added in v0.33.7 

type PublishMessageInspectionParameters struct {
	// MaxSampleSize is the maximum number of messages in a single RPC message that are randomly sampled for async inspection.
	// When the size of a single RPC message exceeds this threshold, a random sample is taken for inspection, but the RPC message is not truncated.
	MaxSampleSize int `validate:"gte=0" mapstructure:"max-sample-size"`
	// ErrorThreshold the threshold at which an error will be returned if the number of invalid RPC messages exceeds this value.
	ErrorThreshold int `validate:"gte=0" mapstructure:"error-threshold"`
}

PublishMessageInspectionParameters contains the "numerical values" for the publish control message inspection. Each RPC has a number of "publish messages" accompanied by control messages. This struct contains the limits for the inspection of these publish messages.

type ResourceManagerConfig 

type ResourceManagerConfig struct {
	Override             ResourceManagerOverrideScope `mapstructure:"limits-override"`        // override limits for specific peers, protocols, etc.
	MemoryLimitRatio     float64                      `mapstructure:"memory-limit-ratio"`     // maximum allowed fraction of memory to be allocated by the libp2p resources in (0,1]
	FileDescriptorsRatio float64                      `mapstructure:"file-descriptors-ratio"` // maximum allowed fraction of file descriptors to be allocated by the libp2p resources in (0,1]
}

ResourceManagerConfig returns the resource manager configuration for the libp2p node. The resource manager is used to limit the number of open connections and streams (as well as any other resources used by libp2p) for each peer.

type ResourceManagerOverrideLimit 

type ResourceManagerOverrideLimit struct {
	// System is the limit for the resource at the entire system. if not set, the default value will be used.
	// For a specific limit, the system-wide dictates the maximum allowed value across all peers and protocols at the entire node scope.
	StreamsInbound int `validate:"gte=0" mapstructure:"streams-inbound"`

	// StreamsOutbound is the max number of outbound streams allowed, at the resource scope.
	StreamsOutbound int `validate:"gte=0" mapstructure:"streams-outbound"`

	// ConnectionsInbound is the max number of inbound connections allowed, at the resource scope.
	ConnectionsInbound int `validate:"gte=0" mapstructure:"connections-inbound"`

	// ConnectionsOutbound is the max number of outbound connections allowed, at the resource scope.
	ConnectionsOutbound int `validate:"gte=0" mapstructure:"connections-outbound"`

	// FD is the max number of file descriptors allowed, at the resource scope.
	FD int `validate:"gte=0" mapstructure:"fd"`

	// Memory is the max amount of memory allowed (bytes), at the resource scope.
	Memory int `validate:"gte=0" mapstructure:"memory-bytes"`
}

ResourceManagerOverrideLimit is the configuration for the resource manager override limit at a certain scope. Any value that is not set will be ignored and the default value will be used.

type ResourceManagerOverrideScope 

type ResourceManagerOverrideScope struct {
	// System is the limit for the resource at the entire system.
	// For a specific limit, the system-wide dictates the maximum allowed value across all peers and protocols at the entire node level.
	System ResourceManagerOverrideLimit `mapstructure:"system"`

	// Transient is the limit for the resource at the transient scope. Transient limits are used for resources that have not fully established and are under negotiation.
	Transient ResourceManagerOverrideLimit `mapstructure:"transient"`

	// Protocol is the limit for the resource at the protocol scope, e.g., DHT, GossipSub, etc. It dictates the maximum allowed resource across all peers for that protocol.
	Protocol ResourceManagerOverrideLimit `mapstructure:"protocol"`

	// Peer is the limit for the resource at the peer scope. It dictates the maximum allowed resource for a specific peer.
	Peer ResourceManagerOverrideLimit `mapstructure:"peer"`

	// Connection is the limit for the resource for a pair of (peer, protocol), e.g., (peer1, DHT), (peer1, GossipSub), etc. It dictates the maximum allowed resource for a protocol and a peer.
	PeerProtocol ResourceManagerOverrideLimit `mapstructure:"peer-protocol"`
}

type ResourceScope 

type ResourceScope string

ResourceScope is the scope of the resource, e.g., system, transient, protocol, peer, peer-protocol. 

const (
	// ResourceScopeSystem is the system scope; the system scope dictates the maximum allowed value across all peers and protocols at the entire node level.
	ResourceScopeSystem ResourceScope = "system"
	// ResourceScopeTransient is the transient scope; the transient scope is used for resources that have not fully established and are under negotiation.
	ResourceScopeTransient ResourceScope = "transient"
	// ResourceScopeProtocol is the protocol scope; the protocol scope dictates the maximum allowed resource across all peers for that protocol.
	ResourceScopeProtocol ResourceScope = "protocol"
	// ResourceScopePeer is the peer scope; the peer scope dictates the maximum allowed resource for a specific peer.
	ResourceScopePeer ResourceScope = "peer"
	// ResourceScopePeerProtocol is the peer-protocol scope; the peer-protocol scope dictates the maximum allowed resource for a protocol and a peer.
	ResourceScopePeerProtocol ResourceScope = "peer-protocol"
)

func (ResourceScope) String 

func (r ResourceScope) String() string

type RpcInspectorParameters 

type RpcInspectorParameters struct {
	// RpcValidationInspector control message validation inspector validation configuration and limits.
	Validation RpcValidationInspector `mapstructure:"validation"`
	// NotificationCacheSize size of the queue for notifications about invalid RPC messages.
	NotificationCacheSize uint32 `mapstructure:"notification-cache-size"`
}

RpcInspectorParameters contains the "numerical values" for the gossipsub RPC control message inspectors parameters.

type RpcValidationInspector 

type RpcValidationInspector struct {
	ClusterPrefixedMessage ClusterPrefixedMessageInspectionParameters `mapstructure:"cluster-prefixed-messages"`
	IWant                  IWantRpcInspectionParameters               `mapstructure:"iwant"`
	IHave                  IHaveRpcInspectionParameters               `mapstructure:"ihave"`
	GraftPrune             GraftPruneRpcInspectionParameters          `mapstructure:"graft-and-prune"`
	PublishMessages        PublishMessageInspectionParameters         `mapstructure:"publish-messages"`
	InspectionQueue        InspectionQueueParameters                  `mapstructure:"inspection-queue"`
	// InspectionProcess configuration that controls which aspects of rpc inspection are enabled and disabled during inspect message request processing.
	InspectionProcess InspectionProcess `mapstructure:"process"`
}

RpcValidationInspector rpc control message validation inspector configuration.

type ScoringParameters 

type ScoringParameters struct {
	PeerScoring               PeerScoringParameters     `validate:"required" mapstructure:"peer-scoring"`
	ScoringRegistryParameters ScoringRegistryParameters `validate:"required" mapstructure:"scoring-registry"`
}

ScoringParameters are the parameters for the score option. Parameters are "numerical values" that are used to compute or build components that compute the score of a peer in GossipSub system.

type ScoringRegistryParameters 

type ScoringRegistryParameters struct {
	// StartupSilenceDuration defines the duration of time, after the node startup,
	// during which the scoring registry remains inactive before penalizing nodes.
	// Throughout this startup silence period, the application-specific penalty
	// for all nodes will be set to 0, and any invalid control message notifications
	// will be ignored.
	//
	// This configuration allows nodes to stabilize and initialize before
	// applying penalties or responding processing invalid control message notifications.
	StartupSilenceDuration time.Duration              `validate:"gt=10m" mapstructure:"startup-silence-duration"`
	AppSpecificScore       AppSpecificScoreParameters `validate:"required" mapstructure:"app-specific-score"`
	SpamRecordCache        SpamRecordCacheParameters  `validate:"required" mapstructure:"spam-record-cache"`
	MisbehaviourPenalties  MisbehaviourPenalties      `validate:"required" mapstructure:"misbehaviour-penalties"`
}

type SpamRecordCacheDecay 

type SpamRecordCacheDecay struct {
	// PenaltyDecaySlowdownThreshold defines the penalty level which the decay rate is reduced by `DecayRateReductionFactor` every time the penalty of a node falls below the threshold, thereby slowing down the decay process.
	// This mechanism ensures that malicious nodes experience longer decay periods, while honest nodes benefit from quicker decay.
	PenaltyDecaySlowdownThreshold float64 `validate:"lt=0" mapstructure:"penalty-decay-slowdown-threshold"`

	// DecayRateReductionFactor defines the value by which the decay rate is decreased every time the penalty is below the PenaltyDecaySlowdownThreshold. A reduced decay rate extends the time it takes for penalties to diminish.
	DecayRateReductionFactor float64 `validate:"gt=0,lt=1" mapstructure:"penalty-decay-rate-reduction-factor"`

	// PenaltyDecayEvaluationPeriod defines the interval at which the decay for a spam record is okay to be adjusted.
	PenaltyDecayEvaluationPeriod time.Duration `validate:"gt=0" mapstructure:"penalty-decay-evaluation-period"`

	SkipDecayThreshold float64 `validate:"gt=-1,lt=0" mapstructure:"skip-decay-threshold"`

	MinimumSpamPenaltyDecayFactor float64 `validate:"gt=0,lte=1" mapstructure:"minimum-spam-penalty-decay-factor"`
	MaximumSpamPenaltyDecayFactor float64 `validate:"gt=0,lte=1" mapstructure:"maximum-spam-penalty-decay-factor"`
}

type SpamRecordCacheParameters 

type SpamRecordCacheParameters struct {
	// CacheSize is size of the cache used to store the spam records of peers.
	// The spam records are used to penalize peers that send invalid messages.
	CacheSize uint32               `validate:"gt=0" mapstructure:"cache-size"`
	Decay     SpamRecordCacheDecay `validate:"required" mapstructure:"decay"`
}

type SubscriptionProviderParameters 

type SubscriptionProviderParameters struct {
	// UpdateInterval is the interval for updating the list of topics the node have subscribed to; as well as the list of all
	// peers subscribed to each of those topics. This is used to penalize peers that have an invalid subscription based on their role.
	UpdateInterval time.Duration `validate:"gt=0s" mapstructure:"update-interval"`

	// CacheSize is the size of the cache that keeps the list of peers subscribed to each topic as the local node.
	// This is the local view of the current node towards the subscription status of other nodes in the system.
	// The cache must be large enough to accommodate the maximum number of nodes in the system, otherwise the view of the local node will be incomplete
	// due to cache eviction.
	CacheSize uint32 `validate:"gt=0" mapstructure:"cache-size"`
}

type TopicScoringParameters 

type TopicScoringParameters struct {
	// SkipAtomicValidation is the  value for the skip atomic validation flag for topics.
	// If set it to true, the gossipsub parameter validation will not fail if we leave some of the
	// topic parameters at their  values, i.e., zero.
	SkipAtomicValidation bool `validate:"required" mapstructure:"skip-atomic-validation"`
	// InvalidMessageDeliveriesWeight this value is applied to the square of the number of invalid message deliveries on a topic.
	// It is used to penalize peers that send invalid messages. By an invalid message, we mean a message that is not signed by the
	// publisher, or a message that is not signed by the peer that sent it.
	InvalidMessageDeliveriesWeight float64 `validate:"lt=0" mapstructure:"invalid-message-deliveries-weight"`
	// InvalidMessageDeliveriesDecay decay factor used to decay the number of invalid message deliveries.
	// The total number of invalid message deliveries is multiplied by this factor at each heartbeat interval to
	// decay the number of invalid message deliveries, and prevent the peer from being disconnected if it stops
	// sending invalid messages.
	InvalidMessageDeliveriesDecay float64 `validate:"gt=0,lt=1" mapstructure:"invalid-message-deliveries-decay"`
	// TimeInMeshQuantum is the  time in mesh quantum for the GossipSub scoring system. It is used to gauge
	// a discrete time interval for the time in mesh counter.
	TimeInMeshQuantum time.Duration `validate:"gte=1h" mapstructure:"time-in-mesh-quantum"`
	// Weight is the  weight of a topic in the GossipSub scoring system.
	// The overall score of a peer in a topic mesh is multiplied by the weight of the topic when calculating the overall score of the peer.
	TopicWeight float64 `validate:"gt=0" mapstructure:"topic-weight"`
	// MeshMessageDeliveriesDecay is applied to the number of actual message deliveries in a topic mesh
	// at each decay interval (i.e., DecayInterval).
	// It is used to decay the number of actual message deliveries, and prevents past message
	// deliveries from affecting the current score of the peer.
	MeshMessageDeliveriesDecay float64 `validate:"gt=0" mapstructure:"mesh-message-deliveries-decay"`
	// MeshMessageDeliveriesCap is the maximum number of actual message deliveries in a topic
	// mesh that is used to calculate the score of a peer in that topic mesh.
	MeshMessageDeliveriesCap float64 `validate:"gt=0" mapstructure:"mesh-message-deliveries-cap"`
	// MeshMessageDeliveryThreshold is the threshold for the number of actual message deliveries in a
	// topic mesh that is used to calculate the score of a peer in that topic mesh.
	// If the number of actual message deliveries in a topic mesh is less than this value,
	// the peer will be penalized by square of the difference between the actual message deliveries and the threshold,
	// i.e., -w * (actual - threshold)^2 where `actual` and `threshold` are the actual message deliveries and the
	// threshold, respectively, and `w` is the weight (i.e., MeshMessageDeliveriesWeight).
	MeshMessageDeliveryThreshold float64 `validate:"gt=0" mapstructure:"mesh-message-deliveries-threshold"`
	// MeshDeliveriesWeight is the weight for applying penalty when a peer is under-performing in a topic mesh.
	// Upon every decay interval, if the number of actual message deliveries is less than the topic mesh message deliveries threshold
	// (i.e., MeshMessageDeliveriesThreshold), the peer will be penalized by square of the difference between the actual
	// message deliveries and the threshold, multiplied by this weight, i.e., -w * (actual - threshold)^2 where w is the weight, and
	// `actual` and `threshold` are the actual message deliveries and the threshold, respectively.
	MeshDeliveriesWeight float64 `validate:"lt=0" mapstructure:"mesh-deliveries-weight"`
	// MeshMessageDeliveriesWindow is the window size is time interval that we count a delivery of an already
	// seen message towards the score of a peer in a topic mesh. The delivery is counted
	// by GossipSub only if the previous sender of the message is different from the current sender.
	MeshMessageDeliveriesWindow time.Duration `validate:"gte=1m" mapstructure:"mesh-message-deliveries-window"`
	// MeshMessageDeliveryActivation is the time interval that we wait for a new peer that joins a topic mesh
	// till start counting the number of actual message deliveries of that peer in that topic mesh.
	MeshMessageDeliveryActivation time.Duration `validate:"gte=2m" mapstructure:"mesh-message-delivery-activation"`
}

TopicScoringParameters score option topic validation configuration parameters.

type Truncate added in v0.33.30 

type Truncate struct {
	// Disabled serves as a fail-safe mechanism to globally deactivate truncation logic. When this fail-safe is activated it disables all
	// aspects of the truncation logic, irrespective of individual configurations like truncation.enable-graft, truncation.enable-prune, etc.
	// Consequently, all metrics collection and logging related to the rpc and inspection will also be disabled.
	// It is important to note that activating this fail-safe results in a comprehensive deactivation truncation features.
	// Please use this setting judiciously, considering its broad impact on the behavior of control message handling.
	Disabled bool `mapstructure:"disabled"`
	// EnableGraft enable graft control message truncation.
	EnableGraft bool `mapstructure:"enable-graft"`
	// EnablePrune enable prune control message truncation.
	EnablePrune bool `mapstructure:"enable-prune"`
	// EnableIHave enable iHave control message truncation.
	EnableIHave bool `mapstructure:"enable-ihave"`
	// EnableIHaveMessageIds enable iHave message id truncation.
	EnableIHaveMessageIds bool `mapstructure:"enable-ihave-message-id"`
	// EnableIWant enable iWant control message truncation.
	EnableIWant bool `mapstructure:"enable-iwant"`
	// EnableIWantMessageIds enable iWant message id truncation.
	EnableIWantMessageIds bool `mapstructure:"enable-iwant-message-id"`
}

Truncate configuration to enable/disable RPC truncation for a particular control message type.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.