What Changed from v1.0

WalletConnect v2.0 is NOT backwards-compatible with v1.0. WalletConnect v1.0 and v2.0 offer essentially the same end-user experience, however they work very differently internally. This means that developers will have to consider different APIs and SDKs. Additionally, some UX considerations will have to be made when integrating v2.0.

Multi-Chain support

Most interfaces are very similar to the previous version but the most contrasting difference between the two versions comes from its multi-chain support.

WalletConnect v1.0 mimics a lot of its behavior from Metamask's browser extension, which meant that sessions tracked a single chainId, an accounts array, and wallets controlled the chainId while dapps followed.

WalletConnect v2.0 instead allows dapps to request a set of chains as part of the scope of the session and Wallets respond with a success or error message when the compatibility is met. Additionally, this means that the Wallet no longer controls the chainId of the chain but instead the session tracks multiple chainIds. Finally, the Wallet will expose one or many accounts matching each of the chains requested by the Dapp and these can be updated on the session state during its lifetime.

Chain-Agnostic interface

Previously on v1.0, WalletConnect expected only EVM-compatible Wallets and Dapps to use its protocol to interoperate. This assumption however brought its own constraints, which disable other chain ecosystems to meet compatibility and utilize the protocol.

WalletConnect v2.0 introduces a set of JSON-RPC methods that are permissioned to use within the session's lifetime. This means that a Dapp can request a minimum set of methods that requires to meet compatibility with the Wallet, which can be responded with a success or error message when the compatibility is met. Additionally, this means that the Dapp can not only determine if the Wallet can sign transactions and/or messages for the chain it needs, but it also can detect support for experimental methods (e.g. eth_signTypedData). Finally, the Wallet can upgrade the set of methods it exposes during its session lifetime.

Session Lifetime

Previously on v1.0, WalletConnect had indefinite session lifetime, which meant that clients would persist the session state until one of the clients emitted an event to disconnect. This unfortunately introduced a lot of stalled session states where one of the clients would lose its state and never emit an event to disconnect.

To counter this, WalletConnect v2.0 introduces expiry timestamps for sessions that are currently defaulted to 7 days. This means that independent of the disconnect event not being emitted by a peer client then a client will disconnect and delete the session state after expiry is met.

Session requests include a TTL (time to live) value which can extend the default lifetime (7 days) of the session. Also, the session expiry timestamp is calculated by the responder client which then shares the timestamp on its session response.

Pairings & Sessions

The newest concept introduced with WalletConnect v2.0 which wasn't present in WalletConnect v1.0 is the pairings. Pairings which are special-purpose sessions used to propose new sessions which have a default lifetime of 30 days. Whenever a QR Code or Deep Link is generated to connect a Dapp and a Wallet, it is used to establish a pairing. Therefore, when a session is expired or terminated, it no longer requires clients to pair again if they still have an active pairing.

Pairings have longer expiration than Sessions because they are meant to be re-used for session proposals and they can request an infinite number of session proposals between Dapps and Wallets.

Single Client

Previously on v1.0, WalletConnect managed one session per each client which itself maintained a WebSocket connection with the Relay (aka Bridge) server. This design was not performant and it also introduced a lot of complexity when managing multiple sessions specially for Wallets.

WalletConnect v2.0 clients are more monolithic but manage multiple sessions within one single client and transport all messages through a single WebSocket connection. This also means that WalletConnect v2.0 clients also manage their storage to persist the state of multiple sessions, and consequently, pairings as well.

Message Acknowledgement

Perhaps the biggest drawback of the WalletConnect v1.0 was that clients did not acknowledge received messages from the server and didn't track the history of JSON-RPC requests received.

WalletConnect v2.0 clients track all JSON-RPC requests sent and received with the client, can ignore duplicates, and acknowledge messages that were received. This means basically that independently of the server or node that WalletConnect v2.0 is connected to, it won't affect the behavior of a session and its state can be restored without interruption.

Project ID

Project ID will be required on v2.0 for the cloud version of WalletConnect, but this will not be required for self-hosted WalletConnect relays. Read more about Project IDs.