Relay Protocol Versioning and Network Upgrades

The WalletConnect relay protocol operates as the message-passing backbone for the entire protocol suite, enabling wallets and dapps to exchange session_proposal, session_request, and notification payloads. Its evolution is governed by a strict versioning scheme that decouples the relay's internal network operations from the higher-level Sign, Auth, and Push APIs. When a relay upgrade is activated, it typically modifies the underlying GossipSub mesh parameters, subscription management logic, or message store behavior. These changes are designed to be backward-compatible at the wire level, meaning a wallet running an older @walletconnect/relay-client can still publish and subscribe to messages on a network that has adopted a newer relay specification, provided the client adheres to the minimum supported protocol version.

The primary mechanism for network upgrades is the introduction of a new relay protocol version string, negotiated during the initial WebSocket connection to a relay node. A client announces its supported versions, and the relay server selects the highest mutually supported version. This handshake allows the network to operate with multiple active protocol versions simultaneously, creating a migration window where upgraded nodes coexist with legacy clients. A breaking change in message serialization, topic hashing, or subscription filtering would necessitate a new major version, while optimizations to GossipSub peer scoring or TTL management can be shipped as minor version bumps. Wallet developers and dapp operators must monitor the RELAY_PROTOCOL_VERSION constant in the official SDKs and ensure their infrastructure is updated before a deprecated version is fully removed from the bootstrap nodes.

The operational impact of a relay upgrade is concentrated on infrastructure operators running self-hosted relay nodes and on wallet SDK integration cycles. When a new relay version is activated, the WalletConnect Foundation coordinates a phased rollout: first to the official public relay infrastructure, then publishing updated SDK releases that default to the new version. Teams operating private relay clusters must plan their own upgrade windows to match the network's minimum supported version, or risk their users being unable to establish connections. Chainscore Labs assists protocol architects and infrastructure teams in reviewing relay upgrade specifications, assessing the compatibility of custom relay implementations, and planning migration strategies that prevent service disruption during version transitions.

The WalletConnect relay protocol enforces a strict semantic versioning contract for its irn (Inbox Relay Network) wire protocol. A major version bump signals a hard break in message serialization or subscription management that is not backward compatible. Minor and patch versions, however, guarantee wire-level compatibility, allowing nodes running different minor versions to coexist in the same GossipSub mesh. This design is the primary mechanism that enables network-wide upgrades to roll out without forcing a coordinated flag day or breaking active sessions between wallets and dapps.

The relay network's GossipSub topology is sharded by topic, where each topic corresponds to a specific protocol application (e.g., Sign, Chat, Push) and its active version. When a new minor version of a protocol is deployed, relay nodes begin subscribing to the new topic while maintaining their subscription to the old one. This creates a transient dual-topic period where messages published on either topic are propagated. The topic string itself encodes the protocol name and version, making the routing rules explicit and machine-readable. A node that has not yet upgraded simply ignores the new topic, preserving its ability to serve legacy clients until it is ready to cut over.

For operators and SDK integrators, the operational consequence is that relay upgrades are not atomic network events but gradual topology shifts. Monitoring the subscription count and message volume on both the old and new topics provides a leading indicator of ecosystem adoption. A premature deprecation of the old topic by a wallet or dapp before its counterparties have migrated will result in silent message delivery failures. Teams managing their own relay infrastructure should treat topic lifecycle management as a critical operational procedure, distinct from application-layer SDK updates. Chainscore Labs can assist infrastructure operators in designing monitoring for topic migration health and validating that their upgrade rollout does not partition their user base.