From 0ffde9cf42a0028b0a51798ba17e08a1ebed1069 Mon Sep 17 00:00:00 2001
From: Franck Royer <franck@status.im>
Date: Wed, 12 May 2021 13:18:37 +1000
Subject: [PATCH] Add documentation to the readme

---
 .cspell.json |  1 +
 CHANGELOG.md |  3 ++
 README.md    | 88 ++++++++++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 86 insertions(+), 6 deletions(-)

diff --git a/.cspell.json b/.cspell.json
index 2c619023e7..be115ec6df 100644
--- a/.cspell.json
+++ b/.cspell.json
@@ -46,6 +46,7 @@
     "nodekey",
     "peerhave",
     "prettierignore",
+    "proto",
     "protobuf",
     "protoc",
     "reactjs",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b7933ba974..a72b41ec97 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Add usage section to the README.
+
 ## [1.0.0] - 2021-05-11
 
 ### Added
diff --git a/README.md b/README.md
index 6442d6e6f0..ee6b9458e0 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,82 @@
-# js-waku
+# WakuJS
 
-A JavaScript implementation of the [Waku v2 protocol](https://specs.vac.dev/specs/waku/v2/waku-v2).
+A JavaScript implementation of the [Waku v2 protocol](https://rfc.vac.dev/spec/10/).
 
-## Documentation
+## Usage
 
-Latest `main` branch documentation can be found at [https://status-im.github.io/js-waku/docs/](https://status-im.github.io/js-waku/docs/).
+Install `web3-waku` package:
+
+```shell
+npm install web3-waku
+```
+
+Start a waku node:
+
+```javascript
+import { Waku } from 'web3-waku';
+
+const waku = await Waku.create();
+```
+
+Connect to a new peer:
+
+```javascript
+import { multiaddr } from 'multiaddr';
+import PeerId from 'peer-id';
+
+waku.libp2p.peerStore.addressBook.add(
+  PeerId.createFromB58String(
+    '16Uiu2HAmPLe7Mzm8TsYUubgCAW1aJoeFScxrLj8ppHFivPo97bUZ'
+  ),
+  [multiaddr('/dns4/node-01.do-ams3.jdev.misc.statusim.net/tcp/7010/wss')]
+);
+```
+
+The `contentTopic` is a metadata `string` that allows categorization of messages on the waku network.
+Depending on your use case, you can either create a new `contentTopic` or look at the [RFCs](https://rfc.vac.dev/) and use an existing `contentTopic`.
+See the [Waku v2 Message spec](https://rfc.vac.dev/spec/14/) for more details.
+
+Listen to new messages received via [Waku v2 Relay](https://rfc.vac.dev/spec/11/), filtering the `contentTopic` to `waku/2/my-cool-app/proto`:
+
+```javascript
+waku.relay.addObserver((msg) => {
+  console.log("Message received:", msg.payloadAsUtf8)
+}, ["waku/2/my-cool-app/proto"]);
+```
+
+Send a message on the waku relay network:
+
+```javascript
+import { WakuMessage } from 'web3-waku';
+
+const msg = WakuMessage.fromUtf8String("Here is a message!", "waku/2/my-cool-app/proto")
+await waku.relay.send(msg);
+```
+
+The [Waku v2 Store protocol](https://rfc.vac.dev/spec/13/) enables full nodes to store messages received via relay
+and clients to retrieve them (e.g. after resuming connectivity).
+The protocol implements pagination meaning that it may take several queries to retrieve all messages.
+
+Query a waku store peer to check historical messages:
+
+```javascript
+// Process messages once they are all retrieved:
+const messages = await waku.store.queryHistory(storePeerId, ["waku/2/my-cool-app/proto"]);
+messages.forEach((msg) => {
+  console.log("Message retrieved:", msg.payloadAsUtf8)
+})
+
+// Or, pass a callback function to be executed as pages are received:
+waku.store.queryHistory(storePeerId, ["waku/2/my-cool-app/proto"],
+  (messages) => {
+    messages.forEach((msg) => {
+      console.log("Message retrieved:", msg.payloadAsUtf8)
+    })
+  });
+```
+
+Find more [examples](#examples) below
+or checkout the latest `main` branch documentation at [https://status-im.github.io/js-waku/docs/](https://status-im.github.io/js-waku/docs/).
 
 Docs can also be generated locally using:
 
@@ -47,10 +119,11 @@ For support, questions & more general topics, please join the discussion on the
 
 ## Web Chat App (ReactJS)
 
-A ReactJS web app is provided as an a show case of the library used in the browser.
-
+A ReactJS chat app is provided as a showcase of the library used in the browser.
 A deployed version is available at https://status-im.github.io/js-waku/
 
+Find the code in the [examples folder](https://github.com/status-im/js-waku/tree/main/examples/web-chat).
+
 To run a development version locally, do:
 
 ```shell
@@ -68,6 +141,9 @@ Use `/help` to see the available commands.
 
 A node chat app is provided as a working example of the library.
 It is interoperable with the [nim-waku chat app example](https://github.com/status-im/nim-waku/blob/master/examples/v2/chat2.nim).
+
+Find the code in the [examples folder](https://github.com/status-im/js-waku/tree/main/examples/cli-chat).
+
 To run the chat app, first ensure you have [Node.js](https://nodejs.org/en/) v14 or above:
 
 ```shell