Skip to content

docs(gossipsub-v1.4): Add design document for large message propagation#720

Open
NomzzNJS wants to merge 4 commits into
libp2p:masterfrom
NomzzNJS:Document-prototype-Define-wire-format
Open

docs(gossipsub-v1.4): Add design document for large message propagation#720
NomzzNJS wants to merge 4 commits into
libp2p:masterfrom
NomzzNJS:Document-prototype-Define-wire-format

Conversation

@NomzzNJS
Copy link
Copy Markdown

Adds a comprehensive design document for the Gossipsub v1.4 Large Message
Propagation specification, formalizing the design based on existing nim-libp2p
and py-libp2p prototype implementations.

What's Included

[NEW] pubsub/gossipsub/design-document.md

  • Problem Analysis - Store-and-forward latency math, IDONTWANT timing gap,
    bandwidth amplification quantification
  • Prototype Analysis - Findings from nim-libp2p (Vac/Shadow simulator)
    and py-libp2p implementations
  • Design Decisions - Rationale for all 6 key decisions (unified extension,
    version bump, 64KB fragments, advisory IMRECEIVING, etc.)
  • Protocol Flow Diagrams - Sequence diagrams for v1.4 happy path,
    redundancy suppression, and reassembly state machine
  • Wire Format Design - Protobuf integration tree, field number allocation,
    overhead analysis (<0.1%)
  • Security Analysis - Full threat model with mitigations
  • Performance Expectations - Shadow simulator results (61% bandwidth
    reduction, 35% latency improvement)
  • Implementation Guidance - Recommended order + testing strategy

[MODIFIED] pubsub/gossipsub/README.md

  • Added link to design document under v1.4 specification entry

seetadev and others added 4 commits April 20, 2026 13:05
- Add comprehensive design-document.md covering prototype analysis
  (nim-libp2p, py-libp2p), design rationale, protocol flow diagrams,
  wire format design, security model, and performance expectations
- Link design document from gossipsub README
- Fix author attribution to @NomzzNJS
@Devguru-codes
Copy link
Copy Markdown

I reviewed it out of curiosity. There are so many issues and errors in this. Some of them which i found are -

  1. The DDoS Suicide Vulnerability (Section 4.6 vs. 5.3) - In a gossip protocol, if a node forwards unvalidated data to its peers, a malicious actor can stream infinite garbage through that node. By the time the node retroactively penalizes the attacker, its own outbound bandwidth would already be saturated. Worse, because that node forwarded invalid data, the libp2p peer scoring system (P4 penalty) will cause all of its honest peers to ban it. To make it even worse, the diagram in Section 5.3 completely contradicts this, explicitly stating that forwarding only happens after the COMPLETE and Validate steps.
  2. Math & Naming Contradictions (Section 8.2) - here the pr has messed up their own resource bounding math:-
    for ex - Per-peer reassembly memory - max_pending_fragments × fragmentation_threshold = 16 × 64 KiB = 1 MB. Per-peer with maximum message size (1 MB messages): 16 × 1 MB = 16 MB. If max_pending_fragments is 16, and each fragment is 64 KiB, the max memory is 1 MB. Where does the "16 × 1 MB = 16 MB" come from? here the pr is confusing max_pending_fragments (number of fragments) with max_pending_messages (number of concurrent messages). I think, the implementation details are deeply confused.
  3. Section 6.3 here uses hardcoded assumptions about message ID - here in the pr - it is assumed that message is exactly 32 bytes. But in gossipsub, Message IDs are opaque byte arrays.They are entirely defined by the application layer.

These are what I was able to find and i believe there are more architectural contradictions here. @seetadev, I would like your opinion here. Your input would be helpful. Thank you.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Triage

Development

Successfully merging this pull request may close these issues.

3 participants