WalletConnect

To enable the connection of a range of different wallets to your application, especially mobile wallets, you can add the support of WalletConnect into the Commerce Widget. Doing so will enable the "Other Wallets" option in the Connect Flow and other flows when connecting, it also will allow for selecting other wallets when bridging.

WalletConnect also allows users to connect to dapps in their mobile browser and use a mobile wallet. This opens up support for mobile web experiences.

What is WalletConnect

WalletConnect is an open-source protocol that allows you to connect your mobile wallet to different decentralized applications and other wallets. Historically this has been done through a QR code, which establishes a secure end-to-end encrypted connection between the two devices. This allows you to interact with dapps and sign transactions securely from your mobile wallet.

Setup

1. Go to https://cloud.walletconnect.com and set up an account
2. Create a project for you application

3. Copy the Project ID

4. Add your Project ID and application metadata to the checkout.widgets() call in the config object (see below example):

import { checkout } from "@imtbl/sdk"


const checkoutSDK = new checkout.Checkout();

/*
 * When you call .widgets() in your application, pass in your
 * WalletConnect projectId
 * Your app's metadata (url is required)
 */
checkoutSDK.widgets({
  config: {
    theme: checkout.WidgetTheme.DARK,
    walletConnect: {
      projectId: '<PROJECT ID>',
      metadata: {
        name: '<My Application>', // show in wallet connect / transaction prompt
        description: '<My Application>', // show in wallet connect / transaction prompt
        url: '<https://myapplication.com>', // your app url is required for transactions to work correctly
        icons: []
      },
    },
  },
}).then((widgetsFactory) => {
  // Create widgets

})

WalletConnect Explorer

You can explore all of the different Wallets and Dapps that WalletConnect support here: https://explorer.walletconnect.com/

WalletConnect Docs

You can find more information about WalletConnect and it's compatibility with the Commerce Widget through their documentation here:

• Ethereum Provider
• WalletConnect Modal

Wallet whitelisting

💡Wallet whitelist is not configurable for now

For now, the Commerce Widgets have a set whitelist of Wallets that have support for Immutable zkEVM. As the list of wallets that support Immutable zkEVM grows, the wallet whitelist will become configurable for your application if you choose to limit your application to a specific set of wallets.

If you wish to add a specific wallet to the whitelist you can make a request to our support team here: support@immutable.com

Some wallets will only be supported in the Production (Mainnet) environment and not in Sandbox (Testnet).

Session restoring and disconnection

After a user has scanned the QR code, or connected their mobile wallet directly, their session will be stored and subsequent connections will pick up the existing session. This session can be disconnected through the Wallet Widget -> Settings page using the Disconnect Wallet button. Additionally, users can inspect the WalletConnect sessions within their wallet and manually disconnect the sessions from there.

Wallet Widget settings page.
The 'Disconnect Wallet' button will disconnect all active WalletConnect sessions.

Disconnect a session manually in MetaMask mobile wallet.
Settings -> Experimental -> View Sessions -> *hold down the session to delete*

Disconnect a session manually in Frontier mobile wallet.
More -> Wallet connections -> Open session menu -> Click Disconnect

How to target L1 in Connect Widget

The targetChainId Connect Widget parameter can be used to specify the chain that the user should connect to. This is useful when you want to target a specific chain, for example, the Ethereum Mainnet (1). Note: the parameter is defaulted to Immutable zkEVM (13371).

Wallet Widget configuration

The Wallet Widget has parameters that can be used to configure the showing and hiding of the network menu (showNetworkMenu) and the disconnect button (showDisconnectButton). See the Wallet Widget Configuration section for more information.

FAQs

1. The transaction confirmation is not showing correctly in my mobile wallet. What can I do?

Transactions not showing could happen for a couple of reasons.

• If your wallet is not on the correct network for that transaction it may not show.
• If there are multiple WalletConnect sessions for the same app in the same wallet.

Recommendations:

• make sure that your mobile wallet is connected to the correct network when Bridging, Swapping etc... For mobile wallets like MetaMask you will need to switch to this network manually. For other wallets like Frontier this should happen automatically.
• close the mobile wallet app completely
• disconnect all of your current WalletConnect sessions and try again with that transaction.

2. I can't connect, or switching network is not working.

Whilst we do our best to add the Immutable zkEVM network to your wallet through the widgets, this can sometimes occur if the network is not added correctly.

If a wallet does not yet support the Immutable zkEVM network you may need to add the network manully to your wallet. The chain details for Immutable zkEVM are:

• Name: Immutable zkEVM
• RPC Url: https://rpc.immutable.com
• Chain ID: 13371
• Token Symbol: IMX
• Explorer URL (optional): https://explorer.immutable.com

Add a network manually in MetaMask mobile wallet.
Settings -> Networks -> Add Network -> Custom networks (Tab) -> Add details