Add GET/POST/DELETE /eth/v1/validator/{pubkey}/builders keymanager endpoints

changelog/james-prysm_keymanager-builders-endpoints.md

@@ -0,0 +1,21 @@
+### Added
+
+- Add `GET`/`POST`/`DELETE /eth/v1/validator/{pubkey}/builders` keymanager endpoints for per-key builder configuration (keymanager-APIs #88).
+
+### Changed
+
+- Add v2 proposer settings (`"version": 2`): builder fields a key does not set inherit from `default_config`. v2 has no `enabled` field; a key participates in builder registration when its resolved `builders` list names at least one builder, and an explicit empty `builders` list opts the key out.
+- v1 builder settings are not migrated to v2: at the gloas fork fee recipients and graffiti carry over, while v1 builder content — including its gas limits — is replaced with defaults, with a warning. Gas limits apply only when explicitly set on v2 settings, so validators follow future chain-default gas limit increases unless they opt out. `--enable-builder` has no effect with v2 settings.
+- Setting a fee recipient, gas limit, or graffiti no longer snapshots `default_config`'s builder settings onto that key; the key keeps following the default as it changes.
+
+### Deprecated
+
+- `--with-builder` generates legacy (pre-gloas) mev-boost builder settings, which are discontinued at the gloas fork; the command now warns when the flag is used.
+
+### Fixed
+
+- Fix the minimal slashing protection database decoding unset builder settings fields as explicit zero values; both validator DB backends now read the same stored settings identically.
+
+### Removed
+
+- Remove the unused `relays` field from the builder config; a settings file that still contains it is unaffected.

cmd/prysmctl/validator/cmd.go

@@ -55,7 +55,8 @@ var (
 	WithBuilderFlag = &cli.BoolFlag{
 		Name:    "with-builder",
 		Aliases: []string{"wb"},
-		Usage:   "adds default builder options to proposer settings output, used for enabling mev-boost and relays",
+		Usage: "adds legacy (pre-gloas) mev-boost builder options to the proposer settings output; " +
+			"these are discontinued at the gloas fork, where builder participation requires v2 settings with a builders list",
 	}
 
 	DefaultFeeRecipientFlag = &cli.StringFlag{

cmd/prysmctl/validator/proposer_settings.go

@@ -69,6 +69,7 @@ func getProposerSettings(c *cli.Context, r io.Reader) error {
 		log.Infof("The default fee recipient is set to %s", defaultFeeRecipient)
 		var builderSettings *validatorpb.BuilderConfig
 		if c.Bool(WithBuilderFlag.Name) {
+			log.Warnf("--%s generates legacy (pre-gloas) mev-boost settings; they are discontinued at the gloas fork. Gloas builder participation requires v2 proposer settings with a builders list.", WithBuilderFlag.Name)
 			builderSettings = &validatorpb.BuilderConfig{
 				Enabled:  true,
 				GasLimit: validatorType.Uint64(params.BeaconConfig().DefaultBuilderGasLimit),

config/proposer/BUILD.bazel

@@ -24,13 +24,17 @@ go_library(
 
 go_test(
     name = "go_default_test",
-    srcs = ["settings_test.go"],
+    srcs = [
+        "effective_builder_config_test.go",
+        "settings_test.go",
+    ],
     embed = [":go_default_library"],
     deps = [
         "//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",
         "//testing/assert:go_default_library",
         "//testing/require:go_default_library",
         "@com_github_ethereum_go_ethereum//common:go_default_library",

config/proposer/effective_builder_config_test.go

@@ -0,0 +1,98 @@
+package proposer
+
+import (
+	"testing"
+
+	"github.com/OffchainLabs/prysm/v7/consensus-types/validator"
+	"github.com/OffchainLabs/prysm/v7/testing/require"
+)
+
+// These cases mirror the test vectors proposed upstream on keymanager-APIs #87
+// for builder-config inheritance granularity.
+func TestEffectiveBuilderConfig(t *testing.T) {
+	entryA := &BuilderEntry{URL: "https://a"}
+	entryB := &BuilderEntry{URL: "https://b"}
+	entryC := &BuilderEntry{URL: "https://c"}
+
+	t.Run("nil per-key returns default", func(t *testing.T) {
+		def := &BuilderConfig{Enabled: true}
+		require.Equal(t, def, effectiveBuilderConfig(nil, def))
+	})
+	t.Run("nil default returns per-key", func(t *testing.T) {
+		perKey := &BuilderConfig{Enabled: true}
+		require.Equal(t, perKey, effectiveBuilderConfig(perKey, nil))
+	})
+	t.Run("min_bid inherits when per-key omits it", func(t *testing.T) {
+		def := &BuilderConfig{Enabled: true, Builders: []*BuilderEntry{entryA, entryB}, MinBid: uint64ValPtr(5000000)}
+		perKey := &BuilderConfig{Enabled: true, Builders: []*BuilderEntry{entryC}}
+		eff := effectiveBuilderConfig(perKey, def)
+		require.NotNil(t, eff.MinBid)
+		require.Equal(t, validator.Uint64(5000000), *eff.MinBid)
+		require.Equal(t, 1, len(eff.Builders))
+		require.Equal(t, "https://c", eff.Builders[0].URL)
+	})
+	t.Run("explicit zero max payment is preserved, not inherited over", func(t *testing.T) {
+		def := &BuilderConfig{MaxExecutionPayment: uint64ValPtr(1000000000)}
+		perKey := &BuilderConfig{Enabled: true, MaxExecutionPayment: uint64ValPtr(0)}
+		eff := effectiveBuilderConfig(perKey, def)
+		require.NotNil(t, eff.MaxExecutionPayment)
+		require.Equal(t, validator.Uint64(0), *eff.MaxExecutionPayment)
+	})
+	t.Run("unset max payment inherits default", func(t *testing.T) {
+		def := &BuilderConfig{MaxExecutionPayment: uint64ValPtr(1000000000)}
+		perKey := &BuilderConfig{Enabled: true}
+		eff := effectiveBuilderConfig(perKey, def)
+		require.NotNil(t, eff.MaxExecutionPayment)
+		require.Equal(t, validator.Uint64(1000000000), *eff.MaxExecutionPayment)
+	})
+	t.Run("explicit per-key disable wins over enabled default", func(t *testing.T) {
+		def := &BuilderConfig{Enabled: true}
+		perKey := &BuilderConfig{Enabled: false, MinBid: uint64ValPtr(1)}
+		require.Equal(t, false, effectiveBuilderConfig(perKey, def).IsEnabled())
+	})
+	t.Run("present per-key builder config is authoritative on enabled", func(t *testing.T) {
+		// A per-key config with enabled false does not inherit an enabled default;
+		// whole-config inheritance happens only when the per-key builder config is nil.
+		def := &BuilderConfig{Enabled: true}
+		perKey := &BuilderConfig{MinBid: uint64ValPtr(1)}
+		require.Equal(t, false, effectiveBuilderConfig(perKey, def).IsEnabled())
+		require.Equal(t, true, effectiveBuilderConfig(nil, def).IsEnabled())
+	})
+	t.Run("present builders list replaces, never unions", func(t *testing.T) {
+		def := &BuilderConfig{Builders: []*BuilderEntry{entryA, entryB}}
+		perKey := &BuilderConfig{Builders: []*BuilderEntry{entryC}}
+		eff := effectiveBuilderConfig(perKey, def)
+		require.Equal(t, 1, len(eff.Builders))
+		require.Equal(t, "https://c", eff.Builders[0].URL)
+	})
+	t.Run("absent builders list inherits default list", func(t *testing.T) {
+		def := &BuilderConfig{Builders: []*BuilderEntry{entryA, entryB}}
+		perKey := &BuilderConfig{Enabled: true}
+		require.Equal(t, 2, len(effectiveBuilderConfig(perKey, def).Builders))
+	})
+	t.Run("zero gas limit inherits default gas limit", func(t *testing.T) {
+		def := &BuilderConfig{GasLimit: validator.Uint64(30000000)}
+		perKey := &BuilderConfig{Enabled: true}
+		require.Equal(t, validator.Uint64(30000000), effectiveBuilderConfig(perKey, def).GasLimit)
+	})
+	t.Run("boost factor inherits per field", func(t *testing.T) {
+		def := &BuilderConfig{MinBid: uint64ValPtr(5000000), BuilderBoostFactor: uint64ValPtr(90)}
+		perKey := &BuilderConfig{Enabled: true, BuilderBoostFactor: uint64ValPtr(120)}
+		eff := effectiveBuilderConfig(perKey, def)
+		require.Equal(t, validator.Uint64(5000000), *eff.MinBid)
+		require.Equal(t, validator.Uint64(120), *eff.BuilderBoostFactor)
+	})
+	t.Run("both-set min_bid: per-key wins", func(t *testing.T) {
+		def := &BuilderConfig{MinBid: uint64ValPtr(5000000)}
+		perKey := &BuilderConfig{MinBid: uint64ValPtr(7000000)}
+		require.Equal(t, validator.Uint64(7000000), *effectiveBuilderConfig(perKey, def).MinBid)
+	})
+	t.Run("nonzero per-key gas limit wins over default", func(t *testing.T) {
+		def := &BuilderConfig{GasLimit: validator.Uint64(30000000)}
+		perKey := &BuilderConfig{GasLimit: validator.Uint64(45000000)}
+		require.Equal(t, validator.Uint64(45000000), effectiveBuilderConfig(perKey, def).GasLimit)
+	})
+	t.Run("nil nil is nil", func(t *testing.T) {
+		require.Equal(t, (*BuilderConfig)(nil), effectiveBuilderConfig(nil, nil))
+	})
+}

config/proposer/loader/loader.go

@@ -1,7 +1,6 @@
 package loader
 
 import (
-	"encoding/json"
 	"fmt"
 	"strconv"
 
@@ -132,13 +131,9 @@ func (psl *SettingsLoader) Load(cliCtx *cli.Context) (*proposer.Settings, error)
 			return nil, err
 		}
 		dbSettings = dbps.ToConsensus()
-		log.Debugf("DB loaded proposer settings: %s", func() string {
-			b, err := json.Marshal(dbSettings)
-			if err != nil {
-				return err.Error()
-			}
-			return string(b)
-		}())
+		log.WithField("version", dbSettings.Version).
+			WithField("proposerKeys", len(dbSettings.ProposerConfig)).
+			Debug("Loaded proposer settings from DB")
 	}
 
 	// start to process based on load method
@@ -186,18 +181,6 @@ func (psl *SettingsLoader) Load(cliCtx *cli.Context) (*proposer.Settings, error)
 	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
@@ -231,6 +214,7 @@ func (psl *SettingsLoader) loadFromFile(cliCtx *cli.Context, dbSettings *validat
 	if settingFromFile == nil {
 		return nil, errors.Errorf("proposer settings is empty after unmarshalling from file specified by %s flag", flags.ProposerSettingsFlag.Name)
 	}
+	markExplicitEmptyBuilders(settingFromFile)
 	log.WithField(flags.ProposerSettingsFlag.Name, cliCtx.String(flags.ProposerSettingsFlag.Name)).Info("Proposer settings loaded from file")
 	return psl.processProposerSettings(settingFromFile, dbSettings), nil
 }
@@ -243,6 +227,7 @@ func (psl *SettingsLoader) loadFromURL(cliCtx *cli.Context, dbSettings *validato
 	if settingFromURL == nil {
 		return nil, errors.Errorf("proposer settings is empty after unmarshalling from url specified by %s flag", flags.ProposerSettingsURLFlag.Name)
 	}
+	markExplicitEmptyBuilders(settingFromURL)
 	log.WithField(flags.ProposerSettingsURLFlag.Name, cliCtx.String(flags.ProposerSettingsURLFlag.Name)).Infof("Proposer settings loaded from URL")
 	return psl.processProposerSettings(settingFromURL, dbSettings), nil
 }
@@ -271,10 +256,17 @@ func mergeProposerSettings(loaded, db *validatorpb.ProposerSettingsPayload, opti
 	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)) {
+	if loaded != nil && loaded.Version > merged.Version {
 		merged.Version = loaded.Version
 	}
+	if merged.Version == proposer.SchemaV2 {
+		if db != nil && db.Version < proposer.SchemaV2 {
+			promotePayloadToV2(db)
+		}
+		if loaded != nil && loaded.Version < proposer.SchemaV2 {
+			promotePayloadToV2(loaded)
+		}
+	}
 
 	var builderConfig *validatorpb.BuilderConfig
 	var gasLimitOnly *validator.Uint64
@@ -286,11 +278,60 @@ func mergeProposerSettings(loaded, db *validatorpb.ProposerSettingsPayload, opti
 	}
 
 	if merged.Version == proposer.SchemaV2 {
-		return mergeProposerSettingsV2(merged, loaded, db, gasLimitOnly)
+		return mergeProposerSettingsV2(merged, loaded, db, builderConfig, gasLimitOnly)
 	}
 	return mergeProposerSettingsV1(merged, loaded, db, builderConfig, gasLimitOnly)
 }
 
+// markExplicitEmptyBuilders stamps the persistence marker for a user source's
+// explicit "builders": [] (opt-out), which yaml keeps distinct from absent.
+func markExplicitEmptyBuilders(p *validatorpb.ProposerSettingsPayload) {
+	mark := func(opt *validatorpb.ProposerOptionPayload) {
+		if opt == nil || opt.Builder == nil {
+			return
+		}
+		if opt.Builder.Builders != nil {
+			opt.Builder.BuildersSet = true
+		}
+	}
+	mark(p.DefaultConfig)
+	for _, opt := range p.ProposerConfig {
+		mark(opt)
+	}
+}
+
+// promotePayloadToV2 mirrors Settings.UpgradeToV2: v1 builder content, including
+// its gas limits, does not apply to v2 and is dropped.
+func promotePayloadToV2(p *validatorpb.ProposerSettingsPayload) {
+	dropped := false
+	promote := func(opt *validatorpb.ProposerOptionPayload) {
+		if opt == nil || opt.Builder == nil {
+			return
+		}
+		opt.Builder = nil
+		dropped = true
+	}
+	promote(p.DefaultConfig)
+	for _, opt := range p.ProposerConfig {
+		promote(opt)
+	}
+	if dropped {
+		log.Warn("v1 builder settings, including gas limits, do not apply to the v2 schema and were replaced with defaults; provide v2 proposer settings to configure builders")
+	}
+}
+
+// selectProposerConfig keeps the pre-v2 source precedence: a loaded per-key
+// section replaces the DB's entirely, so restarting with a file resets the DB.
+func selectProposerConfig(db, loaded *validatorpb.ProposerSettingsPayload) map[string]*validatorpb.ProposerOptionPayload {
+	if loaded != nil && len(loaded.ProposerConfig) > 0 {
+		return loaded.ProposerConfig
+	}
+	if db != nil && len(db.ProposerConfig) > 0 {
+		return db.ProposerConfig
+	}
+	return nil
+}
+
 func mergeProposerSettingsV1(merged, loaded, db *validatorpb.ProposerSettingsPayload, builderConfig *validatorpb.BuilderConfig, gasLimitOnly *validator.Uint64) *validatorpb.ProposerSettingsPayload {
 	stripDBBuilder := builderConfig == nil
 
@@ -304,17 +345,12 @@ func mergeProposerSettingsV1(merged, loaded, db *validatorpb.ProposerSettingsPay
 		merged.DefaultConfig = loaded.DefaultConfig
 	}
 
-	if db != nil && len(db.ProposerConfig) > 0 {
-		merged.ProposerConfig = db.ProposerConfig
-		if stripDBBuilder {
-			for _, option := range db.ProposerConfig {
-				option.Builder = nil
-			}
+	if db != nil && stripDBBuilder {
+		for _, option := range db.ProposerConfig {
+			option.Builder = nil
 		}
 	}
-	if loaded != nil && len(loaded.ProposerConfig) > 0 {
-		merged.ProposerConfig = loaded.ProposerConfig
-	}
+	merged.ProposerConfig = selectProposerConfig(db, loaded)
 
 	if merged.DefaultConfig != nil {
 		merged.DefaultConfig.Builder = processBuilderConfig(merged.DefaultConfig.Builder, builderConfig, gasLimitOnly)
@@ -331,25 +367,26 @@ func mergeProposerSettingsV1(merged, loaded, db *validatorpb.ProposerSettingsPay
 			merged.DefaultConfig = &validatorpb.ProposerOptionPayload{Builder: builderConfig}
 		case gasLimitOnly != nil:
 			merged.DefaultConfig = &validatorpb.ProposerOptionPayload{
-				Builder: &validatorpb.BuilderConfig{Enabled: false, GasLimit: *gasLimitOnly},
+				Builder: &validatorpb.BuilderConfig{GasLimit: *gasLimitOnly},
 			}
 		}
 	}
 	return merged
 }
 
-func mergeProposerSettingsV2(merged, loaded, db *validatorpb.ProposerSettingsPayload, gasLimitOnly *validator.Uint64) *validatorpb.ProposerSettingsPayload {
+func mergeProposerSettingsV2(merged, loaded, db *validatorpb.ProposerSettingsPayload, builderConfig *validatorpb.BuilderConfig, 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
+	merged.ProposerConfig = selectProposerConfig(db, loaded)
+
+	// v2 has no enabled toggle: participation follows the configured builders
+	// list, so --enable-builder has nothing to force on.
+	if builderConfig != nil {
+		log.Warnf("--%s has no effect with v2 proposer settings; configure builders via the settings source or keymanager API", flags.EnableBuilderFlag.Name)
 	}
 
 	if gasLimitOnly == nil {
@@ -383,7 +420,7 @@ func processBuilderConfig(current *validatorpb.BuilderConfig, override *validato
 		return override
 	}
 	if gasLimitOnly != nil {
-		return &validatorpb.BuilderConfig{Enabled: false, GasLimit: *gasLimitOnly}
+		return &validatorpb.BuilderConfig{GasLimit: *gasLimitOnly}
 	}
 	return nil
 }