From fabd3ae65f5a70c90007afa0052e3879bd32606d Mon Sep 17 00:00:00 2001 From: Anton Nashatyrev Date: Wed, 12 Jul 2023 12:23:21 +0400 Subject: [PATCH 1/2] Initial Gossip PING/PONG spec --- pubsub/gossipsub/gossipsub-v1.2.md | 102 +++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 pubsub/gossipsub/gossipsub-v1.2.md diff --git a/pubsub/gossipsub/gossipsub-v1.2.md b/pubsub/gossipsub/gossipsub-v1.2.md new file mode 100644 index 000000000..fa2e5dbf1 --- /dev/null +++ b/pubsub/gossipsub/gossipsub-v1.2.md @@ -0,0 +1,102 @@ +# Gossipsub v1.2 + +# Overview + +This document aims to provide a minimal extension to the [gossipsub +v1.1](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md) +protocol. + +The proposed extensions are backwards-compatible and aim to add utility control messages for +better network efficiency (delivery latency and total throughput) tuning gossip protocol +implementations + +In more specific terms, new control messages are introduced: `PING` and `PONG`. +They are primarily intended for collecting statistics to estimate peer connection +latency and bandwidth and adjusting message broadcasting strategy accordingly. + +# Specification + +## Protocol Id + +Nodes that support this Gossipsub extension should additionally advertise the +version number `1.2.0`. Gossipsub nodes can advertise their own protocol-id +prefix, by default this is `meshsub` giving the default protocol id: +- `/meshsub/1.2.0` + +## Parameters + +This section lists the configuration parameters that needs to agreed on across clients to avoid +peer penalizations + +| Parameter | Description | Reasonable Default | +|-------------------|------------------------------------------------------------------------|--------------------| +| `max_ping_rate` | maximum number of `PING` messages per minute | 60 | + +## PING/PONG Messages + +### Sender + +Sender MAY send `PING` message (either standalone or piggy tailing) at any time. Sender is free to choose +any `id` however it might be reasonable to select unique numbers across the session. + +Sender MUST NOT send `PING` message to a peer if `max_ping_rate` `PING` message were already sent +to that peer during the last minute. + +An implementation is free to choose a reasonable timeout (e.g. 60 seconds) for waiting for a corresponding +`PONG` message. However it is worth considering that a `PONG` message might be +delayed by another message which is already in the send buffer (on wire) , thus the timeout should not be too small. +`PONG` timeout exceeding SHOULD be treated as protocol malfunction and the peer connection +SHOULD be closed + +### Responder + +Upon receiving a `PING` message the responder +- MUST respond with a `PONG` message with the same `id` value +- SHOULD check if the `max_ping_rate` is respected by sending peer (otherwise the peer MAY be penalized) +- SHOULD make his best to respond back with a corresponding `PONG` as soon as possible. That means: + - SHOULD NOT queue the message for later send (e.g. on heartbeat or piggy tailing for a next publish message) + - if there are messages queued for sending to the peer that queue SHOULD be disregarded and the + the `PONG` message should be flushed immediately + +### Usage scenarios + +#### Latency estimation + +This is the most obvious and basic scenario of Ping/Pong usage. Gossip implementation may use estimated +connection latency to optimize message dissemination behavior (e.g. adjust the staggered sending strategy). +This could be implemented without relying on external protocols. + +Worth mentioning that the latencies measured with Gossip Ping/Pong may have significant outliers as all +the gossip messages are transmitted sequentially and both `PING` and `PONG` messages could be delayed +due to a message which was buffered for sending a moment earlier. +Thus it makes sense to consider the lower percentile of measured latencies within some time window. + +#### Message delivery ACKnowledgement + +When sending a message (especially of a larger size) the sender may attach a `PING` control message such +that a receiver would respond with `PONG` as soon as the message transfer is complete. That way the sender +may roughly estimate connection bandwidth to optimize its message dissemination behavior. + +## Protobuf Extension + +The protobuf messages are identical to those specified in the [gossipsub v1.0.0 +specification](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0.md) +with the following control message modifications: + +```protobuf +message RPC { + // ... see definition in the gossipsub specification +} + +message ControlMessage { + // messages from v1.0 + optional ControlPingPong ping = 5; + optional ControlPingPong pong = 6; +} + +message ControlPingPong { + required uint64 id = 1; +} + +``` + From 6a3f1cfda0971e70e086b80528014fc76f1037b6 Mon Sep 17 00:00:00 2001 From: Anton Nashatyrev Date: Mon, 17 Jul 2023 12:18:53 +0400 Subject: [PATCH 2/2] Add authors and interest group members --- pubsub/gossipsub/gossipsub-v1.2.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pubsub/gossipsub/gossipsub-v1.2.md b/pubsub/gossipsub/gossipsub-v1.2.md index fbdd8f13b..af4a1ba5a 100644 --- a/pubsub/gossipsub/gossipsub-v1.2.md +++ b/pubsub/gossipsub/gossipsub-v1.2.md @@ -4,11 +4,13 @@ |-----------------|---------------------------|--------|-----------------| | 1A | Working Draft | Active | r1, 2023-07-14 | -Authors: +Authors: [@Nashatyrev], [@Menduist] -Interest Group: [@vyzo] +Interest Group: [@vyzo], [@Nashatyrev], [@Menduist] [@vyzo]: https://github.com/vyzo +[@Nashatyrev]: https://github.com/Nashatyrev +[@Menduist]: https://github.com/Menduist See the [lifecycle document][lifecycle-spec] for context about maturity level and spec status.