Skip to content

docs: add sequence diagrams for partial messages protocol flows#11

Open
adarsh-7-satyam wants to merge 1 commit into
seetadev:masterfrom
adarsh-7-satyam:docs/gossipsub-partial-messages-sequence-diagrams
Open

docs: add sequence diagrams for partial messages protocol flows#11
adarsh-7-satyam wants to merge 1 commit into
seetadev:masterfrom
adarsh-7-satyam:docs/gossipsub-partial-messages-sequence-diagrams

Conversation

@adarsh-7-satyam
Copy link
Copy Markdown

Description

The partial-messages.md specification is the core document describing Gossipsub 1.4's Large Message Handling extension. While the text accurately describes the protocol mechanics, it lacks any visual representation of the multi-step flows involved. For a protocol as nuanced as Partial Messages — involving capability negotiation, eager data pushing, bitmap-based metadata exchange, and heartbeat gossip — text alone makes it difficult for new implementers to build a correct mental model of how the pieces fit together.

Problem

A developer reading partial-messages.md for the first time would encounter terms like partsMetadata, groupID, requestsPartial, and supportsSendingPartial without ever seeing how these fields flow between peers in a real interaction. The absence of sequence diagrams forces implementers to mentally simulate the protocol from scattered prose, increasing the risk of misimplementation and interoperability failures between py-libp2p and nim-libp2p.

Changes Made

Added a new ## Sequence Diagrams section to partial-messages.md containing four Mermaid sequence diagrams, each covering a distinct protocol flow:

  1. Extension Negotiation — Illustrates how two peers exchange SubOpts messages with requestsPartial and supportsSendingPartial flags to establish mutual support for the Partial Messages extension before any data is transferred.

  2. Eager Push Flow — Shows how a publisher can immediately push initial partialMessage data to a peer as Eager Data without waiting for a metadata exchange, and how the peer can subsequently send partsMetadata to request any remaining parts.

  3. partsMetadata Exchange Flow — Demonstrates the core synchronization mechanism where a peer sends a bitmap of its held parts, the responding peer identifies what is missing, and sends only those specific parts back, enabling efficient reassembly at the receiver.

  4. Heartbeat Gossip with Partial Messages — Depicts how during the periodic heartbeat, a node replaces the standard IHAVE gossip with partsMetadata when communicating with non-mesh peers, allowing them to request and receive only the parts they are missing.

How It Solves The Problem

Each diagram is placed within the existing flow of the document and preceded by a short explanatory paragraph that bridges the prose and the visual. Together, the four diagrams cover the complete lifecycle of a large message — from initial capability announcement, through eager and metadata-driven delivery, to gossip-based propagation — giving implementers a clear, unambiguous reference for every major interaction pattern defined in the spec.

Impact

  • New implementers can now onboard to the Partial Messages extension significantly faster by following the visual flows rather than piecing together the protocol from text alone
  • Reduces the risk of interoperability failures between implementations like py-libp2p and nim-libp2p by providing a shared visual reference for expected message sequences
  • Strengthens the specification's readiness for progression toward Working Draft and Candidate Recommendation status by meeting documentation standards expected of mature protocol specs

Related Issue

Closes #10

Signed-off-by: Adarsh Satyam <adarsh5.satyam@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: add sequence diagrams for Partial Messages protocol flows

1 participant