diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md index 5563537..f67f542 100644 --- a/docs/implementation-plan.md +++ b/docs/implementation-plan.md @@ -7,7 +7,7 @@ **Working model:** one shared feature branch; merge `unstable` regularly; split only when review benefits from it **Formal product name:** `lodestar builder` / `packages/builder` **Optional EPF mission codename:** Forgestar -**Status:** v1.0 merged on 5 August 2026. All plan-review comments are resolved and no plan-level architecture question remains open. This execution copy was reconciled on 11 August against Lodestar v1.46.0-rc.1, the merged equivocation work, Builder PR #9781, the TEST-01/MET-01/REVIEW-01 issue split, the latest Lodestar-team discussion, and the Linear/GitHub backlog. The full plan remains canonical on GitHub because it exceeds HackMD's per-note character limit. Moving implementation details continue to be refined through their owning issues without reopening the accepted architecture. +**Status:** v1.0 merged on 5 August 2026. All plan-review comments are resolved and no plan-level architecture question remains open. This execution copy was reconciled on 14 August against Lodestar v1.46.0, merged Builder PR #9781, its open #9819/#9827 follow-ups, the integrated API-02 fork draft, the TEST-01/MET-01/REVIEW-01 issue split, and the Linear/GitHub backlog. The full plan remains canonical on GitHub because it exceeds HackMD's per-note character limit. Moving implementation details continue to be refined through their owning issues without reopening the accepted architecture. > **Project documents:** [Merged proposal](https://github.com/eth-protocol-fellows/cohort-seven/blob/master/projects/lodestar-eip-7732-builder.md) · [Canonical Living Technical Note](https://github.com/krisoshea-eth/lodestar-eip-7732-builder-docs/blob/main/docs/living-technical-note.md) · [HackMD mirror](https://hackmd.io/@krisos/S1a9mdB7fl) · [Presentation slides](https://docs.google.com/presentation/d/1cmC3fpu652gZFTIm2_P1lIYOfC2M_w3c5qXSUZ4B6lc) · [Lodestar repository](https://github.com/ChainSafe/lodestar) · [Maintained Beacon API Builder flow](https://github.com/ethereum/beacon-APIs/blob/master/validator-flow.md#builder-optional) @@ -454,7 +454,7 @@ The exact preparation route, initial publication offset, and cache hook remain i ### Verified implementation baseline at final review -This snapshot was refreshed on 11 August 2026. It records work that can narrow the board issues without treating a draft, an open follow-up, or partially verified work as Done. +This snapshot was refreshed on 14 August 2026. It records work that can narrow the board issues without treating a draft, an open follow-up, or partially verified work as Done. | Source | Verified state | Effect on this plan | |---|---|---| @@ -468,13 +468,14 @@ This snapshot was refreshed on 11 August 2026. It records work that can narrow t | [Lodestar #9736](https://github.com/ChainSafe/lodestar/pull/9736) | Open draft: correct FULL-parent state use for block production and reward calculation | Audit and reuse it in `BN-02` when available; do not build a parallel FULL-parent path in the Builder project | | [Lodestar #9757](https://github.com/ChainSafe/lodestar/pull/9757) | Merged on 7 August: adds `consensus_and_equivocation` handling and Deathstar proposer-equivocation support, with buildoor used for the first end-to-end proof | Reuse the BN capability in `REV-01` and `QA-01`; retain the Lodestar Builder fixture so the project proves the same rejection once its honest loop works | | [Lodestar #9594](https://github.com/ChainSafe/lodestar/pull/9594), [builder-specs #165](https://github.com/ethereum/builder-specs/pull/165), and [beacon-APIs #630](https://github.com/ethereum/beacon-APIs/pull/630) | #9594 closed without merge on 5 August; the Builder API specifications and replacement Lodestar implementation are still moving | Not a core dependency. Re-audit the settled route and auth shapes before `BN-01` or `EXT-BUILDER-API-01`; do not depend on the abandoned draft and keep staked Builder API request authentication conditional | -| [Lodestar #9758](https://github.com/ChainSafe/lodestar/pull/9758) | Merged at `74a3175`: initial `@lodestar/builder` package and CLI scaffolding, local keystore, bid/envelope signing and tests, source-BN wiring, `waitForGenesis`, shutdown, shared `assertEqualParams`, and active-Builder resolution. The first package was also published to npm | `SIGN-01` is Done with merged review and CI evidence. Remaining CLI/source-BN implementation is now reviewed through #9781, with tests and metrics split into `TEST-01` and `MET-01` | -| [Lodestar #9766](https://github.com/ChainSafe/lodestar/pull/9766) | Merged: aligns the Builder package build and type-check scripts with the workspace TypeScript 7 migration by using `tsc` | Record the CI follow-up under completed `CLI-01`; any remaining #9781 implementation review belongs to `REVIEW-01` | +| [Lodestar #9758](https://github.com/ChainSafe/lodestar/pull/9758) | Merged at `74a3175`: initial `@lodestar/builder` package and CLI scaffolding, local keystore, bid/envelope signing and tests, source-BN wiring, `waitForGenesis`, shutdown, shared `assertEqualParams`, and active-Builder resolution. The first package was also published to npm | `SIGN-01` is Done with merged review and CI evidence. Later CLI/source-BN implementation merged through #9781, with remaining tests and metrics split into `TEST-01` and `MET-01` | +| [Lodestar #9766](https://github.com/ChainSafe/lodestar/pull/9766) | Merged: aligns the Builder package build and type-check scripts with the workspace TypeScript 7 migration by using `tsc` | Record the CI follow-up under completed `CLI-01`; #9781 post-merge reconciliation belongs to `REVIEW-01` | | [Lodestar #9770](https://github.com/ChainSafe/lodestar/pull/9770) | Merged: hides the generated Builder CLI page from the public docs sidebar while the command is not yet functional | Keep the page hidden or clearly marked work in progress until the command is functionally ready and the open `REVIEW-01` work is closed, then restore it as part of `HANDOFF-01`; the administrative closure of `CLI-01` alone is not the publication signal | -| [Lodestar #9781](https://github.com/ChainSafe/lodestar/pull/9781) | Open draft and review-required at head `251347b7b5c5723a84ca6851e603604cdc75cd80` with 33 commits and eight unresolved Nico review threads on 11 August. It contains Builder identity and status tracking, BN/EL readiness, execution fee-recipient and timeout CLI wiring, plus identity/tracker tests. The branch uses the API client's standard `.value()` response path and asynchronous API-error response mocks. The reviewed later-Builder direction is to keep an unknown configured key inert and retry until it is deposited or activated, while preserving a returned non-active lifecycle status as a distinct operator-visible result | Preserve Marko's completed `CLI-01` and `API-01` statuses. Track the remaining review, later-Builder lifecycle implementation, responsibility documentation, and merge in `REVIEW-01`; keep the regression matrix and metrics in `TEST-01` and `MET-01` | -| [Lodestar v1.46.0-rc.1](https://github.com/ChainSafe/lodestar/releases/tag/v1.46.0-rc.1), [#9790](https://github.com/ChainSafe/lodestar/pull/9790), [#9792](https://github.com/ChainSafe/lodestar/pull/9792), and [#9793](https://github.com/ChainSafe/lodestar/pull/9793) | rc.1 at `e2b315e` supersedes rc.0 as the newest immutable audit target. #9790 protects state persistence/database close during a stuck network-worker shutdown and #9792 fixes a QUIC resource leak. #9793 closed without merge because its self-signal/force-exit approach did not generalize, especially for default container PID 1. The underlying stuck handle remains unidentified | Advance `BASELINE-01` to rc.1 and test state persistence, process-manager timeout, and Builder restart/cache/reveal recovery. Retain #9793 as diagnostic history, not an active implementation requirement or root-cause fix | +| [Lodestar #9781](https://github.com/ChainSafe/lodestar/pull/9781) | Merged as `2a04194b900ef972c6f469d06017d5c972be5714` after Nico approved head `3fe4ef4980645144668f8f634884c72a69f83677` and required checks passed. It contains Builder identity and status tracking, BN/EL readiness, execution fee-recipient and timeout CLI wiring, unknown/pending Builder polling with cancellation, identity checks, and tests. Twelve review-thread markers remain in the GitHub UI; #9819 owns test-helper deduplication and open #9827 carries abort-loop and logging nits | Preserve Marko's completed `CLI-01` and `API-01` statuses. Track only post-merge thread-marker and follow-up reconciliation in `REVIEW-01`; keep the broader regression matrix and metrics in `TEST-01` and `MET-01` | +| [Lodestar v1.46.0](https://github.com/ChainSafe/lodestar/releases/tag/v1.46.0) | Latest stable at `3873dd5b032d0ad82581fc3416e9628b4f6f2642`, published 12 August. It predates merged #9781 | Use as the newest immutable release target while `BASELINE-01` records the exact working `unstable` pin | +| [Lodestar v1.46.0-rc.1](https://github.com/ChainSafe/lodestar/releases/tag/v1.46.0-rc.1), [#9790](https://github.com/ChainSafe/lodestar/pull/9790), [#9792](https://github.com/ChainSafe/lodestar/pull/9792), and [#9793](https://github.com/ChainSafe/lodestar/pull/9793) | Historical release-candidate baseline now superseded by v1.46.0. #9790 protects state persistence/database close during a stuck network-worker shutdown and #9792 fixes a QUIC resource leak. #9793 closed without merge because its self-signal/force-exit approach did not generalize, especially for default container PID 1. The underlying stuck handle remains unidentified | Advance `BASELINE-01` to v1.46.0 plus an exact working `unstable` pin and test state persistence, process-manager timeout, and Builder restart/cache/reveal recovery. Retain #9793 as diagnostic history, not an active implementation requirement or root-cause fix | -The board preserves Marko's `CLI-01`, `API-01`, and `SIGN-01` **Done** statuses. `REVIEW-01` and `TEST-01` are **In progress** for the open #9781 review and separated regression work; `API-02` is **In review**, while `MET-01` remains **Todo**. `ENV-01` remains a dependency for API-02's end-to-end evidence. Landed upstream prerequisites may narrow a consuming issue, but do not automatically complete it. +The board preserves Marko's `CLI-01`, `API-01`, and `SIGN-01` **Done** statuses. `REVIEW-01` remains **In progress** for #9781 thread-marker and follow-up reconciliation, and `TEST-01` remains **In progress** for separated regression work. `API-02` is **In review**, while `MET-01` remains **Todo**. `ENV-01` remains a dependency for API-02's end-to-end evidence. Landed upstream prerequisites may narrow a consuming issue, but do not automatically complete it. ### Board hierarchy and pickup model @@ -627,7 +628,7 @@ flowchart TD API2["API-02
block observer"] TEST["TEST-01
Gate-A tests"] MET["MET-01
Builder metrics"] - REVIEW["REVIEW-01
#9781 review and merge"] + REVIEW["REVIEW-01
#9781 follow-up closure"] ENV --> API1 ENV --> API2 CLI --> SIGN @@ -803,14 +804,14 @@ flowchart TD **Why:** The Builder is a first-class protocol role in the Lodestar product line and should have the same clear package/CLI status as `validator`, `beacon`, and `bootnode`. -**Board status:** Done by Marko's project-status decision. The open #9781 review and merge work is not discarded; it is transferred to `REVIEW-01`, while tests and metrics remain in `TEST-01` and `MET-01`. +**Board status:** Done by Marko's project-status decision. The later #9781 implementation is merged; its post-merge thread-marker and follow-up reconciliation remains in `REVIEW-01`, while tests and metrics remain in `TEST-01` and `MET-01`. **Tasks** - [x] Reuse and extend the merged `packages/builder` and `lodestar builder` scaffolding from [Lodestar #9758](https://github.com/ChainSafe/lodestar/pull/9758) rather than recreating it. - [x] Complete command registration through existing CLI conventions. - [x] Add configuration for the source BN, network/chain, local keystore, Builder execution fee recipient, timeouts, and logging. The bounded bid-publication offset remains in `BID-01`; metrics configuration and server wiring remain in `MET-01`. -- [x] Implement the startup, readiness, health, signal-handling, and shutdown scope Marko closed. The later-Builder startup lifecycle and final #9781 review/merge remain in `REVIEW-01`. +- [x] Implement the startup, readiness, health, signal-handling, and shutdown scope Marko closed. The later-Builder startup lifecycle merged in #9781; post-merge reconciliation remains in `REVIEW-01`. - [x] Prevent signing/publication until the implemented key, BN, chain, and Builder-state checks pass; retain the BN-authoritative preparation guard in the later bid path. - [x] Use structured logs without secret material. Bounded metric labels remain in `MET-01`. - [x] Keep the generated Builder CLI page hidden from the public sidebar, as established by [Lodestar #9770](https://github.com/ChainSafe/lodestar/pull/9770), until the command is functionally ready and `REVIEW-01` closes. @@ -837,7 +838,7 @@ flowchart TD **Why:** The sidecar relies on one operator-controlled BN for chain truth, payload creation, balance validation, and reveal material. -**Board status:** Done by Marko's project-status decision. The later-Builder lifecycle implementation, remaining #9781 review feedback, responsibility documentation, and merge evidence are transferred to `REVIEW-01`. +**Board status:** Done by Marko's project-status decision. The later-Builder lifecycle implementation and responsibility documentation landed with #9781 and the Builder docs; post-merge thread-marker and follow-up reconciliation remains in `REVIEW-01`. **Tasks** @@ -845,16 +846,16 @@ flowchart TD - [x] Keep the small Builder `waitForGenesis` copy aligned with validator behavior from [Lodestar #9726](https://github.com/ChainSafe/lodestar/pull/9726): 404 is expected waiting, other failures are warnings, and the abort signal stops polling. - [x] Do not add a Lodestar BN `getGenesis` 404 branch while the API cannot start before anchor-state initialization; retain client handling for Teku and other spec-compliant BNs. - [x] Import `assertEqualParams` from `@lodestar/config` after [Lodestar #9725](https://github.com/ChainSafe/lodestar/pull/9725) and verify the source BN's spec-critical chain parameters before becoming Ready. -- [x] Verify expected genesis/fork/network identity and required BN capabilities within the implementation scope Marko closed; retain final review points in `REVIEW-01`. +- [x] Verify expected genesis/fork/network identity and required BN capabilities within the implementation scope Marko closed; retain post-merge follow-up points in `REVIEW-01`. - [x] Query Builder state by configured pubkey/index and require the expected active Builder version. - [x] Record the resolved Builder index, lifecycle status, and BN-reported balance returned by the same status lookup. - [x] Expose current Builder status/balance through structured diagnostics without treating that snapshot as an independent per-bid solvency decision. The bounded metric remains in `MET-01`. - [x] Observe and report the source BN's sync, optimistic-execution, and EL-availability state at sidecar startup/readiness, and keep the sidecar inert while the source is not ready. - [x] Keep the authoritative `not while syncing` and optimistic-execution guard in the BN preparation/candidate path. Return a typed syncing or unavailable result instead of recreating chain-readiness policy in the sidecar. - [x] Reuse the smallest suitable existing BN helper without importing validator only for `runOnResynced`. -- [x] Implement the typed timeout, cancellation, response-bound, and redacted-error scope Marko closed. The remaining BN-error-detail review points stay in `REVIEW-01`, with regression coverage in `TEST-01`. -- [x] Transfer the reviewed later-deposited or later-activated Builder lifecycle implementation to `REVIEW-01`, with the agreed regression in `TEST-01`. -- [x] Transfer the BN-authoritative-input and sidecar-sanity-check documentation to `REVIEW-01`. +- [x] Implement the typed timeout, cancellation, response-bound, and redacted-error scope Marko closed. Broader regression coverage remains in `TEST-01`. +- [x] Land the reviewed later-deposited or later-activated Builder lifecycle implementation in #9781, with broader cancellation regression work retained in `TEST-01`. +- [x] Record the BN-authoritative-input and sidecar-sanity-check boundary in the implementation plan and Living Technical Note. **Done when:** The sidecar connects only to the expected BN/chain, resolves the intended active Builder, exposes its current BN-reported status/balance, and reports precise readiness failures. @@ -873,6 +874,8 @@ flowchart TD **Done when:** One BN event leads to one bounded evaluation of the corresponding signed block, with no direct p2p subscription. +**Current evidence:** Fork draft [krisoshea-eth/lodestar#48](https://github.com/krisoshea-eth/lodestar/pull/48) has integrated merged #9781 at `1aae68a26fba53c2da1f361f2491042eae220f70`. It has 25 focused observer tests and 45 passing Builder package tests on Node 24.13.0. The upstream Lodestar PR and `ENV-01` real-BN smoke remain before issue closure. + **Operational handoff:** Node 24.13.0 uses Lodestar's npm `eventsource` fallback. The current Builder CLI configures one source BN, while the shared API client can otherwise serve REST calls from fallback URLs and pins SSE to its first URL. The Beacon API event contract defines no SSE `id` or `Last-Event-ID` resumption, so conforming clients cannot be assumed to replay a missed selection notification. `ENV-01` owns the real-process shutdown smoke; `REL-01` owns bounded same-source reconciliation; deferred multi-BN and long-gap behavior remain in their existing tracking issues. #### `TEST-01` — Add the remaining Gate-A tests @@ -907,19 +910,20 @@ flowchart TD #### `REVIEW-01` — Close the #9781 foundation review and lifecycle implementation -**Why:** Preserving Marko's completed CLI-01/API-01 status must not hide the implementation work that is still visible in the live #9781 review. +**Why:** Preserving Marko's completed CLI-01/API-01 status must not hide the post-merge review bookkeeping and accepted follow-ups that remain visible on #9781. **Tasks** -- [ ] Resolve all remaining Nico review threads on [Lodestar #9781](https://github.com/ChainSafe/lodestar/pull/9781). -- [ ] Implement the reviewed behavior for an unknown configured Builder key: remain inert and retry with cancellation until the key is deposited or activated, while keeping a returned non-active lifecycle status distinct and operator-visible. -- [ ] Refactor Builder-status response handling to use the API client's standard `.value()` or `.assertOk()` path and retain bounded, useful error details. -- [ ] Retain the current Gloas health-endpoint assumption while Gloas-capable clients are expected to implement it; revisit only if interoperability evidence exposes a gap. -- [ ] Document BN-authoritative inputs and the sidecar's sanity checks. -- [ ] Link every resulting behavior regression to `TEST-01` and keep metrics-only work in `MET-01`. -- [ ] Merge #9781 with required checks passing and record the final commit, review, and release status. +- [ ] Reconcile all twelve remaining review-thread markers on [Lodestar #9781](https://github.com/ChainSafe/lodestar/pull/9781): five outdated threads, two accepted or already-applied threads, one test-helper follow-up tracked by [#9819](https://github.com/ChainSafe/lodestar/issues/9819), and four logging or abort-loop nits carried by [#9827](https://github.com/ChainSafe/lodestar/pull/9827). +- [x] Implement the reviewed behavior for an unknown configured Builder key: remain inert and retry with cancellation until the key is deposited or activated, while keeping pending, exited, and unknown states distinct and operator-visible. +- [x] Refactor Builder-status response handling to use the API client's standard `.value()` path and retain useful API error details. +- [x] Retain the current Gloas health-endpoint assumption while Gloas-capable clients are expected to implement it; revisit only if interoperability evidence exposes a gap. +- [x] Document BN-authoritative inputs and the sidecar's sanity checks in the implementation plan and Living Technical Note. +- [x] Link broader behavior regressions to `TEST-01`, metrics-only work to `MET-01`, and shared test-helper cleanup to #9819. +- [x] Merge #9781 with required checks passing and record final evidence: merge `2a04194b900ef972c6f469d06017d5c972be5714`, Nico approval on `3fe4ef4980645144668f8f634884c72a69f83677`, and unreleased status because v1.46.0 predates the merge. +- [ ] Review and land, supersede, or explicitly reassign [#9827](https://github.com/ChainSafe/lodestar/pull/9827), then close the corresponding #9781 markers without silently resolving maintainer feedback. -**Done when:** #9781 has merged, its review threads and lifecycle implementation are resolved, the responsibility boundary is documented, and all resulting tests or metrics are linked to their owning follow-up. +**Done when:** #9781's merged implementation and approval are recorded, all remaining review markers are explicitly reconciled, #9827 is resolved or reassigned, the responsibility boundary is documented, and all resulting tests, metrics, or shared-helper work are linked to their owning follow-up. ### Epic B — BN payload, bid, and stateful reveal support @@ -1574,7 +1578,7 @@ The Lodestar review pass and confirmed follow-up decisions from 27 July–4 Augu | Envelope publication validation mode | accepted | Explicitly request `consensus_and_equivocation`; keep the validation BN-owned and test proposer unbundling with Deathstar | | [consensus-specs #5497](https://github.com/ethereum/consensus-specs/pull/5497) and [Lodestar #9739](https://github.com/ChainSafe/lodestar/pull/9739) | accepted and landed | Reuse head-compatible bid validation and per-parent seen-bid behavior; do not implement the superseded single-bid model | | [Lodestar #9723](https://github.com/ChainSafe/lodestar/pull/9723) | clarification | Do not treat it as a Builder-project dependency or use it to block the plan | -| Initial Lodestar Builder package and signer | accepted and landed | Reuse merged [Lodestar #9758](https://github.com/ChainSafe/lodestar/pull/9758); preserve Marko's `SIGN-01`, `CLI-01`, and `API-01` Done statuses. `REVIEW-01` owns the open [#9781](https://github.com/ChainSafe/lodestar/pull/9781) review/lifecycle implementation/documentation/merge work, while `TEST-01` and `MET-01` own their separated scopes | +| Initial Lodestar Builder package and signer | accepted and landed | Reuse merged [Lodestar #9758](https://github.com/ChainSafe/lodestar/pull/9758) and [#9781](https://github.com/ChainSafe/lodestar/pull/9781); preserve Marko's `SIGN-01`, `CLI-01`, and `API-01` Done statuses. `REVIEW-01` owns only #9781 thread-marker and #9827 follow-up reconciliation, while `TEST-01` and `MET-01` own their separated scopes | | Builder startup and bid work while syncing | accepted | Let the sidecar observe and report startup readiness, but keep the authoritative syncing, optimistic-execution, and EL-readiness guard in the BN preparation/candidate path. Reuse the smallest suitable helper; do not import validator only for `runOnResynced`, while leaving a broader package dependency open to a later evidence-based audit | | Exact bid and payload `uint64` values | accepted and landed | Preserve the exact types from [Lodestar #9749](https://github.com/ChainSafe/lodestar/pull/9749), [#9750](https://github.com/ChainSafe/lodestar/pull/9750), and [#9751](https://github.com/ChainSafe/lodestar/pull/9751) through Builder hashing/signing and test the unsafe JavaScript-number boundary | | Epoch-boundary head-compatible bid validation | accepted and landed | Reuse the narrow rule in [Lodestar #9756](https://github.com/ChainSafe/lodestar/pull/9756) and add a focused regression without adopting the retracted broader restriction | @@ -1607,6 +1611,6 @@ The Lodestar review pass and confirmed follow-up decisions from 27 July–4 Augu - [x] Add milestones, weeks, sizes, lanes, statuses, dependencies, and evidence fields. - [ ] Complete remaining owner and reviewer assignments as issues approach Ready. - [x] Preserve `CLI-01` as Done by project decision and keep `ENV-01` Todo in Cycle 2 until its environment work starts; Marko remains the recorded CLI owner. -- [x] Confirm implementation started in Week 8 with no hidden planning dependency; merged #9758 and open #9781 provide the implementation evidence. +- [x] Confirm implementation started in Week 8 with no hidden planning dependency; merged #9758 and #9781 provide the foundation evidence, and API-02 fork draft #48 supplies the current block-observer evidence. - [ ] Publish and preview the short HackMD landing page, then click-test its links to the canonical GitHub plan, review history, Living Technical Note, Linear project, and GitHub Project mirror. - [x] Confirm every diagram still matches the authoritative issue dependencies and accepted decisions after the final feedback pass, including the `REVIEW-01`/`TEST-01`/`MET-01` split. diff --git a/docs/living-technical-note.md b/docs/living-technical-note.md index 6e6015d..75eed4d 100644 --- a/docs/living-technical-note.md +++ b/docs/living-technical-note.md @@ -5,13 +5,13 @@ | Proposal | [Merged](https://github.com/eth-protocol-fellows/cohort-seven/blob/master/projects/lodestar-eip-7732-builder.md); strong-success list amended through [PR #186](https://github.com/eth-protocol-fellows/cohort-seven/pull/186) | | Implementation plan | [v1.0 merged](https://github.com/krisoshea-eth/lodestar-eip-7732-builder-docs/pull/2) on August 5, 2026; the merged GitHub plan is the implementation source of truth | | Spec target | [consensus-specs v1.7.0-alpha.13](https://github.com/ethereum/consensus-specs/releases/tag/v1.7.0-alpha.13), published July 31, 2026 | -| Lodestar baseline | Stable remains [v1.45.0](https://github.com/ChainSafe/lodestar/releases/tag/v1.45.0); [v1.46.0-rc.1](https://github.com/ChainSafe/lodestar/releases/tag/v1.46.0-rc.1) at `e2b315e` is the newest immutable audit target; `BASELINE-01` still owns the exact working `unstable` pin | -| Builder implementation | Initial [`@lodestar/builder`](https://www.npmjs.com/package/@lodestar/builder) package merged in [#9758](https://github.com/ChainSafe/lodestar/pull/9758); [#9781](https://github.com/ChainSafe/lodestar/pull/9781) is an open review-required draft at `251347b7b5` with 33 commits and eight unresolved Nico threads; `SIGN-01`, `CLI-01`, and `API-01` are Done by project decision, `REVIEW-01` and `TEST-01` are In Progress, API-02 is In Review, and `MET-01` is Todo | +| Lodestar baseline | [v1.46.0](https://github.com/ChainSafe/lodestar/releases/tag/v1.46.0) at `3873dd5b032d0ad82581fc3416e9628b4f6f2642` is the latest stable and newest immutable release target; `BASELINE-01` still owns the exact working `unstable` pin | +| Builder implementation | Initial [`@lodestar/builder`](https://www.npmjs.com/package/@lodestar/builder) package merged in [#9758](https://github.com/ChainSafe/lodestar/pull/9758); identity, readiness, fee-recipient wiring, and status tracking merged in [#9781](https://github.com/ChainSafe/lodestar/pull/9781) as `2a04194b900e`; API-02 integrated that baseline in fork PR [#48](https://github.com/krisoshea-eth/lodestar/pull/48). `REVIEW-01` remains In Progress only for post-merge thread-marker and follow-up reconciliation, `TEST-01` is In Progress, API-02 is In Review, and `MET-01` is Todo | | Devnet | [glamsterdam-devnet-7](https://notes.ethereum.org/@ethpandaops/glamsterdam-devnet-7) remains the active published configuration on alpha.12/v7.2.0. Four Tysm/Prysm host definitions were removed in devnet commit [`1ca063f`](https://github.com/ethpandaops/ethereum-package/commit/1ca063f64d17df4479926d380f527bc2181b3f07), and the Dora image override changed in [`df1dfc7`](https://github.com/ethpandaops/ethereum-package/commit/df1dfc727b278eddfbf93f5bb42c83ee5f52e2ff); these are configuration evidence, not runtime-health proof. [`tests-glamsterdam-devnet@v8.1.0`](https://github.com/ethereum/execution-specs/releases/tag/tests-glamsterdam-devnet%40v8.1.0) is the latest successor fixture release but does not establish a devnet-8 launch | | Builder lifecycle identifiers | Deposit request type `0x03`; Builder withdrawal credentials prefix `0xB0` | | Payload deadline | `PAYLOAD_DUE_BPS = 5000`, six seconds into a 12-second slot; PTC payload attestation remains at `7500` | -| Last reconciliation | August 11, 2026: direct Lodestar and project-board checks, Builder PR #9781 review state, API-02 implementation and tests, implementation plan, Linear, and GitHub issue mirror | -| Next milestone | Resolve and merge #9781, reconcile its final Builder initialization with API-02, finish `BASELINE-01` and `ENV-01`, and continue the separated `TEST-01` work before activating the reviewed BN preparation/candidate design while `MET-01` proceeds separately | +| Last reconciliation | August 14, 2026: Lodestar v1.46.0, merged Builder PR #9781 and its full review-thread inventory, open follow-ups #9819/#9827, integrated API-02 implementation and tests, implementation plan, Linear, and GitHub issue mirror | +| Next milestone | Open API-02 against `ChainSafe/lodestar:unstable`, finish `BASELINE-01` and `ENV-01`, reconcile #9781's review markers and #9827 in `REVIEW-01`, and continue the separated `TEST-01` work before activating the reviewed BN preparation/candidate design while `MET-01` proceeds separately | This is the working document for the Lodestar EIP-7732 Builder project, an EPF cohort 7 project by [Kris O'Shea](https://github.com/krisoshea-eth) and [Marko Lazic](https://github.com/markolazic01), mentored by [Nico Flaig](https://github.com/nflaig) (ChainSafe, EIP-7732 co-author). The [project proposal](https://github.com/eth-protocol-fellows/cohort-seven/blob/master/projects/lodestar-eip-7732-builder.md) remains the stable public scope, while the [merged implementation plan](https://github.com/krisoshea-eth/lodestar-eip-7732-builder-docs/blob/main/docs/implementation-plan.md) owns accepted delivery decisions and issue boundaries. This note carries moving technical context, implementation findings, upstream state, code-path maps, adversarial cases, and research watches. Linear owns issue status, ownership, dependencies, and evidence. @@ -66,7 +66,7 @@ This is the working document for the Lodestar EIP-7732 Builder project, an EPF c Run roughly weekly and before each milestone. Update the Doc status table afterwards. - [ ] New consensus-specs prerelease after `v1.7.0-alpha.13`, or a change to the #5497 head-compatible bid rules? -- [ ] Stable Lodestar release after v1.45.0, or material `unstable` changes to the Builder package, Gloas types, payload production, publication, or events? +- [ ] Stable Lodestar release after v1.46.0, or material `unstable` changes to the Builder package, Gloas types, payload production, publication, or events? - [ ] Status change in [#9736](https://github.com/ChainSafe/lodestar/pull/9736), Builder [#9781](https://github.com/ChainSafe/lodestar/pull/9781), the replacement investigation after closed-unmerged shutdown [#9793](https://github.com/ChainSafe/lodestar/pull/9793), builder-specs #165, or beacon-APIs #630? - [ ] Status or contract change in [builder-specs #165](https://github.com/ethereum/builder-specs/pull/165) or [beacon-APIs #630](https://github.com/ethereum/beacon-APIs/pull/630)? - [ ] Cross-client rollout of #5497, especially Teku and the Prysm replacement, and any evidence that strict local-head validation limits propagation? @@ -106,10 +106,11 @@ flowchart LR |---|---|---|---| | 2026-08-11 | API-02 SSE operational boundary | **Keep one source and route recovery explicitly** | Node 24.13.0 selects Lodestar's npm `eventsource` fallback. The Builder CLI currently supplies one BN URL, but the shared API client pins SSE to its first URL while ordinary REST requests can use fallbacks. The Beacon API event contract defines no SSE `id` or `Last-Event-ID` resumption, so conforming clients cannot be assumed to provide exact replay. `ENV-01` owns connected/reconnecting shutdown evidence, `REL-01` owns bounded same-source reconciliation, and deferred multi-BN/long-gap issues retain the wider work | | 2026-08-10 | API-02 selected-bid observation path | **Use standard `block` SSE plus `getBlockV2`** | The Builder subscribes through its source BN API, retrieves the signed fork-correct block by root with five 200 ms retry delays, and deduplicates a FIFO window of 256 roots. `block_gossip`, reconnect, replay, and restart recovery remain deferred to later work; no Lodestar-specific endpoint is required for correctness | -| 2026-08-10 | Later-deposited Builder lifecycle | **Direction reviewed; implementation open** | When the configured key is absent from the BN result, keep the sidecar inert and retry with cancellation so a later deposit or activation can be discovered. Keep a returned non-active lifecycle status distinct and operator-visible. `REVIEW-01` owns implementation and merge; `TEST-01` owns the regressions | +| 2026-08-14 | Builder foundation follow-up | **#9781 merged; cleanup remains** | #9781 merged as `2a04194b900e` after Nico approval and passing checks. Twelve review-thread markers remain for explicit reconciliation; #9819 owns test-helper deduplication and #9827 carries logging and abort-loop nits. `REVIEW-01` stays In Progress until that bookkeeping is closed without reopening completed CLI-01/API-01 scope | +| 2026-08-10 | Later-deposited Builder lifecycle | **Implemented and merged** | When the configured key is absent from the BN result, the sidecar remains inert and retries with cancellation so a later deposit or activation can be discovered. Pending, exited, and unknown results remain distinct and operator-visible. The implementation merged in #9781; `TEST-01` retains broader readiness, CLI, and diagnostic regressions | | 2026-08-10 | Partial monitor and devnet configuration movement | **Record without inferring health** | The August 10 monitor was partial, so unavailable source cursors were not advanced. Direct checks confirmed the #9781 live state, the four devnet host removals in `1ca063f`, and the Dora override in `df1dfc7`; none proves public devnet health or a devnet-8 launch | | 2026-08-09 | Release-candidate and shutdown baseline | **Audit rc.1; root shutdown handle still open** | [v1.46.0-rc.1](https://github.com/ChainSafe/lodestar/releases/tag/v1.46.0-rc.1) supersedes rc.0. #9790 preserves state/database close and #9792 fixes a QUIC resource leak. #9793 closed without merge because the proposed force-exit mechanism did not generalize, especially for container PID 1; none identifies the underlying stuck handle | -| 2026-08-09 | Builder Gate-A issue split | **Completed scopes and follow-ups remain separate** | Marko's `CLI-01` and `API-01` closure is preserved. `REVIEW-01` owns the open #9781 review/lifecycle implementation/merge work, while `TEST-01` and `MET-01` own the remaining test matrix and metrics | +| 2026-08-09 | Builder Gate-A issue split | **Completed scopes and follow-ups remain separate** | Marko's `CLI-01` and `API-01` closure is preserved. After #9781 merged, `REVIEW-01` retains only its thread-marker and follow-up reconciliation, while `TEST-01` and `MET-01` own the remaining test matrix and metrics | | 2026-08-07 | Equivocation validation | **Merged** | [Lodestar #9757](https://github.com/ChainSafe/lodestar/pull/9757) now supplies BN-owned `consensus_and_equivocation` validation and Deathstar proposer-equivocation machinery | | 2026-08-05 | Implementation plan | **v1.0 merged** | [Docs PR #2](https://github.com/krisoshea-eth/lodestar-eip-7732-builder-docs/pull/2); all 14 review threads resolved and no plan-level question remains open | | 2026-08-04 | Public Builder CLI docs | **Hidden until functional** | [Lodestar #9770](https://github.com/ChainSafe/lodestar/pull/9770) merged; restore the sidebar entry during `HANDOFF-01` | @@ -163,15 +164,15 @@ flowchart LR ## Confirmed facts -These items were reconciled against the August 10 partial monitoring report, confirmed Lodestar-team guidance, and direct live primary-source checks through August 11. The partial run did not advance unavailable source cursors or establish runtime health. Re-check them after each baseline bump. +These items were reconciled against the August 10 partial monitoring report, confirmed Lodestar-team guidance, and direct live primary-source checks through August 14. The partial run did not advance unavailable source cursors or establish runtime health. Re-check them after each baseline bump. ### Current Builder implementation state - [Lodestar #9758](https://github.com/ChainSafe/lodestar/pull/9758) created the first real `@lodestar/builder` package. It includes package and CLI scaffolding, one local keystore-backed key, bid and envelope signing with tests, a Builder `waitForGenesis`, source-BN wiring, shared `assertEqualParams`, active-Builder lookup, signal handling, and shutdown. - The package was first published to npm on August 4. `latest` is currently the placeholder `0.0.0`; development builds are published under the `next` tag. This is package availability, not a claim that the command is production-ready. -- `SIGN-01`, `CLI-01`, and `API-01` are complete in the project board. `REVIEW-01` keeps the open [Lodestar #9781](https://github.com/ChainSafe/lodestar/pull/9781) review, lifecycle implementation, documentation, and merge work visible; `TEST-01` and `MET-01` own the remaining cross-cutting test and metric work. -- [Lodestar #9781](https://github.com/ChainSafe/lodestar/pull/9781) is an open review-required draft at head `251347b7b5c5723a84ca6851e603604cdc75cd80`, with 33 commits and eight unresolved Nico review threads on August 11. It adds Builder identity/status tracking, BN and EL readiness polling, `--executionFeeRecipient`, request timeout wiring, and identity/tracker tests. The branch uses the API client's standard `.value()` response path and asynchronous API-error response mocks. The reviewed later-Builder direction is to keep an unknown configured key inert and retry with cancellation until a later deposit or activation can be discovered, while treating a returned non-active lifecycle status as a distinct operator-visible result. Remaining review work covers the later-Builder lifecycle, bounded useful error detail, and the current assumption that Gloas-capable clients expose the health endpoint. -- The current #9781 tests cover successful Builder-index resolution, returned non-active status, version mismatch, status-lookup failure, initial tracker state, first successful polling, balance-only changes, lifecycle-status changes, and failed-poll state preservation. Unknown-key polling and later activation, cancellation, readiness recovery, bounded error detail, genesis logging, and CLI cases remain in `TEST-01`. +- `SIGN-01`, `CLI-01`, and `API-01` are complete in the project board. [Lodestar #9781](https://github.com/ChainSafe/lodestar/pull/9781) merged as `2a04194b900ef972c6f469d06017d5c972be5714` after Nico approved head `3fe4ef4980645144668f8f634884c72a69f83677` and required checks passed. `REVIEW-01` now keeps only the post-merge thread-marker and follow-up reconciliation visible; `TEST-01` and `MET-01` own the remaining cross-cutting test and metric work. +- #9781 adds Builder identity/status tracking, BN and EL readiness polling, `--executionFeeRecipient`, request timeout wiring, and identity/tracker tests. Unknown and pending configured keys wait inertly with cancellation, exited Builders fail distinctly, identity responses are sanity-checked, and API errors use the standard response path. The current assumption that Gloas-capable clients expose the health endpoint was explicitly accepted for now. +- Twelve #9781 review-thread markers remain unresolved in GitHub despite the merge: five are outdated, two record accepted or already-applied behavior, one points to open test-helper deduplication issue [#9819](https://github.com/ChainSafe/lodestar/issues/9819), and four logging or abort-loop nits are carried by open follow-up [#9827](https://github.com/ChainSafe/lodestar/pull/9827). They remain explicit `REVIEW-01` cleanup rather than being silently marked resolved. Broader readiness recovery, bounded diagnostic, genesis logging, and CLI coverage remain in `TEST-01`. - The main implementation gap is no longer signing. It is the complete same-host workflow: a reviewed BN preparation/candidate surface, canonical payload production with the Builder fee recipient, exact complete-bid return, publication timing, selection observation, stateful envelope retrieval, and evidence. - The Builder does not connect directly to the EL in core. The source BN owns Engine API access, proposer/head context, payload construction, value, balance enforcement, reveal material, and publication validation. - The sidecar owns its local key, chain/source-BN checks, active Builder resolution, head observation, bounded scheduling, sanity-checking and signing the exact BN-produced objects, exact local bid matching, diagnostics, and orchestration. @@ -188,8 +189,7 @@ These items were reconciled against the August 10 partial monitoring report, con - [#9766](https://github.com/ChainSafe/lodestar/pull/9766) aligns the Builder package build and type-check scripts with the workspace TypeScript 7 migration. This closes the immediate CI-script regression but does not complete CLI readiness. - [#9770](https://github.com/ChainSafe/lodestar/pull/9770) hides the generated Builder CLI page from the public docs sidebar until the command is functional. - [#9757](https://github.com/ChainSafe/lodestar/pull/9757) merged BN-owned `consensus_and_equivocation` validation and Deathstar proposer-equivocation support. The stored local fixture still needs to replace buildoor with Lodestar Builder after the honest lifecycle works. -- [#9790](https://github.com/ChainSafe/lodestar/pull/9790) and [#9792](https://github.com/ChainSafe/lodestar/pull/9792) are part of v1.46.0-rc.1. They preserve state/database close during a stuck network-worker shutdown and settle aborted QUIC resources respectively, but do not identify the underlying stuck handle. [#9793](https://github.com/ChainSafe/lodestar/pull/9793) closed without merge after review found that its self-signal/force-exit approach did not generalize, especially for default Docker/Kubernetes PID 1. Forced termination remains a process-manager responsibility while the root handle is investigated. -- [#9788](https://github.com/ChainSafe/lodestar/pull/9788) is the open draft v1.46.0 release PR at the rc.1 commit. It is a release watch, not evidence that v1.46.0 stable has shipped. +- [#9790](https://github.com/ChainSafe/lodestar/pull/9790) and [#9792](https://github.com/ChainSafe/lodestar/pull/9792) are included in v1.46.0. They preserve state/database close during a stuck network-worker shutdown and settle aborted QUIC resources respectively, but do not identify the underlying stuck handle. [#9793](https://github.com/ChainSafe/lodestar/pull/9793) closed without merge after review found that its self-signal/force-exit approach did not generalize, especially for default Docker/Kubernetes PID 1. Forced termination remains a process-manager responsibility while the root handle is investigated. - [#9780](https://github.com/ChainSafe/lodestar/pull/9780) is an open circuit-breaker follow-up outside rc.1. Circuit-breaker thresholds and recovery remain unsettled and do not change the core Builder sidecar scope. - [#9755](https://github.com/ChainSafe/lodestar/pull/9755) merged the local-versus-peer fault-ownership fix. Wrapped local EL/import failures now stay on the execution-error path rather than consuming honest peer scores. - [#9762](https://github.com/ChainSafe/lodestar/pull/9762) updated `prepareNextSlot` to derive the proposer from the post-Fulu head state before creating the prepared state, avoiding a second state regeneration and possible double epoch transition. `BN-01` must trace this current flow rather than the older two-regeneration path. @@ -225,18 +225,17 @@ PAYLOAD_ATTESTATION_DUE_BPS = 7500 The phrase “Lodestar baseline” has two layers: -1. **Stable release reference:** [v1.45.0](https://github.com/ChainSafe/lodestar/releases/tag/v1.45.0), published July 27. -2. **Newest immutable audit target:** [v1.46.0-rc.1](https://github.com/ChainSafe/lodestar/releases/tag/v1.46.0-rc.1) at `e2b315e`, which supersedes rc.0 but does not include Builder #9781. -3. **Implementation baseline:** current `unstable`, pinned to an exact SHA by `BASELINE-01` before more code is treated as Ready. +1. **Stable release and newest immutable audit target:** [v1.46.0](https://github.com/ChainSafe/lodestar/releases/tag/v1.46.0) at `3873dd5b032d0ad82581fc3416e9628b4f6f2642`, published August 12. It predates merged Builder #9781. +2. **Implementation baseline:** current `unstable`, pinned to an exact SHA by `BASELINE-01` before more code is treated as Ready. `BASELINE-01` still owns the deliberate project pin and reproducibility evidence. The historical August 5 observation `c65aaefd91a602df1ffb82d929ec479fba8578ac` is not a substitute for completing that issue. -Important moving inputs on August 11: +Important moving inputs on August 14: -- [#9781](https://github.com/ChainSafe/lodestar/pull/9781), open, review-required, and draft at `251347b7b5`: Gate-A Builder identity, readiness, configuration, lifecycle implementation, and tests; +- [#9781](https://github.com/ChainSafe/lodestar/pull/9781), merged as `2a04194b900e`: Gate-A Builder identity, readiness, configuration, lifecycle implementation, and tests; +- [#9827](https://github.com/ChainSafe/lodestar/pull/9827), open and ready for review: Builder abort-loop and logging follow-ups from the final #9781 review; - [#9736](https://github.com/ChainSafe/lodestar/pull/9736), draft: correct FULL-parent state use for production and reward calculation; - [#9761](https://github.com/ChainSafe/lodestar/pull/9761), draft: Gloas compliance coverage; -- [#9788](https://github.com/ChainSafe/lodestar/pull/9788), open draft: v1.46.0 release preparation at the rc.1 commit, not a stable release; - [#9780](https://github.com/ChainSafe/lodestar/pull/9780), open: circuit-breaker review follow-up outside rc.1, with policy still unsettled; - [#9793](https://github.com/ChainSafe/lodestar/pull/9793), closed without merge: retained as diagnostic history for a rejected self-signal/force-exit approach; the root network-worker handle remains unresolved; - [builder-specs #165](https://github.com/ethereum/builder-specs/pull/165) and [beacon-APIs #630](https://github.com/ethereum/beacon-APIs/pull/630), open: API parity, request-auth, timeout, header, and preference details. @@ -355,7 +354,7 @@ Only unresolved or moving items belong here. ### Direct project delivery - **Baseline pin:** record the exact `unstable` SHA, spec/API versions, fixture/image versions, baseline failures, and capability audit in `BASELINE-01`. -- **Source-BN readiness:** resolve and merge [#9781](https://github.com/ChainSafe/lodestar/pull/9781), including the reviewed unknown-key inert wait/retry implementation, standard API-client response handling, bounded useful error detail, and the remaining health-endpoint thread; close the separated regressions through `TEST-01`. +- **Source-BN readiness:** [#9781](https://github.com/ChainSafe/lodestar/pull/9781) is merged. Reconcile its twelve remaining review-thread markers, review open follow-up [#9827](https://github.com/ChainSafe/lodestar/pull/9827), retain [#9819](https://github.com/ChainSafe/lodestar/issues/9819) as separate test-helper cleanup, and close broader regressions through `TEST-01`. - **Preparation/candidate contract:** trace `prepareNextSlot` and return the proposed route/lifecycle for Lodestar review in `BN-01`. - **FULL-parent production:** reuse [Lodestar #9736](https://github.com/ChainSafe/lodestar/pull/9736) if it lands; do not create a parallel workaround. - **Equivocation validation:** [#9757](https://github.com/ChainSafe/lodestar/pull/9757) is merged; rerun the stored fixture with Lodestar Builder. @@ -799,22 +798,22 @@ Do not use the `focil` branch as the default base before those conditions are me ## Current Lodestar code-path map -Status reflects the August 11 reconciliation. The merged implementation plan remains the delivery source of truth; this map highlights moving code seams and upstream work. +Status reflects the August 14 reconciliation. The merged implementation plan remains the delivery source of truth; this map highlights moving code seams and upstream work. | Area | File / PR | Current understanding | Builder follow-up | |---|---|---|---| -| Builder package and CLI | [#9758](https://github.com/ChainSafe/lodestar/pull/9758), [#9766](https://github.com/ChainSafe/lodestar/pull/9766), [#9781](https://github.com/ChainSafe/lodestar/pull/9781) | Initial package and TypeScript follow-up are merged; #9781 is an open review-required draft at `251347b7b5` with identity/status tracking, readiness, fee-recipient and timeout wiring | Keep CLI-01/API-01 closed by project decision; resolve #9781 feedback, lifecycle implementation, documentation, and merge in REVIEW-01 while TEST-01/MET-01 continue separately; keep generated CLI docs hidden until functional | +| Builder package and CLI | [#9758](https://github.com/ChainSafe/lodestar/pull/9758), [#9766](https://github.com/ChainSafe/lodestar/pull/9766), [#9781](https://github.com/ChainSafe/lodestar/pull/9781) | Initial package, TypeScript follow-up, and #9781 identity/status tracking, readiness, fee-recipient, and timeout wiring are merged; #9827 carries final abort-loop and logging nits | Keep CLI-01/API-01 closed by project decision; reconcile the remaining review markers and #9827 in REVIEW-01 while TEST-01/MET-01 continue separately; keep generated CLI docs hidden until functional | | Builder signing | [#9758](https://github.com/ChainSafe/lodestar/pull/9758) | Bid and envelope signing with a local Builder keystore is merged and tested | Treat `SIGN-01` as complete; extend only for fork coverage and failure evidence | | Shared configuration checks | [#9725](https://github.com/ChainSafe/lodestar/pull/9725) | `assertEqualParams` and `NotEqualParamsError` moved to `@lodestar/config` | Import from config; do not create a Builder-to-validator dependency | | Genesis wait behavior | [#9726](https://github.com/ChainSafe/lodestar/pull/9726) | Validator now distinguishes a pre-genesis 404 from other failures | Keep the small Builder copy aligned; do not add unreachable BN code | -| Source-BN client and readiness | [#9781](https://github.com/ChainSafe/lodestar/pull/9781), BN sync helpers | Open draft at `251347b7b5` with eight unresolved Nico threads. Standard `.value()` response handling and asynchronous error-response mocks match the reviewed direction; identity/tracker tests cover the main returned-state and polling cases, while unknown-key polling/later activation, cancellation, readiness recovery, and bounded error detail remain follow-up | Implement the reviewed inert wait/retry path for an unknown configured key, preserve returned non-active status separately, retain the BN-owned preparation guard, and finish the missing test matrix in TEST-01 | +| Source-BN client and readiness | [#9781](https://github.com/ChainSafe/lodestar/pull/9781), [#9827](https://github.com/ChainSafe/lodestar/pull/9827), BN sync helpers | #9781 merged the standard response path, inert wait/retry for unknown and pending keys, cancellation, identity checks, readiness diagnostics, and tracker tests. #9827 is open for abort-loop and logging nits; broader readiness and CLI regressions remain follow-up | Reconcile the merged review markers and #9827 in REVIEW-01, retain the BN-owned preparation guard, and finish the missing test matrix in TEST-01 | | Bid gossip and head compatibility | [#9739](https://github.com/ChainSafe/lodestar/pull/9739), [#9756](https://github.com/ChainSafe/lodestar/pull/9756) | Local-head-compatible multiple bids are merged, including the narrow epoch-boundary direct-parent filter | Track the connected BN head; publish the same-head core path and leave branch flooding conditional | | Exact bid fields | [#9749](https://github.com/ChainSafe/lodestar/pull/9749), [#9750](https://github.com/ChainSafe/lodestar/pull/9750), [#9751](https://github.com/ChainSafe/lodestar/pull/9751) | Exact `UintBn64` propagation is merged for execution payment, bid gas limit, `targetGasLimit`, preferences, payload attributes, and events | Preserve exact values through parsing, caching, signing, hashing, and metrics; test `2^53±1` and `uint64` max | | Candidate preparation and payload cache | BN production and Engine paths, [#9762](https://github.com/ChainSafe/lodestar/pull/9762) | The BN already owns EL access and payload caching; `prepareNextSlot` now avoids the earlier second state regeneration, but the Builder-specific trigger and return shape are not settled | Trace the updated `prepareNextSlot` and existing cleanup before proposing the smallest `/builder` or `/beacon` surface | | FULL-parent production | [#9736](https://github.com/ChainSafe/lodestar/pull/9736) | Draft work remains for operation selection, rewards, exits, and execution requests on the correct state | Keep on the baseline watchlist and cover FULL/EMPTY paths in E2E evidence | | Envelope validation and Deathstar | [#9757](https://github.com/ChainSafe/lodestar/pull/9757) | Merged `consensus_and_equivocation` support and proposer-equivocation test machinery | Use the stored local fixture, then replace buildoor with Lodestar Builder when ready | | Builder API convergence | closed [#9594](https://github.com/ChainSafe/lodestar/pull/9594), [builder-specs #165](https://github.com/ethereum/builder-specs/pull/165), [beacon-APIs #630](https://github.com/ethereum/beacon-APIs/pull/630) | #9594 closed without merge; specifications and a replacement Lodestar implementation are still moving | Re-audit settled routes before BN-01; staked request authentication remains conditional | -| Shutdown and restart | [v1.46.0-rc.1](https://github.com/ChainSafe/lodestar/releases/tag/v1.46.0-rc.1), [#9790](https://github.com/ChainSafe/lodestar/pull/9790), [#9792](https://github.com/ChainSafe/lodestar/pull/9792), [#9793](https://github.com/ChainSafe/lodestar/pull/9793) | rc.1 preserves state/database close and fixes a QUIC resource leak; #9793 closed without merge because its force-exit approach did not generalize; the root stuck handle is unresolved | Add Builder metrics-server shutdown, same-source restart/cache recovery, and process-manager timeout evidence without conflating the BN and Builder handles or adopting the rejected self-signal approach | +| Shutdown and restart | [v1.46.0](https://github.com/ChainSafe/lodestar/releases/tag/v1.46.0), [#9790](https://github.com/ChainSafe/lodestar/pull/9790), [#9792](https://github.com/ChainSafe/lodestar/pull/9792), [#9793](https://github.com/ChainSafe/lodestar/pull/9793) | v1.46.0 preserves state/database close and fixes a QUIC resource leak; #9793 closed without merge because its force-exit approach did not generalize; the root stuck handle is unresolved | Add Builder metrics-server shutdown, same-source restart/cache recovery, and process-manager timeout evidence without conflating the BN and Builder handles or adopting the rejected self-signal approach | | Range-sync fault ownership | [#9755](https://github.com/ChainSafe/lodestar/pull/9755) | Merged fix preserves local-versus-peer error ownership when the EL fails | Retain the regression in tests and metrics; no new Builder workstream is required | | Public CLI documentation | [#9770](https://github.com/ChainSafe/lodestar/pull/9770) | Merged temporary sidebar hide for the not-yet-functional command | Restore the page only after the command is functionally ready and REVIEW-01 closes; the administrative closure of CLI-01 alone is not the publication signal | | FOCIL and advanced adversarial work | [#7342](https://github.com/ChainSafe/lodestar/pull/7342), Deathstar research | Valuable but outside the core Gloas delivery path | Activate only through the implementation plan's extension gate | @@ -899,12 +898,12 @@ Current delivery state at this reconciliation: | `PLAN-01` | Done | GitHub plan merged; GitHub is canonical for the over-limit full plan and the short HackMD landing page remains the public pointer | | Board setup | Done | 47 tracked Linear issues with GitHub issue sync, milestones, scope labels, cycles, saved views, and a public GitHub Project mirror | | `SIGN-01` | Done | Merged and tested in Lodestar #9758 | -| `CLI-01`, `API-01` | Done | Closure preserved in line with Marko's project-status decision; REVIEW-01 carries the remaining #9781 review, lifecycle implementation, documentation, and merge work | -| `REVIEW-01` | In progress | Resolve eight #9781 review threads, implement the reviewed unknown-key inert wait/retry behavior, document responsibility boundaries, and record final merge evidence | +| `CLI-01`, `API-01` | Done | Closure preserved in line with Marko's project-status decision; their #9781 implementation is merged | +| `REVIEW-01` | In progress | #9781 merged with Nico approval and passing checks; reconcile twelve remaining GitHub thread markers, open follow-up #9827, and separate test-helper issue #9819 | | `TEST-01` | In progress | Main returned-state and tracker polling cases landed in #9781; unknown-key/later-activation, cancellation, readiness recovery, bounded-error, genesis-log, and CLI evidence remain | | `MET-01` | Todo | Add the metrics server and bounded process, signer, Builder-status/balance, and readiness metrics with clean shutdown evidence | | `BASELINE-01`, `ENV-01` | Todo | Pin the current unstable baseline and establish the deterministic local network | -| `API-02` | In review | Draft implementation PR #48 and docs PR #13 contain the audited bounded event path; #9781 integration and `ENV-01` end-to-end evidence remain before closure | +| `API-02` | In review | Fork draft #48 has integrated merged #9781; docs PRs #13 and #14 are merged; the upstream Lodestar PR and `ENV-01` real-BN evidence remain before closure | The near-term activation order is: @@ -956,14 +955,13 @@ This note intentionally does not duplicate that weekly log. It records the curre ## PR / branch status -Status checked August 11, 2026 against live primary sources. The August 10 monitor was partial, so its unavailable source cursors were not advanced and no runtime-health inference was made. The tables prioritise items that can change the Builder architecture or current baseline; the daily monitor remains the broader watch inventory. +Status checked August 14, 2026 against live primary sources. The August 10 monitor was partial, so its unavailable source cursors were not advanced and no runtime-health inference was made. The tables prioritise items that can change the Builder architecture or current baseline; the daily monitor remains the broader watch inventory. ### Lodestar | Item | Status | Why it matters | |---|---|---| -| [v1.45.0](https://github.com/ChainSafe/lodestar/releases/tag/v1.45.0) | Latest stable; July 27 | Reproducible stable release, but the Builder project pins a newer `unstable` commit | -| [v1.46.0-rc.1](https://github.com/ChainSafe/lodestar/releases/tag/v1.46.0-rc.1) | Newest immutable audit target at `e2b315e` | Supersedes rc.0; includes shutdown/resource work but not Builder #9781 | +| [v1.46.0](https://github.com/ChainSafe/lodestar/releases/tag/v1.46.0) | Latest stable at `3873dd5b032d0ad82581fc3416e9628b4f6f2642`; August 12 | Newest immutable release target; predates Builder #9781 | | [#9758](https://github.com/ChainSafe/lodestar/pull/9758) — initial Builder | Merged | Establishes `@lodestar/builder`, CLI, key loading, signing, BN wiring, and tests | | [#9725](https://github.com/ChainSafe/lodestar/pull/9725) / [#9726](https://github.com/ChainSafe/lodestar/pull/9726) | Merged | Shared config checks and 404-aware validator genesis waiting | | [#9739](https://github.com/ChainSafe/lodestar/pull/9739) / [#9756](https://github.com/ChainSafe/lodestar/pull/9756) | Merged | Local-head-compatible multi-bid handling and narrow epoch-boundary filtering | @@ -971,8 +969,8 @@ Status checked August 11, 2026 against live primary sources. The August 10 monit | [#9486](https://github.com/ChainSafe/lodestar/pull/9486) / [#9598](https://github.com/ChainSafe/lodestar/pull/9598) | Merged | `head_v2` payload-status observation and the existing Gloas proposer circuit breaker | | [#9766](https://github.com/ChainSafe/lodestar/pull/9766) | Merged | Restores Builder package build/type-check scripts after the TypeScript 7 migration | | [#9770](https://github.com/ChainSafe/lodestar/pull/9770) | Merged | Temporarily hides the incomplete Builder CLI page | -| [#9781](https://github.com/ChainSafe/lodestar/pull/9781) — Builder identity/readiness/CLI | Open review-required draft at `251347b7b5`; 33 commits and eight unresolved Nico threads. The standard `.value()` response path and async error mocks are in the branch | CLI-01/API-01 remain closed by project decision. REVIEW-01 owns the reviewed unknown-key lifecycle implementation and remaining review/merge work; TEST-01 and MET-01 retain their separated scopes | -| [#9788](https://github.com/ChainSafe/lodestar/pull/9788) — v1.46.0 release | Open draft at `e2b315e` | Release watch only; rc.1 remains the newest immutable audit target until a stable release lands | +| [#9781](https://github.com/ChainSafe/lodestar/pull/9781) - Builder identity/readiness/CLI | Merged as `2a04194b900e` after Nico approval and passing checks; twelve review-thread markers remain in the UI | CLI-01/API-01 remain closed by project decision. REVIEW-01 owns explicit thread-marker reconciliation, #9827, and the separate #9819 follow-up; TEST-01 and MET-01 retain their separated scopes | +| [#9827](https://github.com/ChainSafe/lodestar/pull/9827) - Builder review follow-ups | Open, ready for review | Carries abort-loop and logging nits referenced from the final #9781 review; reconcile it through REVIEW-01 | | [#9780](https://github.com/ChainSafe/lodestar/pull/9780) — circuit-breaker follow-up | Open outside rc.1 | Policy and recovery remain unsettled; watch for baseline impact without adding a new core Builder workstream | | [#9594](https://github.com/ChainSafe/lodestar/pull/9594) — Builder actor/API | Closed without merge August 5 | Historical design input only; re-audit the replacement implementation before BN-01 or the staked API extension | | [#9736](https://github.com/ChainSafe/lodestar/pull/9736) — FULL-parent production | Open draft | Correct parent-state operation selection and rewards remain relevant to E2E coverage | diff --git a/docs/work-log.md b/docs/work-log.md index 2a094f2..08c0c93 100644 --- a/docs/work-log.md +++ b/docs/work-log.md @@ -118,3 +118,12 @@ Kris: - Added 25 focused tests covering stream wiring, Gloas and Heze fork-correct output, sequential and concurrent duplicates, event-before-block 404 retry, retry exhaustion, error classification, cancellation, unsupported forks, metadata/body disagreement, bounded eviction, self-build sentinel handling, unexpected stream closure, callback isolation, and shared abort-signal use. The complete Builder package suite now contains 31 passing tests. - Confirmed that standard `block` plus `getBlockV2` is sufficient for correctness. Posted the implementation evidence to [beacon-APIs #599](https://github.com/ethereum/beacon-APIs/issues/599#issuecomment-5257353985); an enriched event remains an efficiency and interoperability improvement rather than a prerequisite. - Audited the runtime event boundary on Node 24.13.0. Lodestar uses the npm `eventsource` fallback; the Builder CLI currently pins one BN URL; shared-client multi-URL fallback would need explicit source affinity; and the Beacon API event contract provides no standard event ID or resumption mechanism. Routed connected/reconnecting shutdown evidence to `ENV-01`, bounded same-source reconciliation to `REL-01`, multi-BN provenance to LOD-37, and long-gap replay/reorg work to LOD-41. + +### Current checkpoint - 14 August 2026 + +Kris and Marko: + +- [Lodestar #9781](https://github.com/ChainSafe/lodestar/pull/9781) merged into `unstable` as `2a04194b900ef972c6f469d06017d5c972be5714` after Nico approved head `3fe4ef4980645144668f8f634884c72a69f83677` and the required checks passed. The unknown-key and pending-Builder wait paths, cancellation-aware polling, Builder identity checks, readiness reporting, fee-recipient wiring, and status tracking are now upstream. +- Merged the updated `unstable` baseline into API-02 at `1aae68a26fba53c2da1f361f2491042eae220f70`, preserving the #9781 initialization gates and the API-02 `BlockObserver`. The focused observer suite remains 25 tests and the integrated Builder package suite now contains 45 passing tests on Node 24.13.0. +- Kept `REVIEW-01` In Progress for post-merge bookkeeping rather than treating #9781 as open. Twelve review-thread markers remain unresolved in GitHub: five are outdated, two record accepted or already-applied behavior, one is tracked by [#9819](https://github.com/ChainSafe/lodestar/issues/9819), and four logging or abort-loop nits are followed up by open [#9827](https://github.com/ChainSafe/lodestar/pull/9827). No maintainer thread was silently resolved. +- Merged API-02 docs [#13](https://github.com/krisoshea-eth/lodestar-eip-7732-builder-docs/pull/13) and the SPEC-01 working draft [#14](https://github.com/krisoshea-eth/lodestar-eip-7732-builder-docs/pull/14). API-02 remains In Review until its fork PR is opened against `ChainSafe/lodestar:unstable`, upstream review completes, and `ENV-01` records the deterministic real-BN event-to-block smoke run.