GossipSub 1.3 Extensions and Topic Observation

Overview

Py-libp2p supports the GossipSub v1.3 Extensions Control Message mechanism and the Topic Observation extension. These features require negotiating the /meshsub/1.3.0 protocol (or later) with peers.

Topic Observation

The Topic Observation extension allows a peer to receive IHAVE notifications for a topic without being a full subscriber. This is useful for presence awareness: knowing when messages are published on a topic without actually receiving the message payloads.

Lifecycle

  1. Start observing: Call start_observing_topic(topic) to send OBSERVE control messages to in-topic peers that support the extension. The router will then send IHAVE notifications to you when new messages arrive on that topic.

  2. Receive IHAVE: As an observer, you receive IHAVE control messages containing message IDs. These are presence notifications only; observers do not typically reply with IWANT to fetch the actual messages.

  3. Stop observing: Call stop_observing_topic(topic) to send UNOBSERVE control messages and stop receiving IHAVE notifications for that topic.

API Usage Snippet

The snippet below demonstrates the Topic Observation API calls. It is not a complete runnable program (host setup, service lifecycle, and peer wiring are omitted for brevity). For a runnable end-to-end example, see PubSub Chat Demo.

from libp2p import new_host
from libp2p.pubsub.gossipsub import PROTOCOL_ID_V13, GossipSub
from libp2p.pubsub.pubsub import Pubsub

# Create host and Pubsub with a v1.3-capable GossipSub router.
host = new_host()
gossipsub = GossipSub(
    protocols=[PROTOCOL_ID_V13],
    degree=6,
    degree_low=4,
    degree_high=12,
)
pubsub = Pubsub(host, gossipsub)

# Start observing a topic (IHAVE-only presence notifications).
# In practice, call this once Pubsub/GossipSub services are running.
await gossipsub.start_observing_topic("my-topic")

# ... later, when done ...
await gossipsub.stop_observing_topic("my-topic")

Protocol Requirements

  • Topic Observation requires both peers to negotiate /meshsub/1.3.0 (or later) and to advertise support via the Extensions Control Message.

  • Extensions are only sent when the negotiated protocol is v1.3+; peers on v1.1/v1.2 do not receive extension fields.

Specification References