js-waku

A JavaScript implementation of the Waku v2 protocol.

Usage

Install js-waku package:

npm install js-waku

Start a waku node

import { Waku } from 'js-waku';

const waku = await Waku.create();

Connect to a new peer

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

// Or, add peer to address book so it auto dials in the background
waku.addPeerToAddressBook(
  '16Uiu2HAmPLe7Mzm8TsYUubgCAW1aJoeFScxrLj8ppHFivPo97bUZ',
  ['/dns4/node-01.do-ams3.wakuv2.test.statusim.net/tcp/443/wss']
);

You can also use getStatusFleetNodes to connect to nodes run by Status:

import { getStatusFleetNodes } from 'js-waku';

getStatusFleetNodes().then((nodes) => {
  nodes.forEach((addr) => {
    waku.dial(addr);
  });
});

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 and use an existing contentTopic. See the Waku v2 Topic Usage Recommendations 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:

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

The examples chat apps currently use content topic "/toy-chat/2/huilong/proto".

Send messages

There are two ways to send messages:

Waku Relay

Waku Relay is the most decentralised 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.

import { WakuMessage } from 'js-waku';

const msg = await WakuMessage.fromUtf8String("Here is a message!", { contentTopic: "/my-cool-app/1/my-use-case/proto" })
await waku.relay.send(msg);

Waku Light Push

Waku Light Push 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.

const ack = await waku.lightPush.push(message);
if (!ack?.isSuccess) {
  // Message was not sent
}

Retrieve archived messages

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

// Process messages once they are all retrieved
const messages = await waku.store.queryHistory({ contentTopics: ["/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({
    contentTopics: ["/my-cool-app/1/my-use-case/proto"],
    callback: (messages) => {
      messages.forEach((msg) => {
        console.log("Message retrieved:", msg.payloadAsUtf8);
      });
    }
  });

More documentation

Find more examples below or checkout the latest main branch documentation at https://status-im.github.io/js-waku/docs/.

Docs can also be generated locally using:

npm install
npm run doc

Changelog

Release changelog can be found here.

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
19/WAKU2-LIGHTPUSH	✔

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) or #waku-support on Status Community Discord.

Examples

Web Chat App (ReactJS)

A ReactJS chat app is provided as a showcase of the library used in the browser. It implements Waku v2 Toy Chat protocol. A deployed version is available at https://status-im.github.io/js-waku/.

Find the code in the examples folder.

To run a development version locally, do:

git clone https://github.com/status-im/js-waku/ ; cd js-waku
npm install   # Install dependencies for js-waku
npm run build # Build js-waku
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/js-waku

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 implements Waku v2 Toy Chat protocol.

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/js-waku/ ; cd js-waku
npm install   # Install dependencies for js-waku
npm run build # Build js-waku
cd examples/cli-chat
npm install # Install dependencies for the cli app
npm run start -- --autoDial

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.

Ethereum Direct Message

A PoC implementation of 20/ETH-DM.

Ethereum Direct Message, or Eth-DM, is a protocol that allows sending encrypted message to a recipient, only knowing their Ethereum Address.

This is protocol has been created to demonstrated how encryption and signature could be added to messages sent over the Waku v2 network.

The main branch's HEAD is deployed on GitHub Pages at https://status-im.github.io/js-waku/eth-dm/.

To run a development version locally, do:

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

Contributing

See CONTRIBUTING.md.

License

Licensed and distributed under either of

• MIT license: LICENSE-MIT or http://opensource.org/licenses/MIT

or

• Apache License, Version 2.0, (LICENSE-APACHE-v2 or http://www.apache.org/licenses/LICENSE-2.0)

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