From b5ecbea230a775e69dad24867adf3d1c6910bbd8 Mon Sep 17 00:00:00 2001 From: status-im-auto Date: Mon, 4 Dec 2023 17:17:17 +0000 Subject: [PATCH] Update documentation --- spec/12/index.html | 331 +++++++++++++++++++++++++++++---------------- spec/63/index.html | 10 +- 2 files changed, 220 insertions(+), 121 deletions(-) diff --git a/spec/12/index.html b/spec/12/index.html index 6905c25b2..d5786b438 100644 --- a/spec/12/index.html +++ b/spec/12/index.html @@ -5,15 +5,13 @@ - + - + @@ -197,18 +195,9 @@

  • Adversarial Model @@ -281,18 +270,12 @@

    • -

    previous versions: 00

    -
    -

    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.

    +

    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 identifier*: /vac/waku/filter/2.0.0-beta1

    Content filtering is a way to do message-based filtering. Currently the only content filter being applied is on contentTopic. This @@ -341,103 +324,223 @@

    Protobuf #

    -
    syntax = "proto3";
+
    message FilterRequest {
+  bool subscribe = 1;
+  string topic = 2;
+  repeated ContentFilter contentFilters = 3;
 
-// 12/WAKU2-FILTER rfc: https://rfc.vac.dev/spec/12/
-package waku.filter.v2;
-
-// Protocol identifier: /vac/waku/filter-subscribe/2.0.0-beta1
-message FilterSubscribeRequest {
-  enum FilterSubscribeType {
-    SUBSCRIBER_PING = 0;
-    SUBSCRIBE = 1;
-    UNSUBSCRIBE = 2;
-    UNSUBSCRIBE_ALL = 3;
+  message ContentFilter {
+    string contentTopic = 1;
   }
-
-  string request_id = 1;
-  FilterSubscribeType filter_subscribe_type = 2;
-
-  // Filter criteria
-  optional string pubsub_topic = 10;
-  repeated string content_topics = 11;
 }
 
-message FilterSubscribeResponse {
-  string request_id = 1;
-  uint32 status_code = 10;
-  optional string status_desc = 11;
+message MessagePush {
+  repeated WakuMessage messages = 1;
 }
 
-// Protocol identifier: /vac/waku/filter-push/2.0.0-beta1
-message MessagePush {
-  WakuMessage waku_message = 1;
-  optional string pubsub_topic = 2;
+message FilterRPC {
+  string requestId = 1;
+  FilterRequest request = 2;
+  MessagePush push = 3;
 }
-
    
-  Filter-Subscribe
-  #
-
    
-
    A filter service node MUST support the filter-subscribe protocol
-to allow filter clients to subscribe, modify, refresh and unsubscribe a desired set of filter criteria.
-The combination of different filter criteria for a specific filter client node is termed a “subscription”.
-A filter client is interested in receiving messages matching the filter criteria in its registered subscriptions.
    
-
    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.
-An incentive mechanism is currently planned but underspecified.
    
-
    
-  Filter Subscribe Request
-  #
-
    
-
    A client node MUST send all filter requests in a FilterSubscribeRequest message.
-This request MUST contain a request_id.
-The request_id MUST be a uniquely generated string.
-Each request MUST include a filter_subscribe_type, indicating the type of request.
    
-
    
-  Filter Subscribe Response
-  #
+

    + FilterRPC + # +

    +

    A node MUST send all Filter messages (FilterRequest, MessagePush) wrapped inside a +FilterRPC this allows the node handler to determine how to handle a message as the Waku +Filter protocol is not a request response based protocol but instead a push based system.

    +

    The requestId MUST be a uniquely generated string. When a MessagePush is sent +the requestId MUST match the requestId of the subscribing FilterRequest whose filters +matched the message causing it to be pushed.

    +

    + FilterRequest + # +

    +

    A FilterRequest contains an optional topic, zero or more content filters and +a boolean signifying whether to subscribe or unsubscribe to the given filters. +True signifies ‘subscribe’ and false signifies ‘unsubscribe’.

    +

    A node that sends the RPC with a filter request and subscribe set to ’true’ +requests that the filter node SHOULD notify the light requesting node of messages +matching this filter.

    +

    A node that sends the RPC with a filter request and subscribe set to ‘false’ +requests that the filter node SHOULD stop notifying the light requesting node +of messages matching this filter if it is currently doing so.

    +

    The filter matches when content filter and, optionally, a topic is matched. +Content filter is matched when a WakuMessage contentTopic field is the same.

    +

    A filter node SHOULD honor this request, though it MAY choose not to do so. If +it chooses not to do so it MAY tell the light why. The mechanism for doing this +is currently not specified. For notifying the light node a filter node sends a +MessagePush message.

    +

    Since such a filter 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.

    +

    + MessagePush + # +

    +

    A filter node that has received a filter request SHOULD push all messages that +match this filter to a light node. These WakuMessage’s are likely to come from the +relay protocol and be kept at the Node, but there MAY be other sources or +protocols where this comes from. This is up to the consumer of the protocol.

    +

    A filter node MUST NOT send a push message for messages that have not been +requested via a FilterRequest.

    +

    If a specific light node isn’t connected to a filter node for some specific +period of time (e.g. a TTL), then the filter node MAY choose to not push these +messages to the node. This period is up to the consumer of the protocol and node +implementation, though a reasonable default is one minute.

    +
    +

    + Future Work + # +

    + +

    Anonymous filter subscription: This feature guarantees that nodes can anonymously subscribe for a message filter (i.e., without revealing their exact content filter). As such, no adversary in the WakuFilter protocol would be able to link nodes to their subscribed content filers. The current version of the WakuFilter protocol does not provide anonymity as the subscribing node has a direct connection to the full node and explicitly submits its content filter to be notified about the matching messages. However, one can consider preserving anonymity through one of the following ways:

    + +

    + Changelog + # +

    +

    + Next + #

    -

    In return to any FilterSubscribeRequest, -a filter service node SHOULD respond with a FilterSubscribeResponse with a requestId matching that of the request. -This response MUST contain a status_code indicating if the request was successful or not. -Successful status codes are in the 2xx range. -Client nodes SHOULD consider all other status codes as error codes and assume that the requested operation had failed. -In addition, the filter service node MAY choose to provide a more detailed status description in the status_desc field.

    -

    - Filter matching - # + +

    + 2.0.0-beta2 + #

    -

    In the description of each request type below, -the term “filter criteria” refers to the combination of pubsub_topic and a set of content_topics. -The request MAY include filter criteria, conditional to the selected filter_subscribe_type. -If the request contains filter criteria, -it MUST contain a pubsub_topic -and the content_topics set MUST NOT be empty. -A WakuMessage matches filter criteria when its content_topic is in the content_topics set -and it was published on a matching pubsub_topic.

    -

    - Filter Subscribe Types - # +

    Initial draft version. Released 2020-10-28

    + +

    + 2.0.0-beta1 + #

    -

    The following filter subscribe types are defined:

    -

    - SUBSCRIBER_PING - # -

    -

    A filter client that sends a FilterSubscribeRequest with filter_subscribe_type set to SUBSCRIBER_PING -requests that the service node SHOULD indicate if it has any active subscriptions for this client. -The filter client SHOULD exclude any filter criteria from the request. -The filter service node SHOULD respond with a success code if it has any active subscriptions for this client -or an error code if not. -The filter service node SHOULD ignore any filter criteria in the request.

    -

    - SUBSCRIBE - # -

    -

    A filter client that sends a FilterSubscribeRequest with filter_subscribe_type set to SUBSCRIBE -requests that the service node SHOULD push messages matching this filter to the client. -The filter client MUST include the desired filter criteria in the request. -A client MAY use this request type to modify an existing subscription +

    Initial draft version. Released 2020-10-05

    +

    + Copyright + # +

    +

    Copyright and related rights waived via +CC0.

    +

    + References + # +

    +
      +
    1. +

      Message Filtering (Wikipedia)

      +
      2. +
    2. +

      Libp2p PubSub spec - topic validation

      +
      3. +
    + + + + + + + + +
    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + +t MAY use this request type to modify an existing subscription by providing additional filter criteria in a new request. A client MAY use this request type to refresh an existing subscription by providing the same filter criteria in a new request. diff --git a/spec/63/index.html b/spec/63/index.html index 1881aba79..879b6a40e 100644 --- a/spec/63/index.html +++ b/spec/63/index.html @@ -5,13 +5,9 @@ - + - + @@ -258,7 +254,7 @@

  • Contributors: - ? + Jimmy Debe jimmy@status.im