Module Mavryk_gossipsub.Gossipsub_intf

module type ITERABLE = sig ... end
module type AUTOMATON_SUBCONFIG = sig ... end
module type SPAN = sig ... end
module type TIME = sig ... end
module type AUTOMATON_CONFIG = sig ... end
type 'span per_topic_score_limits = {
  1. time_in_mesh_weight : float;
    (*

    P1: The weight of the score associated to the time spent in the mesh.

    *)
  2. time_in_mesh_cap : float;
    (*

    P1: The maximum value considered for the score associated to the time spent by a peer in the mesh.

    *)
  3. time_in_mesh_quantum : 'span;
    (*

    P1: The score associated to the time spent t in the mesh is (min t time_in_mesh_cap) / time_in_mesh_quantum.

    *)
  4. first_message_deliveries_weight : float;
    (*

    P2: The weight of the score associated to the number of first message deliveries.

    *)
  5. first_message_deliveries_cap : int;
    (*

    P2: The maximum value considered during score computation for the number of first message deliveries.

    *)
  6. first_message_deliveries_decay : float;
    (*

    P2: The score is multiplied by this factor every score_cleanup_ticks heartbeat. This parameter must be in the unit interval.

    *)
  7. mesh_message_deliveries_weight : float;
    (*

    P3: The weight of the score associated to the number of first/near-first mesh message deliveries.

    *)
  8. mesh_message_deliveries_window : 'span;
    (*

    P3: The delay added to the first delivery of a message to obtain the upper bound up to which a duplicate message is counted as nearly-first delivered.

    *)
  9. mesh_message_deliveries_activation : 'span;
    (*

    P3: How long should a peer be in the mesh before we start evaluating P3.

    *)
  10. mesh_message_deliveries_cap : int;
    (*

    P3: The maximum value considered during score computation for the number of first/near-first mesh message deliveries.

    *)
  11. mesh_message_deliveries_threshold : int;
    (*

    P3: The number of messages received from a peer in the mesh in the associated topic above which the peer won't be penalized

    *)
  12. mesh_message_deliveries_decay : float;
    (*

    P3: The score is multiplied by this factor every score_cleanup_ticks heartbeat. This parameter must be in the unit interval.

    *)
  13. mesh_failure_penalty_weight : float;
    (*

    P3b: Penalty induced when a peer gets pruned with a non-zero mesh message delivery deficit.

    *)
  14. mesh_failure_penalty_decay : float;
    (*

    P3b: The score is multiplied by this factor every score_cleanup_ticks heartbeat. This parameter must be in the unit interval.

    *)
  15. invalid_message_deliveries_weight : float;
    (*

    P4: Penalty induced when a peer sends an invalid message.

    *)
  16. invalid_message_deliveries_decay : float;
    (*

    P4: The score is multiplied by this factor every score_cleanup_ticks heartbeat. This parameter must be in the unit interval.

    *)
}
type ('topic, 'span) topic_score_limits =
  1. | Topic_score_limits_single of 'span per_topic_score_limits
    (*

    Use this constructor when the topic score parameters do not depend on the topic.

    *)
  2. | Topic_score_limits_family of {
    1. all_topics : 'topic Mavryk_base.TzPervasives.Seq.t;
    2. parameters : 'topic -> 'span per_topic_score_limits;
    3. weights : 'topic -> float;
    }
    (*

    Use this constructor when the topic score parameters may depend on the topic.

    *)
type ('topic, 'span) score_limits = {
  1. topics : ('topic, 'span) topic_score_limits;
    (*

    Per-topic score parameters.

    *)
  2. topic_score_cap : float option;
    (*

    An optional cap on the total positive contribution of topics to the score of the peer. If not equal to None, must be non-negative.

    *)
  3. behaviour_penalty_weight : float;
    (*

    P7: The weight of the score associated to the behaviour penalty. This parameter must be negative.

    *)
  4. behaviour_penalty_threshold : float;
    (*

    P7: The threshold on the behaviour penalty counter above which we start penalizing the peer.

    *)
  5. behaviour_penalty_decay : float;
    (*

    P7: The score is multiplied by a factor of behaviour_penalty_decay every score_cleanup_ticks heartbeat. This parameter must be in the unit interval.

    *)
  6. app_specific_weight : float;
    (*

    P5: Application-specific peer scoring

    *)
  7. decay_zero : float;
    (*

    The minimum value under which a score is considered to be equal to 0 after applying decay. This parameter must be non-negative.

    *)
}
type ('topic, 'peer, 'message_id, 'span) limits = {
  1. max_recv_ihave_per_heartbeat : int;
    (*

    The maximum number of IHave control messages we can receive from a peer between two heartbeats. It is called MaxIHaveMessages in the Go implementation.

    *)
  2. max_sent_iwant_per_heartbeat : int;
    (*

    The maximum number of IWant control message ids we can send to a peer between two heartbeats. It is also the maximum number of message ids to include in an IHave message. It is called MaxIHaveLength in the Go implementation.

    *)
  3. max_gossip_retransmission : int;
    (*

    The maximum number of times the local peer allows a remote peer to request the same message id through IWant gossip before the local peer starts ignoring them. This is designed to prevent peers from spamming with requests.

    *)
  4. degree_optimal : int;
    (*

    The optimal number of full connections per topic. For example, if it is 6, each peer will want to have about six peers in their mesh for each topic they're subscribed to. It should be set somewhere between degree_low and degree_high.

    *)
  5. publish_threshold : float;
    (*

    The threshold value (as a score) from which we can publish a message to our peers.

    *)
  6. gossip_threshold : float;
    (*

    The threshold value (as a score) for a peer to emit/accept gossip: if the remote peer score is below this threshold, the local peer won't emit or accept gossip from the remote peer.

    *)
  7. do_px : bool;
    (*

    The flag controls whether peer exchange (PX) is enabled.

    *)
  8. accept_px_threshold : float;
    (*

    The threshold value (as a score) from which we accept peer exchanges.

    *)
  9. peers_to_px : int;
    (*

    The number of peers to include in prune Peer eXchange. (This is called PrunePeers in the Go implementation.)

    *)
  10. unsubscribe_backoff : 'span;
    (*

    The duration that prevent reconnections after leaving a topic to our full connections.

    *)
  11. graft_flood_threshold : 'span;
    (*

    If a graft comes before graft_flood_threshold has elapsed since the last prune, then there is an extra score penalty applied to the peer through P7.

    *)
  12. prune_backoff : 'span;
    (*

    The duration added when we prune a peer.

    *)
  13. retain_duration : 'span;
    (*

    The duration added to remove metadata about a disconnected peer.

    *)
  14. fanout_ttl : 'span;
    (*

    fanout_ttl controls how long we keep track of a fanout topic. If it's been fanout_ttl since we've published to a topic that we're not subscribed to, then we don't track that topic anymore, that is, we delete it from the fanout map.

    *)
  15. heartbeat_interval : 'span;
    (*

    The time between heartbeats.

    *)
  16. backoff_cleanup_ticks : int;
    (*

    The number of heartbeat ticks setting the frequency at which the backoffs are checked and potentially cleared.

    *)
  17. score_cleanup_ticks : int;
    (*

    score_cleanup_ticks is the number of heartbeat ticks setting the frequency at which the scores are refreshed and potentially cleared.

    *)
  18. degree_low : int;
    (*

    The lower bound on the number of peers we keep in a topic mesh. If we have fewer than degree_low peers, the heartbeat will attempt to graft some more into the mesh at the next heartbeat.

    *)
  19. degree_high : int;
    (*

    The upper bound on the number of peers we keep in a topic mesh. If there are more than degree_high peers, the heartbeat will select some to prune from the mesh at the next heartbeat.

    *)
  20. degree_score : int;
    (*

    degree_score affects how peers are selected when pruning a mesh due to over subscription. At least degree_score of the retained peers will be high-scoring, while the remainder are chosen randomly.

    *)
  21. degree_out : int;
    (*

    The number of outbound connections to maintain in a topic mesh. When the mesh is pruned due to over subscription, we make sure that we have outbound connections to at least degree_out of the survivor peers. This prevents Sybil attackers from overwhelming our mesh with incoming connections. degree_out must be set below degree_low, and must not exceed degree_optimal / 2.

    *)
  22. degree_lazy : int;
    (*

    degree_lazy affects how many peers the local peer will emit gossip to at each heartbeat. The local peer will send gossip to at least degree_lazy peers outside its mesh or fanout. The actual number may be more, depending on gossip_factor and how many peers the local peer is connected to.

    *)
  23. gossip_factor : float;
    (*

    gossip_factor affects how many peers the local peer will emit gossip to at each heartbeat. The local peer will send gossip to gossip_factor * (total number of non-mesh/non-fanout peers), or degree_lazy peers, whichever is greater.

    *)
  24. history_length : int;
    (*

    The size of the message cache used for gossip. The message cache will remember messages for history_length heartbeats.

    *)
  25. history_gossip_length : int;
    (*

    history_gossip_length controls how many cached message ids the local peer will advertise in IHave gossip messages. When asked for its seen message ids, the local peer will return only those from the most recent history_gossip_length heartbeats. The slack between history_gossip_length and history_length allows the local peer to avoid advertising messages that will be expired by the time they're requested. history_gossip_length must be less than or equal to history_length.

    *)
  26. opportunistic_graft_ticks : int64;
    (*

    The number of heartbeat ticks setting the frequency at which to attempt to improve the mesh with opportunistic grafting. Every opportunistic_graft_ticks, if the median score of the mesh peers falls below the opportunistic_graft_threshold, then the local peer will select some high-scoring mesh peers to graft.

    *)
  27. opportunistic_graft_peers : int;
    (*

    The number of peers to opportunistically graft.

    *)
  28. opportunistic_graft_threshold : float;
    (*

    The median mesh score threshold before triggering opportunistic grafting; this should have a small positive value.

    *)
  29. score_limits : ('topic, 'span) score_limits;
    (*

    score-specific parameters.

    *)
  30. seen_history_length : int;
    (*

    seen_history_length controls the size of the message cache used for recording seen messages. The seen messages cache will remember messages for seen_history_length heartbeats.

    *)
}
type ('peer, 'message_id) parameters = {
  1. peer_filter : 'peer -> [ `IHave of 'message_id | `IWant of 'message_id | `Graft ] -> bool;
}
module type SCORE = sig ... end

The SCORE module type describes primitives used to update the scores associated to each peer. Score computation is described in more details in the specification.

module type MESSAGE_CACHE = sig ... end
module type AUTOMATON = sig ... end
module type WORKER_CONFIGURATION = sig ... end
module type WORKER = sig ... end

The interface of a gossipsub worker.