config.example.toml

# The main configuration file for the Commit-Boost sidecar.
# Some fields are optional and can be omitted, in which case the default value, if present, will be used.

# Chain spec ID. Supported values:
# A network ID. Supported values: Mainnet, Holesky, Sepolia, Helder.
# A custom object, e.g., chain = { genesis_time_secs = 1695902400, path = "/path/to/spec.json" }, with a path to a chain spec file, either in .json format (e.g., as returned by the beacon endpoint /eth/v1/config/spec), or in .yml format (see examples in tests/data).
# A custom object, e.g., chain = { genesis_time_secs = 1695902400, slot_time_secs = 12, genesis_fork_version = "0x01017000" }.
chain = "Holesky"

# Configuration for the PBS module
[pbs]
# Docker image to use for the PBS module.
# OPTIONAL, DEFAULT: ghcr.io/commit-boost/pbs:latest
docker_image = "ghcr.io/commit-boost/pbs:latest"
# Whether to enable the PBS module to request signatures from the Signer module (not used in the default PBS image)
# OPTIONAL, DEFAULT: false
with_signer = false
# Host to receive BuilderAPI calls from beacon node
# OPTIONAL, DEFAULT: 127.0.0.1
host = "127.0.0.1"
# Port to receive BuilderAPI calls from beacon node
# OPTIONAL, DEFAULT: 18550
port = 18550
# Whether to forward `status` calls to relays or skip and return 200
# OPTIONAL, DEFAULT: true
relay_check = true
# Whether to return after the first successful registration, or wait for all relays to respond
# OPTIONAL, DEFAULT: true
wait_all_registrations = true
# Timeout in milliseconds for the `get_header` call to relays. Note that the CL has also a timeout (e.g. 1 second) so
# this should be lower than that, leaving some margin for overhead
# OPTIONAL, DEFAULT: 950
timeout_get_header_ms = 950
# Timeout in milliseconds for the `submit_blinded_block` call to relays.
# OPTIONAL, DEFAULT: 4000
timeout_get_payload_ms = 4000
# Timeout in milliseconds for the `register_validator` call to relays.
# OPTIONAL, DEFAULT: 3000
timeout_register_validator_ms = 3000
# Whether to skip signature verification of headers against the relay pubkey
# OPTIONAL, DEFAULT: false
skip_sigverify = false
# Minimum bid in ETH that will be accepted from `get_header`
# Can be specified as a float or a string for extra precision (e.g. "0.01")
# OPTIONAL, DEFAULT: 0.0
min_bid_eth = 0.0
# List of URLs of relay monitors to send registrations to
# OPTIONAL
relay_monitors = []
# How late in milliseconds in the slot is "late". This impacts the `get_header` requests, by shortening timeouts for `get_header` calls to
# relays and make sure a header is returned within this deadline. If the request from the CL comes later in the slot, then fetching headers is skipped
# to force local building and miniminzing the risk of missed slots. See also the timing games section below
# OPTIONAL, DEFAULT: 2000
late_in_slot_time_ms = 2000
# Whether to enable extra validation of get_header responses, if this is enabled you need to set `rpc_url`
# OPTIONAL, DEFAULT: false
extra_validation_enabled = false
# Execution Layer RPC url to use for extra validation
# OPTIONAL
rpc_url = "http://abc.xyz"

# The PBS module needs one or more [[relays]] as defined below.
[[relays]]
# Relay ID to use in telemetry
# OPTIONAL, DEFAULT: URL hostname
id = "example-relay"
# Relay URL in the format scheme://pubkey@host
url = "http://0xa1cec75a3f0661e99299274182938151e8433c61a19222347ea1313d839229cb4ce4e3e5aa2bdeb71c8fcf1b084963c2@abc.xyz"
# Headers to send with each request for this relay
# OPTIONAL
headers = { X-MyCustomHeader = "MyCustomValue" }
# Whether to enable timing games, as tuned by `target_first_request_ms` and `frequency_get_header_ms`.
# These values should be carefully chosen for each relay, as each relay has different latency and timing games setups.
# They should only be used by advanced users, and if mis-configured can result in unforeseen effects, e.g. fetching a lower header value,
# or getting a temporary IP ban.
#
# EXAMPLES
# Assuming: timeout_get_header_ms = 950, frequency_get_header_ms = 300, target_first_request_ms = 200, late_in_slot_time_ms = 2000
#
# 1) CL request comes at 100ms in the slot (max timeout 1050ms in the slot), then:
#   - sleep for 100ms
#   - send request at 200ms with 850ms timeout
#   - send request at 500ms with 550ms timeout
#   - send request at 800ms with 250ms timeout
# 2) CL request comes at 1500ms in the slot (max timeout 2000ms in the slot), then:
#   - send request at 1500ms with 500ms timeout
#   - send request at 1800ms with 200ms timeout
# 3) CL request comes 2500ms in the slot then:
#   - return 204 and force local build
#
# OPTIONAL, DEFAULT: false
enable_timing_games = false
# Target time in slot when to send the first header request
# OPTIONAL
target_first_request_ms = 200
# Frequency in ms to send get_header requests
# OPTIONAL
frequency_get_header_ms = 300

# Configuration for the PBS multiplexers, which enable different configs to be used for get header requests, depending on validator pubkey
# Note that:
# - multiple sets of keys can be defined by adding multiple [[mux]] sections. The validator pubkey sets need to be disjoint
# - the mux is only used for get header requests
# - if any value is missing from the mux config, the default value from the main config will be used
[[mux]]
# Which validator pubkeys to match against this mux config
validator_pubkeys = [
    "0x80c7f782b2467c5898c5516a8b6595d75623960b4afc4f71ee07d40985d20e117ba35e7cd352a3e75fb85a8668a3b745",
    "0xa119589bb33ef52acbb8116832bec2b58fca590fe5c85eac5d3230b44d5bc09fe73ccd21f88eab31d6de16194d17782e",
]
timeout_get_header_ms = 900
late_in_slot_time_ms = 1500
# For each mux, one or more [[pbs_mux.relays]] can be defined, which will be used for the matching validator pubkeys
# Only the relays defined here will be used, and the rest of the relays defined in the main config will be ignored
# Any field defined here will override the default value from the relay config with the same id in [[relays]]
[[mux.relays]]
id = "example-relay"
headers = { X-MyCustomHeader = "ADifferentCustomValue" }

# Configuration for the Signer Module, only required if any `commit` module is present, or if `pbs.with_signer = true`
# OPTIONAL
[signer]
# Docker image to use for the Signer module.
# OPTIONAL, DEFAULT: ghcr.io/commit-boost/signer:latest
docker_image = "ghcr.io/commit-boost/signer:latest"
# Configuration for how the Signer module should load validator keys. Currently two types of loaders are supported:
#   - File: load keys from a plain text file (unsafe, use only for testing purposes)
#   - ValidatorsDir: load keys from a `keys` and `secrets` folder (ERC-2335 style keystores as used in Lighthouse)
[signer.loader]
# File: path to the keys file
key_path = "./keys.example.json"
# ValidatorsDir: path to the keys directory
# keys_path = ""
# ValidatorsDir: path to the secrets directory
# secrets_path = ""
# Configuration for how the Signer module should store proxy delegations. Currently one type of store is supported:
#   - File: store keys and delegations from a plain text file (unsafe, use only for testing purposes)
# OPTIONAL, if missing proxies are lost on restart
[signer.store]
# File: path to the keys file
proxy_dir = "./proxies"

# Commit-Boost can optionally run "modules" which extend the capabilities of the sidecar.
# Currently, two types of modules are supported:
#   - "commit": modules which request commitment signatures from the validator keys
#   - "events": modules which callback to BuilderAPI events as triggered from the PBS modules, used e.g. for monitoring
# If any "commit" module is present, then the [signer] section should also be configured
# OPTIONAL
[[modules]]
# Unique ID of the module
id = "DA_COMMIT"
# Type of the module. Supported values: commit, events
type = "commit"
# Docker image of the module
docker_image = "test_da_commit"
# Environment file for the module
env_file = ".cb.env"

# Additional config needed by the business logic of the module should also be set here.
# See also `examples/da_commit/src/main.rs` for more information
sleep_secs = 5

# Other environment variables for the module
[modules.env]
SOME_ENV_VAR = "some_value"


# Configuration for how metrics should be collected and scraped
# OPTIONAL, skip metrics collection if missing
[metrics]
# Host for prometheus, grafana, and cadvisor
# OPTIONAL, DEFAULT: 127.0.0.1
host = "127.0.0.1"
# Path to a `prometheus.yml` file to use in Prometheus. If using a custom config file, be sure to add a
# file discovery section as follows:
# ```yml
# file_sd_configs:
#   - files:
#       - /etc/prometheus/targets.json
# ```
# and use the `targets.json` file generated by `commit-boost-cli init`
prometheus_config = "./docker/prometheus.yml"
# Whether to start Grafana with built-in dashboards
# OPTIONAL, DEFAULT: true
use_grafana = true
# Whether to start cadvisor for system monitoring
# OPTIONAL, DEFAULT: true
use_cadvisor = true

# Configuration for how logs should be collected and stored
# OPTIONAL, info to stdout if missing
[logs]
# Path to the log directory
# OPTIONAL, DEFAULT: /var/logs/commit-boost
log_dir_path = "./logs"
# Log level. Supported values: trace, debug, info, warn, error
# OPTIONAL, DEFAULT: debug to file, info to stdout
log_level = "debug"
# Maximum number of log files to keep
# OPTIONAL
max_log_files = 30