Send and Receive Messages Using Light Push and Filter
This guide provides detailed steps to start using the @waku/sdk
package by setting up a Light Node to send messages using the Light Push protocol, and receive messages using the Filter protocol. Have a look at the installation guide for steps on adding @waku/sdk
to your project.
Create a light node
Use the createLightNode()
function to create a Light Node and interact with the Waku Network:
import { createLightNode } from "@waku/sdk";
// Create and start a Light Node
const node = await createLightNode({ defaultBootstrap: true });
await node.start();
// Use the stop() function to stop a running node
// await node.stop();
When the defaultBootstrap
parameter is set to true
, your node will be bootstrapped using the default bootstrap method. Have a look at the Bootstrap Nodes and Discover Peers guide to learn more methods to bootstrap nodes.
A node needs to know how to route messages. In order to do that you can use standard pubsub topic (/waku/2/default-waku/proto
). If your project uses a different shared pubsub topic, you can configure this using the ShardInfo
parameter or by using a set of contentTopics
that your node will be using:
// Create the shard info
const shardInfo = { clusterId: 3, shards: [1, 2] };
// Create node with custom shard info
const node = await createLightNode({
defaultBootstrap: true,
shardInfo: shardInfo,
});
Connect to remote peers
Use the waitForRemotePeer()
function to wait for the node to connect with peers on the Waku Network:
import { waitForRemotePeer } from "@waku/sdk";
// Wait for a successful peer connection
await waitForRemotePeer(node);
The protocols
parameter allows you to specify the protocols that the remote peers should have enabled:
import { waitForRemotePeer, Protocols } from "@waku/sdk";
// Wait for peer connections with specific protocols
await waitForRemotePeer(node, [Protocols.LightPush, Protocols.Filter]);
Choose a content topic
Choose a content topic for your application and create a message encoder
and decoder
:
import { createEncoder, createDecoder } from "@waku/sdk";
// Choose a content topic
const contentTopic = "/light-guide/1/message/proto";
// Create a message encoder and decoder
const encoder = createEncoder({ contentTopic });
const decoder = createDecoder(contentTopic);
The ephemeral
parameter allows you to specify whether messages should NOT be stored by Store peers:
const encoder = createEncoder({
contentTopic: contentTopic, // message content topic
ephemeral: true, // allows messages NOT be stored on the network
});
The pubsubTopicShardInfo
parameter allows you to configure a different shared pubsub topic for your encoder
and decoder
:
// Create the shard info
const shardInfo = { clusterId: 3, shard: 1 };
// Create encoder and decoder with custom shard info
const encoder = createEncoder({
contentTopic: contentTopic,
pubsubTopicShardInfo: shardInfo,
});
const decoder = createDecoder(contentTopic, shardInfo);
In this example, users send and receive messages on a shared content topic. However, real applications may have users broadcasting messages while others listen or only have 1:1 exchanges. Waku supports all these use cases.
Create a message structure
Create your application's message structure using Protobuf's valid message fields:
import protobuf from "protobufjs";
// Create a message structure using Protobuf
const ChatMessage = new protobuf.Type("ChatMessage")
.add(new protobuf.Field("timestamp", 1, "uint64"))
.add(new protobuf.Field("sender", 2, "string"))
.add(new protobuf.Field("message", 3, "string"));
Have a look at the Protobuf installation guide for adding the protobufjs
package to your project.
Send messages using light push
To send messages over the Waku Network using the Light Push
protocol, create a new message object and use the lightPush.send()
function:
// Create a new message object
const protoMessage = ChatMessage.create({
timestamp: Date.now(),
sender: "Alice",
message: "Hello, World!",
});
// Serialise the message using Protobuf
const serialisedMessage = ChatMessage.encode(protoMessage).finish();
// Send the message using Light Push
await node.lightPush.send(encoder, {
payload: serialisedMessage,
});
Receive messages using filter
To receive messages using the Filter
protocol, create a callback function for message processing, then use the filter.subscribe()
function to subscribe to a content topic
:
// Create the callback function
const callback = (wakuMessage) => {
// Check if there is a payload on the message
if (!wakuMessage.payload) return;
// Render the messageObj as desired in your application
const messageObj = ChatMessage.decode(wakuMessage.payload);
console.log(messageObj);
};
// Create a Filter subscription
const { error, subscription } = await node.filter.createSubscription({ contentTopics: [contentTopic] });
if (error) {
// handle errors if happens
throw Error(error);
}
// Subscribe to content topics and process new messages
await subscription.subscribe([decoder], callback);
The pubsubTopicShardInfo
parameter allows you to configure a different shared pubsub topic for your Filter
subscription:
// Create the shard info
const shardInfo = { clusterId: 3, shard: 1 };
// Create Filter subscription with custom shard info
const subscription = await node.filter.createSubscription(shardInfo);
You can use the subscription.unsubscribe()
function to stop receiving messages from a content topic:
await subscription.unsubscribe([contentTopic]);
You have successfully sent and received messages over the Waku Network using the Light Push
and Filter
protocols. Have a look at the light-js and light-chat examples for working demos.