Connecting to Merlin via BTC wallet
Last updated
Last updated
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.
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:
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.
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.
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.
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.
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.
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.
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:
Landing Page: https://particle.network/btc-connect.html