Skip to content

Commit cdb2f52

Browse files
ppopthppopth
committed
Topic observation
1 parent 4f6850b commit cdb2f52

File tree

1 file changed

+166
-0
lines changed

1 file changed

+166
-0
lines changed

‎pubsub/gossipsub/gossipsub-v1.3.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# gossipsub v1.3: Topic observation
2+
3+
| Lifecycle Stage | Maturity | Status | Latest Revision |
4+
|-----------------|---------------|--------|-----------------|
5+
| 1A | Working Draft | Active | r1, 2024-05-28 |
6+
7+
Authors: [@pop]
8+
9+
Interest Group: [@pop]
10+
11+
[@pop]: https://github.com/ppopth
12+
13+
See the [lifecycle document][lifecycle-spec] for context about maturity level and spec status.
14+
15+
[lifecycle-spec]: https://github.com/libp2p/specs/blob/master/00-framework-01-spec-lifecycle.md
16+
17+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
18+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
19+
20+
- [Overview](#overview)
21+
- [Motivation](#motivation)
22+
- [Parameters](#parameters)
23+
- [Observing a topic](#observing-a-topic)
24+
- [Notifying observing peers](#notifying-observing-peers)
25+
- [Unobserving a topic](#unobserving-a-topic)
26+
- [Limits on observing peers](#limits-on-observing-peers)
27+
- [Control Messages](#control-messages)
28+
- [OBSERVE](#observe)
29+
- [UNOBSERVE](#unobserve)
30+
- [Protobuf](#protobuf)
31+
32+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
33+
34+
## Overview
35+
36+
This document specifies a minimal extension to the [gossipsub v1.2](gossipsub-v1.2.md) protocol.
37+
38+
The proposed extension is intended to enable the nodes to get notified when there is a new message in
39+
a topic without actually receiving the actual message.
40+
41+
Four new control messages are introduced: `OBSERVE`, `OBSERVED`, 'UNOBSERVE', and `UNOBSERVED`. They
42+
are primarily used to notify the peers that the node wants to observe/unobserve if there is a new
43+
message in the topic.
44+
45+
## Motivation
46+
47+
There are many use cases of topic observation:
48+
49+
- For a node that just wants to get notified when there is a new message in the topic and doesn't
50+
want to consume too much bandwidth by directly subscribing to the topic.
51+
52+
- For a node that wants to subscribe to the topic, but has some bandwidth constraint. The node can
53+
observe the topic and see which peer notifies it first and later send the `IWANT` to get the
54+
actual message. This ensures that the bandwidth used is approximately the size of the message.
55+
56+
The downside of topic observation is that the observing node is not part of the mesh network, so it
57+
only consumes the messages, but doesn't contribute to other peers by forwarding the messages.
58+
59+
## Parameters
60+
61+
This section lists new configurable parameters.
62+
63+
| Parameter | Description | Reasonable Default |
64+
|-------------|------------------------------------------------------------|--------------------|
65+
| `D_observe` | (Optional) the maximum number of observing peers per topic | `D` |
66+
67+
## Observing a topic
68+
69+
A node can observe a topic by sending an `OBSERVE` message to a peer that already subscribes to the topic.
70+
If the observation is successful, the peer will send back an `OBSERVED` message.
71+
72+
If the node already subscribes to the topic, it doesn't make sense for that node to observe the topic so
73+
the node SHOULD NOT send an `OBSERVE` message for that topic.
74+
75+
## Notifying observing peers
76+
77+
When a node receives a message in the topic, it will fordward the message to its mesh peers as usual and
78+
, in addition, it will also send the `IHAVE` message to the peers observing that topic.
79+
80+
Unlike normal `IHAVE` messages which are sent at the heartbeats, these `IHAVE`s are sent immediately when
81+
the message arrives.
82+
83+
After the observing peers receive the `IHAVE`, they MAY choose to request the message by sending an `IWANT`.
84+
85+
After the node receives an `IWANT` from an observing (not subscribing) peer, it SHOULD send back the message.
86+
87+
## Unobserving a topic
88+
89+
A node can unobserve a topic by sending an `UNOBSERVE` message to a peer that it previously sent an `OBSERVE`.
90+
If the unobservation is successful, the peer will send back an `UNOBSERVED` message.
91+
92+
## Limits on observing peers
93+
94+
If there are too many observing peers, those peers can send the `IWANT` messages and the node will have to
95+
send too many messages out to those peers which consumes a lot of bandwidth of the node.
96+
97+
The node MUST limit the number of observing peers per topic below or equal to `D_observe`.
98+
99+
If a node receives an `OBSERVE`, but the limit is already reached, it MAY send an `UNOBSERVED` to the peer
100+
with lowest score. Note that an `UNOBSERVED` can be sent, even if there is no `UNOBSERVE`.
101+
102+
## Control Messages
103+
104+
There are four new control messages introduced in this extension: `OBSERVE`, `OBSERVED`,
105+
`UNOBSERVE`, and `UNOBSERVED`.
106+
107+
### OBSERVE
108+
109+
The `OBSERVE` message informs a peer that the node wants to receive an IHAVE message immediately when
110+
there is a new message in the specified topic arriving at the peer.
111+
112+
If the node already subscribes to the topic, the peer MUST ignore the `OBSERVE` message.
113+
114+
### OBSERVED
115+
116+
The `OBSERVED` message informs a peer that the observation is successful.
117+
118+
### UNOBSERVE
119+
120+
The `UNOBSERVE` message informs a peer that the node doesn't want to receive an IHAVE message
121+
immediately for the specified topic anymore. This is like an undo message for the `OBSERVE`.
122+
123+
If there is no previous `OBSERVE` message for the specified topic from the node, the peer MUST ignore
124+
the `UNOBSERVE` message.
125+
126+
### UNOBSERVED
127+
128+
There are two use cases for `UNOBSERVED`:
129+
130+
- To inform a peer that the unobservation is successful.
131+
132+
- To inform a peer that it has been forced to unobserve.
133+
134+
## Protobuf
135+
136+
This extension extends the existing `ControlMessage` structure as follows.
137+
138+
```protobuf
139+
message RPC {
140+
// ... see definition in the gossipsub specification
141+
}
142+
143+
message ControlMessage {
144+
// ... see definition in the gossipsub specification
145+
repeated ControlObserve observe = 6;
146+
repeated ControlObserved observed = 7;
147+
repeated ControlUnobserve unobserve = 8;
148+
repeated ControlUnobserved unobserved = 9;
149+
}
150+
151+
message ControlObserve {
152+
optional string topicID = 1;
153+
}
154+
155+
message ControlObserved {
156+
optional string topicID = 1;
157+
}
158+
159+
message ControlUnobserve {
160+
optional string topicID = 1;
161+
}
162+
163+
message ControlUnobserved {
164+
optional string topicID = 1;
165+
}
166+
```

0 commit comments

Comments
 (0)