package octez-libs

  1. Overview
  2. Docs
A package that contains multiple base libraries used by the Octez suite

Install 

dune-project
 Dependency

www.tezos.com Readme Edit opam file Versions (5)

Authors

  1. T
    Tezos devteam

Maintainers

  1. C
    contact@tezos.com

Sources

tezos-18.0.tar.gz
sha256=dbc3b675aee59c2c574e5d0a771193a2ecfca31e7a5bc5aed66598080596ce1c
sha512=b97ed762b9d24744305c358af0d20f394376b64bfdd758dd4a81775326caf445caa57c4f6445da3dd6468ff492de18e4c14af6f374dfcbb7e4d64b7b720e5e2a

doc/octez-libs.tezos-gossipsub/Tezos_gossipsub/Make/index.html

Module Tezos_gossipsub.MakeSource

Parameters

Signature

Module for peer

Module for topic

Sourcemodule Message_id = C.Subconfig.Message_id

Module for message_id

Sourcemodule Message = C.Subconfig.Message

Module for message

Module for time

Module for time duration

Sourcemodule Score : Gossipsub_intf.SCORE with type time = Time.t and type topic = Topic.t

Module for peers scores

Sourcetype message = Message.t
Sourcetype span = Span.t
Sourcetype state

The state managed by the gossipsub automaton. The state is purely functional.

Limits of the gossipsub protocol.

Parameters of the gossipsub protocol.

The types of payloads for inputs to the gossipsub automaton.

Sourcetype add_peer = {
  1. direct : bool;
  2. outbound : bool;
  3. peer : Peer.t;
}
Sourcetype remove_peer = {
  1. peer : Peer.t;
}
Sourcetype ihave = {
  1. peer : Peer.t;
  2. topic : Topic.t;
  3. message_ids : Message_id.t list;
}
Sourcetype iwant = {
  1. peer : Peer.t;
  2. message_ids : Message_id.t list;
}
Sourcetype graft = {
  1. peer : Peer.t;
  2. topic : Topic.t;
}
Sourcetype prune = {
  1. peer : Peer.t;
  2. topic : Topic.t;
  3. px : Peer.t Tezos_base.TzPervasives.Seq.t;
  4. backoff : span;
}
Sourcetype publish_message = {
  1. topic : Topic.t;
  2. message_id : Message_id.t;
  3. message : message;
}
Sourcetype receive_message = {
  1. sender : Peer.t;
  2. topic : Topic.t;
  3. message_id : Message_id.t;
  4. message : message;
}
Sourcetype join = {
  1. topic : Topic.t;
}
Sourcetype leave = {
  1. topic : Topic.t;
}
Sourcetype subscribe = {
  1. topic : Topic.t;
  2. peer : Peer.t;
}
Sourcetype unsubscribe = {
  1. topic : Topic.t;
  2. peer : Peer.t;
}
Sourcetype set_application_score = {
  1. peer : Peer.t;
  2. score : float;
}
Sourcetype _ output =
  1. | Ihave_from_peer_with_low_score : {
    1. score : Score.t;
    2. threshold : float;
    } -> [ `IHave ] output
    (*

    The peer who sent an IHave message has a score below threshold.

    *)
  2. | Too_many_recv_ihave_messages : {
    1. count : int;
    2. max : int;
    } -> [ `IHave ] output
    (*

    The peer sent us more than max IHave messages within two successive heartbeat calls.

    *)
  3. | Too_many_sent_iwant_messages : {
    1. count : int;
    2. max : int;
    } -> [ `IHave ] output
    (*

    We sent more than max IWant messages to this peer within two successive heartbeat calls.

    *)
  4. | Message_topic_not_tracked : [ `IHave ] output
    (*

    We received an IHave message for a topic we don't track.

    *)
  5. | Message_requested_message_ids : Message_id.t list -> [ `IHave ] output
    (*

    The messages ids we want to request from the peer which sent us an IHave message. The implementation honors the max_sent_iwant_per_heartbeat limit.

    *)
  6. | Iwant_from_peer_with_low_score : {
    1. score : Score.t;
    2. threshold : float;
    } -> [ `IWant ] output
    (*

    The peer who sent an IWant message has a score below threshold.

    *)
  7. | On_iwant_messages_to_route : {
    1. routed_message_ids : [ `Ignored | `Not_found | `Too_many_requests | `Message of message ] Message_id.Map.t;
    } -> [ `IWant ] output
    (*

    As an answer for an `IWant message, the automaton returns a map associating to each requested message_id either `Ignored if the peer is filtered out by peer_filter, `Not_found if the message is not found, or Message m if m is the message with the given id.

    *)
  8. | Peer_filtered : [ `Graft ] output
    (*

    The peer we attempt to graft has not been selected by peer_filter.

    *)
  9. | Unsubscribed_topic : [ `Graft ] output
    (*

    We didn't join the topic for which we are attempting to graft a peer.

    *)
  10. | Peer_already_in_mesh : [ `Graft ] output
    (*

    Attempting to graft a peer which has already been grafted.

    *)
  11. | Grafting_direct_peer : [ `Graft ] output
    (*

    Attempting to graft a direct peer.

    *)
  12. | Unexpected_grafting_peer : [ `Graft ] output
    (*

    The peer we attempt to graft is not known.

    *)
  13. | Grafting_peer_with_negative_score : [ `Graft ] output
    (*

    Attempting to graft a peer with a negative score.

    *)
  14. | Grafting_successfully : [ `Graft ] output
    (*

    Grafting the given peer for the provided topic succeeded.

    *)
  15. | Peer_backed_off : [ `Graft ] output
    (*

    We cannot graft the given peer because it is backed off.

    *)
  16. | Mesh_full : [ `Graft ] output
    (*

    Grafting a peer for a topic whose mesh has already sufficiently many peers.

    *)
  17. | Prune_topic_not_tracked : [ `Prune ] output
    (*

    Attempting to prune a peer for a non-tracked topic.

    *)
  18. | Peer_not_in_mesh : [ `Prune ] output
    (*

    Attempting to prune a peer which is not in the mesh.

    *)
  19. | Ignore_PX_score_too_low : Score.t -> [ `Prune ] output
    (*

    The given peer has been pruned for the given topic, but no alternative peers are returned because the peer's score is too low. The score of the peer is included in the return value.

    *)
  20. | No_PX : [ `Prune ] output
    (*

    The given peer has been pruned for the given topic. No alternatives peers was provided in prune.

    *)
  21. | PX : Peer.Set.t -> [ `Prune ] output
    (*

    The given peer has been pruned for the given topic. The given set of peers alternatives in prune for that topic is returned.

    *)
  22. | Publish_message : {
    1. to_publish : Peer.Set.t;
    } -> [ `Publish_message ] output
    (*

    to_publish contains:

    • Direct peers for the message's topic;
    • The peers in the topic's mesh, if the peer is subscribed to the topic. Otherwise, the peers in the topic's fanout.
    *)
  23. | Already_published : [ `Publish_message ] output
    (*

    Attempting to publish a message that has already been published.

    *)
  24. | Route_message : {
    1. to_route : Peer.Set.t;
    } -> [ `Receive_message ] output
    (*

    to_route contains:

    • Direct peers for the message's topic;
    • The peers in the topic's mesh minus the original sender of the message.
    *)
  25. | Already_received : [ `Receive_message ] output
    (*

    Received a message that has already been recevied before.

    *)
  26. | Not_subscribed : [ `Receive_message ] output
    (*

    Received a message from a remote peer for a topic we are not subscribed to (called "unknown topic" in the Go implementation).

    *)
  27. | Invalid_message : [ `Receive_message ] output
  28. | Unknown_validity : [ `Receive_message ] output
    (*

    Attempting to publish a message that is invalid.

    *)
  29. | Already_joined : [ `Join ] output
    (*

    Attempting to join a topic we already joined.

    *)
  30. | Joining_topic : {
    1. to_graft : Peer.Set.t;
    } -> [ `Join ] output
    (*

    When successfully joining a topic, the set of grafted peers for that topic is returned.

    *)
  31. | Not_joined : [ `Leave ] output
    (*

    Attempting to leave a topic which we didn't join or had already left.

    *)
  32. | Leaving_topic : {
    1. to_prune : Peer.Set.t;
    2. noPX_peers : Peer.Set.t;
    } -> [ `Leave ] output
    (*

    When successfully leaving a topic, the set of pruned peers for that topic is returned alongside a subset of those peers for which no alternative PX will be proposed.

    *)
  33. | Heartbeat : {
    1. to_graft : Topic.Set.t Peer.Map.t;
      (*

      The set of topics per peer that have been grafted.

      *)
    2. to_prune : Topic.Set.t Peer.Map.t;
      (*

      The set of topics per peer that have been pruned.

      *)
    3. noPX_peers : Peer.Set.t;
      (*

      Set of peers for which peer exchange (PX) will not be proposed.

      *)
    } -> [ `Heartbeat ] output
  34. | Peer_added : [ `Add_peer ] output
    (*

    The output returned when successfully adding a peer.

    *)
  35. | Peer_already_known : [ `Add_peer ] output
    (*

    The output returned when attempting to add a peer which is already known.

    *)
  36. | Removing_peer : [ `Remove_peer ] output
    (*

    The output returned when successfully removing a peer.

    *)
  37. | Subscribed : [ `Subscribe ] output
    (*

    The output returned once we successfully processed a subscribe request sent from a peer.

    *)
  38. | Subscribe_to_unknown_peer : [ `Subscribe ] output
    (*

    The output returned when we receive a subscribe message from a peer we don't know.

    *)
  39. | Unsubscribed : [ `Unsubscribe ] output
    (*

    The output returned once we successfully processed an unsubscribe request sent from a peer.

    *)
  40. | Unsubscribe_from_unknown_peer : [ `Unsubscribe ] output
    (*

    The output returned when we receive an unsubscribe message from a peer we don't know.

    *)
  41. | Set_application_score : [ `Set_application_score ] output
    (*

    The output returned when we set the application score of a peer

    *)

Output produced by one of the actions below.

type 'a monad := state -> state * 'a output

A type alias for the state monad.

Initialise a state.

Sourceval add_peer : add_peer -> [ `Add_peer ] monad

add_peer { direct; outbound; peer } is called to notify a new connection. If direct is true, the gossipsub always forwards messages to those peers. outbound is true if it is an outbound connection, that is, a connection initiated by the local (not the remote) peer. Note however that the notion of "outbound" connections can be refined, relaxed or redefined by the application layer to fit its own needs.

Sourceval remove_peer : remove_peer -> [ `Remove_peer ] monad

remove_peer { peer } notifies gossipsub that we are disconnected from a peer. Do note that the state still maintain information for this connection for retain_duration seconds.

Sourceval handle_subscribe : subscribe -> [ `Subscribe ] monad

handle_subscribe {topic; peer} handles a request from a remote peer informing us that it is subscribed to topic.

Sourceval handle_unsubscribe : unsubscribe -> [ `Unsubscribe ] monad

handle_unsubscribe {topic; peer} handles a request from a remote peer informing us that it unsubscribed from topic.

Sourceval handle_ihave : ihave -> [ `IHave ] monad

handle_ihave { peer; topic; message_ids } handles the gossip message IHave emitted by peer for topic with the message_ids.

Sourceval handle_iwant : iwant -> [ `IWant ] monad

handle_iwant { peer; message_ids } handles the gossip message IWant emitted by peer for topic with the message_ids.

Sourceval handle_graft : graft -> [ `Graft ] monad

handle_graft { peer; topic } handles the gossip message Graft emitted by peer for topic. This action allows to graft a connection to a full connection allowing the transmission of full messages for the given topic.

Sourceval handle_prune : prune -> [ `Prune ] monad

handle_prune { peer; topic; px; backoff } handles the gossip message Prune emitted by peer for topic. This action allows to prune a full connection. In that case, the remote peer can send a list of peers to connect to as well as a backoff time, which is a duration for which we cannot Graft this peer on this topic.

Sourceval handle_receive_message : receive_message -> [ `Receive_message ] monad

handle_receive_message { sender; topic; message_id; message } handles a message received from sender on the gossip network. The function returns a set of peers to which the (full) message will be directly forwarded.

Sourceval publish_message : publish_message -> [ `Publish_message ] monad

publish { topic; message_id; message } allows to publish a message on the gossip network from the local node. The function returns a set of peers to which the (full) message will be directly forwarded.

Sourceval heartbeat : [ `Heartbeat ] monad

heartbeat executes the heartbeat routine of the algorithm.

Sourceval join : join -> [ `Join ] monad

join { topic } handles a join to a new topic. On success, the function returns the set of peers that have been grafted to form the mesh of the joined topic.

Sourceval leave : leave -> [ `Leave ] monad

leave { topic } handles a leave from a topic. On success, the function returns the set of peers, forming the mesh, that have been pruned for that topic.

Sourceval set_application_score : set_application_score -> [ `Set_application_score ] monad

set_application_score {peer; score} handles setting the application score of peer. If the peer is not known, this does nothing.

Sourceval select_px_peers : state -> peer_to_prune:Peer.t -> Topic.t -> noPX_peers:Peer.Set.t -> Peer.t list

Select random peers for Peer eXchange. Note that function is deterministic; however, it has side effects in that it updates the state's random state.

Sourceval select_gossip_messages : state -> ihave list

Select the gossip messages to be sent. These are IHave control messages referring to recently seen messages (that is, sent during the last history_gossip_length heartbeat ticks), to be sent to a random selection of peers. The message ids for a peer and a topic are also selected at random among the possible ones. At most max_sent_iwant_per_heartbeat message ids are sent.

The local peer will send gossip to at most gossip_factor * (total number of non-mesh/non-fanout peers), or degree_lazy random peers, whichever is greater.

Note that function is deterministic; however, it has side effects in that it updates the state's random state.

Sourceval pp_add_peer : Format.formatter -> add_peer -> unit
Sourceval pp_remove_peer : Format.formatter -> remove_peer -> unit
Sourceval pp_ihave : Format.formatter -> ihave -> unit
Sourceval pp_iwant : Format.formatter -> iwant -> unit
Sourceval pp_graft : Format.formatter -> graft -> unit
Sourceval pp_prune : Format.formatter -> prune -> unit
Sourceval pp_receive_message : Format.formatter -> receive_message -> unit
Sourceval pp_publish_message : Format.formatter -> publish_message -> unit
Sourceval pp_join : Format.formatter -> join -> unit
Sourceval pp_leave : Format.formatter -> leave -> unit
Sourceval pp_subscribe : Format.formatter -> subscribe -> unit
Sourceval pp_unsubscribe : Format.formatter -> unsubscribe -> unit
Sourceval pp_set_application_score : Format.formatter -> set_application_score -> unit
Sourceval pp_output : Format.formatter -> 'a output -> unit
Sourcemodule Introspection : sig ... end