Skip to content

feat(builder): coordinate bounded payload build jobs - #9973

Draft
krisoshea-eth wants to merge 29 commits into
ChainSafe:unstablefrom
krisoshea-eth:krisoshea/lod-58-payload-orch-01-spike
Draft

feat(builder): coordinate bounded payload build jobs#9973
krisoshea-eth wants to merge 29 commits into
ChainSafe:unstablefrom
krisoshea-eth:krisoshea/lod-58-payload-orch-01-spike

Conversation

@krisoshea-eth

@krisoshea-eth krisoshea-eth commented Sep 2, 2026

Copy link
Copy Markdown

Motivation

The Builder needs a small boundary for coordinating payload preparation and retrieval before event, CLI, storage, and bid wiring are added.

This PR is stacked on #9958. Until that dependency merges, the upstream diff contains both the payload-source and orchestration changes. The isolated two-file orchestration comparison is krisoshea-eth/lodestar#61.

Description

Add a package-internal PayloadOrchestrator that accepts an injected PayloadSource and a caller-defined retrieval time. It shares truly identical jobs, rejects reuse of one job ID with different request content, bounds distinct active jobs, cancels preparation or retrieval on timeout and shutdown, suppresses late results, and cleans up every terminal path.

Orchestration failures use structured error codes. Source and transport errors retain their original types. Invalid limits and invalid retrieval timestamps are rejected before any source request starts. Request retries and transport timeouts remain owned by the concrete payload source.

This draft does not add Builder or CLI wiring, choose a shared or dedicated EL, produce payload attributes, store payloads, construct bids, publish bids, or implement selection and reveal.

Testing

Validated with Node 24.13.0:

  • 27 focused PayloadOrchestrator tests
  • Builder type-check
  • Biome on the changed files
  • git diff --check

The tests verify request cancellation, phase timeouts, duplicate sharing, and structured rejection when one job ID is reused with different retrieval time, forkchoice state, payload attributes, or custody columns.

Evidence

The temporary integration branch proves that the source, orchestrator, and store seams compose. At 6c1aff6c66, the current source, orchestration, store, policy, preferences, bid, selection, and reveal components compose cleanly. All 152 Builder unit tests pass, together with type-check, Biome, build/import, and diff checks. This is deterministic integration evidence, not a live Engine or source-BN end-to-end run.

AI assistance

AI assistance was used during codebase research, implementation, drafting, testing, and review. The submitted code and PR text were reviewed and revised by the author, including manual edits and technical decisions.

krisoshea-eth and others added 3 commits September 2, 2026 16:31
…01-add-the-payloadsource-contract-and-engine' into krisoshea/lod-58-payload-orch-01-spike
…01-add-the-payloadsource-contract-and-engine' into krisoshea/lod-58-payload-orch-01-spike
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

1 participant