Add per-validator builder configuration API by jimmygchen · Pull Request #9864 · sigp/lighthouse

jimmygchen · 2026-08-19T04:35:23Z

Description

Adds the per-validator builder configuration endpoints from ethereum/keymanager-APIs#88.

GET /eth/v1/validator/{pubkey}/builder_config returns the configuration in use for the validator.
POST /eth/v1/validator/{pubkey}/builder_config replaces and persists the full configuration on a per-validator basis. It does not merge with the previous entry.
DELETE /eth/v1/validator/{pubkey}/builder_config removes the stored entry, so the validator inherits the global configuration again.

The API stores per-validator entries under validator_configs in builder_definitions.yml.

Changes made by POST and DELETE apply to subsequent builder preference publication and Gloas block production without a restart.

Closes #9796

Additional Info

This PR is stacked on #9807 and should be reviewed after it.

mergify · 2026-08-19T19:57:28Z

This pull request has merge conflicts. Could you please resolve them @jimmygchen? 🙏

mergify · 2026-08-21T14:47:23Z

This pull request has merge conflicts. Could you please resolve them @jimmygchen? 🙏

mergify · 2026-08-26T20:02:50Z

This pull request has merge conflicts. Could you please resolve them @jimmygchen? 🙏

chong-he

I have go through the PR and tested the endpoint manually and they look great. Just some minor comments and a bug found by Codex

chong-he · 2026-08-27T00:51:35Z

+#[derive(Debug)]
+pub struct CustomForbidden(pub String);
+
+impl Reject for CustomForbidden {}
+
+pub fn custom_forbidden(msg: String) -> warp::reject::Rejection {
+    warp::reject::custom(CustomForbidden(msg))
+}
+


This is a new reject type for the http apis. It actually correct matches the specs 403 Forbidden, as from the spec:

A builder configuration was found, but cannot be removed. This may be because it was in configuration files that cannot be updated.

Given that this is new, so I look up existing Keymanager API, e.g., the fee recipient one:

lighthouse/validator_client/http_api/src/lib.rs

Lines 1013 to 1017 in 60f8759

.delete_validator_fee_recipient(&validator_pubkey)

.map_err(|e| {

warp_utils::reject::custom_server_error(format!(

"Error persisting fee recipient removal: {:?}",

e

and found that it is returning 500 for a deletion error, which isn't following the spec error code. I suspect this is the case for other existing Keymanager endpoints too. But then the error code has been incorrect for so long and it doesn't look like a big deal anyway.

Just pointing this out

Yes this is according to spec. I've left the existing endpoint response scope outside of PR.

chong-he · 2026-08-27T00:58:55Z

+}
+
+impl ValidatorBuilderConfig {
+    pub(crate) fn validate(&self) -> Result<(), Error> {


Nit: there are a few function with name validate, maybe we can rename name for better clarity? For example, this can be renamed to validate_validator_builder_config or something like that

i think this may look a bit too verbose, because you'd end up having something like
validator_builder_config.validate_validator_builder_config

chong-he · 2026-08-27T00:59:02Z

        self.builders.push(definition);
    }

    pub fn validate(&self) -> Result<(), Error> {


Same comment as above

same as above

chong-he · 2026-08-27T01:00:27Z

+    }
+
+    /// Return the fully resolved configuration for a validator without signing builder auth data.
+    pub fn validator_config(


Maybe rename to get_validator_config? Sounds a bit clearer to me, but this is also a bit so feel free to ignore

Changed this to get_validator_config, thanks

chong-he · 2026-08-27T01:06:14Z

+    fn global_max_execution_payment(&self, builder: &ValidatorBuilderDefinition) -> Option<u64> {
+        let auth_data = builder
+            .auth_data
+            .clone()
+            .unwrap_or_else(|| builder.url.to_default_auth_data());
+        self.builders
+            .iter()
+            .filter(|global| global.enabled)
+            .find(|global| {
+                global.url == builder.url
+                    && global
+                        .auth_data
+                        .clone()
+                        .unwrap_or_else(|| global.url.to_default_auth_data())
+                        == auth_data
+            })
+            .map(|global| global.max_execution_payment)
+    }


Is this intended that we want to find the max_execution_payment for the matching builder when it's not provided in the POST? I thought it could be simpler if we just default to 0 and no need to find the matching entries if the field is not provided

Yes, the lookup is intentional. An omitted max_execution_payment takes the validator client's configured value, so defaulting directly to 0 would be incorrect. We match the enabled global entry by URL and effective auth_data. 0 is only used when no entry matches.

chong-he · 2026-08-27T01:21:25Z

+                    builder.min_bid = Some(builder.min_bid.unwrap_or(min_bid));
+                    builder.builder_boost_factor =
+                        Some(builder.builder_boost_factor.unwrap_or(builder_boost_factor));
+                    builder


Found by Codex:

Say we have a global builder enabled with min_bid: 100. And then we POST builder_config for a validator with request body:

{"min_bid": "500"}

When we GET the validator config, we don't get 500 min_bid for this validator, it uses the top level value:

{ "data": { "min_bid": "1", # global top level "builder_boost_factor": "100", # global top level "builders": [ { "url": "https://builder.example", "auth_data": "0x68747470733a2f2f6275696c6465722e6578616d706c65", "builder_pubkeys": [], "max_execution_payment": "123", "min_bid": "100", # should be 500 here "builder_boost_factor": "100" } ] } }

(althought the YAML file is showing per-validator min-bid is 500)

But if we POST with a builder url in the request body, then it works:

Request body:

{"min_bid": "500", "builders": [{"url": "https://example"}]}

Response of GET:

{ "data": { "min_bid": "500", "builder_boost_factor": "100", "builders": [ { "url": "https://another-builder.example", "auth_data": "0x68747470733a2f2f616e6f746865722d6275696c6465722e6578616d706c65", "builder_pubkeys": [], "max_execution_payment": "0", "min_bid": "500", # 500 min_bid shown correctly "builder_boost_factor": "100" } ] } }

Great catch. Fixed in 7de5c200f. Validator level defaults now override inherited global builder values. The test uses conflicting values and checks that DELETE restores the global values.

jimmygchen added ready-for-review The code is ready for review HTTP-API builder API gloas val-client Relates to the validator client binary and removed builder API labels Aug 19, 2026

jimmygchen requested review from chong-he and ethDreamer August 19, 2026 05:50

eserilev mentioned this pull request Aug 19, 2026

glamsterdam-devnet-8 #9881

Draft

ethDreamer requested a review from jxs as a code owner August 19, 2026 19:31

mergify Bot added waiting-on-author The reviewer has suggested changes and awaits thier implementation. and removed ready-for-review The code is ready for review labels Aug 19, 2026

jimmygchen force-pushed the codex/feat-per-validator-builder-config branch from f0f272a to c3f6c06 Compare August 21, 2026 06:35

mergify Bot added ready-for-review The code is ready for review and removed waiting-on-author The reviewer has suggested changes and awaits thier implementation. labels Aug 21, 2026

mergify Bot added waiting-on-author The reviewer has suggested changes and awaits thier implementation. and removed ready-for-review The code is ready for review labels Aug 21, 2026

jimmygchen force-pushed the codex/feat-per-validator-builder-config branch from c3f6c06 to 3c16568 Compare August 21, 2026 15:07

chong-he added the under-review A reviewer has only partially completed a review. label Aug 24, 2026

jimmygchen force-pushed the codex/feat-per-validator-builder-config branch from 3c16568 to d4866c8 Compare August 26, 2026 00:41

mergify Bot added ready-for-review The code is ready for review and removed waiting-on-author The reviewer has suggested changes and awaits thier implementation. labels Aug 26, 2026

mergify Bot added waiting-on-author The reviewer has suggested changes and awaits thier implementation. and removed ready-for-review The code is ready for review labels Aug 26, 2026

chong-he reviewed Aug 27, 2026

View reviewed changes

jimmygchen added 9 commits August 27, 2026 01:42

Add per-validator builder configuration API

309a1e1

Refine per-validator builder configuration API

570836c

Simplify builder configuration request types

07d5581

Tighten builder configuration request handling

f5c7174

Clarify builder uint64 deserializer name

21ba0a4

Document strict keymanager uint64 parsing

19f9f78

Simplify builder configuration updates

a5d33a7

Simplify builder configuration publication

302d8d7

Clarify builder configuration updates

023488e

jimmygchen force-pushed the codex/feat-per-validator-builder-config branch from d4866c8 to 023488e Compare August 27, 2026 01:47

jimmygchen added 2 commits August 27, 2026 04:16

Fix inherited builder configuration precedence

7de5c20

Restore concise builder config validation name

64ea090

jimmygchen added ready-for-review The code is ready for review and removed waiting-on-author The reviewer has suggested changes and awaits thier implementation. labels Aug 27, 2026

	.delete_validator_fee_recipient(&validator_pubkey)
	.map_err(\|e\| {
	warp_utils::reject::custom_server_error(format!(
	"Error persisting fee recipient removal: {:?}",
	e

Uh oh!

Conversation

jimmygchen commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Additional Info

Uh oh!

mergify Bot commented Aug 19, 2026

Uh oh!

mergify Bot commented Aug 21, 2026

Uh oh!

mergify Bot commented Aug 26, 2026

Uh oh!

chong-he left a comment

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!

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

Projects

Milestone

Development

Uh oh!

2 participants

jimmygchen commented Aug 19, 2026 •

edited

Loading