Builder Configuration

This applies from the Gloas fork onwards. It configures how the validator client sources execution-payload bids from external builders under ePBS.

The validator client reads its external-builder settings from a YAML file named builder_definitions.yml in the validator directory (<datadir>/validators/builder_definitions.yml). The file contains:

• A global bid policy — min_bid and builder_boost_factor, applied to bids received over p2p (gossip) and used as the default for any builder that does not set its own.
• A list of builders to request bids from directly, each with optional per-builder overrides of the global policy.
• Per-validator configurations under validator_configs, managed through the standard keymanager API. Each map key is a validator public key.

Use GET, POST, and DELETE at /eth/v1/validator/{pubkey}/builder_config. GET returns the configuration in use. POST replaces the stored configuration. DELETE restores global inheritance.

Example

# Global bid policy: applies to p2p (gossip) bids, and is the default for any
# builder below that omits the corresponding field.
min_bid: 0                    # gwei — bids below this rank last; one wins only if nothing else is viable
builder_boost_factor: 100     # percent — 100 = neutral, >100 favors builders, 0 = prefer local

builders:
  # Minimal builder — inherits the global policy.
  - enabled: true
    url: "https://builder-a.example.com"
    max_execution_payment: 1000000000   # gwei — cap on the trusted execution payment

  # Builder overriding the globals and pinning the expected builder key.
  - enabled: true
    url: "https://builder-b.example.com"
    max_execution_payment: 1000000000
    min_bid: 500000000                  # override the global for this builder
    builder_boost_factor: 120           # override the global for this builder
    builder_pubkeys:                    # optional — reject a bid not signed by one of these keys
      - "0xa1b2c3d4..."
    # auth_data: "0x6275696c..."        # optional — defaults to the hostname of `url`

# Optional per-validator configuration.
# validator_configs:
#   "0x<validator-public-key>":
#     min_bid: 500000000
#     builders: []                 # explicitly disable direct builders for this validator

Comments are not preserved. The validator client rewrites this file when builder settings change through the keymanager API. Keep an annotated copy elsewhere if you rely on inline notes.

Fields

Top level (global bid policy)

Per builder (each entry under builders)

All byte fields (builder_pubkeys entries, auth_data) are 0x-prefixed hex strings. All payment values (min_bid, max_execution_payment) are in gwei.

The default auth_data excludes the scheme, credentials, port, path, query and fragment of the URL. For example, both https://builder.example.com and https://builder.example.com/ use builder.example.com. An internationalized hostname must use punycode. IPv6 addresses use compressed, bracketed hexadecimal form, such as [::1] or [::ffff:c000:201].

A builder that uses a different identity must agree explicit auth_data with the validator operator. Explicit values are signed exactly as configured. See the default authentication data specification.

How bids are selected

At block-production time the validator client requests a bid from each enabled builder with a url, and also considers bids seen over p2p. For each candidate bid:

• min_bid — a bid whose total value is below the applicable min_bid is ranked behind any floor-clearing candidate (including the local block) rather than dropped, so it wins only when nothing else is viable (e.g. the local build failed). Direct builders use their own (or the inherited per-validator) value; p2p bids use the validator’s min_bid.
• builder_boost_factor — the surviving bid’s value is scaled by its boost factor (boost × value ÷ 100) before being compared against the locally-built block. A factor below 100 favors the local block; above 100 favors the builder; 0 always prefers local; 2^64 − 1 strongly favors the builder. The factor is a multiplier, not an absolute override, so a zero-value bid still ranks 0 and loses to any non-zero local block.
• max_execution_payment — bounds how much of a builder’s (off-chain) execution payment counts toward its bid value. This applies only to direct builders; p2p bids carry no trusted execution payment.
• builder_pubkeys — for a direct builder, if non-empty, the returned bid must be signed by one of these keys or it is discarded.

The highest-value bid after these rules wins. Per-builder min_bid/builder_boost_factor apply only to bids requested directly by URL. For p2p bids, per-validator defaults override the global values.