Warning: This feature is considered experimental, do not use it in production yet.
The main objective of the Peer Scoring System is to protect the RSK node’s resources from abusive or malicious peers. For this, the RSK node keeps track of a reputation for each peer that connects to it and disconnects those whose current reputation falls below acceptable levels.
There are three possible actions that the Peer Scoring system can perform:
All event-firing scenarios will start by the node receiving a message from a peer.
All messages are automatically recorded as events. However, for the current version, only some of them have a negative impact on the peer’s reputation. These events are:
INVALID_NETWORK
: This occurs when the received network ID is different from the network ID of the node.INVALID_BLOCK
: This happens when the received block is not valid as per RSK block validation requirements.INVALID_MESSAGE
: This happens when the message received is not valid as per RSK message validation requirements.If one of these events is recorded, the peer’s reputation will be marked accordingly, and the penalisation process will start automatically. This occurs only in nodes where the peer scoring feature is enabled.
A peer with a bad reputation will be punished, meaning that when the node receives a message from it, the peer will be automatically disconnected and the received message will be discarded. Penalties are applied at two levels:
address
, andnodeID
.The default duration for the first punishment is 10 minutes. This can be changed via the RSK node configuration:
scoring.addresses.duration
for address
levelscoring.nodes.duration
for nodeID
levelThese values are specified in minutes.
It is worth mentioning that penalty duration will be incremented by a percentage value each time a penalty is applied to a peer. The default increase rate is 10%. This can be changed via the RSK node configuration:
scoring.addresses.increment
for address
levelscoring.nodes.increment
for nodeID
levelIt is possible to define a maximum time for a node to stay in a penalised state,
which defaults to 7 days for address
level and 0 (unlimited) for nodeID
level.
This can be changed via the RSK node configuration:
scoring.addresses.maximum
for address
levelscoring.nodes.maximum
for nodeID
levelThese values are specified in minutes.
A banned peer is considered as a peer with a bad reputation. Therefore, it will be disconnected the next time a message is received, and its messages will be discarded. However, the action of banning a peer, unlike the RSK nodes’s automatic reputation tracking, is a manual action.
In order to manually ban or unban a peer, this can be done by address, the following RPC methods should be used:
sco_banAddress(String address)
:
sco_unbanAddress(String address)
:
To check what addresses are banned, use the following method:
sco_bannedAddresses()
:
Warning: These methods should be used with caution.
This can be changed via the RSK node configuration:
scoring.punishmentEnabled
This value is specified as a boolean.
Warning: The recommendation is to keep the defaults, this is a complex and powerful feature that should be used with caution.
The following related RPC methods are available.
sco_banAddress(String address)
: see Manually banning of peer nodes.sco_unbanAddress(String address)
: see Manually banning of peer nodes.sco_bannedAddresses()
: see Manually banning of peer nodes.sco_peerList()
: Returns the collected peer scoring informationsco_reputationSummary()
: Returns the reputation summary of all the peers connectedsco_clearPeerScoring(String id)
: Clears scoring for the received id (firstly tried as an address, used as a nodeID otherwise).Please note the default and recommended config is to NOT expose these methods publicly.
Go to top