Biconomy Gas Estimations

A utility package that performs simulation and estimations of all ERC-4337 User Operation gas limits.

Usage

Create a Gas Estimator

You can create the gas estimator for you chain of choice in multiple ways.

❌ Don't use public RPC URLs because they often don't support more advanced features like state overrides and debug_traceCall

Using a chainId and a rpcUrl:

import { mainnet } from "viem/chains"

const gasEstimator = createGasEstimator({
  chainId: mainnet.id,
  rpc: "https://rpc.url",
});
Copy

Using a viem public client:

import { mainnet } from "viem/chains"

const viemClient = createPublicClient({
  chain: miannet,
  transport: http("https://rpc.url"),
});

const gasEstimator = createGasEstimator({
  chainId: testChain.chainId,
  rpc: viemClient,
});
Copy

Or using a full chain specification (useful for new chains not supported by default by this package):

const customChain: SupportedChain = {
  chainId: 4337,
  name: "Biconomy Mainnet",
  isTestnet: false,
  stack: ChainStack.Optimism,
  eip1559: true,
  entryPoints: {
    [EntryPointVersion.v060]: {
      address: "0x006",
    },
    [EntryPointVersion.v070]: {
      address: "0x007",
    },
  },
  stateOverrideSupport: {
    balance: true,
    bytecode: true,
    stateDiff: true,
  },
  smartAccountSupport: {
    smartAccountsV2: true,
    nexus: true,
  },
  simulation: {
    preVerificationGas: 1n,
    verificationGasLimit: 2n,
    callGasLimit: 3n,
  },
  paymasters: DEFAULT_PAYMASTERS,
};

const gasEstimator = createGasEstimator({
  chainId: customChain.chainId,
  rpc: rpcUrl,
  chain: customChain,
});
Copy

Estimating User Operation gas limits

By default the gas estimator tries to be as flexible as possible and return the gas estimates, even if the sender (or the paymaster) doesn't have funds to pay for gas.

💡 If the target chain (or your RPC provider) doesn't support state overrides, the estimation will fail if the on-chain requirements (such as sender and paymaster balance) are not met and there's not much we can do.

const gasEstimate =
  await gasEstimator.estimateUserOperationGas({
    unEstimatedUserOperation: userOperation,
    baseFeePerGas,
  });
Copy

Simulation mode

In case you don't want the package to perform any state overrides by default you can use the simulation mode and the package will throw an appropriate error if the sender doesn't have enough balance or any other on-chain requirement is not met.

await gasEstimator.estimateUserOperationGas({
  unEstimatedUserOperation: userOperation,
  baseFeePerGas,
  options: {
    simulation: true
  }
});
Copy

Passing custom state overrides

You can pass additional state overrides when estimating, there's a helper StateOverrideBuilder you can use:

await gasEstimator.estimateUserOperationGas({
  unEstimatedUserOperation: userOperation,
  baseFeePerGas,
  stateOverrides: new StateOverrideBuilder().
    .overrideBalance(
      address,
      parseEther("100"),
    )
    .overridePaymasterDeposit(
      entryPointAddress,
      paymasterAddress
    )
    .build()
});
Copy

API Reference

For detailed documentation and API reference, visit our api documentation here.

Building

To build the project do bun run build

Publishing

Production Release

To publish a new production version:

1. Create a new changeset (documents your changes):

bun run changeset
Copy

2. Version the package (updates package.json and changelog):

bun run changeset:version
Copy

3. Publish to npm:

bun run changeset:release
Copy

Canary Release

To publish a canary (preview) version:

bun run changeset:release:canary
Copy

This will publish a canary version to npm with a temporary version number. The original package.json will be restored automatically after publishing.

Canary Release

Note: You need to have appropriate npm permissions to publish the package.