Skip to content

waggle: initial version - #732

Open
jxs wants to merge 3 commits into
libp2p:masterfrom
jxs:waggle
Open

waggle: initial version#732
jxs wants to merge 3 commits into
libp2p:masterfrom
jxs:waggle

Conversation

@jxs

@jxs jxs commented Aug 5, 2026

Copy link
Copy Markdown
Member

first draft to start the conversation, info is in the spec.

Comment thread pubsub/waggle.md Outdated

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be "subset of peers subscribed to the piece's topic". I'd also not explicitly require that this subset is random, the application should choose the subset. Of course, the application may choose that subset randomly.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's a great insight, agree and updated, thanks Daniel

Comment thread pubsub/waggle.md Outdated
Comment on lines +62 to +63

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

again, subset of subscribed peers.

Also, I am unsure if this should be codified here. At the very least, there should be a MAY somewhere in here IMO.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updated to remove the random reference. Why MAY? this is part of the dissemination, the protocol should guarantee that applications are able to in the limit flood the network so that a full dissemination is achieved.
If applications set the gossip factor to 0 this step is skipped

Comment thread pubsub/waggle.md
Comment on lines +75 to +77
## 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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There should not be a waggle maintained object cache. Waggle can not by itself utilize such a cache, as all fields are opaque, so the caching should just be responsibility of the application,

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the fields being opaque doesn't mean you can't store them as bytes as we do with partial messages cache, which compares and validate against new received pieces

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

such a general purpose cache might be very inefficient, depending on the object being disseminated. I'd just let the application manage it.

In the end, maybe this boils down to being an API question: Either a highly configurable and modifiable cache that lives in the waggle implementation, or letting this be the responsibility of the application. I lean towards the latter.

Comment thread pubsub/waggle.md Outdated
Comment on lines +96 to +101
message Message {
oneof payload {
TopicSubscription subscription = 1;
ObjectPieces publication = 2;
}
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As TopicSubscription is only sent exactly once, I'd omit this message definition

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks Daniel, meanwhile updated the protobuf schema according to what we spoke

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.

2 participants