From f2cb3d20b701e12779daded1456a77c2d8d1f651 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Oliveira?= Date: Wed, 5 Aug 2026 10:15:21 +0100 Subject: [PATCH 1/3] waggle: initial version --- pubsub/waggle.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 pubsub/waggle.md diff --git a/pubsub/waggle.md b/pubsub/waggle.md new file mode 100644 index 000000000..38f5bd709 --- /dev/null +++ b/pubsub/waggle.md @@ -0,0 +1,116 @@ +# Waggle: Next-generation pubsub protocol for libp2p +| Lifecycle Stage | Maturity | Status | Latest Revision | +|---|---|---|---| +| 1A | Working Draft | Active | r1, YYYY-MM-DD | + +Authors: [@dknopik](@dknopik), [@jxs](@jxs), [@sukunrt](@sukunrt), + +Interest Group: [...] + +See the [lifecycle document][lifecycle-spec] for context about maturity level and spec status. + +[lifecycle-spec]: https://github.com/libp2p/specs/blob/master/00-framework-01-spec-lifecycle.md + +## Overview +This work presents a publish-subscribe protocol for the dissemination of incrementally reconstructed objects, incorporating lessons learned from years of Gossipsub development. +Nodes advertise support for the protocol using `/waggle/1.0` as the protocol string. + +**Contents** + +- [Overview](#overview) +- [Motivations and Prior Work](#motivations-and-prior-work) +- [Topic Membership](#topic-membership) +- [Publishing and Dissemination](#publishing-and-dissemination) +- [Object Cache](#object-cache) +- [Peer Discovery](#peer-discovery) +- [Peer Scoring and Abuse Mitigation](#peer-scoring-and-abuse-mitigation) +- [Opaque Protocol Fields](#opaque-protocol-fields) +- [Wire Format](#wire-format) + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", +and "OPTIONAL" in this document are to be interpreted as described in +[RFC 2119](https://tools.ietf.org/html/rfc2119) and +[RFC 8174](https://tools.ietf.org/html/rfc8174). + +## Motivations and Prior Work + +The libp2p pubsub protocols have been evolving to meet the demands of their users. However, an increasingly common pattern across many applications remains poorly supported: the dissemination of incrementally reconstructed objects. Whether a large payload is deliberately split into smaller pieces for transmission or different nodes initially possess different pieces of the same application-defined object, each node begins with only partial information, and the goal is for all nodes to exchange pieces until they converge on the complete content. + +Previous work on partial messages attempted to retrofit chunking onto Gossipsub through its extension system. However, integrating chunk dissemination with Gossipsub's mesh dynamics, including IHAVE/IWANT exchanges, heartbeat-driven maintenance, and message validation, proved increasingly complex. These mechanisms were designed around complete-message propagation, making incremental reconstruction a poor match for Gossipsub's underlying abstractions and requiring protocol logic to work against the architecture. + +This complexity is compounded by years of accumulated legacy. Extensions must coexist with features that are either application-specific or of limited practical use, while core mechanisms such as scoring tightly couple application-level trust decisions with the network layer. More recent efforts to address limitations, such as head-of-line blocking through topic streams, further increase the amount of protocol machinery that new extensions must accommodate. + +Rather than continuing to layer functionality onto a protocol whose abstractions are fundamentally message-centric, we argue that a broad class of dissemination problems is better served by a model that treats partial views as first-class objects. Instead of assuming that peers exchange complete messages, this model views communication as the progressive exchange of constituent pieces that allow nodes to converge on an application-defined object. These pieces need not correspond to literal fragments of the original object; they may represent independently transferable information that contributes to reconstruction. In file distribution, these pieces may be chunks of the original file or erasure-coded shards generated to improve dissemination efficiency; in attestation propagation, they are validator attestations that collectively form the attestation set for a slot. By treating partial views as first-class objects, routing, scheduling, validation, and flow control can operate directly on incremental reconstruction and exchange of metadata, instead of emulating it through complete-message semantics. This approach is necessarily incompatible with Gossipsub's message-centric model, but supports a broader class of peer-to-peer dissemination problems. +Peer scoring is an application-defined concern. The broadcast protocol should surface relevant information to the application and let it decide how to score and penalize peers, rather than baking scoring semantics into the network layer. +There is limited utility in maintaining a stable mesh through GRAFT and PRUNE messages. Publishing to a random subset of connected peers potentially selected using latency or other application-defined criteria provides the same robustness and coverage with significantly reduced implementation complexity. + +## Topic Membership + +Topics define independent dissemination scopes within the network. To subscribe to a topic, a peer opens a new dedicated outbound stream with its connected peers and MUST include the topic it wishes to participate in. Each topic is carried on its own dedicated stream. A peer subscribing to multiple topics opens a separate stream for each topic. +Peers maintain the subscription state of their connected peers. Once subscribed, the peer becomes eligible to participate in the dissemination of objects associated with that topic. +To unsubscribe from a topic, a peer closes the corresponding stream, indicating that it no longer wishes to participate in dissemination for that topic. Upon closure, connected peers update their subscription state by removing the association between that peer and the topic. +The protocol does not prescribe how topics are created, named, or authorized. Topic management and access control are application-defined. + +## Publishing and dissemination + + Objects are disseminated through incremental publication of their constituent pieces. A publisher may divide an object into multiple pieces and publish those pieces independently, including through repeated publication attempts. Pieces do not need to originate from a single publisher; any peer possessing a piece may participate in its propagation. Each published piece belongs to a topic and MUST be disseminated through the corresponding topic stream. + +To publish a piece, a node selects a random subset of its connected peers and transmits it to them. Upon receiving a previously unknown piece, a peer updates its local object view and begins propagating the piece through its own connected peers. + +The receiving peer uses the metadata it maintains about remote peers to identify peers that are known to be missing the received piece. The peer then transmits the piece to those peers, allowing dissemination to leverage existing knowledge of incomplete views. In addition, the peer advertises its updated metadata to peers that maintain a view of its state, allowing them to track the newly available piece. + +To discover additional dissemination opportunities, a peer also selects a random subset of connected peers for which it has no current metadata view and advertises its current object metadata to them. These exchanges allow peers to progressively discover missing pieces and establish additional synchronization relationships throughout the network. + +The number of peers selected for initial publication, piece forwarding, and metadata dissemination SHOULD be configurable by implementations and tuned according to application and deployment requirements, with consideration for dissemination amplification needs, bandwidth constraints, and network overhead. + +## Opaque Protocol Fields + +Topic identifiers, object identifiers, and piece metadata are opaque protocol fields whose semantics are defined by applications. The protocol does not prescribe how these fields are generated, assigned, encoded, or interpreted. + +Applications SHOULD use stable identifiers that allow peers to consistently refer to the same topic or object across independent connections and dissemination attempts. Applications MAY use content-derived identifiers, such as cryptographic hashes, when content addressing is appropriate. + +Applications are responsible for defining the representation and interpretation of piece metadata, including how pieces are tracked and how objects are reconstructed. + +## Object Cache + +The lifetime of cached object and piece state SHOULD be configurable by implementations and tunable by applications according to their resource constraints and dissemination requirements. + +## Peer discovery + +Peer discovery is outside the scope of this protocol. The protocol assumes that peers have an existing set of connected peers with which they can exchange subscriptions, metadata, and object pieces. +Applications and deployments SHOULD use dedicated peer discovery mechanisms, such as Distributed Hash Tables (DHTs) or other discovery protocols, to identify and establish connections with peers. + +## Peer scoring and abuse mitigation + +This protocol does not define a peer scoring system or prescribe how peers should be ranked, trusted, or penalized. Peer reputation, trust models, and application-specific scoring policies are considered application-layer concerns. +Implementations SHOULD expose dissemination-related events and peer behavior information to applications, allowing them to implement their own scoring mechanisms. Such information MAY include successful piece exchanges, failed requests, invalid pieces, protocol violations, subscription behavior, and resource consumption. +Applications MAY use this information to determine whether a peer should continue participating in dissemination, be deprioritized, or be disconnected. The protocol does not mandate how application-level decisions affect peer interactions. +At the protocol layer, implementations SHOULD provide basic protections against resource exhaustion and malformed behavior. These protections MAY include limiting concurrent streams, bounding metadata size, rate limiting requests and advertisements, validating piece identifiers and object metadata, and preventing peers from causing unbounded memory or bandwidth consumption. + +## Wire Format + +The protocol uses Protocol Buffers (protobuf) as its wire format. Messages are encoded using the following schema: + +```protobuf +message Message { + oneof payload { + TopicSubscription subscription = 1; + ObjectPieces publication = 2; + } +} + +message TopicSubscription { + required bytes topicID = 1; +} + +message ObjectPieces { + required bytes objectID = 2; + + // Encoded representation of the pieces the peer has and the pieces it needs. + optional bytes piecesMetadata = 3; + + // The raw bytes of one or more pieces of the object being published. + optional bytes pieces = 4; +} +``` From 18c94230a64590048ccb4e95ca95a973dbdbffb0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Oliveira?= Date: Thu, 6 Aug 2026 22:53:17 +0100 Subject: [PATCH 2/3] update protobuf --- pubsub/waggle.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/pubsub/waggle.md b/pubsub/waggle.md index 38f5bd709..f57c05cab 100644 --- a/pubsub/waggle.md +++ b/pubsub/waggle.md @@ -93,24 +93,13 @@ At the protocol layer, implementations SHOULD provide basic protections against The protocol uses Protocol Buffers (protobuf) as its wire format. Messages are encoded using the following schema: ```protobuf -message Message { - oneof payload { - TopicSubscription subscription = 1; - ObjectPieces publication = 2; - } -} - message TopicSubscription { required bytes topicID = 1; } message ObjectPieces { required bytes objectID = 2; - - // Encoded representation of the pieces the peer has and the pieces it needs. optional bytes piecesMetadata = 3; - - // The raw bytes of one or more pieces of the object being published. optional bytes pieces = 4; } ``` From 9328b68f8375c54dbe197e1814014a9c916ca5a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Oliveira?= Date: Thu, 6 Aug 2026 23:05:35 +0100 Subject: [PATCH 3/3] address Daniel's review --- pubsub/waggle.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pubsub/waggle.md b/pubsub/waggle.md index f57c05cab..817f9073c 100644 --- a/pubsub/waggle.md +++ b/pubsub/waggle.md @@ -43,7 +43,7 @@ This complexity is compounded by years of accumulated legacy. Extensions must co Rather than continuing to layer functionality onto a protocol whose abstractions are fundamentally message-centric, we argue that a broad class of dissemination problems is better served by a model that treats partial views as first-class objects. Instead of assuming that peers exchange complete messages, this model views communication as the progressive exchange of constituent pieces that allow nodes to converge on an application-defined object. These pieces need not correspond to literal fragments of the original object; they may represent independently transferable information that contributes to reconstruction. In file distribution, these pieces may be chunks of the original file or erasure-coded shards generated to improve dissemination efficiency; in attestation propagation, they are validator attestations that collectively form the attestation set for a slot. By treating partial views as first-class objects, routing, scheduling, validation, and flow control can operate directly on incremental reconstruction and exchange of metadata, instead of emulating it through complete-message semantics. This approach is necessarily incompatible with Gossipsub's message-centric model, but supports a broader class of peer-to-peer dissemination problems. Peer scoring is an application-defined concern. The broadcast protocol should surface relevant information to the application and let it decide how to score and penalize peers, rather than baking scoring semantics into the network layer. -There is limited utility in maintaining a stable mesh through GRAFT and PRUNE messages. Publishing to a random subset of connected peers potentially selected using latency or other application-defined criteria provides the same robustness and coverage with significantly reduced implementation complexity. +There is limited utility in maintaining a stable mesh through GRAFT and PRUNE messages. Publishing to a subset of connected peers potentially selected using latency or other application-defined criteria provides the same robustness and coverage with significantly reduced implementation complexity. ## Topic Membership @@ -56,11 +56,11 @@ The protocol does not prescribe how topics are created, named, or authorized. To Objects are disseminated through incremental publication of their constituent pieces. A publisher may divide an object into multiple pieces and publish those pieces independently, including through repeated publication attempts. Pieces do not need to originate from a single publisher; any peer possessing a piece may participate in its propagation. Each published piece belongs to a topic and MUST be disseminated through the corresponding topic stream. -To publish a piece, a node selects a random subset of its connected peers and transmits it to them. Upon receiving a previously unknown piece, a peer updates its local object view and begins propagating the piece through its own connected peers. +To publish a piece, a node selects a subset of its connected peers and transmits it to them. Upon receiving a previously unknown piece, a peer updates its local object view and begins propagating the piece through its own connected peers. The receiving peer uses the metadata it maintains about remote peers to identify peers that are known to be missing the received piece. The peer then transmits the piece to those peers, allowing dissemination to leverage existing knowledge of incomplete views. In addition, the peer advertises its updated metadata to peers that maintain a view of its state, allowing them to track the newly available piece. -To discover additional dissemination opportunities, a peer also selects a random subset of connected peers for which it has no current metadata view and advertises its current object metadata to them. These exchanges allow peers to progressively discover missing pieces and establish additional synchronization relationships throughout the network. +To discover additional dissemination opportunities, a peer also selects a subset of connected peers for which it has no current metadata view and advertises its current object metadata to them. These exchanges allow peers to progressively discover missing pieces and establish additional synchronization relationships throughout the network. The number of peers selected for initial publication, piece forwarding, and metadata dissemination SHOULD be configurable by implementations and tuned according to application and deployment requirements, with consideration for dissemination amplification needs, bandwidth constraints, and network overhead.