Waku Relay architecture note for dApp pub/sub

The problem with dApp messaging on constrained devices

Applications that need real‑time pub/sub over an open network face a trade‑off: full nodes give reliability but are too heavy for browsers and mobile, while centralized relays break censorship resistance. Waku Relay is the practical compromise used for low‑latency message dissemination with intermittent connectivity and optional end‑to‑end encryption.

The useful takeaway is that the smallest viable deployment is a gossip‑based overlay with Lightpush for publishers and Lightpull for retrieval, not a full store‑and‑forward mesh on every client.

Requirements that drive the design

Low‑latency pub/sub for dApps is the primary requirement. Messages should reach interested peers in seconds under normal network conditions.

Tolerance to intermittent connectivity matters because clients run in browsers or on mobile. A node may go offline and reconnect without losing the ability to publish later.

Optional end‑to‑end encryption is required. The network must allow application‑layer encryption so relays do not need to trust payload confidentiality.

Resource constraints mean the design must run on constrained nodes. Light clients should not maintain full gossip mesh state or persistent stores.

Smallest suitable design

Waku v2 Relay implements a gossip overlay on libp2p. The overlay uses a floodsub‑like topic mechanism where peers subscribe to a content topic, e.g., /waku/2/default-waku/proto, and exchange messages via gossip.

The minimal architecture separates three roles:

• Relay nodes maintain the gossip mesh and forward messages to peers subscribed to the same topic.
• Lightpush clients publish without subscribing. They send a message to a relay which then gossips it. This reduces bandwidth and state on constrained devices.
• Lightpull clients retrieve missed messages on demand from a relay or store node, instead of maintaining a continuous subscription.

Persistence is optional and provided by the Waku Store protocol. A store node indexes messages by topic and timestamp and serves historical queries. Real‑time delivery does not depend on store availability.

A concrete minimal configuration for a relay is:

# Run on a server with network access and ability to listen on TCP/UDP
# Requires network bind and outbound libp2p connections
# Risk: exposure to public peer discovery and potential resource exhaustion from spam
go-waku --relay --topics /waku/2/default-waku/proto

A light publisher can use Lightpush to the same topic:

# Run on a constrained client, no subscription needed
# Replace <relay-ip>, <port>, <peer-id> with real values
js-waku lightpush --relay-multiaddr /ip4/<relay-ip>/tcp/<port>/p2p/<peer-id> --topic /waku/2/default-waku/proto

Expected check: the relay logs a received message and peers subscribed to the topic receive it via gossip within a few seconds under normal conditions.

Trust and data boundaries

Nodes trust only their own libp2p peer identity. Peer IDs are derived from public keys, and connections are encrypted at the transport layer by libp2p. If peer‑ID validation or transport encryption is flawed, metadata can leak and Sybil attacks become easier.

Message payload is opaque to relays unless the application does not encrypt. Relays see metadata: topic, timestamp, message ID, and sender peer ID. This metadata is visible to all peers subscribed to the same pubsub topic and to any relay that forwards the message.

Application‑layer encryption must be applied before publishing if payload confidentiality is required. Waku does not provide metadata privacy by default.

Operational checks

Maintain connections with periodic heartbeat pings. libp2p keeps peer liveness via keep‑alive messages; operators should monitor peer count per topic.

Gossip‑score penalizes misbehaving peers. The score decays over time and increases for good behavior such as forwarding valid messages. Monitor metrics exposed by the node for gossip‑score per peer to detect degradation.

Store‑forward acknowledgments, often called store receipts, confirm persistence. If a store is used, a publisher can request a receipt before considering a message durably delivered. Real‑time delivery via gossip is separate from this receipt.

A practical check is to disable store‑forward on a peer, send a message, and verify real‑time delivery still occurs via gossip while the store receipt fails. This demonstrates the separation of immediate delivery and persistence guarantees.

Failure modes

Temporary message loss during network partitions. Gossip relies on mesh connectivity; partitions can delay or drop messages until the mesh reconnects. Recovery occurs via rebroadcast and score decay that allows new peers to join.

Historic message drops when store nodes exhaust capacity. Stores have finite retention. Queries for old messages may return partial results or errors.

Spam injection by malicious peers degrades gossip scores and can increase bandwidth usage. The gossip‑score mechanism eventually penalizes the peer, but transient flooding can still impact latency.

Latency and throughput vary with network size, node resources, and geographic distribution. Results from a single testnet may not generalize to mainnet conditions.

When the design should change

A new requirement for full metadata privacy would necessitate mixing or private relays. Standard Relay exposes topic subscriptions and peer IDs. Private relay or mixnet layers would be needed to hide who talks to whom.

A shift to high‑throughput streaming, such as video, would motivate moving from pure gossip to bandwidth‑reservation circuits or dedicated transport layers. Gossip is optimized for small control messages, not sustained high bandwidth.

If durability becomes a hard requirement, the minimal design must add replicated stores with explicit retention policies and acknowledgment workflows, increasing operational cost.

Limitations to keep in mind: security guarantees rely on correct libp2p encryption and peer‑ID validation; observed latency varies with network conditions; and light clients depend on the honesty and availability of relays they push to.