BB x Pimlico Alto Banner.png

Introduction

This tutorial guides you through integrating ERC-4337-compatible bundlers for account abstraction in blockchain applications using the Pimlico Alto plugin. Pimlico Alto simplifies bundling user operations into transactions and submitting them to the blockchain via standard JSON-RPC requests. It supports permissionless.js, enabling seamless Web3 application development and testing.

What You'll Learn

Install and configure Pimlico Alto in your BuildBear Sandbox.
Use permissionless.js to create and manage smart accounts.
Set up Alto Bundler on your BuildBear network.
Fund smart accounts for transactions.
Swap DAI to USDC on Uniswap V3, by sending user operation(s) via the smart account client to the Alto Bundler on BuildBear Sandbox

Why test Pimlico AA with BuildBear Sandbox?

Seamless Integration

Pimlico Alto Plugin is designed for effortless integration with BuildBear Sandboxes, making it easy to experiment with Account Abstraction (AA) features.

Permissionless.js Support

High-level API for managing ERC-4337 smart accounts, bundlers, and paymasters.
Built on Viem for modularity and extensibility.

JSON-RPC Support for Bundler

Interact with the bundler using standard methods:

eth_sendUserOperation
eth_estimateUserOperationGas
eth_getUserOperationReceipt
eth_getUserOperationByHash
eth_supportedEntryPoints
pimlico_getUserOperationGasPrice
pimlico_getUserOperationStatus

Unlocked Faucets

BuildBear provides unlimited access to native and ERC-20 tokens, ensuring smooth development and testing.

Step 1: Setting Up Pimlico Alto

Create a BuildBear Sandbox

Navigate to BuildBear and create a new Sandbox or use an existing one.
Open the Plugins tab in your Sandbox dashboard.

Install the Pimlico Alto Plugin

Locate Pimlico Alto Bundler in the plugin marketplace.
Click Install to add it to your environment.
Verify installation in the Installed Plugins tab.

Retrieve the RPC URL

Open your BuildBear Sandbox dashboard.
Copy the RPC URL, which also serves as the Pimlico Client API endpoint.

For example:

BuildBear Sandbox RPC URL: https://rpc.buildbear.io/parliamentary-katebishop-6df91ec9

Pimlico Client API: https://rpc.buildbear.io/parliamentary-katebishop-6df91ec9

Install Dependencies

Ensure all necessary dependencies are installed. Example package.json:

{
 "name": "pimlico-tutorial-template",
 "version": "1.0.0",
 "dependencies": {
   "dotenv": "^16.3.1",
   "ethers": "^6.13.5",
   "permissionless": "^0.2.0",
   "viem": "^2.20.0"
 },
 "devDependencies": {
   "@types/node": "^20.11.10",
   "tsx": "^3.13.0"
 }
}

Step 2: Configuring BuildBear

Define Sandbox URL

Set the buildbearSandboxUrl using your BuildBear RPC URL.

const buildbearSandboxUrl = "https://rpc.buildbear.io/uzair";

Set Up BuildBear Sandbox Network

Setup your custom BuildBear Sandbox network using viem

const BBSandboxNetwork = /*#__PURE__*/ defineChain({
  id: 23351, // IMPORTANT : replace this with your Sandbox's chain id
  name: "BuildBear x Polygon Mainnet Sandbox", // name your network
  nativeCurrency: { name: "MATIC", symbol: "MATIC", decimals: 18 }, // native currency of forked network
  rpcUrls: {
    default: {
      http: [buildbearSandboxUrl],
    },
  },
  blockExplorers: {
    default: {
      name: "BuildBear x Polygon Mainnet Scan", // block explorer for network
      url: "https://explorer.buildbear.io/uzair",
      apiUrl: "https://api.buildbear.io/uzair/api",
    },
  },
});

Generate a Private Key (Optional)

Generate or retrieve a private key for your smart account & store it in .env file.

const privateKey = process.env.PRIVATE_KEY || generatePrivateKey();
appendFileSync(".env", `\nPRIVATE_KEY=${privateKey}`);

Set Up Public Client

Create a new public client using the BuildBear Sandbox RPC URL.

const privateKey = process.env.PRIVATE_KEY || generatePrivateKey();
appendFileSync(".env", `\nPRIVATE_KEY=${privateKey}`);

Step 3: Configuring Pimlico Client & Smart Accounts

Set Up Pimlico Client

Configure the Pimlico Client with the BuildBear Sandbox RPC URL and EntryPoint details.

const pimlicoClient = createPimlicoClient({
  transport: http(buildbearSandboxUrl),
  entryPoint: { address: entryPoint07Address, version: "0.7" },
});

Create Smart Account & Client

Use the private key to create a signer, and then use the signer to create a safe smart account. Use the smart account to setup a smart account client to send the transactions & user operations from that smart account

const signer = privateKeyToAccount(privateKey);
const account = await toSafeSmartAccount({
  client: publicClient,
  owners: [signer],
  entryPoint: { address: entryPoint07Address, version: "0.7" },
  version: "1.4.1",
});
const smartAccountClient = createSmartAccountClient({
  account,
  chain: BBSandboxNetwork,
  bundlerTransport: http(buildbearSandboxUrl),
  userOperation: {
    estimateFeesPerGas: async () => (await pimlicoClient.getUserOperationGasPrice()).fast,
  },
});

Step 4: Funding & Executing Transactions

Funding Your Smart Account Wallet: Since paymasters are not supported, it’s essential for users to fund their wallets. An underfunded or empty wallet will result in errors during transactions.

Addresses can be funded with the RPC Methods supported by all the BuildBear’s Sandboxes

For the user operation to work correctly you will need to have

Native Tokens for gas fees
DAI ERC20 token to swap to USDC
USDC (Optional)

Check Account Balance

if (+balance.toString() <= 0 || +daiBalanceBefore.toString() <= 0) {
  console.log("====================================");
  console.log(
    `⚠️⚠️Fund your Account with DAI & NATIVE tokens from your BuildBear Sandbox Faucet and try running the script again.\nSmart Account Address: ${account.address}`
  );
  console.log("====================================");
  exit();
} else {
  console.log("====================================");
  console.log(`Smart Account Address: ${account.address}`);
  console.log("====================================");
}

Fund Smart Account

Call your BuildBear RPC Sandbox URL, with the following parameters to get faucet funds, or use Faucet in Navigation Pane on the Sandbox Dashboard

Native Token Faucet

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "buildbear_nativeFaucet",
  "params": [{ "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "balance": "10000" }]
}

ERC Token Faucet

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "buildbear_nativeFaucet",
  "params": [{ "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "balance": "10000" }]
}

Setup Helper Functions

// Helper Functions

// get USDC Balance of Smart Account
async function getUSDCBalance(): Promise<string> {
  let res = await publicClient.readContract({
    address: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
    abi: ERC20Abi,
    functionName: "balanceOf",
    args: [account.address],
  });
  return formatUnits(res as bigint, 6).toString();
}

// get DAI Balance of Smart Account
async function getDAIBalance(): Promise<string> {
  let res = await publicClient.readContract({
    address: "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063",
    abi: ERC20Abi,
    functionName: "balanceOf",
    args: [account.address],
  });
  return formatUnits(res as bigint, 18).toString();
}

Send Transaction

With sufficient funds in the account, send the transaction to the bundler, via the smart account client specifying the receiver, value, and optional data.

Initialize the swap parameters for the DAI => USDC Swap

let swapParams = {
  tokenIn: "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063" as `0x${string}`, // DAI
  tokenOut: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174" as `0x${string}`, // USDC
  fee: 3000 as number, //fee
  recipient: account.address, // recipient
  deadline: (Math.floor(Date.now() / 1000) + 60 * 30) as unknown as bigint, // expiration
  amountIn: parseEther("1") as bigint, //amountIn
  amountOutMinimum: 0 as unknown as bigint, //amountOutMinimum
  sqrtPriceLimitX96: 0 as unknown as bigint, //sqrtPriceLimitX96
};

Send the User Operation via smart account for:

Approving DAI spending by UniswapV3Router
Executing exactInputSingle tx to UniswapV3Router for the swap

// send the user operation to approve dai & swap for usdc on UniV3

const txHash = await smartAccountClient.sendUserOperation({
  account,
  calls: [
    {
      to: "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063" as `0x${string}`, //DAI
      abi: parseAbi(["function approve(address,uint)"]),
      functionName: "approve",
      args: ["0xE592427A0AEce92De3Edee1F18E0157C05861564", parseEther("1")],
    },
    {
      to: "0xE592427A0AEce92De3Edee1F18E0157C05861564",
      abi: parseAbi([
        "function exactInputSingle((address, address , uint24 , address , uint256 , uint256 , uint256 , uint160)) external payable returns (uint256 amountOut)",
      ]),
      functionName: "exactInputSingle",
      args: [
        [
          swapParams.tokenIn,
          swapParams.tokenOut,
          swapParams.fee,
          swapParams.recipient,
          swapParams.deadline,
          swapParams.amountIn,
          swapParams.amountOutMinimum,
          swapParams.sqrtPriceLimitX96,
        ],
      ],
    },
  ],
});
console.log("🟠 Swapping DAI....");

let { receipt } = await smartAccountClient.waitForUserOperationReceipt({
  hash: txHash,
});

console.log(
  `🟢User operation included: https://explorer.buildbear.io/uzair/tx/${receipt.transactionHash}`
);

balance = await publicClient.getBalance({ address: account.address }); // Get the balance of the sender
let daiBalanceAfter = await getDAIBalance();
let usdcBalanceAfter = await getUSDCBalance();

console.log(
  `🟢 Yay! 🎉🎉 Swapped ${formatUnits(swapParams.amountIn, 18)} DAI to ${
    +usdcBalanceAfter - +usdcBalanceBefore
  } USDC`
);

console.log("🟢 Balance after transaction: ", formatEther(balance));
console.log("🟢 DAI Balance after transaction: ", daiBalanceAfter);
console.log("🟢 USDC Balance after transaction: ", usdcBalanceAfter);

Execute the script with npm start and the swap should go through producing the following output:

====================================
Smart Account Address: 0xa03Af1e5A78F70d8c7aCDb0ddaa2731E4A56E8FB
====================================
====================================
-------- UserOp to Swap DAI to USDC on Uniswap V3 with Alto ---------
🟠Balance before transaction:  194.996055684952779832
🟠DAI Balance before transaction:  30000000192
🟠USDC Balance before transaction:  302.985378
====================================
🟠 Approving DAI....
====================================
🟠 Swapping DAI....
🟢User operation included: https://explorer.buildbear.io/uzair/tx/0x243f6ad379bd4b306038d9afdcc842d60e14b33624050f37005724a45a99b33f
🟢 Yay!! 🎉🎉 Swapped 1 DAI to 0.9949579999999969 USDC
🟢 Balance after transaction:  194.995769640950494282
🟢 DAI Balance after transaction:  30000000191
🟢 USDC Balance after transaction:  303.980336

(Optional) Debugging and Deep Dive into UserOp with Sentio

Clicking on View On Sentio, will open a sentio debugger for the transaction, where you can observe the Overview of transaction, such as Fund Flow, Call Traces & Graphs, as well as the Gas Metrics.

Fund Flow

Depicts the flow of funds among different contracts and their order of execution

Call Trace

Shows the entire call trace for the transaction, including the contract calls, functions called within the contract, the inputs and the outputs

Call Graph

Similar to Call Trace, but provides a top-level view of the contracts & function calls

Gas Profiler

Depicts the gas limits, actual gas used, initial gas as well as the gas used by each of the functions as part of the function call

Debugging With Sentio

Besides the Overview, is a Debugger Tab, where one can view and debug individual call to each of the functions and view the inputs, gas metrics & return values.

There is also a contracts section, which allows a deeper insight into the contract and the functions within it

Besides the Contracts tab, there is a Events tab, which shows the event emissions by each of the functions as part of the transaction.

Lastly, the State tab, it provides the overview of state of funds before and after the transaction for accounts involved in the transaction.

Conclusion

By following this tutorial, you have successfully: Set up Pimlico Alto on BuildBear. Configured a smart account using permissionless.js. Funded the account and executed a user operation that performs token swap on Uniswap V3.

For full code and demos, check out the GitHub repository!

Execute Token Swaps on Uniswap V3 with Pimlico Alto & BuildBear

BUILDBEAR // BLOGS

Execute Token Swaps on Uniswap V3 with Pimlico Alto & BuildBear

Let’s get started then, Shall we?

Let’s get started then, Shall we?