Using Waku Relay with Lightpush for Bandwidth‑Efficient Message Delivery in Mobile dApps

Quick answer

Enable Lightpush on a Waku Relay node so the client announces its interest in a content topic. The relay then stores incoming messages and forwards only those that match the announced interest, cutting bandwidth for devices that connect sporadically.

How Lightpush works with Waku Relay

Waku Relay builds on libp2p’s pubsub layer. A full‑mesh subscription would cause every peer to receive all messages on a topic, which is wasteful for mobile apps that may be offline or on metered connections. Lightpush changes this pattern:

1. The client creates a Relay node and calls enableLightpush(). This sends a lightweight announcement to peers, listing the content topics it cares about.
2. Peers that store messages (the Relay nodes) keep those messages for a configurable retention window (default 1 hour). When a Lightpush announcement arrives, they check the stored buffer and forward any matching messages.
3. If the client reconnects after being offline, it receives the buffered messages that arrived while it was away, provided they are still within the retention window.

Worked configuration and code example (Node.js)

The example below shows a minimal setup using the official @waku/sdk package. Replace the placeholders with your own values.

const { Waku } = require('@waku/sdk');

async function startLightpushNode() {
  // 1️⃣ Create a Relay node (default uses WebSocket transport)
  const waku = await Waku.create();

  // 2️⃣ Enable Lightpush – announce interest in a content topic
  await waku.lightpush.enable();
  const contentTopic = '/my-app/1/chat/proto'; // example content topic
  await waku.lightpush.addContentTopic(contentTopic);

  // 3️⃣ Subscribe to receive messages that match the topic
  waku.filter.subscribeContentTopic(contentTopic, (envelope) => {
    const payload = new TextDecoder().decode(envelope.payload);
    console.log('Received message:', payload);
  });

  // 4️⃣ Publish a test message (optional, for local verification)
  const encoder = new TextEncoder();
  const msgEnv = waku.message.create(encoder.encode('Hello Lightpush!'), contentTopic);
  await waku.message.publish(msgEnv);

  return waku;
}

// Run the node
startLightpushNode().catch(console.error);

Where to run: any Node.js environment with network access (local machine, CI, or a mobile‑compatible bundle via tools like Browserify or Webpack). Required permissions: ordinary user; no elevated privileges are needed. Expected checks: after the node starts, logs should contain lines similar to "lightpush announcement sent" and later "message forwarded" when a peer publishes to the same topic. Risks: if the node cannot reach any peers, announcements are dropped and no messages will be forwarded.

Limits and practical considerations

• Message size – Waku Relay enforces a maximum payload of ~64 KiB. Larger data must be split or stored off‑chain.
• Retention window – Messages are kept only for the configured store duration (default 1 hour). If a Lightpush client stays offline longer than this window, the message is lost unless you run a dedicated mailstore or rely on a peer with longer retention.
• Peer health – Store‑and‑forward depends on at least one Relay node that has received the message and is reachable when the client returns. Unstable peer connectivity can cause gaps.
• Key material for private topics** – When using symmetric‑key encrypted content topics, all interested parties must share the same key. Mis‑managed keys lead to undecryptable messages.

Common mistakes and how to avoid them

• Over‑broad topic filters – Adding a wildcard or overly generic content topic causes the relay to forward every message, negating Lightpush’s bandwidth benefit. Test with a known test vector (e.g., publish a message to a unique topic and verify only that topic triggers delivery).
• Forgetting to re‑add topics after a restart** – Lightpush state is not persisted automatically. After a process restart, call addContentTopic again for each topic you need.
• Assuming instant delivery** – Lightpush is pull‑based; there is a delay proportional to the gossip propagation and the store interval. Measure end‑to‑end latency in your target network before assuming real‑time behavior.
• Ignoring bandwidth measurements** – Even with Lightpush, a misbehaving peer can flood you with unrelated messages if it forwards incorrectly. Use a tool like iftop or nethogs on the device interface to confirm that traffic drops when Lightpush is enabled versus a full‑mesh subscription.

Verification checklist (do not claim execution)

1. Start two local Waku nodes with the SDK.
2. On node A, enable Lightpush and add a content topic.
3. On node B, publish a JSON envelope to that same topic.
4. Disconnect node A for a period shorter than the retention window, then reconnect.
5. Check node A’s logs for a "lightpush announcement" entry and later a "message forwarded" entry.
6. Confirm the payload appears in node A’s subscription handler.
7. Optionally, run a bandwidth monitor and compare traffic with a full‑mesh subscription on the same topic.