From 7d90205591c46bdaee6c9d3329ebcaea12126aac Mon Sep 17 00:00:00 2001
From: Kim De Mey <kim.demey@gmail.com>
Date: Mon, 20 Jul 2020 12:01:49 +0200
Subject: [PATCH] Start adding waku v2 api calls (#50)

* Start adding waku v2 api calls

* Another attempt at Waku v2 API
---
 docs/api/v2/node.md | 100 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 88 insertions(+), 12 deletions(-)

diff --git a/docs/api/v2/node.md b/docs/api/v2/node.md
index 89cbe7361..34fab6002 100644
--- a/docs/api/v2/node.md
+++ b/docs/api/v2/node.md
@@ -1,16 +1,82 @@
-# Node API
-
-TBD.
-
-*NOTE: Below is a scratch of what the API currently looks like. This will likely change. See https://github.com/status-im/nim-waku/issues/39*
+# Waku APIs
 
 ## Nim API
 
-*NOTE: Some of these are currently at the protocol layer rather than than the Node itself.*
+### WakuSub API
 
-```
+This is an internal API to be used by the Waku API. It is practically a small
+layer above GossipSub. And possibly a request/response libp2p protocol.
+
+```Nim
+# TODO: Some init call to set things up?
 method publish*(w: WakuSub, topic: string, data: seq[byte]) {.async.}
 method subscribe*(w: WakuSub, topic: string, handler: TopicHandler) {.async.}
+method unsubscribe*(w: WakuSub, topics: seq[TopicPair]) {.async.}
+
+# TODO: Calls for non GossipSub communication.
+```
+
+### Waku API
+
+This API is very dependend on how the protocol should work for functionality
+such as light nodes (no relaying) and nodes that do not want to get messages
+from all `WakuTopic`s.
+
+See also issue:
+https://github.com/vacp2p/specs/issues/156
+
+For now it is assumed that we will require a seperate request-response protocol
+for this, next to the GossipSub domain.
+
+```Nim
+type
+  WakuOptions = object
+    # If there are more capabilities than just light node, we can create a
+    # capabilities field.
+    lightNode: bool
+    topics: seq[WakuTopic]
+    bloomfilter: Bloom # TODO: No longer needed with Gossip?
+    limits: Limits
+
+proc init(w: WakuNode, conf: WakuConfig)
+## Initialize the WakuNode.
+##
+## When not a light node, this will set up the node to be part of the gossipsub
+## network with a subscription to the general Waku Topic.
+## When a light node, this will connect to full node peer(s) with provided
+## `topics` or `bloomfilter` for the full node to filter messages on.
+
+proc publish(w: WakuNode, topic: WakuTopic, data: seq[byte]): bool
+## Publish a message with specified `WakuTopic`.
+##
+## Both full node and light node can use the GossipSub network to publish.
+
+proc subscribe(w: WakuNode, topics: seq[WakuTopic], handler: WakuHandler): Identifier
+## Subscribe to the provided `topics`, handler will be called on receival of
+## messages on those topics.
+##
+## In case of a full node, this will be through the GossipSub network (see,
+## subscription in `init`)
+## In case of the light node, this will likely be through a separate request
+## response network where the full node filters out the messages.
+
+proc unsubscribe(id: Identifier): bool
+## Unsubscribe handler for topics.
+
+# Can get rid of the identifiers in subscribe and unsubscribe and track topics +
+# handler like in WakuSub, if that is more convenient.
+
+proc setLightNode(isLightNode: bool)
+## Change light node setting. This might trigger change in subscriptions from
+## the gossip domain to the request response domain and vice versa.
+
+proc setTopicInterest(topics: seq[string])
+## Change the topic interests.
+# TODO: Only valid if light node?
+
+proc setBloomFilter(topics: seq[string])
+## Change the topic interests.
+# TODO: Still required if we have gossip?
 ```
 
 ## JSON RPC
@@ -18,10 +84,20 @@ method subscribe*(w: WakuSub, topic: string, handler: TopicHandler) {.async.}
 **TODO: Data should be RPC Messages / bytes**
 **TODO: Enable topic handler**
 
-Call sigs:
+Call signatures:
+
+```Nim
+proc waku_version(): string
+proc waku_info(): WakuInfo
+proc waku_publish(topic: string, message: string): bool
+proc waku_subscribe(topics: seq[string]): Identifier
+proc waku_unsubscribe(id: Identifier): bool
+
+# TODO: Do we still want to be able to pull for data also?
+# E.g. a getTopicsMessages(topics: seq[string])?
+
+proc waku_setLightNode(isLightNode: bool)
+proc waku_setTopicInterest(topics: seq[string])
+proc waku_setBloomFilter(topics: seq[string])
 
 ```
-proc waku_version(): string
-proc waku_publish(topic: string, message: string): bool
-proc waku_subscribe(topic: string): bool
-```