Clarifications in the gossipsub specification

Today, I had a chat with some of the libp2p core engineers (@vasco-santos, @raulk and @jacobheun ) and @mgoelzer. Mike mentioned that I should create an issue with clarifications that should be added to the gossipsub specification.

Here are some clarifications that I think the gossipsub specification needs:

• Gossipsub creates an overlay network over an underlying network. Thus, it doesn't affect the underlying network's topology. The network topology of gossipsub is a strongly connected mesh (see #122 ). This is implied in the spec but I think making it more explicit might help.

• Adding a glossary for terms that aren't used in the p2p networking literature such as ambient peer discovery.

• In meshsub, when a peer selects a subset of peers to create the mesh with, which peers are under consideration? Is it the peers that the peer finds from ambient peer discovery or is the peers that have subscribed to that peer's topic(s)?

• In meshsub, clarifying how often the stabilization algorithm is run could be helpful to implementers that just want to use meshsub. This could also be an implementation detail that could instead be added to an implementers guide.

• Adding guidelines for the choice of parameters such as D, D_high and D_low. These are obviously implementation independent. It might be a good idea to add this to an implementers' guide

• The control message piggybacking section is unclear and says that one should consult the Go implementation. Is this portion of gossipsub implementation specific or can it be described without being tied to a specific implementation?

• The gossip is emitted to random subsets of peers not in the mesh, similar to randomsub, and it allows us to propagate metadata about message flow throughout the network.

The above statement is unclear. I remember when the spec was just starting, that there was a distinction between eager push and lazy push. Lazy push is when a peer sends metadata about a message to other peers and eager push is when a peer sends all of the data to other peers. Is the above statement alluding to that?

• Add more specifications to the message cache data structure. As it stands, one has to go over the Go implementation of a message cache to understand what it does.

• Clarify the different between Join and Subscribe. Similarly, for Leave and Unsubscribe.

• I think the description of the Join operation can be better written.

• Add guidelines for when to run the heartbeat procedure for stabilizing the mesh, emitting gossip and maintaining fanout.

Start with the gossipsub specification sections on topology, mesh formation, stabilization, control-message piggybacking, gossip, message cache, and Join/Subscribe operations. Compare the relevant behavior with the Go implementation where the issue says the specification is underspecified. Done means the listed terminology, semantics, timing, parameters, and implementation guidance are resolved and documented consistently.