# PeerScoring/Reputation in substrate

Peer scoring tells about the reputation of the connected peers, Reputation value of the node, between `i32::MIN` (we hate that node) and `i32::MAX` (we love that node).
The node start with the reputation of 0 through [discover](https://github.com/paritytech/substrate/blob/master/client/peerset/src/peersstate.rs#L582) method. First the reserved peers will be added to the peerset that could be provided by bootnodes. The peerscore/reputation helps to identify and request network, whether we need to connect the peer or disconnect the peer, also to accept or reject the incoming peer connection request. This will help to setup the connection to the best reputated peers, which will provide the favourable data to us. If any connected peers misbehaves, The PSM Peer set manager identifies it and decrease the reputation of the peer. Also, If the remote peers sits idle we are decaying the reputation every seconds. To be the good reputated peer it need to work and send good and favourable messages to us.

Substrate is avoiding the 32-second "try to connect to some nodes" construct.

Instead:

Split the peer slots into three parts:
- **Reserved** (peers that have been passed by the --reserved flag - they get their own special slots and should be continuously, though responsibly, (re)connected to)
- **Outgoing** (number of slots == min_peers, these are connections to nodes that we discover/remember and initiate)
- **Incoming** (number of slots == max_peers - min_peers, these are inbound connections from nodes that have discovered us)

### Regarding Outgoing peers:

- We start by connecting to up to min_peers nodes; they each take a slot in our Outgoing peer table.
- We attempt to connect to a (/the highest scoring, once reputation system is done) node when one of the following happens:
- A previous connection to a node has failed.
- A peer who was in the Outgoing table has been/become disconnected.
- We have discovered new nodes and have slots free in the Outgoing peer table.
- The backoff timer of a previous node has expired and we can retry connecting.

### PeerSet
Peerset data structure is used to manage PSM flow. Data in PeerSet containg Node which have reputation value.

**Peer Set Manager (PSM)**. Contains the strategy for choosing which nodes the network should be connected to.
- The PSM handles *sets* of nodes. A set of nodes is defined as the nodes that are believed to support a certain capability, such as handling blocks and transactions of a specific chain, or collating a certain parachain.
- For each node in each set, the peerset holds a flag specifying whether the node is connected to us or not.
- This connected/disconnected status is specific to the node and set combination, and it is for example possible for a node to be connected through a specific set but not another.
- In addition, for each, set, the peerset also holds a list of reserved nodes towards which it will at all time try to maintain a connection with.

Reputation and slots allocation system behind the peerset.
The [PeersState] state machine is responsible for managing the reputation and allocating slots. It holds a list of nodes, each associated with a reputation value, a list of sets the node belongs to, and for each set whether we are connected or not to this node. Thanks to this list, it knows how many slots are occupied. It also holds a list of nodes which don't occupy slots.
Note: This module is purely dedicated to managing slots and reputations. Features such as for example connecting to some nodes in priority should be added outside of this module, rather than inside.

The PSM is now composed of a PeersState data structure (in peersstate.rs) that just holds the state of each peer (their reputation, whether they are connected, whether they are reserved), plus a few utility functions.

pub struct Peerset {
	/// Underlying data structure for the nodes's states.
	data: peersstate::PeersState,
	/// For each set, lists of nodes that don't occupy slots and that we should try to always be
	/// connected to, and whether only reserved nodes are accepted. Is kept in sync with the list
	/// of non-slot-occupying nodes in [`Peerset::data`].
	reserved_nodes: Vec<(HashSet<PeerId>, bool)>,
	/// Receiver for messages from the `PeersetHandle` and from `tx`.
	rx: TracingUnboundedReceiver<Action>,
	/// Sending side of `rx`.
	tx: TracingUnboundedSender<Action>,
	/// Queue of messages to be emitted when the `Peerset` is polled.
	message_queue: VecDeque<Message>,
	/// When the `Peerset` was created.
	created: Instant,
	/// Last time when we updated the reputations of connected nodes.
	latest_time_update: Instant,
	/// Next time to do a periodic call to `alloc_slots` with all sets. This is done once per
	/// second, to match the period of the reputation updates.
	next_periodic_alloc_slots: Delay,
}

/// State storage behind the peerset.
///
/// # Usage
///
/// This struct is nothing more but a data structure containing a list of nodes, where each node
/// has a reputation and is either connected to us or not.
#[derive(Debug, Clone)]
pub struct PeersState {
	/// List of nodes that we know about.
	///
	/// > **Note**: This list should really be ordered by decreasing reputation, so that we can
	///           easily select the best node to connect to. As a first draft, however, we don't
	///           sort, to make the logic easier.
	nodes: HashMap<PeerId, Node>,

	/// Configuration of each set. The size of this `Vec` is never modified.
	sets: Vec<SetInfo>,
}

/// State of a single node that we know about.
#[derive(Debug, Clone, PartialEq, Eq)]
struct Node {
	/// List of sets the node belongs to.
	/// Always has a fixed size equal to the one of [`PeersState::set`]. The various possible sets
	/// are indices into this `Vec`.
	sets: Vec<MembershipState>,

	/// Reputation value of the node, between `i32::MIN` (we hate that node) and
	/// `i32::MAX` (we love that node).
	reputation: i32,
}
/// Whether we are connected to a node in the context of a specific set.
enum MembershipState {
	/// Node isn't part of that set.
	NotMember,
	/// We are connected through an ingoing connection.
	In,
	/// We are connected through an outgoing connection.
	Out,
	/// Node is part of that set, but we are not connected to it.
	NotConnected {
		/// When we were last connected to the node, or if we were never connected when we
		/// discovered it.
		last_connected: Instant,
	},
}

ReputationChange which are responsible to increase and decrease the reputations of the peers are as follow. These values will be added to the current peer reputation. The reputation value will be transaferred through channel using `report_peer` method. The ReportPeer will leads to call on_report_peers which add the reputation to the peer reputation. If the updated peer is not under BANNED_THRESHOLD, and peerstate is in connected status then it will be updated to disconnected state. Also, try to fill available out slots with nodes for the given set

TODO: ~~Below reputation values need to be analyzed how it is updating the reputationg values. Whether it's adding the calculated value to the current reputation or it is putting the calculated values.~~ Also, How the negative values helping the peer scoring.

//sync.rs
        pub const BLOCKCHAIN_READ_ERROR: Rep = Rep::new(-(1 << 16), "DB Error");

	/// Reputation change when a peer sent us a status message with a different
	/// genesis than us.
	pub const GENESIS_MISMATCH: Rep = Rep::new(i32::MIN, "Genesis mismatch");

	/// Reputation change for peers which send us a block with an incomplete header.
	pub const INCOMPLETE_HEADER: Rep = Rep::new(-(1 << 20), "Incomplete header");

	/// Reputation change for peers which send us a block which we fail to verify.
	pub const VERIFICATION_FAIL: Rep = Rep::new(-(1 << 29), "Block verification failed");

	/// Reputation change for peers which send us a known bad block.
	pub const BAD_BLOCK: Rep = Rep::new(-(1 << 29), "Bad block");

	/// Peer did not provide us with advertised block data.
	pub const NO_BLOCK: Rep = Rep::new(-(1 << 29), "No requested block data");

	/// Reputation change for peers which send us non-requested block data.
	pub const NOT_REQUESTED: Rep = Rep::new(-(1 << 29), "Not requested block data");

	/// Reputation change for peers which send us a block with bad justifications.
	pub const BAD_JUSTIFICATION: Rep = Rep::new(-(1 << 16), "Bad justification");

	/// Reputation change when a peer sent us invlid ancestry result.
	pub const UNKNOWN_ANCESTOR: Rep = Rep::new(-(1 << 16), "DB Error");

	/// Peer response data does not have requested bits.
	pub const BAD_RESPONSE: Rep = Rep::new(-(1 << 12), "Incomplete response");
    
    //mod.rs
    
    // cost scalars for reporting peers.
mod cost {
	use sc_network::ReputationChange as Rep;
	pub(super) const PAST_REJECTION: Rep = Rep::new(-50, "Grandpa: Past message");
	pub(super) const BAD_SIGNATURE: Rep = Rep::new(-100, "Grandpa: Bad signature");
	pub(super) const MALFORMED_CATCH_UP: Rep = Rep::new(-1000, "Grandpa: Malformed cath-up");
	pub(super) const MALFORMED_COMMIT: Rep = Rep::new(-1000, "Grandpa: Malformed commit");
	pub(super) const FUTURE_MESSAGE: Rep = Rep::new(-500, "Grandpa: Future message");
	pub(super) const UNKNOWN_VOTER: Rep = Rep::new(-150, "Grandpa: Unknown voter");

	pub(super) const INVALID_VIEW_CHANGE: Rep = Rep::new(-500, "Grandpa: Invalid view change");
	pub(super) const PER_UNDECODABLE_BYTE: i32 = -5;
	pub(super) const PER_SIGNATURE_CHECKED: i32 = -25;
	pub(super) const PER_BLOCK_LOADED: i32 = -10;
	pub(super) const INVALID_CATCH_UP: Rep = Rep::new(-5000, "Grandpa: Invalid catch-up");
	pub(super) const INVALID_COMMIT: Rep = Rep::new(-5000, "Grandpa: Invalid commit");
	pub(super) const OUT_OF_SCOPE_MESSAGE: Rep = Rep::new(-500, "Grandpa: Out-of-scope message");
	pub(super) const CATCH_UP_REQUEST_TIMEOUT: Rep =
		Rep::new(-200, "Grandpa: Catch-up request timeout");

	// cost of answering a catch up request
	pub(super) const CATCH_UP_REPLY: Rep = Rep::new(-200, "Grandpa: Catch-up reply");
	pub(super) const HONEST_OUT_OF_SCOPE_CATCH_UP: Rep =
		Rep::new(-200, "Grandpa: Out-of-scope catch-up");
}
        
        
        // benefit scalars for reporting peers.
mod benefit {
	use sc_network::ReputationChange as Rep;
	pub(super) const NEIGHBOR_MESSAGE: Rep = Rep::new(100, "Grandpa: Neighbor message");
	pub(super) const ROUND_MESSAGE: Rep = Rep::new(100, "Grandpa: Round message");
	pub(super) const BASIC_VALIDATED_CATCH_UP: Rep = Rep::new(200, "Grandpa: Catch-up message");
	pub(super) const BASIC_VALIDATED_COMMIT: Rep = Rep::new(100, "Grandpa: Commit");
	pub(super) const PER_EQUIVOCATION: i32 = 10;
}

        

Reputation change when a peer sends us a gossip message that we didn't know about and change for a peer when a request timed out.

// state_machine.rs
	use sc_network::ReputationChange as Rep;
	/// Reputation change when a peer sends us a gossip message that we didn't know about.
	pub const GOSSIP_SUCCESS: Rep = Rep::new(1 << 4, "Successfull gossip");
	/// Reputation change when a peer sends us a gossip message that we already knew about.
	pub const DUPLICATE_GOSSIP: Rep = Rep::new(-(1 << 2), "Duplicate gossip");
    
    //handle.rs
    //lightclient handle
    vec![ReputationChange::new(-(1 << 12), "bad request")]
    
    
    //sender.rs
    
	/// Reputation change for a peer when a request timed out.
	pub const TIMEOUT: ReputationChange =
		ReputationChange::new(-(1 << 8), "light client request timeout");
	/// Reputation change for a peer when a request is refused.
	pub const REFUSED: ReputationChange =
		ReputationChange::new(-(1 << 8), "light client request refused");

Reputation change when a peer doesn't respond in time to our messages.

        //protocol.rs
        
	/// Reputation change when a peer doesn't respond in time to our messages.
	pub const TIMEOUT: Rep = Rep::new(-(1 << 10), "Request timeout");
	/// Reputation change when a peer refuses a request.
	pub const REFUSED: Rep = Rep::new(-(1 << 10), "Request refused");
	/// Reputation change when we are a light client and a peer is behind us.
	pub const PEER_BEHIND_US_LIGHT: Rep = Rep::new(-(1 << 8), "Useless for a light peer");
	/// We received a message that failed to decode.
	pub const BAD_MESSAGE: Rep = Rep::new(-(1 << 12), "Bad message");
	/// Peer has different genesis.
	pub const GENESIS_MISMATCH: Rep = Rep::new_fatal("Genesis mismatch");
	/// Peer is on unsupported protocol version.
	pub const BAD_PROTOCOL: Rep = Rep::new_fatal("Unsupported protocol");
	/// Peer role does not match (e.g. light peer connecting to another light peer).
	pub const BAD_ROLE: Rep = Rep::new_fatal("Unsupported role");
	/// Peer send us a block announcement that failed at validation.
	pub const BAD_BLOCK_ANNOUNCEMENT: Rep = Rep::new(-(1 << 12), "Bad block announcement");
    

Reputation change when a peer sends us any transaction. Here, ANY_TRANSACTION will

    //transaction.rs
    	use sc_peerset::ReputationChange as Rep;
	/// Reputation change when a peer sends us any transaction.
	///
	/// This forces node to verify it, thus the negative value here. Once transaction is verified,
	/// reputation change should be refunded with `ANY_TRANSACTION_REFUND`
	pub const ANY_TRANSACTION: Rep = Rep::new(-(1 << 4), "Any transaction");
	/// Reputation change when a peer sends us any transaction that is not invalid.
	pub const ANY_TRANSACTION_REFUND: Rep = Rep::new(1 << 4, "Any transaction (refund)");
	/// Reputation change when a peer sends us an transaction that we didn't know about.
	pub const GOOD_TRANSACTION: Rep = Rep::new(1 << 7, "Good transaction");
	/// Reputation change when a peer sends us a bad transaction.
	pub const BAD_TRANSACTION: Rep = Rep::new(-(1 << 12), "Bad transaction");
	/// We received an unexpected transaction packet.
	pub const UNEXPECTED_TRANSACTIONS: Rep = Rep::new_fatal("Unexpected transactions packet");
    

### Updating peerscore/Reputation towards zero with elapsing time
The peers reputation decreases towards 0 over time. If the reputation decreases towards 0 and deletion of peer as connected Time + FORGET_TIME exceeds.
- `update_time` basically runs a loop for each elapsed second, move the node reputation towards zero with elapsing time.
- If we multiply each second the reputation by `k` (where `k` is between 0 and 1), it takes `ln(0.5) / ln(k)` seconds to reduce the reputation by half. Use this formula to empirically determine a value of `k` that looks correct.
- We use `k = 0.98`, so we divide by `50`. With that value, it takes 34.3 seconds to reduce the reputation by half.
- If the peer reaches a reputation of 0, and there is no connection to it during (last connected time + FORGET_TIME),forget it. The `forget_peers()` removes the peer from the list of members of the set. This will remove the peer node from map of peerState.nodes.
- If the node is node is not connected and the reputation is 0, This node will resides in peerset till the connected Time + FORGET_TIME exceeds.

### Slot Allocation and Deallocation
- We don't [allocate slot](https://github.com/paritytech/substrate/blob/5be50ac14b23147c6f120745c2205a86a2675169/client/peerset/src/lib.rs#L537) for the nodes whose reputation is under [BANNED_THRESHOLD](https://github.com/paritytech/substrate/blob/5be50ac14b23147c6f120745c2205a86a2675169/client/peerset/src/lib.rs#L52)
- If we have a [incoming connection](https://github.com/paritytech/substrate/blob/5be50ac14b23147c6f120745c2205a86a2675169/client/peerset/src/lib.rs#L624) request from a node whose reputation is under BANNED_THRESHOLD, Then we send [reject message](https://github.com/paritytech/substrate/blob/5be50ac14b23147c6f120745c2205a86a2675169/client/peerset/src/lib.rs#L192) to the node.
- While dropping a connection to a node, we will change the reputation to -256 [`DISCONNECT_REPUTATION_CHANGE`](https://github.com/paritytech/substrate/blob/5be50ac14b23147c6f120745c2205a86a2675169/client/peerset/src/lib.rs#L646)

[#394](https://github.com/paritytech/substrate/pull/394)
There is always a reason given when calling reporting `report_peers`, and that reason implies a Severity, which semantically informs substrate-libp2p on what course of action to take in response (e.g. lowering a reputation score, simple disconnect, temporary ban or permanent ban).

### Message by peerset

[Message](https://github.com/paritytech/substrate/blob/master/client/peerset/src/lib.rs#L172) that can be sent by PSM Peerset manager to the network package in order to perform following actions.
- **Connect:** Request to open a connection to the given peer. From the point of view of the PSM, we are immediately connected.
- **Drop:** Drop the connection to the given peer, or cancel the connection attempt after a `Connect`.
- **Accept:** Equivalent to `Connect` for the peer corresponding to the incoming index.
- **Reject:** Equivalent to `Drop` for the peer corresponding to this incoming index.

If the peer score is not good enough to be connected, Then PSM sends a request to DROP the connection with the peer.

**Outgoing Peers:** While filling available slots in `alloc_slots` with peers, The network package got a request from peer state to **Connect** the peer.

**Incoming Peers:** While filling available slots in `alloc_slots` with peers,It tries to accept the peer as an incoming connection.If there are enough slots available, switches the node to "connected" and returns Ok. If the slots are full, the node stays "not connected" and we return Err. For Ok network package gets **Accept** request from PSM to accept the peer request else, gets the **Reject** request from PSM to reject the incomming connection.
Non-slot-occupying nodes don't count towards the number of slots.

Network package handles the request [here](https://github.com/paritytech/substrate/blob/master/client/network/src/protocol/notifications/behaviour.rs#L2036).

### Network behaviour that handles opening substreams for custom protocols with other peers.

# How it works

The role of the `Notifications` is to synchronize the following components:

- The libp2p swarm that opens new connections and reports disconnects.
- The connection handler (see `group.rs`) that handles individual connections.
- The peerset manager (PSM) that requests links to peers to be established or broken.
- The external API, that requires knowledge of the links that have been established.

In the state machine below, each `PeerId` is attributed one of these states:

- [`PeerState::Requested`]: No open connection, but requested by the peerset. Currently dialing.
- [`PeerState::Disabled`]: Has open TCP connection(s) unbeknownst to the peerset. No substream
is open.
- [`PeerState::Enabled`]: Has open TCP connection(s), acknowledged by the peerset.
- Notifications substreams are open on at least one connection, and external
API has been notified.
- Notifications substreams aren't open.
- [`PeerState::Incoming`]: Has open TCP connection(s) and remote would like to open substreams.
Peerset has been asked to attribute an inbound slot.

In addition to these states, there also exists a "banning" system. If we fail to dial a peer, we back-off for a few seconds. If the PSM requests connecting to a peer that is currently backed-off, the next dialing attempt is delayed until after the ban expires. However, the PSM will still consider the peer to be connected. This "ban" is thus not a ban in a strict sense: if a backed-off peer tries to connect, the connection is accepted. A ban only delays dialing attempts.

There may be multiple connections to a peer. The status of a peer on the API of this behaviour and towards the peerset manager is aggregated in the following way:

1. The enableddisabled status is the same across all connections, as decided by the peerset manager.
2. `send_packet` and `write_notification` always send all data over the same connection to preserve the ordering provided by the transport, as long as that connection is open. If it closes, a second open connection may take over, if one exists, but that case should be no different than a single connection failing and being re-established
in terms of potential reordering and dropped messages. Messages can be received on any connection.
3. The behaviour reports `NotificationsOut::CustomProtocolOpen` when the first connection reports `NotifsHandlerOut::OpenResultOk`.
4. The behaviour reports `NotificationsOut::CustomProtocolClosed` when the last connection reports `NotifsHandlerOut::ClosedResult`.

In this way, the number of actual established connections to the peer is an implementation detail of this behaviour. Note that, in practice and at the time of this writing, there may be at most two connections to a peer and only as a result of simultaneous dialing. However, the implementation accommodates for any number of connections.

Network protocol uses [peerset_handle](https://github.com/paritytech/substrate/blob/master/client/network/src/protocol.rs#L176) used to report changes. Peersethandle is a data structure with its implementation required to pass the message to the PSM manager in order to perform following actions as below,
- AddReservedPeer
- RemoveReservedPeer
- SetReservedPeers
- SetReservedOnly
- ReportPeer
- AddToPeersSet
- RemoveFromPeersSet

Side of the peer set manager owned by the network. In other words, the "receiving" side. Implements the Stream trait and can be polled for messages. The Stream never ends and never errors.
This peersetHandle is used in Network Behaviour Service. This handler is used by many service like grandpa, transactions, sync etc in order to report peers (ReportPeer) score if it misbehaves during the service execution. The peerset polling loop receives the transmitted message and perform corresponding operation that is implemented in peerSet implementation.