Skip to main content

Dapps

The followings steps describe the various paths for dapps to migrate to v2:

  1. web3-provider
  2. ethereum-provider
  3. Web3Modal v1.0
  4. Web3Modal v2.0
  5. react-native-dapp
  6. web3-onboard
  7. Dynamic
  8. solana-labs/wallet-adapter
  9. web3-react
  10. ConnectKit

web3-provider​

If you are using @walletconnect/web3-provider, we stopped supporting this provider in favor of the improved version published under @walletconnect/ethereum-provider and you will be able to check the latest version on NPM here.

ethereum-provider​

caution

For usage with typescript, make sure you are using Typescript version 5.0.0 or higher.

  • Ensure you have a projectId from WalletConnect Cloud. You can get one for free here
  • Upgrade @walletconnect/ethereum-provider from 1.x.x to 2.x.x.

Previously, you would have passed in an infuraId like:

import WalletConnectProvider from '@walletconnect/ethereum-provider'

const web3Provider = new WalletConnectProvider({
  infuraId: 'INFURA_ID'
})

The new implementation requires projectId and chains instead. Here is an example of the new initialization:

import { EthereumProvider } from '@walletconnect/ethereum-provider'

const provider = await EthereumProvider.init({
  projectId: 'WALLETCONNECT_PROJECT_ID', // required
  chains: [1], // required
  showQrModal: true // requires @web3modal/standalone
})
  • Install @web3modal/standalone if you want to use the QR Code modal.

Further references for the ethereum-provider can be found here.

For more documentation about implementation with Web3Modal, refer to the following:

Web3Modal v1.0​

We recommend that you replace your existing integration with the latest version of Web3Modal, we recommend following one of these paths:

  • Full Web3Modal: This provides the full Web3modal experience with wagmi which allows users to connect wallets, perform transactions and manage accounts easy.
  • Standalone Web3Modal: A leaner version of Web3Modal if you want to use SignClient and your own web3 library.

If you still want to use Web3Modal v1.0 but just upgrade the WalletConnect ethereum-provider to v2.0 then you can update to the latest version available on NPM which you can find here.

Web3Modal v2.0​

If you are using our new redesigned Web3Modal v2.0, you can simply enable v2.0 by using the feature flag version: 2 when injecting modal connectors. Please ensure that you are using a minimum version of 2.2.0. Here is a code example:

import { w3mConnectors } from '@web3modal/ethereum'
import { createClient } from 'wagmi'

// ...

const wagmiClient = createClient({
  autoConnect: true,
  connectors: w3mConnectors({
    projectId,
    chains,
    version: 2 // add this line
  }),
  provider
})

// ...

For more documentation, follow the docs for Web3Modal here.

react-native-dapp​

If you are using @walletconnect/react-native-dapp, we are currently in alpha for web3modal-react-native. Please note this is in alpha and subject to change. The repo can be found here.

In the meantime, you can check out the other React Native Examples repo which integreates Universal Provider + our Cloud Explorer API. This provides the foundations for a React Native dapp to connect to wallets.

web3-onboard​

If you are using the WalletConnect package with Blocknative's web3-onboard the migration is straight forward. The latest WC package is backwards compatible (until the WC v1 sunset). When you are ready to transition, bump the @web3-onboard/walletconnect package version to >= 2.3.0 and adjust the initialization params to include:

{
  /**
  * Defaults to version: 1 - this behavior will be deprecated after the WalletConnect v1 sunset
  */
  version: 2,

  /**
  * Project ID associated with [WalletConnect account](https://cloud.walletconnect.com)
  */
  projectId: string
}

Note: The @web3-onboard/walletconnect package will default to version 1 until the WC v1 sunset is complete

Dynamic​

Switching to v2 is straightforward using Dynamic. To upgrade, ensure you are using v0.15 or later of @dynamic-labs/sdk-react . Once set up, visit your Dynamic developer dashboard and head to the integrations page. Select the WalletConnect card, toggle v2 on and add your WalletConnect project ID. Once enabled, Dynamic will automatically use WalletConnect v2 for wallets that support it, and v1 for wallets that don’t.

solana-labs/wallet-adapter​

If you are using solana-labs/wallet-adapter, this is already working on WalletConnect v2 so there is nothing to change here. There will be a new version released with an updated UI modal coming shortly.

web3-react​

web3-react has created their own modules for WalletConnect v2. You can test their playground here and read their example implementation here. In order to get started with the migration, we suggest upgrading your @web3-react/types, @web3-react/store and @web3-react/core as well as installing @web3-react/walletconnect-v2.

After you have the respective packages, you will have to obtain a projectID from our Cloud Platform and add it your .env file.

You will need to then initialize WalletConnect v2 as a connector as referenced here.

import { initializeConnector } from '@web3-react/core'
import { WalletConnect as WalletConnectV2 } from '@web3-react/walletconnect-v2'

import { MAINNET_CHAINS } from '../chains'

const [mainnet, ...optionalChains] = Object.keys(MAINNET_CHAINS).map(Number)

export const [walletConnectV2, hooks] = initializeConnector<WalletConnectV2>(
  actions =>
    new WalletConnectV2({
      actions,
      options: {
        projectId: process.env.walletConnectProjectId,
        chains: [mainnet],
        optionalChains,
        showQrModal: true
      }
    })
)

Note: Be sure to test with several chains in order to complete your implementation for WalletConnect v2.

Then use the @web3-react/walletconnect-v2 package with the following methods in your components.

  • URIListener: Event listener for when v2 URI is created. Code reference here.
  • activate: Create a session pairing with WalletConnect v2. Code reference here.
  • deactivate: Disconnect your session from your wallet. Code reference here.
  • connectEagerly: Connect to v2 protocol on mount. Code reference here.

Sample codes of reference can be found in:

ConnectKit​

To migrate to WalletConnect V2 using ConnectKit, you need to upgrade connectkit and wagmi to the latest version

caution

WalletConnect V2 is only supported in ConnectKit v1.3.0 and above

info

For version 1.4.0 and above, you need to remove ethers and install viem instead.

yarn remove ethers
yarn add wagmi@latest viem@latest

Run the following command to install it using Yarn:

yarn add connectkit@^latest wagmi@^latest

WalletConnect v2 requires a project ID to be set and included in the configuration. You can get a projectID from WalletConnect Cloud for free.

Create a new environment variable WALLETCONNECT_PROJECT_ID in your .env file and set it to your project ID.

WALLETCONNECT_PROJECT_ID=YOUR_PROJECT_ID

Next, update your code by including the walletConnectProjectId inside the config object for getDefaultClient:

...
const client = createClient(
  getDefaultClient({
    ...
+    walletConnectProjectId: process.env.WALLETCONNECT_PROJECT_ID,
    ...
  }),
);
...

Note:

  • For a version specific upgrade, refer to the official migration guide by Family.
  • When customizing your configuration for advanced usage, it is important to include the projectId within your WalletConnectConnector object. You can learn more about it here
  • Make sure you have compatible versions of ethers and viem. Check your project's dependencies to ensure compatibility with ConnectKit.

For a comprehensive example, refer to the provided sample code: