5. Configuration and Tuning
GossipSub is highly configurable, allowing you to tune its behavior to suit your application’s specific needs. These parameters are managed through the GossipSubParams class, which can be passed to the GossipSubRouter constructor.
Understanding these parameters is key to optimizing for different network conditions, whether you need high throughput, low latency, or resilience in a hostile environment.
// Example of creating a router with custom parametersfinal customParams = GossipSubParams( D: 8, DHigh: 16, DLow: 6, fanoutTTL: Duration(seconds: 30),);
final router = GossipSubRouter(params: customParams);Key Parameters
Section titled “Key Parameters”The following are the most important parameters you can configure in GossipSubParams.
Mesh Size Control
Section titled “Mesh Size Control”These parameters control the number of peers in your node’s mesh for any given topic. The mesh is the set of peers to which you forward full messages immediately.
D(default:6): The desired number of peers in the mesh. This is the target number the router will try to maintain.DLow(default:4): The minimum number of peers in the mesh. If the number of mesh peers drops below this, the router will actively seek out new peers toGRAFT.DHigh(default:12): The maximum number of peers in the mesh. If the number of mesh peers exceeds this, the router willPRUNEconnections to bring it back towardsD.
Tuning Advice:
- A larger
Dincreases robustness (more paths for messages to flow) at the cost of increased bandwidth, as you are sending full messages to more peers. - For topics with high message rates, a slightly larger
Dmight be beneficial. - The gap between
DLowandDHighprevents the network from constantly grafting and pruning, a behavior known as “churn”.
Gossip Propagation (DLazy)
Section titled “Gossip Propagation (DLazy)”DLazy(default:6): The number of non-mesh peers to whom you will sendIHAVEgossip messages. This controls how widely your messages are announced to the broader network.
Tuning Advice:
- Increasing
DLazycan speed up message propagation to peers outside your immediate mesh, at the cost of more control message overhead.
Heartbeat
Section titled “Heartbeat”The heartbeat is the router’s periodic task, as in go-libp2p-pubsub. It keeps each mesh between DLow and DHigh peers, prunes mesh peers with a negative score, maintains the fanouts, gossips the IDs of recent messages (IHAVE) and penalises peers that did not deliver messages they advertised.
heartbeatInterval(default:1 second): The time between heartbeats.heartbeatInitialDelay(default:100 ms): The time fromGossipSubRouter.start()to the first heartbeat.opportunisticGraftTicks(default:60): Opportunistic grafting (see below) runs once every this many heartbeats.
These defaults are go-libp2p-pubsub’s. All nodes in a network should use the same heartbeat interval.
Joining and Leaving Topics
Section titled “Joining and Leaving Topics”When the node subscribes to a topic, the router sends GRAFT to up to D peers at once. It picks them first from the topic’s fanout, then from the other connected peers subscribed to the topic, and leaves out peers with a negative score or in a backoff. When the node unsubscribes, the router sends PRUNE to each of its mesh peers for the topic.
unsubscribeBackoff(default:10 seconds): The backoff in thePRUNEmessages sent on unsubscribe. It asks the pruned peers not toGRAFTthe node again for this time.
Backoff
Section titled “Backoff”Every PRUNE carries a backoff: the time during which the two peers must not GRAFT each other again for the topic. The router keeps the backoff of the PRUNE messages it sends and receives, and does not GRAFT a peer during one.
pruneBackoff(default:1 minute): The backoff in thePRUNEmessages that the heartbeat sends, and the backoff applied when a receivedPRUNEhas none.graftFloodThreshold(default:10 seconds): A peer that sendsGRAFTduring a backoff gets aPRUNEand a behaviour penalty (P6); it gets a second penalty if it sends theGRAFTwithin this time of thePRUNE.
Fanout Control
Section titled “Fanout Control”The “fanout” is the set of peers you send full messages to for a topic you are not subscribed to but have published to. This ensures your message gets into the network.
fanoutTTL(default:1-minute): The duration for which a fanout map is maintained for a topic after you last published to it.
Tuning Advice:
- If your application publishes infrequently to many topics, a shorter
fanoutTTLcan reduce memory usage.
Mesh Degree and Gossip
Section titled “Mesh Degree and Gossip”The defaults are go-libp2p-pubsub’s.
D(6),DLow(5),DHigh(12): the target mesh size and its bounds. The heartbeat GRAFTs peers belowDLowand PRUNEs back toDatDHighor more.DScore(4): when pruning an oversized mesh, the number of peers kept for their score; the rest are kept at random.DOut(2): the number of outbound peers (connections the node dialed) kept in each mesh, against Sybils that connect to the node. Must be belowDLowandD/2.DLazy(6) andgossipFactor(0.25): each heartbeat gossips tomax(DLazy, gossipFactor * peers)topic peers outside the mesh.historyLength(5) andhistoryGossip(3): messages stay in the message cache for 5 heartbeats, forIWANT; the last 3 are gossiped.maxIHaveLength(5000),maxIHaveMessages(10),iwantFollowupTime(3 s),gossipRetransmission(3): limits on gossip from and to a peer. A peer that does not deliver a message it advertised withiniwantFollowupTimegets a behaviour penalty.floodPublish(true): the node’s own messages go to every topic peer with a score of at leastpublishThreshold, not only to the mesh.opportunisticGraftTicks(60) andopportunisticGraftPeers(2): when the median score of a mesh is belowopportunisticGraftThreshold, the heartbeat GRAFTs up to 2 peers that score above the median.- IDONTWANT (GossipSub v1.2): for a received message of at least
idontwantMessageThreshold(1 KiB) bytes, the node tells its v1.2 mesh peers not to send it a copy.
D = DLow = DHigh = DOut = DScore = 0 is the bootstrapper setting: no mesh.
Protocols
Section titled “Protocols”GossipSubRouter speaks /meshsub/1.3.0, /meshsub/1.2.0, /meshsub/1.1.0, /meshsub/1.0.0 and /floodsub/1.0.0, in that order of preference, and uses the features of the protocol negotiated with each peer. FloodSub peers get every message of their topics. FloodSubRouter and RandomSubRouter are also available.
With a v1.3 peer, each side announces its extensions in its first RPC, as go-libp2p-pubsub does; announcing them again costs a behaviour penalty of 10. No canonical extension exists yet. The experimental test extension is turned on with GossipSubRouter(testExtension: TestExtensionConfig(onReceiveTestExtension: ...)), as Go’s WithTestExtension; router.extensions.of(peer) tells what a peer announced.
Outbound Queue
Section titled “Outbound Queue”PubSub(peerOutboundQueueSize: 32) is the number of RPCs queued for each peer before more are dropped, as go-libp2p-pubsub’s WithPeerOutboundQueueSize (default 32, which defaultPeerOutboundQueueSize holds). Raise it if you publish bursts of messages faster than a peer’s connection takes them. It must be positive.
Message Validation
Section titled “Message Validation”seenMessagesTTL(GossipSubParams, default:2 minutes): How long the router remembers a message ID. A copy that arrives within this time is dropped as a duplicate without validation. As in go-libp2p-pubsub, the cache has no size limit.seenMessagesStrategy(GossipSubParams, default:SeenMessagesStrategy.firstSeen): WhetherseenMessagesTTLruns from when a message was first seen or, withlastSeen, from when it was last seen, as Go’sWithSeenMessagesStrategy.FloodSubRouterandRandomSubRoutertake both too.validatorTimeout(PubSubconstructor, default:5 seconds): The default time limit for one run of a topic validator. A slower run givesignore.Duration.zeromeans no limit.registerTopicValidator(..., timeout:)sets it per topic.validateThrottle(PubSubconstructor, default:8192): The maximum number of messages in validation at the same time. More messages are dropped asignore.registerTopicValidator(..., concurrency:)sets a per-topic limit (default1024).
See Validating Messages.
Blacklist
Section titled “Blacklist”As go-libp2p-pubsub’s WithBlacklist, PubSub(blacklist: Blacklist()) takes the set of blacklisted peers (an empty one by default), and pubsub.blacklistPeer(peerId) adds a peer, removing it from the router if it is connected. A blacklisted peer is not added or greeted, its RPCs are ignored, and messages it forwards or wrote are dropped before validation.
Discovery
Section titled “Discovery”As go-libp2p-pubsub’s WithDiscovery, PubSub(discovery: ...) takes a dart_libp2p Discovery service (a DHT, mDNS, a rendezvous point…) to find the peers of your topics:
- Each subscribed topic is advertised under the namespace
floodsub:<topic>(discoveryNamespacePrefix), the same as Go nodes use, and advertised again when the advertisement expires (or 2 minutes after a failure). The last unsubscription stops it. - Every second (
discoveryPollInterval), each subscribed topic on which the router has not enough peers (Router.enoughPeers:DLowfor GossipSub, 5 for FloodSub, 6 for RandomSub) is looked up, for at most 10 seconds, and the peers found are dialed. discoveryOptionsare passed to each call of the service (Go’sWithDiscoveryOpts).discoveryConnectorcreates the connector that dials the peers found (Go’sWithDiscoverConnector). The default,defaultDiscoveryConnector, is Go’s: a dart_libp2pBackoffConnectorthat waits 10 seconds to 1 hour, growing, before dialing the same peer again, for up to 100 peers, with dials of up to 2 minutes.
To wait for peers before publishing, as Go’s WithReadiness, pass ready:
await pubsub.publish(topic, data, ready: minTopicSize(3), readyTimeout: Duration(seconds: 30));The router decides when the topic is ready (minTopicSize(n) asks enoughPeers(topic, n)). While waiting, PubSub looks up peers of the topic if it has a discovery service. If readyTimeout passes first, the message is not published and a TimeoutException is thrown.
Peer Gater
Section titled “Peer Gater”As go-libp2p-pubsub’s WithPeerGater, GossipSubRouter(peerGaterParams: PeerGaterParams()) turns on the peer gater, which is off by default. When validation is being throttled (more than validateThrottle messages in validation), the gater handles only the control messages of some peers, chosen at random, the more likely the fewer of their messages were delivered: duplicates, ignored and rejected messages count against a peer (duplicateWeight, ignoreWeight, rejectWeight). Counters are kept per IP address, decay over time, and are kept for retainStats (6 hours) after the last peer of an address disconnects. PeerGaterParams has Go’s defaults (threshold: 0.33, quiet: 1 minute…).
Peer Scoring
Section titled “Peer Scoring”Peer scoring is off by default, as in go-libp2p-pubsub. Turn it on by giving the router both score parameters and thresholds (go-libp2p-pubsub’s WithPeerScore):
final router = GossipSubRouter( scoreParams: PeerScoreParams( topics: { 'chat': TopicScoreParams( topicWeight: 1, invalidMessageDeliveriesWeight: -10, // P4: weight * count^2 invalidMessageDeliveriesDecay: scoreParameterDecay(const Duration(hours: 1)), ), }, behaviourPenaltyWeight: -10, // P7 behaviourPenaltyDecay: scoreParameterDecay(const Duration(hours: 1)), ), scoreThresholds: const PeerScoreThresholds( gossipThreshold: -10, publishThreshold: -50, graylistThreshold: -80, acceptPXThreshold: 10, opportunisticGraftThreshold: 5, ),);The score follows go-libp2p-pubsub’s score.go: per scored topic, P1 (time in mesh), P2 (first deliveries), P3 (mesh delivery deficit), P3b (mesh failure penalty) and P4 (invalid messages), weighted by topicWeight and capped by topicScoreCap; then P5 (application-specific), P6 (IP colocation) and P7 (behaviour penalty). Only the topics in topics are scored. Both parameter sets are validated with go-libp2p-pubsub’s rules. router.score gives each peer’s score and its components (snapshot).
To score a topic created later, or to change a topic’s parameters, call router.setTopicScoreParams(topic, TopicScoreParams(...)), as go-libp2p-pubsub’s Topic.SetScoreParams. It works before or after the router starts, throws a StateError if scoring is off, and caps the peers’ delivery counters if the new caps are lower. For example, to penalise the senders of rejected messages on a new topic (P4) instead of computing an application-specific score (P5):
router.setTopicScoreParams('room-42', TopicScoreParams( topicWeight: 1, invalidMessageDeliveriesWeight: -10, invalidMessageDeliveriesDecay: scoreParameterDecay(const Duration(hours: 1)),));The thresholds: below gossipThreshold a peer gets no gossip and its gossip is ignored; below publishThreshold it gets none of our published messages; below graylistThreshold its RPCs are ignored. With all thresholds at 0, any negative score graylists a peer.
retainScore(PeerScoreParams, default:1 hour): how long the score of a disconnected peer with a score of 0 or less is kept, so that the peer cannot clear its penalties by reconnecting.
Prune and Peer Exchange (PX)
Section titled “Prune and Peer Exchange (PX)”Peer Exchange is off by default, as in go-libp2p-pubsub (WithPeerExchange); GossipSubRouter(doPX: true) turns it on, for bootstrappers and other well-connected nodes.
prunePeers(default:16): The number of other topic peers with a score of 0 or more to include in aPRUNE, with their signed peer records. As in go-libp2p-pubsub, the router keeps its own certified address book (router.certifiedAddrBook), filled with the records identify receives from each peer and those received through PX. No PX is sent to a peer pruned for a negative score. It is also the most peers connected to from one receivedPRUNE.
Whatever doPX is, the router connects to the PX peers of a received PRUNE if the sender’s score is at least acceptPXThreshold (PeerScoreThresholds, default 0), as go-libp2p-pubsub does. A signed peer record must be about the peer and signed by its key; its addresses are stored in the address book for two minutes, then the peer is dialed at the addresses known for it.
connectors(default:8): the PX connections attempted at once.maxPendingConnections(default:128): the PX peers waiting to be connected to; more are ignored.connectionTimeout(default:30 seconds): how long a PX connection attempt may take.
Tuning Advice:
- A higher value can help pruned peers reconnect faster, improving overall network health.