Skip to main content

Proposer settings

Proposer settings control how your validator client proposes blocks: for each validator key, the fee recipient, gas limit, graffiti, and builder configuration, plus a default for every key you don't configure individually. This page is the reference for the version 2 (v2) schema, introduced for the Gloas fork.

Before Gloas, the builder section only said whether to register a key with MEV-Boost relays. From the fork, builders are on-chain participants that your validator asks for bids directly, so v2 adds fields for which builders to use, how much of their promised payment to count, a minimum bid, and how to weigh bids against your own block, and it moves the gas limit out of builder.

If you only need to set a fee recipient, see Configure Fee Recipient. For how builders work from the fork, see Configure MEV Builder; for MEV-Boost before it, see MEV-Boost (before Gloas).

Already using MEV-Boost? Migrate before the fork

v1 builder settings (enabled and the gas_limit inside builder) stop working at the Gloas fork, and Prysm doesn't convert them. Most operators need one change before then: replace enabled with a builders list. It is safe to do now. See Migrating from v1 to v2.

Requires the Gloas fork

The builder fields, the --builder-* flags, and the keymanager builder_config endpoints on this page only work on networks with a Gloas fork epoch scheduled: testnets and devnets first, and mainnet once the fork is scheduled there. On other networks, a v2 file still loads, but bids are never requested, and the endpoints return 501. Fee recipient, gas limit, and graffiti settings work everywhere. Until the fork epoch, builders still run through MEV-Boost, and a builders list only decides which keys register; see Running v2 settings before the Gloas fork.

Configuring builders​

One builder for every key, trusting its promised payments in full. This is all most operators need:

./prysm.sh validator \
  --suggested-fee-recipient=0x6e35733c5af9B61374A128e6F85f553aF09ff89A \
  --builder-urls=https://builder-a.example \
  --builder-max-execution-payment=18446744073709551615  # 2^64 - 1: count promised payments in full

In a file, default_config is the settings for every key that has no entry of its own under proposer_config, so here it covers every key; the flags set the same defaults. The Per key tab shows the remaining fields.

max_execution_payment is a trust decision. A bid's value is guaranteed by the builder's staked balance; its execution_payment is only a promise to pay inside the block, which the protocol doesn't check. This field sets how much of that promise Prysm counts when it values the bid. The maximum, 18446744073709551615 (2^64 − 1), counts it in full, the same trust you gave a relay under MEV-Boost: a builder that doesn't pay can cost you the whole promised amount. A smaller value in gwei (100000000 is 0.1 ETH) caps that loss. Unset or 0 counts none of it, so bids that depend on promised payment rarely beat your own block, and Prysm warns at startup about entries that leave it unset. Prysm has no separate flag gating this; the value itself is the opt-in. Set it per builder entry, or on the builder object as the default for all of its entries; the keymanager API reads and writes it per entry.

A gas limit you set overrides the gas limit schedule

From the Gloas fork onward, a gas_limit in your settings, per key or in default_config, is the gas limit your validator signs into its proposer preferences. --suggested-gas-limit overrides all of them: at startup it sets every key's gas limit, including values from your settings file, URL, or the keymanager API. Either way, a set value overrides the network's scheduled gas limit, so the key keeps it and doesn't pick up scheduled increases. Prysm warns at startup when the flag is set, and once per epoch when it signs a preference that differs from the schedule. Unless you want a fixed gas limit, leave gas_limit unset and don't use the flag.

Configuring Gloas builders with flags​

The flags set the same builder configuration for every key, the way --suggested-fee-recipient sets a default fee recipient. Per-key settings from a file, URL, or the keymanager API take priority over them.

FlagEffect
--builder-urlsComma-separated builder URLs to request bids from, at most 64. Auth data agreed with a builder goes in a 0x-hex fragment (https://builder.example#0x0123); otherwise the lowercased hostname is used. An invalid URL, a non-hex fragment, more than 64 entries, or a duplicate stops the validator client from starting.
--builder-min-bidMinimum bid, in gwei: the bid value plus its execution payment, counted up to --builder-max-execution-payment.
--builder-boost-factorPercentage applied to a bid's value before comparing it with your local payload: 100 is neutral, below 100 favors your payload, 0 always uses it (also against P2P bids).
--builder-max-execution-paymentMaximum execution payment, in gwei, counted toward a bid: 0 counts only the value backed by the builder's stake, 18446744073709551615 counts promised payment in full. See Configuring builders.

Set --builder-max-execution-payment with --builder-urls; on its own, --builder-urls counts none of a builder's promised payment. Pass the flags on every start: they apply only to the run that sets them, and Prysm warns when it drops stored values because the flags are missing. Before the fork, a non-empty --builder-urls also registers keys with MEV-Boost, as --enable-builder does, including keys whose builder object has only v1 fields; set "builders": [] on a key to keep it out.

Migrating from v1 to v2​

The v1 builder fields control MEV-Boost registration, which doesn't exist after the fork, so Prysm doesn't convert them; you replace them.

What replaces what​

To setv1v2
The file's schema versionno version field, or version: 1version: 2. Optional: a file with no version is treated as v2 once it has any v2 builder field below. If the file says version: 1, change it to 2
Use builders for a keybuilder.enabled: truea non-empty builder.builders list
Use builders for every key, by flag--enable-builder (registers every key; does nothing after the fork, and warns next to v2 settings)--builder-urls with --builder-max-execution-payment, or a builders list in default_config
Don't request builder bids for a keybuilder.enabled: falsebuilder.builders: [], or no builder object to follow default_config
Which builders to usenot possible: --http-mev-relay set one relay for every keybuilders[].url, per key
Accept bids only from specific buildersnot possiblebuilders[].builder_pubkeys
Authenticate your requests to a buildernot possiblebuilders[].auth_data (defaults to the URL's hostname)
A gas limitbuilder.gas_limit, or --suggested-gas-limitgas_limit next to fee_recipient, or --suggested-gas-limit for every key (it replaces any gas_limit in the file); both override the gas limit schedule from the fork onward, so leave them out to follow it
Ignore bids below a minimumbeacon node --min-builder-bid, for every keymin_bid, per builder config or per entry
Favor your local block over builder bidsbeacon node --local-block-value-boost, for every keybuilder_boost_factor, per builder config or per entry
Count a builder's promised execution paymentnot possible: you relied on the relaymax_execution_payment, per builder config or per entry; unset counts none
Relaysrelaysdeprecated and ignored, because Gloas has no relays
Generate the builder fields with prysmctl validator proposer-settings--with-buildernot available: the flag still writes v1 fields and warns, so add the builders list by hand
A fee recipient or graffitifee_recipient, graffitiunchanged

How to migrate​

  1. Replace each "enabled": true with a builders list and set max_execution_payment on each entry. Replace each "enabled": false with "builders": [], or remove the builder object if the key should follow default_config.
  2. Delete gas_limit instead of moving it, unless you want a fixed gas limit. Next to fee_recipient, it overrides the gas limit schedule from the fork onward; inside builder it never did. Remove --suggested-gas-limit for the same reason.
  3. Delete relays if present. Optionally add "version": 2; the builder fields already make the file v2.
  4. Restart the validator client and check the startup logs. The beacon node keeps using --http-mev-relay until the fork; after the fork epoch, remove it and --enable-builder, and stop MEV-Boost.

A migrated file, with one key on a builder and every other key off builders:

---
version: 2
proposer_config:
  '0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a':
    fee_recipient: '0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3'
    builder:
      builders:
        - url: 'https://builder-a.example'
          max_execution_payment: '18446744073709551615'
default_config:
  fee_recipient: '0x6e35733c5af9B61374A128e6F85f553aF09ff89A'
  builder:
    builders: []

Running v2 settings before the Gloas fork​

You can migrate anytime before the fork. Until the fork epoch, your validator still uses MEV-Boost, and your v2 settings decide which keys to register:

Your v2 settingsBefore the fork (MEV-Boost)After the fork (Gloas)
Non-empty builders listKey is registered with MEV-Boost relays, as with v1 enabled: trueBids are requested from the listed builders
Empty list (builders: [])Key is not registered, unless the legacy enabled: true is also setNo builder bids are requested
No builders field, but other builder fields set (min_bid, etc.)The key's own config doesn't decide; the default_config setting applies, if anyUses the builders list from default_config
Legacy enabled: true together with v2 fieldsKey is registeredenabled is ignored, and removed at the fork

Registration still uses your fee recipient and gas limit (a gas_limit next to fee_recipient wins over a legacy one inside builder), and the beacon node's --http-mev-relay setup doesn't change until the fork. The keymanager builder_config endpoints return 501 until your network schedules the fork.

What happens if you don't migrate​

Nothing changes before the fork, except that Prysm warns at startup about deprecated v1 builder fields once your network schedules Gloas. At the fork epoch, Prysm removes enabled and the gas_limit inside builder with a warning and keeps fee recipients and graffiti. Your gas limit follows the network schedule, and Prysm requests no builder bids until you add v2 settings (trustless P2P bids can still beat your own block; see How a bid is valued). This fallback never counts a payment that isn't backed by a builder's staked balance.

How proposer settings are supplied​

  • Command-line flags: --suggested-fee-recipient and the builder flags set default_config for every key, and --suggested-gas-limit sets every key's gas limit.
  • --proposer-settings-file=<path>: a local JSON or YAML file using the schema on this page.
  • --proposer-settings-url=<url>: a URL that returns the same schema as JSON (Prysm sends a GET request; YAML is only supported for files).
  • Keymanager APIs: endpoints for each key's fee recipient, gas limit, graffiti, and builder configuration.

--proposer-settings-file and --proposer-settings-url can't be combined; the validator client won't start with both. Files and URL responses are parsed strictly: a field name Prysm doesn't recognize, a version above 2, or a builder_pubkeys or auth_data value that isn't 0x-hex stops the settings from loading. (pubkeys, the old name of builder_pubkeys, is the common case.)

A default_config in a file or URL replaces the defaults set by --suggested-fee-recipient and the builder flags, so put those values in the file. --suggested-gas-limit is the exception: it replaces every gas limit in the file, in default_config and on each key, and with a v1 file the gas_limit inside builder too.

The validator client saves loaded settings to its database, so changes made through the keymanager APIs survive restarts. A file or URL takes priority over the database at startup: a non-empty proposer_config replaces all stored per-key settings, and a default_config replaces the stored default. If you manage keys through the keymanager APIs and restart with a settings file, those keys are reset to what the file says.

Field reference​

Amounts and gas limits can be written as strings ("60000000") or plain numbers; strings are recommended because the keymanager API uses them. version must be a plain number. All amounts (min_bid, max_execution_payment) are in gwei.

Top-level fields​

FieldDescription
versionOptional. 2 is the current schema. A file with no version is treated as version 2 as soon as it contains any v2 builder field (builders, min_bid, builder_boost_factor, or max_execution_payment), with an info log. Don't set version: 1 on a file with v2 builder fields; Prysm takes the version as written. A version above 2 fails to load.
proposer_configA map from validator BLS public key (98-character 0x-prefixed hex) to the options for that key.
default_configOptions for every validator key not listed in proposer_config.

Options (per key, and in default_config)​

FieldDescription
fee_recipientThe Ethereum address that receives priority fees and, after Gloas, builder payments. A per-key value overrides default_config, which overrides --suggested-fee-recipient.
gas_limitThe gas limit your validator asks for in blocks built for it. New in v2 at this level. Leave it unset to follow the network's scheduled gas limit, or the chain default in your Prysm release when no schedule entry applies (the command-line options page shows that default for --suggested-gas-limit). Set it only to use a fixed value instead, and note that --suggested-gas-limit replaces it; see the warning above. In v1, the gas limit was set inside builder; that location stops working at the Gloas fork.
graffitiThe graffiti string included in blocks proposed by this key.
builderBuilder configuration for this key. See below. Leave it out to use the builder configuration from default_config.

The builder object​

FieldDescription
buildersThe builders this key requests bids from. See Builder entries. Leaving it out means the key uses the list from default_config; an empty list ([]) means it requests bids from no builders (bids broadcast over P2P can still win; see How a bid is valued). At most 64 entries. Duplicate or invalid entries are dropped with a warning; values that aren't valid 0x-hex fail the load.
min_bidMinimum effective value, in gwei; lower bids are ignored. Unset means no minimum. Can be overridden per entry.
max_execution_paymentMaximum execution payment, in gwei, counted toward a bid: unset or 0 counts none, 18446744073709551615 counts it in full. This is how much you trust the builder to pay; see Configuring builders. Can be overridden per entry.
builder_boost_factorPercentage applied to bid values before comparing them with your local block: 100 (default) is neutral, above favors builders, below favors your block, 0 means a bid never wins. Can be overridden per entry.
enabledLegacy (v1). Registers the key with MEV-Boost before the Gloas fork, even next to builders: []. Ignored by the Gloas builder settings and removed at the fork. In v2, a non-empty builders list registers the key instead; see Running v2 settings before the Gloas fork.
gas_limitLegacy (v1). The MEV-Boost registration gas limit. In v2, set gas_limit next to fee_recipient instead.

The v1 relays field is deprecated and ignored, but still accepted.

Builder entries​

Each entry in a builders list describes one builder your validator can request bids from:

FieldDescription
urlRequired. The builder's HTTP(S) endpoint, up to 2048 bytes, with an ASCII hostname. Entries with the same url and auth_data are duplicates.
min_bidOverrides the enclosing config's min_bid for this builder.
max_execution_paymentOverrides the enclosing config's max_execution_payment for this builder.
builder_boost_factorOverrides the enclosing config's builder_boost_factor for this builder.
builder_pubkeysOptional allowlist of builder BLS public keys (48-byte 0x-hex strings, at most 64). If set, only bids from these builders are accepted from this URL.
auth_dataOptional bytes, as a 0x-hex string, that your validator signs to authenticate its requests to this builder. Defaults to the lowercased hostname of url (builder.example; IPv6 in brackets), as the builder spec defines, so most operators never set it. At most 4096 bytes.

A field not set on an entry is taken from the enclosing builder config, and then from the builder config in default_config. builder_pubkeys and auth_data use the same names and 0x-hex format as the keymanager builder API, so you can copy an entry between the two. Files written for an earlier development build used a pubkeys field with base64 values; rename the field and convert each value to hex (echo '<base64 value>' | base64 -d | od -An -tx1 | tr -d ' \n', then prefix 0x).

How a bid is valued​

After Gloas, the beacon node builds a local payload for every proposal, requests bids from your configured builders (in parallel, with a 600ms budget by default; --builder-bid-timeout on the beacon node), and collects bids broadcast over the P2P network. Each bid that passes the chain's validity checks is valued at its value, which the protocol guarantees from the builder's staked balance, plus its execution_payment, which the builder only promises to pay, counted up to your max_execution_payment. Bids below min_bid are discarded; the rest are multiplied by builder_boost_factor / 100, and the highest is compared with your local payload. Ties go to your own block.

Bids from the P2P network. Builders can also broadcast bids to every proposer over P2P without any configuration. These must carry a zero execution_payment, so only their guaranteed value counts, and Prysm compares them with your local payload on every proposal, whether or not you configured any builders, using the min_bid and builder_boost_factor from your builder config (none and 100 if you have no config). An empty builders list stops bid requests, not P2P bids; to always use your own block, set builder_boost_factor to 0.

If no bid wins, your validator uses its own payload. A builder that wins and then doesn't reveal its payload is blacklisted for the rest of the epoch, or for 256 epochs after a second failure within five, and its bids are ignored meanwhile; see How a Gloas proposal uses builders for the full flow.

The gas limit schedule​

From the Gloas fork, a key with no gas_limit on the key or in default_config uses the network's scheduled gas limit (EIP-8261), taken from the GAS_LIMIT_SCHEDULE entries in the network config, or the chain default when no entry applies yet. Prysm ships the schedule for the networks it supports. On a custom network or devnet, pass the network's config.yaml to the validator client with --chain-config-file too, or it won't have one. To see the gas limit a key signs, call the keymanager GET /eth/v1/validator/{pubkey}/gas_limit endpoint.

Inheritance and merge rules​

min_bid, max_execution_payment, and builder_boost_factor are inherited one field at a time. A per-key value takes priority. If the key doesn't set a field, the value from default_config is used. If neither sets it, the default applies: no minimum bid, no promised payment counted, and a boost factor of 100. Builder entries inherit from their enclosing config in the same way.

The builders list is replaced, not merged. A per-key list, including an empty list ([]), replaces the default list completely. If a key doesn't set builders, it uses the default list, and a key with no builder object at all uses the whole builder object from default_config. So to stop a single key from requesting builder bids, set "builders": [].

gas_limit works the same way: a per-key value takes priority over default_config, and if neither sets it, the network's scheduled gas limit or the chain default applies. --suggested-gas-limit replaces both levels for every key.

Keymanager APIs​

The fee recipient, gas limit, graffiti, and builder_config endpoints read and write these settings for one key at a time; see Keymanager APIs for their behavior and wire format. Changes made through them survive restarts unless a settings file or URL replaces them at startup, as described in How proposer settings are supplied.

Startup warnings explained​

Unknown fields, a version above 2, invalid builder flags, and builder_pubkeys or auth_data values that aren't 0x-hex stop the settings from loading. Builder entries that break a size or format limit are dropped with a warning instead. Most messages below appear at startup; a few repeat as long as the cause remains.

Log message (abbreviated)MeaningAction
"Proposer settings contain v2 builder fields but no version; treating the source as version 2" (info)Your unversioned settings are being read as version 2.None. Add "version": 2 to avoid the message.
"Proposer settings contain deprecated v1 builder fields (enabled, builder-level gas limits); they stop applying at the gloas fork…"Your network has Gloas scheduled and your settings contain v1 builder fields (--enable-builder, or --suggested-gas-limit without v2 settings, counts too).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 fields remain.Migrate to v2 now.
"V1 builder settings, including gas limits, do not apply to gloas and were replaced with defaults…"At the fork, Prysm removed your v1 builder settings.Add v2 settings if you want builders or a fixed gas limit.
"Builders have no max_execution_payment (default 0): execution payment is ignored, so these builders' bids may lose to the local payload."The listed builders have no max_execution_payment on the entry or on any builder config they inherit from, so only each bid's value counts. Gloas-scheduled networks only; an explicit 0 doesn't trigger it.Set max_execution_payment on each entry (see Configuring builders), or ignore it if that's what you want.
"Removed N invalid or duplicate builder entries from proposer settings"Entries had a missing, too long, or unparseable url, a non-ASCII hostname, more than 64 entries (the first 64 are kept), more than 64 or wrong-length builder_pubkeys, auth_data over 4096 bytes, or duplicated another entry.Fix the entries named in the log's reasons field (duplicates are counted but not listed).
"--enable-builder is legacy (pre-gloas) mev-boost content and has no effect after the gloas fork…"--enable-builder is set together with v2 settings.Remove the flag once your v2 settings say which keys use builders.
"--suggested-gas-limit overrides the network gas limit schedule from the Gloas fork; remove it to follow the schedule"The flag fixes every key's gas limit, replacing any gas_limit in your settings, so scheduled increases won't apply. A second warning follows if the value is above the highest scheduled limit.Remove the flag unless you want a fixed gas limit.
"Dropped the default builder settings a previous run stored in the validator DB…" (or the same for the default gas limit)Stored default builders or a default gas limit weren't reused because this run's flags and settings source don't set them.Pass the flags (or the settings source) on every start.
"…configure Gloas builders, but this network has no Gloas fork scheduled"Builder flags are set on a network without Gloas. Only --builder-urls does anything here (it enables MEV-Boost registration).Remove the flags, or check that you're on the right network.
"The default_config from --proposer-settings-file replaces the builder defaults set by …"The settings source and the builder flags both set defaults; the file wins.Expected. Remove the flags, or remove default_config from the source.
"Default builder config has no default fee recipient; only keys with their own fee recipient can register"default_config has a builder object but no fee recipient, so keys without their own fee recipient aren't registered with MEV-Boost. Repeats every slot before the fork.Set fee_recipient in default_config, or use --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…"Your settings source is replacing stored per-key settings; the log lists them in droppedKeys and overriddenKeys.Expected if you manage keys with a file. Keymanager API changes don't 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, with a flag or in a file. You don't need "version": 2, a builder section, or any new flags. After the fork, your validator requests no builder bids and its gas limit follows the network schedule, unless you set --suggested-gas-limit or a gas_limit. Trustless bids broadcast over P2P can still beat your own block; see How a bid is valued if you never want that.

Can I mix the flags and a v2 file?​

Yes, and the file takes priority for everything except the gas limit: a default_config in the file replaces --suggested-fee-recipient and the builder flags, so put those values in the file. --suggested-gas-limit applies on top of the file: it replaces every gas_limit in it, per key and in default_config, and overrides the gas limit schedule after the fork. --enable-builder only affects registration before the fork. Prysm warns about both flags.