From 912292ad1d85874181fb9158e7a893229f21efb1 Mon Sep 17 00:00:00 2001
From: Richard Ramos <info@richardramos.me>
Date: Fri, 6 May 2022 10:38:15 -0400
Subject: [PATCH] chore: add docs for waku store

---
 README.md        |  3 +-
 docs/encoding.md |  2 +-
 docs/store.md    | 83 ++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 86 insertions(+), 2 deletions(-)
 create mode 100644 docs/store.md

diff --git a/README.md b/README.md
index c5a9f5bb..62d1dd9f 100644
--- a/README.md
+++ b/README.md
@@ -52,7 +52,8 @@ make dynamic-library
 ## Tutorials and documentation
 - [Receive and send messages using Waku Relay](docs/relay.md)
 - [Send messages using Waku Lightpush](docs/lightpush.md)
-- [Encoding and decoding Waku Messages](docs/encoding.md)
+- [Encrypting and decrypting Waku Messages](docs/encoding.md)
+- [Retrieve message history using Waku Store](docs/store.md)
 - [C Bindings](library/README.md)
 
 ## Examples
diff --git a/docs/encoding.md b/docs/encoding.md
index 7821bde0..0bc421f1 100644
--- a/docs/encoding.md
+++ b/docs/encoding.md
@@ -1,4 +1,4 @@
-Encoding and decoding Waku Messages
+Encrypting and decrypting Waku Messages
 ===
 
 The Waku Message format provides an easy way to encrypt messages using symmetric or asymmetric encryption. The encryption comes with several handy design requirements: confidentiality, authenticity and integrity. You can find more details about Waku Message Payload Encryption in 26/WAKU-PAYLOAD.
diff --git a/docs/store.md b/docs/store.md
new file mode 100644
index 00000000..cdedc725
--- /dev/null
+++ b/docs/store.md
@@ -0,0 +1,83 @@
+Retrieve message history using Waku Store
+===
+
+DApps running on a phone or in a browser are often offline: The browser could be closed or mobile app in the background.
+
+[Waku Relay](https://rfc.vac.dev/spec/11/) is a gossip protocol. As a user, it means that your peers forward you messages they just received. If you cannot be reached by your peers, then messages are not relayed; relay peers do not save messages for later.
+
+However, [Waku Store](https://rfc.vac.dev/spec/13/) peers do save messages they relay, allowing you to retrieve them at a later time. The Waku Store protocol is best-effort and does not guarantee data availability. Waku Relay should still be preferred when online; Waku Store can be used after resuming connectivity: For example, when the dApp starts.
+
+
+```go
+import (
+    "context"
+    
+    "github.com/status-im/go-waku/waku/v2/protocol/store"
+)
+
+...
+query := store.Query{
+    Topic: ..., // optional pubsub topic
+    ContentTopics: []string{...}, // optional content topics
+    StartTime: ..., // optional start time in ms
+    EndTime: ..., // optional end time in ms
+}
+
+result, err := wakuNode.Store().Query(context.Background(), query, WithPaging(true, 20));
+for {
+    if err != nil {
+        fmt.Println(err)
+        break
+    }
+
+    if len(result.messages) == 0 {
+        // No more messages available
+        break
+    }
+
+    for _, msg := range result.messages {
+        fmt.Println(string(msg.Payload))
+    }
+
+    // Fetch more messages
+    result, err := wakuNode.Store().Next(context.Background(), result)
+}
+```
+
+To retrieve message history, a `store.Query` struct should be created with the attributes to filter the messages. This struct should be passed to `wakuNode.Store().Query`. A successful execution will return a `store.Result` that can be used to retrieve more messages if pagination is being used. `wakuNode.Store().Next` should be used if the number of messages in the `store.Result` is greater than 0.
+
+The query function also accepts a list of options:
+
+### Options
+- `store.WithPeer(peerID)` - use an specific peer ID (which should be part of the node peerstore) to broadcast the message with 
+- `store.WithAutomaticPeerSelection(host)` - automatically select a peer that supports store protocol from the peerstore to broadcast the message with
+- `store.WithFastestPeerSelection(ctx)` - automatically select a peer based on its ping reply time
+- `store.WithCursor(index)` - use cursor to retrieve messages starting from the index of a WakuMessage. This cursor can be obtained from a `store.Result` obtained from `wakuNode.Store().Query` 
+- `store.WithPaging(asc, pageSize)` - specify the order and maximum number of records to return
+
+## Filter messages
+
+### By timestamp
+By default, Waku Store nodes keep messages for 30 days. Depending on your use case, you may not need to retrieve 30 days worth of messages. Waku Message defines an optional unencrypted timestamp field. The timestamp is set by the sender. 
+You can filter messages that include a timestamp within given bounds with the `StartTime` and `EndTime` attributes of `store.Query`. If a message does have their timestamp attribute defined, the time when they were stored in the node will be used instead.
+
+```go
+// 7 days/week, 24 hours/day, 60min/hour, 60secs/min, 100ms/sec
+query := store.Query{
+    StartTime:  utils.GetUnixEpoch() - 7 * 24 * 60 * 60 * 1000,
+    EndTime:  utils.GetUnixEpoch()
+}
+
+result, err := wakuNode.Store().Query(context.Background(), query);
+```
+
+### By topic
+It is possible to filter the messages by the pubsub topic in which they were published, and by their content topic. The `ContentTopics` attribute maps to the `contentTopic` field of a `WakuMessage`. Multiple content topics can be specified. Leaving these fields empty will retrieve messages regardless on the pubsub topic they were published and content topic they contain.
+```go
+query := store.Query{
+    Topic: "some/pubsub/topic",
+    ContentTopics: []string{"content/topic/1", "content/topic/2"},
+}
+
+result, err := wakuNode.Store().Query(context.Background(), query);
+```
\ No newline at end of file