diff --git a/pubsub/gossipsub/gossipsub-v1.3.md b/pubsub/gossipsub/gossipsub-v1.3.md new file mode 100644 index 000000000..ad52682af --- /dev/null +++ b/pubsub/gossipsub/gossipsub-v1.3.md @@ -0,0 +1,166 @@ +# gossipsub v1.3: Topic observation + +| Lifecycle Stage | Maturity | Status | Latest Revision | +|-----------------|---------------|--------|-----------------| +| 1A | Working Draft | Active | r1, 2024-05-28 | + +Authors: [@pop] + +Interest Group: [@pop] + +[@pop]: https://github.com/ppopth + +See the [lifecycle document][lifecycle-spec] for context about maturity level and spec status. + +[lifecycle-spec]: https://github.com/libp2p/specs/blob/master/00-framework-01-spec-lifecycle.md + + + + +- [Overview](#overview) +- [Motivation](#motivation) +- [Parameters](#parameters) +- [Observing a topic](#observing-a-topic) +- [Notifying observing peers](#notifying-observing-peers) +- [Unobserving a topic](#unobserving-a-topic) +- [Limits on observing peers](#limits-on-observing-peers) +- [Control Messages](#control-messages) + - [OBSERVE](#observe) + - [UNOBSERVE](#unobserve) +- [Protobuf](#protobuf) + + + +## Overview + +This document specifies a minimal extension to the [gossipsub v1.2](gossipsub-v1.2.md) protocol. + +The proposed extension is intended to enable the nodes to get notified when there is a new message in +a topic without actually receiving the actual message. + +Four new control messages are introduced: `OBSERVE`, `OBSERVED`, `UNOBSERVE`, and `UNOBSERVED`. They +are primarily used to notify the peers that the node wants to observe/unobserve if there is a new +message in the topic. + +## Motivation + +There are many use cases of topic observation: + +- For a node that just wants to get notified when there is a new message in the topic and doesn't + want to consume too much bandwidth by directly subscribing to the topic. + +- For a node that wants to subscribe to the topic, but has some bandwidth constraint. The node can + observe the topic and see which peer notifies it first and later send the `IWANT` to get the + actual message. This ensures that the bandwidth used is approximately the size of the message. + +The downside of topic observation is that the observing node is not part of the mesh network, so it +only consumes the messages, but doesn't contribute to other peers by forwarding the messages. + +## Parameters + +This section lists new configurable parameters. + +| Parameter | Description | Reasonable Default | +|-------------|------------------------------------------------------------|--------------------| +| `D_observe` | (Optional) the maximum number of observing peers per topic | `D` | + +## Observing a topic + +A node can observe a topic by sending an `OBSERVE` message to a peer that already subscribes to the topic. +If the observation is successful, the peer will send back an `OBSERVED` message. + +If the node already subscribes to the topic, it doesn't make sense for that node to observe the topic so +the node SHOULD NOT send an `OBSERVE` message for that topic. + +## Notifying observing peers + +When a node receives a message in the topic, it will fordward the message to its mesh peers as usual and +, in addition, it will also send the `IHAVE` message to the peers observing that topic. + +Unlike normal `IHAVE` messages which are sent at the heartbeats, these `IHAVE`s are sent immediately when +the message arrives. + +After the observing peers receive the `IHAVE`, they MAY choose to request the message by sending an `IWANT`. + +After the node receives an `IWANT` from an observing (not subscribing) peer, it SHOULD send back the message. + +## Unobserving a topic + +A node can unobserve a topic by sending an `UNOBSERVE` message to a peer that it previously sent an `OBSERVE`. +If the unobservation is successful, the peer will send back an `UNOBSERVED` message. + +## Limits on observing peers + +If there are too many observing peers, those peers can send the `IWANT` messages and the node will have to +send too many messages out to those peers which consumes a lot of bandwidth of the node. + +The node MUST limit the number of observing peers per topic below or equal to `D_observe`. + +If a node receives an `OBSERVE`, but the limit is already reached, it MAY send an `UNOBSERVED` to the peer +with lowest score. Note that an `UNOBSERVED` can be sent, even if there is no `UNOBSERVE`. + +## Control Messages + +There are four new control messages introduced in this extension: `OBSERVE`, `OBSERVED`, +`UNOBSERVE`, and `UNOBSERVED`. + +### OBSERVE + +The `OBSERVE` message informs a peer that the node wants to receive an IHAVE message immediately when +there is a new message in the specified topic arriving at the peer. + +If the node already subscribes to the topic, the peer MUST ignore the `OBSERVE` message. + +### OBSERVED + +The `OBSERVED` message informs a peer that the observation is successful. + +### UNOBSERVE + +The `UNOBSERVE` message informs a peer that the node doesn't want to receive an IHAVE message +immediately for the specified topic anymore. This is like an undo message for the `OBSERVE`. + +If there is no previous `OBSERVE` message for the specified topic from the node, the peer MUST ignore +the `UNOBSERVE` message. + +### UNOBSERVED + +There are two use cases for `UNOBSERVED`: + +- To inform a peer that the unobservation is successful. + +- To inform a peer that it has been forced to unobserve. + +## Protobuf + +This extension extends the existing `ControlMessage` structure as follows. + +```protobuf +message RPC { + // ... see definition in the gossipsub specification +} + +message ControlMessage { + // ... see definition in the gossipsub specification + repeated ControlObserve observe = 6; + repeated ControlObserved observed = 7; + repeated ControlUnobserve unobserve = 8; + repeated ControlUnobserved unobserved = 9; +} + +message ControlObserve { + optional string topicID = 1; +} + +message ControlObserved { + optional string topicID = 1; +} + +message ControlUnobserve { + optional string topicID = 1; +} + +message ControlUnobserved { + optional string topicID = 1; +} +```