WalletConnect v2.0: what’s new?
January 26th, 2022

If you follow WalletConnect or me on Twitter, you would’ve seen plenty of teasers on different features and properties of the v2.0 protocol. In this article we will break down every single one of them and the key differences from the previous v1.0 protocol.

The user experience will remain exactly the same yet the new protocol will break interoperability but for very good reasons. Here are the main features of WalletConnect v2.0 protocol introduces:

  • Chain Agnostic Interface
  • Multi-Chain Support
  • Pairing & Session Separation
  • JSON-RPC Permissions
  • Improved Session Management
  • Decentralized Message Relaying

Chain Agnostic Interface

An often discussed, requested and misunderstood topic has been WalletConnect’s support for multiple blockchains. WalletConnect is first and foremost an encrypted communication protocol that only cares about two parties coming to agreement over a session.

However when v1.0 was released it made the assumption that both parties were communicating about any EVM-compatible chain thanks to chainId specified by EIP-155 standard but this meant that other blockchains like Cosmos and Polkadot would be incompatible given that their chains are not identifiable by the same standard.

Hence came the initiative back in 2019 to start CAIPs (Chain Agnostic Improvement Proposals) to provide a common ground for multi-chain applications. These standardize interfaces across different blockchain ecosystems which may not share tooling and infrastructure. CAIPs were developed together with projects on Ethereum, Cosmos, Polkadot, Solana, Near, Filecoin, etc.

Thanks to these newly defined standards that we developed in CAIPs WalletConnect v2.0 was able to expand its support very easily to be chain agnostic. Below you can find some examples of how accounts are specified for different chains.

# Ethereum mainnet
# Bitcoin mainnet
# Cosmos Hub
# Kusama network

Multi-Chain Support

Another drawback of v1.0 is that, just like other current tooling in this space, support for an application to connect to multiple chains simultaneously was missing. It has become normalized that a connection between an app and a wallet assumes a single active chain.

Simultaneous chain connections were long considered on CAIPs discussions prior to WalletConnect v2.0 development which is defined both by the account addresses to be suffixed by the chain identifier and also by the JSON-RPC standard to invoke requests with a target chain.

Thus, this new feature would enable a future where apps can interface with wallets on multiple chains without requiring any synchronization to switch context either automatically by the wallet or the user themselves.

Pairing & Session Separation

Sometimes you need to push forward imperfect solutions to then iterate on problems that your earlier self wasn’t able to predict, for example, a major bottleneck was that WalletConnect v1.0 required a user to scan a QR Code or use a deep link every time they wanted to connect to a new application from their wallet.

Fortunately this is not the case with the v2.0 protocol where pairing and session have been decoupled. The app using the WalletConnect protocol will cache previously paired wallets which it can use to send new session proposals without pairing all over again. This relationship of a pairing will of course not be shared between wallets but it can be shared between applications in the same browser through an iframe.

The most important consideration for the development of this feature was that the pairing is essentially a relationship between clients while sessions are a relationship between app and wallet. Understanding the platform where the client is run is what will constrain the re-use of pairings to propose new sessions between two clients.

JSON-RPC Permissions

The first challenge created by introducing chain agnostic interfaces were the incompatibilities between apps and wallets regarding the JSON-RPC API methods being used in a session. While it solved v1.0 protocol’s assumption that both were using the Ethereum JSON-RPC API it meant they also needed to communicate the API being used. Therefore in v2.0 protocol you are required to specify the JSON-RPC methods upfront when proposing a session. Since the issue being tackled was API compatibility, it was very easy to describe which methods are to be used before session settlement thus it would also need to be approved by the wallet when connecting to an app.

JSON-RPC permissions basically serve two purposes, before and after session settlement. Before session settlement, they describe the API requirements of the app in order for the session to proceed without any errors. That way, the wallet is able to parse if it will be able to support all methods, but also if it approves the use of these methods by the app. After session settlement, the clients will be able to filter out any JSON-RPC requests used on either side which are incompatible with the described set of methods for the session.

A great example of this feature in today’s Ethereum applications supporting WalletConnect is when an experimental method like signing typed data (eth_signTypedData) is required by the app but unsupported by the wallet. In this context, these permissions provide an amazing mechanism to detect support without requiring maintenance of a registry for which wallets support new API methods.

Improved Session Management

Session management has probably been one of the most overlooked aspects of the v1.0 protocol and I personally find to be the biggest game changer for the v2.0 protocol. While it may not be as attractive as multi-chain support for many developers the underlying management of the sessions on the client will be dramatically improved in two areas: explicit expiries and request history.

Explicit expiries simply means that session proposals include a Time to Live (TTL) which is by default set to one week but can be changed as the expiry is calculated on the wallet side after settlement which is then communicated back to the app. This eliminates the current scenario where either apps or wallets manage sessions indefinitely due to one of the parties not communicating its termination. Additionally a mechanism to ping is also included to evaluate if the peer client is currently online or not. While WalletConnect does not require parties to be online for the whole duration of the session, it’s useful for apps to understand whether the wallet is immediately available to sign a request.

Request history is probably the only feature which was never asked before because the v1.0 delegated this responsibility to the server. For v2.0 protocol all clients will have a record of all the JSON-RPC requests made during a session and also which ones have already been responded. This enables a client to protect itself from receiving duplicate requests and track pending requests that need to be responded.

Decentralized Message Relaying

Perhaps unknown by many but v1.0 protocol was initially designed to be used on the Whisper network. However it was more important at the time that the protocol was adopted by as many applications possible so it was implemented that messages are relayed through a centralized server that mimics a pub-sub architecture like Whisper. Three years later, with Whisper did not survive the test of time but a replacement protocol emerged called Waku. So now that WalletConnect is much better positioned to adopt a decentralized message relay network as its primary transport for messages.

WalletConnect v2.0 uses Waku 2.0 by default to relay messages in a decentralized manner which removes the previous requirement of two clients being connected to the same server. In fact, WalletConnect 2.0 does not even require clients to be connected to a server at all since Waku 2.0 is built on top of libp2p, and therefore it can relay messages client-side like a browser and propagate them through the network to reach the peer client.

That being said we are still going to provide public proxy servers to the Waku network to ensure a smooth transition for developers to adopt v2.0 and also to guarantee the lowest latency and uptime possible perserving this way the same user experience under different network conditions.

What’s next for WalletConnect 2.0?

Currently we are publishing all open-source code for Javascript clients compatible for browsers, node.js and react-native and we have started to onboard multiple projects to beta testing it in production.

The development of Swift and Kotlin clients for the iOS and Android platforms is currently in Alpha stage and we expect to make available stable Beta releases for projects to integrate by January 2022.

Currently we already published a provider for Ethereum and will subsequently release providers for other blockchains starting with Cosmos and Polkadot then followed by Solana and Near.

Our goal will always be to provide the best developer experience, so that applications can offer the best user experience in blockchain. There will be releasing more SDKs in the future and offer more infrastructure services that allow apps to integrate seamlessly with wallets.

Want to learn more?

Check out our documentation and join our Discord to be part of our community.

Arweave TX
Ethereum Address
Content Digest