Proposer settings

Proposer settings define how your validator client proposes blocks: the fee recipient address, gas limit, graffiti, and builder configuration for each of your validator keys, plus a default that applies to every key you don't configure individually.

This page is the canonical reference for the version 2 (v2) proposer settings schema introduced for the Gloas fork, which enshrines proposer-builder separation (ePBS) into the protocol. It covers every field, how values are inherited and merged, how v2 behaves on networks that haven't forked yet, what happens to v1 settings at the fork, and which flags are deprecated.

If you only need to set a fee recipient, start with Configure Fee Recipient. For the end-to-end builder workflow (MEV-Boost today, in-protocol builders after Gloas), see Configure MEV Builder.

Update to v2

If your proposer settings file configures builders, move it to the v2 builder fields. v1 builder settings describe the MEV-Boost world: they keep working until the Gloas fork, and are then dropped and replaced with defaults. Fee recipients and graffiti carry over either way. You don't have to add a version field to do this — Prysm reads the schema from the fields you use. See Migrating from v1 to v2.

Why there is a v2

Before Gloas, external block building happened outside the protocol: validators registered with relays (MEV-Boost), and the beacon node requested blinded blocks from a relay. The v1 proposer settings schema reflects that world — its builder section is essentially a registration toggle (enabled) plus a registration gas limit.

Gloas changes the model. Builders become on-chain actors with their own indices, public keys, and staked balances. Your validator no longer registers with a relay; instead it decides, per proposal, which builder bids to consider and how to value them. That requires expressing things v1 has no words for: which builders you'll talk to, how much of a builder's promised payment you're willing to trust, a minimum acceptable bid, and how to weigh builder bids against your own locally built block. The v2 schema adds those fields and moves the gas limit to its natural, builder-independent home.

How proposer settings are supplied

Nothing changes here with v2 — the same sources work, in the same way:

• Command-line flags, which populate default_config for every key: --suggested-fee-recipient and --suggested-gas-limit, plus --builder-urls, --builder-min-bid, --builder-boost-factor and --builder-max-execution-payment for Gloas builders. See Configuring builders with flags.
• --proposer-settings-file=<path>: a local JSON or YAML file using the schema on this page.
• --proposer-settings-url=<url>: a remote endpoint returning the same schema as a JSON payload (Prysm issues a GET request and parses the response body as JSON).
• Keymanager APIs: per-key fee recipient, gas limit, graffiti, and (new) builder configuration endpoints.

--proposer-settings-file and --proposer-settings-url are mutually exclusive — the validator client refuses to start with both. A URL must return JSON; YAML is only read from files.

Unknown fields fail the load

Files and URL responses are parsed strictly: a field name Prysm doesn't recognize — a typo, or a field copied from another client or from the keymanager API wire format — stops the validator client from loading the settings, rather than being ignored. A common case is pubkeys, the old name of the builder allowlist field; it is now builder_pubkeys, as in the keymanager API.

A default_config in a settings file or URL replaces the flag-built default as a whole — including the defaults from --suggested-fee-recipient and --suggested-gas-limit — so when you use a settings source with a default_config, set those values in the file.

Loaded settings are persisted in the validator client database, so changes made through the keymanager APIs survive restarts. On startup, a file or URL takes precedence over what's in the database: if the source contains a proposer_config section, it replaces the stored per-key section entirely, and a default_config in the source replaces the stored default. If you manage per-key settings through the keymanager APIs, restarting with a settings file resets per-key entries to the file's contents.

Configuring Gloas builders with flags

From the Gloas fork onward, if the same builder configuration suits every key, these flags set it without a settings file — the same way --suggested-fee-recipient sets a default fee recipient. Per-key settings from a file, URL, or the keymanager API win over them. One pre-fork exception: a non-empty --builder-urls also opts per-key builder objects that carry only v1 fields (even enabled: false) into MEV-Boost registration; give such a key "builders": [] to keep it out.

Flag	Effect
--builder-urls	Comma-separated builder URLs to request bids from. Auth data agreed with a builder can be appended as a hex fragment (https://builder.example#0x0123); without one, the URL's lowercased hostname is used (builder.example). At most 64 entries; more than that, or a duplicate, stops the validator client from starting.
--builder-min-bid	Minimum total payment in gwei a bid must offer to be considered — the bid value plus its execution payment, up to --builder-max-execution-payment.
--builder-boost-factor	Percentage applied to builder bid values when comparing them against your local payload. 100 is neutral, below 100 favors the local payload, 0 always builds locally.
--builder-max-execution-payment	Maximum execution layer payment in gwei counted toward a bid. 0 counts only the collateral-backed bid value; anything above rests on the builder's promise to pay — see Trusting builders.

Setting --builder-urls before the fork is not inert: a non-empty list also enables MEV-Boost registration, as --enable-builder does.

Flag defaults last only for the run that sets them

Builder defaults set by these flags apply per run: restart without the flags and Prysm does not carry them over from the validator database. It warns when it drops stored defaults for this reason, so pass the flags on every start if you want them to stick.

The v2 schema

A complete example configuring one validator key explicitly, with a default for all other keys:

JSON

{
  "version": 2,
  "proposer_config": {
    "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {
      "fee_recipient": "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3",
      "gas_limit": "60000000",
      "graffiti": "prysm-validator",
      "builder": {
        "min_bid": "10000000",
        "builder_boost_factor": "100",
        "builders": [
          {
            "url": "https://builder-a.example",
            "max_execution_payment": "100000000"
          },
          {
            "url": "https://builder-b.example"
          }
        ]
      }
    }
  },
  "default_config": {
    "fee_recipient": "0x6e35733c5af9B61374A128e6F85f553aF09ff89A",
    "builder": {
      "builders": []
    }
  }
}

YAML

---
version: 2
proposer_config:
  '0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a':
    fee_recipient: '0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3'
    gas_limit: '60000000'
    graffiti: 'prysm-validator'
    builder:
      min_bid: '10000000'
      builder_boost_factor: '100'
      builders:
        - url: 'https://builder-a.example'
          max_execution_payment: '100000000'
        - url: 'https://builder-b.example'
default_config:
  fee_recipient: '0x6e35733c5af9B61374A128e6F85f553aF09ff89A'
  builder:
    builders: []

In this example, the explicitly configured key considers bids from two builders—trusting builder A's promised execution payments up to 0.1 ETH, and builder B only for what the protocol can enforce — while ignoring bids whose value to the proposer is below 0.01 ETH. Every other key in the client uses the default: self-built (local) blocks only, because builders is an explicit empty list.

Numeric values may be written as strings ("60000000") or bare numbers (60000000); strings are recommended for consistency with the keymanager API wire format. All amounts (min_bid, max_execution_payment) are denominated in gwei.

Top-level fields

Field	Description
version	Optional. Schema version; 2 is the current schema. You rarely need to set it: Prysm reads a source as version 2 as soon as it contains any v2 builder field (builders, min_bid, builder_boost_factor, or max_execution_payment), logging that it did so. For a file that only sets fee recipients, gas limits, and graffiti, the version makes no difference at all — those fields behave identically in both schemas. Set it when you want the file to state its own intent, or to keep the inference log out of your startup output.
proposer_config	A map from validator BLS public key (98-character 0x-prefixed hex) to a per-key options object.
default_config	An options object applied to every validator public key not listed in proposer_config.

Options (per key, and in default_config)

Field	Description
fee_recipient	The Ethereum address that receives priority fees (and, after Gloas, builder payments). A per-key value overrides default_config, which overrides --suggested-fee-recipient.
gas_limit	The gas limit your validator advertises as its preference for blocks built on its behalf. New in v2 at this level. Leave it unset to follow the network's scheduled gas limit (EIP-8261), or the chain default shipped in your Prysm release when no schedule entry is active — the command-line options reference is generated per release, and the default it shows for --suggested-gas-limit is that same value. Set it only to deliberately opt out of the network schedule; Prysm logs a warning once per epoch when your explicit value is above or below the scheduled value. In v1 the gas limit lived inside builder; that placement is legacy and stops applying at the Gloas fork.
graffiti	Graffiti string included in blocks proposed by this key.
builder	Builder configuration for this key — see below. Omit it entirely if you only self-build.

An explicit gas limit overrides the Gloas gas limit schedule

From the Gloas fork onward, a gas_limit set here — or the default set by --suggested-gas-limit — is the gas limit signed into your proposer preferences, and it overrides the network's scheduled gas limit (EIP-8261). The key stays pinned at that value and stops following scheduled increases. Prysm warns at startup when the flag is set, and once per epoch while an explicit value is above or below the schedule.

Unless you deliberately want to opt out, leave gas_limit unset and drop --suggested-gas-limit.

The builder object

Field	Description
builders	The list of builders this key will request bids from (see Builder entries). The list's presence matters: omitting builders in a per-key config inherits the default_config list, while an explicit empty list ([]) means "use no builders" — self-build only — for that key. At most 64 entries; duplicate or invalid entries are dropped at load time with a warning.
min_bid	Minimum acceptable bid value in gwei, applied to the effective value of a bid. Bids below the floor are ignored. Unset means no floor. Can be overridden per builder entry.
max_execution_payment	The maximum execution-layer payment, in gwei, you are willing to count toward a builder's bid. This is a trust decision — read Trusting builders before setting it. Unset or 0 means trustless-only. Can be overridden per builder entry.
builder_boost_factor	Percentage multiplier applied to builder bid values when comparing them against your locally built block. 100 (the default) is neutral, values above 100 favor builders, values below 100 favor local blocks, and 0 means builder bids can never win. Can be overridden per builder entry.
enabled	Legacy (v1). Opts the key into MEV-Boost validator registration before the Gloas fork. Ignored by the v2 builder flow and dropped at the fork. In v2 files, a non-empty builders list serves this purpose pre-fork — see Before the fork.
gas_limit	Legacy (v1). The pre-Gloas registration gas limit. In v2, set gas_limit at the option level (next to fee_recipient) instead.

The v1 relays field is deprecated and never read. It is still accepted, so a file that contains it loads fine despite strict parsing, but it has no effect.

Builder entries

Each entry in a builders list describes one builder your validator is willing to request bids from:

Field	Description
url	Required. The builder's HTTP endpoint (up to 2048 bytes). Entries with the same url and auth_data are deduplicated.
min_bid	Per-entry override of the enclosing config's min_bid.
max_execution_payment	Per-entry override of the enclosing config's max_execution_payment. Setting trust ceilings per entry, rather than config-wide, is the recommended pattern.
builder_boost_factor	Per-entry override of the enclosing config's builder_boost_factor.
builder_pubkeys	Optional allowlist of builder BLS public keys, as 0x-hex strings. When set, only bids signed by these on-chain builder identities are accepted from this entry; when omitted, any active builder responding at the URL is accepted. At most 64 keys.
auth_data	Optional opaque bytes, as a 0x-hex string, that your validator signs to authenticate its requests to this builder. When omitted, it defaults to the lowercased hostname of url (for example builder.example; IPv6 hosts in brackets), which is the spec convention — most operators never set this. At most 4096 bytes.

Fields left unset on an entry fall back to the enclosing builder config, then to default_config's builder config.

note

builder_pubkeys and auth_data use the same names and 0x-hex encoding in a settings file as in the keymanager builder API, so an entry can be copied between the two unchanged. A value that isn't valid 0x-hex stops the validator client from loading the file or URL.

If you wrote a settings file against an earlier development build, which used a pubkeys field and base64 values, rename the field to builder_pubkeys and convert each value to hex — for example echo '<base64 value>' | base64 -d | od -An -tx1 | tr -d ' \n', then prefix the output with 0x.

How a bid is valued

Understanding min_bid, max_execution_payment, and builder_boost_factor requires knowing how Prysm picks a payload after Gloas. When your validator is about to propose, the beacon node gathers candidate execution payload bids from your configured builders (and from bids gossiped on the P2P network), plus your own locally built payload, then:

1. Effective value. Each builder bid carries two amounts: value, which the protocol enforces against the builder’s staked on-chain balance, and execution_payment, an additional payment the builder promises to deliver inside the execution payload itself. The bid's effective value is value plus the execution payment capped at your max_execution_payment. With the cap unset or 0, promised payments count for nothing and only the collateral-backed value matters. Bids that arrive over P2P gossip must carry a zero execution payment, so gossiped bids are always fully collateral-backed.
2. Floor. Discard a bid whose effective value is below the applicable min_bid.
3. Validity. Bids are checked the same way the chain will check them: the builder must be active and able to cover the bid's value from its balance, the bid must target your slot, parent block, fee recipient, and gas limit preference, and the signature must verify. Builders temporarily blacklisted by the circuit breaker (for winning an auction and then failing to reveal the payload) are skipped.
4. Comparison. Multiply each surviving bid’s effective value by its builder_boost_factor divided by 100, then compare it against the value of your locally built payload and every other bid. The highest boosted value wins; ties go to the local payload.

If no builder bid wins — or none was configured — the validator self-builds using the local execution client, exactly as it does today. A synced local execution client remains mandatory.

Trusting builders: max_execution_payment

This setting hands trust to a builder

A builder bid's value is safe by construction: the protocol verifies the builder's staked balance covers it before the bid can win, and settles the payment on-chain when the builder delivers its payload — a builder cannot bid money it doesn't have. Its execution_payment is only a promise: an amount the builder claims it will pay your fee recipient inside the payload it later reveals. The protocol neither escrows it nor checks that it is ever paid.

• Setting max_execution_payment above 0 means bids can win your auction based on promised money. A malicious or buggy builder can outbid everyone with a large promised payment it never delivers. Treat the value as the amount of credit you extend to that builder per block, and set it per builder entry — only for builders you have a reason to trust — rather than config-wide.
• Leaving it unset (or 0) keeps you trustless, but the flip side is that builders whose bids rely mainly on execution payments will rarely or never beat your local blocks — your builders may effectively go unused, and Prysm logs a warning at startup naming the builder entries this applies to.
• The maximum value 18446744073709551615 (2^64 − 1) means "accept any promised amount" and is not recommended.

Prysm has no separate opt-in flag gating this behavior: writing a non-zero max_execution_payment into your settings is the opt-in. Some other clients guard the equivalent setting behind an explicitly named flag; in Prysm, review this field with the same care you would give such a flag.

Inheritance and merge rules

Scalar builder fields (min_bid, max_execution_payment, builder_boost_factor) are inherited field-by-field: a per-key value wins, an unset per-key value falls back to default_config, and a value unset in both resolves to its neutral default (no floor, trustless-only, boost factor 100). The same logic applies one level down, from builder entries to their enclosing config.

The builders list is replaced, not merged: a per-key list (including an explicit []) fully replaces the default list, and omitting the key inherits the default list unchanged. This is what makes [] the per-key "self-build only" opt-out.

gas_limit at the option level follows the same per-key-wins pattern; when unset at both levels, the network's scheduled gas limit or chain default applies.

Running v2 settings before the Gloas fork

You can and should switch to v2 ahead of the fork. During the transition window — after upgrading Prysm but before your network reaches the Gloas fork epoch — the two builder worlds coexist, and v2 settings drive the old one by convention:

Your v2 settings say	Pre-fork MEV-Boost behavior	Post-fork Gloas behavior
Non-empty builders list	Key is registered with MEV-Boost relays (equivalent to v1 enabled: true)	Bids requested from the listed builders
Explicit empty list (builders: [])	Key is not registered	Self-build only
No builders key, but other builder fields set (min_bid, etc.)	No registration signal from this key — the default_config choice (or none) applies	Inherits the default builders list
Legacy enabled: true alongside v2 fields	Key is registered	enabled ignored, then dropped at the fork

In other words: listing builders in v2 keeps your MEV-Boost registrations flowing until the fork, then seamlessly becomes your Gloas builder list. Registration still uses your fee recipient and gas limit (the option-level gas_limit wins over a legacy builder-level one), and the beacon node's --http-mev-relay wiring is unchanged until the fork.

Two more transition behaviors to be aware of:

• Version inference. A file or URL without version that contains any v2 builder field is treated as version 2, with an info log, so a missing version stamp can never get your Gloas builder configuration dropped as v1 content. Inference keys off the builder fields only — but an option-level gas_limit applies regardless of schema version, so a file that sets one without any builder config needs nothing else.
• Keymanager builder endpoints. GET/POST/DELETE /eth/v1/validator/{pubkey}/builder_config respond 501 Not Implemented on networks that have no Gloas fork scheduled, since builder configuration cannot take effect there. Once your network schedules the fork (testnets first), the endpoints go live — before the fork epoch itself.

Migrating from v1 to v2

v1 builder settings are not migrated automatically, because the v1 fields answer a question ("register with relays?") that no longer exists after the fork.

What replaces what

What you want to express	v1	v2
Which schema this file uses	no version field, or version: 1	version: 2 — optional, since any v2 builder field below implies it
Use builders for a key	builder.enabled: true	a non-empty builder.builders list
Don't use builders for a key	builder.enabled: false	builder.builders: [], or no builder object at all to inherit the default
Choose which builders	not expressible — the beacon node's --http-mev-relay picked one relay for every key	builders[].url, per key
Accept bids only from specific builders	not expressible	builders[].builder_pubkeys
Authenticate your requests to a builder	not expressible	builders[].auth_data (defaults to the URL's hostname)
Set a gas limit	builder.gas_limit, or --suggested-gas-limit	gas_limit at the option level, beside fee_recipient, or --suggested-gas-limit. Both override the EIP-8261 schedule from the fork onward — leave the field unset and drop the flag to follow the schedule instead
Ignore bids below a floor	beacon node --min-builder-bid, applied to every key	min_bid, per builder config or per entry
Favor your local block over builder bids	beacon node --local-block-value-boost, applied to every key	builder_boost_factor, per builder config or per entry
Count a builder's promised execution payment	not expressible — trust in the relay was implicit	max_execution_payment, per builder config or per entry; unset means trustless-only
List relays	relays	deprecated and ignored — relays don't exist in the Gloas builder market
Set a fee recipient or graffiti	fee_recipient, graffiti	unchanged

The same file, both ways

Here is the same intent expressed in both schemas:

v1 (legacy)

{
  "proposer_config": {
    "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {
      "fee_recipient": "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3",
      "builder": {
        "enabled": true,
        "gas_limit": "60000000"
      }
    }
  },
  "default_config": {
    "fee_recipient": "0x6e35733c5af9B61374A128e6F85f553aF09ff89A",
    "builder": {
      "enabled": false
    }
  }
}

v2

{
  "version": 2,
  "proposer_config": {
    "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {
      "fee_recipient": "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3",
      "gas_limit": "60000000",
      "builder": {
        "builders": [
          { "url": "https://builder-a.example" }
        ]
      }
    }
  },
  "default_config": {
    "fee_recipient": "0x6e35733c5af9B61374A128e6F85f553aF09ff89A",
    "builder": {
      "builders": []
    }
  }
}

Migration checklist:

1. Optionally add "version": 2. The builder fields in the next step are what actually move the file to v2; the version field only makes that explicit.
2. Replace each "enabled": true with a concrete builders list of builder endpoints you choose, and each "enabled": false with "builders": [] (or remove the builder object entirely to inherit the default).
3. Delete gas_limit rather than moving it, unless you mean to pin a value. Moving it out of builder up to the option level is not a like-for-like move: a builder-level value never fed the gas limit schedule, but an option-level one becomes your signed proposer preference and overrides EIP-8261 from the Gloas fork onward, so the key stops following scheduled increases. Leave it unset and the schedule applies automatically.
4. Delete relays if present (it is ignored; leaving it in place is harmless but misleading).
5. Decide your trust posture per builder: leave max_execution_payment unset to stay trustless, or set a deliberate per-entry cap for builders you trust.
6. Restart the validator client and check the startup logs — the warnings below tell you if Prysm read your intent differently than you meant it.

What happens if you don't migrate

Nothing breaks before the fork: v1 files keep driving MEV-Boost registrations exactly as they always have. From the moment your network schedules Gloas, Prysm warns at startup that the settings contain deprecated v1 builder fields. At the fork epoch:

• enabled and builder-level gas_limit values are dropped and replaced with defaults, with a warning.
• Fee recipients and graffiti carry over untouched.
• Your effective gas limit becomes the network's scheduled value (unless you set an option-level gas_limit).
• No builders are configured, so every proposal self-builds until you provide v2 settings or use the keymanager API.

Dropping v1 builder content is deliberately safe-by-default: the failure mode is "self-build with protocol defaults," never "trust a builder you didn't name."

Flag changes and deprecations

Flag	Status
--suggested-fee-recipient (validator)	Unchanged.
--proposer-settings-file / --proposer-settings-url (validator)	Unchanged; still mutually exclusive.
--enable-builder / --enable-validator-registration (validator)	Legacy. Still opts all keys into MEV-Boost registration before the fork and has no effect after it. Per-key v2 choices win over it, but keys that inherit default_config are registered even if the default says "builders": []. Prysm warns when it's combined with version 2 settings. Post-fork equivalent: a builders list in v2 settings, --builder-urls, or the keymanager API.
--builder-urls, --builder-min-bid, --builder-boost-factor, --builder-max-execution-payment (validator)	New: set the default Gloas builder configuration for every key without a settings file — see Configuring builders with flags.
--suggested-gas-limit (validator)	Sets the default gas limit before and after the fork: registered with builders pre-Gloas, signed into your proposer preferences from Gloas onward, where it overrides the EIP-8261 schedule. Prysm warns at startup when it is set on a Gloas-scheduled network, and again when the value exceeds the highest scheduled limit. Remove it to follow the schedule. A settings file or URL with a default_config replaces the flag's value, so set gas_limit there instead if you use one.
--stateless (validator)	New with Gloas: the validator requests the block and execution payload envelope together and republishes the envelope itself. Forced on automatically when multiple beacon nodes are configured on a Gloas-scheduled network.
--http-mev-relay (beacon node)	Drives the MEV-Boost flow, which ends at the Gloas fork. After the fork the beacon node contacts builders using the entries your validator client supplies — no beacon node builder flag is needed.
--builder-bid-timeout (beacon node)	New, optional: how long the beacon node waits for builders to return execution payload bids before falling back to P2P bids or the local payload. Defaults to 600ms, must be greater than zero, and only applies from the Gloas fork onward.
--min-builder-bid, --local-block-value-boost (beacon node)	Pre-fork MEV-Boost controls. Their post-fork equivalents are per-key min_bid and builder_boost_factor in v2 proposer settings.
--with-builder (prysmctl validator)	Legacy. Generates pre-fork MEV-Boost builder settings and warns when used.

Keymanager APIs

All existing proposer-related keymanager endpoints continue to work, with two behavioral updates and one new endpoint group. See the Keymanager APIs page for authentication.

• Gas limit endpoints now read and write the option-level (v2) gas limit and no longer require a builder to be enabled. For a key with no gas limit of its own, GET reports the chain default shipped in your release, not the scheduled value the key actually follows. DELETE resets the key to default_config's gas limit when one is set (from the file or --suggested-gas-limit); otherwise it unsets the value, and the key follows the network's scheduled gas limit. It returns 404 if the key has no gas limit to reset.
• Fee recipient, gas limit, and graffiti writes no longer snapshot default_config's builder settings onto the key; the key continues to follow the default builder config as it changes.
• GET/POST/DELETE /eth/v1/validator/{pubkey}/builder_config (new, per keymanager-APIs #88) manage the per-key builder config:
  • GET returns the key's config resolved against default_config, with concrete values for every field (no floor is reported as "0", neutral boost as "100", trustless-only as "0"), safe to re-submit as-is. The API has no config-level max_execution_payment: it exists only per builder entry, and GET folds any config-level value from your file into each entry.
  • POST replaces the key's builder config in full — it is not a partial update. Fee recipient, gas limit, and graffiti are untouched. An empty body object clears the per-key builder config, so the key follows the client defaults. Because the replacement is total, a config-level max_execution_payment set for the key in a file is not kept — carry it on each entry you submit.
  • DELETE removes the per-key builder config; the key inherits default_config again.
  • On the wire, integers are decimal strings and byte fields (builder_pubkeys, auth_data) are 0x-hex.
  • The endpoints respond 501 on networks with no Gloas fork scheduled.

Startup warnings explained

Prysm validates proposer settings at load time. Unknown fields and invalid builder flags stop the load; invalid builder entries are dropped with a warning instead, so block production isn't blocked by one bad entry. The logs you may see, and what to do:

Log message (abbreviated)	Meaning	Action
"Proposer settings contain v2 builder fields but no version; treating the source as version 2" (info)	Version inference did its job — your builder configuration is being read as v2.	None needed. Add "version": 2 if you'd rather state it explicitly and silence the log.
"Proposer settings contain deprecated v1 builder fields (enabled, builder-level gas limits); they stop applying at the gloas fork…"	You're on a Gloas-scheduled network with v1 builder content. --enable-builder, or --suggested-gas-limit without v2 settings, also counts.	Migrate to v2 before the fork epoch.
"Proposer settings contain v1 builder fields, which do not apply to gloas; proposer preferences are prepared with defaults…"	Logged at each epoch start from the last epoch before the fork while v1 builder content remains.	Migrate to v2 now — the fork is one epoch away.
"V1 builder settings, including gas limits, do not apply to gloas and were replaced with defaults…"	The fork cutover dropped your v1 builder content.	Provide v2 settings if you want builders (or an explicit gas limit).
"Builder entries have no max_execution_payment: their execution layer payment is ignored and only collateral-backed bid value counts…"	Your builder entries are in trustless-only mode.	Intentional? No action. Otherwise set a deliberate per-entry cap — after reading Trusting builders.
"Removed N invalid or duplicate builder entries from proposer settings"	Entries failed validation — missing, oversized, or unparseable url, a non-ASCII hostname (use punycode), more than 64 entries (the first 64 are kept), more than 64 or invalid builder_pubkeys, oversized auth_data — or duplicated another entry.	Check the log's reasons field and fix the matching entries in your source.
"--enable-builder is legacy (pre-gloas) mev-boost content and has no effect after the gloas fork…"	A legacy flag is set alongside v2 settings.	Drop the flag once you've expressed the intent in v2 settings.
"--suggested-gas-limit overrides the network gas limit schedule from the Gloas fork; remove it to follow the schedule"	Your explicit gas limit is pinning the key, so scheduled increases no longer apply.	Remove the flag unless you mean to opt out. A second warning follows if the value exceeds the highest scheduled limit.
"Dropped the default builder settings a previous run stored in the validator DB…" (same pattern for the default gas limit)	Default builders or a default gas limit stored by an earlier run — from flags or an earlier settings source — are not carried over when this run's flags and settings source don't set them.	Pass --builder-urls (or the settings source) on every start, or move the configuration into a settings file.
"…configure Gloas builders, but this network has no Gloas fork scheduled"	Builder flags are set on a network with no Gloas fork scheduled.	--builder-min-bid, --builder-boost-factor and --builder-max-execution-payment do nothing here, but a non-empty --builder-urls still enables MEV-Boost registration. Drop them, or check you are on the network you meant.
"The default_config from --proposer-settings-file replaces the builder defaults set by …"	A settings source and the builder flags both set defaults, and the file wins.	Expected. Drop the flags, or remove default_config from the source if you meant the flags to apply.
"Default builder config has no default fee recipient; only keys with their own fee recipient can register"	Your v2 default_config has a builder object but no fee recipient, so before the fork, keys without their own fee recipient are not registered with MEV-Boost.	Set fee_recipient in default_config (or --suggested-fee-recipient if you have no settings source).
"Per-key proposer settings saved in the validator DB by a previous run differ from the configured settings file/URL…"	The source is authoritative and is replacing stored per-key entries. The log names them in droppedKeys and overriddenKeys, with counts.	Expected if you manage keys by file. If you set them through the keymanager API, note they do not survive a restart while a file or URL is configured.

Frequently asked questions

Do I have to do anything if I never use builders?

Set your fee recipient (flag or file) and you're done. You don't need "version": 2, a builder section, or any new flags. At the fork, your validator keeps self-building local blocks, and your gas limit automatically follows the network schedule — unless you set --suggested-gas-limit or a gas_limit, which pin it.

Is v2 backwards compatible with v1?

For everything except builders, yes — fee_recipient, graffiti, and the file mechanics are identical, and option-level gas_limit is additive. For builders, v2 replaces v1, with a compatibility convention during the transition: a non-empty builders list doubles as the pre-fork registration opt-in, and an empty list as the opt-out.

Do I need to set version in my file?

Usually not. Prysm reads your file as version 2 the moment it uses any v2 builder field, and a file that only sets fee recipients, gas limits, or graffiti behaves identically either way. Set it when you want the file to document its own intent, or to silence the inference log at startup.

Which networks does this apply to right now?

The v2 builder fields only have effect on networks with a Gloas fork epoch scheduled — testnets and devnets first, mainnet once the fork is scheduled there. On other networks, the keymanager builder endpoints return 501 and the Gloas-related warnings stay quiet, but a v2 file loads fine everywhere.

Where did relays go?

Relays are a MEV-Boost concept and don't exist in the Gloas builder market. The field is deprecated and never read; files that still contain it load normally, and the field is ignored.

Can I mix the flags and a v2 file?

Yes, and the file wins. A default_config in the file replaces the flag defaults as a whole, so put your fee recipient (and any gas limit) there rather than relying on --suggested-fee-recipient or --suggested-gas-limit. --enable-builder only influences pre-fork registrations, and Prysm warns that it's legacy when combined with v2 settings. --suggested-gas-limit keeps applying after the fork, where it overrides the schedule, and Prysm warns about that on Gloas-scheduled networks.