CONFIG.md

March 3, 2026 ยท View on GitHub

Parameters that can come from an env var must be set as "env:XXXX" where XXXX is the name of the var. Every field has a default if omitted.

Main fields

NameTypeCommentsDefault
full_telemetry_server_portint6069
full_telemetry_server_ipstring"0.0.0.0"
redacted_telemetry_server_portint6070
redacted_telemetry_server_ipstring"0.0.0.0"
log_jsonboolJSON vs Rawfalse
log_levelenv/stringDefines the log level (EnvFilter) for each mod. See https://docs.rs/tracing-subscriber/latest/tracing_subscriber/index.html for more info on this."info"
log_colorboolfalse
otlp_env_nameoptional stringName of the OTEL environment (e.g. production, staging).None
error_storage_pathoptional stringPath to a sqlite file that will store info for some critical errorsNone
coinbase_secret_keyoptional env/stringIf no key is provided a random one is generated. Format is "0x121232432...."None
el_node_ipc_pathoptional stringPath for Ipc communication with reth's mempool, Usually something like "/tmp/reth.ipc". If not set mempool will not be used as a source of txsNone
jsonrpc_server_portint8645
jsonrpc_server_ipstring"0.0.0.0"
jsonrpc_server_max_connectionsoptional intMax connections for JSON-RPC server. If omitted, 4096 is used.None (effective 4096)
ignore_cancellable_ordersboolIf true any order with replacement id will be droppedtrue
ignore_blobsboolIf true txs with blobs will be ignoredfalse
chainstring"mainnet"
reth_datadiroptional stringIt will assume default child dirs "db"/"static_files".
It's mandatory to set reth_datadir or reth_db_path+reth_static_files_path or ipc_provider
"/mnt/data/reth"
reth_db_pathoptional stringIt's mandatory to set reth_datadir or reth_db_path+reth_static_files_path or ipc_providerNone
reth_static_files_pathoptional stringIt's mandatory to set reth_datadir or reth_db_path+reth_static_files_path or ipc_providerNone
ipc_provideroptional objectIf set, use IPC for EVM state instead of local reth db. Fields: ipc_path (path), request_timeout_ms (u64, default 100), mempool_server_url (string).None
blocklist_file_pathoptional stringBackwards compatibility. Downloads blocklist from a file. Same as setting a file name on blocklist.None
blocklistoptional stringCan contain an url or a file name.
If it's a url download blocklist from url and updates periodically.
If it's a filename just loads the file (no updates).
None
blocklist_url_max_age_hoursoptional intIf the downloaded file get older than this we abort.None
blocklist_url_max_age_secsoptional intIf the downloaded file get older than this we abort. Used for debugging onlyNone
require_non_empty_blocklistoptional boolIf true, will not allow start without a blocklist or with an empty blocklist.false
extra_datastringExtra data for generated blocks"extra_data_change_me"
simulation_threadsintNumber of threads used for incoming order simulation1
simulation_use_random_coinbasebooltrue
root_hash_use_sparse_trieboolUses cached sparse trie for root hash (much faster)false
root_hash_sparse_trie_versionstringSparse trie version: "v1" or "v2"."v1"
root_hash_compare_sparse_trieboolIf using sparse trie also computes against reth's native version to check the hash is okfalse
root_hash_threadsintThreads used when using reth's native root hash calculation. If 0 global rayon pool is used0
adjust_finalized_blocksboolUse pipelined finalization (blocks prefinalized first, payment tx inserted later for faster bidding).false
watchdog_timeout_secoptional intIf no block building is started in this period rbuilder exits.None
live_buildersvec[string]List of builders to be used for live building.
Notice that you can define on builders some builders and select only a few here.
["mgp-ordering","mp-ordering"]
evm_caching_enableboolIf enabled per block EVM execution will be enabledfalse
faster_finalizeboolIf enabled improves block finalization by catching proofsfalse
time_to_keep_mempool_txs_secsu64After this time a mempool tx is dropped.60
system_recipient_allowlistvec[Address]Senders from which incoming tx profit is not counted towards coinbase profit.[]
backtest_fetch_mempool_data_direnv/stringDir used to store mempool data used in backtesting"/mnt/data/mempool"
backtest_fetch_eth_rpc_urlstringurl to EL node RPC used in backtesting"http://127.0.0.1:8545"
backtest_fetch_eth_rpc_parallelintNumber of parallel connections allowed on backtest_fetch_eth_rpc_url1
backtest_fetch_output_filestringPath to a sqlite containing block information for backtesting. This file is filled with backtest-fetch"/tmp/rbuilder-backtest.sqlite"
backtest_results_store_pathstringPath to a sqlite containing backtest results"/tmp/rbuilder-backtest-results.sqlite"
backtest_buildersvec[string]List of builders to be used for backtesting.
Notice that you can define on builders some builders and select only a few here.
[]
backtest_protect_bundle_signersvec[string]Doc pending.[]
orderflow_tracing_store_pathoptional stringWe will store a file per block in this path.None
orderflow_tracing_max_blocksintMax number of blocks to keep on disk. Set > 0 if you enable orderflow_tracing_store_path.0
max_order_execution_duration_warning_usoptional u64If set, log a warning when an order execution exceeds this duration (microseconds).None
NameTypeCommentsDefault
relaysvec[RelayConfig]List of relays used to get validator registration info and/or submitting. Below are the details for RelayConfig fields. Example:
[[relays]]
name = "relay1"
optimistic = true
priority = 1
url = "https://relay1"
use_gzip_for_submit = true
use_ssz_for_submit = true
mode:full

[[relays]]
name = "relay2"
...more params...
[]
registration_update_interval_msoptional u64Period used to refresh validators registration info.5000
RelayConfig.namemandatory stringHuman readable name for the relay
RelayConfig.urlmandatory stringUrl to relay's endpoint
RelayConfig.grpc_urloptional stringUrl to relay's gRPC endpoint (only bloxroute at 2025/08/20).None
RelayConfig.authorization_headeroptional env/stringIf set "authorization" header will be added to RPC callsNone
RelayConfig.builder_id_headeroptional env/stringIf set "X-Builder-Id" header will be added to RPC callsNone
RelayConfig.api_token_headeroptional env/stringIf set "X-Api-Token" header will be added to RPC callsNone
RelayConfig.modestringValid values:
"full": Relay will be used to get validator registration info and for submitting blocks
"slot_info": Relay will be used to get validator registration info
"test": Relay will be used for submitting blocks and extra metadata will be added
"full"
RelayConfig.use_ssz_for_submitoptional boolfalse
RelayConfig.use_gzip_for_submitoptional boolfalse
RelayConfig.optimisticoptional boolfalse
RelayConfig.interval_between_submissions_msoptional intCaps the submission rate to the relayNone
RelayConfig.max_bid_ethoptional stringMax bid we can submit to this relay. Any bid above this will be skipped.
None -> No limit.
None
RelayConfig.adjustment_fee_payeroptional stringAddress that pays bid adjustment fees for this relay.None
RelayConfig.submit_config.optimistic_v3boolUse optimistic V3 submissions for this relay.false
RelayConfig.submit_config.optimistic_v3_bid_adjustment_requiredboolWhether bid adjustments are required for optimistic V3.false
RelayConfig.submit_config.optimistic_v3_max_bid_ethoptional stringDo not use optimistic V3 when bid value is above this (ETH). None = no cap.None
RelayConfig.is_bloxrouteboolSet to true for bloxroute relays to add extra headers.false
RelayConfig.bloxroute_rproxy_regionsvec[string]Bloxroute rproxy regions to try, in order of preference.[]
RelayConfig.bloxroute_rproxy_onlyboolIf true, only submit to bloxroute rproxy endpoints when available.false
RelayConfig.ask_for_filtering_validatorsoptional boolAdds "filtering=true" as query to the call relay/v1/builder/validators to get all validators (including those filtering OFAC).
On 2025/06/24 only supported by ultrasound.
false
RelayConfig.can_ignore_gas_limitoptional boolIf we submit a block with a different gas than the one the validator registered with in this relay the relay does not mind. Useful for gas limit conflicts. On 2025/08/20 only ultrasound confirmed that is ok with this. (we didn't asked the rest yet)false
enabled_relaysvec[string]Extra hardcoded relays to add (see DEFAULT_RELAYS in config.rs)[]
relay_secret_keyoptional env/stringSecret key that will be used to sign submissions to the relay.None
cl_node_urlvec[env/string]Array of urls to CL clients to get the new payload events.["http://127.0.0.1:3500"]
genesis_fork_versionoptional stringGenesis fork version for the chain. If not provided it will be fetched from the beacon client.None
relay_bid_scrapersSee bid scraper publishersEmpty
optimistic_v3_server_ipstringOptimistic V3 server bind IP."0.0.0.0"
optimistic_v3_server_portintOptimistic V3 server port.6071
optimistic_v3_public_urlstringPublic URL where relays can fetch blocks (for optimistic V3).""
optimistic_v3_relay_pubkeysset[string]BLS public keys of relays that may use optimistic V3.[]

Building algorithms

rbuilder can use multiple building algorithms and each algorithm can be instantiated multiple times with it's own set of parameters each time. Each instantiated algorithm starts with:

NameTypeCommentsDefault
namemandatory stringName of the instance. Referenced on live_builders/backtest_builders
algomandatory stringAlgorithm to use. Currently we have 2 algorithms:
- "ordering-builder": Uses OrderingBuildingAlgorithm
- "parallel-builder": (Experimental) Uses ParallelBuilder.

Fields for algo="ordering-builder"

NameTypeCommentsDefault
discard_txsmandatory boolIf a tx inside a bundle fails with TransactionErr (don't confuse this with reverting which is TransactionOk with !.receipt.success) and it's configured as allowed to revert (for bundles tx in reverting_tx_hashes or dropping_tx_hashes) we continue the execution of the bundle. The most typical value is true.
sortingmandatory stringValid values:
-"mev-gas-price": Sorts the SimulatedOrders by its effective gas price. This not only includes the explicit gas price set in the tx but also the direct coinbase payments so we compute it as (coinbase balance delta after executing the order) / (gas used).
-"max-profit": Sorts the SimulatedOrders by its absolute profit which is computed as the coinbase balance delta after executing the order.
-"type-max-profit": (Experimental) Orders are ordered by their origin (bundle then mempool) and then by their absolute profit.
-"length-three-max-profit":(Experimental) Orders are ordered by length 3 (orders length >= 3 first) and then by their absolute profit.
-"length-three-mev-gas-price":(Experimental) Orders are ordered by length 3 (orders length >= 3 first) and then by their mev gas price.
failed_order_retriesmandatory intOnly when a tx fails because the profit was worst than expected: Number of time an order can fail during a single block building iteration.
When thi happens it gets reinserted in the PrioritizedOrderStore with the new simulated profit (the one that failed).
drop_failed_ordersmandatory boolif a tx fails in a block building iteration it's dropped so next iterations will not use it.
build_duration_deadline_msoptional intAmount of time allocated for EVM execution while building block. If None it only stops when it tried all orders.None
pre_filtered_build_duration_deadline_msoptional intAmount of time allocated for EVM execution for the pre-filtered building step. If None it only stops when it tried all orders.
In this second building step the building algorithm will only try to include orders other algorithms landed in their last locks.
0
ignore_mempool_profit_on_bundlesboolWhen computing profit to prioritize orders on s/bundles any profit from a mempool tx will be ignored.false

Fields for algo="parallel-builder"

NameTypeCommentsDefault
discard_txsmandatory boolIf a tx inside a bundle fails with TransactionErr (don't confuse this with reverting which is TransactionOk with !.receipt.success) and it's configured as allowed to revert (for bundles tx in reverting_tx_hashes or dropping_tx_hashes) we continue the execution of the bundle. The most typical value is true.
num_threadsmandatory intNumber of threads to use for merging.
safe_sorting_onlyboolOnly use sort modes that don't risk breaking "best refund for user" (avoids putting worst kickback first).true

Bidding fields

NameTypeCommentsDefault
slot_delta_to_start_bidding_msoptional intWhen the sample bidder (see TrueBlockValueBiddingService) will start bidding relative to the slot start.
Usually a negative number.
None
subsidyoptional stringValue added to the bids (see TrueBlockValueBiddingService).
The builder address must have enough balance for the subsidy.
Example: "1.23" for 1.23 ETH
None
subsidy_overridesvec[{relay, value}]Per-relay subsidy override. Example: [[subsidy_overrides]] relay = "flashbots_test2" value = "0.05"[]