AtHeartEngineer/rfc-index
1
0
Fork 0
mirror of https://github.com/vacp2p/rfc-index.git synced 2026-01-09 23:58:02 -05:00
Code Issues Packages Projects Releases Wiki Activity

12/WAKU2-FILTER: Update (#119)

Browse Source 
An update of the 12/WAKU2-FILTER RFC. Some rearrange some sections,
updated links and terms.

---------

Co-authored-by: Hanno Cornelius <68783915+jm-clius@users.noreply.github.com>
This commit is contained in:
Jimmy Debe
2025-03-25 11:48:27 -04:00
committed by GitHub
parent 8ee2a6d6b2
commit e8a3f8a77d
2 changed files with 94 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
waku/standards/core/12/filter.md
View File

@@ -13,61 +13,54 @@ contributors:
- Ebube Ud <ebube@status.im> - Ebube Ud <ebube@status.im>
--- ---
previous versions: [00](./previous-versions00) previous versions: [00](/waku/standards/core/12/previous-versions/00/filter.md)
---
`WakuFilter` is a protocol that enables subscribing to messages that a peer receives.
This is a more lightweight version of `WakuRelay`
specifically designed for bandwidth restricted devices.
This is due to the fact that light nodes subscribe to full-nodes and
only receive the messages they desire.
## Content filtering
**Protocol identifiers**: **Protocol identifiers**:
- _filter-subscribe_: `/vac/waku/filter-subscribe/2.0.0-beta1` - _filter-subscribe_: `/vac/waku/filter-subscribe/2.0.0-beta1`
- _filter-push_: `/vac/waku/filter-push/2.0.0-beta1` - _filter-push_: `/vac/waku/filter-push/2.0.0-beta1`
Content filtering is a way to do [message-based ---
filtering](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering).
Currently the only content filter being applied is on `contentTopic`. This
corresponds to topics in Waku v1.
## Rationale ## Abstract
Unlike the `store` protocol for historical messages, this protocol allows for This specification describes the `12/WAKU2-FILTER` protocol,
native lower latency scenarios such as instant messaging. It is thus which enables a client to subscribe to a subset of real-time messages from a Waku peer.
complementary to it. This is a more lightweight version of [11/WAKU2-RELAY](/waku/standards/core/11/relay.md),
useful for bandwidth restricted devices.
This is often used by nodes with lower resource limits to subscribe to full Relay nodes and
only receive the subset of messages they desire,
based on content topic interest.
Strictly speaking, it is not just doing basic request response, but performs ## Motivation
sender push based on receiver intent. While this can be seen as a form of light
pub/sub, it is only used between two nodes in a direct fashion. Unlike the Unlike the [13/WAKU2-STORE](/waku/standards/core/13/store.md) protocol
Gossip domain, this is meant for light nodes which put a premium on bandwidth. for historical messages, this protocol allows for native lower latency scenarios,
such as instant messaging.
It is thus complementary to it.
Strictly speaking, it is not just doing basic request-response, but
performs sender push based on receiver intent.
While this can be seen as a form of light publish/subscribe,
it is only used between two nodes in a direct fashion. Unlike the
Gossip domain, this is suitable for light nodes which put a premium on bandwidth.
No gossiping takes place. No gossiping takes place.
It is worth noting that a light node could get by with only using the `store` It is worth noting that a light node could get by with only using the
protocol to query for a recent time window, provided it is acceptable to do [13/WAKU2-STORE](/waku/standards/core/13/store.md) protocol to
frequent polling. query for a recent time window, provided it is acceptable to do frequent polling.
## Design Requirements ## Semantics
The effectiveness and reliability of the content filtering service enabled by The key words “MUST”, “MUST NOT”, “REQUIRED”,
`WakuFilter` protocol rely on the _high availability_ of the full nodes “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and
as the service providers. “OPTIONAL” in this document are to be interpreted as described in [2119](https://www.ietf.org/rfc/rfc2119.txt).
To this end, full nodes must feature _high uptime_
(to persistently listen and capture the network messages)
as well as _high Bandwidth_ (to provide timely message delivery to the light nodes).
## Security Consideration ### Content filtering
Note that while using `WakuFilter` allows light nodes to save bandwidth, Content filtering is a way to do
it comes with a privacy cost in the sense that they need to [message-based filtering](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering).
disclose their liking topics to the full nodes to retrieve the relevant messages. Currently the only content filter being applied is on `contentTopic`.
Currently, anonymous subscription is not supported by the `WakuFilter`, however,
potential solutions in this regard are sketched
below in [Future Work](#future-work) section.
### Terminology ### Terminology
@@ -76,33 +69,11 @@ refers to any piece of data that can be used to uniquely identify a user.
For example, the signature verification key, and For example, the signature verification key, and
the hash of one's static IP address are unique for each user and hence count as PII. the hash of one's static IP address are unique for each user and hence count as PII.
## Adversarial Model
Any node running the `WakuFilter` protocol
i.e., both the subscriber node and the queried node are considered as an adversary.
Furthermore, we consider the adversary as a passive entity
that attempts to collect information from other nodes to conduct an attack but
it does so without violating protocol definitions and instructions.
For example, under the passive adversarial model,
no malicious node intentionally hides the messages
matching to one's subscribed content filter
as it is against the description of the `WakuFilter` protocol.
The following are not considered as part of the adversarial model:
- An adversary with a global view of all the nodes and their connections.
- An adversary that can eavesdrop on communication links
between arbitrary pairs of nodes (unless the adversary is one end of the communication).
In specific, the communication channels are assumed to be secure.
### Protobuf ### Protobuf
```protobuf ```protobuf
syntax = "proto3"; syntax = "proto3";
// 12/WAKU2-FILTER rfc: https://rfc.vac.dev/spec/12/
package waku.filter.v2;
// Protocol identifier: /vac/waku/filter-subscribe/2.0.0-beta1 // Protocol identifier: /vac/waku/filter-subscribe/2.0.0-beta1
message FilterSubscribeRequest { message FilterSubscribeRequest {
enum FilterSubscribeType { enum FilterSubscribeType {
@@ -145,7 +116,6 @@ in its registered subscriptions.
Since a filter service node is consuming resources to provide this service, Since a filter service node is consuming resources to provide this service,
it MAY account for usage and adapt its service provision to certain clients. it MAY account for usage and adapt its service provision to certain clients.
An incentive mechanism is currently planned but underspecified.
#### Filter Subscribe Request #### Filter Subscribe Request
@@ -156,8 +126,8 @@ Each request MUST include a `filter_subscribe_type`, indicating the type of requ
#### Filter Subscribe Response #### Filter Subscribe Response
In return to any `FilterSubscribeRequest`, When responding to a `FilterSubscribeRequest`,
a filter service node SHOULD respond with a `FilterSubscribeResponse` a filter service node SHOULD send a `FilterSubscribeResponse`
with a `requestId` matching that of the request. with a `requestId` matching that of the request.
This response MUST contain a `status_code` indicating if the request was successful This response MUST contain a `status_code` indicating if the request was successful
or not. or not.
@@ -178,41 +148,43 @@ conditional to the selected `filter_subscribe_type`.
If the request contains filter criteria, If the request contains filter criteria,
it MUST contain a `pubsub_topic` it MUST contain a `pubsub_topic`
and the `content_topics` set MUST NOT be empty. and the `content_topics` set MUST NOT be empty.
A `WakuMessage` matches filter criteria A [14/WAKU2-MESSAGE](/waku/standards/core/14/message.md) matches filter criteria
when its `content_topic` is in the `content_topics` set when its `content_topic` is in the `content_topics` set
and it was published on a matching `pubsub_topic`. and it was published on a matching `pubsub_topic`.
#### Filter Subscribe Types #### Filter Subscribe Types
The following filter subscribe types are defined: The filter-subscribe types are defined as follows:
##### SUBSCRIBER_PING ##### SUBSCRIBER_PING
A filter client that sends a `FilterSubscribeRequest` with A filter client that sends a `FilterSubscribeRequest` with
`filter_subscribe_type` set to `SUBSCRIBER_PING` `filter_subscribe_type` set to `SUBSCRIBER_PING`,
requests that the service node SHOULD indicate if it has any active subscriptions requests that the filter service node SHOULD indicate if it has any active subscriptions
for this client. for this client.
The filter client SHOULD exclude any filter criteria from the request. The filter client SHOULD exclude any filter criteria from the request.
The filter service node SHOULD respond with a success code The filter service node SHOULD respond with a success `status_code`
if it has any active subscriptions for this client if it has any active subscriptions for this client
or an error code if not. or an error `status_code` if not.
The filter service node SHOULD ignore any filter criteria in the request. The filter service node SHOULD ignore any filter criteria in the request.
##### SUBSCRIBE ##### SUBSCRIBE
A filter client that sends a `FilterSubscribeRequest` with A filter client that sends a `FilterSubscribeRequest` with
`filter_subscribe_type` set to `SUBSCRIBE` `filter_subscribe_type` set to `SUBSCRIBE`
requests that the service node SHOULD push messages matching this filter to the client. requests that the filter service node SHOULD push messages
matching this filter to the client.
The filter client MUST include the desired filter criteria in the request. The filter client MUST include the desired filter criteria in the request.
A client MAY use this request type to _modify_ an existing subscription A client MAY use this request type to _modify_ an existing subscription
by providing _additional_ filter criteria in a new request. by providing _additional_ filter criteria in a new request.
A client MAY use this request type to _refresh_ an existing subscription A client MAY use this request type to _refresh_ an existing subscription
by providing _the same_ filter criteria in a new request. by providing _the same_ filter criteria in a new request.
The filter service node SHOULD respond with a success code The filter service node SHOULD respond with a success `status_code`
if it successfully honored this request if it successfully honored this request
or an error code if not. or an error `status_code` if not.
The filter service node SHOULD respond with an error code and discard the request The filter service node SHOULD respond with an error `status_code` and
if the subscribe request does not contain valid filter criteria, discard the request if the `FilterSubscribeRequest`
does not contain valid filter criteria,
i.e. both a `pubsub_topic` _and_ a non-empty `content_topics` set. i.e. both a `pubsub_topic` _and_ a non-empty `content_topics` set.
##### UNSUBSCRIBE ##### UNSUBSCRIBE
@@ -226,11 +198,11 @@ it desires to unsubscribe from in the request.
A client MAY use this request type to _modify_ an existing subscription A client MAY use this request type to _modify_ an existing subscription
by providing _a subset of_ the original filter criteria by providing _a subset of_ the original filter criteria
to unsubscribe from in a new request. to unsubscribe from in a new request.
The filter service node SHOULD respond with a success code The filter service node SHOULD respond with a success `status_code`
if it successfully honored this request if it successfully honored this request
or an error code if not. or an error `status_code` if not.
The filter service node SHOULD respond with an error code and discard the request The filter service node SHOULD respond with an error `status_code` and
if the unsubscribe request does not contain valid filter criteria, discard the request if the unsubscribe request does not contain valid filter criteria,
i.e. both a `pubsub_topic` _and_ a non-empty `content_topics` set. i.e. both a `pubsub_topic` _and_ a non-empty `content_topics` set.
##### UNSUBSCRIBE_ALL ##### UNSUBSCRIBE_ALL
@@ -241,8 +213,8 @@ requests that the service node SHOULD _stop_ pushing messages
matching _any_ filter to the client. matching _any_ filter to the client.
The filter client SHOULD exclude any filter criteria from the request. The filter client SHOULD exclude any filter criteria from the request.
The filter service node SHOULD remove any existing subscriptions for this client. The filter service node SHOULD remove any existing subscriptions for this client.
It SHOULD respond with a success code if it successfully honored this request It SHOULD respond with a success `status_code` if it successfully honored this request
or an error code if not. or an error `status_code` if not.
### Filter-Push ### Filter-Push
@@ -253,7 +225,8 @@ matching registered subscriptions to this client.
A filter service node SHOULD push all messages A filter service node SHOULD push all messages
matching the filter criteria in a registered subscription matching the filter criteria in a registered subscription
to the subscribed filter client. to the subscribed filter client.
These [`WakuMessage`s](../14/message.md) are likely to come from [`11/WAKU2-RELAY`](../11/relay.md), These [`WakuMessage`s](/waku/standards/core/14/message.md)
are likely to come from [`11/WAKU2-RELAY`](/waku/standards/core/11/relay.md),
but there MAY be other sources or protocols where this comes from. but there MAY be other sources or protocols where this comes from.
This is up to the consumer of the protocol. This is up to the consumer of the protocol.
@@ -264,7 +237,7 @@ for a period of time,
the filter service node MAY choose to stop pushing messages to the client and the filter service node MAY choose to stop pushing messages to the client and
remove its subscription. remove its subscription.
This period is up to the service node implementation. This period is up to the service node implementation.
We consider `1 minute` to be a reasonable default. It is RECOMMENDED to set `1 minute` as a reasonable default.
#### Message Push #### Message Push
@@ -280,9 +253,35 @@ A filter client SHOULD verify that each `MessagePush` it receives
originated from a service node where the client has an active subscription originated from a service node where the client has an active subscription
and that it matches filter criteria belonging to that subscription. and that it matches filter criteria belonging to that subscription.
--- ### Adversarial Model
## Future Work Any node running the `WakuFilter` protocol
i.e., both the subscriber node and
the queried node are considered as an adversary.
Furthermore, we consider the adversary as a passive entity
that attempts to collect information from other nodes to conduct an attack but
it does so without violating protocol definitions and instructions.
For example, under the passive adversarial model,
no malicious node intentionally hides the messages
matching to one's subscribed content filter
as it is against the description of the `WakuFilter` protocol.
The following are not considered as part of the adversarial model:
- An adversary with a global view of all the nodes and their connections.
- An adversary that can eavesdrop on communication links
between arbitrary pairs of nodes (unless the adversary is one end of the communication).
In specific, the communication channels are assumed to be secure.
### Security Considerations
Note that while using `WakuFilter` allows light nodes to save bandwidth,
it comes with a privacy cost in the sense that they need to
disclose their liking topics to the full nodes to retrieve the relevant messages.
Currently, anonymous subscription is not supported by the `WakuFilter`, however,
potential solutions in this regard are discussed below.
#### Future Work
<!-- Alternative title: Filter-subscriber unlinkability --> <!-- Alternative title: Filter-subscriber unlinkability -->
**Anonymous filter subscription**: **Anonymous filter subscription**:
This feature guarantees that nodes can anonymously subscribe for a message filter This feature guarantees that nodes can anonymously subscribe for a message filter
@@ -318,25 +317,6 @@ Examples of such 2PC protocols are
[Oblivious Transfers](https://link.springer.com/referenceworkentry/10.1007%2F978-1-4419-5906-5_9#:~:text=Oblivious%20transfer%20(OT)%20is%20a,information%20the%20receiver%20actually%20obtains.) [Oblivious Transfers](https://link.springer.com/referenceworkentry/10.1007%2F978-1-4419-5906-5_9#:~:text=Oblivious%20transfer%20(OT)%20is%20a,information%20the%20receiver%20actually%20obtains.)
and one-way Private Set Intersections (PSI). and one-way Private Set Intersections (PSI).
## Changelog
### Next
- Added initial threat model and security analysis.
### 2.0.0-beta2
Initial draft version. Released [2020-10-28](https://github.com/vacp2p/specs/commit/5ceeb88cee7b918bb58f38e7c4de5d581ff31e68)
- Fix: Ensure contentFilter is a repeated field, on implementation
- Change: Add ability to unsubscribe from filters.
Make `subscribe` an explicit boolean indication.
Edit protobuf field order to be consistent with libp2p.
### 2.0.0-beta1
Initial draft version. Released [2020-10-05](https://github.com/vacp2p/specs/commit/31857c7434fa17efc00e3cd648d90448797d107b)
## Copyright ## Copyright
Copyright and related rights waived via Copyright and related rights waived via
@@ -344,13 +324,14 @@ Copyright and related rights waived via
## References ## References
- [message-based - [11/WAKU2-RELAY](/waku/standards/core/11/relay.md)
filtering](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering) - [message-based filtering](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering)
- [`WakuMessage`s](../14/message.md) - [13/WAKU2-STORE](/waku/standards/core/13/store.md)
- [`11/WAKU2-RELAY`](../11/relay.md) - [14/WAKU2-MESSAGE](/waku/standards/core/14/message.md)
- [Oblivious Transfers](https://link.springer.com/referenceworkentry/10.1007%2F978-1-4419-5906-5_9#:~:text=Oblivious%20transfer%20(OT)%20is%20a,information%20the%20receiver%20actually%20obtains) - [Oblivious Transfers](https://link.springer.com/referenceworkentry/10.1007%2F978-1-4419-5906-5_9#:~:text=Oblivious%20transfer%20(OT)%20is%20a,information%20the%20receiver%20actually%20obtains)
- previous versions: [00](./previous-versions00) - 12/WAKU2-FILTER previous version: [00](waku/standards/core/12/previous-versions/00/filter.md)
### Informative
1. [Message Filtering (Wikipedia)](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering) 1. [Message Filtering (Wikipedia)](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering)
2. [Libp2p PubSub spec - topic validation](https://github.com/libp2p/specs/tree/master/pubsub#topic-validation) 2. [Libp2p PubSub spec - topic validation](https://github.com/libp2p/specs/tree/master/pubsub#topic-validation)

4
waku/standards/core/12/previous-versions00/filter.md → waku/standards/core/12/previous-versions/00/filter.md
View File

@@ -4,6 +4,7 @@ title: 12/WAKU2-FILTER
name: Waku v2 Filter name: Waku v2 Filter
status: draft status: draft
tags: waku-core tags: waku-core
version: v00
editor: Hanno Cornelius <hanno@status.im> editor: Hanno Cornelius <hanno@status.im>
contributors: contributors:
- Dean Eigenmann <dean@status.im> - Dean Eigenmann <dean@status.im>
@@ -11,9 +12,8 @@ contributors:
- Sanaz Taheri <sanaz@status.im> - Sanaz Taheri <sanaz@status.im>
- Ebube Ud <ebube@status.im> - Ebube Ud <ebube@status.im>
--- ---
version: 00
---
`WakuFilter` is a protocol that enables subscribing to messages that a peer receives. `WakuFilter` is a protocol that enables subscribing to messages that a peer receives.
This is a more lightweight version of `WakuRelay` This is a more lightweight version of `WakuRelay`
specifically designed for bandwidth restricted devices. specifically designed for bandwidth restricted devices.