Skip to content

Commit 1b537be

Browse files
ufarooqstatusufarooqstatus
committed
GossipSub v1.4 specs to include message preamble, IWANT optimizations and IMReceiving message
1 parent b5f7fce commit 1b537be

File tree

1 file changed

+164
-0
lines changed

1 file changed

+164
-0
lines changed

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

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# gossipsub v1.4: Message preamble to limit duplicate transmissions of large messages
2+
3+
| Lifecycle Stage | Maturity | Status | Latest Revision |
4+
|-----------------|---------------------------|--------|-----------------|
5+
| 1A | Working Draft | Active | r0, 2024-12-17 |
6+
7+
Authors: [@ufarooqstatus], [@kaiserd]
8+
9+
Interest Group: TBD
10+
11+
[@kaiserd]: https://github.com/kaiserd
12+
[@ufarooqstatus]: https://github.com/ufarooqstatus
13+
14+
See the [lifecycle document][lifecycle-spec] for context about maturity level and spec status.
15+
16+
[lifecycle-spec]: https://github.com/libp2p/specs/blob/master/00-framework-01-spec-lifecycle.md
17+
18+
# Overview
19+
20+
This document outlines small extensions to the [gossipsub
21+
v1.2](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.2.md)
22+
protocol to improve performance when handling large message transmissions.
23+
The extensions are optional, fully compatible with v1.2 of the protocol,
24+
and involve minor modifications to peer behavior when receiving or forwarding large messages.
25+
26+
The proposed modifications address the issue that the number of IWANT requests and duplicates increases significantly with the message size.
27+
This happens because sending a large message can take considerable time,
28+
and during this time, the receiver is unaware of the IDs of the messages it is receiving.
29+
30+
Under the current arrangement, if IHAVE announcements are received for a message that is already being received,
31+
the receiver may generate multiple IWANT requests, triggering unnecessary retransmissions of the same message.
32+
Higher message reception time also increases the probability of simultaneously receiving the same message from many peers.
33+
34+
Prepending a preamble while sending a large message can allow receivers
35+
to immediately gain insights into the IDs and lengths of the messages they are receiving.
36+
This can allow receivers to defer IWANT requests for messages they are currently receiving,
37+
thereby reducing the number of unnecessary IWANT requests.
38+
39+
At the same time, receivers may inform their mesh members about ongoing message reception.
40+
For this purpose, a new control message (IMReceiving) is introduced,
41+
indicating that the peer sending IMReceiving message is currently receiving messages identified by their message IDs,
42+
and sending duplicates might be unnecessary.
43+
44+
On receiving an IMReceiving message, a peer should defer sending of messages identified by the message IDs in IMReceiving message.
45+
This can lead to a significant reduction in bandwidth utilization and message latency.
46+
47+
# Specification
48+
49+
## Protocol Id
50+
51+
Nodes that support this Gossipsub extension should additionally advertise the
52+
version number `1.4.0`. Gossipsub nodes can advertise their own protocol-id
53+
prefix, by default this is `meshsub` giving the default protocol id:
54+
- `/meshsub/1.4.0`
55+
56+
## Parameters
57+
58+
This section lists the configuration parameters that clients need to agree on to avoid peer penalizations.
59+
60+
| Parameter | Description | Reasonable Default |
61+
|--------------------------|------------------------------------------------------------------|--------------|
62+
| `peer_preamble_announcements` | The maximum number of preamble announcements for unfinished transfers per peer | 1??? |
63+
| `mesh_preamble_announcements` | The maximum number of preamble announcements to accept for unfinished transfers per topic per heartbeat interval | 3??? |
64+
| `max_iwant_requests` | The maximum number of simultaneous IWANT requests for a message | 1??? |
65+
| `preamble_threshold` | The smallest message size to use message preamble | 200KB??? |
66+
67+
68+
69+
## Message Preamble
70+
71+
### Basic scenario
72+
73+
When a peer starts relaying a message that exceeds the preamble_threshold size,
74+
it may include a control message (called message preamble) at the start of the message.
75+
76+
The purpose of the preamble is to allow receivers to instantly learn about the incoming message.
77+
The preamble must include the message ID and length,
78+
providing receivers with immediate access to critical information about the incoming message.
79+
The receiver must immediately process a message preamble without waiting to download the entire message.
80+
81+
On receiving a preamble that advertises a message ID not present in the seen cache,
82+
a receiver should add that message ID to the ongoing_receives list.
83+
The ongoing_receives list is crucial in limiting IWANT requests and simultaneous reception of the same message from mesh peers.
84+
85+
The receiver may use message length to leniently estimate message download time.
86+
If the message is successfully downloaded before the estimated download time has elapsed,
87+
the message ID is removed from the ongoing_receives list and added to the seen cache.
88+
89+
If the download takes longer than the estimated download time,
90+
the sender may be penalized through P4 to discourage peers from intentionally delaying message transmission.
91+
92+
The message preamble is considered _optional_ for both the sender and the receiver.
93+
This means that the sender may choose not to prepend the preamble,
94+
and the receiver may also opt to ignore it.
95+
Adding a message preamble may increase control overhead for small messages.
96+
Therefore, it is preferable to use it only for messages that exceed the preamble_threshold.
97+
98+
99+
### Limiting IWANT Requests
100+
101+
When a peer receives an IHAVE announcement for a message ID not present in the seen cache,
102+
the peer must also check the ongoing_receives list before making an IWANT request.
103+
104+
If the message ID is found in the ongoing_receives list,
105+
the peer should postpone sending the IWANT request for a defer_interval.
106+
The defer_interval may be based on the message download time.
107+
108+
If the message download completes before the defer_interval expires,
109+
the IWANT request for that message will not be generated.
110+
However, if the defer_interval elapses and the download has not completed,
111+
the peer can proceed to make the IWANT request for the missing message.
112+
113+
The total number of outstanding IWANT requests for a single message should not exceed max_iwant_requests.
114+
Every peer must respond to the received IWANT requests.
115+
Failing to do so may result in behavioural penalty through P7.
116+
This will discourage peers from intentionally not replying to IWANT requests.
117+
118+
### IMReceiving Message
119+
120+
The IMReceiving message serves a distinct purpose compared to the IDONTWANT message.
121+
An IDONTWANT can only be transmitted after receiving the entire message.
122+
In contrast, an IMReceiving should be transmitted immediately after receiving a preamble indicating a large message transfer.
123+
The IMReceiving message requests peers to refrain from resending a large message that is already being received.
124+
125+
When a peer receives a message preamble indicating a message ID that is not present in the seen cache,
126+
it should send an IMReceiving message to the nodes in its full message mesh.
127+
On receiving an IMReceiving from a peer,
128+
a node should postpone sending the messages indicated by the IMReceiving to that peer.
129+
The defer_interval can be leniently estimated based on the message length.
130+
131+
An IDONTWANT from the peer will indicate successful reception of the message.
132+
If an IDONTWANT for the deferred message is not received and the defer_interval has elapsed,
133+
the node may proceed to transmit the message.
134+
135+
136+
## Protobuf Extension
137+
138+
The protobuf messages are identical to those specified in the [gossipsub v1.2
139+
specification](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.2.md)
140+
with the following control message modifications:
141+
142+
```protobuf
143+
message RPC {
144+
// ... see definition in the gossipsub specification
145+
}
146+
147+
message ControlMessage {
148+
// ... see definition in the gossipsub specification
149+
repeated ControlPreamble preamble = 6;
150+
repeated ControlIMReceiving imreceiving = 7;
151+
}
152+
153+
message ControlPreamble {
154+
optional bytes messageID = 1;
155+
optional int32 messageLength = 2;
156+
}
157+
158+
message ControlIMReceiving {
159+
optional bytes messageID = 1;
160+
optional int32 messageLength = 2;
161+
}
162+
163+
```
164+

0 commit comments

Comments
 (0)