chore(js-waku)!: update API for NetworkConfig (#193)

* intro * update js-waku docs * update shard instructions Co-authored-by: Sasha <[email protected]> * remove chat references in message structure * add info on contentTopics parameter * chore: update guide for v0.027 * chore: prioritize autosharding over static sharding * chore: update cspell for autosharding --------- Co-authored-by: Sasha <[email protected]> Co-authored-by: Danish Arora <[email protected]>
waku-org · Oct 1, 2024 · 7e81fdc · 7e81fdc
1 parent c5d1838
commit 7e81fdc
Show file tree

Hide file tree

Showing 3 changed files with 78 additions and 28 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -17,6 +17,7 @@
     "enrtree",
     "Discv5",
     "gossipsub",
+    "autosharding",
     "lightpush",
     "pubtopic1",
     "proto",

diff --git a/docs/guides/js-waku/light-send-receive.md b/docs/guides/js-waku/light-send-receive.md
@@ -24,6 +24,34 @@ await node.start();
 When the `defaultBootstrap` parameter is set to `true`, your node will be bootstrapped using the [default bootstrap method](/guides/js-waku/configure-discovery#default-bootstrap-method). Have a look at the [Bootstrap Nodes and Discover Peers](/guides/js-waku/configure-discovery) guide to learn more methods to bootstrap nodes.
 :::
 
+A node needs to know how to route messages. By default, it will use The Waku Network configuration (`{ clusterId: 1, shards: [0,1,2,3,4,5,6,7] }`). For most applications, it's recommended to use autosharding:
+
+```js
+// Create node with auto sharding (recommended)
+const node = await createLightNode({
+  defaultBootstrap: true,
+  networkConfig: {
+    clusterId: 1,
+    contentTopics: ["/my-app/1/notifications/proto"],
+  },
+});
+```
+
+### Alternative network configuration
+
+If your project requires a specific network configuration, you can use static sharding:
+
+```js
+// Create node with static sharding
+const node = await createLightNode({
+  defaultBootstrap: true,
+  networkConfig: {
+    clusterId: 1,
+    shards: [0, 1, 2, 3],
+  },
+});
+```
+
 ## Connect to remote peers
 
 Use the `waitForRemotePeer()` function to wait for the node to connect with peers on the Waku Network:
@@ -41,15 +69,12 @@ The `protocols` parameter allows you to specify the [protocols](/learn/concepts/
 import { waitForRemotePeer, Protocols } from "@waku/sdk";
 
 // Wait for peer connections with specific protocols
-await waitForRemotePeer(node, [
-	Protocols.LightPush,
-	Protocols.Filter,
-]);
+await waitForRemotePeer(node, [Protocols.LightPush, Protocols.Filter]);
 ```
 
 ## Choose a content topic
 
-[Choose a content topic](/learn/concepts/content-topics) for your application and create a message `encoder` and `decoder`:
+Choose a [content topic](/learn/concepts/content-topics) for your application and create a message `encoder` and `decoder`:
 
 ```js
 import { createEncoder, createDecoder } from "@waku/sdk";
@@ -66,11 +91,25 @@ The `ephemeral` parameter allows you to specify whether messages should **NOT**
 
 ```js
 const encoder = createEncoder({
-	contentTopic: contentTopic, // message content topic
-	ephemeral: true, // allows messages NOT be stored on the network
+  contentTopic: contentTopic, // message content topic
+  ephemeral: true, // allows messages NOT be stored on the network
 });
 ```
 
+The `pubsubTopicShardInfo` parameter allows you to configure a different network configuration for your `encoder` and `decoder`:
+
+```js
+// Create the network config
+const networkConfig = { clusterId: 3, shards: [1, 2] };
+
+// Create encoder and decoder with custom network config
+const encoder = createEncoder({
+  contentTopic: contentTopic,
+  pubsubTopicShardInfo: networkConfig,
+});
+const decoder = createDecoder(contentTopic, networkConfig);
+```
+
 :::info
 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.
 :::
@@ -83,10 +122,10 @@ Create your application's message structure using [Protobuf's valid message](htt
 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"));
+const DataPacket = new protobuf.Type("DataPacket")
+  .add(new protobuf.Field("timestamp", 1, "uint64"))
+  .add(new protobuf.Field("sender", 2, "string"))
+  .add(new protobuf.Field("message", 3, "string"));
 ```
 
 :::info
@@ -99,18 +138,18 @@ To send messages over the Waku Network using the `Light Push` protocol, create a
 
 ```js
 // Create a new message object
-const protoMessage = ChatMessage.create({
-    timestamp: Date.now(),
-    sender: "Alice",
-    message: "Hello, World!",
+const protoMessage = DataPacket.create({
+  timestamp: Date.now(),
+  sender: "Alice",
+  message: "Hello, World!",
 });
 
 // Serialise the message using Protobuf
-const serialisedMessage = ChatMessage.encode(protoMessage).finish();
+const serialisedMessage = DataPacket.encode(protoMessage).finish();
 
 // Send the message using Light Push
 await node.lightPush.send(encoder, {
-    payload: serialisedMessage,
+  payload: serialisedMessage,
 });
 ```
 
@@ -121,11 +160,11 @@ To receive messages using the `Filter` protocol, create a callback function for
 ```js
 // 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);
+  // Check if there is a payload on the message
+  if (!wakuMessage.payload) return;
+  // Render the messageObj as desired in your application
+  const messageObj = DataPacket.decode(wakuMessage.payload);
+  console.log(messageObj);
 };
 
 // Create a Filter subscription
@@ -140,6 +179,16 @@ if (error) {
 await subscription.subscribe([decoder], callback);
 ```
 
+The `pubsubTopicShardInfo` parameter allows you to configure a different network configuration for your `Filter` subscription:
+
+```js
+// Create the network config
+const networkConfig = { clusterId: 3, shards: [1, 2] };
+
+// Create Filter subscription with custom network config
+const subscription = await node.filter.createSubscription(networkConfig);
+```
+
 You can use the `subscription.unsubscribe()` function to stop receiving messages from a content topic:
 
 ```js

diff --git a/docs/guides/js-waku/use-waku-react.md b/docs/guides/js-waku/use-waku-react.md
@@ -118,7 +118,7 @@ function App() {
 	const decoder = createDecoder(contentTopic);
 
 	// Create a message structure using Protobuf
-	const ChatMessage = new protobuf.Type("ChatMessage")
+	const DataPacket = new protobuf.Type("DataPacket")
 		.add(new protobuf.Field("timestamp", 1, "uint64"))
 		.add(new protobuf.Field("message", 2, "string"));
 
@@ -223,13 +223,13 @@ function App() {
 
 		// Create a new message object
 		const timestamp = Date.now();
-		const protoMessage = ChatMessage.create({
+		const protoMessage = DataPacket.create({
 			timestamp: timestamp,
 			message: inputMessage
 		});
 
 		// Serialise the message and push to the network
-		const payload = ChatMessage.encode(protoMessage).finish();
+		const payload = DataPacket.encode(protoMessage).finish();
 		const { recipients, errors } = await push({ payload, timestamp });
 
 		// Check for errors
@@ -258,7 +258,7 @@ function App() {
 	useEffect(() => {
 		setMessages(filterMessages.map((wakuMessage) => {
 			if (!wakuMessage.payload) return;
-			return ChatMessage.decode(wakuMessage.payload);
+			return DataPacket.decode(wakuMessage.payload);
 		}));
 	}, [filterMessages]);
 }
@@ -283,7 +283,7 @@ function App() {
 		const allMessages = storeMessages.concat(filterMessages);
 		setMessages(allMessages.map((wakuMessage) => {
 			if (!wakuMessage.payload) return;
-			return ChatMessage.decode(wakuMessage.payload);
+			return DataPacket.decode(wakuMessage.payload);
 		}));
 	}, [filterMessages, storeMessages]);
 }
@@ -295,4 +295,4 @@ To explore the available Store query options, have a look at the [Retrieve Messa
 
 :::tip
 You have successfully integrated `@waku/sdk` into a React application using the `@waku/react` package. Have a look at the [web-chat](https://github.com/waku-org/js-waku-examples/tree/master/examples/web-chat) example for a working demo and the [Building a Tic-Tac-Toe Game with Waku](https://blog.waku.org/tictactoe-tutorial) tutorial to learn more.
-:::
+:::