enh/1231-add-gossipsub-1.3-support

docs/examples.rst

@@ -24,6 +24,7 @@ Examples
    examples.multiple_connections
    tls-support
    gossipsub-1.2
+   gossipsub-1.3
    examples.websocket
    examples.tls
    examples.tcp

docs/gossipsub-1.3.rst

@@ -0,0 +1,84 @@
+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
+:doc:`examples.pubsub`.
+
+.. code-block:: python
+
+    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
+------------------------
+
+* `GossipSub v1.3 Extensions <https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.3.md>`_
+* `Topic Observation proposal <https://ethresear.ch/t/gossipsub-topic-observation-proposed-gossipsub-1-3/20907>`_
+
+Related Documentation
+---------------------
+
+* :doc:`gossipsub-1.2` - GossipSub 1.2 features (IDONTWANT, etc.)
+* :doc:`examples.pubsub` - PubSub chat example
+* :doc:`libp2p.pubsub` - Complete PubSub API documentation

docs/libp2p.pubsub.rst

@@ -3,7 +3,9 @@ libp2p.pubsub package
 
 Py-libp2p provides a comprehensive PubSub implementation with support for both FloodSub and GossipSub protocols, including the latest GossipSub 1.2 specification with IDONTWANT control messages for improved bandwidth efficiency.
 
-For detailed information about GossipSub 1.2 features and configuration, see :doc:`gossipsub-1.2`.
+For detailed information about GossipSub features and configuration, see
+:doc:`gossipsub-1.2` (IDONTWANT, etc.) and :doc:`gossipsub-1.3` (v1.3 extensions,
+Topic Observation).
 
 Subpackages
 -----------