What does the peer reputation value correspond to?

Question

When inspecting the peer reputation of the connected peers, they can have a very wide range a value, how can it be interpreted ?

Answer 1

To inspect the peer reputation of connected peers when running a collator node using the substrate-node-template it was necessary to log trace events from the logs:

RUST_LOG=trace RUST_BACKTRACE=1 <INSERT_PATH_NODE_BINARY>/parachain-collator <INSERT_OPTIONS_ARGS_SUBCOMMANDS>

Examples of various collator node logs that mention the peer reputation values ranges (i.e. x to y) include:

<DATE_TIME> TRACE tokio-runtime-worker peerset: [Relaychain] Dropping <PEER_NODE_IDENTITY>: -256 to -256
<DATE_TIME> TRACE tokio-runtime-worker peerset: [Relaychain] Report : +100 to -156. Reason: Grandpa: Neighbor message    
<DATE_TIME> TRACE tokio-runtime-worker peerset: [Relaychain] Report <PEER_NODE_IDENTITY>: -16 to 82. Reason: Any transaction    
<DATE_TIME> TRACE tokio-runtime-worker peerset: [Relaychain] Report <PEER_NODE_IDENTITY>: -4096 to -4014. Reason: Bad transaction 
<DATE_TIME> TRACE tokio-runtime-worker peerset: [Relaychain] Fleeting <PEER_NODE_IDENTITY>: -156 -> -153  
<DATE_TIME> TRACE tokio-runtime-worker peerset: [Parachain] Fleeting <PEER_NODE_IDENTITY>: -156 -> -153

To find out what the peer reputation values and reasons in the logs mean, it was necessary to refer to the Substrate source code and documentation:

A search for the keyword "reputation" in the Substrate Rust Docs here shows that peer reputation of a PeerId (peer node identity) is handled by the sc_network, sc_service, and sc_peerset Rust crates.

In the documentation it says that reputation changes are accrued and applied to the PeerId sending a request. They are stored in a vector of the Struct ReputationChange, which is the description of a reputation adjustment for a node, which includes the fields peer reputation delta (change) value of type i32, and the reason for the reputation change of type string.

It shows the implementation includes a function new_fatal(reason: &'static str) -> ReputationChange that accepts a reason for the new reputation change that forces minimum possible reputation. Examples of the reasons for these reputation changes are in the Substrate source code as Rep::new_fatal(<REASON>), such as when a peer sent us the same (block) request multiple times, when the peer is using an unsupported protocol version, when the peer roles that are trying to connect do not match each other, or when a peer id provides an invalid justification to import a block hash. However, since this function forces minimum possible reputation it doesn't need to accept a fields with a peer reputation delta (change) value.

Whereas for implementations of the function new(value: i32, reason: &'static str) -> ReputationChange in the Substrate source code as Rep::new(<PEER_REPUTATION_CHANGE>, <REASON>), the first argument accepts a peer reputation delta (change) value, and the 2nd argument accepts the reason for the change.

To interpret the trace log above ...Dropping <PEER_NODE_IDENTITY>: -256 to -256:

We can see in the Substrate source code here that we call function add_reputation that performs an arithmetic addition on the reputation score of that peer with value DISCONNECT_REPUTATION_CHANGE of -256 to reduce the reputation of a peer node by that value because we got disconnected from it.

The peer reputation that is shown in the logs as -256 to -256 is generated from the 2nd and 3rd arguments of the trace log code in the peerset dropped function of the Substrate source code, as shown below, where the 2nd argument is the reputation change to apply to the peer node that dropped, and the 3rd argument is the existing current reputation of that peer node.

trace!(target: "peerset", "Dropping {}: {:+} to {}", peer_id, DISCONNECT_REPUTATION_CHANGE, entry.reputation());

So the trace log <DATE_TIME> TRACE tokio-runtime-worker peerset: [Relaychain] Dropping <PEER_NODE_IDENTITY>: -256 to -256 can be interpreted in English as "at this date and time a relay chain node used the peerset crate to report in the network trace logs that peer node with identity <PEER_NODE_IDENTITY> got disconnected from the relay chain so the peer had its reputation reduced by the reputation change value of -256, so its new reputation is -256", so in this case prior to dropping the peer node had a reputation of 0.

To interpret the trace log above ...Report <PEER_NODE_IDENTITY>: -4096 to -4014. Reason: Bad transaction:

If you do a search of the Substrate source code you will find the report is triggered by the report_peer function here when importing a bad transaction that was sent from a peer, where BAD_TRANSACTION is declared here with the reputation change to apply to the peer and the reason for the change Rep = Rep::new(-(1 << 12), "Bad transaction"), so since their new reputation after applying the reputation change to their reputation must have been greater than or equal to the BANNED_THRESHOLD, we don't drop that peer yet, but we report that their reputation was reduced by -4096 and their new reputation is -4014. So prior to applying that reputation change their reputation must have been x, where (x - 4096 = -4014), so x = 82.

The reason why the reputation change is -4096, is because the -(1 << 12) argument is provided to the new function as the peer reputation change value, which is a bitwise left shift operation (<<), where you get the binary value of 1 (0000000000001) then shift it left 12 times so it becomes 1000000000000, and then convert that binary value to its decimal equivalent of 4096.