proposer settings updates for proposer preferences validator client side

[james-prysm]

What type of PR is this?

Bug fix

What does this PR do? Why is it needed?

• New schema version: ProposerSettingsPayload.version = 2. Existing v1/unset files keep working — the loader preserves them as-is, but a deprecation warning is logged at startup when gloas is scheduled on the network. The validator runtime upgrades v1 → v2 in place (Settings.UpgradeToV2) once gloas is active (currentEpoch >= GloasForkEpoch), via upgradeProposerSettingsToV2 called from PushProposerSettings / submitProposerPreferences: builder.gas_limit is promoted to the top-level gas_limit (default config and per-validator entries, unless a top-level value is already set), all builder blocks are dropped, and the upgraded settings are persisted to the DB. The upgrade is deliberately deferred until the fork — not earlier — because the pre-gloas relay-registration path still reads the builder block. Settings already on v2 are never rewritten.

• gas_limit is a new top-level field on ProposerOptionPayload (v2): the target gas limit signed into gloas proposer preferences, honored per-validator and in default_config. Resolution: per-validator gas_limit → default_config.gas_limit → chain default (zero values fall through).

• Two independent gas limit signals: relay registrations (mev-boost, pre-gloas) always read builder.gas_limit; proposer preferences always read the top-level gas_limit. A v2 file migrated before gloas can keep its builder block (enabled, relays, gas_limit) for registrations while declaring the preferences target at the top level — the two never mix.

• Keymanager gas-limit API is version-aware: on v1 settings it keeps managing the builder gas limit (registration signal); on v2 it manages the top-level gas limit (preferences signal).

ethereum/keymanager-APIs#86 updated here people did not favor this

Beacon-node changes are not in this PR.

Example files

v1 (legacy — unchanged, still supported):

{
  "proposer_config": {
    "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {
      "fee_recipient": "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3",
      "builder": { "enabled": true, "gas_limit": "45000000", "relays": ["https://example-relay.com"] }
    }
  },
  "default_config": {
    "fee_recipient": "0x6e35733c5af9B61374A128e6F85f553aF09ff89A",
    "builder": { "enabled": true, "gas_limit": "40000000" }
  }
}

v2 (new format — the builder block is optional and keeps its registration meaning until gloas):

{
  "version": 2,
  "proposer_config": {
    "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {
      "fee_recipient": "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3",
      "gas_limit": "45000000",
      "builder": { "enabled": true, "gas_limit": "45000000", "relays": ["https://example-relay.com"] }
    }
  },
  "default_config": {
    "fee_recipient": "0x6e35733c5af9B61374A128e6F85f553aF09ff89A",
    "gas_limit": "40000000"
  }
}

Behavior matrix

"Registrations" = signed validator registrations to builder relays (pre-gloas only). "Preferences" = signed gloas proposer preferences (submission begins one epoch before the fork for next-epoch duties).

Schema	Builder block	Before gloas	At/after gloas
v1	with builder (enabled)	Registrations sent with builder.gas_limit. Preferences (from gloas−1) use the chain default — the builder gas limit isn't consulted for preferences until the migration promotes it. Startup deprecation warning (when gloas is scheduled).	Auto-migrated to v2 on the first settings push: builder.gas_limit promoted to top-level gas_limit (unless already set), builder blocks dropped, persisted to DB. Registrations stop; preferences carry the promoted gas limit.
v1	without builder	No registrations. Preferences use the chain default.	Auto-migrated to v2 (version bump only). Preferences use the chain default; fee recipients unchanged.
v2	with builder (enabled)	Registrations sent with builder.gas_limit, exactly as on v1. Preferences use the top-level gas_limit.	Registrations stop at the fork; builder block becomes inert. Preferences use the top-level gas_limit.
v2	without builder	No registrations — explicit opt-out. Preferences (from gloas−1) use the top-level gas_limit.	Steady state: preferences only.

test kurtosis

check that proposer preferences are updated correctly, snooper is enabled.

extra_files:
  proposer-config-v2.json: |
    {
      "version": 2,
      "default_config": {
        "fee_recipient": "0x6e35733c5af9B61374A128e6F85f553aF09ff89A",
        "gas_limit": "40000000"
      }
    }

participants_matrix:
  el:
    - el_type: ethrex
      el_image: ethpandaops/ethrex:glamsterdam-devnet-4
  cl:
    - cl_type: prysm
      cl_image: gcr.io/offchainlabs/prysm/beacon-chain:latest
      vc_image: gcr.io/offchainlabs/prysm/validator:latest
      cl_extra_params:
        - --verbosity=debug
      vc_extra_mounts:
        /proposer: proposer-config-v2.json
      vc_extra_params:
        - --enable-beacon-rest-api
        - --verbosity=debug
        # Point prysm vc at the mounted v2 proposer settings file.
        - --proposer-settings-file=/proposer/proposer-config-v2.json
  count: 2

network_params:
  fulu_fork_epoch: 0
  gloas_fork_epoch: 2
  seconds_per_slot: 6
  genesis_delay: 40

additional_services:
  - dora
  - spamoor

# spamoor generates load so payloads are non-empty: eoatx for normal EL txs, blobs to exercise the
# blob/KZG path through the stateless envelope Contents flow.
spamoor_params:
  spammers:
    - scenario: eoatx
      config:
        throughput: 10
    - scenario: blobs
      config:
        throughput: 2
keymanager_enabled: true
global_log_level: debug

curl -s -H "Authorization: Bearer $TOKEN" $URL/eth/v1/keystores | jq -r '.data[].validating_pubkey'

PK=<pubkey>
curl -s -H "Authorization: Bearer $TOKEN" $URL/eth/v1/validator/$PK/gas_limit

curl -s -X DELETE -H "Authorization: Bearer $TOKEN" $URL/eth/v1/validator/$PK/gas_limit

Note beacon node updates are not part of this pr.

Which issues(s) does this PR fix?

Fixes #

Other notes for review

Acknowledgements

• I have read CONTRIBUTING.md.
• I have included a uniquely named changelog fragment file.
• I have added a description with sufficient context for reviewers to understand this PR.
• I have tested that my changes work as expected and I added a testing plan to the PR description (if applicable).

[CLAassistant]

All committers have signed the CLA.

[nalepae]

The example in PR desc asserts DELETE … gas_limit ==> 204 then GET … gas_limit ==> 40.000.000 (from file). With the current ResetGasLimit implementation it would return the chain default, not 40.000.000.

[nalepae]

Not tested

[james-prysm]

added in 7fd6e54

[syjn99]

The validator runtime upgrades v1 → v2 in place (Settings.UpgradeToV2) one epoch before the Gloas fork

Little bit confused at this point as it deviates with PR description: as the upgrade will take place when currentEpoch >= gloasForkEpoch.

[james-prysm]

yeah let me update the note, instead of upgrading the file it only upgrades after gloas, we take the builder gas limit before. I wonder if it's better if I also allow for v2 before and just ignore builder configs afterwards.

[james-prysm]

6846b55 updated to support v2 early migration

[james-prysm]

I need to open an updated docs pr for this , related to issue OffchainLabs/prysm-documentation#1187