Module libp2p::gossipsub

Gossipsub is a P2P pubsub (publish/subscription) routing layer designed to extend upon flooodsub and meshsub routing protocols.

Overview

Note: The gossipsub protocol specifications (https://github.com/libp2p/specs/tree/master/pubsub/gossipsub) provide an outline for the routing protocol. They should be consulted for further detail.

Gossipsub is a blend of meshsub for data and randomsub for mesh metadata. It provides bounded degree and amplification factor with the meshsub construction and augments it using gossip propagation of metadata with the randomsub technique.

The router maintains an overlay mesh network of peers on which to efficiently send messages and metadata. Peers use control messages to broadcast and request known messages and subscribe/unsubscribe from topics in the mesh network.

Important Discrepancies

This section outlines the current implementation’s potential discrepancies from that of other implementations, due to undefined elements in the current specification.

• Topics - In gossipsub, topics configurable by the hash_topics configuration parameter. Topics are of type TopicHash. The current go implementation uses raw utf-8 strings, and this is default configuration in rust-libp2p. Topics can be hashed (SHA256 hashed then base64 encoded) by setting the hash_topics configuration parameter to true.

• Sequence Numbers - A message on the gossipsub network is identified by the source PeerId and a nonce (sequence number) of the message. The sequence numbers in this implementation are sent as raw bytes across the wire. They are 64-bit big-endian unsigned integers. They are chosen at random in this implementation of gossipsub, but are sequential in the current go implementation.

Using Gossipsub

GossipsubConfig

The GossipsubConfig struct specifies various network performance/tuning configuration parameters. Specifically it specifies:

• protocol_id - The protocol id that this implementation will accept connections on.
• history_length - The number of heartbeats which past messages are kept in cache (default: 5).
• history_gossip - The number of past heartbeats that the node will send gossip metadata about (default: 3).
• mesh_n - The target number of peers store in the local mesh network. (default: 6).
• mesh_n_low - The minimum number of peers in the local mesh network before. trying to add more peers to the mesh from the connected peer pool (default: 4).
• mesh_n_high - The maximum number of peers in the local mesh network before removing peers to reach mesh_n peers (default: 12).
• gossip_lazy - The number of peers that the local node will gossip to during a heartbeat (default: mesh_n = 6).
• `heartbeat_initial_delay - The initial time delay before starting the first heartbeat (default: 5 seconds).
• heartbeat_interval - The time between each heartbeat (default: 1 second).
• fanout_ttl - The fanout time to live time period. The timeout required before removing peers from the fanout for a given topic (default: 1 minute).
• max_transmit_size - This sets the maximum transmission size for total gossipsub messages on the network.
• hash_topics - Whether to hash the topics using base64(SHA256(topic)) or to leave as plain utf-8 strings.
• manual_propagation - Whether gossipsub should immediately forward received messages on the network. For applications requiring message validation, this should be set to false, then the application should call propagate_message(message_id, propagation_source) once validated, to propagate the message to peers.

This struct implements the Default trait and can be initialised via GossipsubConfig::default().

Gossipsub

The Gossipsub struct implements the NetworkBehaviour trait allowing it to act as the routing behaviour in a Swarm. This struct requires an instance of PeerId and GossipsubConfig.

Example

An example of initialising a gossipsub compatible swarm:

#extern crate libp2p;
#extern crate futures;
#extern crate tokio;
#use libp2p::gossipsub::GossipsubEvent;
#use libp2p::{identity, gossipsub,
#};
let local_key = identity::Keypair::generate_ed25519();
let local_pub_key = local_key.public();

// Set up an encrypted TCP Transport over the Mplex and Yamux protocols
let transport = libp2p::build_development_transport(local_key);

// Create a Floodsub/Gossipsub topic
let topic = libp2p::floodsub::TopicBuilder::new("example").build();

// Create a Swarm to manage peers and events
let mut swarm = {
    // set default parameters for gossipsub
    let gossipsub_config = gossipsub::GossipsubConfig::default();
    // build a gossipsub network behaviour
    let mut gossipsub =
        gossipsub::Gossipsub::new(local_pub_key.clone().into_peer_id(), gossipsub_config);
    gossipsub.subscribe(topic.clone());
    libp2p::Swarm::new(
        transport,
        gossipsub,
        libp2p::core::topology::MemoryTopology::empty(local_pub_key),
    )
};

// Listen on all interfaces and whatever port the OS assigns
let addr = libp2p::Swarm::listen_on(&mut swarm, "/ip4/0.0.0.0/tcp/0".parse().unwrap()).unwrap();
println!("Listening on {:?}", addr);

Modules

error	Error types that can result from gossipsub.
protocol

Structs

Gossipsub	Network behaviour that handles the gossipsub protocol.
GossipsubConfig	Configuration parameters that define the performance of the gossipsub network.
GossipsubConfigBuilder	The builder struct for constructing a gossipsub configuration.
GossipsubMessage	A message received by the gossipsub system.
GossipsubRpc	An RPC received/sent.
MessageId	A type for gossipsub message ids.
Topic	A gossipsub topic.
TopicHash

Enums

GossipsubEvent	Event that can happen on the gossipsub behaviour.
MessageAuthenticity	Determines if published messages should be signed or not.
ValidationMode	The types of message validation that can be employed by gossipsub.