model

Documentation

Index

• Constants
• type ProtocolSpamRecord
• type RecordAdjustFunc
• type SpamRecordFactoryFunc
  • func SpamRecordFactory() SpamRecordFactoryFunc

Constants

const (
	// DisallowListingThreshold is the threshold for concluding a node behavior is malicious and disallow-listing the node.
	// If the overall penalty of this node drops below this threshold, the node is reported to be disallow-listed by
	// the networking layer, i.e., existing connections to the node are closed and the node is no longer allowed to connect till
	// its penalty is decayed back to zero.
	// maximum block-list period is 1 day
	DisallowListingThreshold = -24 * 60 * 60 // (Don't change this value)

	// DefaultPenaltyValue is the default penalty value for misbehaving nodes.
	// By default, each reported infringement will be penalized by this value. However, the penalty can be amplified
	// by the engine that reports the misbehavior. The penalty system is designed in a way that more than 100 misbehaviors/sec
	// at the default penalty value will result in disallow-listing the node. By amplifying the penalty, the engine can
	// decrease the number of misbehaviors/sec that will result in disallow-listing the node. For example, if the engine
	// amplifies the penalty by 10, the number of misbehaviors/sec that will result in disallow-listing the node will be
	// 10 times less than the default penalty value and the node will be disallow-listed after 10 misbehaviors/sec.
	DefaultPenaltyValue = 0.01 * DisallowListingThreshold // (Don't change this value)

	// InitialDecaySpeed is the initial decay speed of the penalty of a misbehaving node.
	// The decay speed is applied on an arithmetic progression. The penalty value of the node is the first term of the
	// progression and the decay speed is the common difference of the progression, i.e., p(n) = p(0) + n * d, where
	// p(n) is the penalty value of the node after n decay intervals, p(0) is the initial penalty value of the node, and
	// d is the decay speed. Decay intervals are set to 1 second (protocol invariant). Hence, with the initial decay speed
	// of 1000, the penalty value of the node will be decreased by 1000 every second. This means that if a node misbehaves
	// 100 times in a second, it gets disallow-listed, and takes 86.4 seconds to recover.
	// In mature implementation of the protocol, the decay speed of a node is decreased by 90% each time the node is
	// disallow-listed. This means that if a node is disallow-listed for the first time, it takes 86.4 seconds to recover.
	// If the node is disallow-listed for the second time, its decay speed is decreased by 90% from 1000 to 100, and it
	// takes around 15 minutes to recover. If the node is disallow-listed for the third time, its decay speed is decreased
	// by 90% from 100 to 10, and it takes around 2.5 hours to recover. If the node is disallow-listed for the fourth time,
	// its decay speed is decreased by 90% from 10 to 1, and it takes around a day to recover. From this point on, the decay
	// speed is 1, and it takes around a day to recover from each disallow-listing.
	InitialDecaySpeed = 1000 // (Don't change this value)
)

To give a summary with the default value:

1. The penalty of each misbehavior is 0.01 * DisallowListingThreshold = -864
2. The penalty of each misbehavior is decayed by a decay value at each decay interval. The default decay value is 1000. This means that by default if a node misbehaves 100 times in a second, it gets disallow-listed, and takes 86.4 seconds to recover. We emphasize on the default penalty value can be amplified by the engine that reports the misbehavior.
3. Each time a node is disallow-listed, its decay speed is decreased by 90%. This means that if a node is disallow-listed for the first time, it takes 86.4 seconds to recover. If the node is disallow-listed for the second time, its decay speed is decreased by 90% from 1000 to 100, and it takes around 15 minutes to recover. If the node is disallow-listed for the third time, its decay speed is decreased by 90% from 100 to 10, and it takes around 2.5 hours to recover. If the node is disallow-listed for the fourth time, its decay speed is decreased by 90% from 10 to 1, and it takes around a day to recover. From this point on, the decay speed is 1, and it takes around a day to recover from each disallow-listing.

Types

type ProtocolSpamRecord

type ProtocolSpamRecord struct {
	// OriginId is the node id of the misbehaving node. It is assumed an authorized (i.e., staked) node at the
	// time of the misbehavior report creation (otherwise, the networking layer should not have dispatched the
	// message to the Flow protocol layer in the first place).
	OriginId flow.Identifier

	// Decay speed of Penalty for this misbehaving node. Each node may have a different Decay speed based on its behavior.
	// Subsequent disallow listings of the node will decrease the Decay speed of the node so it will take longer to be allow-listed.
	Decay float64

	// CutoffCounter is a counter that is used to determine how many times the connections to the node has been cut due to
	// its Penalty value dropping below the disallow-listing threshold.
	// Note that the cutoff connections are recovered after a certain amount of time.
	CutoffCounter uint64

	// DisallowListed indicates whether the node is currently disallow-listed or not. When a node is in the disallow-list,
	// the existing connections to the node are cut and no new connections are allowed to be established, neither incoming
	// nor outgoing.
	DisallowListed bool

	// total Penalty value of the misbehaving node. Should be a negative value.
	Penalty float64
}

ProtocolSpamRecord is a record of a misbehaving node. It is used to keep track of the Penalty value of the node and the number of times it has been slashed due to its Penalty value dropping below the disallow-listing threshold.

type RecordAdjustFunc

type RecordAdjustFunc func(ProtocolSpamRecord) (ProtocolSpamRecord, error)

RecordAdjustFunc is a function that is used to adjust the fields of a ProtocolSpamRecord. The function is called with the current record and should return the adjusted record. Returned error indicates that the adjustment is not applied, and the record should not be updated. In BFT setup, the returned error should be treated as a fatal error.

type SpamRecordFactoryFunc

type SpamRecordFactoryFunc func(flow.Identifier) ProtocolSpamRecord

SpamRecordFactoryFunc is a function that creates a new protocol spam record with the given origin id and initial values. Args: - originId: the origin id of the spam record. Returns: - ProtocolSpamRecord, the created record.

func SpamRecordFactory

func SpamRecordFactory() SpamRecordFactoryFunc

SpamRecordFactory returns the default factory function for creating a new protocol spam record. Returns: - SpamRecordFactoryFunc, the default factory function. Note that the default factory function creates a new record with the initial values.