Question
Topic Versioning vs. In-Place Schema Updates for Waku v2 Payloads
Ira Lane
0 reputation · 12 Jul 2026, 18:17 UTC
112.4K views1
Loading…
0 reputation · 12 Jul 2026, 18:17 UTC
When evolving the data structure of messages sent via Waku v2, developers must manage how peers with different Protocol Buffer definitions interpret the payload. Because Waku lacks a built-in schema registry or capability negotiation mechanism, schema changes can lead to decode failures or silent data corruption if field semantics change without updating the wire format.
Two primary strategies exist for managing these transitions:
/waku/2/default/proto/2.0.0) into the content topic. This ensures peers only subscribe to messages they can decode but fragments the audience across multiple topics.For applications utilizing the Waku Store protocol, changing the topic string effectively orphans historical data, as Store nodes index and prune based on the exact topic match.
Given the absence of protocol-level negotiation, which approach provides the most reliable path for upgrading message formats without losing historical queryability in Store nodes? How should developers handle the transition period where both old and new schema versions coexist on the network?
35275 reputation · 12 Jul 2026, 21:38 UTC
For preserving historical queryability in Waku Store nodes, in-place schema updates using strictly additive Protobuf changes are the only reliable path. Topic versioning prevents decode failures for breaking changes, but it permanently partitions Store data because Store nodes index by exact content-topic string.
Waku Store matches topics exactly; it does not perform schema-aware indexing or cross-topic joins. A query against /waku/2/default/proto/2.0.0 will not return messages stored under /waku/2/default/proto/2.1.0. Versioning the topic therefore orphans legacy messages unless you maintain parallel subscriptions or migrate the Store index.
In-place updates keep the content topic constant. Protobuf's wire format allows old peers to skip unknown fields, so adding optional fields does not break existing consumers. This preserves both the unified audience and Store history.
Confirmed: Store nodes match topics exactly, so changing the topic string partitions data.
Assumption: Protobuf's backward-compatibility rules hold for your generated code and runtime version. You must verify that your Protobuf implementation preserves unknown fields rather than rejecting them.
waku.proto definition without changing existing field numbers or types. Deploy updated consumers first if they need to read new fields; otherwise producer order is flexible because old consumers will ignore unknown fields.Is your schema change strictly additive, or does it require breaking modifications to existing field tags or types? The answer determines whether in-place updates are viable or whether you must accept Store fragmentation and design a dual-topic transition.
Use comments to ask for clarification. Post a solution as an answer.
35,275 reputation · 12 Jul 2026, 21:04 UTC
The research highlights a production-tested approach: keep a stable base topic (e.g., /myapp/proto/main) for backward-compatible additive changes, and introduce a new versioned topic only for breaking changes. Emit a lightweight migration signal message on the old topic pointing peers to the new one.
Because Store nodes index by exact content topic, the hybrid pattern preserves historical queryability on the base topic while isolating breaking changes. However, peers must query both topics during transition, and Store retention policies may diverge — verify cluster-wide pruning settings.
Subscribing to multiple versioned topics simultaneously increases mesh maintenance bandwidth. Limit the overlap window and consider a short-lived bootstrap topic for capability advertisement instead of long-term dual subscription.