From 067fdaba4c5c3ab83ac2b6df7a5b298996728c82 Mon Sep 17 00:00:00 2001 From: F Date: Wed, 1 Dec 2021 15:44:28 +1100 Subject: [PATCH] Fix links, remove overview file, add light push (#2) --- src/SUMMARY.md | 2 +- src/guides/README.md | 1 + src/guides/encrypt_messages_version_1.md | 8 +- src/guides/light_push_send_messages.md | 86 ++++++++++++++++++++ src/guides/reactjs_relay.md | 6 +- src/guides/reactjs_store.md | 8 +- src/guides/relay_receive_send_messages.md | 13 +-- src/guides/store_retrieve_messages.md | 10 +-- src/introduction.md | 16 ++-- src/overview.md | 96 ----------------------- src/quick_start.md | 6 +- 11 files changed, 124 insertions(+), 128 deletions(-) create mode 100644 src/guides/light_push_send_messages.md delete mode 100644 src/overview.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 117c5b2..7f72e36 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -3,7 +3,6 @@ [Introduction](introduction.md) - [Quick Start](quick_start.md) -- [Overview](overview.md) - [Guides](guides/README.md) - [How to Choose a Content Topic](guides/choose_content_topic.md) - [Receive and Send Messages Using Waku Relay](guides/relay_receive_send_messages.md) @@ -11,6 +10,7 @@ - [Encrypt Messages Using Waku Message Version 1](guides/encrypt_messages_version_1.md) - [Receive and Send Messages Using Waku Relay With ReactJS](guides/reactjs_relay.md) - [Retrieve Messages Using Waku Store With ReactJS](guides/reactjs_store.md) + - [Send Messages Using Waku Light Push](guides/light_push_send_messages.md) - [Examples](examples.md) [Implemented Waku Protocols](waku_protocols.md) diff --git a/src/guides/README.md b/src/guides/README.md index b8f1619..a11015d 100644 --- a/src/guides/README.md +++ b/src/guides/README.md @@ -9,6 +9,7 @@ - [Receive and Send Messages Using Waku Relay](relay_receive_send_messages.md) - [Retrieve Messages Using Waku Store](store_retrieve_messages.md) - [Encrypt Messages Using Waku Message Version 1](encrypt_messages_version_1.md) +- [Send Messages Using Waku Light Push](light_push_send_messages.md) ## ReactJS diff --git a/src/guides/encrypt_messages_version_1.md b/src/guides/encrypt_messages_version_1.md index d9fcc61..3e3d6ff 100644 --- a/src/guides/encrypt_messages_version_1.md +++ b/src/guides/encrypt_messages_version_1.md @@ -74,7 +74,7 @@ pass the key in the `symKey` property to `WakuMessage.fromBytes`. Same as Waku Messages version 0 (unencrypted), `payload` is your message payload and `contentTopic` is the content topic for your dApp. -See [Receive and Send Messages Using Waku Relay](relay-receive-send-messages.md) for details. +See [Receive and Send Messages Using Waku Relay](./relay_receive_send_messages.md) for details. ```js import { WakuMessage } from 'js-waku'; @@ -84,7 +84,7 @@ const message = await WakuMessage.fromBytes(payload, contentTopic, { }); ``` -The Waku Message can then be sent to the Waku network using [Waku Relay](relay-receive-send-messages.md) or Waku Light Push: +The Waku Message can then be sent to the Waku network using Waku Relay or Waku Light Push: ```js await waku.lightPush.push(message); @@ -141,7 +141,7 @@ to do so, pass it in the `encPublicKey` property to `WakuMessage.fromBytes`. Same as clear Waku Messages, `payload` is your message payload and `contentTopic` is the content topic for your dApp. -See [Receive and Send Messages Using Waku Relay](relay-receive-send-messages.md) for details. +See [Receive and Send Messages Using Waku Relay](./relay_receive_send_messages.md) for details. ```js import { WakuMessage } from 'js-waku'; @@ -151,7 +151,7 @@ const message = await WakuMessage.fromBytes(payload, contentTopic, { }); ``` -The Waku Message can then be sent to the Waku network using [Waku Relay](relay-receive-send-messages.md) or Waku Light Push: +The Waku Message can then be sent to the Waku network using Waku Relay or Waku Light Push: ```js await waku.lightPush.push(message); diff --git a/src/guides/light_push_send_messages.md b/src/guides/light_push_send_messages.md new file mode 100644 index 0000000..60ce61f --- /dev/null +++ b/src/guides/light_push_send_messages.md @@ -0,0 +1,86 @@ +# Send Messages Using Waku Light Push + +Waku Light Push enables a client to receive a confirmation when sending a message. + +The Waku Relay protocol sends messages to connected peers but does not provide any information on whether said peers have received messages. +This can be an issue when facing potential connectivity issues. +For example, when the connection drops easily, or it is connected to a small number of relay peers. + +Waku Light Push allows a client to get a response from a remote peer when sending a message. +Note this only guarantees that the remote peer has received the message, +it cannot guarantee propagation to the network. + +It also means weaker privacy properties as the remote peer knows the client is the originator of the message. +Whereas with Waku Relay, a remote peer would not know whether the client created or forwarded the message. + +You can find Waku Light Push's specifications on [Vac RFC](https://rfc.vac.dev/spec/19/). + +# Content Topic + +Before starting, you need to choose a _Content Topic_ for your dApp. +Check out the [how to choose a content topic guide](./choose_content_topic.md) to learn more about content topics. + +For this guide, we are using a single content topic: `/light-push-guide/1/guide/proto`. + +# Installation + +You can install [js-waku](https://npmjs.com/package/js-waku) using your favorite package manager: + +```shell +npm install js-waku +``` + +# Create Waku Instance + +In order to interact with the Waku network, you first need a Waku instance: + +```js +import { Waku } from 'js-waku'; + +const wakuNode = await Waku.create({ bootstrap: true }); +``` + +Passing the `bootstrap` option will connect your node to predefined Waku nodes. +If you want to bootstrap to your own nodes, you can pass an array of multiaddresses instead: + +```js +import { Waku } from 'js-waku'; + +const waku = await Waku.create({ + bootstrap: [ + '/dns4/node-01.ac-cn-hongkong-c.wakuv2.test.statusim.net/tcp/443/wss/p2p/16Uiu2HAkvWiyFsgRhuJEb9JfjYxEkoHLgnUQmr1N5mKWnYjxYRVm', + '/dns4/node-01.do-ams3.wakuv2.test.statusim.net/tcp/443/wss/p2p/16Uiu2HAmPLe7Mzm8TsYUubgCAW1aJoeFScxrLj8ppHFivPo97bUZ' + ] +}); +``` + +# Wait to be connected + +When using the `bootstrap` option, it may take some time to connect to other peers. +To ensure that you have a light push peer available to send messages to, +use the following function: + +```js +await waku.waitForConnectedPeer(); +``` + +The returned `Promise` will resolve once you are connected to a Waku peer. + +# Send messages + +You can now send a message using Waku Light Push. +By default, it sends the messages to a single randomly selected light push peer. +The peer is selected among the dApp's connected peers. + +If the dApp is not connected to any light push peer, an error is thrown. + +```ts +import {WakuMessage} from 'js-waku'; + +const wakuMessage = await WakuMessage.fromUtf8String('Here is a message', `/light-push-guide/1/guide/proto`); + +const ack = await waku.lightPush.push(wakuMessage); +if (!ack?.isSuccess) { + // Message was not sent +} +``` diff --git a/src/guides/reactjs_relay.md b/src/guides/reactjs_relay.md index 0b6a2a0..436b85a 100644 --- a/src/guides/reactjs_relay.md +++ b/src/guides/reactjs_relay.md @@ -4,7 +4,7 @@ It is easy to use DappConnect with ReactJS. In this guide, we will demonstrate how your ReactJS dApp can use Waku Relay to send and receive messages. Before starting, you need to choose a _Content Topic_ for your dApp. -Check out the [how to choose a content topic guide](choose-content-topic.md) to learn more about content topics. +Check out the [how to choose a content topic guide](./choose_content_topic.md) to learn more about content topics. For this guide, we are using a single content topic: `/min-react-js-chat/1/chat/proto`. # Setup @@ -28,7 +28,7 @@ Start the dev server and open the dApp in your browser: npm run start ``` -Note: We have noticed some issues with React bundling due to `npm` pulling an old version of babel. +Note: We have noticed some [issues](https://github.com/status-im/js-waku/issues/165) with React bundling due to `npm` pulling an old version of babel. If you are getting an error about the [optional chaining (?.)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) character not being valid, try cleaning up and re-installing your dependencies: @@ -297,4 +297,4 @@ function App() { And Voilà! You should now be able to send and receive messages. Try out by opening the app from different browsers. -You can see the complete code in the [Minimal ReactJS Chat App](/examples/min-react-js-chat). +You can see the complete code in the [Minimal ReactJS Chat App](https://github.com/status-im/js-waku/tree/main/examples/min-react-js-chat). diff --git a/src/guides/reactjs_store.md b/src/guides/reactjs_store.md index 7bd2d46..b0c19c3 100644 --- a/src/guides/reactjs_store.md +++ b/src/guides/reactjs_store.md @@ -21,7 +21,7 @@ For example, when the dApp starts. In this guide, we'll review how you can use Waku Store to retrieve messages. Before starting, you need to choose a _Content Topic_ for your dApp. -Check out the [how to choose a content topic guide](choose-content-topic.md) to learn more about content topics. +Check out the [how to choose a content topic guide](./choose_content_topic.md) to learn more about content topics. # Setup @@ -44,7 +44,7 @@ Start the dev server and open the dApp in your browser: npm run start ``` -Note: We have noticed some issues with React bundling due to `npm` pulling an old version of babel. +Note: We have noticed some [issues](https://github.com/status-im/js-waku/issues/165) with React bundling due to `npm` pulling an old version of babel. If you are getting an error about the [optional chaining (?.)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) character not being valid, try cleaning up and re-installing your dependencies: @@ -273,7 +273,7 @@ Depending on your use case, you may not need to retrieve 30 days worth of messag [Waku Message](https://rfc.vac.dev/spec/14/) defines an optional unencrypted `timestamp` field. The timestamp is set by the sender. -By default, js-waku [sets the timestamp of outgoing message to the current time](https://github.com/status-im/js-waku/blob/a056227538f9409aa9134c7ef0df25f602dbea58/src/lib/waku_message/index.ts#L76). +By default, js-waku sets the timestamp of outgoing message to the current time. You can filter messages that include a timestamp within given bounds with the `timeFilter` option. @@ -293,4 +293,4 @@ waku.store ## End result -You can see the complete code in the [Minimal ReactJS Waku Store App](/examples/store-reactjs-chat). +You can see the complete code in the [Minimal ReactJS Waku Store App](https://github.com/status-im/js-waku/tree/main/examples/store-reactjs-chat). diff --git a/src/guides/relay_receive_send_messages.md b/src/guides/relay_receive_send_messages.md index 07e3014..5578ac4 100644 --- a/src/guides/relay_receive_send_messages.md +++ b/src/guides/relay_receive_send_messages.md @@ -4,7 +4,7 @@ Waku Relay is a gossip protocol that enables you to send and receive messages. You can find Waku Relay's specifications on [Vac RFC](https://rfc.vac.dev/spec/11/). Before starting, you need to choose a _Content Topic_ for your dApp. -Check out the [how to choose a content topic guide](choose-content-topic.md) to learn more about content topics. +Check out the [how to choose a content topic guide](./choose_content_topic.md) to learn more about content topics. For this guide, we are using a single content topic: `/relay-guide/1/chat/proto`. @@ -23,7 +23,7 @@ In order to interact with the Waku network, you first need a Waku instance: ```js import { Waku } from 'js-waku'; -const wakuNode = await Waku.create({ bootstrap: true }); +const waku = await Waku.create({ bootstrap: true }); ``` Passing the `bootstrap` option will connect your node to predefined Waku nodes. @@ -32,7 +32,7 @@ If you want to bootstrap to your own nodes, you can pass an array of multiaddres ```js import { Waku } from 'js-waku'; -const wakuNode = await Waku.create({ +const waku = await Waku.create({ bootstrap: [ '/dns4/node-01.ac-cn-hongkong-c.wakuv2.test.statusim.net/tcp/443/wss/p2p/16Uiu2HAkvWiyFsgRhuJEb9JfjYxEkoHLgnUQmr1N5mKWnYjxYRVm', '/dns4/node-01.do-ams3.wakuv2.test.statusim.net/tcp/443/wss/p2p/16Uiu2HAmPLe7Mzm8TsYUubgCAW1aJoeFScxrLj8ppHFivPo97bUZ' @@ -50,11 +50,12 @@ use the following function: await waku.waitForConnectedPeer(); ``` -The returned Promise will resolve once you are connected to a Waku Relay peer. +The returned `Promise` will resolve once you are connected to a Waku Relay peer. # Receive messages -To watch messages for your app, you need to register an observer on relay for your app's content topic: +To receive messages for your app, +you need to register an observer on relay for your app's content topic: ```js const processIncomingMessage = (wakuMessage) => { @@ -185,7 +186,7 @@ waku.relay.addObserver(processIncomingMessage, ['/relay-guide/1/chat/proto']); That is it! Now, you know how to send and receive messages over Waku using the Waku Relay protocol. -Feel free to check out other [guides](menu.md) or [examples](/examples/examples.md). +Feel free to check out other [guides](./) or [examples](/examples.md). Here is the final code: diff --git a/src/guides/store_retrieve_messages.md b/src/guides/store_retrieve_messages.md index e37c4b8..bf00a10 100644 --- a/src/guides/store_retrieve_messages.md +++ b/src/guides/store_retrieve_messages.md @@ -3,7 +3,7 @@ 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/18/) is a gossip protocol. +[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. @@ -18,7 +18,7 @@ For example, when the dApp starts. In this guide, we'll review how you can use Waku Store to retrieve messages. Before starting, you need to choose a _Content Topic_ for your dApp. -Check out the [how to choose a content topic guide](choose-content-topic.md) to learn more about content topics. +Check out the [how to choose a content topic guide](./choose_content_topic.md) to learn more about content topics. For this guide, we are using a single content topic: `/store-guide/1/news/proto`. @@ -172,9 +172,9 @@ It will throw an error if no store node is available. By default, Waku Store nodes store messages for 30 days. Depending on your use case, you may not need to retrieve 30 days worth of messages. -[Waku Message](https://rfc.vac.dev/spec/14/) defiles an optional unencrypted `timestamp` field. +[Waku Message](https://rfc.vac.dev/spec/14/) defines an optional unencrypted `timestamp` field. The timestamp is set by the sender. -By default, js-waku [sets the timestamp of outgoing message to the current time](https://github.com/status-im/js-waku/blob/a056227538f9409aa9134c7ef0df25f602dbea58/src/lib/waku_message/index.ts#L76). +By default, js-waku sets the timestamp of outgoing message to the current time. You can filter messages that include a timestamp within given bounds with the `timeFilter` option. @@ -199,4 +199,4 @@ waku.store ## End result -You can see a similar example implemented in ReactJS in the [Minimal ReactJS Waku Store App](/examples/store-reactjs-chat). +You can see a similar example implemented in ReactJS in the [Minimal ReactJS Waku Store App](https://github.com/status-im/js-waku/tree/main/examples/store-reactjs-chat). diff --git a/src/introduction.md b/src/introduction.md index 4274cd3..1768ff3 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -2,22 +2,24 @@ DappConnect is a suite of libraries, SDKs and documentations to help you use Waku in your dApp. -Waku is decentralized, censorship-resistant, network and protocol family. +Waku is a decentralized, censorship-resistant, network and protocol family. It enables you to add communication features to your dApp in a decentralized manner, -ensuring your users that they will not be censored or deplatformed. +ensuring to your users that they will not be censored or de-platformed. Waku can be used for chat purposes and for many machine-to-machine use cases. You can learn more about Waku at [waku.vac.dev](https://waku.vac.dev). -The [get started](./overview) documentation introduces the js-waku library and the main API you would need to start building. JS-Waku is the TypeScript implementation of the Waku protocol, built for browser environment. -The [guides](./guides) describe specific usages of js-waku in more details. +The [quick start](./quick_start.md) presents an easy way to send and receive messages using js-waku. -The js-waku repository also holds a number of [examples](./examples.md). -The examples are working proof-of-concepts that demonstrate several features of Waku. -Check out the [example list](./examples.md) to see what feature each example demonstrates. +The [guides](./guides) explain specific js-waku features +and how it can be used with popular web frameworks. + +The js-waku repository also holds a number of [examples](https://github.com/status-im/js-waku/tree/main/examples). +The examples are working Proof-of-Concepts that demonstrate how to use js-waku. +Check out the [example list](./examples.md) to see what usage each example demonstrates. Finally, if you want to learn how Waku works under the hoods, check the specs at [rfc.vac.dev](https://rfc.vac.dev/). diff --git a/src/overview.md b/src/overview.md deleted file mode 100644 index c1d3cc4..0000000 --- a/src/overview.md +++ /dev/null @@ -1,96 +0,0 @@ -# JS-Waku Overview - -In this section you will learn how what are js-waku's key API and how to use them. - -To learn more about a specific API, you can refer to the [API documentation](). - -Our [guides](guides) provide more detailed explanation of some Waku functionality and how they can be used with popular web frameworks. - -## Installation - -Install `js-waku` package: - -```shell -npm install js-waku -# or with yarn -yarn add js-waku -``` - -### Start a waku node - -```ts -import { Waku } from 'js-waku'; - -const waku = await Waku.create({ bootstrap: true }); -``` - -### Listen for messages - -The `contentTopic` is a metadata `string` that allows categorization of messages on the waku network. -Depending on your use case, you can either create one (or several) new `contentTopic`(s) or look at the [RFCs](https://rfc.vac.dev/) and use an existing `contentTopic`. -See [How to Choose a Content Topic](guides/choose_content_topic.md) for more details. - -For example, if you were to use a new `contentTopic` such as `/my-cool-app/1/my-use-case/proto`, -here is how to listen to new messages received via [Waku v2 Relay](https://rfc.vac.dev/spec/11/): - -```ts -waku.relay.addObserver((msg) => { - console.log("Message received:", msg.payloadAsUtf8) -}, ["/my-cool-app/1/my-use-case/proto"]); -``` - -### Send messages - -There are two ways to send messages: - -#### Waku Relay - -[Waku Relay](https://rfc.vac.dev/spec/11/) is the most decentralized option, -peer receiving your messages are unlikely to know whether you are the originator or simply forwarding them. -However, it does not give you any delivery information. - -```ts -import { WakuMessage } from 'js-waku'; - -const msg = await WakuMessage.fromUtf8String("Here is a message!", "/my-cool-app/1/my-use-case/proto") -await waku.relay.send(msg); -``` - -#### Waku Light Push - -[Waku Light Push](https://rfc.vac.dev/spec/19/) gives you confirmation that the light push server node has -received your message. -However, it means that said node knows you are the originator of the message. -It cannot guarantee that the node will forward the message. - -```ts -const ack = await waku.lightPush.push(message); -if (!ack?.isSuccess) { - // Message was not sent -} -``` - -### Retrieve archived messages - -The [Waku v2 Store protocol](https://rfc.vac.dev/spec/13/) enables more permanent nodes to store messages received via relay -and ephemeral clients to retrieve them (e.g. mobile phone 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: - -```ts -// Process messages once they are all retrieved -const messages = await waku.store.queryHistory(['/my-cool-app/1/my-use-case/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(['/my-cool-app/1/my-use-case/proto'], { - callback: (messages) => { - messages.forEach((msg) => { - console.log('Message retrieved:', msg.payloadAsUtf8); - }); - } -}); -``` diff --git a/src/quick_start.md b/src/quick_start.md index 6e6cb70..3573e7f 100644 --- a/src/quick_start.md +++ b/src/quick_start.md @@ -4,8 +4,6 @@ In this section you will learn how to receive and send messages using Waku Relay A more in depth guide for Waku Relay can be found [here](guides/relay_receive_send_messages.md). -For an overview of the js-waku API, go [there](overview.md). - ## Install Install the `js-waku` package: @@ -50,3 +48,7 @@ import { WakuMessage } from 'js-waku'; const msg = await WakuMessage.fromUtf8String("Here is a message!", "/my-cool-app/1/my-use-case/proto") await waku.relay.send(msg); ``` + +### Building an app + +Check out the [ReactJS Waku Relay guide](./guides/reactjs_relay.md) to learn how you can use the code above in a React app.