proposer settings updates for proposer preferences validator client side (OffchainLabs#16762)

**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):

```json
{
  "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):

```json
{
  "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**

- [x] I have read
[CONTRIBUTING.md](https://github.com/prysmaticlabs/prysm/blob/develop/CONTRIBUTING.md).
- [x] I have included a uniquely named [changelog fragment
file](https://github.com/prysmaticlabs/prysm/blob/develop/CONTRIBUTING.md#maintaining-changelogmd).
- [x] I have added a description with sufficient context for reviewers
to understand this PR.
- [x] I have tested that my changes work as expected and I added a
testing plan to the PR description (if applicable).

---------

Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com>

Author: james-prysm

changelog/james-prysm_proposer-preferences-settings.md

@@ -0,0 +1,6 @@
+### Changed
+
+- proposer settings no longer recognize the builder option post gloas and introduces a new gas_limit option for proposer preferences, supported per validator and in the default config.
+- the builder gas_limit and the new top-level gas_limit are independent signals: relay registrations keep reading builder.gas_limit pre-gloas, while proposer preferences read only the top-level gas_limit (falling back to the default config, then the chain default).
+- gas limit keymanager endpoint continues to update gas limit on a per validator basis post gloas.
+- v1 proposer settings files remain supported without modification: a deprecation warning is logged on gloas-scheduled networks and settings are upgraded automatically in the validator client at the gloas fork, promoting builder gas limits to the top level unless one is already set. Settings already on v2 are never rewritten.

config/proposer/BUILD.bazel

@@ -2,18 +2,23 @@ load("@prysm//tools/go:def.bzl", "go_library", "go_test")
 
 go_library(
     name = "go_default_library",
-    srcs = ["settings.go"],
+    srcs = [
+        "log.go",
+        "settings.go",
+    ],
     importpath = "github.com/OffchainLabs/prysm/v7/config/proposer",
     visibility = ["//visibility:public"],
     deps = [
         "//config:go_default_library",
         "//config/fieldparams:go_default_library",
+        "//config/params:go_default_library",
         "//consensus-types/validator:go_default_library",
         "//encoding/bytesutil:go_default_library",
         "//proto/prysm/v1alpha1/validator-client:go_default_library",
         "@com_github_ethereum_go_ethereum//common:go_default_library",
         "@com_github_ethereum_go_ethereum//common/hexutil:go_default_library",
         "@com_github_pkg_errors//:go_default_library",
+        "@com_github_sirupsen_logrus//:go_default_library",
     ],
 )
 
@@ -26,8 +31,10 @@ go_test(
         "//config/params:go_default_library",
         "//consensus-types/validator:go_default_library",
         "//encoding/bytesutil:go_default_library",
+        "//testing/assert:go_default_library",
         "//testing/require:go_default_library",
         "@com_github_ethereum_go_ethereum//common:go_default_library",
         "@com_github_ethereum_go_ethereum//common/hexutil:go_default_library",
+        "@com_github_sirupsen_logrus//hooks/test:go_default_library",
     ],
 )

config/proposer/loader/BUILD.bazel

@@ -13,6 +13,7 @@ go_test(
         "//config/proposer:go_default_library",
         "//consensus-types/validator:go_default_library",
         "//encoding/bytesutil:go_default_library",
+        "//proto/prysm/v1alpha1/validator-client:go_default_library",
         "//testing/assert:go_default_library",
         "//testing/require:go_default_library",
         "//validator/db/iface:go_default_library",

config/proposer/loader/loader.go

@@ -179,12 +179,25 @@ func (psl *SettingsLoader) Load(cliCtx *cli.Context) (*proposer.Settings, error)
 	if err != nil {
 		return nil, err
 	}
+	ps.WarnDeprecatedSchema()
 	if err := psl.db.SaveProposerSettings(cliCtx.Context, ps); err != nil {
 		return nil, err
 	}
 	return ps, nil
 }
 
+func hasBuilderShape(p *validatorpb.ProposerSettingsPayload) bool {
+	if p.DefaultConfig != nil && p.DefaultConfig.Builder != nil {
+		return true
+	}
+	for _, o := range p.ProposerConfig {
+		if o != nil && o.Builder != nil {
+			return true
+		}
+	}
+	return false
+}
+
 func (psl *SettingsLoader) applyOverrides() {
 	if psl.options.builderConfig != nil && psl.options.gasLimit != nil {
 		psl.options.builderConfig.GasLimit = *psl.options.gasLimit
@@ -250,41 +263,51 @@ func (psl *SettingsLoader) processProposerSettings(loadedSettings, dbSettings *v
 	return newSettings
 }
 
-// mergeProposerSettings merges database settings with loaded settings, giving precedence to loadedSettings
+// mergeProposerSettings merges database settings with loaded settings, giving
+// precedence to loadedSettings. Dispatches by schema version: v1 still flows
+// through Builder; v2 lives on Option directly.
 func mergeProposerSettings(loaded, db *validatorpb.ProposerSettingsPayload, options *flagOptions) *validatorpb.ProposerSettingsPayload {
 	merged := &validatorpb.ProposerSettingsPayload{}
+	if db != nil {
+		merged.Version = db.Version
+	}
+	// v1-shaped source content must not inherit DB's v2, else the runtime upgrade is skipped.
+	if loaded != nil && (loaded.Version != 0 || hasBuilderShape(loaded)) {
+		merged.Version = loaded.Version
+	}
 
-	// Apply builder config overrides
 	var builderConfig *validatorpb.BuilderConfig
 	var gasLimitOnly *validator.Uint64
-
 	if options != nil {
 		if options.builderConfig != nil {
 			builderConfig = options.builderConfig.ToConsensus()
 		}
-		if options.gasLimit != nil {
-			gasLimitOnly = options.gasLimit
-		}
+		gasLimitOnly = options.gasLimit
 	}
 
-	// Merge DefaultConfig
+	if merged.Version == proposer.SchemaV2 {
+		return mergeProposerSettingsV2(merged, loaded, db, gasLimitOnly)
+	}
+	return mergeProposerSettingsV1(merged, loaded, db, builderConfig, gasLimitOnly)
+}
+
+func mergeProposerSettingsV1(merged, loaded, db *validatorpb.ProposerSettingsPayload, builderConfig *validatorpb.BuilderConfig, gasLimitOnly *validator.Uint64) *validatorpb.ProposerSettingsPayload {
+	stripDBBuilder := builderConfig == nil
+
 	if db != nil && db.DefaultConfig != nil {
 		merged.DefaultConfig = db.DefaultConfig
-		// db always falls back to local building if no builder settings are provided
-		if builderConfig == nil {
+		if stripDBBuilder {
 			db.DefaultConfig.Builder = nil
 		}
 	}
 	if loaded != nil && loaded.DefaultConfig != nil {
 		merged.DefaultConfig = loaded.DefaultConfig
 	}
 
-	// Merge ProposerConfig
 	if db != nil && len(db.ProposerConfig) > 0 {
 		merged.ProposerConfig = db.ProposerConfig
-		for _, option := range db.ProposerConfig {
-			// db always falls back to local building if no builder settings are provided
-			if builderConfig == nil {
+		if stripDBBuilder {
+			for _, option := range db.ProposerConfig {
 				option.Builder = nil
 			}
 		}
@@ -302,10 +325,46 @@ func mergeProposerSettings(loaded, db *validatorpb.ProposerSettingsPayload, opti
 		}
 	}
 
-	if merged.DefaultConfig == nil && builderConfig != nil {
-		merged.DefaultConfig = &validatorpb.ProposerOptionPayload{Builder: builderConfig}
+	if merged.DefaultConfig == nil {
+		switch {
+		case builderConfig != nil:
+			merged.DefaultConfig = &validatorpb.ProposerOptionPayload{Builder: builderConfig}
+		case gasLimitOnly != nil:
+			merged.DefaultConfig = &validatorpb.ProposerOptionPayload{
+				Builder: &validatorpb.BuilderConfig{Enabled: false, GasLimit: *gasLimitOnly},
+			}
+		}
+	}
+	return merged
+}
+
+func mergeProposerSettingsV2(merged, loaded, db *validatorpb.ProposerSettingsPayload, gasLimitOnly *validator.Uint64) *validatorpb.ProposerSettingsPayload {
+	if db != nil && db.DefaultConfig != nil {
+		merged.DefaultConfig = db.DefaultConfig
+	}
+	if loaded != nil && loaded.DefaultConfig != nil {
+		merged.DefaultConfig = loaded.DefaultConfig
+	}
+	if db != nil && len(db.ProposerConfig) > 0 {
+		merged.ProposerConfig = db.ProposerConfig
+	}
+	if loaded != nil && len(loaded.ProposerConfig) > 0 {
+		merged.ProposerConfig = loaded.ProposerConfig
 	}
 
+	if gasLimitOnly == nil {
+		return merged
+	}
+	if merged.DefaultConfig == nil {
+		merged.DefaultConfig = &validatorpb.ProposerOptionPayload{GasLimit: *gasLimitOnly}
+	} else {
+		merged.DefaultConfig.GasLimit = *gasLimitOnly
+	}
+	for _, option := range merged.ProposerConfig {
+		if option != nil {
+			option.GasLimit = *gasLimitOnly
+		}
+	}
 	return merged
 }
 
@@ -320,7 +379,13 @@ func processBuilderConfig(current *validatorpb.BuilderConfig, override *validato
 		}
 		return current
 	}
-	return override
+	if override != nil {
+		return override
+	}
+	if gasLimitOnly != nil {
+		return &validatorpb.BuilderConfig{Enabled: false, GasLimit: *gasLimitOnly}
+	}
+	return nil
 }
 
 func reviewGasLimit(gasLimit validator.Uint64) validator.Uint64 {