AtHeartEngineer/specs
1
0
Fork 0
mirror of https://github.com/vacp2p/specs.git synced 2026-01-09 07:17:56 -05:00
Code Issues Packages Projects Releases Wiki Activity

move overview of new parameters to the end of the document

Browse Source
This commit is contained in:
vyzo
2020-03-20 19:40:49 +02:00
parent 58b75a657f
commit d391e8d8af
1 changed files with 79 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

158
pubsub/gossipsub/gossipsub-v1.1.md
View File

@@ -57,84 +57,6 @@ as the protocol string.
## Protocol extensions
### Overview of New Parameters
The extensions that make up gossipsub v1.1 introduce several new application configurable
parameters. This section lists all the new parameters along with a brief description. More detail is
available in the discussion of the protocol extensions below.
The following parameters apply globally:
| Parameter | Type | Description | Reasonable Default |
|----------------|------------------|------------------------------------------------------------------------|--------------------|
| `PruneBackoff` | Duration | Time after pruning a mesh peer before we consider grafting them again. | `1 minute` |
| `FloodPublish` | Boolean | Whether to enable flood publishing | `true` |
| `GossipFactor` | Float [0.0, 1.0] | % of peers to send gossip to, if we have more than `D_lazy` available | `0.25` |
The remaining parameters apply to [Peer Scoring](#peer-scoring). Because many parameters are
inter-related and may be application-specific, reasonable defaults are not shown here. See
[Guidelines for Tuning the Scoring Function](#guidelines-for-tuning-the-scoring-function) to
understand how tune the parameters to the needs of an application.
The following peer scoring parameters apply globally to all peers and topics:
| Parameter | Type | Description | Constraints |
|---------------------|----------|-------------------------------------------------------------------------|------------------------------|
| `GossipThreshold` | Float | No gossip emitted to peers below threshold; incoming gossip is ignored. | Must be < 0 |
| `PublishThreshold` | Float | No self-published messages are sent to peers below threshold. | Must be < `GossipThreshold` |
| `GraylistThreshold` | Float | All RPC messages are ignored from peers below threshold. | Must be < `PublishThreshold` |
| `DecayInterval` | Duration | Interval at which parameter decay is calculated. | |
| `DecayToZero` | Float | Limit below which we consider a decayed param to be "zero". | Should be close to 0.0 |
| `RetainScore` | Duration | Time to remember peer scores after a peer disconnects. | |
The remaining peer score parameters affect how scores are computed for each peer based on their
observed behavior.
Parameters with type `Weight` are floats in the range [0.0, 1.0] that determine
how much a score parameter contributes to the overall score for a peer. See [The Score
Function](#the-score-function) for details.
There are some parameters that apply to the peer "as a whole", regardless of
which topics they are subscribed to:
| Parameter | Type | Description | Constraints |
|-------------------------------|--------|-------------------------------------------------------|---------------------------------------------------------------|
| `AppSpecificWeight` | Weight | Weight of `P₅`, the application-specific score. | Must be positive, however score values may be negative. |
| `IPColocationFactorWeight` | Weight | Weight of `P₆`, the IP colocation score. | Must be negative, to penalize peers with multiple IPs. |
| `IPColocationFactorThreshold` | Float | Number of IPs a peer may have before being penalized. | Must be at least 1. Values above threshold will be penalized. |
The remaining parameters are applied to a peer's behavior within a single topic. Implementations
should be able to accept configurations for multiple topics, keyed by topic ID string. Each topic
may be configured with the following params. If a topic is not configured, a peer's behavior in that
topic will not contribute to their score. If a peer is in multiple configured topics, each topic
will contribute to their total score according to the `TopicWeight` parameter.
| Parameter | Type | Description | Constraints |
|-----------------------------------|----------|-----------------------------------------------------------------------|-----------------------------------------------------------------------|
| `TopicWeight` | Weight | How much does behavior in this topic contribute to the overall score? | |
| **`P₁`** | | **Time in Mesh** | |
| `TimeInMeshWeight` | Weight | Weight of `P₁`. | Should be a small positive value. |
| `TimeInMeshQuantum` | Duration | Time a peer must be in mesh to accrue one "point" for `P₁`. | |
| `TimeInMeshCap` | Float | Maximum value for `P₁`. | Should be a small positive value. |
| **``P₂``** | | **First Message Deliveries** | |
| `FirstMessageDeliveriesWeight` | Weight | Weight of `P₂`. | Should be positive, to reward fast peers. |
| `FirstMessageDeliveriesDecay` | Float | Decay factor for `P₂`. | |
| `FirstMessageDeliveriesCap` | Float | Maximum value for `P₂`. | |
| **`P₃`** | | **Mesh Message Delivery Rate** | |
| `MeshMessageDeliveriesWeight` | Weight | Weight of `P₃`. | Should be negative, to penalize peers below threshold. |
| `MeshMessageDeliveriesDecay` | Float | Decay factor for `P₃`. | |
| `MeshMessageDeliveriesThreshold` | Float | Value for `P₃` below which we start penalizing peers. | Should be positive. Value depends on expected message rate for topic. |
| `MeshMessageDeliveriesCap` | Float | Maximum value for `P₃`. | Must be >= `MeshMessageDeliveriesThreshold`. |
| `MeshMessageDeliveriesActivation` | Duration | Time a peer must be in the mesh before we start applying `P₃` score. | |
| `MeshMessageDeliveryWindow` | Duration | Time after first delivery that is considered "near-first". | Should be small, e.g. 1-5 ms. |
| **`P₃b`** | | **Mesh Message Delivery Failures** | |
| `MeshFailurePenaltyWeight` | Weight | Weight of `P₃b`. | Should be negative, to penalize failed deliveries. |
| `MeshFailurePenaltyDecay` | Float | Decay factor for `P₃b`. | |
| **`P₄`** | | **Invalid Messages** | |
| `InvalidMessageDeliveriesWeight` | Weight | Weight of`P₄`. | Should be negative, to penalize invalid messages. |
| `InvalidMessageDeliveriesDecay` | Float | Decay factor for `P₄`. | |
### Peer Exchange on PRUNE
Gossipsub relies on ambient peer discovery in order to find peers within a topic of interest.
@@ -491,6 +413,84 @@ if invalidMessageDeliveries < DecayToZero {
`TBD`: We are currently developing a multiple types of simulations that will inform us on how to best recommend tunning the Scoring function. We will update this section once that work is complete
### Overview of New Parameters
The extensions that make up gossipsub v1.1 introduce several new application configurable
parameters. This section lists all the new parameters along with a brief description. More detail is
available in the discussion of the protocol extensions below.
The following parameters apply globally:
| Parameter | Type | Description | Reasonable Default |
|----------------|------------------|------------------------------------------------------------------------|--------------------|
| `PruneBackoff` | Duration | Time after pruning a mesh peer before we consider grafting them again. | `1 minute` |
| `FloodPublish` | Boolean | Whether to enable flood publishing | `true` |
| `GossipFactor` | Float [0.0, 1.0] | % of peers to send gossip to, if we have more than `D_lazy` available | `0.25` |
The remaining parameters apply to [Peer Scoring](#peer-scoring). Because many parameters are
inter-related and may be application-specific, reasonable defaults are not shown here. See
[Guidelines for Tuning the Scoring Function](#guidelines-for-tuning-the-scoring-function) to
understand how tune the parameters to the needs of an application.
The following peer scoring parameters apply globally to all peers and topics:
| Parameter | Type | Description | Constraints |
|---------------------|----------|-------------------------------------------------------------------------|------------------------------|
| `GossipThreshold` | Float | No gossip emitted to peers below threshold; incoming gossip is ignored. | Must be < 0 |
| `PublishThreshold` | Float | No self-published messages are sent to peers below threshold. | Must be < `GossipThreshold` |
| `GraylistThreshold` | Float | All RPC messages are ignored from peers below threshold. | Must be < `PublishThreshold` |
| `DecayInterval` | Duration | Interval at which parameter decay is calculated. | |
| `DecayToZero` | Float | Limit below which we consider a decayed param to be "zero". | Should be close to 0.0 |
| `RetainScore` | Duration | Time to remember peer scores after a peer disconnects. | |
The remaining peer score parameters affect how scores are computed for each peer based on their
observed behavior.
Parameters with type `Weight` are floats in the range [0.0, 1.0] that determine
how much a score parameter contributes to the overall score for a peer. See [The Score
Function](#the-score-function) for details.
There are some parameters that apply to the peer "as a whole", regardless of
which topics they are subscribed to:
| Parameter | Type | Description | Constraints |
|-------------------------------|--------|-------------------------------------------------------|---------------------------------------------------------------|
| `AppSpecificWeight` | Weight | Weight of `P₅`, the application-specific score. | Must be positive, however score values may be negative. |
| `IPColocationFactorWeight` | Weight | Weight of `P₆`, the IP colocation score. | Must be negative, to penalize peers with multiple IPs. |
| `IPColocationFactorThreshold` | Float | Number of IPs a peer may have before being penalized. | Must be at least 1. Values above threshold will be penalized. |
The remaining parameters are applied to a peer's behavior within a single topic. Implementations
should be able to accept configurations for multiple topics, keyed by topic ID string. Each topic
may be configured with the following params. If a topic is not configured, a peer's behavior in that
topic will not contribute to their score. If a peer is in multiple configured topics, each topic
will contribute to their total score according to the `TopicWeight` parameter.
| Parameter | Type | Description | Constraints |
|-----------------------------------|----------|-----------------------------------------------------------------------|-----------------------------------------------------------------------|
| `TopicWeight` | Weight | How much does behavior in this topic contribute to the overall score? | |
| **`P₁`** | | **Time in Mesh** | |
| `TimeInMeshWeight` | Weight | Weight of `P₁`. | Should be a small positive value. |
| `TimeInMeshQuantum` | Duration | Time a peer must be in mesh to accrue one "point" for `P₁`. | |
| `TimeInMeshCap` | Float | Maximum value for `P₁`. | Should be a small positive value. |
| **``P₂``** | | **First Message Deliveries** | |
| `FirstMessageDeliveriesWeight` | Weight | Weight of `P₂`. | Should be positive, to reward fast peers. |
| `FirstMessageDeliveriesDecay` | Float | Decay factor for `P₂`. | |
| `FirstMessageDeliveriesCap` | Float | Maximum value for `P₂`. | |
| **`P₃`** | | **Mesh Message Delivery Rate** | |
| `MeshMessageDeliveriesWeight` | Weight | Weight of `P₃`. | Should be negative, to penalize peers below threshold. |
| `MeshMessageDeliveriesDecay` | Float | Decay factor for `P₃`. | |
| `MeshMessageDeliveriesThreshold` | Float | Value for `P₃` below which we start penalizing peers. | Should be positive. Value depends on expected message rate for topic. |
| `MeshMessageDeliveriesCap` | Float | Maximum value for `P₃`. | Must be >= `MeshMessageDeliveriesThreshold`. |
| `MeshMessageDeliveriesActivation` | Duration | Time a peer must be in the mesh before we start applying `P₃` score. | |
| `MeshMessageDeliveryWindow` | Duration | Time after first delivery that is considered "near-first". | Should be small, e.g. 1-5 ms. |
| **`P₃b`** | | **Mesh Message Delivery Failures** | |
| `MeshFailurePenaltyWeight` | Weight | Weight of `P₃b`. | Should be negative, to penalize failed deliveries. |
| `MeshFailurePenaltyDecay` | Float | Decay factor for `P₃b`. | |
| **`P₄`** | | **Invalid Messages** | |
| `InvalidMessageDeliveriesWeight` | Weight | Weight of`P₄`. | Should be negative, to penalize invalid messages. |
| `InvalidMessageDeliveriesDecay` | Float | Decay factor for `P₄`. | |
### Spam Protection Measures
In order counter spam that elicits responses and consumes resources, some measures have been taken:
@@ -504,4 +504,4 @@ In order counter spam that elicits responses and consumes resources, some measur
- Invalid message spam, either directly transmitted or as a response to an `IHAVE` message is
penalized by the score function. A peer transmitting lots of spam will quickly get graylisted,
reducing the surface of spam-induced computation (eg validation). The application can take
further steps and blacklist the peer if the spam persists after the negative score decays.
further steps and blacklist the peer if the spam persists after the negative score decays.