GossipSub: How IPFS's PubSub Layer Actually Works

GossipSub solves a problem the DHT and Bitswap, both covered earlier in this series, aren't built for: pushing a message to every interested peer as it happens, rather than answering a one-time lookup. Where the DHT answers "who has this CID" on request, GossipSub is a standing channel, peers subscribe to a topic once and keep receiving whatever gets published to it, which is exactly the mechanism behind real-time IPNS updates and any other pattern that needs live propagation instead of request-response.

TL;DR:

• GossipSub is libp2p's publish-subscribe protocol: peers subscribe to named topics and receive every message published to them, without needing to know in advance who's going to send something
• It works by maintaining a mesh, a bounded-degree overlay network of peers per topic, and propagating both full messages and lightweight gossip about what's been seen recently across that mesh
• The gossip half runs on two message types: IHAVE, a peer announcing message IDs it has recently seen, and IWANT, a peer requesting the full content of specific messages it's missing
• This design blends two ideas on purpose: a mesh for efficient, low-redundancy delivery of full messages, and gossip for resilience, catching messages a peer's direct mesh connections happened to miss
• IPNS records, covered earlier in this series, can be published over PubSub as an alternative to the DHT, propagating updates directly to already-subscribed peers instead of waiting on a DHT lookup

A Different Problem Than the DHT Solves

This series' DHT article covers a specific pattern: a peer wants to know who has a given CID, right now, and runs a lookup to find out. That model assumes the answer is being asked for, on demand, by whoever needs it. GossipSub assumes the opposite: peers who already care about a topic want to be pushed new information the moment it exists, without repeatedly asking. Subscribing once and then receiving a stream of updates is a fundamentally different shape than a lookup, and libp2p handles it with a separate protocol rather than stretching the DHT to cover both.

Topics: Subscribe Once, Receive Continuously

A GossipSub topic is just a named channel. A peer subscribes to a topic it cares about, and from that point forward receives every message another peer publishes to that same topic, without needing to know ahead of time who those publishers are or how many of them exist. Publishing works the same way in reverse: a peer sends a message to a topic once, and the protocol's job is making sure it reaches every subscriber, not just the peers the publisher happens to be directly connected to.

The Mesh: An Efficient Delivery Backbone

Underneath a topic, GossipSub maintains a mesh, an overlay network of peers with a bounded number of direct connections per topic, rather than every subscriber connecting to every other subscriber. Full messages get forwarded directly across mesh links, which keeps delivery efficient and keeps redundant copies of the same message from flooding the network. The tradeoff is that a mesh alone isn't guaranteed to reach every peer reliably on its own, connections drop, meshes reshape, and a peer can miss a message that only traveled through links it wasn't part of at that moment.

Gossip: IHAVE and IWANT as the Safety Net

That's what the "gossip" half of GossipSub is for. Alongside full messages traveling the mesh, peers periodically send IHAVE announcements, lightweight lists of message IDs they've recently seen, to peers they're gossiping with but aren't necessarily meshed with directly. A peer that sees an IHAVE for a message it doesn't already have can respond with IWANT, requesting the full content specifically. This two-message pattern is deliberately cheap: IHAVE messages are small metadata, not full payloads, so a peer can gossip about a lot of recent activity without the bandwidth cost of forwarding every message to every gossip partner.

Why Combine a Mesh With Gossip At All

Splitting delivery into a mesh plus a gossip layer gets the benefit of each without fully committing to either one's downside. A pure mesh-only design is efficient but fragile against the exact connection churn a real peer-to-peer network has constantly. A pure gossip-only design (spreading full messages via metadata-and-request round trips everywhere) is resilient but wastes bandwidth compared to direct mesh forwarding. GossipSub runs both at once: the mesh carries the bulk of normal delivery efficiently, and gossip catches whatever the mesh's own reshaping and churn cause it to miss.

Where This Connects to IPNS

This series' IPNS article already mentioned that IPNS records can be published two ways: through the DHT's provider-record mechanism, or over PubSub. GossipSub is the concrete protocol behind that second option. Publishing an IPNS update over PubSub means peers already subscribed to that name's topic receive the new record directly as it's published, rather than needing to run a fresh DHT lookup to notice the update, a real latency difference for any peer that's already listening.

Where This Fits an AIOZ Pin Workflow

Nothing about AIOZ Pin's own pinning and gateway features depends on GossipSub directly, pinning is about persistent storage and discoverability, covered throughout this series' DHT and reproviding coverage. Where GossipSub becomes relevant is for anyone layering their own IPNS-based update mechanism on top of AIOZ-Pin-hosted content, the pattern this series' IPNS article already covers: publishing new versions faster to already-subscribed clients by using PubSub instead of relying solely on the DHT's lookup-based propagation.

Frequently Asked Questions

What problem does GossipSub solve that the DHT doesn't? Real-time, ongoing delivery to everyone subscribed to a topic. The DHT answers a one-time lookup; GossipSub keeps pushing new messages to already-subscribed peers as they're published.

What is a GossipSub mesh? An overlay network of peers per topic, each maintaining a bounded number of direct connections, used to efficiently forward full messages without every peer connecting to every other peer.

What do IHAVE and IWANT messages do? IHAVE is a lightweight announcement of message IDs a peer has recently seen; IWANT is a request for the full content of specific messages a peer learned about but doesn't already have.

Why does GossipSub use both a mesh and gossip instead of just one? The mesh is efficient but can miss messages during connection churn; gossip is a resilient backstop that catches what the mesh's own reshaping causes it to drop, without the bandwidth cost of forwarding everything to everyone.

How does GossipSub relate to IPNS? IPNS records can be published over PubSub instead of the DHT, so already-subscribed peers receive an updated record directly rather than needing to run a fresh lookup to discover it.

Does AIOZ Pin use GossipSub for pinning? No. Pinning and gateway access don't depend on GossipSub. It's relevant specifically for anyone building their own PubSub-based update mechanism, like faster IPNS propagation, on top of pinned content.

Related Reading

• IPNS: Mutable Pointers to Immutable IPFS Content - the DHT-vs-PubSub publishing choice this article's PubSub half explains in depth
• libp2p: The Networking Layer Underneath IPFS - the connection layer GossipSub's mesh and gossip messages travel over
• How IPFS Finds and Retrieves Your Files: DHT Provider Records and Bitswap Explained - the lookup-based model GossipSub's push-based delivery contrasts with

References

• libp2p specs: GossipSub v1.0
• go-libp2p-pubsub