Reducing Gossip Noise with Waku v2 Light Push

In a decentralized pub/sub network, the "gossip flood" is a common bottleneck. When every subscriber receives every message on a topic—including those they don't need—bandwidth is wasted, latency increases, and mobile device batteries drain rapidly. Waku v2 addresses this with Light Push, a mechanism that allows subscribers to attach filters to their subscriptions so only relevant messages are delivered.

The Overhead of Waku v1

Waku v1 relied heavily on long-polling or unrestricted gossip. If your application subscribed to a general topic like #updates, you received every single envelope propagated through that channel, regardless of the specific content. The application layer had to discard irrelevant messages after they had already traversed the network and consumed data. This "blind delivery" makes scaling decentralized notifications difficult, especially for clients on constrained networks.

How Light Push Optimizes Delivery

Light Push shifts the filtering logic closer to the network edge. It leverages libp2p GossipSub for initial topic routing but introduces a filtering layer using Bloom filters—probabilistic data structures used to test whether an element is a member of a set.

When a subscriber initiates a connection, they provide a topic filter. The network uses this filter to ensure that only envelopes matching the criteria are forwarded to the subscriber. This prevents the relay from flooding the client with noise, significantly reducing the energy cost of parsing unwanted payloads on the device.

Implementing Light Push in Go

To use Light Push, you must use a Waku v2 compatible library. The following example demonstrates how to subscribe to a topic with a specific filter using the Go implementation.

package main

import (
	"context"
	"log"
	"github.com/waku-org/go-waku/waku"
)

func main() {
	ctx := context.Background()
	// Initialize node with a local listen address
	node, err := waku.New(ctx, waku.WithListenAddr("/ip4/0.0.0.0/tcp/0"))
	if err != nil {
		log.Fatalf("failed to start waku node: %v", err)
	}

	// Define the topic and the Bloom filter string
	topic := "demo-chat"
	filter := "matching-keywords-hash" // Must follow Waku envelope spec format

	// Subscribe using the WithLightPush option
	subscription, err := node.Subscribe(ctx, topic, waku.WithLightPush(filter))
	if err != nil {
		log.Fatalf("failed to subscribe: %v", err)
	}

	for msg := range subscription.Chan() {
		log.Printf("Received filtered message: %s", msg.Payload)
	}
}

Execution and Verification

• Environment: Run this on a system with Go 1.21+ and the github.com/waku-org/go-waku module.
• Permissions: Ensure the process has outbound network access to Waku relays (typically ports 9000-9090).
• Placeholders: Replace "matching-keywords-hash" with a valid Bloom filter string derived from the Waku envelope specification.
• Verification: To verify the result, subscribe to a high-traffic topic with and without the WithLightPush option. Compare the number of envelopes received per minute; a successful implementation will show a significant drop in irrelevant messages.

Trade-offs and Limitations

Light Push is a powerful optimization, but it introduces specific engineering trade-offs:

• Version Mismatch: Waku v1 and v2 are not directly compatible. Migrating to Light Push requires updating both the client logic and the topic naming schemes.
• Relay Dependency: Light Push is an extension. If a relay node operator has not configured their node to support the Light Push extension, the filter request is ignored, and the client reverts to receiving all gossip for that topic.
• Bloom Filter False Positives: Because Bloom filters are probabilistic, there is a small chance a message that does not match the filter will still be delivered.

Actionable Migration Path

If you are moving from a v1 architecture to v2 to leverage Light Push, follow these steps:

1. Verify Support: Run the version command for your client library (Go, JS, or Rust) to ensure the LightPush or Filter flag is available.
2. Audit Relays: Check that your primary relay nodes are running Waku v2 and have the necessary extensions enabled.
3. Implement Filters: Replace generic subscriptions with filtered subscriptions and monitor the filter field in the Envelope message format to ensure it aligns with your library's expectations.