Fix links, remove overview file, add light push (#2)
This commit is contained in:
F
GitHub
parent
b7dae41be9
commit
067fdaba4c
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
|
|
|
|||
|
|
@ -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
|
||||
}
|
||||
```
|
||||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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/).
|
||||
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
});
|
||||
}
|
||||
});
|
||||
```
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue