Options to configure a bundler with environment variables.

The Bundler can be configured through environment variables or a .env file at the working directory. Some variables are required while others are optional.

Base variables

These variables are generally relevant to all bundler modes.


Environment VariableDescription
ERC4337_BUNDLER_ETH_CLIENT_URLRPC url to the execution client.
ERC4337_BUNDLER_PRIVATE_KEYThe private key for the EOA used to relay User Operation bundles to the EntryPoint.


Environment VariableDescriptionDefault Value
ERC4337_BUNDLER_PORTPort to run the HTTP server on.4337
ERC4337_BUNDLER_DATA_DIRECTORYDirectory to store the embedded database./tmp/stackup_bundler
ERC4337_BUNDLER_SUPPORTED_ENTRY_POINTSComma separated EntryPoint addresses to support. The first address is the preferred EntryPoint.Depends on the major version. See πŸ—ΊοΈ Entity Addresses
ERC4337_BUNDLER_BENEFICIARYAddress to send gas cost refunds for relaying User Operation bundles.Defaults to the public address of required private key.
The name of the native tracer to use during validation. This will be "bundlerCollectorTracer" if using builds from ERC-4337 execution client repo.Defaults to nil and will fallback to using the reference JS tracer.
ERC4337_BUNDLER_MAX_VERIFICATION_GASThe maximum verificationGasLimit on a received UserOperation.6,000,000 gas
ERC4337_BUNDLER_MAX_BATCH_GAS_LIMITThe maximum gas limit that can be submitted per UserOperation batch.18,000,000 gas
ERC4337_BUNDLER_MAX_OP_TTL_SECONDSThe maximum duration that a userOp can stay in the mempool before getting dropped.180 seconds
ERC4337_BUNDLER_OP_LOOKUP_LIMITThe maximum block range when looking up a User Operation with eth_getUserOperationReceipt or eth_getUserOperationByHash.

Higher limits allow for fetching older User Operations but will result in higher request latency due to additional compute on the underlying node.
2,000 blocks
ERC4337_BUNDLER_IS_OP_STACK_NETWORKA boolean value for bundlers on an OP stack network to properly account for the L1 callData cost.false
ERC4337_BUNDLER_IS_ARB_STACK_NETWORKA boolean value for bundlers on an Arbitrum stack network to properly account for the L1 callData cost.false
ERC4337_BUNDLER_IS_RIP7212_SUPPORTEDA boolean value for bundlers on a network that supports RIP-7212 precompile for secp256r1 signature verification.false

Searcher mode variables

These variables are relevant to bundlers running in searcher mode.


Environment VariableDescription
ERC4337_BUNDLER_ETH_BUILDER_URLSComma separated list of RPC urls to block builders that support eth_sendBundle. UserOperation bundles will be broadcasted to all builders in the list.


Environment VariableDescriptionDefault Value
ERC4337_BUNDLER_BLOCKS_IN_THE_FUTUREThe number of future blocks to submit a transaction for. A higher value may slow down processing but has a higher chance of inclusion.6 blocks

Reputation constants

These variables relate to the constants defined in ERC-7562 account abstraction validation scope rules.

Environment VariableDefault value
or 1 day
ERC4337_BUNDLER_MIN_STAKE_VALUE2,000,000,000,000,000 wei
or 0.002 ETH

Alternative mempools

Stackup Bundler supports alternative mempools via a standard JSON schema.

Environment VariableDescription
ERC4337_BUNDLER_ALT_MEMPOOL_IPFS_GATEWAYAll mempool configurations are pulled from this IPFS gateway. A connection to a trusted IPFS node will ensure mempool configurations are immutable.
ERC4337_BUNDLER_ALT_MEMPOOL_IDSComma separated list of mempool IDs to support. Alternative mempool IDs are equivalent to their IPFS CIDs.

Observability variables

Stackup Bundler supports tracers and metrics via OpenTelemetry.

Environment VariableDescription
ERC4337_BUNDLER_OTEL_SERVICE_NAMEThe name for this service (e.g. stackup-bundler).
ERC4337_BUNDLER_OTEL_COLLECTOR_URLThe URL to forward OpenTelemetry signals to.
ERC4337_BUNDLER_OTEL_COLLECTOR_HEADERSOptional collector request headers. This must be in the form of key1=value1&key2=value2.
ERC4337_BUNDLER_OTEL_INSECURE_MODEOptional flag to disable transport security for the exporter's gRPC connection. Defaults to false.