fa035fa86b
* Waku v2: Add content filter for waku topics This addresses https://github.com/vacp2p/specs/issues/156 and https://github.com/vacp2p/specs/issues/160 * Fix spellcheck and indent * More protobuf fmt * spellcheck * Update specs/waku/waku-v2.md Co-authored-by: Dean Eigenmann <7621705+decanus@users.noreply.github.com> Co-authored-by: Dean Eigenmann <7621705+decanus@users.noreply.github.com>
7.7 KiB
| title | version | status | authors |
|---|---|---|---|
| Waku | 2.0.0-alpha1 | Raw | Oskar Thorén <oskar@status.im> |
Table of Contents
- Abstract
- Motivation and goals
- Definitions
- Underlying Transports and Prerequisites
- Wire Specification
- Changelog
- Copyright
- References
Abstract
Waku is a privacy-preserving peer-to-peer messaging protocol for resource restricted devices. It implements PubSub over libp2p and adds capabilities on top of it. These capabilities are: (i) retrieving historical messages for mostly-offline devices (ii) adaptive nodes, allowing for heterogeneous nodes to contribute, and (iii) bandwidth preservation for light nodes. This makes it ideal for running a p2p protocol on mobile.
Historically, it has its roots in Waku v1, which stems from Whisper, originally part of the Ethereum stack. However, Waku v2 acts more as a thin wrapper for PubSub and has a different API. It is implemented in an iterative manner where initial focus is on porting essential functionality to libp2p. See rough road map.
Motivation and goals
-
Generalized messaging. Many applications requires some form of messaging protocol to communicate between different subsystems or different nodes. This messaging can be human-to-human or machine-to-machine or a mix.
-
Peer-to-peer. These applications sometimes have requirements that make them suitable for peer-to-peer solutions.
-
Resource restricted.These applications often run in constrained environments, where resources or the environment is restricted in some fashion. E.g.:
- limited bandwidth, CPU, memory, disk, battery, etc
- not being publicly connectable
- only being intermittently connected; mostly-offline
- Privacy. These applications have a desire for some privacy guarantees, such as pseudonymity, metadata protection in transit, etc.
Waku provides a solution that satisfies these goals in a reasonable matter.
Definitions
TODO
Underlying Transports and Prerequisites
TODO Right now this is more like a set of components
Peer Discovery
WakuSub and PubSub don't provide an peer discovery mechanism. This has to be provided for by the environment.
PubSub interface
Waku v2 is implementing the PubSub interface in Libp2p. See PubSub interface for libp2p (r2, 2019-02-01) for more details.
Protocol Identifier
The current protocol identifier
is: /wakusub/2.0.0-alpha1.
FloodSub
WakuSub is currently a subprotocol of FloodSub. Future versions of WakuSub will support GossipSub v1.0 and GossipSub 1.1.
Bridge mode
To maintain compatibility with Waku v1, a bridge mode can be achieved. See separate spec.
TODO Detail this in a separate spec
Wire Specification
We are using protobuf RPC messages between peers. Here's what the protobuf messages looks like, as defined in the PubSub interface. Please see PubSub interface spec for more details.
In this section we specify two things:
- How WakuSub is using these messages.
- Additional message types.
Protobuf
message RPC {
repeated SubOpts subscriptions = 1;
repeated Message publish = 2;
repeated ContentFilter contentFilter = 3;
message SubOpts {
optional bool subscribe = 1;
optional string topicid = 2;
}
message ContentFilter {
optional string contentTopic = 1;
}
}
message Message {
optional string from = 1;
optional bytes data = 2;
optional bytes seqno = 3;
repeated string topicIDs = 4;
optional bytes signature = 5;
optional bytes key = 6;
optional string contentTopic = 7;
}
WakuSub does not currently use the ControlMessage defined in GossipSub.
However, later versions will add likely add this capability.
TopicDescriptor as defined in the PubSub interface spec is not currently used.
RPC
These are messages sent to directly connected peers. They SHOULD NOT be gossiped. See section below on how the fields work.
Message
The from field MAY indicate which peer is publishing the message.
The data field SHOULD be filled out with whatever payload is being sent. Encryption of this field is done at a separate layer.
The seqno field MAY be used to provide a linearly increasing number. See PubSub spec for more details.
The topicIDs field MUST contain the topics that a message is being published on.
The signature field MAY contain the signature of the message, thus providing authentication of the message. See PubSub spec for more details.
The key field MAY be present and relates to signing. See PubSub spec for more details.
TODO: Don't quite understand this scenario, to clarify. Wouldn't it always be in from?
The key field contains the signing key when it cannot be inlined in the source peer ID. When present, it must match the peer ID.
SubOpts
To do topic subscription management, we MAY send updates to our peers. If we do so, then:
The subscribe field MUST contain a boolean, where 1 means subscribe and 0 means unsubscribe to a topic.
The topicid field MUST contain the topic.
NOTE: This doesn't appear to be documented in PubSub spec, upstream?
ContentFilter
Content filter is a way to do message-based
filtering.
Currently the only content filter being applied is on contentTopic. This
corresponds to topics in Waku v1.
A node that only sets this field but doesn't subscribe to any topic SHOULD only
get notified when the content subtopic matches. A content subtopic matches when
a message contentTopic is the same. This means such a node acts as a light node.
A node that receives this RPC SHOULD apply this content filter before relaying. Since such a node is doing extra work for a light node, it MAY also account for usage and be selective in how much service it provides. This mechanism is currently planned but underspecified.
Historical message support
TODO(Dean): Fill out this section with historical message API.
- Add issue for this in specs repository
Changelog
TODO(Oskar): Update changelog once we are in draft, which is when implementation matches spec
Copyright
Copyright and related rights waived via CC0.