[PAYLOAD-SOURCE-01] Add the PayloadSource contract and Engine adapter

[krisoshea-eth]

Why

PAYLOAD-01 needs a small reviewable foundation before Builder lifecycle wiring and slot orchestration. Nico's nflaig/builder branch proves the direct-Engine approach end to end, but its first Builder commit combines 24 files and about 2,130 added lines. This slice extracts the reusable payload-source boundary onto current unstable.

Planning

• Lane: Builder/Engine API
• Effort: S to M
• Ready now
• Owner: Kris
• Reviewer: Lodestar maintainer
• Parent: PAYLOAD-01
• Architecture source: nflaig/builder at 99fd8fa9ad

Scope

• Define the narrow PayloadSource, BuildRequest, BuildHandle, and BuiltPayload contracts.
• Add an initial Engine-backed adapter through an injected Engine boundary.
• Reconcile whether the adapter should depend on @lodestar/beacon-node or use a smaller Builder-owned interface.
• Preserve the fork, execution payload, execution requests, blobs bundle, source identity, payload ID, and execution payload value without narrowing.
• Return precise outcomes for null payload IDs, missing blobs, missing execution requests, unsupported responses, transport failures, timeout, and cancellation.
• Add focused deterministic unit tests against the current Engine interface.
• Record any current-unstable differences from Nico's implementation.

Out of scope

• Builder and CLI wiring.
• Payload-attributes event changes.
• Shared versus dedicated EL deployment policy.
• Multi-source orchestration and best-payload selection.
• Payload storage, bid construction, publication, selection, and reveal.

Done when

One injected Engine source can prepare and retrieve one complete fork-correct payload through focused tests, without changing the Builder runtime lifecycle.

Evidence

• Lodestar PR: ChainSafe/lodestar#9958 (draft)
• Current base SHA: 1e9a530f9897d50d2d6337cd4143c8dc53667c66
• Implementation head: 04d7ccd81f6c5504b9c9df6b35ff587b7ad8fd8c
• Payload-source tests: 12 focused tests passed; 39 Builder package tests passed
• Engine failure and cancellation tests: transport, timeout, cancellation, null payload ID, source mismatch, missing blobs, and missing execution requests covered
• Fork evidence: Gloas and Heze payload attributes remain fork-correlated; the Heze test carries inclusionListTransactions
• Post-Gloas Engine input: caller-provided custodyColumns is preserved through the adapter, following consensus-specs #5549 and execution-apis #774
• Validation: Builder type-check, lint, build, import check, and diff check passed with Node 24.13.0 and pnpm 11.0.0
• Reviewer:

[linear-code]

LOD-57

[krisoshea-eth]

Draft implementation opened upstream: ChainSafe#9958

Evidence:

• Base: 1e9a530f9897d50d2d6337cd4143c8dc53667c66
• Head: 2a3291d99f
• Focused payload-source tests: 12 passed
• Builder package tests: 39 passed
• Builder type-check, lint, build, import check, and diff check passed with Node 24.13.0 and pnpm 11.0.0

The PR remains draft. Runtime and CLI wiring remain in LOD-58.