Configuration

Options to configure a bundler with env 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.

Environment variables

Required

# Connection string to a standard Ethereum node.
ERC4337_BUNDLER_ETH_CLIENT_URL

# The private key for the EOA used to relay bundles to the EntryPoint.
ERC4337_BUNDLER_PRIVATE_KEY

Optional

# Port to run the Client on.
# Defaults to 4337.
ERC4337_BUNDLER_PORT

# Data directory to store embedded mempool.
# Defaults to /tmp/stackup_bundler.
ERC4337_BUNDLER_DATA_DIRECTORY

# Comma separated EntryPoint addresses to support.
# The first address is the preferred EntryPoint.
# Default depends on major version, see release notes on GitHub.
ERC4337_BUNDLER_SUPPORTED_ENTRY_POINTS

# Address to send gas refunds for relaying bundlers.
# Defaults to the public address of the private key.
ERC4337_BUNDLER_BENEFICIARY

# The maximum verificationGasLimit on a received UserOperation.
# Defaults to 1500000 wei.
ERC4337_BUNDLER_MAX_VERIFICATION_GAS

# The maximum gas limit that can be submitted per UserOperation batch.
# Defaults to 25000000 gas.
ERC4337_BUNDLER_MAX_BATCH_GAS_LIMIT

# A percentage buffer to add on top of the estimated verificationGasLimit.
# It will only be added if a paymaster is present.
# This covers the edge case where postOp gas > verification gas.
# Defaults to 10%.
ERC4337_BUNDLER_PAYMASTER_GAS_ESTIMATE_BUFFER

# The maximum durarion that a userOp can stay in the mempool before getting dropped.
# Defaults to 180 seconds.
ERC4337_BUNDLER_MAX_OP_TTL_SECONDS

# The maximum number of pending UserOperations an unstaked sender is allowed.
# Defaults to 4.
ERC4337_BUNDLER_MAX_OPS_FOR_UNSTAKED_SENDER

Searcher mode variables

These variables are relevant to bundlers running in searcher mode.

Required

# Connection string to a block builder that supports eth_sendBundle RPC.
ERC4337_BUNDLER_ETH_BUILDER_URL

Optional

# The number of future blocks to submit a transaction for.
# A higher value may slow down processing but has a higher chance of inclusion.
# Defaults to 25.
ERC4337_BUNDLER_BLOCKS_IN_THE_FUTURE

Observability variables

As of v0.6.9, Stackup Bundler supports tracers and metrics via OpenTelemetry.

# The name for this service (e.g. stackup-bundler).
# To enable O11y, this must be set along with the collector URL.
ERC4337_BUNDLER_OTEL_SERVICE_NAME

# The URL to forward OpenTelemetry signals to.
# To enable O11y, this must be set along with the service name.
ERC4337_BUNDLER_OTEL_COLLECTOR_URL

# Optional collector request headers.
# This must be in the form of "key1=value1&key2=value2".
ERC4337_BUNDLER_OTEL_COLLECTOR_HEADERS

# Optional flag to disable transport security for the exporter's gRPC connection.
# Defaults to false.
ERC4337_BUNDLER_OTEL_INSECURE_MODE