# Gossipsub Topic Scoring Parameters for Eth2

## Resources

- Blacktemplar's parameter [spreadsheet](https://docs.google.com/spreadsheets/d/1y0DalL4PVBodg1wLlvXjJcnbItwmSmiHdd4z2TTYiNY/edit?usp=sharing)
- [Gossipsub v1.1 spec](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md)

## Overview

This document outlines the basic principles of the gossipsub scoring parameters and how they are calculated and their specific application to an Ethereum 2.0 Network. It provides a more "consumable" form of the parameters and how we got to their value.

**Note:** These are initial values based on theoretical expected numbers and are likely to change during further simulations.

### General Gossipsub Parameters

This gives an overview of the general parameters, and expected values for the Ethereum 2.0 network. These help form the basic structure of the mesh network in gossipsub and apply globally to all peers regardless of topic. These are work regardless of whether scoring is enabled.

| Parameter | Value | Description |
| -------- | -------- | -------- |
| D_low | 6 | Mesh maintenance - Finds more peers below this value |
| D | 8 | Mesh maintenance - Target peers in the mesh|
| D_high | 12 | Mesh maintenance - Remove peers above this value|
| D_lazy | 8 | Minimum number of peers to gossip to (if they exist)|

Hopefully these are straightforward and the values given here should suit our needs. I've excluded some of the ones we have in the spec already.

Below are the general gossipsub v1.1 parameters.

| Parameter | Value | Description |
| -------- | -------- | -------- |
| Prune Backoff | 1 min | The amount of time a peer must wait before regrafting to the mesh once being pruned |
| Flood publish | True | When publishing a message we send to all known peers of a topic not just those in the mesh (this should help message propagation) |
| Gossip factor | 0.25 | The factor of peers to gossip to during a round. With `D_lazy` as a minimum. [See here](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#adaptive-gossip-dissemination) for further info|
| D_score | 4 | When pruning the mesh due to oversubscription, we keep this many highest-scoring peers. |
| D_out | 2 | When pruning the mesh due to oversubscription, we keep this many outbound connected peers. |
| Peers_in_PX | 16 | The maximum number of alternate peers a peer can connect to when being pruned (not applicable in rust-libp2p currently) |
| Graft Flood Threshold | 10 secs | Extra penalty if a peer grafts before this time |
| Opportunistic graft ticks | 85 | Number of heartbeats before attempting opportunistic grafting (this is where we look for better scored peers for our mesh) |
| Opportunistic graft peers | 2 | Number of peers to opportunistically graft |
| Gossip Retransmission | 3 | The maximum number of times we allow a peer to ask via IWANT for the same message id. |
| Max IHAVE length | 5000 | The maximum number of message ids we send in an IHAVE gossip |
| Max IHAVE messages | 5 | The maximum number of IHAVE messages we allow per peer per heartbeat. |
| IWANT follow up time | 3 secs | The maximum amount of time a peer has to respond to an IWANT before being penalized. |

### General Scoring Parameters

These parameters are general and apply to all peers regardless of topic. This are only used once scoring is enabled.

#### Thresholds
| Parameter | Value | Description |
| -------- | -------- | -------- |
| GossipThreshold | -4000 | If a peer has a score below this value we no longer gossip to or accept gossip from that peer |
| PublishThreshold | -8000 | If a peer has a score below this value we no longer publish to that peer |
| GreylistThreshold | -16000 | If a peer has a score below this value we no longer accept messages from the peer |
| Accept PX Threshold | 100 | If a peer has a score below this value we no longer accept PX peers from their prunes |
| Opportunistic Graft Threshold | 5 | If a peer has a score below this value we consider them for replacement via oppertunistic grafting |
| Ip Colocation threshold | 10 | The number of peers allowed with the same IP. Peers exceeding this get quadratically penalized |

#### Scoring Parameters

| Parameter | Value | Description |
| -------- | -------- | -------- |
| DecayInterval | 1 Slot | The time interval in which to apply decays to scores |
| DecayToZero | 0.1 | The minimum score before the next decay sets the score to 0 |
| Retain Score | 100 epochs | The duration of time we remember scores for disconnected peers |
| App Specific Weight | 1 | Application can provide a score. We don't give it additional weighting |
| IP Colocation Factor Weight | -1 | The weighting assigned to penalize peers using the same IP |
| Behaviour Penality Weight | -99 | Penalty for bad behaviours: Attempted to re-graft too early and not responding to IWANT messages in the `IWANT follow up time` |
| Behaviour penalty decay | 0.928 | The decay rate for the behaviour penalty (see notes on Decay Rate) |
| Topic Score Cap | 32.72 | The maximum score a peer can attain from topic scores. We need to adjust this to make sure malicious peer cannot attain very high scores |

#### Note on decay parameters

The decay factor of a score applies every `DecayInterval`. It's often more useful to define the decay parameter as the time it takes to decay to 0.

For a value to decay to 0, it we need to apply the `DecayFactor` enough times for the score to reach 0.1.

This is computed as

$\text{decay_factor} = \text{decay_to_zero}^{\frac{1}{\text{no_slots_to_decay_to_0}}}$

With our current values, and for example, if we want a score to decay in an epoch the decay factor will be:

$\text{decay_factor} = \text{0.1}^{\frac{1}{32}} = 0.93057$

#### Note on Topic Score Cap Estimation

There are scores, such as `FirstMeshDeliveries` where for a given topic we expect a regular number of messages. Thus every slot, we could expect a certain positive score, `x` but every slot this score will decay by the constant decay factor. This leads to a geometric series which has a limiting value which is what we consider when deciding the cap for scores. Its calculated as

$\text{max_theoretic_score} = \frac{\text{expected_score_per_slot}}{1 - \text{decay_factor}}$

We take this into account when choosing topic cap limits.

## Topic Specific Parameters

These are parameters that apply to each specific topic. This will outline what each are and then we provide potential values for each topic related to eth2 in the following section.

### Topics Parameters

| Parameter | Description |
| -------- | -------- |
| Topic Weight | The weight that is applied to the total score of the specific topic |
| Time in Mesh Weight | This is the weight applied to a positive score that we give to peers for the time they have been in our mesh for this topic. The longer they stay in the mesh the greater their score |
| Time in mesh quantum | The interval time period that a peer is in the mesh gets additional scoring |
| Time in mesh cap | The maximum score we give to peers for staying in the mesh for this topic |
| First Message Deliveries Weight | These are the number of unique messages a peer delivers in a topic. This is a positive score and this provides the weight to that score |
| First Message Deliveries Decay | The decay rate for the score |
| First Message Deliveries Cap | The Cap for the score |
| Mesh message deliveries weight | This is the number of messages delivered in the mesh within `mesh_messsage_deliveries_window`. Peers must send at least the threshold number of messages for a topic or be penalized. This is the score's weight |
| Mesh Message Deliveries Decay | This is the decay for the score |
| Mesh Message Deliveries Threshold | The minimum number of messages a peer must send on the topic |
| Mesh Message Deliveries Cap | The upper bound of messages that are counted (including decay) before the score is set to 0 |
| Mesh Message Deliveries Activation | The time a peer is in the mesh before this penalty score is applied |
| Mesh Message Deliveries Window | The time from first seeing a message that we consider future messages as valid |
| Mesh Failure Penalty Weight | If a peer gets pruned with a negative mesh message deliveries score we keep track and weight the peer by this value |
| Mesh Failure Penalty Decay | The decay of this score |
| Invalid Message Deliveries Weight | The weighting for invalid messages (application rejects or encoding errors) |
| Invalid Message Deliveries Decay | The decay of this score |

## Expected Messages Per Topic (To estimate score parameters)

All expected values are measured per epoch.

| Topic | Expected Value | Reason |
| -------- | -------- | -------- |
| Beacon Block | 32 | A perfect network should have 32. However we expect skip slots an not 100% participation so thresholds will be lower |
| Beacon Aggregate | $\frac{V}{8}$ | committees_per_slot = no_validators / slots_per_epoch / target_committee_size. Aggregators = committees_per_slot * aggregators_per_committee * slots_per_epoch |
| Attestation subnet | $\frac{V}{64}$ | Number of validators / number of subnets |
| Voluntary Exit | 0 | Dont expect any but there may be some |
| Proposer Slashings | 0 | Dont expect any but there may be some |
| Attester Slashings | 0 | Dont expect any but there may be some |

## Topic Score Parameters

### Beacon Block

| Parameter | Value | Description |
| -------- | --- | -------- |
| Topic Weight | 0.5 | Relative to other topics |
| Time in Mesh Weight | 0.0324 | We want to weight this small to not give out large scores. This value is based on the gossipsub report |
| Time in mesh quantum | 1 slot | Count based on slots |
| Time in mesh cap | 300 | Based on the gossipsub report |
| First Message Deliveries Weight | 1 | ? |
| First Message Deliveries Decay | 0.9928 | 20 epoch decay to 0 |
| First Message Deliveries Cap | 23 | Expected value given average blocks per slot (1) (Might want to increase) |
| Mesh message deliveries weight | -0.020408 | Match to worst case (no messages delivered) we match the gossipsub report |
| Mesh Message Deliveries Decay | 0.9928 | 20 epoch decay to 0 |
| Mesh Message Deliveries Threshold | 35 | Assume 0.5 blocks per slot and half of them are sent in time |
| Mesh Message Deliveries Cap | 139 | Natural upper bound for 1 block per slot |
| Mesh Message Deliveries Activation| 8 epochs | The time required to build up to the threshold assuming average of 0.6 blocks per slot |
| Mesh Message Deliveries Window | 200ms | Short enough to prevent replay but long enough to account for network delay |
| Mesh Failure Penalty Weight | -0.02048 | Same as `mesh_message_deliveries` |
| Mesh Failure Penalty Decay | 0.9928 | 20 epoch decay to 0 |
| Invalid Message Deliveries Weight | -99 | As in report |
| Invalid Message Deliveries Decay | 0.9994 | Very slow to decay to remember bad peers |

### Attestation Aggregate Topic

| Parameter | Value | Description |
| -------- | --- | -------- |
| Topic Weight | 0.5 | Relative to other topics |
| Time in Mesh Weight | 0.0324 | We want to weight this small to not give out large scores. This value is based on the gossipsub report |
| Time in mesh quantum | 1 slot | Count based on slots |
| Time in mesh cap | 300 | Based on the gossipsub report |
| First Message Deliveries Weight | 0.05 | Lots more messages, weight them less |
| First Message Deliveries Decay | 0.631 | 10 slot decay to 0 |
| First Message Deliveries Cap | $\frac{V}{755.712}$ | expected_per_slot = v/8/32. Value is expected_per_slot/6/( 1 - decay_rate) the division by 8 is our degree |
| Mesh message deliveries weight | -0.0026 | Scaled to match the gossipsub report |
| Mesh Message Deliveries Decay | 0.631 | 10 slot decay to 0 |
| Mesh Message Deliveries Threshold | $\frac{V}{377.856}$ | aggregators_per_slot = v/8/32. Assume 1/4 get delivered within the window. Value = aggregators_per_slot/4/(1-decay_rate) |
| Mesh Message Deliveries Cap | $\frac{V}{94.464}$ | Natural bound for expected aggregators per slot. value = aggregators_per_slot/(1-decay_rate) |
| Mesh Message Deliveries Activation| 4 slots | The time required to build up to the threshold assuming average of 0.6 messages get delivered per slot |
| Mesh Message Deliveries Window | 200ms | Short enough to prevent replay but long enough to account for network delay |
| Mesh Failure Penalty Weight | -0.0026 | Same as `mesh_message_deliveries` |
| Mesh Failure Penalty Decay | 0.631 | 20 epoch decay to 0 |
| Invalid Message Deliveries Weight | -99 | As in report |
| Invalid Message Deliveries Decay | 0.9994 | Very slow to decay to remember bad peers |

### Subnet Topics

Need to fine tune. We only count invalids at the moment.

| Parameter | Value | Description |
| -------- | --- | -------- |
| Topic Weight | 0.5 | Relative to other topics |
| Time in Mesh Weight | 0 | |
| Time in mesh quantum | - | |
| Time in mesh cap | - | |
| First Message Deliveries Weight | 0 | |
| First Message Deliveries Decay | - | |
| First Message Deliveries Cap | - | |
| Mesh message deliveries weight | 0 | |
| Mesh Message Deliveries Decay | - | |
| Mesh Message Deliveries Threshold | - | |
| Mesh Message Deliveries Cap | - | |
| Mesh Message Deliveries Activation|- | |
| Mesh Message Deliveries Window | - | |
| Mesh Failure Penalty Weight | 0 | |
| Mesh Failure Penalty Decay | - | |
| Invalid Message Deliveries Weight | -99 | As in report |
| Invalid Message Deliveries Decay | 0.9994 | Very slow to decay to remember bad peers |

### Other topics

See the spreadsheet for topics which we do not expect regular messages on.