Lightpush in Waku: Trading CPU for Bandwidth on Sparse Pubsub Topics

If you run a Waku node on a phone or a metered connection, the default relay behavior feels like paying a bandwidth tax for conversations you never join. Every message on a shared pubsub topic gets forwarded by your node whether or not you care about it. Lightpush changes that by letting peers advertise which topics they actually want and filtering at each hop. The payoff is lower relayed bytes; the cost is extra CPU per message and a real risk of silent message loss if filters are wrong.

Why plain relay wastes bytes on sparse topics

Waku builds on libp2p's pubsub, and the default relay behavior resembles floodsub: a message published to a topic is forwarded by peers that maintain the mesh for that topic, regardless of whether the forwarding node has any interest in the content. In a network with many active topics but low per-topic density—what developers call topic sparsity—most forwarded bytes are irrelevant to the node doing the relaying. A mobile client relaying messages for a topic it never reads is the canonical example.

How Lightpush narrows the forwarding path

Lightpush keeps floodsub for topic discovery and mesh maintenance, but adds a filtering layer at each hop. Peers advertise interest in specific content topics, and a forwarding node only passes messages that match a neighbor's advertised interests. To keep memory bounded and avoid re-forwarding the same payload, implementations use a sliding window cache: a fixed-size buffer of recently seen message identifiers that is checked before a message is relayed again.

Aspect	Plain floodsub relay	Lightpush
Forwarding rule	Relay all messages on subscribed topics	Relay only messages matching a neighbor's advertised interests
Topic discovery	floodsub mesh	floodsub mesh plus per-hop Lightpush filters
Duplicate protection	Basic deduplication	Sliding window cache per peer
Bandwidth profile	High when topic sparsity is high	Lower relayed bytes on sparse topics
CPU profile	Lower per message	Higher per message due to filter evaluation

Worked example: comparing relay bytes locally

The fastest way to understand the trade-off is to run a node both ways and compare counters. The commands below assume you have cloned the Waku repository and built the binaries. Because Waku evolves quickly, treat the flag names and file paths as illustrative and verify them against your checkout.

Where to run: a local shell on a development machine or CI runner with the Go toolchain installed.
Permissions: standard user access; no elevated privileges are required for a local test node.
Placeholders: replace <repo-dir> with your clone path and <metrics-port> with an unused local port.

# Clone and inspect the filter logic
git clone https://github.com/waku-org/waku-v2.git <repo-dir>
cd <repo-dir>
less relay/lightpush.go

Start a node with Lightpush enabled and expose metrics:

# Run from the repository root or build output directory
./build/waku --lightpush --metrics-address 127.0.0.1 --metrics-port <metrics-port>

In a second terminal, poll the metrics endpoint:

curl http://127.0.0.1:<metrics-port>/metrics

Expected checks: the metrics output should include topic-specific counters. Note the relay byte totals, then restart the node without --lightpush and compare. The repository also includes a benchmarking tool; the research notes reference waku-bench for this purpose:

# Compare relay byte counts with and without Lightpush
./build/waku-bench --lightpush --duration 60s
./build/waku-bench --duration 60s

Relevant risks: enabling Lightpush changes forwarding behavior. If your node previously acted as a generic relay for topics outside your own interest set, it will stop forwarding them. On very constrained devices, the per-message filter evaluation can increase latency. To revert, disable the flag and restart the node.

The CPU and configuration trade-off

Lightpush is not free. Every message now requires filter evaluation before forwarding. On a Raspberry Pi or low-end phone, that CPU cost may matter. More importantly, the filter is a configuration surface: if you exclude a topic you actually need, messages are dropped. Unlike a subscription error in application code, this loss happens at the network layer and can be silent. Development benchmarks from the Waku testnet have reported reductions around 40% in relayed bytes compared with plain floodsub when topic sparsity is high, but those gains only materialize if your filter set matches your real traffic.

Before you enable it in production

Run Lightpush alongside your current relay setup for one traffic cycle. Compare the relay byte counters, confirm your critical topics are present in the filter set, and measure CPU on your target hardware. If the byte savings do not offset the operational risk of misconfiguration, plain relay may still be the safer default.