Once upon a time, not so long ago, chain switching was quite the ordeal. If users wanted to exchange some tokens on Ethereum and then, say, Optimism, they had to disconnect and reconnect their wallet in order to do so.
This cumbersome chain switching UX was something to be solved, which we did with WalletConnect v2.0. For the first time, users could switch between chains in the same session, thanks to the new version of the WalletConnect Protocol, which was designed with the Chain Agnostic Improvement Proposals standards (specifically CAIP-25) in mind. This approach means that the protocol is chain-, event-, method-, and even wallet-agnostic, which makes possible adoption by externally owned account (EOA) wallets, smart contract wallets (SCW), or any other kind of wallet.
To achieve this, WalletConnect v2.0 exposes a developer-friendly abstraction called “namespaces”, which wallets and apps negotiate to define a given wallet session’s “authorization scope” as defined by CAIP-217. CAIP-217 is itself modeled on the Internet Engineering Task Force’s (IETF) RAR extensions for OAuth 2.0.
However, our initial abstraction of CAIP-25, which defines the authorization procedure for a chain-agnostic provider to interface with a wallet as part of their initialization and/or “handshake” protocol, overlooked the lift required by some wallets. Smart contract-based wallets, in particular, implement chain selection and switching quite distinctly from one another in both UX and dapp-interface terms. We thank WalletConnect users for bringing it to our attention, and we deeply appreciate your patience as we’ve worked to resolve this.
In preparation for the WalletConnect v2.0 migration, many apps also opted to require all of the most critical chains, methods, and events at first connection (i.e. required namespaces), leaving others as optional for end user flexibility (i.e. optional namespaces). While this implementation works well for many wallets, it creates challenges for others, most notably smart contract wallets like Safe, which can run on only one chain at a time as a matter of design. If an app sets Ethereum Mainnet (chainID 1) as one of the required namespaces, a Safe wallet running only on its own Gnosis Chain would therefore have to reject the connection — NOT a great end-user experience!
In light of these reasons, we are today introducing new guidance to wallets and apps on the implementation of CAIP-25 and namespaces so that we as an ecosystem can ensure frictionless UX for web3 users everywhere. In particular, wagmi will be updating their namespaces settings on December 7, which is why we strongly recommend for you to test and ensure support for empty / undefined required namespaces by this date.
CAIP-25 implementation guidance for wallets and apps: Required and optional namespaces
Apps should carefully consider what their initial/default settings are when they establish connection with wallets, and how to react to various possible responses.
Wallets, on the other hand, have many more options for supporting connections to apps. Nonetheless, wallets should also analyze their code paths for different usage patterns and corner cases to minimize the number of stalled-out connections and negative end user experiences.
If you’re a wallet:
Ensure you are leveraging our namespace builder util tool, which does namespace parsing for you. Also make sure that you have updated to the following Web3Wallet SDKs or higher — Swift: 1.8.6; Kotlin: BOM-1.17.0; JavaScript: ^1.9.1. This will allow your wallet to handle all possible namespace scenarios that apps may have as supported by CAIP-25.
Provide end-user messaging for connection errors related to namespaces.
Consider user stories around “progressive authorization” (exposing more namespaces over time to unlock more utility and user stories within an app) and how that could interact with defaults or user configurations.
If you choose not to leverage our namespace builder (not recommended) or it is not available on your platform of choice, ensure at a minimum that your wallet can handle the following common usage patterns:
Case #1: Recommended default for all apps
- requiredNamespace is empty / undefined
- optionalNamespace is defined
Case #2
- requiredNamespace is defined
- optionalNamespace is defined
Case #3
- requiredNamespace is defined
- optionalNamespace is empty / undefined
Case #4
- requiredNamespace is empty / undefined
- optionalNamespace is empty / undefined
You can also find the above guidance in our docs.
If you’re an app:
Moving forward, WalletConnect is recommending any app to provide the most flexibility they can afford end users in their namespaces setup:
- requiredNamespaces must be undefined/unset. In the ethereum-provider library, requiredNamespaces are represented by chains, methods and events properties.
- All the supported chains by the app must be set in the scope of optionalNamespaces.
- Make sure you’re listening to wallet events, as they might update the session permissions (e.g. add new chains).
This approach will allow your app to continue connecting with EOA wallets, and it will also smooth over UX differences and connection possibilities for other types of wallets (especially smart contract wallets like Safe, as well as the next generation of account abstraction wallets).
Technical implementation guide for apps
Please follow the instructions according to your set up.
Ethereum Provider package
If you’re an app developer that uses the Ethereum provider package, we recommend the following:
- Move all chains to optionalChains and leave the chains property as undefined/unset.
- Set Events and Methods to undefined/unset.
- optionalMethods and optionalEvents are populated by default by the library, so you don’t need to add them unless you’d like to be selective on which methods and events are proposed for sessions.
Implementation example:
