feat(builder): add readiness gating and builder identity resolution by markolazic01 · Pull Request #9781 · ChainSafe/lodestar

markolazic01 · 2026-08-06T12:30:32Z

Motivation

Further development of ePBS builder entity.

Description

Extracts builder identity resolution to identity.ts and expands basic functionality into resolveBuilderIdentity and getBuilderStatus.
Introduces readiness.ts, containing waitForNodeReady function which polls until the BN is synced and its EL is online + logNodeVersion.
BuilderStatusTracker service for tracking builder status and balance.
--executionFeeRecipient cli option
Wiring for all features.

Lacks:

Metrics
Tests

markolazic01 · 2026-08-09T12:20:47Z

Marking this ready. Leaving metrics and readiness tests as a follow-up.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 250ae7bff1

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

nflaig

did a quick pass, generally looks pretty good

nflaig · 2026-08-09T14:10:26Z

+
+  if (builderEntry.status !== "active") {
+    throw Error(`Builder not active: ${builderEntry.status}`);
+  }


what if builder is deposited later, should this wait instead of throwing?

we can add the wait, probably on the fetchBuilder()'s length check:
https://github.com/markolazic01/lodestar/blob/51c3493b2b7cfd788d665b99611de9856d6307b1/packages/builder/src/identity.ts#L61
because that would indicate that the builder is not yet known, while status other than "active" indicates that builder exited.
How does this sound?

yep that sounds good, the reason I brought this up is because it's quite common for operators today to import bls keys in the validator client even if those are completely unknown to the chain, but it's good so you can prepare your setup, then later, once those keys are deposited and become known to the chain, the validator clients picks them up automatically with no interaction from the operator. Similar ux would be great to have for the builder

nflaig · 2026-08-09T14:12:18Z

+
+  if (!builderRes.ok) {
+    throw Error(`Failed to get builder state from beacon node: ${builderRes.status}`);
+  }


might be useful to also print out the error response from the beacon node

applied, noting this requires await res.errorBody() first, as error() reads the error body synchronously.

noting this requires await res.errorBody()

I don't like this pattern, see #9781 (comment)

nflaig · 2026-08-10T09:22:04Z

+  if (!builderRes.ok) {
+    await builderRes.errorBody();


I don't really like this manual checking for ok and then handling the error like this, the api client is designed in a way that most of the time it's better to use .value() or .assertOk()

this is fixed now, there is another check in here:
https://github.com/markolazic01/lodestar/blob/7386db08081ce635662d6898c925036cd2015b71/packages/builder/src/readiness.ts#L17-L24
I left this one in because I haven't found a cleaner way to log the error message otherwise.

that's fine but keep in mind that network errors will still throw (eg. host not reachable or any tcp error)

regarding http errors (which ok is related to) there shouldn't be any scenario where getSyncingStatus returns 500 or similar

so need to make sure to handle network error gracefully which usually requires a try/catch or .catch

nflaig · 2026-08-10T09:25:51Z

+
+export async function logNodeVersion(api: ApiClient, logger: Logger): Promise<void> {
+  try {
+    const versionRes = await api.node.getNodeVersionV2();


some clients may not have this api yet, but that's fine for now, we might need to bully them a bit to implement it, but since it's gloas related, it's fine to assume it's implemented by clients

nflaig · 2026-08-10T09:40:48Z

the title is a bit too long, would be good to make it more succinct, details are in the commit body afterwards based on the PR description

Co-authored-by: Nico Flaig <nflaig@protonmail.com>

markolazic01 · 2026-08-10T14:07:43Z

Thanks for reviewing, applied the suggestions and updated the description.

nflaig · 2026-08-10T19:43:20Z

+  return apiResponse;
+}
+
+export async function mockApiErrorResponse<E extends Endpoint>(status: HttpStatusCode): Promise<ApiResponse<E>> {


maybe could dedupe these in packages/test-utils if it's 1:1 what the validator uses, would be rather a follow-up PR though

The only difference between implementation here and in the builder would be the functions listed here:

lodestar/packages/validator/test/utils/apiStub.ts

Line 15 in 1dde9ab

export function getApiClientStub(): ApiClientStub {

but I think it's alright to have all the functions that consumers need in one place.
I also removed some unused parts of it here, but these two can be put in sync based on what is used.

Should we tell lodekeeper to make an issue for it? So we don't forget about this.

@lodekeeper can you create an issue on this?
It's about adapting apiStub helper and moving it into a common place (packages/test-utils) after this PR is merged.

Done — opened #9819 to track this.

Captured the reconciliation points from the current files: mockApiResponse is already identical, the getApiClientStub function lists differ (builder is a minimal subset + getStateBuilders), and — one extra beyond the function list — the builder's mockApiErrorResponse is now async + await res.errorBody() vs the validator's sync version, so the dedup will need to reconcile that too.

nflaig · 2026-08-10T19:46:28Z

+
+    if (syncingStatus.isOptimistic) {
+      logger.warn("Beacon node head is optimistic, execution payloads are not yet verified");
+    }


so for the operator it should be clear that in case the EL is syncing we won't be able to submit any bids

nflaig · 2026-08-10T19:48:57Z

+    throw Error(`Builder not known to the beacon node: ${id}`);
+  }
+
+  return builders[0];


we should probably sanity check the response from the beacon node to make sure it resolved "our" builder

nflaig · 2026-08-10T19:50:40Z

-    if (builderStatus.status !== "active") {
-      throw Error(`Builder not active: ${builderStatus.status}`);
-    }
+    const index = await resolveBuilderIdentity(api, logger, builderSigner.getPubkeyHex());


so this still assumes the builder is active before starting up the builder client? see #9781 (comment)

I do think this is fine for now, we don't need to address it in this PR, it's more a nice to have to improve ux for operators

markolazic01 added 11 commits August 4, 2026 13:39

refactor: extract builder identity resolution to identity.ts

f9c1ca7

feat: add builder status query and share builder fetch helper

6dd7f0c

feat: check beacon node readiness on startup

dd2bc25

chore: log builder index

4cbb72b

feat: wait for beacon node readiness instead of failing at startup

0d22e6d

feat: add executionFeeRecipient cli option

35aec8d

feat: gloas fork schedule check

42c7085

chore: log gvr

8424ecf

refactor: throw typed errors from fetchBuilder

14dbd09

feat: add builder status tracker

f5f50d0

feat: poll builder status and balance every epoch

96dafe8

github-project-automation Bot added this to Lodestar Team Coordination Aug 6, 2026

Merge branch 'unstable' into feat/builder-api-01

6764758

nflaig reviewed Aug 6, 2026

View reviewed changes

Comment thread packages/builder/src/services/builderStatusTracker.ts

markolazic01 added 4 commits August 6, 2026 15:56

chore: BuilderStatusTracker description

e90ebb2

chore: zero address as a constant

354c6f4

Merge branch 'unstable' into feat/builder-api-01

87bade7

feat: requestTimeout cli flag

d68905f

markolazic01 changed the title ~~feat(builder): beacon node readiness, builder identity resolution and execution fee recipient~~ feat(builder): beacon node readiness, builder identity resolution and cli flags for execution fee recipient and request timeout Aug 7, 2026

markolazic01 added 6 commits August 7, 2026 17:37

Merge branch 'unstable' into feat/builder-api-01

5492130

test(builder): add BuilderStatusTracker unit tests

d98ca85

test(builder): extract getStateBuilders response fixture

0a13a30

wip: identity tests

4fa1405

test(builder): identity tests pt2

926adbc

Merge branch 'unstable' into feat/builder-api-01

250ae7b

markolazic01 marked this pull request as ready for review August 9, 2026 12:19

markolazic01 requested a review from a team as a code owner August 9, 2026 12:19

chatgpt-codex-connector Bot reviewed Aug 9, 2026

View reviewed changes

Comment thread packages/builder/test/unit/utils/apiStub.ts

nflaig reviewed Aug 9, 2026

View reviewed changes

markolazic01 added 4 commits August 10, 2026 00:00

chore: minor improvements

ded9e62

fix: status change log warn -> info

1b056f9

chore: log error messages

8c83008

refactor: genesis warn

51c3493

nflaig reviewed Aug 10, 2026

View reviewed changes

Comment thread packages/builder/src/readiness.ts

nflaig reviewed Aug 10, 2026

View reviewed changes

Comment thread packages/cli/src/cmds/builder/handler.ts Outdated

nflaig reviewed Aug 10, 2026

View reviewed changes

Comment thread packages/builder/src/builder.ts Outdated

Comment thread packages/builder/src/readiness.ts

markolazic01 and others added 2 commits August 10, 2026 16:01

Update packages/cli/src/cmds/builder/handler.ts

300e29c

Co-authored-by: Nico Flaig <nflaig@protonmail.com>

Update packages/builder/src/builder.ts

ce6e28d

Co-authored-by: Nico Flaig <nflaig@protonmail.com>

markolazic01 changed the title ~~feat(builder): beacon node readiness, builder identity resolution and cli flags for execution fee recipient and request timeout~~ feat(builder): add readiness gating and builder identity resolution Aug 10, 2026

markolazic01 added 5 commits August 10, 2026 17:42

refactor: remove builder response check

0e25f09

fix: mockApiErrorResponse

7386db0

Merge branch 'unstable' into feat/builder-api-01

81ed67f

fix: drop await errorBody()

460616e

fix: add missing import

251347b

nflaig reviewed Aug 10, 2026

View reviewed changes

markolazic01 marked this pull request as draft August 10, 2026 20:25

This was referenced Aug 10, 2026

feat(builder): observe beacon node blocks krisoshea-eth/lodestar#48

Draft

[API-02] Consume BN block events and retrieve fork-correct blocks krisoshea-eth/lodestar#12

Open

lodekeeper mentioned this pull request Aug 13, 2026

Dedupe builder/validator test apiStub helpers into packages/test-utils #9819

Open

markolazic01 added 2 commits August 13, 2026 18:42

feat(builder): wait for builder to become known to the beacon node

c04b3c3

feat(builder): wait for pending builder to become active

9916c34

Uh oh!

Uh oh!

Conversation

markolazic01 commented Aug 6, 2026

Uh oh!

Uh oh!

markolazic01 commented Aug 9, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

nflaig left a comment

Choose a reason for hiding this comment

Uh oh!

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!

Uh oh!

Uh oh!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nflaig commented Aug 10, 2026

Uh oh!

markolazic01 commented Aug 10, 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

Projects

Milestone

Development

Uh oh!

3 participants