Skip to main content

Binary

warning

Running the modules natively means you opt out of the security guarantees made by Docker, and it is up to you to set up the modules and ensure they run safely.

Setup​

Get the binary of the module either by compiling from source or by downloading a published release.

Services need environment variables to work correctly.

Common​

  • CB_CONFIG: required, path to the .toml config file.
  • CB_CHAIN_SPEC: optional, path to a chain spec file. It overrides the path of the top-level chain key in the .toml config, and only when chain uses the spec-file form chain = { genesis_time_secs = ..., path = "..." } (see Custom chains). If chain is a network name (e.g. chain = "Holesky") or the fully-inline custom object, this variable is silently ignored.
  • CB_METRICS_PORT: optional, port where to expose the /metrics endpoint for Prometheus. Without it the module doesn't serve metrics, whatever [metrics] sets; commit-boost init sets it from start_port when [metrics] is enabled.
  • CB_LOGS_DIR: optional, directory to store logs. This will override the directory in the .toml config.

PBS Service​

  • CB_PBS_ENDPOINT: optional, override to specify the IP:port endpoint where the PBS service will open the port for the beacon node.
  • CB_MUX_PATH_{ID}: optional, override where to load mux validator keys for mux with id={ID}.

Signer Service​

  • CB_JWTS: required (the Signer service will not start without it), comma-separated list of module_id=jwt_secret pairs for module authentication.
  • CB_SIGNER_ADMIN_JWT: required, secret to use for admin JWT.
  • CB_SIGNER_JWT_AUTH_FAIL_LIMIT: optional, override the number of failed JWT auth attempts before rate-limiting a client (default: 3).
  • CB_SIGNER_JWT_AUTH_FAIL_TIMEOUT_SECONDS: optional, override the rate-limit timeout window in seconds (default: 300).
  • CB_SIGNER_ENDPOINT: optional, override to specify the IP:port endpoint to bind the signer server to.
  • CB_SIGNER_TLS_CERTIFICATES: optional, override of the TLS certificates directory (must contain cert.pem and key.pem). Only used when the signer's tls_mode is set to a certificate path.
  • For loading keys we currently support:
    • CB_SIGNER_LOADER_FILE: path to a .json with plaintext keys (for testing purposes only).
    • CB_SIGNER_LOADER_KEYS_DIR and CB_SIGNER_LOADER_SECRETS_DIR: paths to the keys and secrets directories or files (ERC-2335 style keystores, see Signer config for more info).
  • For storing proxy keys we currently support:
    • CB_PROXY_STORE_DIR: directory where proxy keys and delegations will be saved in plaintext (for testing purposes only).
    • CB_PROXY_KEYS_DIR and CB_PROXY_SECRETS_DIR: paths to the keys and secrets directories or files (ERC-2335 style keystores, see Proxy keys store for more info).
  • For Dirk remote signer the following envs are available (see Dirk config for more info):
    • CB_SIGNER_DIRK_CERT_FILE: optional, override of the cert_path in the [signer.dirk] config, path to the client certificate file.
    • CB_SIGNER_DIRK_KEY_FILE: optional, override of the key_path in the [signer.dirk] config, path to the client key file.
    • CB_SIGNER_DIRK_SECRETS_DIR: optional, override of the secrets_path in the [signer.dirk] config, path to the secrets directory.
    • CB_SIGNER_DIRK_CA_CERT_FILE: optional, path to the CA certificate file.

Modules​

  • CB_MODULE_ID: required, unique id of the module.

Commit modules​

  • CB_SIGNER_URL: required, url to the Signer service server.
  • CB_SIGNER_JWT: required, the module's pre-shared JWT secret, from which the module mints per-request tokens. Must be identical to this module's entry in the signer's CB_JWTS; generate one per module (e.g. openssl rand -hex 32). See Module JWT.

Modules might also have additional envs required, which should be detailed by the maintainers.

Start​

After creating the cb-config.toml file, set up the required envs and run the binary. For example:

CB_CONFIG=./cb-config.toml commit-boost pbs

Or for the Signer service:

CB_CONFIG=./cb-config.toml CB_JWTS="MY_MODULE=<secret>" CB_SIGNER_ADMIN_JWT="<secret>" commit-boost signer

For a worked signer startup, see Verifying the Signer Service.