docs.waku.org/assets/js/c57f3997.997cbe1f.js

"use strict";(self.webpackChunkwaku_guide=self.webpackChunkwaku_guide||[]).push([[732],{28453:(e,s,n)=>{n.d(s,{R:()=>a,x:()=>i});var t=n(96540);const o={},r=t.createContext(o);function a(e){const s=t.useContext(r);return t.useMemo(function(){return"function"==typeof e?e(s):{...s,...e}},[s,e])}function i(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:a(e.components),t.createElement(r.Provider,{value:s},e.children)}},88839:(e,s,n)=>{n.r(s),n.d(s,{assets:()=>c,contentTitle:()=>i,default:()=>h,frontMatter:()=>a,metadata:()=>t,toc:()=>d});const t=JSON.parse('{"id":"guides/js-waku/light-send-receive","title":"Send and Receive Messages Using Light Push and Filter","description":"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.","source":"@site/docs/guides/js-waku/light-send-receive.md","sourceDirName":"guides/js-waku","slug":"/guides/js-waku/light-send-receive","permalink":"/guides/js-waku/light-send-receive","draft":false,"unlisted":false,"editUrl":"https://github.com/waku-org/docs.waku.org/tree/develop/docs/guides/js-waku/light-send-receive.md","tags":[],"version":"current","lastUpdatedAt":null,"frontMatter":{"title":"Send and Receive Messages Using Light Push and Filter","hide_table_of_contents":true},"sidebar":"guides","previous":{"title":"Send and Receive Messages in a Reliable Channel","permalink":"/guides/js-waku/reliable-channels"},"next":{"title":"Retrieve Messages Using Store Protocol","permalink":"/guides/js-waku/store-retrieve-messages"}}');var o=n(74848),r=n(28453);const a={title:"Send and Receive Messages Using Light Push and Filter",hide_table_of_contents:!0},i=void 0,c={},d=[{value:"Create a light node",id:"create-a-light-node",level:2},{value:"Alternative network configuration",id:"alternative-network-configuration",level:3},{value:"Connect to remote peers",id:"connect-to-remote-peers",level:2},{value:"Choose a content topic",id:"choose-a-content-topic",level:2},{value:"Create a message structure",id:"create-a-message-structure",level:2},{value:"Send messages using light push",id:"send-messages-using-light-push",level:2},{value:"Receive messages using filter",id:"receive-messages-using-filter",level:2}];function l(e){const s={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",p:"p",pre:"pre",strong:"strong",...(0,r.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsxs)(s.p,{children:["This guide provides detailed steps to start using the ",(0,o.jsx)(s.code,{children:"@waku/sdk"})," package by setting up a ",(0,o.jsx)(s.a,{href:"/learn/glossary#light-node",children:"Light Node"})," to send messages using the ",(0,o.jsx)(s.a,{href:"/learn/concepts/protocols#light-push",children:"Light Push protocol"}),", and receive messages using the ",(0,o.jsx)(s.a,{href:"/learn/concepts/protocols#filter",children:"Filter protocol"}),". Have a look at the ",(0,o.jsx)(s.a,{href:"/guides/js-waku/#installation",children:"installation guide"})," for steps on adding ",(0,o.jsx)(s.code,{children:"@waku/sdk"})," to your project."]}),"\n",(0,o.jsx)(s.h2,{id:"create-a-light-node",children:"Create a light node"}),"\n",(0,o.jsxs)(s.p,{children:["Use the ",(0,o.jsx)(s.code,{children:"createLightNode()"})," function to create a ",(0,o.jsx)(s.a,{href:"/learn/glossary#light-node",children:"Light Node"})," and interact with the Waku Network:"]}),"\n",(0,o.jsx)(s.pre,{children:(0,o.jsx)(s.code,{className:"language-js",children:'import { createLightNode } from "@waku/sdk";\n\n// Create and start a Light Node\nconst node = await createLightNode({ defaultBootstrap: true });\nawait node.start();\n\n// Use the stop() function to stop a running node\n// await node.stop();\n'})}),"\n",(0,o.jsx)(s.admonition,{type:"info",children:(0,o.jsxs)(s.p,{children:["When the ",(0,o.jsx)(s.code,{children:"defaultBootstrap"})," parameter is set to ",(0,o.jsx)(s.code,{children:"true"}),", your node will be bootstrapped using the ",(0,o.jsx)(s.a,{href:"/guides/js-waku/configure-discovery#default-bootstrap-method",children:"default bootstrap method"}),". Have a look at the ",(0,o.jsx)(s.a,{href:"/guides/js-waku/configure-discovery",children:"Bootstrap Nodes and Discover Peers"})," guide to learn more methods to bootstrap nodes."]})}),"\n",(0,o.jsxs)(s.p,{children:["A node needs to know how to route messages. By default, it will use The Waku Network configuration (",(0,o.jsx)(s.code,{children:"{ clusterId: 1, shards: [0,1,2,3,4,5,6,7] }"}),"). For most applications, it's recommended to use autosharding:"]}),"\n",(0,o.jsx)(s.pre,{children:(0,o.jsx)(s.code,{className:"language-js",children:'// Create node with auto sharding (recommended)\nconst node = await createLightNode({\n  defaultBootstrap: true,\n  networkConfig: {\n    clusterId: 1,\n    contentTopics: ["/my-app/1/notifications/proto"],\n  },\n});\n'})}),"\n",(0,o.jsx)(s.h3,{id:"alternative-network-configuration",children:"Alternative network configuration"}),"\n",(0,o.jsx)(s.p,{children:"If your project requires a specific network configuration, you can use static sharding:"}),"\n",(0,o.jsx)(s.pre,{children:(0,o.jsx)(s.code,{className:"language-js",children:"// Create node with static sharding\nconst node = await createLightNode({\n  defaultBootstrap: true,\n  networkConfig: {\n    clusterId: 1,\n    shards: [0, 1, 2, 3],\n  },\n});\n"})}),"\n",(0,o.jsx)(s.h2,{id:"connect-to-remote-peers",children:"Connect to remote peers"}),"\n",(0,o.jsxs)(s.p,{children:["Use the ",(0,o.jsx)(s.code,{children:"node.waitForPeers()"})," function to wait for the node to connect with peers on the Waku Network:"]}),"\n",(0,o.jsx)(s.pre,{children:(0,o.jsx)(s.code,{className:"language-js",children:"// Wait for a successful peer connection\nawait node.waitForPeers();\n"})}),"\n",(0,o.jsxs)(s.p,{children:["The ",(0,o.jsx)(s.code,{children:"protocols"})," parameter allows you to specify the ",(0,o.jsx)(s.a,{href:"/learn/concepts/protocols",children:"protocols"})," that the remote peers should have enabled:"]}),"\n",(0,o.jsx)(s.pre,{children:(0,o.jsx)(s.code,{className:"language-js",children:'import { Protocols } from "@waku/sdk";\n\n// Wait for peer connections with specific protocols\nawait node.waitForPeers([Protocols.LightPush, Protocols.Filter]);\n'})}),"\n",(0,o.jsx)(s.h2,{id:"choose-a-content-topic",children:"Choose a content topic"}),"\n",(0,o.jsxs)(s.p,{children:["Choose a ",(0,o.jsx)(s.a,{href:"/learn/concepts/content-topics",children:"content topic"})," for your application and create a message ",(0,o.jsx)(s.code,{children:"encoder"})," and ",(0,o.jsx)(s.code,{children:"decoder"}),":"]}),"\n",(0,o.jsx)(s.pre,{children:(0,o.jsx)(s.code,{className:"language-js",children:'import { createEncoder, createDecoder } from "@waku/sdk";\n\n// Choose a content topic\nconst contentTopic = "/light-guide/1/message/proto";\n\n// Create a message encoder and decoder\nconst encoder = createEncoder({ contentTopic });\nconst decoder = createDecoder(contentTopic);\n'})}),"\n",(0,o.jsxs)(s.p,{children:["The ",(0,o.jsx)(s.code,{children:"ephemeral"})," parameter allows you to specify whether messages should ",(0,o.jsx)(s.strong,{children:"NOT"})," be stored by ",(0,o.jsx)(s.a,{href:"/guides/js-waku/store-retrieve-messages",children:"Store peers"}),":"]}),"\n",(0,o.jsx)(s.pre,{children:(0,o.jsx)(s.code,{className:"language-js",children:"const encoder = createEncoder({\n  contentTopic: contentTopic, // message content topic\n  ephemeral: true, // allows messages NOT be stored on the network\n});\n"})}),"\n",(0,o.jsxs)(s.p,{children:["The ",(0,o.jsx)(s.code,{children:"pubsubTopicShardInfo"})," parameter allows you to configure a different network configuration for your ",(0,o.jsx)(s.code,{children:"encoder"})," and ",(0,o.jsx)(s.code,{children:"decoder"}),":"]}),"\n",(0,o.jsx)(s.pre,{children:(0,o.jsx)(s.code,{className:"language-js",children:"// Create the network config\nconst networkConfig = { clusterId: 3, shards: [1, 2] };\n\n// Create encoder and decoder with custom network config\nconst encoder = createEncoder({\n  contentTopic: contentTopic,\n  pubsubTopicShardInfo: networkConfig,\n});\nconst decoder = createDecoder(contentTopic, networkConfig);\n"})}),"\n",(0,o.jsx)(s.admonition,{type:"info",children:(0,o.jsx)(s.p,{children:"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."})}),"\n",(0,o.jsx)(s.h2,{id:"create-a-message-structure",children:"Create a message structure"}),"\n",(0,o.jsxs)(s.p,{children:["Create your application's message structure using ",(0,o.jsx)(s.a,{href:"https://github.com/protobufjs/protobuf.js#usage",children:"Protobuf's valid message"})," fields:"]}),"\n",(0,o.jsx)(s.pre,{children:(0,o.jsx)(s.code,{className:"language-js",children:'import protobuf from "protobufjs";\n\n// Create a message structure using Protobuf\nconst DataPacket = new protobuf.Type("DataPacket")\n  .add(new protobuf.Field("timestamp", 1, "uint64"))\n  .add(new protobuf.Field("sender", 2, "string"))\n  .add(new protobuf.Field("message", 3, "string"));\n'})}),"\n",(0,o.jsx)(s.admonition,{type:"info",children:(0,o.jsxs)(s.p,{children:["Have a look at the ",(0,o.jsx)(s.a,{href:"/guides/js-waku/#message-structure",children:"Protobuf installation"})," guide for adding the ",(0,o.jsx)(s.code,{children:"protobufjs"})," package to your project."]})}),"\n",(0,o.jsx)(s.h2,{id:"send-messages-using-light-push",children:"Send messages using light push"}),"\n",(0,o.jsxs)(s.p,{children:["To send messages over the Waku Network using the ",(0,o.jsx)(s.code,{children:"Light Push"})," protocol, create a new message object and use the ",(0,o.jsx)(s.code,{children:"lightPush.send()"})," function:"]}),"\n",(0,o.jsx)(s.pre,{children:(0,o.jsx)(s.code,{className:"language-js",children:'// Create a new message object\nconst protoMessage = DataPacket.create({\n  timestamp: Date.now(),\n  sender: "Alice",\n  message: "Hello, World!",\n});\n\n// Serialise the message using Protobuf\nconst serialisedMessage = DataPacket.encode(protoMessage).finish();\n\n// Send the message using Light Push\nawait node.lightPush.send(encoder, {\n  payload: serialisedMessage,\n});\n'})}),"\n",(0,o.jsx)(s.h2,{id:"receive-messages-using-filter",children:"Receive messages using filter"}),"\n",(0,o.jsxs)(s.p,{children:["To receive messages using the ",(0,o.jsx)(s.code,{children:"Filter"})," protocol, create a callback function for message processing, then use the ",(0,o.jsx)(s.code,{children:"filter.subscribe()"})," function to subscribe to a ",(0,o.jsx)(s.code,{children:"content topic"}),":"]}),"\n",(0,o.jsx)(s.pre,{children:(0,o.jsx)(s.code,{className:"language-js",children:"// Create the callback function\nconst callback = (wakuMessage) => {\n  // Check if there is a payload on the message\n  if (!wakuMessage.payload) return;\n  // Render the messageObj as desired in your application\n  const messageObj = DataPacket.decode(wakuMessage.payload);\n  console.log(messageObj);\n};\n\n// Create a Filter subscription\nconst { error, subscription } = await node.filter.createSubscription({ contentTopics: [contentTopic] });\n\nif (error) {\n    // handle errors if happens\n    throw Error(error);\n}\n\n// Subscribe to content topics and process new messages\nawait subscription.subscribe([decoder], callback);\n"})}),"\n",(0,o.jsxs)(s.p,{children:["The ",(0,o.jsx)(s.code,{children:"pubsubTopicShardInfo"})," parameter allows you to configure a different network configuration for your ",(0,o.jsx)(s.code,{children:"Filter"})," subscription:"]}),"\n",(0,o.jsx)(s.pre,{children:(0,o.jsx)(s.code,{className:"language-js",children:"// Create the network config\nconst networkConfig = { clusterId: 3, shards: [1, 2] };\n\n// Create Filter subscription with custom network config\nconst subscription = await node.filter.createSubscription(networkConfig);\n"})}),"\n",(0,o.jsxs)(s.p,{children:["You can use the ",(0,o.jsx)(s.code,{children:"subscription.unsubscribe()"})," function to stop receiving messages from a content topic:"]}),"\n",(0,o.jsx)(s.pre,{children:(0,o.jsx)(s.code,{className:"language-js",children:"await subscription.unsubscribe([contentTopic]);\n"})}),"\n",(0,o.jsx)(s.admonition,{title:"Congratulations!",type:"tip",children:(0,o.jsxs)(s.p,{children:["You have successfully sent and received messages over the Waku Network using the ",(0,o.jsx)(s.code,{children:"Light Push"})," and ",(0,o.jsx)(s.code,{children:"Filter"})," protocols. Have a look at the ",(0,o.jsx)(s.a,{href:"https://github.com/waku-org/js-waku-examples/tree/master/examples/light-js",children:"light-js"})," and ",(0,o.jsx)(s.a,{href:"https://github.com/waku-org/js-waku-examples/tree/master/examples/light-chat",children:"light-chat"})," examples for working demos."]})})]})}function h(e={}){const{wrapper:s}={...(0,r.R)(),...e.components};return s?(0,o.jsx)(s,{...e,children:(0,o.jsx)(l,{...e})}):l(e)}}}]);