From fa035fa86b04540d3b91d4eaa98807145107c253 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Thor=C3=A9n?= <ot@oskarthoren.com>
Date: Tue, 28 Jul 2020 16:11:05 +0800
Subject: [PATCH] Waku v2: Add content filter for waku topics (#163)

* 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>
---
 specs/waku/waku-v2.md | 53 +++++++++++++++++++++++++++++++++----------
 wordlist.txt          |  4 ++++
 2 files changed, 45 insertions(+), 12 deletions(-)

diff --git a/specs/waku/waku-v2.md b/specs/waku/waku-v2.md
index fbb361d6..56f503b7 100644
--- a/specs/waku/waku-v2.md
+++ b/specs/waku/waku-v2.md
@@ -113,22 +113,28 @@ In this section we specify two things:
 
 ```protobuf
 message RPC {
-	repeated SubOpts subscriptions = 1;
-	repeated Message publish = 2;
+  repeated SubOpts subscriptions = 1;
+  repeated Message publish = 2;
+  repeated ContentFilter contentFilter = 3;
 
-	message SubOpts {
-		optional bool subscribe = 1;
-		optional string topicid = 2;
-	}
+  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 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;
 }
 ```
 
@@ -137,6 +143,11 @@ 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.
@@ -164,6 +175,22 @@ 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](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.
+
+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.
@@ -200,3 +227,5 @@ Copyright and related rights waived via
 6. [Whisper spec (EIP627)](https://eips.ethereum.org/EIPS/eip-627)
 
 7. [Waku v2 plan](https://vac.dev/waku-v2-plan)
+
+8. [Message Filtering (Wikipedia)](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering)
diff --git a/wordlist.txt b/wordlist.txt
index 6eb9b691..c560af35 100644
--- a/wordlist.txt
+++ b/wordlist.txt
@@ -22,6 +22,9 @@ cas
 changelog
 Changelog
 COSS
+ContentFilter
+contentFilter
+contentTopic
 CPU
 DAG
 DAGs
@@ -127,6 +130,7 @@ subprotocols
 TBD
 TCP
 textlint
+topicid
 topicIDs
 Thorén
 tla