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, Hoodi. Lower case values e.g. "mainnet" are also accepted
# 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", fulu_fork_slot = 5283840, chain_id = 17000 }. All fields are required.
chain = "Holesky"

# Configuration for the PBS service
[pbs]
# Docker image to use for the PBS service.
# OPTIONAL, DEFAULT: ghcr.io/commit-boost/commit-boost:latest
docker_image = "ghcr.io/commit-boost/commit-boost:latest"
# Whether to enable the PBS service to request signatures from the Signer service (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
# (from v0.12.0-rc1) ePBS bids only: ms kept back from the beacon node's X-Timeout-Ms deadline for
# Commit-Boost's answer to reach the beacon node. The default suits a beacon node on the same host; raise it when they
# run on different hosts. Must be above 0 and under one slot, 12000 on mainnet (https://commit-boost.github.io/commit-boost-client/get_started/epbs#timing)
# OPTIONAL, DEFAULT: 20
# proposer_deadline_buffer_ms = 20
# (from v0.12.0-rc1) ePBS only: whether to dial a builder the auth data names when none of the key's relay entries match it, else answer 400 (https://commit-boost.github.io/commit-boost-client/get_started/epbs#builders-outside-your-config)
# OPTIONAL, DEFAULT: true
# dial_unconfigured_builders = true
# 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 and pubkey matching 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
# 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 `rpc_url` must also be set
# OPTIONAL, DEFAULT: false
extra_validation_enabled = false
# Execution Layer RPC url to use for extra validation
# OPTIONAL
# rpc_url = "https://ethereum-holesky-rpc.publicnode.com"
# URL of your local SSV node API endpoint, if you have a mux that targets an SSV node operator
# OPTIONAL, DEFAULT: "http://localhost:16000/v1/"
# ssv_node_api_url = "http://localhost:16000/v1/"
# URL of the public SSV API server, if you have a mux that targets an SSV node operator. This is used as
# a fallback if the user's own SSV node is not reachable.
# OPTIONAL, DEFAULT: "https://api.ssv.network/api/v4/"
# ssv_public_api_url = "https://api.ssv.network/api/v4/"
# Timeout for any HTTP requests sent from the PBS service to other services, in seconds
# OPTIONAL, DEFAULT: 10
http_timeout_seconds = 10
# Maximum number of retries for validator registrations per relay
# OPTIONAL, DEFAULT: 3
register_validator_retry_limit = 3
# Maximum number of validators to register in a single request.
# OPTIONAL, DEFAULT: "" (unlimited)
validator_registration_batch_size = ""
# For any Registry-based Mux configurations that have dynamic pubkey
# refreshing enabled, this is how often to refresh the list of pubkeys
# from the registry, in seconds. Enabling registry refreshing is done per-mux
# with the mux's `enable_refreshing` property. If none of the muxes have it
# enabled, this value will not be used.
# OPTIONAL, DEFAULT: 384
mux_registry_refresh_interval_seconds = 384

# The PBS service 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, which is how a relay api key is supplied.
# A value is written one of three ways:
#   literal  -> headers = { X-Api-Key = "my-api-key" }
#   file     -> headers = { X-Api-Key = { file = "/run/secrets/relay-key" } }
#   env      -> headers = { X-Api-Key = { env = "RELAY_API_KEY" } }
# A file or env value is read at startup and on every config reload (see the configuration docs).
# OPTIONAL
headers = { X-MyCustomHeader = "MyCustomValue" }
# GET parameters to add to each request URL for this relay
# OPTIONAL
get_params = { param1 = "value1", param2 = "value2" }
# How to fetch headers from this relay.
#   "http"     -> one request per get_header, at the relay url above
#   "stream"   -> websocket stream of bid updates, only for relays that support it. Connects to
#                 ws(s)://<relay url>/eth/v1/builder/header_stream/{slot}/{parent_hash}/{pubkey}.
#                 Requires a UUID api key, set it in `headers` field above under the `X-Api-Key`
#                 name; it is sent on the websocket handshake. Can use 
#                 https://www.uuidgenerator.net/version4 to generate one.
#                 (from v0.12.0-rc1) After Gloas this also streams ePBS bids (https://commit-boost.github.io/commit-boost-client/get_started/epbs#bid-streaming)
# OPTIONAL, DEFAULT: "http"
get_header = "http"
# Whether to enable timing games, as tuned by `target_first_request_ms` and `frequency_get_header_ms`.
# NOTE: if neither `target_first_request_ms` nor `frequency_get_header_ms` is set, this flag has no effect.
#
# 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, and (from v0.12.0-rc1) ePBS bid and builder preferences requests
# - if any value is missing from the mux config, the default value from the main config will be used
[[mux]]
# Unique ID for the mux config
id = "test_mux"
# Which validator pubkeys to match against this mux config. This can be empty or omitted if a loader is specified.
# Any keys loaded via the loader will be added to this list.
validator_pubkeys = [
    "0x80c7f782b2467c5898c5516a8b6595d75623960b4afc4f71ee07d40985d20e117ba35e7cd352a3e75fb85a8668a3b745",
    "0xa119589bb33ef52acbb8116832bec2b58fca590fe5c85eac5d3230b44d5bc09fe73ccd21f88eab31d6de16194d17782e",
]
# Loader for validator pubkeys. Three types of loaders are supported:
#   - File: path to a file containing a list of validator pubkeys in JSON format
#   - URL: URL to an HTTP endpoint returning a list of validator pubkeys in JSON format
#   - Registry: details of a registry to load keys from. Supported registries:
#       - Lido: staking module registries. Requires the PBS `rpc_url` to be set, and accepts a `lido_module_id`
#         in the mux loader (defaults to 1); see the mux key loaders docs for the module ids per chain.
#       - SSV: SSV API
#       - Stader: Stader Permissioned/Permissionless NodePool (mainnet only). Requires the PBS `rpc_url` to be set (like Lido),
#         and a `stader_pool` ("permissioned" or "permissionless") in the mux loader.
#       You can toggle the 'enable_refreshing' flag to let this registry periodically query Lido, SSV, or Stader and refresh the list of validator pubkeys belonging to the corresponding operator.
#       Each of these registry entries must be unique:
#       - There can only be one Lido entry with a given Lido node operator ID.
#       - There can only be one SSV entry with a given SSV node operator ID.
#       - There can only be one Stader entry with a given pool and node operator ID.
#       - A Lido entry can have the same node operator ID as an SSV entry if they happen to coincide; they're treated as separate entities.
#
# Example JSON list:
# [
#   "0x80c7f782b2467c5898c5516a8b6595d75623960b4afc4f71ee07d40985d20e117ba35e7cd352a3e75fb85a8668a3b745",
#   "0xa119589bb33ef52acbb8116832bec2b58fca590fe5c85eac5d3230b44d5bc09fe73ccd21f88eab31d6de16194d17782e"
#]
# OPTIONAL
loader = "./tests/data/mux_keys.example.json"
# loader = { url = "http://localhost:8000/keys" }
# loader = { registry = "lido", node_operator_id = 8, lido_module_id = 1, enable_refreshing = false }
# Curated Module v2 (CMv2): lido_module_id = 4 on mainnet, 5 on hoodi
# loader = { registry = "lido", node_operator_id = 8, lido_module_id = 4, enable_refreshing = false }
# loader = { registry = "ssv", node_operator_id = 8, enable_refreshing = false }
# loader = { registry = "stader", node_operator_id = 8, stader_pool = "permissionless", enable_refreshing = false }
late_in_slot_time_ms = 1500
timeout_get_header_ms = 900
# For each mux, one or more [[mux.relays]] can be defined, which will be used for the matching validator pubkeys
# For `get_header`, only the relays defined here will be used, and the relays defined in the main [[relays]] config will be ignored
# (from v0.12.0-rc1) For ePBS, each key's builder config decides which builders are asked for that key (https://commit-boost.github.io/commit-boost-client/get_started/epbs#routing-by-auth-data)
# The fields specified here are the same as in [[relays]] (headers, get_params, get_header, enable_timing_games, target_first_request_ms, frequency_get_header_ms)
[[mux.relays]]
id = "mux-relay-1"
url = "http://0xa119589bb33ef52acbb8116832bec2b58fca590fe5c85eac5d3230b44d5bc09fe73ccd21f88eab31d6de16194d17782e@def.xyz"

# Configuration for the Signer service, only required if any `commit` module is present, or if `pbs.with_signer = true`
# Currently two types of Signer service are supported (only one can be used at a time):
#   - Dirk: a remote Dirk instance
#   - Local: a local Signer service
# More details on the docs (https://commit-boost.github.io/commit-boost-client/get_started/configuration/#signer-service)
[signer]
# Docker image to use for the Signer service.
# OPTIONAL, DEFAULT: ghcr.io/commit-boost/commit-boost:latest
docker_image = "ghcr.io/commit-boost/commit-boost:latest"
# Host to bind the Signer API server to
# OPTIONAL, DEFAULT: 127.0.0.1
host = "127.0.0.1"
# Port to listen for Signer API calls on
# OPTIONAL, DEFAULT: 20000
port = 20000
# Number of JWT authentication attempts a client can fail before blocking that client temporarily from Signer access
# OPTIONAL, DEFAULT: 3
jwt_auth_fail_limit = 3
# How long to block a client from Signer access, in seconds, if it failed JWT authentication too many times.
# This also defines the interval at which failed attempts are regularly checked and expired ones are cleaned up.
# OPTIONAL, DEFAULT: 300
jwt_auth_fail_timeout_seconds = 300

# HTTP header to use to determine the real client IP, if the Signer is behind a proxy (e.g. nginx)
# OPTIONAL. If missing, the client IP will be taken directly from the TCP connection.
# [signer.reverse_proxy]
# Type of reverse proxy configuration. Supported values:
# - unique: use a single HTTP header value as the client IP.
# - rightmost: use the rightmost IP from a comma-separated list of IPs in the HTTP header.
# type = "unique"
# Unique: HTTP header name to use to determine the real client IP. If the header appears multiple times, the request will be rejected.
# header = "X-Real-IP"
# Rightmost: HTTP header name to use to determine the real client IP from a comma-separated list of IPs. If the header appears multiple times, the last value will be used.
# header = "X-Forwarded-For"
# Rightmost: number of trusted proxies in front of the Signer, whose IPs will be skipped when extracting the client IP from the rightmost side of the list. Must be greater than 0.
# trusted_count = 1

# [signer.tls_mode]
# How to use TLS for the Signer's HTTP server; two modes are supported:
# - type = "insecure": disable TLS, so the server runs in HTTP mode (not recommended for production).
# - type = "certificate": Use TLS. Include a property named "path" below this with the provided path; `path` should be a directory containing existing `cert.pem` and `key.pem` files to use. They are NOT auto-generated: the Signer fails to start if either file is missing.
# OPTIONAL, DEFAULT:
# type = "insecure"

# For Remote signer:
# NOT IMPLEMENTED. The `[signer.remote]` (Web3Signer) variant parses, but the Signer service
# rejects it at startup with `Remote signer configured`. Dirk is currently the only supported
# remote signer; use `[signer.dirk]` below.
# [signer.remote]
# URL of the Web3Signer instance
# url = "https://remote.signer.url"
# For Dirk signer:
# [signer.dirk]
# Path to the client certificate to authenticate with Dirk
# cert_path = "/path/to/client.crt"
# Path to the client key
# key_path = "/path/to/client.key"
# Path to the secrets directory where the accounts passwords are stored
# secrets_path = "/path/to/secrets"
# Path to the CA certificate that signed the Dirk server certificate
# OPTIONAL
# ca_cert_path = "/path/to/ca.crt"
# Limits the maximum size of a decoded gRPC response
# OPTIONAL. Default: 4MB
# max_response_size_bytes = 4194304

# Add one entry like this for each Dirk host
# [[signer.dirk.hosts]]
# Domain name of the server to use in TLS verification, if different from the URL
# OPTIONAL
# server_name = "localhost-1"
# Complete URL of a Dirk gateway
# url = "https://localhost:8881"
# Wallets to load consensus keys from
# wallets = ["Wallet1", "DistributedWallet"]

# [[signer.dirk.hosts]]
# server_name = "localhost-2"
# url = "https://localhost:8882"
# wallets = ["Wallet2", "DistributedWallet"]

# Configuration for how the Signer service should store proxy delegations.
# OPTIONAL
# [signer.dirk.store]
# proxy_dir = "/path/to/proxies"

# For Local signer:
# Configuration for how the Signer service 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` file/folder (ERC-2335 style keystores). More details can be found in the docs (https://commit-boost.github.io/commit-boost-client/get_started/configuration/)
[signer.local.loader]
# File: path to the keys file
key_path = "./tests/data/keys.example.json"
# ValidatorsDir: format of the keystore (lighthouse, prysm, teku, lodestar, or nimbus)
# format = "lighthouse"
# ValidatorsDir: full path to the keys directory
# For lighthouse, it's the path to the directory where the `<pubkey>` directories are located, under each of which is a `voting-keystore.json` file.
# For prysm, it's the path to the `all-accounts.keystore.json` file.
# For teku, it's the path to the directory where all `<pubkey>.json` files are located.
# For lodestar, it's the path to the directory where all `<pubkey>.json` files are located.
# For nimbus, it's the path to the directory where the `<pubkey>` directories are located, under each of which is a `keystore.json` file.
# keys_path = ""
# ValidatorsDir: full path to the secrets file/directory
# For lighthouse, it's the path to the directory where the `<pubkey>` files are located.
# For prysm, it's the path to the file containing the wallet decryption password.
# For teku, it's the path to the directory where all `<pubkey>.txt` files are located.
# For lodestar, it's the path to the file containing the decryption password.
# For nimbus, it's the path to the directory where the `<pubkey>` files are located.
# secrets_path = ""
# Configuration for how the Signer service should store proxy delegations. Supported types of store are:
#   - File: store keys and delegations from a plain text file (unsafe, use only for testing purposes)
#   - ERC2335: store keys and delegations safely using ERC-2335 style keystores. More details can be found in the docs (https://commit-boost.github.io/commit-boost-client/get_started/configuration#proxy-keys-store)
# OPTIONAL, if missing proxies are lost on restart
[signer.local.store]
# File: path to the keys file
proxy_dir = "./proxies"
# ERC2335: path to the keys directory
# keys_path = "./tests/data/proxy/keys"
# ERC2335: path to the secrets directory
# secrets_path = "./tests/data/proxy/secrets"

# Commit-Boost can optionally run "modules" which extend the capabilities of the sidecar.
# Currently, one type of module is supported:
#   - "commit": modules which request commitment signatures from the validator keys
# If any "commit" module is present, then the [signer] section should also be configured
# OPTIONAL
[[modules]]
# Unique ID of the module
id = "DA_COMMIT"
# Unique hash that the Signer service will combine with the incoming data in signing requests to generate a signature specific to this module
signing_id = "0x6a33a23ef26a4836979edff86c493a69b26ccf0b4a16491a815a13787657431b"
# Type of the module. Supported values: commit
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]
# Whether to collect metrics
# OPTIONAL, DEFAULT: true
enabled = true
# Host to listen on for metrics
# OPTIONAL, DEFAULT: 127.0.0.1
host = "127.0.0.1"
# Services will listen for Prometheus scrapes on this port, port + 1, +2, etc.
# OPTIONAL, DEFAULT: 10000
start_port = 10000

# Configuration stdout logs
# OPTIONAL, DEFAULT: enabled
[logs.stdout]
# Whether to enable stdout logging
# OPTIONAL, DEFAULT: true
enabled = true
# Log level. Supported values: trace, debug, info, warn, error
# OPTIONAL, DEFAULT: info
level = "info"
# Log in JSON format
# OPTIONAL, DEFAULT: false
use_json = false
# Whether to enable ANSI color codes
# OPTIONAL, DEFAULT: true
color = true

# Configuration file logs
# OPTIONAL, DEFAULT: disabled
[logs.file]
# Whether to enable file logging
# OPTIONAL, DEFAULT: false
enabled = true
# Log level. Supported values: trace, debug, info, warn, error
# OPTIONAL, DEFAULT: info
level = "debug"
# Log in JSON format
# OPTIONAL, DEFAULT: true
use_json = true
# Path to the log directory
# OPTIONAL, DEFAULT: /var/logs/commit-boost
dir_path = "./logs"
# Maximum number of log files to keep
# OPTIONAL
max_files = 30