Skip to main content

Namespaces

What are Namespaces?​

The WalletConnect protocol v2.0 was designed with a better web3 end-user experience in mind, with the goal of being chain-, event-, method-, and even wallet-agnostic. To achieve this, WalletConnect v2.0 exposes a developer-friendly abstraction called “namespaces”, designed in accordance with CAIP-25.

During the WalletConnect v2.0 migration, many apps 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. This includes smart contract wallets like Safe as well as non-smart contract wallets that also run on only one chain at a time as a matter of design.

Testing Your Wallet's Implementation​

Updated October 10, 2023

If you are a wallet that has implemented WalletConnect's Web3Wallet SDK, we highly recommend for you to test your wallet's implementation of “namespaces” immediately. Testing only takes a few minutes and is extremely important as it may impact your wallet's ability to connect with apps.

How to Test​

Simply connect your wallet to our example app here: https://se-sdk-dapp.vercel.app/.

If you can connect, it is a good indicator that your wallet correctly supports namespaces. Hooray - there’s nothing for you to do!

If you can’t connect, we recommend updating your wallet as soon as possible by following the steps outlined below.

Updating Your Wallet's Namespaces Implementation​

Ensure you are leveraging our namespace builder util tool, which does namespace parsing for you and allows your wallet to handle all possible namespace scenarios that apps may have as supported by CAIP-25. You should also support the latest version of the Web3Wallet SDK as indicated below:

  • Swift: 1.8.6
  • Kotlin: BOM-1.17.0
  • JavaScript: ^1.9.1

If you choose not to leverage our namespace builder (not recommended) or if it is not available on your platform of choice, ensure at a minimum that your wallet can handle the following common usage patterns:

Case No. 1 - Recommended Default for All Apps​

  • requiredNamespace is empty / undefined
  • optionalNamespace is defined

Case No. 2​

  • requiredNamespace is defined
  • optionalNamespace is defined

Case No. 3​

  • requiredNamespace is defined
  • optionalNamespace is empty / undefined

Case No. 4​

  • requiredNamespace is empty / undefined
  • optionalNamespace is empty / undefined

And that's it! By simply following the steps above, your wallet should now support all scenarios in regards to namespaces.

Technical Implementation Guide for Apps​

Please follow the instructions according to your setup.

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: '<https://my-dapp.com>',
    icons: ['<https://my-dapp.com/logo.png>']
  }
})

Web3Modal SDK​

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

npm install wagmi@latest

Wagmi - WalletConnectConnector​

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

Need Technical Support? If you require technical support along the way, please drop a message on the WalletConnect GitHub and our team will get back to you as soon as possible.

Need Technical Support?​

If you require technical support along the way, please drop a message on the WalletConnect GitHub and our team will get back to you as soon as possible.