permissionless.js: ERC-4337 Account Abstraction Utilities

Common errors

• Error: The client must be configured with a chain. Ensure that `chain` is not `undefined`.

  cause Attempting to create a `permissionless` client (e.g., `createBundlerClient`) without providing a valid `chain` object from `viem/chains`.
  fix When initializing `createPublicClient` or `createBundlerClient`, `createSmartAccountClient`, ensure a `chain` object (e.g., `optimismSepolia`) is passed in the configuration.

• Error: Invalid user operation signature

  cause The `UserOperation` was signed incorrectly, or the `signature` field does not match the expected format or validation logic of the smart account.
  fix Verify that the private key or signer used for signing is correct, the `UserOperation` fields were not mutated after signing, and that the smart account's `validateUserOp` logic on-chain is correctly implemented.

• Error: Paymaster returned an invalid response.

  cause The connected Paymaster service responded with an error or an incorrectly formatted object during the `sponsorUserOperation` call, often due to insufficient funds, an invalid `UserOperation`, or rate limiting.
  fix Check the Paymaster's specific API documentation for error codes. Ensure the `UserOperation` is valid and that your Paymaster account has sufficient balance or allowance for the transaction. Also, verify your API key and endpoint URL.

• Error: Could not estimate gas for UserOperation

  cause The bundler failed to estimate gas for the `UserOperation`, often indicating a revert on execution, an invalid `callData`, or an issue with the gas parameters.
  fix Inspect the `callData` for correctness. Use a debugger (if available for your bundler) or manually trace the `UserOperation` execution to identify the revert reason. Ensure `sender` account has enough ETH for the `preVerificationGas` or that the paymaster is properly sponsoring.

Warnings

• breaking Version 0.3.0 introduced a critical fix for a vulnerability in previous Kernel validator versions. Users on older Kernel-based smart accounts should upgrade immediately to patch 'unsafe to use' functionality.
  Fix: Upgrade `permissionless` to v0.3.0 or higher and ensure your Kernel smart account factory supports the patched version.
• gotcha `permissionless` has `viem` and `ox` as peer dependencies. Ensure you install compatible versions as specified in `package.json` to avoid runtime errors or type mismatches. Regular updates to `permissionless` often include peer dependency version bumps (e.g., v0.3.4 updated `viem` to `^2.44.4` and `ox` to `^0.11.3`).
  Fix: Check your project's `package.json` for `permissionless` and its peer dependencies. Run `npm install viem@^2.44.4 ox@^0.11.3` (or the specific versions required by your `permissionless` version).
• gotcha The `ox` library, a dependency for cryptographic operations, is dynamically loaded. In certain environments or bundler configurations, this might lead to 'Cannot find module 'ox'' errors if not properly handled by your build system.
  Fix: Ensure `ox` is explicitly listed as a dependency in your `package.json` and installed, even though it's a peer dependency. If using a bundler like Webpack or Rollup, ensure it can handle dynamic imports or include `ox` in your build configuration.
• gotcha The `entryPoint` address is a critical configuration parameter for all ERC-4337 clients (`BundlerClient`, `PaymasterClient`, `SmartAccountClient`). Using an incorrect or outdated entryPoint address will lead to transaction failures.
  Fix: Always use the correct `ENTRYPOINT_ADDRESS_V06` or `ENTRYPOINT_ADDRESS_V07` (or newer if available) constant provided by `permissionless` that matches the network and bundler/paymaster you are interacting with.

Install

• npm install permissionless npm
• yarn add permissionless yarn
• pnpm add permissionless pnpm

Imports

• createSmartAccountClient
  wrong:

  const createSmartAccountClient = require('permissionless');

  correct:

  import { createSmartAccountClient } from 'permissionless';

  permissionless is an ESM-first library. Use `import` statements.
• createBundlerClient
  wrong:

  import createBundlerClient from 'permissionless/clients/createBundlerClient';

  correct:

  import { createBundlerClient } from 'permissionless';

  Most client creation functions are named exports from the top-level package.
• UserOperation
  wrong:

  import { UserOperation } from 'permissionless/types';

  correct:

  import type { UserOperation } from 'permissionless/types';

  Type imports should use `import type` for clarity and bundler optimization.

Quickstart

Demonstrates setting up `viem` and `permissionless` clients, creating a simple smart account, preparing a user operation with paymaster sponsorship, and logging the prepared UserOperation.

import { createPublicClient, http, privateKeyToAccount, Address } from 'viem';
import { optimismSepolia } from 'viem/chains';
import { createBundlerClient, createSmartAccountClient, createPimlicoPaymasterClient, ENTRYPOINT_ADDRESS_V07, signerToSimpleSmartAccount } from 'permissionless';
import { type UserOperation } from 'permissionless/types';

const privateKey = (process.env.PRIVATE_KEY as `0x${string}`) || '0x...'; // Replace with your private key
const pimlicoRpcUrl = process.env.PIMLICO_RPC_URL || 'https://api.pimlico.io/v2/optimism-sepolia/rpc?apikey=YOUR_PIMLICO_API_KEY';

const chain = optimismSepolia;
const publicClient = createPublicClient({
  chain,
  transport: http(chain.rpcUrls.default.http[0]),
});

const bundlerClient = createBundlerClient({
  chain,
  transport: http(pimlicoRpcUrl),
  entryPoint: ENTRYPOINT_ADDRESS_V07
});

const paymasterClient = createPimlicoPaymasterClient({
  chain,
  transport: http(pimlicoRpcUrl),
  entryPoint: ENTRYPOINT_ADDRESS_V07
});

async function sendSimpleUserOperation() {
  const signer = privateKeyToAccount(privateKey);

  const simpleSmartAccountClient = await signerToSimpleSmartAccount(publicClient, {
    signer,
    entryPoint: ENTRYPOINT_ADDRESS_V07,
    factoryAddress: '0x9406Cc6185a346906296840746125a0E447645E4' // Example SimpleAccountFactory
  });

  const smartAccountClient = createSmartAccountClient({
    account: simpleSmartAccountClient,
    chain,
    transport: http(pimlicoRpcUrl),
    entryPoint: ENTRYPOINT_ADDRESS_V07
  });

  console.log(`Smart account address: ${smartAccountClient.account.address}`);

  const userOperation = await smartAccountClient.prepareUserOperation({
    userOperation: {
      callData: await smartAccountClient.account.encodeCallData({
        to: smartAccountClient.account.address,
        value: 0n,
        data: '0x'
      })
    },
    sponsorUserOperation: async ({ userOperation }) => {
      return paymasterClient.sponsorUserOperation({
        userOperation,
        entryPoint: ENTRYPOINT_ADDRESS_V07
      });
    }
  });

  // For demonstration, not actually sending a transaction
  console.log('Prepared UserOperation:', userOperation);

  // To send, uncomment:
  // const userOpHash = await smartAccountClient.sendUserOperation({
  //   userOperation: userOperation,
  //   entryPoint: ENTRYPOINT_ADDRESS_V07
  // });
  // console.log(`UserOperation sent, hash: ${userOpHash}`);
  // const receipt = await bundlerClient.waitForUserOperationReceipt({ hash: userOpHash });
  // console.log('UserOperation receipt:', receipt);
}

sendSimpleUserOperation().catch(console.error);