Skip to main content

Dapp Usage

Implementation​

This library is compatible with Node.js, browsers and React Native applications (Node.js modules require polyfills for React Native).

Dapps will also need to install WalletConnectModal for the UI.

npm install @walletconnect/modal
info

For an example implementation, please refer to our react-dapp-v2 example.

Install Packages​

Dapps will also need to install WalletConnectModal for the UI.

npm install @walletconnect/modal

Create a Session​

1. Initiate your WalletConnect client with the relay server, using your Project ID.

import SignClient from '@walletconnect/sign-client'

const signClient = await SignClient.init({
  projectId: '<YOUR_PROJECT_ID>',
  // optional parameters
  relayUrl: '<YOUR RELAY URL>',
  metadata: {
    name: 'Example Dapp',
    description: 'Example Dapp',
    url: '#',
    icons: ['https://walletconnect.com/walletconnect-logo.png']
  }
})

2. Add listeners for desired SignClient events.

info

To listen to pairing-related events, please follow the guidance for Pairing API event listeners.

signClient.on('session_event', ({ event }) => {
  // Handle session events, such as "chainChanged", "accountsChanged", etc.
})

signClient.on('session_update', ({ topic, params }) => {
  const { namespaces } = params
  const _session = signClient.session.get(topic)
  // Overwrite the `namespaces` of the existing session with the incoming one.
  const updatedSession = { ..._session, namespaces }
  // Integrate the updated session state into your dapp state.
  onSessionUpdate(updatedSession)
})

signClient.on('session_delete', () => {
  // Session was deleted -> reset the dapp state, clean up from user session, etc.
})

3. Create a new WalletConnectModal instance.

import { WalletConnectModal } from '@walletconnect/modal'

const walletConnectModal = new WalletConnectModal({
  projectId: '<YOUR_PROJECT_ID>',
  // `standaloneChains` can also be specified when calling `walletConnectModal.openModal(...)` later on.
  standaloneChains: ['eip155:1']
})

4. Connect the application and specify session permissions.

try {
  const { uri, approval } = await signClient.connect({
    // Optionally: pass a known prior pairing (e.g. from `signClient.core.pairing.getPairings()`) to skip the `uri` step.
    pairingTopic: pairing?.topic,
    // Provide the namespaces and chains (e.g. `eip155` for EVM-based chains) we want to use in this session.
    requiredNamespaces: {
      eip155: {
        methods: [
          'eth_sendTransaction',
          'eth_signTransaction',
          'eth_sign',
          'personal_sign',
          'eth_signTypedData'
        ],
        chains: ['eip155:1'],
        events: ['chainChanged', 'accountsChanged']
      }
    }
  })

  // Open QRCode modal if a URI was returned (i.e. we're not connecting an existing pairing).
  if (uri) {
    walletConnectModal.openModal({ uri })
    // Await session approval from the wallet.
    const session = await approval()
    // Handle the returned session (e.g. update UI to "connected" state).
    // * You will need to create this function *
    onSessionConnect(session)
    // Close the QRCode modal in case it was open.
    walletConnectModal.closeModal()
  }
} catch (e) {
  console.error(e)
}

Session Authenticate with ReCaps​

The authenticate() method enhances the WalletConnect protocol, offering EVM dApps a sophisticated mechanism to request wallet authentication and simultaneously establish a session. This innovative approach not only authenticates the user but also facilitates a seamless session creation, integrating the capabilities defined by ERC-5573, also known as ReCaps.

ReCaps extend the SIWE protocol, enabling users to give informed consent for dApps to exercise scoped capabilities on their behalf. This consent mechanism is crucial for authorizing a dApp to perform actions or access resources, thus ensuring security and trust in dApp interactions. These scoped capabilities are specified through ReCap URIs in the resources field of the AuthRequestParams, which translate to human-readable consent in the SIWE message, detailing the actions a dApp is authorized to undertake.

To initiate an authentication and authorization request, a dApp invokes the authenticate() method, passing in parameters that include desired capabilities as outlined in EIP-5573. The method generates a pairing URI for user interaction, facilitating a streamlined authentication and consent process.

Example of initiating an authentication request with ReCaps:

const { uri, response } = await signClient.authenticate({
  chains: ['eip155:1', 'eip155:2'], // chains your dapp requests authentication for
  domain: 'localhost', // your domain
  uri: 'http://localhost/login', // uri
  nonce: '1239812982', // random nonce
  methods: ['personal_sign', 'eth_chainId', 'eth_signTypedData_v4'], // the methods you wish to use
  resources: ['https://example.com'] // any resources relevant to the connection
})

// Present the URI to users as QR code to be able to connect with a wallet
...

// wait for response
const result = await response()

// after a Wallet establishes a connection response will resolve with auths ( authentication objects ) & the established session
const { auths, session } = result;

// now you can send requests to that session

Making Requests​

Once the session has been established successfully, you can start making JSON-RPC requests to be approved and signed by the wallet:

const result = await signClient.request({
  topic: session.topic,
  chainId: 'eip155:1',
  request: {
    method: 'personal_sign',
    params: [
      '0x7468697320697320612074657374206d65737361676520746f206265207369676e6564',
      '0x1d85568eEAbad713fBB5293B45ea066e552A90De'
    ]
  }
})

For more information on available JSON-RPC requests, see the JSON-RPC reference.

Restoring a Session​

Sessions are saved to localstorage, meaning that even if the web page is reloaded, the session can still be retrieved, as demonstrated in the following code:

const lastKeyIndex = signClient.session.getAll().length - 1
const lastSession = signClient.session.getAll()[lastKeyIndex]

Finding a Specific Session​

If you need to find a specific session, you can do so by passing in a known requiredNamespace and calling find.

const specificSession = _client.find({
  requiredNamespaces: {
    eip155: {
      methods: [
        'eth_sendTransaction',
        'eth_signTransaction',
        'eth_sign',
        'personal_sign',
        'eth_signTypedData'
      ],
      chains: ['eip155:5'],
      events: ['chainChanged', 'accountsChanged']
    }
  }
})