BB x Pimlico Banner.png

Introduction

This tutorial guides you through integrating Pimlico Paymaster with their ERC-4337 compatible Alto bundler for account abstraction in blockchain applications using the Pimlico 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. Additionally it also supports Paymaster services allowing the users to perform gasless transactions, and paying for gas in ERC20s instead

What You'll Learn to

Install and configure Pimlico plugin in your BuildBear Sandbox.
Use permissionless.js to create and manage smart accounts.
Set up Alto Bundler on your BuildBear network.
Set up ERC20 Paymaster with Pimlico Client
Calculating gas estimates for Paymaster
Fund smart accounts for transactions.
Swap DAI to USDT 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 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

ERC20 Paymaster Support

Choose from a list of vast tokens, supported by Pimlico’s ERC20 Paymaster, and pay for transactions in ERC20 instead of Chain-Native tokens.

A full list of supported tokens and the corresponding chains can be found here: Supported ERC20s

Unlocked Faucets

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

Step 1: Setting Up Pimlico

1️⃣ 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.

2️⃣ Install the Pimlico Plugin

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

3️⃣ Retrieve the RPC URL

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

Example:

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

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

4️⃣ Install Dependencies

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

{
  "name": "pimlico-tutorial-template",
  "version": "1.0.0",
  "description": "A template repository for Pimlico tutorials (https://docs.pimlico.io/tutorial)",
  "main": "index.ts",
  "type": "module",
  "scripts": {
    "start": "tsx index.ts"
  },
  "author": "",
  "license": "MIT",
  "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

Note: For the purpose of this walkthrough, a sandbox forked from Polygon Mainnet is needed

1️⃣ Define the Sandbox URL

Set the buildbearSandboxUrl using your BuildBear RPC URL.

const buildbearSandboxUrl = "https://rpc.buildbear.io/{SANDBOX-ID}";

2️⃣ Set Up BuildBear Sandbox Network

Setup your custom BuildBear Sandbox network using viem

const BBSandboxNetwork = /*#__PURE__*/ defineChain({
  id: SANDBOX-CHAIN-ID, // IMPORTANT : replace this with your Sandbox's chain id
  name: "BuildBear x Polygon Mainnet Sandbox", // name your network
  nativeCurrency: { name: "BBETH", symbol: "BBETH", 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/{SANDBOX-ID}",
      apiUrl: "https://api.buildbear.io/{SANDBOX-ID}/api",
    },
  },
});

3️⃣ 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}`);

4️⃣ Set Up Public Client

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

export const publicClient = createPublicClient({
  chain: BBSandboxNetwork,
  transport: http(buildbearSandboxUrl),
});

Step 3: Configuring Pimlico Client & Smart Accounts

1️⃣ 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",
  },
});

2️⃣ 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 with Paymaster endpoint to send gasless transactions & user operations from that smart account

Only paymaster: pimlicoClient is to be defined when one needs (truly) gasless tx and wants pimlico to sponsor it on the behalf of the sender. In case of ERC20 Paymaster, paymaster context is also need to define upfront, what token will the user pay with for the gas to the ERC20 Paymaster for it’s sponsorship

const signer = privateKeyToAccount(privateKey);

const account = await toSafeSmartAccount({
  client: publicClient,
  owners: [signer],
  entryPoint: {
    address: entryPoint07Address,
    version: "0.7",
  }, // global entrypoint
  version: "1.4.1",
});

const smartAccountClient = createSmartAccountClient({
  account,
  chain: BBSandboxNetwork,
  bundlerTransport: http(buildbearSandboxUrl), //sending the tx to buildbear
  paymaster: pimlicoClient,
  userOperation: {
    estimateFeesPerGas: async () => {
      return (await pimlicoClient.getUserOperationGasPrice()).fast;
    },
  },
});

Step 4: Funding & Executing Transactions

Funding Your Smart Account Wallet: Funding your smart account with ERC20 token, in our case DAI, is essential since it will facilitate sending of gasless tx and allow for paying for tx in ERC20 instead. 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

DAI ERC20 token to swap to USDT
USDT (Optional)

1️⃣ Check Account Balance

if (+daiBalanceBefore.toString() <= 0) {
  console.log("====================================");
  console.log(
    `⚠️⚠️Fund your Account with DAI 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("====================================");

}

2️⃣ 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_ERC20Faucet",
  "params": [{ "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","token": "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063", "balance": "10000" }]

}

3️⃣ Setup Helper Functions

// Helper Functions

// get USDT Balance of Smart Account
async function getUSDTBalance(): Promise<string> {
  let res = await publicClient.readContract({
    address: "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    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();
}

4️⃣ Initialize Swap Params & Estimating cost of UserOp in DAI

Initialize the swap parameters for the DAI => USDT Swap

let swapParams = {
  tokenIn: "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063" as `0x${string}`, // DAI
  tokenOut: "0xc2132D05D31c914a87C6611C10748AEb04B58e8F" as `0x${string}`, // USDT
  fee: 3000 as number, //fee
  recipient: account.address, // recipient
  deadline: (Math.floor(Date.now() / 1000) + 60 * 2) 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
  v3Router: "0xE592427A0AEce92De3Edee1F18E0157C05861564" as `0x${string}`,
  paymasterV7Address:
    "0x0000000000000039cd5e8ae05257ce51c473ddd1" as `0x${string}`,
};

The following part is optional in case of ERC20 Paymaster but not at all needed when using Verifying Paymaster. In case of ERC20 Paymaster, it's still recommended to include to avoid overpayment to it.

console.log("====================================");

console.log("🟠 Calculating UserOp Cost in DAI....");

// Get quotes for tokens in array on given network
const quotes = await pimlicoClient.getTokenQuotes({
  chain: BBSandboxNetwork,
  tokens: [swapParams.tokenIn],
});

// extract post op gas, exchange rate and paymaster from quotes
const { postOpGas, exchangeRate, paymaster } = quotes[0];

// prepare user operation & calculating the estimate
const userOperation: UserOperation<"0.7"> =
  await smartAccountClient.prepareUserOperation({
    calls: [
      {
        to: "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063" as `0x${string}`, //DAI
        abi: parseAbi(["function approve(address,uint)"]),
        functionName: "approve",
        args: [swapParams.v3Router, parseEther("1")],
      },
      {
        to: swapParams.v3Router, //UniV3 Router
        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,
          ],
        ],
      },
    ],
  });

// calculate max cost in token
const userOperationMaxGas =
  userOperation.preVerificationGas +
  userOperation.callGasLimit +
  userOperation.verificationGasLimit +
  (userOperation.paymasterPostOpGasLimit || 0n) +
  (userOperation.paymasterVerificationGasLimit || 0n);

// calculate max cost in token
const userOperationMaxCost = userOperationMaxGas * userOperation.maxFeePerGas;

// using formula here https://github.com/pimlicolabs/singleton-paymaster/blob/main/src/base/BaseSingletonPaymaster.sol#L334-L341
const maxCostInToken =
  ((userOperationMaxCost + postOpGas * userOperation.maxFeePerGas) *
    exchangeRate) /
  BigInt(1e18);
console.log("====================================");

5️⃣ 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.

Send the User Operation via smart account for:

Approving DAI spending to Paymaster Address to facilitate paying for tx in DAI (Important)
- It is crucial to include a approve tx, because this is how the paymaster knows to pull funds from smart account and pay for tx on user’s behalf
Approving DAI spending by UniswapV3Router to exchange for USDT
Executing exactInputSingle tx to UniswapV3Router for the swap
Specifying paymasterContext is crucial in case of ERC20 paymaster, it tells the Pimlico to pull the token with the given address in exchange for gas sponsorships

const txHash = await smartAccountClient.sendUserOperation({
  account,
  calls: [
    {
      to: "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063" as `0x${string}`, //DAI
      abi: parseAbi(["function approve(address,uint)"]),
      functionName: "approve",
      args: [swapParams.paymasterV7Address, maxCostInToken],
    },
    {
      to: "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063" as `0x${string}`, //DAI
      abi: parseAbi(["function approve(address,uint)"]),
      functionName: "approve",
      args: [swapParams.v3Router, parseEther("1")],
    },
    {
      to: swapParams.v3Router, //UniV3 Router
      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,
        ],
      ],
    },
  ],
  paymasterContext: {
    token: swapParams.tokenIn,
  },
});
console.log("🟠 Swapping DAI....");

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

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

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

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

console.log("🟢 Balance after transaction: ", formatEther(balance));
console.log("🟢 DAI Balance after transaction: ", daiBalanceAfter);
console.log("🟢 USDT Balance after transaction: ", usdtBalanceAfter);
console.log("🟢 Max DAI Estimate for UserOp: ", formatEther(maxCostInToken));
console.log(
  "🟢 DAI charged for UserOp: ",
  (+daiBalanceBefore - +daiBalanceAfter - 1).toFixed(18).replace(/\.?0+$/, "") // Adjust decimal places as needed
);

exit();

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 USDT on Uniswap V3 with Alto ---------
🟠 Balance before transaction:  100.99956781271324068
🟠 DAI Balance before transaction:  85.99999999999986006
🟠 USDT Balance before transaction:  14.970922
====================================
🟠 Approving DAI....
====================================
🟠 Calculating UserOp Cost in DAI....
====================================
🟠 Swapping DAI....
🟢User operation included: https://explorer.dev.buildbear.io/{SANDBOX-ID}/tx/0x9ea4bc26e6af350aee9fc384a6704bcd87c91aeda0bd3c368f07b6fefb18847d
🟢 Yay!! 🎉🎉 Swapped 1 DAI to 0.9979220000000009 USDT
🟢 Balance after transaction:  100.99956781271324068
🟢 DAI Balance after transaction:  84.999999999999848441
🟢 USDT Balance after transaction:  15.968844
🟢 Max DAI Estimate for UserOp:  1.056731379494445588
🟢 DAI charged for UserOp:  0.000000000000014211

(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.

1️⃣Fund Flow

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

2️⃣Call Trace

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

3️⃣Call Graph

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

4️⃣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

5️⃣ 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 on BuildBear. ✅ Configured a smart account using permissionless.js. ✅ Setup ERC20 Paymaster with Pimlico Client & Alto Bundler. ✅Funded the account. ✅Executed a user operation to swap token on Uniswap V3 and pay DAI for gas.

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

Executing Token Swap on Uniswap V3 with Pimlico's ERC20 Paymaster & Alto Bundler

BUILDBEAR // TUTORIALS

Executing Token Swap on Uniswap V3 with Pimlico's ERC20 Paymaster & Alto Bundler

Let’s get started then, Shall we?

Let’s get started then, Shall we?