Skip to main content

WalletConnect 2.0 Manual Configuration

warning

This guide is for advanced users who want to manually configure WalletConnect 2.0 with FCL-JS. Since @onflow/fcl@1.11.0, FCL-JS has supported WalletConnect 2.0 out of the box. For most users, we recommend using this built-in WalletConnect 2.0 support (see how to configure FCL-JS here).

To improve developer experience and streamline Flow dApp integration with WalletConnect 2.0 wallets, FCL ^1.3.0 introduces support for discovery-service plugins. These ServicePlugins allow for injection of client configured services, service methods, and the execution strategies required to interact with them. FCL dApps can opt-in through use of the fcl-wc package and FCL Plugin Registry.

When using FCL Discovery for authentication, dApps are able to support most FCL-compatible wallets and their users on Flow without any custom integrations or changes needed to the dApp code.

These instructions explain how dApps can also add support for FCL compatible wallets that use the WalletConnect 2.0 protocol.

How does it work?

  • The fcl-wc package is used to initialize a WalletConnect 2.0 SignClient instance, and build a discovery-service ServicePlugin based on dApp specified options.
  • discovery-service plugins are used to add opt-in wallets and other services to FCL Wallet Discovery (UI/API).
  • The FCL Plugin Registry offers dApps the ability to add new services, methods, and the execution strategies needed to interact with them.

Requirements

  • fcl version >= 1.3.0
  • fcl-wc version >= 1.0.0

Implementation path

1Add required packagesInstall and import minimum fcl and fcl-wc versions
2Obtain a WalletConnect projectIDVisit WalletConnect Cloud Registry and register for public relay server access and an application projectId
3Initialize WalletConnect SignClient and FclWcServicePluginInitialize WalletConnect SignClient and FclWcServicePlugin with configuration options
4Add FclWcServicePlugin to FCL Plugin RegistryInject FclWcServicePlugin via fcl.pluginRegistry.add(FclWcServicePlugin)

1. Add required packages

Install the fcl and fcl-wc packages:


_10
npm install @onflow/fcl@ @onflow/fcl-wc

2. Obtain a WalletConnect projectID

Visit WalletConnect Cloud Registry and register for public relay server access and an application projectId.

3. Initialize WalletConnect SignClient and FclWcServicePlugin

In addition to the WalletConnect SignClient, the init method of fcl-wc returns a ServicePlugin object. This object can be injected using the FCL Plugin Registry to add support for new service methods and their corresponding execution strategies (like WC/RPC for WalletConnect ). A discovery-service ServicePlugin may also include additional opt-in wallets to offer your users through FCL Wallet Discovery.

Configuration options

Initialize WalletConnect SignClient and FclWcServicePlugin with the following configuration options:

NameTypeDefaultDescription
projectIdboolean (required)nullA WalletConnect projectId for public relay server access. Your Project ID can be obtained from WalletConnect Cloud Dashboard
metadataobject{ }Optional dApp metadata to describe your application and define its appearance in a web browser. More details can be found here
includeBaseWCbooleanfalseOptional configuration to include a generic WalletConnect service in FCL Discovery (UI/API).
BaseWC Service offers no deeplink support for mobile.
wcRequestHookfunctionnullOptional function is called on all desktop WalletConnect client session proposals and signing requests. Use this to handle alerting user to check wallet for approval.
pairingModalOverridefunctionnullOptional function called to allow override of included QRCodeModal. Function receives two arguments:
1. Connection uri to display QR code or send to wallet to create pairing.
2. Callback function to manually cancel the request.
walletsarray[ ]Optional list of WalletConnect authn services to include in FCL Wallet Discovery (UI/API).
Only available for use on testnet. These services will be combined with wallets returned from WalletConnect cloud registry API and sent to Discovery for display in UI and inclusion in API response.

Returns

NameTypeDescription
FclWcServicePluginServicePluginA ServicePlugin of type discovery-service. May also include optional authn services to offer through FCL Wallet Discovery (UI/API).
clientSignClientAn initialized WalletConnect SignClient.

_10
const FclWcServicePlugin = {
_10
name: "fcl-plugin-service-walletconnect",
_10
f_type: "ServicePlugin", // the type of FCL plugin
_10
type: "discovery-service", // the is a service sent to Discovery
_10
services: [Service], // (optional) Generic, Cloud Registry and client injected WalletConnect services
_10
serviceStrategy: {method: "WC/RPC", exec: execStrategy, // the method name and execution strategy for WalletConnect services
_10
}

Setting FCL config flow.network to testnet or mainnet is required to use fcl-wc as it enables "WC/RPC" service strategy to request correct chain permissions.


_10
import {config} from '@onflow/config'
_10
_10
config({
_10
"flow.network": "mainnet"
_10
})

See FCL Configuration for more information.

4. Add FclWcServicePlugin to FCL Plugin Registry

In addition to the WalletConnect SignClient, the init method of fcl-wc returns a ServicePlugin object. This object can be injected into the FCL Plugin Registry to add FCL support for new service methods, (like WC/RPC for WalletConnect) and their corresponding execution strategies.

Usage


_19
import * as fcl from '@onflow/fcl';
_19
import { init } from 'fcl-wc';
_19
_19
const { FclWcServicePlugin, client } = await init({
_19
projectId: WC_PROJECT_ID, // required
_19
metadata: WC_APP_METADATA, // optional
_19
includeBaseWC: false, // optional, default: false
_19
wallets: [], // optional, default: []
_19
wcRequestHook: (wcRequestData) => {
_19
// optional,default: null
_19
handlePendingRequest(data);
_19
},
_19
pairingModalOverride: (uri, rejectPairingRequest) => {
_19
// optional,default: null
_19
handlePendingPairingRequest(data);
_19
},
_19
});
_19
_19
fcl.pluginRegistry.add(FclWcServicePlugin);


ServicePlugin Spec

KeyValue TypeDescription
namestringThe name of the plugin.
f_typestringThe type of plugin (currently only supports ServicePlugin type).
typestringThe plugin subtype (currently only supports discovery-service type).
servicesarrayA list of services to add to FCL.
serviceStrategy{ method: string, exec: function }The method and corresponding strategy FCL uses to interact with the service. A service with the service.method property set to "WC/RPC" tells FCL to use the corresponding service strategy if it is supported by the dApp.

Integrating With Wallet Discovery

Knowing all the wallets available to users on a blockchain can be challenging. FCL's Discovery mechanism relieves much of the burden of integrating with Flow compatible wallets and let's developers focus on building their dApp and providing as many options as possible to their users.

There are two ways an app can use Wallet Discovery:

  1. The UI version which can be configured for display via iFrame, Popup, or Tab.

  2. The API version which allows you to access authentication services directly in your code via fcl.discovery.authn method which we'll describe below.

When using FCL Wallet Discovery for authentication, dApps are able to support FCL-compatible wallets on Flow without any custom integrations or changes needed to the dApp code.

discovery-service ServicePlugin

FclWcServicePlugin is a ServicePlugin of type discovery-service. discovery-service plugins may include additional authentication services to offer through FCL Wallet Discovery.

Once a valid discovery-service plugin is registered, FCL shares client supported services with Discovery to add registered and injected wallets to the UI and API.

To connect a Flow supported wallet using WalletConnect 2.0, users of your dApp will go through the authentication process and have the option to select their preferred wallet.

Once a WalletConnect session is established and a currentUser is authenticated, FCL will handle client pairings and sessions during FCL authn, and initiate signing requests as part of authz using fcl.mutate and user-sign using fcl.signUserMessage.

How to add your FCL compatible WalletConnect wallet to Discovery (UI/API)

  1. Submit a PR to add your wallet to FCL Wallet Discovery services.json
  2. Submit your FCL compatible wallet to WalletConnect Cloud Registry
  3. Add Wallet Service to fcl-wc init options. testnet only.

FCL tells Wallet Discovery which services are supported by the client (installed extensions and discovery-service ServicePlugins) so only those supported will be shown in Discovery UI or returned via Discovery API.

Wallet Discovery UI

Wallet Provider Spec

Implementation path

1Obtain a WalletConnect projectIdRegister to receive a projectId from the WalletConnect Cloud Registry.
2Conform to FCL Wallet Provider SpecCompatible wallets must support flow_authn, flow_authz, and flow_user_sign methods and wrap data in the appropriate FCL Response type. Services returned with the AuthnResponse of flow_authn should set service.endpoint to corresponding methods.
ServiceType authz : flow_authz
ServiceType user-signature : flow_user_sign
3Add wallet to WalletConnect Cloud Registry API (optional)Submit your wallet to be included in the WalletConnect Cloud Registry API and Explorer
4ResponsesAll responses need to be wrapped in a PollingResponse

Metadata requirements

In order to correctly identify, improve pairing, and include deep link support for mobile, services using the WC/RPC method need to use the same universal link as their uid and url in Wallet metadata. Wallets sourced from WalletConnect Cloud Registry automatically build the service from data and will set the service.uid to the universal link.


_16
import SignClient from '@walletconnect/sign-client';
_16
_16
export let signClient: SignClient;
_16
_16
export async function createSignClient() {
_16
signClient = await SignClient.init({
_16
projectId: PROJECT_ID,
_16
relayUrl: 'wss://relay.walletconnect.com',
_16
metadata: {
_16
name: 'Awesome Wallet',
_16
description: 'Awesome Wallet with FCL Support for WalletConnect',
_16
url: 'https://deeplink.awesome-wallet.com/',
_16
icons: ['https://avatars.githubusercontent.com/u/37784886'],
_16
},
_16
});
_16
}

Next steps

  1. Read the FCL Wallet Provider Spec.
  2. Check out the a WalletConnect 2.0 React POC Wallet and FCL Flow dApp with support for WalletConnect v2.0.
  3. Read and review the WalletConnect 2.0 Docs, examples and resources.