AppKit and WalletKit have arrived. Explore the all-new product stacks.
Learn more
Blog Home
AppKit, Network, WalletKit
November 29, 2023
The WalletConnect logo
CAIP-25 guidance: Migrating to empty / undefined required namespaces

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:

const provider = await EthereumProvider.init({
  projectId: 'YOUR_PROJECT_ID',
  optionalChains:[1, 5, 56, 42161, 137],
  showQrModal: true,
  metadata: {
    name: "My Dapp",
    description: "My Dapp description",
    url: "<>",
    icons: ["<>"],

Web3Modal SDK

Update wagmi to version 1.4.9 or above. Please note that this version will be released on December 7.

npm i wagmi@latest

Wagmi — WalletConnectConnector

Update wagmi to version 1.4.9 or above. Please note that this version will be released on December 7.

You can also find the above guidance in our docs.

Need help — or want to get involved?

The WalletConnect team is always here to assist you should you encounter any difficulties. All you need to do is reach out to us on the WalletConnect GitHub and let us know the issue you are facing.

As this blog post has shown, a lot of the behind-the-scenes work we do here at WalletConnect focuses on standards for web3, which are critical to moving this industry forward. If you’re passionate about technical and community coordination, I highly encourage you to get involved.

Notice: Explorer API legacy endpoints deprecation

As part of our ongoing commitment to providing secure, efficient, and up-to-date services, we are announcing the deprecation of certain legacy endpoints within the Explorer API by 13:00 (GMT) on January 30, 2024. This deprecation only affects you if you are still using registry.walletconnect.ORG or the affected endpoints listed here; you will also find your upgrade path there.

Recommended Articles
More articles

Build what's next.
Build with WalletConnect.

Get started
© 2024 WalletConnect, Inc.