Configuration

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.

Required

Environment Variable	Description
ERC4337_BUNDLER_ETH_CLIENT_URL	RPC url to the execution client.
ERC4337_BUNDLER_PRIVATE_KEY	The private key for the EOA used to relay User Operation bundles to the EntryPoint.

Optional

Environment Variable	Description	Default Value
ERC4337_BUNDLER_PORT	Port to run the HTTP server on.	4337
ERC4337_BUNDLER_DATA_DIRECTORY	Directory to store the embedded database.	/tmp/stackup_bundler
ERC4337_BUNDLER_SUPPORTED_ENTRY_POINTS	Comma separated EntryPoint addresses to support. The first address is the preferred EntryPoint.	Depends on the major version. See 🗺️ Entity Addresses
ERC4337_BUNDLER_BENEFICIARY	Address to send gas cost refunds for relaying User Operation bundles.	Defaults to the public address of required private key.
ERC4337_BUNDLER_ NATIVE_BUNDLER_COLLECTOR_TRACER	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_GAS	The maximum verificationGasLimit on a received UserOperation.	6,000,000 gas
ERC4337_BUNDLER_MAX_BATCH_GAS_LIMIT	The maximum gas limit that can be submitted per UserOperation batch.	18,000,000 gas
ERC4337_BUNDLER_MAX_OP_TTL_SECONDS	The maximum duration that a userOp can stay in the mempool before getting dropped.	180 seconds
ERC4337_BUNDLER_OP_LOOKUP_LIMIT	The 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_NETWORK	A boolean value for bundlers on an OP stack network to properly account for the L1 callData cost.	false
ERC4337_BUNDLER_IS_ARB_STACK_NETWORK	A boolean value for bundlers on an Arbitrum stack network to properly account for the L1 callData cost.	false
ERC4337_BUNDLER_IS_RIP7212_SUPPORTED	A 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.

Required

Environment Variable	Description
ERC4337_BUNDLER_ETH_BUILDER_URLS	Comma separated list of RPC urls to block builders that support `eth_sendBundle`. UserOperation bundles will be broadcasted to all builders in the list.

Optional

Environment Variable	Description	Default Value
ERC4337_BUNDLER_BLOCKS_IN_THE_FUTURE	The 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 Variable	Default value
ERC4337_BUNDLER_MIN_UNSTAKE_DELAY	86,400 seconds or 1 day
ERC4337_BUNDLER_MIN_STAKE_VALUE	2,000,000,000,000,000 wei or 0.002 ETH
ERC4337_BUNDLER_SAME_SENDER_MEMPOOL_COUNT	4 UserOperations
ERC4337_BUNDLER_SAME_UNSTAKED_ENTITY_MEMPOOL_COUNT	11 UserOperations
ERC4337_BUNDLER_THROTTLED_ENTITY_MEMPOOL_COUNT	4 UserOperations
ERC4337_BUNDLER_THROTTLED_ENTITY_LIVE_BLOCKS	10 UserOperations
ERC4337_BUNDLER_THROTTLED_ENTITY_BUNDLE_COUNT	4 UserOperations
ERC4337_BUNDLER_MIN_INCLUSION_RATE_DENOMINATOR	10
ERC4337_BUNDLER_THROTTLING_SLACK	10
ERC4337_BUNDLER_BAN_SLACK	50

Alternative mempools

Stackup Bundler supports alternative mempools via a standard JSON schema.

Environment Variable	Description
ERC4337_BUNDLER_ALT_MEMPOOL_IPFS_GATEWAY	All 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_IDS	Comma 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 Variable	Description
ERC4337_BUNDLER_OTEL_SERVICE_NAME	The name for this service (e.g. stackup-bundler).
ERC4337_BUNDLER_OTEL_COLLECTOR_URL	The URL to forward OpenTelemetry signals to.
ERC4337_BUNDLER_OTEL_COLLECTOR_HEADERS	Optional collector request headers. This must be in the form of `key1=value1&key2=value2`.
ERC4337_BUNDLER_OTEL_INSECURE_MODE	Optional flag to disable transport security for the exporter's gRPC connection. Defaults to false.