Skip to main content

Configuration

Commit-Boost needs a configuration file detailing all the services that you want to run. Create a cb-config.toml and adjust it depending on which modules you plan to run.

For a full explanation of all the fields, check out here.

For some additional examples on config presets, check out here.

Minimal PBS setup on Holesky​

chain = "Holesky"

[pbs]
port = 18550

[[relays]]
url = ""

[metrics]
prometheus_config = "./docker/prometheus.yml"

You can find a list of MEV-Boost Holesky relays here. After the sidecar is started, it will expose a port (18550 in this example), that you need to point your CL to. This may be different depending on which CL you're running, check out here for a list of configuration guides.

Note that in this setup, the signer module will not be started.

Signer module​

Commit-Boost supports both local and remote signers. The signer module is responsible for signing the transactions that other modules generates. Please note that only one signer at a time is allowed.

Local signer​

To start a local signer module, you need to include its parameters in the config file

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

We currently support Lighthouse, Prysm, Teku and Lodestar's keystores so it's easier to load the keys. We're working on adding support for additional keystores. These are the expected file structures for each format:

Lighthouse

File structure:​

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

Config:​

[signer]
[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:​

[signer]
[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:​

[signer]
[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:​

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

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

Proxy keys store​

Proxy keys can be used to sign transactions with a different key than the one used to sign the block. Proxy keys are generated by the Signer module and authorized by the validator key. Each module have their own proxy keys, that can be BLS or ECDSA.

To persist proxy keys across restarts, you must enable the proxy store in the config file. There are 2 options for this:

File

The keys are stored in plain text in a file. This method is unsafe and should only be used for testing.

File structure​

<proxy_dir>
└── <MODULE_ID>
      └── bls
          ├── <PROXY_PUBKEY1>
          └── <PROXY_PUBKEY2>

Configuration​

[signer.local.store]
proxy_dir = "path/to/proxy_dir"

Where each <PROXY_PUBKEY> file contains the following:

{
  "secret": "0x...",
  "delegation": {
    "message": {
      "delegator": "0x...",
      "proxy": "0x..."
    },
    "signature": "0x..."
  }
}
ERC2335

The keys are stored in a ERC-2335 style keystore, among with a password. This way, you can safely share the keys directory so without the password they are useless.

File structure​

├── <keys_path>
│   └── <CONSENSUS_PUBLIC_KEY>
│       └── <MODULE_ID>
│           ├── bls/
│           │   ├── <PROXY_PUBLIC_KEY1>.json
│           │   ├── <PROXY_PUBLIC_KEY1>.sig
│           │   ├── <PROXY_PUBLIC_KEY2>.json
│           │   └── <PROXY_PUBLIC_KEY2>.sig
│           └── ecdsa/
│               ├── <PROXY_PUBLIC_KEY3>.json
│               └── <PROXY_PUBLIC_KEY3>.sig
└── <secrets_path>
    └── <CONSENSUS_PUBLIC_KEY>
        └── <MODULE_ID>
            ├── bls/
            │   ├── <PROXY_PUBLIC_KEY1>
            │   └── <PROXY_PUBLIC_KEY2>
            └── ecdsa
                └── <PROXY_PUBLIC_KEY3>

Configuration​

[signer.local.store]
keys_path = "path/to/keys"
secrets_path = "path/to/secrets"

Where the <PROXY_PUBLIC_KEY>.json files contain ERC-2335 keystore, the <PROXY_PUBLIC_KEY>.sig files contain the signature of the delegation, and <PROXY_PUBLIC_KEY> files contain the password to decrypt the keystores.

Remote signer​

You might choose to use an external service to sign the transactions. For now, we support Web3Signer but we're working on adding support for additional signers.

The parameters needed for the remote signer are:

[signer.remote]
url = "https://remote.signer.url"

Custom module​

We currently provide a test module that needs to be built locally. To build the module run:

bash scripts/build_local_modules.sh

This will create a Docker image called test_da_commit that periodically requests signatures from the validator, and a test_builder_log module that logs BuilderAPI events.

The cb-config.toml file needs to be updated as follows:

[pbs]
port = 18550

[[relays]]
url = ""

[signer]
[signer.loader]
format = "lighthouse"
keys_path = "/path/to/keys"
secrets_path = "/path/to.secrets"

[metrics]
prometheus_config = "./docker/prometheus.yml"

[[modules]]
id = "DA_COMMIT"
type = "commit"
docker_image = "test_da_commit"
sleep_secs = 5

[[modules]]
id = "BUILDER_LOG"
type = "events"
docker_image = "test_builder_log"

A few things to note:

  • We now added a signer section which will be used to create the Signer module.
  • There is now a [[modules]] section which at a minimum needs to specify the module id, type and docker_image. Additional parameters needed for the business logic of the module will also be here,

To learn more about developing modules, check out here.

Vouch​

Vouch is a multi-node validator client built by Attestant. Vouch is particular in that it also integrates a MEV-Boost client to interact with relays. The Commit-Boost PBS module is compatible with the Vouch blockrelay since it implements the Builder-API, just like relays do. For example, depending on your setup and preference, you may want to fetch headers from a given relay using Commit-Boost vs using the built-in Vouch blockrelay.

Configuration​

Get familiar on how to set up Vouch here.

You can setup Commit-Boost with Vouch in two ways. For simplicity, assume that in Vouch blockrelay.listen-address: 127.0.0.0:19550 and in Commit-Boost pbs.port = 18550.

Beacon Node to Vouch​

In this setup, the BN Builder-API endpoint will be pointing to the Vouch blockrelay (e.g. for Lighthouse you will need the flag --builder=http://127.0.0.0:19550).

Modify the blockrelay.config file to add Commit-Boost:

"relays": {
    "http://127.0.0.0:18550": {}
}

Beacon Node to Commit Boost​

In this setup, the BN Builder-API endpoint will be pointing to the PBS module (e.g. for Lighthouse you will need the flag --builder=http://127.0.0.0:18550).

This will bypass the blockrelay entirely so make sure all relays are properly configured in the [[relays]] section.

Note: this approach could also work if you have a multi-beacon-node setup, where some BNs fetch directly via Commit-Boost while others go through the blockrelay.

Notes​

  • It's up to you to decide which relays will be connected via Commit-Boost ([[relays]] section in the toml config) and which via Vouch (additional entries in the relays field). Remember that any rate-limit will be shared across the two sidecars, if running on the same machine.
  • You may occasionally see a timeout error during registrations, especially if you're running a large number of validators in the same instance. This can resolve itself as registrations will be cleared later in the epoch when relays are less busy processing other registrations. Alternatively you can also adjust the builderclient.timeout option in .vouch.yml.