Quick Start Guide

The collateral requirement to register a validator to ETHGas is currently *zero* ETH!

You can start using ETHGas today for FREE and earn higher rewards for every block 🥳

1

Set up Commit-Boost

2

Register validators to ETHGas

3

Earn higher rewards

That's it, you're earning higher rewards! You can sit back and relax 🏖️

This guide is a simplified quick start configuration that assumes a standard validator setup. For a full technical guide with every available configuration option, check out the repo README.

Commit-Boost

The ethgas-preconf-commit-boost-module repo contains everything needed to setup and run Commit-Boost as well as the ETHGas module. If you are already running an existing version of Commit-Boost, you can either:

1. Use this single repo instead for simpler configuration management.

2. Or, continue using your existing version, making sure to add the configuration, rpc_url, ETHGas [[relays]], etc.

To get started, clone the repo:

git clone https://github.com/ethgas-developer/ethgas-preconf-commit-boost-module.git

Copy docker-compose-example.yml as docker-compose.yml and make any required modifications.

cp docker-compose-example.yml docker-compose.yml

Create an empty .cb.env file and generate a new jwt for the signer module by running:

touch .cb.env
docker compose -f docker-compose.yml up cb_gen_jwt

Create a config.toml file and enter the following configuration:

touch config.toml

This is a minimal setup and does not cover all environment types. For a comprehensive list of all available configuration options, open the config.example.mainnet.toml file.

Mainnet

config.toml

chain = "Mainnet"

[pbs]
# Must be set to true to allow signers to work with PBS module.
with_signer = true

# Port to receive BuilderAPI calls from beacon node
# NOTE: This is the same as the default mev-boost port,
#       since this PBS module replaces the default mev-boost client 
port = 18550

# The PBS module needs one or more [[relays]] as defined below.
# The configuration options enable_timing_games, target_first_request_ms and frequency_get_header_ms are set as recommended defaults. If those default settings are not included, it may lead to reduced validator performance.
[[relays]]
id = "ethgas-us"
url = "https://0x88ef3061f598101ca713d556cf757763[e-mail]"
enable_timing_games = true
target_first_request_ms = 0
frequency_get_header_ms = 100

[[relays]]
id = "ethgas-eu"
url = "https://0x88ef3061f598101ca713d556cf757763[e-mail]"
enable_timing_games = true
target_first_request_ms = 0
frequency_get_header_ms = 100

[[relays]]
id = "ethgas-ap"
url = "https://0x88ef3061f598101ca713d556cf757763[e-mail]"
enable_timing_games = true
target_first_request_ms = 0
frequency_get_header_ms = 100

[signer]
port = 20000

Hoodi

Signers

This section continues the configuration of the config.toml file for the signer modules. Select the signer that you are using add the configuration below the [signer] section in your config.toml file

Local Signers

Lighthouse

File structure:

├── keys
│   ├── <PUBLIC_KEY_1>
│   │   └── voting-keystore.json
│   └── <PUBLIC_KEY_2>
│       └── voting-keystore.json
└── secrets
    ├── <PUBLIC_KEY_1>
    └── <PUBLIC_KEY_2>

Config:

config.toml

[signer.local.loader]
format = "lighthouse"
keys_path = "keys"
secrets_path = "secrets"

Prysm

File structure:

├── wallet
│   └── direct
│       └── accounts
│           └──all-accounts.keystore.json
└── secrets
    └── password.txt

Config:

config.toml

[signer.local.loader]
format = "prysm"
keys_path = "wallet/direct/accounts/all-accounts.keystore.json"
secrets_path = "secrets/password.txt"

Teku

File structure:

├── keys
│   ├── <PUBLIC_KEY_1>.json
│   └── <PUBLIC_KEY_2>.json
└── secrets
    ├── <PUBLIC_KEY_1>.txt
    └── <PUBLIC_KEY_2>.txt

Config:

config.toml

[signer.local.loader]
format = "teku"
keys_path = "keys"
secrets_path = "secrets"

Lodestar

File structure:

├── keys
│   ├── <PUBLIC_KEY_1>.json
│   └── <PUBLIC_KEY_2>.json
└── secrets
    └── password.txt

Config:

config.toml

[signer.local.loader]
format = "lodestar"
keys_path = "keys"
secrets_path = "secrets/password.txt"

All keys have the same password stored in secrets/password.txt

Nimbus

File structure:

├── keys
│   ├── <PUBLIC_KEY_1>
│   │   └── keystore.json
│   └── <PUBLIC_KEY_2>
│       └── keystore.json
└── secrets
    ├── <PUBLIC_KEY_1>
    └── <PUBLIC_KEY_2>

Config:

config.toml

[signer.local.loader]
format = "nimbus"
keys_path = "keys"
secrets_path = "secrets"

Remote Signers

Web3Signer

Web3Signer implements the same API as Commit-Boost, so there's no need to set up a Signer module. The parameters needed for the remote signer are:

config.toml

[signer.remote]
# URL of the Web3Signer instance
url = "https://remote.signer.url"

Dirk

Dirk is a distributed key management system that can be used to sign transactions. In this case the Signer module is needed as an intermediary between the modules and Dirk. The following parameters are needed:

config.toml

[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"

# 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
accounts = ["Wallet1", "DistributedWallet"]

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

• cert_path and key_path are the paths to the client certificate and key used to authenticate with Dirk.

• wallets is a list of wallets from which the Signer module will load all accounts as consensus keys. Generated proxy keys will have format <WALLET_NAME>/<ACCOUNT>/<MODULE_ID>/<UUID>, so accounts found with that pattern will be ignored.

• secrets_path is the path to the folder containing the passwords of the generated proxy accounts, which will be stored in <secrets_path>/<WALLET_NAME>/<ACCOUNT>/<MODULE_ID>/<UUID>.pass.

config.mainnet.toml

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

Delegation signatures will be stored in files with the format <proxy_dir>/delegations/<MODULE_ID>/<PROXY_KEY>.sig.

A full example of a config file with Dirk can be found here.

ETHGas Module

The ETHGas module is run each time you want to update your ETHGas account configuration. This includes actions like:

• Registering and deregistering validators

• Updating your entity name, etc.

Currently, the only authentication optoions are adding your EOA_SIGNING_KEY or ACCESS_JWT to the config directly (or through a .env file). An improvement is planned to allow the generation of an API key in the ETHGas validator UI that can then be reused in this module configuration file. This would provide an alternative method for validators who want to use a hardware wallet and/or multisig wallet for authentication.

Mainnet

config.toml

[[modules]]
id = "ETHGAS_COMMIT"
type = "commit"
env_file = ".cb.env"

docker_image = "ghcr.io/ethgas-developer/commitboost_ethgas_commit:latest"
exchange_api_base = "https://hoodi.app.ethgas.com"
entity_name = "..." # my_amazing_team
overall_wait_interval_in_second = 0
registration_mode = "standard" # standard, standard-mux, ssv, obol, skipped
enable_registration = true
enable_pricer = true
enable_builder = false
enable_ofac = false
collateral_per_slot = "0" # No collateral is currently required
builder_pubkey = "0x94a076b27f294dc44b9fd44d8e2b063fb129bc85ed047da1cefb82d16e1a13e6b50de31a86f5b233d1e6bbaca3c69173" # Titan, you could change it to any other registered builder pubkey
is_jwt_provided = false
query_pubkey = true
# Specify either eoa_signing_key or access_jwt & refresh_jwt depending on is_jwt_provided boolean value
# Alternatively, you can set EOA_SIGNING_KEY or ACCESS_JWT & REFRESH_JWT in .cb.env as env variables
eoa_signing_key = "0x..." # for registration in exchange, required if is_jwt_provided = false
access_jwt = "xxx.xxx.xxx" # required if is_jwt_provided = true
refresh_jwt = "xxx.xxx.xxx" # required if is_jwt_provided = true

Hoodi

Metrics and Logs

config.toml

# 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

Start the Signer module

For DVT validators or remote signer, you don't need to run this module.

For registration of non-DVT validators, run:

docker compose -f docker-compose.yml up cb_signer

✅ If your signer starts successfully, you should see the log similar to INFO Starting signing service version="0.8.0" commit_hash="f51f5bd61831fde943057b29ffd6e26e7eb23765" modules=["ETHGAS_COMMIT"] endpoint=0.0.0.0:20000 loaded_consensus=100 loaded_proxies=0 where loaded_consensus indicates the total number of loaded keys.

Start the ETHGas Commit module

You are advised to run this module at or after the 2nd slot of the current epoch, so you can have more time to configure the PBS module.

This module only needs to be run whenever you modify the configuration of this module, e.g. when you want to register or deregister a validator to the ETHGas Exchange, to change collateral settings, etc. Think of running this module as "Update my config and sync with ETHGas".

To register the validators to the ETHGas Exchange, run:

docker compose -f docker-compose.yml up cb_ethgas_commit

✅ You will see the log INFO successful registration, you can now sell preconfs on ETHGas! or INFO successful registration, the default pricer can now sell preconfs on ETHGas on behalf of you! if all goes well

❌ If the module encounters ConnectionRefused error when it tries to connect to http://cb_signer:20000/signer/v1/get_pubkeys, please wait for 20 minutes to retry.

Start the PBS module

Start the PBS module by running:

docker compose -f docker-compose.yml up cb_pbs

The default port used by the PBS module is the same default port as MEV-Boost. If you had previously configured a custom port for MEV-Boost, make sure you have configured that on the PBS module.

✅ You will see the log DEBUG register_validators{req_id=...}:handler{relay_id="ethgas"}: registration successful code=200 latency=...ms if all goes well.

Once the ETHGas Commit module has completed the registration process and right before the start of the next epoch, stop your existing MEV-Boost client, restart the beacon node with new builder endpoint (if the port is different), and immediately start the PBS module.

To hot reload the config without restarting the module, run:

docker compose -f docker-compose.yml exec cb_pbs curl -X POST http://localhost:18550/reload

✅ You will see the log INFO : config reload successful if the config reloads successfully.

Refer here for more details about hot reloading.