Add documentation to the readme

This commit is contained in:
Franck Royer 2021-05-12 13:18:37 +10:00
parent b227114d8e
commit 0ffde9cf42
No known key found for this signature in database
GPG Key ID: A82ED75A8DFC50A4
3 changed files with 86 additions and 6 deletions

View File

@ -46,6 +46,7 @@
"nodekey",
"peerhave",
"prettierignore",
"proto",
"protobuf",
"protoc",
"reactjs",

View File

@ -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

View File

@ -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