Skip to content

cli.md

Latest commit

 

History

History
347 lines (304 loc) · 24.7 KB

cli.md

File metadata and controls

347 lines (304 loc) · 24.7 KB
Raw

Rundler CLI

The Rundler Command Line Interface (CLI) offers a wide array of options and subcommands. Most options contain reasonable defaults that can be overridden.

Subcommands

  • node: Runs the Pool, Builder, and RPC servers in a single process.
  • rpc: Runs the Rpc server.
  • pool: Runs the Pool server.
  • builder: Runs the Builder server.

The pool and builder commands will also start a gRPC endpoint to allow other processes to interact with each service.

Common Options

These options are common to all subcommands and can be used globally:

Chain Specification

See chain spec for a detailed description of chain spec derivation from these options.

  • --network: Network to look up a hardcoded chain spec. (default: None)
    • env: NETWORK
  • --chain_spec: Path to a chain spec TOML file.
    • env: CHAIN_SPEC
  • (env only): Chain specification overrides.
    • env: *CHAIN_**

Rundler Common

  • --node_http: EVM Node HTTP URL to use. (REQUIRED)
    • env: NODE_HTTP
  • --max_verification_gas: Maximum verification gas. (default: 5000000).
    • env: MAX_VERIFICATION_GAS
  • --max_uo_cost: Maximum cost of a UO that the mempool will accept. Optional, defaults to MAX (default: None).
    • env: MAX_UO_COST
  • --min_stake_value: Minimum stake value. (default: 1000000000000000000).
    • env: MIN_STAKE_VALUE
  • --min_unstake_delay: Minimum unstake delay. (default: 86400).
    • env: MIN_UNSTAKE_DELAY
  • --tracer_timeout: The timeout used for custom javascript tracers, the string must be in a valid parseable format that can be used in the ParseDuration function on an ethereum node. See Docs Here. (default: 15s)
    • env: TRACER_TIMEOUT
  • --enable_unsafe_fallback: If set, allows the simulation code to fallback to an unsafe simulation if there is a tracer error. (default: false)
    • env: ENABLE_UNSAFE_FALLBACK
  • --user_operation_event_block_distance: Number of blocks to search when calling eth_getUserOperationByHash/eth_getUserOperationReceipt. (default: all blocks)
    • env: USER_OPERATION_EVENT_BLOCK_DISTANCE
  • --user_operation_event_block_distance_fallback: Number of blocks to search when falling back during eth_getUserOperationByHash/eth_getUserOperationReceipt upon initial failure using user_operation_event_block_distance. (default: None)
    • env: USER_OPERATION_EVENT_BLOCK_DISTANCE_FALLBACK
  • --verification_estimation_gas_fee: The gas fee to use during verification estimation. (default: 1000000000000 10K gwei).
  • --bundle_base_fee_overhead_percent: bundle transaction base fee overhead over network pending value. (default: 27).
    • env: BUNDLE_BASE_FEE_OVERHEAD_PERCENT
  • --bundle_priority_fee_overhead_percent: bundle transaction priority fee overhead over network value. (default: 0).
    • env: BUNDLE_PRIORITY_FEE_OVERHEAD_PERCENT
  • --priority_fee_mode_kind: Priority fee mode kind. Possible values are base_fee_percent and priority_fee_increase_percent. (default: priority_fee_increase_percent).
    • options: ["base_fee_percent", "priority_fee_increase_percent"]
    • env: PRIORITY_FEE_MODE_KIND
  • --priority_fee_mode_value: Priority fee mode value. (default: 0).
    • env: PRIORITY_FEE_MODE_VALUE
  • --base_fee_accept_percent: Percentage of the current network fees a user operation must have in order to be accepted into the mempool. (default: 100).
    • env: BASE_FEE_ACCEPT_PERCENT
  • --pre_verification_gas_accept_percent: Percentage of the required PVG that a user operation must have in order to be accepted into the mempool. Only applies if there is dynamic PVG, else the full amount is required. (default: 50)
    • env: PRE_VERIFICATION_GAS_ACCEPT_PERCENT
  • --execution_gas_limit_efficiency_reject_threshold: The ratio of execution gas used to gas limit under which to reject UOs upon entry to the mempool (default: 0.0 disabled)
    • env: EXECUTION_GAS_LIMIT_EFFICIENCY_REJECT_THRESHOLD
  • --verification_gas_limit_efficiency_reject_threshold: The ratio of verification gas used to gas limit under which to reject UOs upon entry to the mempool (default: 0.0 disabled)
    • env: VERIFICATION_GAS_LIMIT_EFFICIENCY_REJECT_THRESHOLD
  • --verification_gas_allowed_error_pct: The allowed error percentage during verification gas estimation. (default: 15)
    • env: VERIFICATION_GAS_ALLOWED_ERROR_PCT
  • --call_gas_allowed_error_pct: The allowed error percentage during call gas estimation. (default: 15)
    • env: CALL_GAS_ALLOWED_ERROR_PCT
  • --max_gas_estimation_gas: The gas limit to use during the call to the gas estimation binary search helper functions. (default: 550M)
    • env: MAX_GAS_ESTIMATION_GAS
  • --max_gas_estimation_rounds: The maximum amount of remote RPC calls to make during gas estimation while attempting to converge to the error percentage. (default: 3)
    • env: MAX_GAS_ESTIMATION_ROUNDS
  • --aws_region: AWS region. (default: us-east-1).
    • env: AWS_REGION
    • (Only required if using other AWS features)
  • --unsafe: Flag for unsafe bundling mode. When set Rundler will skip checking simulation rules (and any debug_traceCall). (default: false).
    • env: UNSAFE
  • --mempool_config_path: Path to the mempool configuration file. (example: mempool-config.json, s3://my-bucket/mempool-config.json). (default: None)
    • This path can either be a local file path or an S3 url. If using an S3 url, Make sure your machine has access to this file.
    • env: MEMPOOL_CONFIG_PATH
    • See here for details.
  • --builders_config_path: Path to the entry point builders configuration file (example: builders.json, s3://my-bucket/builders.json). (default: None)
    • This path can either be a local file path or an S3 url. If using an S3 url, Make sure your machine has access to this file.
    • env: BUILDERS_CONFIG_PATH
    • NOTE: most deployments can ignore this and use the settings below.
    • See here for details.
  • --enabled_entry_points: Enabled entry point versions. (default: v0.7)
    • env: ENABLED_ENTRY_POINTS
    • Options: v0.6, v0.7, v0.8, v0.9
  • --num_signers: Number of signers (and workers) to use for bundle building. Each worker handles all configured entrypoints via the shared signer architecture. (default: 1)
    • env: NUM_SIGNERS
    • NOTE: Workers share signers and dynamically select entrypoints based on mempool state. See builder architecture for details.
  • --da_gas_tracking_enabled: Enable the DA gas tracking feature of the mempool (default: false)
    • env: DA_GAS_TRACKING_ENABLED
  • --max_expected_storage_slots: Optionally set the maximum number of expected storage slots to submit with a conditional transaction. (default: None)
    • env: MAX_EXPECTED_STORAGE_SLOTS
  • --enabled_aggregators: List of enabled aggregators.
  • --aggregator_options: List of aggregator specific options
    • env: ENABLED_AGGREGATORS
    • List of KEY=VALUE delimited by ',': i.e. ENABLED_AGGREGATORS="KEY1=VALUE1,KEY2=VALUE2"
    • Options: see aggregator.rs
  • --provider_client_timeout_seconds: Timeout in seconds of external provider RPC requests (default: 10)
    • env: PROVIDER_CLIENT_TIMEOUT_SECONDS
  • --provider_rate_limit_retry_enabled: Enable retries on rate limit errors - with default backoff settings (default: false)
    • env: PROVIDER_RATE_LIMIT_RETRY_ENABLED
  • --provider_consistency_retry_enabled: Enable retries on block consistency errors - with default backoff settings (default: false)
    • env: PROVIDER_CONSISTENCY_RETRY_ENABLED
  • --eip7702_authority_pending_check_enabled: Enable checking for EIP-7702 authority pending transaction errors (default: false)
    • env: EIP7702_AUTHORITY_PENDING_CHECK_ENABLED
    • NOTE: This uses the NODE_RPC and thus is only viable on networks with P2P mempools. L2s with centralized sequencers will not work.

Metrics Options

Options for the metrics server:

  • --metrics.port: Port to listen on for metrics requests. default: 8080.
    • env: METRICS_PORT
  • --metrics.host: Host to listen on for metrics requests. default: 0.0.0.0.
    • env: METRICS_HOST
  • --metrics.tags: Tags for metrics in the format key1=value1,key2=value2,....
    • env: METRICS_TAGS
  • --metrics.sample_interval_millis: Sample interval to use for sampling metrics. default: 1000.
    • env: METRICS_SAMPLE_INTERVAL_MILLIS

Logging Options

Options for logging:

  • RUST_LOG environment variable is used for controlling log level see: env_logger. Only level is supported.
  • --log.file: Log file. If not provided, logs will be written to stdout.
    • env: LOG_FILE
  • --log.json: If set, logs will be written in JSON format.
    • env: LOG_JSON
  • --log.otlp_grpc_endpoint: If set, tracing spans will be forwarded to the provided gRPC OTLP endpoint.
  • env: LOG_OTLP_GRPC_ENDPOINT

RPC Options

List of command line options for configuring the RPC API.

  • --rpc.port: Port to listen on for JSON-RPC requests (default: 3000)
    • env: RPC_PORT
  • --rpc.host: Host to listen on for JSON-RPC requests (default: 0.0.0.0)
    • env: RPC_HOST
  • --rpc.api: Which APIs to expose over the RPC interface (default: eth,rundler)
    • env: RPC_API
  • --rpc.timeout_seconds: Timeout for RPC requests (default: 20)
    • env: RPC_TIMEOUT_SECONDS
  • --rpc.max_connections: Maximum number of concurrent connections (default: 100)
    • env: RPC_MAX_CONNECTIONS
  • --rpc.corsdomain: Enable the cors functionality on the server (default: None and therefore corsdomain is disabled).
    • env: RPC_CORSDOMAIN
  • --rpc.pool_url: Pool URL for RPC (default: http://localhost:50051)
    • env: RPC_POOL_URL
    • Only required when running in distributed mode
  • --rpc.builder_url: Builder URL for RPC (default: http://localhost:50052)
    • env: RPC_BUILDER_URL
    • Only required when running in distributed mode
  • --rpc.permissions_enabled: True if user operation permissions are enabled on the RPC API (default: false)
    • env: RPC_PERMISSIONS_ENABLED
    • NOTE: Do not enable this on a public API - for internal, trusted connections only.
  • --rpc.priority_fee_suggested_buffer_percent: Priority fee buffer percent for gas price suggestions. The suggested priority fee will be this percent above the current required priority fee. (default: 30)
    • env: RPC_PRIORITY_FEE_SUGGESTED_BUFFER_PERCENT
  • --rpc.base_fee_suggested_buffer_percent: Base fee buffer percent for gas price suggestions. The suggested max fee will use a base fee multiplied by (100 + this value) / 100. (default: 50)
    • env: RPC_BASE_FEE_SUGGESTED_BUFFER_PERCENT

Pool Options

List of command line options for configuring the Pool.

  • --pool.port: Port to listen on for gRPC requests (default: 50051)
    • env: POOL_PORT
    • Only required when running in distributed mode
  • --pool.host: Host to listen on for gRPC requests (default: 127.0.0.1)
    • env: POOL_HOST
    • Only required when running in distributed mode
  • --pool.max_size_in_bytes: Maximum size in bytes for the pool (default: 500000000, 0.5 GB)
    • env: POOL_MAX_SIZE_IN_BYTES
  • --pool.same_sender_mempool_count: Maximum number of user operations for an unstaked sender (default: 4)
    • env: POOL_SAME_SENDER_MEMPOOL_COUNT
  • --pool.min_replacement_fee_increase_percentage: Minimum replacement fee increase percentage (default: 10)
    • env: POOL_MIN_REPLACEMENT_FEE_INCREASE_PERCENTAGE
  • --pool.blocklist_path: Path to a blocklist file (e.g blocklist.json, s3://my-bucket/blocklist.json)
    • env: POOL_BLOCKLIST_PATH
    • This path can either be a local file path or an S3 url. If using an S3 url, Make sure your machine has access to this file.
    • See here for details.
  • --pool.allowlist_path: Path to an allowlist file (e.g allowlist.json, s3://my-bucket/allowlist.json)
    • env: POOL_ALLOWLIST_PATH
    • This path can either be a local file path or an S3 url. If using an S3 url, Make sure your machine has access to this file.
    • See here for details.
  • --pool.chain_poll_interval_millis: Interval at which the pool polls an Eth node for new blocks (default: 100)
    • env: POOL_CHAIN_POLL_INTERVAL_MILLIS
  • --pool.chain_sync_max_retries: The amount of times to retry syncing the chain before giving up and waiting for the next block (default: 5)
    • env: POOL_CHAIN_SYNC_MAX_RETRIES
  • --pool.paymaster_tracking_enabled: Boolean field that sets whether the pool server starts with paymaster tracking enabled (default: true)
    • env: POOL_PAYMASTER_TRACKING_ENABLED
  • --pool.paymaster_cache_length: Length of the paymaster cache (default: 10_000)
    • env: POOL_PAYMASTER_CACHE_LENGTH
  • --pool.reputation_tracking_enabled: Boolean field that sets whether the pool server starts with reputation tracking enabled (default: true)
    • env: POOL_REPUTATION_TRACKING_ENABLED
  • --pool.drop_min_num_blocks: The minimum number of blocks that a UO must stay in the mempool before it can be requested to be dropped by the user (default: 10)
    • env: POOL_DROP_MIN_NUM_BLOCKS
  • --pool.max_time_in_pool_secs: The maximum amount of time a UO is allowed to be in the mempool, in seconds. (default: None)
    • env: POOL_MAX_TIME_IN_POOL_SECS
  • --pool.suspect_tracking_enabled: Master switch for poison user operation handling — suspect tracking, isolation, and removal (default: false)
    • env: POOL_SUSPECT_TRACKING_ENABLED
    • When disabled, bundle outcomes change no UO state and the pool.*suspect* options below have no effect.
  • --pool.rpc_failures_before_suspect: Number of non-terminal RPC submission failures before a UO becomes a suspect and is only submitted alone (default: 3)
    • env: POOL_RPC_FAILURES_BEFORE_SUSPECT
    • See poison user operations for details. With a single builder signer, the scheduler cannot guarantee progress for both suspect and normal work when both remain continuously eligible.
  • --pool.max_suspect_rpc_failures: Number of non-terminal RPC submission failures a suspect is allowed before it is removed from the pool. 0 disables removal. (default: 8)
    • env: POOL_MAX_SUSPECT_RPC_FAILURES
    • The suspect backoff schedule spaces these failures; a provider incident outlasting the cumulative backoff can remove healthy UOs. Raise this threshold to tolerate longer incidents.
  • --pool.suspect_rpc_backoff_initial_secs: Initial delay in seconds between suspect isolation attempts, doubling with each failure (default: 1)
    • env: POOL_SUSPECT_RPC_BACKOFF_INITIAL_SECS
  • --pool.suspect_rpc_backoff_max_secs: Maximum delay in seconds between suspect isolation attempts (default: 600)
    • env: POOL_SUSPECT_RPC_BACKOFF_MAX_SECS

Builder Options

List of command line options for configuring the Builder.

  • --builder.port: Port to listen on for gRPC requests (default: 50051)
    • env: BUILDER_PORT
    • Only required when running in distributed mode
  • --builder.host: Host to listen on for gRPC requests (default: 127.0.0.1)
    • env: BUILDER_HOST
    • Only required when running in distributed mode
  • --builder.max_bundle_size: Maximum number of ops to include in one bundle (default: 128)
    • env: BUILDER_MAX_BUNDLE_SIZE
  • --builder.max_blocks_to_wait_for_mine: After submitting a bundle transaction, the maximum number of blocks to wait for that transaction to mine before trying to resend with higher gas fees (default: 2)
    • env: BUILDER_MAX_BLOCKS_TO_WAIT_FOR_MINE
  • --builder.replacement_fee_percent_increase: Percentage amount to increase gas fees when retrying a transaction after it failed to mine (default: 10)
    • env: BUILDER_REPLACEMENT_FEE_PERCENT_INCREASE
  • --builder.max_cancellation_fee_increases: Maximum number of cancellation fee increases to attempt (default: 15)
    • env: BUILDER_MAX_CANCELLATION_FEE_INCREASES
  • --builder.max_replacement_underpriced_blocks: The maximum number of blocks to wait in a replacement underpriced state before issuing a cancellation transaction (default: 20)
    • env: BUILDER_MAX_REPLACEMENT_UNDERPRICED_BLOCKS
  • --builder.sender: Choice of what sender type to use for transaction submission. (default: raw, options: raw, flashbots, bloxroute, polygonprivate)
    • env: BUILDER_SENDER
  • --builder.submit_url: Only used if builder.sender == "raw" or "polygonprivate." If present, the URL of the ETH provider that will be used to send transactions. Defaults to the value of node_http. Not used by the fallback sender, which always submits to node_http.
    • env: BUILDER_SUBMIT_URL
  • --builder.use_conditional_rpc: Only used if builder.sender == "raw." Use eth_sendRawTransactionConditional when submitting. (default: false)
    • env: BUILDER_USE_CONDITIONAL_RPC
  • --builder.flashbots_relay_builders: Only used if builder.sender == "flashbots." Additional builders to send bundles to through the Flashbots relay RPC (comma-separated). List of builders that the Flashbots RPC supports can be found here. (default: flashbots)
    • env: BUILDER_FLASHBOTS_RELAY_BUILDERS
  • --builder.flashbots_relay_auth_key: Only used/required if builder.sender == "flashbots." Authorization key to use with the flashbots relay. See here for more info. (default: None)
    • env: BUILDER_FLASHBOTS_RELAY_AUTH_KEY
  • --builder.bloxroute_auth_header: Only used/required if builder.sender == "bloxroute." If using the bloxroute transaction sender on Polygon, this is the auth header to supply with the requests. (default: None)
    • env: BUILDER_BLOXROUTE_AUTH_HEADER
  • --builder.sender_recovery_interval_secs: Enable automatic failover to a raw sender when a non-raw builder.sender is unavailable, set to the number of seconds to remain on the fallback before re-attempting the primary. The fallback always submits to node_http, never to builder.submit_url. Has no effect when builder.sender == "raw." (default: None, no fallback configured)
    • env: BUILDER_SENDER_RECOVERY_INTERVAL_SECS
  • --builder.sender_failure_threshold: Number of consecutive unavailable responses from the primary sender before activating the fallback. Only applies when builder.sender_recovery_interval_secs is set. (default: 3)
    • env: BUILDER_SENDER_FAILURE_THRESHOLD
  • --builder.pool_url: If running in distributed mode, the URL of the pool server to use. (default: http://localhost:50051)
    • env: BUILDER_POOL_URL
    • Only required when running in distributed mode
  • --builder.assigner_max_ops_per_request: Maximum number of operations requested from the mempool per entrypoint query. (default: 1024)
    • env: BUILDER_ASSIGNER_MAX_OPS_PER_REQUEST
  • --builder.assigner_starvation_ratio: Starvation ratio for the assigner. This value acts as a multiplier on signer count (num_signers * starvation_ratio) before force-selecting a starved entrypoint. For example, with 4 signers and the default ratio of 0.50, an entrypoint is force-selected after 2 idle cycles. (default: 0.50)
    • env: BUILDER_ASSIGNER_STARVATION_RATIO
  • --builder.rate_limit_backoff_initial_millis: Initial delay a builder waits before its next submission after the submission endpoint rate limited it. Doubles (with jitter) on each consecutive rate-limited attempt. Any attempt that is not rate limited resets it. (default: 100)
    • env: BUILDER_RATE_LIMIT_BACKOFF_INITIAL_MILLIS
  • --builder.rate_limit_backoff_max_millis: Maximum delay a builder waits between submissions while the submission endpoint is rate limiting it. (default: 2000)
    • env: BUILDER_RATE_LIMIT_BACKOFF_MAX_MILLIS

Signer Options

  • --signer.private_keys: Private keys to use for signing transactions, separated by ,
    • env: SIGNER_PRIVATE_KEYS
  • --signer.mnemonic: Mnemonic to use for signing transactions
    • env: SIGNER_MNEMONIC
  • --signer.aws_kms_key_ids: AWS KMS key IDs to use for signing transactions, separated by ,.
    • env: SIGNER_AWS_KMS_KEY_IDS
    • To enable signer locking see SIGNER_ENABLE_KMS_LOCKING.
  • --signer.aws_kms_grouped_keys: AWS KMS key ids grouped to keys in aws_kms_key_ids Separated by ,. Groups are made based on the number of signers required. There must be enough signers to make a full group for every entry in aws_kms_key_ids.
    • env: SIGNER_AWS_KMS_GROUPED_KEYS
  • --signer.enable_kms_locking: True if keys should be locked before use. Only applies to keys in aws_kms_key_ids.
    • env: SIGNER_ENABLE_KMS_LOCKING
  • --signer.redis_uri: Redis URI to use for KMS leasing (default: "")
    • env: SIGNER_REDIS_URI -Only required when SIGNER_ENABLE_KMS_LOCKING is set
  • --signer.redis_lock_ttl_millis: Redis lock TTL in milliseconds (default: 60000)
    • env: SIGNER_REDIS_LOCK_TTL_MILLIS
    • Only required when SIGNER_ENABLE_KMS_LOCKING is set
  • --signer.enable_kms_funding: Whether to enable kms funding from aws_kms_key_ids to the key ids in aws_kms_key_groups. (default: false)
    • env: SIGNER_ENABLE_KMS_FUNDING
  • --signer.fund_below: If KMS funding is enabled, this is the signer balance value below which to trigger a funding event
    • env: SIGNER_FUND_BELOW
  • --signer.fund_to: If KMS funding is enabled, this is the signer balance to fund to during a funding event
    • env: SIGNER_FUND_TO
  • --signer.funding_txn_poll_interval_ms: During funding, this is the poll interval for transaction status (default: 1000)
    • env: SIGNER_FUNDING_TXN_POLL_INTERVAL_MS
  • --signer.funding_txn_poll_max_retries: During funding, this is the maximum amount of time to poll for transaction status before abandoning (default: 20)
    • env: SIGNER_FUNDING_TXN_POLL_MAX_RETRIES
  • --signer.funding_txn_priority_fee_multiplier: During funding, this is the multiplier to apply to the network priority fee (default: 2.0)
    • env: SIGNER_FUNDING_TXN_PRIORITY_FEE_MULTIPLIER
  • --signer.funding_txn_base_fee_multiplier: During funding, this is the multiplier to apply to the network base fee (default: 2.0)
    • env: SIGNER_FUNDING_TXN_BASE_FEE_MULTIPLIER

Signing schemes

Rundler supports multiple ways to sign bundle transactions. In configuration precedence order:

  1. KMS locked master key with funded sub-keys: --signer.enable_kms_funding
  2. Private keys: --signer.private_keys
  3. Mnemonic: --signer.mnemonic
  4. KMS locked keys: --signer.aws_kms_key_ids

KMS Locking

If --signer.enable_kms_locking is set, keys that are listed in --signer.aws_kms_key_ids are always locked before usage so that they can be safely shared across multiple Rundler instances without nonce issues.

Locking uses Redis and thus a Redis URL must be provided to Rundler for key leasing to make sure keys are not accessed at the same time from concurrent processes.

KMS Funding

If --signer.enable_kms_funding is set this scheme will be enabled. It will look for subkeys in the following precedence order:

  1. aws_kms_grouped_keys: Must have enough signers to make a full group for each aws_kms_key_ids. Group size is based on number of signers requested.
    • If locking is enabled, once a funding KMS key is locked, the corresponding group is used for all subkeys.
    • Else, the first group is always used
  2. private_keys: Private keys for the subkeys. The same list applies regardless of which KMS key is locked.
  3. mnemonic: Supports a mnemonic from which multiple subkeys can be derived. The same mnemonic applies regardless of which KMS key is locked

When funding is enabled, Rundler will run a background process that will fund keys whose balance has fallen below fund_below with a transaction from the funding key that increases their balance to fund_to.

Example Usage

Here are some example commands to use the CLI:

# Run the Node subcommand with custom options
$ ./rundler node --network dev --node_http http://localhost:8545 --signer.private_keys 0x0000000000000000000000000000000000000000000000000000000000000001

# Run the RPC subcommand with custom options and enable JSON logging. The builder (localhost:50052) and pool (localhost:50051) will need to be running before this starts.
$ ./rundler rpc --network dev --node_http http://localhost:8545 --log.json

# Run the Pool subcommand with custom options and specify a mempool config file
$ ./target/debug/rundler pool --network dev --max_simulate_handle_ops_gas 15000000 --mempool_config_path mempool.json --node_http http://localhost:8545