Topic Versioning vs. In-Place Schema Updates for Waku v2 Payloads

Message Schema Evolution in Waku v2

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.

Design Trade-offs

Two primary strategies exist for managing these transitions:

• Topic Versioning: Embedding version strings (e.g., /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.
• In-Place Updates: Maintaining a single topic and relying on Protobuf's backward compatibility rules. This preserves a unified audience but risks runtime errors in SDKs if field types are modified or if old peers cannot handle new required logic.

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.

Technical Uncertainty

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?