Waku v2 Topic‑Based Pub/Sub: Routing, Encryption, and Storage

When deploying Waku v2, the topic‑based pub/sub model can cut bandwidth and improve privacy, but it requires careful tuning of history size and encryption. This guide walks through the key trade‑offs, a concrete node configuration, and how to verify the setup.

Why Topic‑Based Pub/Sub Matters in Waku v2

Waku v2 replaces the flat inbox model with a content‑topic system. Each message is tagged with a topic hash, and nodes only forward messages that match a subscriber’s hash. This selective routing cuts bandwidth, lowers message overhead, and makes the network more scalable.

Key Decision Points

Topic Hash Selection – Pick a deterministic hash (e.g., SHA‑256 of a human‑readable string) so that all participants use the same topic.
End‑to‑End Encryption – Optional Noise protocol patterns let you encrypt the payload while leaving the topic hash visible for routing.
Relay History Size – Configure historyLength to control how many past messages a relay keeps. Larger windows improve catch‑up but increase storage.
Message Size Limits – The maxMessageSize flag protects relays from oversized packets that could be used for denial‑of‑service.

Concrete Example: Running a Relay with Topic Filtering and Encryption

Below is a minimal configuration for a Waku v2 relay that accepts messages on the topic "myapp/updates", stores the last 500 messages, and enforces a 1 MiB size limit. End‑to‑end encryption is enabled using the Noise X25519_ChaChaPoly_SHA256 pattern.

# waku‑relay --topic myapp/updates \
  --history-length 500 \
  --max-message-size 1048576 \
  --encryption-noise X25519_ChaChaPoly_SHA256 \
  --listen-addr /ip4/0.0.0.0/tcp/9000

Run the command as a user with network permissions (e.g., root or a dedicated service account). The relay will bind to TCP 9000 and accept inbound connections from peers that also advertise the same topic.

Verifying Topic Routing

Start a publisher:

waku‑publish --topic myapp/updates --message "Hello, world!"

Start a subscriber on a separate terminal:
```
waku‑subscribe --topic myapp/updates
```
Only the subscriber should display the “Hello, world!” message. If you subscribe to a different hash (e.g., myapp/other), no message will be received.

Checking Encryption Status

When the publisher uses the --encrypt flag with the recipient’s public key, the payload is encrypted. The subscriber must provide the matching private key to decrypt. Use waku‑keys to generate a key pair:

waku‑keys generate

Store the private key securely; the public key is shared with the publisher. If encryption is misconfigured, the subscriber will print an error and the message will be discarded.

Trade‑offs and Limitations

Storage vs. Catch‑up – A history of 500 messages is a common starting point, but if your application needs to replay longer backlogs, increase the value. Remember that each message can be up to 1 MiB, so storage grows linearly.
Latency on Constrained Devices – The Noise handshake adds a few milliseconds of overhead. For high‑frequency telemetry (hundreds of messages per second), test the impact on your target hardware.
Denial‑of‑Service Risk – Without a maxMessageSize guard, a malicious actor could flood the relay with huge packets, exhausting memory. Always set a sensible limit.
Topic Collision – Two unrelated services using the same topic hash will share bandwidth. Use a namespace prefix (e.g., app1/updates) to avoid accidental overlap.

Practical Checklist Before Production

Define a clear topic namespace and document the hash derivation.
Generate and securely distribute key pairs if end‑to‑end encryption is required.
Choose a historyLength that balances storage cost and required replay capability.
Set maxMessageSize based on the largest payload you expect.
Run a stress test: publish bursts of messages and monitor CPU, memory, and network usage on the relay.
Verify that subscribers only receive messages for their subscribed topics and that encrypted payloads decrypt correctly.

Closing Thoughts

Waku v2’s topic‑based pub/sub gives you fine‑grained control over what traffic flows through the network, and optional end‑to‑end encryption preserves privacy without breaking routing. The key to a successful deployment is careful tuning of history size, message limits, and encryption settings to match your application’s bandwidth and security profile. Start small, validate with the verification steps above, and scale the relay configuration as your user base grows.

Aligning Topic Hashes and Managing Relay Storage

When configuring a Waku v2 relay, ensure the topic string used for hashing is identical across publisher, subscriber and relay; any extra space, case change or encoding variation creates a different hash and breaks routing.

Use a deterministic namespace prefix (e.g., app1/updates) and document the exact string that will be hashed.
Set historyLength based on expected replay needs while keeping in mind that encrypted payloads increase storage consumption linearly.
Apply maxMessageSize to prevent denial‑of‑service attacks and to avoid rejecting legitimate large messages.

Verification can be done by publishing a message with the exact topic and confirming only a subscriber using the same hash receives it; inspect relay logs for "topic hash mismatch" warnings to catch inconsistencies early.

Choosing Topic‑Based Pub/Sub in Waku v2: A Practical Guide to Routing, Encryption, and Storage Settings