Account abstraction with Biconomy

TIP

Privy now allows you to natively use smart wallet for a better developer experience. Check out the docs here.

Biconomy is a toolkit for creating ERC-4337-compatible smart accounts for your users, using the user's EOA as the smart account's signer. This allows you to easily add Account Abstraction features into your app.

You can easily integrate Biconomy alongside Privy to create smart wallets from your user's embedded or external wallets, allowing you to enhance your app with gas sponsorship and more!

Read below to learn how to configure your app to create smart wallets for all your users!

TIP

Want to see an end-to-end integration of Privy with Biconomy? Check out an example app and repo!

What is an EOA?

An EOA, or externally-owned account, is any Ethereum account that is controlled by a private key. Privy's embedded wallets and most external wallets (MetaMask, Coinbase Wallet, Rainbow Wallet, etc.) are EOAs.

EOAs differ from contract accounts, which are instead controlled by smart contract code and do not have their own private key. Biconomy's smart wallet is a contract account. Contract accounts have enhanced capabilities, such as gas sponsorship and batched transactions.

Since they do not have their own private key, contract accounts cannot directly produce signatures and initiate transaction flows. Instead, each contract account is generally "managed" by an EOA, which authorizes actions taken by the contract account via a signature; this EOA is called a signer.

In this integration, the user's EOA (from Privy) serves as the signer for their smart wallet (from Biconomy). The smart wallet (Biconomy) holds all assets and submits all transactions to the network, but the signer (Privy) is responsible for producing signatures and "kicking off" transaction flows.

1. Install Privy and Biconomy

In your app's repository, install the @privy-io/react-auth SDK from Privy and the @biconomy/account SDK from Biconomy:

npm i @privy-io/react-auth @biconomy/account

2. Configure your app's PrivyProvider

First, follow the instructions in the Privy Quickstart to get your app set up with Privy.

Next, set Add confirmation modals to "off" in your app's Embedded wallets page in the Privy dashboard. This will configure Privy to not show its default UIs when your user must sign messages or send transactions. Instead, we recommend you use your own custom UIs for showing users the UserOperations they sign.

Then, update the config.embeddedWallets.createOnLogin property of your PrivyProvider to 'users-without-wallets'.This will configure Privy to create an embedded wallet for users logging in via a web2 method (email, phone, socials), ensuring that all of your users have a wallet that can be used as an EOA.

Your PrivyProvider should then look like:

<PrivyProvider
    appId='insert-your-privy-app-id'
    config={{
        embeddedWallets: {
            createOnLogin: 'users-without-wallets', 
        }
        ...insertTheRestOfYourPrivyProviderConfig
    }}
>
    {/* Your app's components */}
</PrivyProvider>

3. Configure your Biconomy bundler and paymaster

Go to the Biconomy Dashboard and configure a Paymaster and a Bundler for your app. Make sure these correspond to the desired network for your user's smart accounts.

Configuring your Biconomy Paymaster

Once you've configured a Paymaster, you can also deposit funds into your app's gas tank and configure specific policies for gas sponsorship.

Save the bundler URL and paymaster API key for your project, as you will need those values later.

4. Initialize your users' smart accounts

When users log into your app, Privy provisions each user an embedded wallet, which is an EOA. In order to leverage the features of Biconomy's account abstraction, each user also needs a Biconomy smart account. You can provision Biconomy smart accounts for each user by assigning their embedded wallet as a signer for their smart account.

To start, after a user logs in, find the user's embedded wallet from Privy's useWallets hook, and switch its network to your app's target network. You can find embedded wallet by finding the only entry in the useWallets array with a walletClientType of 'privy'.

import {useWallets} from '@privy-io/react-auth';
...
// Find the embedded wallet
const {wallets} = useWallets();
const embeddedWallet = wallets.find((wallet) => (wallet.walletClientType === 'privy'));
// Switch the embedded wallet to your target network
// Replace '80001' with your desired chain ID.
await embeddedWallet.switchChain(80001);

Next, using your paymaster API key and bundler URL from the Biconomy Dashboard, initialize the user's smart account using Biconomy's createSmartAccountClient method:

import { createSmartAccountClient } from "@biconomy/account";
...
// Get an ethers provider and signer for the user's embedded wallet
const provider = await embeddedWallet.getEthersProvider();
const signer = provider.getSigner();

const smartAccount = await createSmartAccountClient({
    signer: signer,
    bundlerUrl: 'your-bundler-url-from-the-biconomy-dashboard',
    biconomyPaymasterApiKey: 'your-paymaster-api-key-from-the-biconomy-dashboard'
});

TIP

You can also store the user's smart account address on Privy's user object. See this guide for more.

Want to see this code end-to-end?

You can find the code snippets above pasted in an end-to-end example below.

import {createSmartAccountClient} from '@biconomy/account';

import {useWallets} from '@privy-io/react-auth';

// Find the embedded wallet and switch it to your target network
const {wallets} = useWallets();
const embeddedWallet = wallets.find((wallet) => wallet.walletClientType === 'privy');
await embeddedWallet.switchChain(80001);

const provider = await embeddedWallet.getEthersProvider();
const signer = provider.getSigner();

// Initialize your smart account
const smartAccount = await createSmartAccountClient({
  signer: signer,
  bundlerUrl: 'your-bundler-url-from-the-biconomy-dashboard',
  biconomyPaymasterApiKey: 'your-paymaster-api-key-from-the-biconomy-dashboard',
});

Note: if your app uses React, we suggest that you store the user's Biconomy smartAccount in a React context that wraps your application. This allows you to easily access the smart account from your app's pages and components.

5. Send transactions from the smart account

Now that your users have Biconomy smart accounts, they can now send transaction from their smart account.

To send a transaction from a user's smart account, use Biconomy's sendTransaction method. An example of sending a transaction to mint an NFT gaslessly is below:

// Initialize an ethers JsonRpcProvider for your network
const provider = new ethers.providers.JsonRpcProvider(`insert-rpc-url-for-your-network`);
// Initialize an ethers contract instance for your NFT
const nft = new ethers.Contract('insert-your-NFT-address', insertYourNftAbi, provider);

// Construct a Transaction for the minting transaction
const mintTransaction = await nft.populateTransaction.mint!('insert-the-smart-account-address');
// `smartAccount` is the Biconomy smart account we initialized above
const mintTx = {
  to: 'insert-your-NFT-address',
  data: mintTransaction.data,
};

// Send transaction to mempool, to mint NFT gaslessly
const userOpResponse = await smartAccount.sendTransaction(mintTx, {
  paymasterServiceData: {mode: PaymasterMode.SPONSORED},
});

const {transactionHash} = await userOpResponse.waitForTxHash();
console.log('Transaction Hash', transactionHash);

const userOpReceipt = await userOpResponse.wait();
if (userOpReceipt.success == 'true') {
  console.log('UserOp receipt', userOpReceipt);
  console.log('Transaction receipt', userOpReceipt.receipt);
}

That's it! You've configured your app to create smart wallets for all of your users, and can seamlessly add in AA features like gas sponsorship and more. 🎉