Add `GET`/`POST`/`DELETE /eth/v1/validator/{pubkey}/builders` keymanager endpoints by james-prysm · Pull Request #17261 · OffchainLabs/prysm

james-prysm · 2026-07-29T18:48:29Z

What type of PR is this?

Feature

What does this PR do? Why is it needed?

Adds the per-key builder configuration endpoints from [keymanager-APIs #88](ethereum/keymanager-APIs#88) and the v2 proposer-settings schema that backs them. This is how an operator tells the validator client which external builders each key may source gloas blocks from, and under what per-builder limits.

New endpoints — GET/POST/DELETE /eth/v1/validator/{pubkey}/builders:

POST replaces the key's builder configuration in full. enabled is required; each entry requires a url; no two entries may share (url, auth_data) (an omitted auth_data compares as its derived value, the UTF-8 bytes of the url). Violations are rejected with 400 rather than partially stored.
GET returns the configuration fully resolved: omitted entry fields are filled with the values that will be used (key defaults, then validator client config, then runtime fallbacks — no floor, neutral boost, trustless-only payment ceiling), so re-submitting a GET response pins those values.
DELETE removes the key's configuration so it follows the validator client again (204, also when nothing was set). This differs from enabled: false, which is a stored statement that the key sources no builder bids at all.
The builders list is tri-state: omitted = use the validator client's builders, [] = use none (p2p bids only), a list = use exactly these. The use-none marker survives persistence via a proto presence field.

v2 proposer settings ("version": 2): gas limit moves to the option level (a validator property, not a builder property), builder configs gain the builders[] entry list plus min_bid/builder_boost_factor defaults, and per-key fields resolve with field-level inheritance from default_config. v1 settings keep their exact object-level semantics until migrated. The unused relays field is removed.

Timeline across the fork

Before gloas: v1 settings behave byte-for-byte as on develop (registration, fee recipients, gas limits). The new endpoints are live; POST /builders migrates the node's settings to v2 in place (builder lists are v2 content, so writing them is the opt-in). v1 settings that contain builder content log a deprecation warning at startup; fee-recipient/graffiti-only settings never do.
One epoch before gloas: for keys with v2 builder configs, the VC starts pre-signing RequestAuths and submitting ahead-of-time builder preferences for upcoming proposal slots, so preferences are in place at the beacon node for the fork's first slot. v1 settings have nothing legitimate to warm and stay inert.
At and after gloas: any remaining v1 settings migrate automatically on the first push cycle of the fork epoch — idempotent and value-preserving (gas limits hoisted to the option level and resolving to the same values; an explicit max_execution_payment: 0 survives). mev-boost registration naturally ends. Keys whose migrated config has no builders entries solicit no builder bids and produce blocks locally: safe, but outside the builder market until the operator opts in.

Design decisions and tradeoffs

Version follows content. POST /builders upgrades to v2 immediately (explicit, authenticated opt-in); the fork is the automatic backstop for everyone else; fee recipient and graffiti are schema-neutral and never touch the version. Tradeoff: one pre-fork POST switches the whole node to v2 semantics — accepted as an explicit admin action; a store-without-upgrade variant was tried and rejected as a worse contract (content sitting in version limbo until the fork).
Migration carries nothing into the builder market. relays/--enable-builder do not translate into builder entries; participation post-gloas requires an explicitly configured list. Tradeoff: do-nothing operators lose builder revenue but never miss a proposal — the right default when the fork changes who is trusted with payments.
--enable-builder keeps its v1 meaning: it forces the default builder toggle on, even over an explicit false in the default config. Per-key enabled: false still opts a key out (the spec's escape hatch). Tradeoff: flag-over-config at the default level, chosen for continuity — a v1 file plus the flag produces the same result before and after migration.
File/URL settings stay authoritative wholesale: restarting with a file resets per-key state, exactly as today, because there is no other reliable way to clear the DB. Tradeoff: API writes are ephemeral for file users (matching the existing fee-recipient endpoints); the reset path stays predictable.
Current preferences wire is builder-URL-keyed, so same-url entries collapse to the lowest (safest) payment ceiling, and per-entry min_bid/builder_boost_factor/builder_pubkey/custom auth_data are stored and returned by GET but only take effect with the beacon-APIs Updates pubkey from bytes32 to bytes #630 inline produce wire (marked with TODO(gloas) at both the producer and consumer).

Testing plan (kurtosis)

Config (gloas-km88.yml), gloas at epoch 3 to leave pre-fork time for API calls:

participants:
  - el_type: geth
    el_image: ethpandaops/geth:bal-devnet-6
    cl_type: prysm
    cl_image: gcr.io/offchainlabs/prysm/beacon-chain:latest
    vc_image: gcr.io/offchainlabs/prysm/validator:latest
    supernode: true
    count: 2
    cl_extra_params:
      - --verbosity=debug
    vc_extra_params:
      - --verbosity=debug
      - --http-host=0.0.0.0
      - --http-port=7500

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

additional_services:
  - dora

Setup: kurtosis run --enclave km88 github.com/ethpandaops/ethereum-package --args-file gloas-km88.yml, then from inside the first VC container grab a validating pubkey (PK) and the keymanager token (TOKEN, from the wallet dir's auth-token file). All calls below run inside that container against http://127.0.0.1:7500.

A — API CRUD and resolution (pre-fork, epoch 0–2):

GET /eth/v1/validator/$PK/builders → 200 with enabled: false, builders: [], resolved fallbacks (min_bid "0", builder_boost_factor "100").
POST {"enabled":true,"min_bid":"1000","builders":[{"url":"https://builder-a.example","max_execution_payment":"250000000"}]} → 202.
GET again → entry returned with auth_data resolved to the hex of the url bytes, entry min_bid "1000" inherited from the key default.
POST a duplicate (url, auth_data) pair and an entry without url → both 400, config unchanged.
DELETE → 204; GET shows defaults again; second DELETE → 204.

Which issue(s) does this PR fix?

addresse ethereum/keymanager-APIs#88

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).

james-prysm · 2026-08-07T16:14:09Z

  ];
-  repeated string relays = 3;
+  reserved 3;
+  reserved "relays";


for the reviewer, let me know what you think if we really need this value, i think removing it outright is a breaking change possibly but it's never been used before so not sure if i can just remove it

I think it's OK to keep it

james-prysm · 2026-08-07T21:31:40Z

pr changes how bid pathing works and affects #17124

james-prysm · 2026-08-07T21:49:37Z

 		return nil, errors.Wrapf(err, "could not unmarshal %s", cleanedConfigFilePath)
 	}

-	// yaml.Unmarshal converts nil array to empty array.


we never used the relay field to begin with so just get rid of it

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

james-prysm · 2026-08-11T15:32:21Z

for the reviewer, lets leave the enable-builder flag fixes/changes to a separate pr, the ux is akward here but i don't want to clutter this pr with more

james-prysm · 2026-08-11T15:44:17Z

+		promote(opt)
+	}
+	if dropped {
+		log.Warn("v1 builder settings do not apply to the v2 schema and were replaced with defaults; provide v2 proposer settings to configure builders")


i'm choosing to force promote those who didn't update their configs themselves, what do you guys think?

james-prysm · 2026-08-11T15:55:41Z

+
+	// v2 has no enabled toggle: participation follows the configured builders
+	// list, so --enable-builder has nothing to force on.
+	if builderConfig != nil {


we can change this in a subsequent pr ( or if there's something temporary we can do it here too)

james-prysm · 2026-08-11T16:22:00Z

+	return targets
+}
+
+func uint64Ptr(v *validatortypes.Uint64) *uint64 {


maybe i should move this? not sure if this type should live here

…f explicit

james-prysm · 2026-08-11T16:28:12Z

+	return be, nil
+}
+
+func parseUint(s, field string) (validator.Uint64, error) {


maybe i should move this somewhere else as a helper?

I think it's harmless to use strconv.ParseUint(s, 10, 64) every time, and decide the caller to create a new error with field.

… sure we only use gas limits on explicitly set upgraded settings

james-prysm · 2026-08-11T22:04:13Z

i explicitly gated the new endpoints in this pr until gloas is set, we can decide in a follow up if we want that vs allowing it on release that focuses mroe on the fork transition aspects ( will update pr description)

syjn99 · 2026-08-12T08:07:22Z

+type BuilderEntry struct {
+	Url                 string   `json:"url"`
+	AuthData            *string  `json:"auth_data,omitempty"`
+	BuilderPubkeys      []string `json:"builder_pubkeys"`


The builder BLS public keys this entry accepts bids from. Empty or omitted accepts any builder; otherwise a bid not signed by one of them MUST NOT be accepted.

Do we have to make this field required?

I think post requests accept it omitted and only get is required

syjn99 · 2026-08-12T08:26:15Z

  ];
-  repeated string relays = 3;
+  reserved 3;
+  reserved "relays";


I think it's OK to keep it

syjn99

One other comment is that we should rewrite our documentation that mentions about the version system of proposer settings. Also would be great if we can restructurize the docs - this guide is under fee recipient section.

syjn99 · 2026-08-12T10:50:23Z

 	walletDir                 string
 	jwtSecret                 []byte
 	grpcHeaders               []string
+	proposerSettingsLock      sync.Mutex


If we really need the serialization for read and write, why don't we use atomic.Pointer[proposer.Settings] in validator struct instead of the Server managing the lock? Or we might add a lock in validator struct.

I don't think atomic.Pointer is enough in this case i think we need s lock anyways. probably something to deal with in a followup pr though

syjn99 · 2026-08-12T10:58:38Z

@@ -129,16 +129,53 @@ message ProposerOptionPayload {

 // BuilderConfig is a property of ProposerOptionPayload
 message BuilderConfig {


Maybe marking each fields as deprecated like: [ deprecated = true ]?

post gloas we can probably just delete those fields, not sure if marking deprecated as true works if still used in v1

syjn99 · 2026-08-12T11:05:18Z

-	}
+// UpsertProposeOption returns pubkey's option, creating it if absent. A new
+// option keeps BuilderConfig nil so it inherits default_config.
+func (ps *Settings) UpsertProposeOption(pubkey [fieldparams.BLSPubkeyLength]byte) *Option {


Nit, to make this method "upsert" on the ps, I'd pass a callback function as an argument and let it mutate the Option: mutate func(*Option) *Option so it'll look like:

settings.UpsertProposeOption(bytesutil.ToBytes48(pubkey), func(opt *proposer.Option) { opt.FeeRecipientConfig = &proposer.FeeRecipientConfig{FeeRecipient: feeRecipient} })

hmm looking at it, it doesn't seem to remove any duplication, is there another reason to do this? ( i haven't set this up yet)

syjn99 · 2026-08-12T11:19:27Z

+    (ethereum.eth.ext.cast_type) =
+        "github.com/OffchainLabs/prysm/v7/consensus-types/validator.Uint64"
+  ];
+  optional uint64 max_execution_payment = 5 [


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

Line 100 in ae5ccd6

maxExecutionPayments sync.Map // validator pubkey [48]byte -> max execution payment (Gwei uint64).

Seems like we still has a map from pubkey -> max_execution_payment value. So does this mean per-entry max_execution_payment is not enforced?

james-prysm · 2026-08-12T19:33:42Z

One other comment is that we should rewrite our documentation that mentions about the version system of proposer settings. Also would be great if we can restructurize the docs - this guide is under fee recipient section.

yes that's a needed step i think it should be part of a followup pr as even this pr has some tradeoffs we still need to address in a followup

terencechain · 2026-08-12T21:48:40Z

+// UpgradeToV2 is the v1 cutover: v1 builder configs, including their gas limits,
+// do not apply to gloas and are dropped. Returns true if anything changed.
 func (ps *Settings) UpgradeToV2() bool {
 	if ps == nil || ps.isV2() {


this means v1 builder content that ends up under a v2 stamp is never cleaned up

scrubbed in 57a9174#diff-22d828bd0d0814ea79cf0313093e66de9c290b6e89166ae373e49d5da8aff21a what do you think

terencechain · 2026-08-12T21:49:08Z

-		if opt.GasLimit == 0 {
-			opt.GasLimit = opt.BuilderConfig.GasLimit
-		}
+		opt.BuilderConfig = nil


this also drops an explicit --suggested-gas-limit

I think we should handle this in a sebsequent pr, i'm afraid of using this to override the schedule numbers and should think more about it, let me see what I can do to make sure it's cut off for now

officially dropped in 57a9174#diff-22d828bd0d0814ea79cf0313093e66de9c290b6e89166ae373e49d5da8aff21a what do you think?

terencechain · 2026-08-12T21:49:58Z

 	}
+	// Pointer changed = a keymanager write landed after our snapshot; swapping
+	// our stale clone would erase it. This cleanup simply reruns next cycle.
+	if v.ProposerSettings() != snapshot {


I think there's a race, the keymanager handlers serialize on the server's proposerSettingsLock but this path takes no lock

crap i think you're right let me see how i can fix this

57a9174#diff-22d828bd0d0814ea79cf0313093e66de9c290b6e89166ae373e49d5da8aff21a passed in a mutation function i think it fixes it but will double check again

initial commit implementing ethereum/keymanager-APIs#88

4c09570

james-prysm changed the title ~~initial commit implementing https://github.com/ethereum/keymanager-AP…~~ Add GET/POST/DELETE /eth/v1/validator/{pubkey}/builders keymanager endpoints Jul 29, 2026

james-prysm and others added 7 commits July 30, 2026 15:23

gaz

27698ca

Merge branch 'develop' into km88-proposer-settings

f48d53b

Merge branch 'develop' into km88-proposer-settings

602d824

updating based on removal of p2p boost config

f4c3354

self review

df8afee

Merge branch 'develop' into km88-proposer-settings

cc92577

make changelog more concise

ea814aa

james-prysm added the gloas label Aug 7, 2026

github-project-automation Bot added this to Gloas Aug 7, 2026

github-project-automation Bot moved this to Unassigned in Gloas Aug 7, 2026

james-prysm added the api label Aug 7, 2026

james-prysm added 5 commits August 7, 2026 09:39

rolling back some flag overrides

4f25f60

reverting change

40486bd

clarifying changelog

aa6247b

self review on comments

586904e

moving functions around after self review

ba99fc3

james-prysm commented Aug 7, 2026

View reviewed changes

james-prysm added 2 commits August 7, 2026 16:00

more bug fixes and missing items after self review

d9b6989

Merge branch 'develop' into km88-proposer-settings

0d863aa

james-prysm requested review from syjn99 and terencechain August 7, 2026 21:24

james-prysm marked this pull request as ready for review August 7, 2026 21:24

james-prysm commented Aug 7, 2026

View reviewed changes

syjn99 reviewed Aug 9, 2026

View reviewed changes

Comment thread validator/rpc/handlers_validator_config.go Outdated

Comment thread validator/rpc/handlers_validator_config.go Outdated

Comment thread validator/rpc/structs.go Outdated

syjn99 self-requested a review August 10, 2026 12:22

james-prysm and others added 2 commits August 10, 2026 07:01

Update validator/rpc/structs.go

3429854

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

Update validator/rpc/handlers_validator_config.go

29ea6a0

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

james-prysm added 3 commits August 10, 2026 09:27

remove proxy that is no longer used

2a365bc

remove enabled tag and use builders tag instead

e68f2fe

gaz

4ea3e1a

james-prysm commented Aug 11, 2026

View reviewed changes

self review points, don't migrate gas limit in v1 and take in in v2 i…

9698cf1

…f explicit

james-prysm commented Aug 11, 2026

View reviewed changes

fixing test order

bf4fd8c

james-prysm mentioned this pull request Aug 11, 2026

Add EIP-8261 gas limit schedule support #17339

Merged

james-prysm added 2 commits August 11, 2026 16:57

adding gloas gates for endpoints, fixing bugs after self review, make…

3cd047b

… sure we only use gas limits on explicitly set upgraded settings

gaz

da52e2e

syjn99 reviewed Aug 12, 2026

View reviewed changes

Comment thread config/proposer/loader/loader.go

syjn99 reviewed Aug 12, 2026

View reviewed changes

james-prysm added 2 commits August 12, 2026 10:26

Merge branch 'develop' into km88-proposer-settings

1526ec2

jun's comments

ae648dc

adding test

3234435

terencechain reviewed Aug 12, 2026

View reviewed changes

james-prysm added 2 commits August 12, 2026 22:12

terence's comments

57a9174

Merge branch 'develop' into km88-proposer-settings

934cc8d

		@@ -129,16 +129,53 @@ message ProposerOptionPayload {

		// BuilderConfig is a property of ProposerOptionPayload
		message BuilderConfig {

Uh oh!

Conversation

james-prysm commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

james-prysm commented Aug 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

james-prysm commented Aug 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

james-prysm commented Aug 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

syjn99 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

james-prysm commented Aug 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

james-prysm commented Jul 29, 2026 •

edited

Loading