Waku Content-Topic Routing: Balancing Real-Time Delivery and History

The Problem: Avoiding Network Noise in Decentralized Pub/Sub

In a decentralized network, broadcasting every message to every peer is unsustainable. If you are building a distributed application—such as a decentralized chat or a sensor network—you cannot afford to have every node process every packet. The challenge is creating a system where peers only receive data they have explicitly asked for, without relying on a central broker to manage those subscriptions.

Thesis: Namespaced Routing via Content Topics

Waku v2 solves this by using content-topic routing built on libp2p GossipSub. Instead of addressing messages to specific peer IDs, messages are tagged with a namespaced path. This allows the network to route data based on the interest of the peers rather than their identity. By choosing between relay nodes for speed and store nodes for persistence, developers can tune their application for either real-time updates or historical retrieval.

Structuring Namespaced Content Topics

A content topic in Waku v2 follows a specific hierarchical grammar: /waku/2/<application>/<topic>/<encoding>. This structure serves three critical functions:

• Application Isolation: The <application> segment ensures that different apps using the same Waku network do not clash.
• Stream Identification: The <topic> segment allows a single app to have multiple channels (e.g., /sensors/temp vs /sensors/humidity).
• Serialization Clarity: The <encoding> segment (e.g., json or protobuf) informs the receiving peer how to decode the binary payload.

Because the network routes based on these paths, a peer subscribing to /waku/2/myapp/alerts/json will never receive traffic from /waku/2/myapp/logs/json, significantly reducing bandwidth waste.

Choosing Your Node Role: Relay vs. Store

Waku separates the concerns of propagation and persistence. Depending on your engineering goals, you will deploy nodes in different roles:

Role	Primary Function	Data Lifecycle	Best Use Case
Relay	Forwards messages to subscribers	Ephemeral (Memory)	Real-time notifications, live chat
Store	Indexes and saves messages	Persistent (Disk)	Message history, offline synchronization
Combined	Both forwarding and saving	Hybrid	Full-service infrastructure nodes

Practical Implementation Example

To verify this behavior, you can use the Waku v2 Go implementation. This example assumes you have the Waku binary installed and a config.yaml configured for your local network.

1. Deploy a Relay Node: Run this on a machine with port 4001 open to the network.

   waku --config config.yaml --mode relay --content-topic "/waku/2/demo/weather/json"

   Check: Verify the node logs indicate it is listening for GossipSub traffic on the specified topic.

2. Publish Data: Use a producer node to send a payload.

   waku --config config.yaml --mode producer --content-topic "/waku/2/demo/weather/json" --payload '{"temp": 22.5}'

   Risk: Since GossipSub is best-effort, if no relay is reachable, the message may not propagate.

3. Subscribe and Verify: Run a subscriber node to confirm receipt.

   waku --config config.yaml --mode subscriber --content-topic "/waku/2/demo/weather/json"

   Verification: The subscriber should output the JSON payload immediately upon publication.

4. Retrieve via Store: If a store node is running, query the history for a specific time window.

   waku store query --topic "/waku/2/demo/weather/json" --since 2026-11-12T00:00:00Z

Limitations and Trade-offs

Content-topic routing introduces a fundamental trade-off between visibility and privacy. Because any peer can subscribe to a public topic path, all messages on that topic are visible to all subscribers. For sensitive data, you must implement end-to-end encryption (E2EE) at the application layer before publishing the payload.

Additionally, store nodes are not guaranteed to be permanent archives. Retention policies are managed by the node operator; if a store node prunes data after 24 hours, your application must be designed to handle gaps in historical data. Finally, be aware that API signatures vary between the Go and TypeScript (waku-js) implementations.

Closing Action Plan

To move from a prototype to a production-ready Waku deployment, start by defining a strict content-topic schema for your application. Test your latency by measuring the time between publication and receipt via a relay, and verify your data durability by querying a store node after a relay restart. If your application requires strict ordering or guaranteed delivery, you will need to implement a sequencing layer on top of Waku, as the underlying GossipSub protocol does not provide these guarantees.