Waku Relay TTL & History Guide

Configure Waku relay TTL and buffer size, fetch historical messages without persistent peers, and avoid misconfigurations that cause data loss or cache flooding.

Configuring Waku Relay TTL for Message History

When subscribers join a Waku topic after a message was published, missing it is a real risk if peers go offline. Waku relay nodes address this by caching messages in an in‑memory buffer with a time‑to‑live (TTL) value, enabling on‑demand history retrieval without a permanent peer connection.

Useful takeaway

Set waku.relay.ttl to a window that covers your expected subscription lag, and adjust waku.relay.buffer.size to fit your message volume. The relay will keep messages within that TTL, and subscribers can fetch them via the relay endpoint.

How relay buffering works

Relay nodes subscribe to a libp2p topic pubsub mesh. Incoming messages are stored in a buffer sized by waku.relay.buffer.size. Each message carries a TTL (seconds) that the relay uses to expire entries. A gossip subprotocol propagates messages across the mesh, so even when the original publisher disconnects, other relays may still hold a copy within the retention window.

{\"waku\": {\"relay\": {\"ttl\": 3600, \"buffer\": {\"size\": 1000 } } } }

Waku v4 versus v5 retention behavior

Waku v4 treats the TTL as a hard expiration: once the window closes, the message is removed from the relay\'s cache. Waku v5 introduces sliding‑window retention and per‑message provenance tags, allowing more nuanced control over how long history stays available. Upgrading from v4 to v5 may require adjusting your TTL policy to maintain the same availability window.

Common mistakes

Setting the TTL too short causes messages to vanish before downstream subscribers receive them.
Exposing the relay without authentication lets adversarial nodes flood the cache, degrading performance.
Running the relay on a firewalled or NAT‑restricted node means it won\'t forward messages, making the feature appear broken despite correct configuration.

Verification steps

Publish a test message with a known TTL, then run waku relay fetch --topic <topic> to confirm the message appears in the relay\'s store before expiration. Check the relay\'s status endpoint for TTL counters and buffer occupancy; compare results between Waku v4 and v5 nodes to observe sliding‑window versus hard‑expiration behavior. Ensure the relay\'s multiaddress is reachable in your target network.

Limits and persistent storage

Without configured persistent storage, relay data is lost when the process restarts. Applications that need durable history must enable disk‑backed persistence or integrate an external cache. Additionally, Waku pubsub filtering is best‑effort; complex boolean expressions may be silently dropped, so subscribers should validate message content rather than rely on server‑side filter enforcement.

Waku Relay TTL Configuration, History Fetching, and Common Pitfalls