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

beacon-chain/rpc/prysm/v1alpha1/validator/server.go

@@ -97,7 +97,7 @@ type Server struct {
 	lastBidSlot                      primitives.Slot
 	lastBidSource                    bidSource // Guarded by lastBidLock, set during Gloas block build, read when proposing.
 	lastBidBuilderURL                string    // Guarded by lastBidLock, winning Builder-API URL for lastBidSlot.
-	maxExecutionPayments             sync.Map  // validator pubkey [48]byte -> max execution payment (Gwei uint64).
+	maxExecutionPayments             sync.Map  // pubkey [48]byte -> Gwei uint64, min-collapsed per-entry caps; TODO(gloas): re-key per builder identity with beacon-APIs #630.
 }
 
 // Deprecated: The gRPC API will remain the default and fully supported through v8 (expected in 2026) but will be eventually removed in favor of REST API.

changelog/james-prysm_keymanager-builders-endpoints.md

@@ -0,0 +1,25 @@
+### Added
+
+- Add `GET`/`POST`/`DELETE /eth/v1/validator/{pubkey}/builders` keymanager endpoints for per-key builder configuration (keymanager-APIs #88). The endpoints respond 501 on networks without a scheduled gloas fork, where builder configuration cannot take effect.
+
+### Changed
+
+- Add v2 proposer settings (`"version": 2`) for configuring gloas builders; see the keymanager-APIs specification for the schema.
+- Proposer settings sources without a `version` are treated as version 2 when they contain v2 builder fields.
+- In v2 proposer settings, a nonempty `builders` list opts a key into mev-boost registration before the gloas fork, and an explicit empty list opts it 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 dropped and replaced with defaults, with a warning. Gas limits apply post-fork only when explicitly set at the option level, so validators follow future chain-default gas limit increases unless they opt out.
+- The gas-limit keymanager API writes the option-level gas limit and no longer requires an enabled builder; deleting a gas limit unsets it (following the chain default) instead of pinning the current default value. Builder registration resolves fee recipients and participation independently, so a key with an enabled builder and only a default fee recipient now registers.
+- 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.
+- `--enable-builder` and `--suggested-gas-limit` produce only legacy (pre-gloas) content: they still drive mev-boost registrations before the fork, but never override v2 proposer settings or the gas limit schedule, and warn that they have no effect after gloas. An explicitly configured gas limit below the scheduled network gas limit is honored with a once-per-epoch warning.
+
+### 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

@@ -25,13 +25,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))
+	})
+}