JavaScript implementation of Waku v2 https://js.waku.org
Go to file
Franck Royer 27b08ff8b6
Merge pull request #149 from status-im/dial-usage
2021-05-13 16:00:49 +10:00
.github Rename repo to waku-js 2021-05-13 11:01:41 +10:00
.vscode Format json files 2021-05-04 10:49:14 +10:00
examples Enhance addPeerToAddressBook 2021-05-13 13:42:40 +10:00
nim-waku@7c5df3379b Upgrade nim-waku to latest version 2021-05-07 11:30:36 +10:00
proto Remove `Proto` suffix 2021-05-10 15:53:23 +10:00
src Enhance addPeerToAddressBook 2021-05-13 13:42:40 +10:00
.cspell.json Add documentation to the readme 2021-05-12 13:35:25 +10:00
.editorconfig Initial commit 2021-03-05 09:34:01 +11:00
.eslintrc.json Exclude test files from build 2021-05-11 14:05:12 +10:00
.gitignore Check in protobuf generated files 2021-04-20 15:32:10 +10:00
.gitmodules Re-add nim-waku submodule 2021-03-19 11:23:34 +11:00
.mocharc.json Move mocha --exit to config file 2021-05-05 09:59:32 +10:00
.prettierignore Use waku messages over waku relay 2021-03-10 16:22:49 +11:00
CHANGELOG.md Update usage with dial peer method 2021-05-13 13:43:08 +10:00
CONTRIBUTING.md Rename repo to waku-js 2021-05-13 11:01:41 +10:00
LICENSE-APACHE-v2 Apply MIT or Apache V2.0 License 2021-04-28 21:27:26 +10:00
LICENSE-MIT Apply MIT or Apache V2.0 License 2021-04-28 21:27:26 +10:00
README.md Update usage with dial peer method 2021-05-13 13:43:08 +10:00
bors.toml Move web-chat to examples folder 2021-05-05 16:35:14 +10:00
buf.gen.yaml Implement chat message protobuf to support nick and time handles 2021-04-01 11:01:15 +11:00
buf.yaml Use waku messages over waku relay 2021-03-10 16:22:49 +11:00
netlify.toml Add netlify config 2021-05-11 10:50:58 +10:00
package-lock.json Set first release version to 0.1.0 2021-05-13 11:01:41 +10:00
package.json Rename repo to waku-js 2021-05-13 11:01:41 +10:00
tsconfig.dev.json Exclude test files from build 2021-05-11 14:05:12 +10:00
tsconfig.json Exclude test files from build 2021-05-11 14:05:12 +10:00
tsconfig.module.json Exclude test files from build 2021-05-11 14:05:12 +10:00

README.md

WakuJS

A JavaScript implementation of the Waku v2 protocol.

Usage

Install waku-js package:

npm install waku-js

Start a waku node:

import { Waku } from 'waku-js';

const waku = await Waku.create();

Connect to a new peer:

import { multiaddr } from 'multiaddr';
import PeerId from 'peer-id';

// Directly dial a new peer
await waku.dial('/dns4/node-01.do-ams3.jdev.misc.statusim.net/tcp/7010/wss/p2p/16Uiu2HAmPLe7Mzm8TsYUubgCAW1aJoeFScxrLj8ppHFivPo97bUZ');

// Or, add peer to address book so it auto dials in the background
waku.addPeerToAddressBook(
  '16Uiu2HAmPLe7Mzm8TsYUubgCAW1aJoeFScxrLj8ppHFivPo97bUZ',
  ['/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 and use an existing contentTopic. See the Waku v2 Message spec for more details.

Listen to new messages received via Waku v2 Relay, filtering the contentTopic to waku/2/my-cool-app/proto:

waku.relay.addObserver((msg) => {
  console.log("Message received:", msg.payloadAsUtf8)
}, ["waku/2/my-cool-app/proto"]);

Send a message on the waku relay network:

import { WakuMessage } from 'waku-js';

const msg = WakuMessage.fromUtf8String("Here is a message!", "waku/2/my-cool-app/proto")
await waku.relay.send(msg);

The Waku v2 Store protocol 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:

// 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 below or checkout the latest main branch documentation at https://status-im.github.io/waku-js/docs/.

Docs can also be generated locally using:

npm install
npm run doc

Waku Protocol Support

You can track progress on the project board.

  • ✔: Supported
  • 🚧: Implementation in progress
  • : Support is not planned
Spec Implementation Status
6/WAKU1
7/WAKU-DATA
8/WAKU-MAIL
9/WAKU-RPC
10/WAKU2 🚧
11/WAKU2-RELAY
12/WAKU2-FILTER
13/WAKU2-STORE ✔ (querying node only)
14/WAKU2-MESSAGE
15/WAKU2-BRIDGE
16/WAKU2-RPC
17/WAKU2-RLNRELAY
18/WAKU2-SWAP

Bugs, Questions & Features

If you encounter any bug or would like to propose new features, feel free to open an issue.

For support, questions & more general topics, please join the discussion on the Vac forum (use #js-waku tag).

Examples

Web Chat App (ReactJS)

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/waku-js/

Find the code in the examples folder.

To run a development version locally, do:

git clone https://github.com/status-im/waku-js/ ; cd waku-js
npm install   # Install dependencies for waku-js
npm run build # Build waku-js
cd examples/web-chat   
npm install   # Install dependencies for the web app
npm run start # Start development server to serve the web app on http://localhost:3000/waku-js

Use /help to see the available commands.

CLI Chat App (NodeJS)

A node chat app is provided as a working example of the library. It is interoperable with the nim-waku chat app example.

Find the code in the examples folder.

To run the chat app, first ensure you have Node.js v14 or above:

node --version

Then, install and run:

git clone https://github.com/status-im/waku-js/ ; cd waku-js
npm install   # Install dependencies for waku-js
npm run build # Build waku-js
cd examples/cli-chat
npm install # Install dependencies for the cli app
npm run start -- --staticNode /ip4/134.209.139.210/tcp/30303/p2p/16Uiu2HAmPLe7Mzm8TsYUubgCAW1aJoeFScxrLj8ppHFivPo97bUZ

You can also specify an optional listenAddr parameter (.e.g --listenAddr /ip4/0.0.0.0/tcp/7777/ws). This is only useful if you want a remote node to dial to your chat app, it is not necessary in normal usage when you just connect to the fleet.

Contributing

See CONTRIBUTING.md.

License

Licensed and distributed under either of

or

at your option. These files may not be copied, modified, or distributed except according to those terms.