Skip to content

Gossip Protocol

Aviv Eyal edited this page Oct 1, 2019 · 3 revisions

P2P Gossip Protocol Design Notes

A gossip protocol is a protocol used to disseminate messages across the network. We must employ a robust and measurable protocol since some of Spacemesh’s core protocols are bound to message propagation latency. This protocol will ensure all peers will get a message within a certain time and harden the network's security since nodes can receive and send message without knowing the origin/destination physical address.

The gossip protocol is plugged to the swarm, it consists of two parts -

  • Neighborhood maintenance
  • Message dissemination and termination

Upon receiving a message with the gossip header it will be forwarded to the gossip protocol.

package gossip

Public API

  • Start() error - Starts the gossip protocol neighborhood
  • ‘Shutdown()’ - Graceful shutdown, should send all queue operation returns an error incase the message is invalid (known messages are considered invalid). Otherwise returns the payload of the message, without the Gossip header, to be processed by the protocol handler

Gossip message headers

A message is sent with a Metadata header, this header contains another header, Gossip. If the gossip header is present the swarm will identify this message as gossip and forward it to the gossip protcol with the headers.

Message {
    Metadata = {
    … // some other headers
        Gossip = {
            … // TBD: more headers related to gossip


The neighborhood is in charge of holding config.RandomConnections number of peers with active connection. Whenever there are less then this number of peers (e.g. peers went offline, during startup) it asks DHT for the new peers, using the PeerSampler and tries to connect with them. It will continue fetching new peers until it got sufficient number of peers or until it exhausted the number of retries. The number of retries is derived from the number of peers existing in DHT.

Interface PeerSampler

Struct in charge of fetching peers from DHT. We would like to examine several methods of peer selection: Select random peers across all peers in DHT. Select peers in a round robin manner from the DHT’s buckets. Select peers in any of the ways above with a restriction that you only select peers which are part of a region (prefix) that was stated in the message (based on the method described in (

Connection loop
    peers map[string]*peer // the neighborhood, size: config.RandomConnections
    oldMessages map[string]struct{} // tracking messages we know

Incoming messages handling

On receiving a new Gossip message swarm will call Gossip.Broadcast which will return an error in case the message was already seen or in case the message is invalid. If this is a valid message, swarm will process the message using the protocol handler.

Message dissemination

The Gossip protocol will iterate on all peers it has in its cache and enqueue the message to every one of them. The message will be added to a cache of known messages.

Saving bandwidth optimization - Push-Pull

To save bandwidth on big messages, we add an optimization to make sure they will only be sent once. The gossip protocol will use a push-pull mechanism, it will inform its neighbors that it got a new message and will share an identifier of the message, if the receiving node didn’t get the message already it will request it and we will send it.