Connecting to Merlin via BTC wallet

Merlin is working with Particle Network to provide a simple mechanism to use Merlin Chain via native Bitcoin wallets through BTC Connect. If you want your dApp to support Bitcoin users natively, either continue reading this document or visit Particle Network's BTC Connect documentation.

High-Level Overview of BTC Connect

BTC Connect refers to a technology built by Particle Network, allowing Bitcoin users to connect with (EVM-compatible) applications on Merlin Chain through Bitcoin native wallets, such as UniSat, OKX, Bitget and so on.

In short, BTC Connect offers a simple, easy-to-integrate SDK that facilitates native Bitcoin wallet connection and interactions. Since native Bitcoin accounts are incompatible with EVM environments, BTC Connect generates and deploys a smart account on Merlin Chain, signed and authenticated by the user's Bitcoin wallet.

Beyond the benefit of allowing a path for native Bitcoin accounts to interact with your application, BTC Connect leverages ERC-4337 account abstraction (hence the utilization of a smart account). This allows you to sponsor the gas fees users leveraging BTC Connect, execute batched transactions, etc.

An overview of this dynamic between a user's native Bitcoin account and their associated smart account deployed on Merlin Chain can be found below:

Integrating BTC Connect

Implementing BTC Connect within your application on Merlin Chain and, therefore, onboarding native Bitcoin users through smart accounts can be done in just a few lines of code.

This document will briefly highlight the three high-level steps required to start using BTC Connect.

For more information about leveraging BTC Connect, visit Particle Network's documentation.

Step 1: Installing Dependencies

BTC Connect requires the installation of one primary dependency, although Particle Network often recommends that four total libraries be used to ensure a cohesive integration.

These are the following:

@particle-network/btc-connectkit, the primary SDK handling BTC Connect.
@particle-network/aa, for streamlining interaction with the user's smart account.
@particle-network/chains, to easily connect with Merlin Chain.
ethers (or web3, viem, etc.), to construct and execute transactions.

With this in mind, you can install the above libraries by running the command below at the root of your project.

yarn add @particle-network/btc-connectkit @particle-network/aa @particle-network/chains ethers


# OR


npm install @particle-network/btc-connectkit @particle-network/aa @particle-network/chains ethers

Step 2: Configuration

Configuring and initializing BTC Connect essentially involves the construction of ConnectProvider, a React component that should wrap the JSX (or component) where you intend to use BTC Connect. Often, this is done within the index file (of an application following the create-react-app structure).

To initialize ConnectProvider (the core configuration object for BTC Connect), you'll first need three key values from the Particle Network dashboard to place within the options parameter. These are your project ID (projectId), client key (clientKey), and app ID (appId).

Because these values are required for BTC Connect to function properly, you'll need to retrieve them through the process below:

Register (or log in) to the Particle Network dashboard.
Create a new project through the "Add New Project" button.
Copy your Project ID and Client Key, saving them within corresponding .env variables ideally.
Create a new application (in this case, a web app).
Enter the name of your application and its domain (if you don't have a domain yet, use a placeholder here).
Copy your App ID and place it within an additional .env variable.

Beyond retrieving your authentication keys, you'll also need to decide which native Bitcoin wallets to support within your application (such as UniSat, Bitget, or OKX); each of these wallets has associated connector objects that you'll need to initiate within the connectors parameter on ConnectProvider.

An example of a complete index file has been included below.

import React from 'react';
import ReactDOM from 'react-dom/client';
import {
  ConnectProvider,
  OKXConnector,
  UnisatConnector,
  BitgetConnector
} from '@particle-network/btc-connectkit';


import { Merlin } from '@particle-network/chains';


import App from './App';


// Optional, may be needed depending on your environment.
import('buffer').then(({ Buffer }) => {
  window.Buffer = Buffer;
});
// -------


ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
  <React.StrictMode>
    <ConnectProvider
      options={{
        projectId: process.env.REACT_APP_PROJECT_ID, // ---
        clientKey: process.env.REACT_APP_CLIENT_KEY, // Retrieved from https://dashboard.particle.network
        appId: process.env.REACT_APP_APP_ID, // ---
        aaOptions: {
          accountContracts: {
            BTC: [
              {
                chainIds: [Merlin.id], // The chain you'd like to use, Merlin in this case.
                version: '1.0.0', // Keep this as 1.0.0 for now.
              },
            ],
          },
        },
        walletOptions: {
          visible: true, // Whether or not the embedded wallet modal (for controlling the smart account) is shown.
        }
      }}
      // List of supported wallets.
      connectors={[new UnisatConnector(), new OKXConnector(), new BitgetConnector()]}
    >
      <App /> // This component should be where you intend on using BTC Connect.
    </ConnectProvider>
  </React.StrictMode>
);

Step 3: Wallet Connection

Once you've configured and initialized BTC Connect through ConnectProvider, navigate to the file containing the component wrapped within ConnectProvider (App in the example above). This is where you'll be able to use BTC Connect for wallet connection.

BTC Connect is controlled through a variety of React hooks, such as:

useETHProvider, to retrieve a smart account object for either direct construction and execution of transactions or to be used with Ethers/Web3.js/etc.
useBTCProvider, for managing native Bitcoin addresses and transactions.
useConnectModal, the generalized connection modal allowing a user to connect with the wallets outlined in connectors.

Using these hooks, you'll need to define specific objects/functions to be used within your application, as shown in the example below.

import React, { useState, useEffect } from 'react';
import { useETHProvider, useBTCProvider, useConnectModal } from '@particle-network/btc-connectkit';
import { AAWrapProvider } from '@particle-network/aa'; // Optional
;
import { ethers } from 'ethers';


import './App.css';




const App = () => {
  const { smartAccount } = useETHProvider();
  const { openConnectModal, disconnect } = useConnectModal();
  const { accounts, sendBitcoin } = useBTCProvider();
    
  // Optional, but streamlines usage of the smart account
  const customProvider = new ethers.providers.Web3Provider(new AAWrapProvider(smartAccount), "any");
    
  ...
}

With these functions defined, you'll be able to use openConnectModal() to display a standard connection interface, allowing a user to choose one of the wallets previously listed within connectors.

E.g.

const handleLogin = () => {
    if (!accounts.length) {
      openConnectModal(); // Immediately opens the connection modal upon calling.
      // Ideally bound to a "Connect Wallet" button.
    }
};

Now that a user has connected their wallet, you can execute transactions (either through smartAccount or through an object such as customProvider in the first snippet) as you would within any other application.

Additional Resources

For a complete example application (including the snippets shown above) built on the Merlin Testnet, take a look at the BTC Connect demo GitHub repository.

More information on BTC Connect can be found through the following links:

Overview: https://blog.particle.network/btc-connect-bitcoin-account-abstraction
Landing Page: https://particle.network/btc-connect.html

PreviousConnecting to Merlin via EVM wallet NextMulti-sig Wallets

Last updated 15 days ago