@lodestar/beacon-node 1.51.0-dev.e21949cfcf → 1.51.0-dev.e2bf489dd3

package/src/chain/chain.ts

@@ -4,6 +4,7 @@ import {Type} from "@chainsafe/ssz";
 import {routes} from "@lodestar/api";
 import {BeaconConfig} from "@lodestar/config";
 import {
+  AncestorStatus,
   CheckpointWithHex,
   EpochDifference,
   ForkChoiceStateGetter,
@@ -90,8 +91,9 @@ import {persistPayloadEnvelopeInput} from "./blocks/writePayloadEnvelopeInputToD
 import {BlsMultiThreadWorkerPool, BlsSingleThreadVerifier, IBlsVerifier} from "./bls/index.js";
 import {BuilderCircuitBreaker} from "./builderCircuitBreaker.js";
 import {ColumnReconstructionTracker} from "./ColumnReconstructionTracker.js";
-import {ChainEvent, ChainEventEmitter} from "./emitter.js";
+import {ChainEvent, ChainEventEmitter, ReorgEventData} from "./emitter.js";
 import {ForkchoiceCaller, initializeForkChoice} from "./forkChoice/index.js";
+import {ForkChoiceExecutionEngine} from "./forkChoiceExecutionEngine.js";
 import {GetBlobsTracker} from "./GetBlobsTracker.js";
 import {CommonBlockBody, FindHeadFnName, IBeaconChain, ProposerPreparationData, StateGetOpts} from "./interface.js";
 import {LightClientServer} from "./lightClient/index.js";
@@ -166,7 +168,7 @@ const DEFAULT_MAX_PENDING_UNFINALIZED_PAYLOAD_ENVELOPE_WRITES = 16;
 export class BeaconChain implements IBeaconChain {
   readonly genesisTime: UintNum64;
   readonly genesisValidatorsRoot: Root;
-  readonly executionEngine: IExecutionEngine;
+  readonly executionEngine: ForkChoiceExecutionEngine;
   readonly executionBuilder?: IExecutionBuilder;
   readonly builderCircuitBreaker: BuilderCircuitBreaker;
   readonly builderApiClient: BuilderApiClient;
@@ -317,7 +319,6 @@ export class BeaconChain implements IBeaconChain {
     this.genesisTime = anchorState.genesisTime;
     this.anchorStateLatestBlockSlot = anchorState.latestBlockHeader.slot;
     this.genesisValidatorsRoot = anchorState.genesisValidatorsRoot;
-    this.executionEngine = executionEngine;
     this.executionBuilder = executionBuilder;
     const signal = this.abortController.signal;
     const emitter = new ChainEventEmitter();
@@ -457,6 +458,12 @@ export class BeaconChain implements IBeaconChain {
     this.payloadEnvelopeProcessor = new PayloadEnvelopeProcessor(this, metrics, signal);
 
     this.forkChoice = forkChoice;
+    this.executionEngine = new ForkChoiceExecutionEngine(executionEngine, {
+      forkChoice,
+      recomputeHeadAfterELInvalidResponse: () => this.recomputeHeadAfterELInvalidResponse(),
+      logger,
+      metrics,
+    });
 
     this.builderCircuitBreaker = new BuilderCircuitBreaker(
       {faultInspectionWindow: opts.faultInspectionWindow, allowedFaults: opts.allowedFaults},
@@ -1430,6 +1437,58 @@ export class BeaconChain implements IBeaconChain {
     }
   }
 
+  /**
+   * Apply chain side effects of a fork choice head change: head state, head metrics, and reorg detection
+   */
+  onHeadChanged(oldHead: ProtoBlock, newHead: ProtoBlock, maybeHeadState?: IBeaconStateView): void {
+    // Set head state as strong reference
+    this.regen.updateHeadState(newHead, maybeHeadState);
+
+    const delaySec = this.clock.secFromSlot(newHead.slot);
+    this.logger.verbose("New chain head", {
+      slot: newHead.slot,
+      root: newHead.blockRoot,
+      payloadStatus: newHead.payloadStatus,
+      delaySec,
+    });
+    this.metrics?.headSlot.set(newHead.slot);
+
+    this.onNewHead(newHead);
+    this.metrics?.forkChoice.changedHead.inc();
+
+    const ancestorResult = this.forkChoice.getCommonAncestorDepth(oldHead, newHead);
+    if (ancestorResult.code === AncestorStatus.CommonAncestor) {
+      // CommonAncestor = chain reorg, old head and new head not direct descendants
+
+      const forkChoiceReorgEventData: ReorgEventData = {
+        depth: ancestorResult.depth,
+        epoch: computeEpochAtSlot(newHead.slot),
+        slot: newHead.slot,
+        newHeadBlock: newHead.blockRoot,
+        oldHeadBlock: oldHead.blockRoot,
+        newHeadState: newHead.stateRoot,
+        oldHeadState: oldHead.stateRoot,
+        executionOptimistic: isOptimisticBlock(newHead),
+      };
+
+      this.emitter.emit(routes.events.EventType.chainReorg, forkChoiceReorgEventData);
+      this.logger.verbose("Chain reorg", forkChoiceReorgEventData);
+
+      this.metrics?.forkChoice.reorg.inc();
+      this.metrics?.forkChoice.reorgDistance.observe(ancestorResult.depth);
+    }
+  }
+
+  private recomputeHeadAfterELInvalidResponse(): void {
+    // validateLatestHash only re-scores proto-array, the cached head is still the old one
+    const oldHead = this.forkChoice.getHead();
+    const newHead = this.recomputeForkChoiceHead(ForkchoiceCaller.executionInvalid);
+    if (newHead.blockRoot === oldHead.blockRoot && newHead.payloadStatus === oldHead.payloadStatus) {
+      return;
+    }
+    this.onHeadChanged(oldHead, newHead);
+  }
+
   /**
    * Emit `head` and `head_v2` when the fork choice head differs between two observations. Every caller that
    * can move the head, `updateAndGetHead()` and `updateTime()`, must capture the head before and pass both.

package/src/chain/forkChoice/index.ts

@@ -34,6 +34,17 @@ export type ForkChoiceOpts = RawForkChoiceOpts & {
 export enum ForkchoiceCaller {
   prepareNextSlot = "prepare_next_slot",
   importBlock = "import_block",
+  executionInvalid = "execution_invalid",
+}
+
+/**
+ * Where an execution engine INVALID verdict comes from. Only `blockSegment` verdicts are about the payload the engine
+ * just processed and keep the consensus failure semantics in fork choice, the others are applied leniently.
+ */
+export enum ExecutionInvalidSource {
+  forkchoiceUpdated = "forkchoice_updated",
+  newPayload = "new_payload",
+  blockSegment = "block_segment",
 }
 
 /**

package/src/chain/forkChoiceExecutionEngine.ts

@@ -0,0 +1,197 @@
+import {ExecutionStatus, IForkChoice, LVHInvalidResponse} from "@lodestar/fork-choice";
+import {ForkName, ForkPostFulu, ForkPreFulu, isForkPostFulu} from "@lodestar/params";
+import {RootHex, bellatrix} from "@lodestar/types";
+import {BlobAndProof} from "@lodestar/types/deneb";
+import {BlobAndProofV2} from "@lodestar/types/fulu";
+import {Logger} from "@lodestar/utils";
+import {ExecutionPayloadBodyV2} from "../execution/engine/types.js";
+import {DATA} from "../execution/engine/utils.js";
+import {
+  ClientVersion,
+  ExecutionEngineState,
+  ExecutionPayloadStatus,
+  ForkchoiceUpdatedResult,
+  IExecutionEngine,
+  PayloadAttributes,
+  PayloadId,
+  PayloadIdCache,
+  VersionedHashes,
+} from "../execution/index.js";
+import {Metrics} from "../metrics/index.js";
+import {ExecutionInvalidSource} from "./forkChoice/index.js";
+
+export type ForkChoiceExecutionEngineModules = {
+  forkChoice: IForkChoice;
+  /** Recompute and switch the chain head, fork choice is already updated when this runs */
+  recomputeHeadAfterELInvalidResponse: () => void;
+  logger: Logger;
+  metrics: Metrics | null;
+};
+
+/**
+ * The only handle on the execution engine. Payloads are imported optimistically, so every engine verdict that can
+ * change fork choice is applied here.
+ */
+export class ForkChoiceExecutionEngine {
+  private readonly forkChoice: IForkChoice;
+  private readonly recomputeHeadAfterELInvalidResponse: () => void;
+  private readonly logger: Logger;
+  private readonly metrics: Metrics | null;
+
+  constructor(
+    private readonly engine: IExecutionEngine,
+    modules: ForkChoiceExecutionEngineModules
+  ) {
+    this.forkChoice = modules.forkChoice;
+    this.recomputeHeadAfterELInvalidResponse = modules.recomputeHeadAfterELInvalidResponse;
+    this.logger = modules.logger;
+    this.metrics = modules.metrics;
+  }
+
+  get state(): ExecutionEngineState {
+    return this.engine.state;
+  }
+
+  get clientVersion(): ClientVersion | null | undefined {
+    return this.engine.clientVersion;
+  }
+
+  get payloadIdCache(): PayloadIdCache {
+    return this.engine.payloadIdCache;
+  }
+
+  notifyNewPayload(
+    ...args: Parameters<IExecutionEngine["notifyNewPayload"]>
+  ): ReturnType<IExecutionEngine["notifyNewPayload"]> {
+    return this.engine.notifyNewPayload(...args);
+  }
+
+  /**
+   * `headBlockRoot` is the root of the node whose payload hash is sent as `headBlockHash`, captured by the caller
+   * before the call: root and hash identify the exact fork choice node, gloas variant included.
+   *
+   * The verdict is applied to fork choice before returning. An INVALID verdict throws when preparing a payload so
+   * block production fails, otherwise it resolves to null.
+   */
+  async notifyForkchoiceUpdate(
+    fork: ForkName,
+    headBlockRoot: RootHex,
+    headBlockHash: RootHex,
+    safeBlockHash: RootHex,
+    finalizedBlockHash: RootHex,
+    payloadAttributes?: PayloadAttributes
+  ): Promise<PayloadId | null> {
+    const result = await this.engine.notifyForkchoiceUpdate(
+      fork,
+      headBlockHash,
+      safeBlockHash,
+      finalizedBlockHash,
+      payloadAttributes
+    );
+    this.applyForkchoiceUpdatedResult(headBlockRoot, headBlockHash, result);
+
+    if (result.payloadStatus.status === ExecutionPayloadStatus.INVALID) {
+      if (payloadAttributes) {
+        throw Error(`Invalid prepare payload, validationError=${result.payloadStatus.validationError ?? ""}`);
+      }
+      return null;
+    }
+    return result.payloadId;
+  }
+
+  getPayload(...args: Parameters<IExecutionEngine["getPayload"]>): ReturnType<IExecutionEngine["getPayload"]> {
+    return this.engine.getPayload(...args);
+  }
+
+  getInclusionList(): Promise<bellatrix.Transactions> {
+    return this.engine.getInclusionList();
+  }
+
+  getPayloadBodiesByHashV2(blockHashes: DATA[]): Promise<(ExecutionPayloadBodyV2 | null)[]> {
+    return this.engine.getPayloadBodiesByHashV2(blockHashes);
+  }
+
+  getBlobs(
+    fork: ForkPostFulu,
+    versionedHashes: VersionedHashes,
+    buffers?: Uint8Array[]
+  ): Promise<BlobAndProofV2[] | null>;
+  getBlobs(
+    fork: ForkPreFulu,
+    versionedHashes: VersionedHashes,
+    buffers?: Uint8Array[]
+  ): Promise<(BlobAndProof | null)[]>;
+  getBlobs(
+    fork: ForkName,
+    versionedHashes: VersionedHashes,
+    buffers?: Uint8Array[]
+  ): Promise<BlobAndProofV2[] | (BlobAndProof | null)[] | null> {
+    if (isForkPostFulu(fork)) {
+      return this.engine.getBlobs(fork, versionedHashes, buffers);
+    }
+    return this.engine.getBlobs(fork as ForkPreFulu, versionedHashes, buffers);
+  }
+
+  /**
+   * Apply an execution engine INVALID verdict to fork choice and move the chain head off the invalid chain
+   */
+  invalidateExecutionPayloads(lvh: LVHInvalidResponse, source: ExecutionInvalidSource): void {
+    const logCtx = {
+      source,
+      blockRoot: lvh.invalidateFromParentBlockRoot,
+      blockHash: lvh.invalidateFromParentBlockHash,
+      latestValidHash: lvh.latestValidExecHash ?? "null",
+    };
+    const applied = this.forkChoice.validateLatestHash(lvh, {strict: source === ExecutionInvalidSource.blockSegment});
+    if (!applied) {
+      this.logger.warn("Execution engine INVALID verdict not applied to fork choice", logCtx);
+      return;
+    }
+    this.metrics?.forkChoice.executionInvalidations.inc({source});
+    this.logger.warn("Invalidated execution payloads in fork choice", logCtx);
+
+    try {
+      this.recomputeHeadAfterELInvalidResponse();
+    } catch (e) {
+      this.logger.error("Error recomputing head after execution payload invalidation", logCtx, e as Error);
+    }
+  }
+
+  private applyForkchoiceUpdatedResult(
+    headBlockRoot: RootHex,
+    headBlockHash: RootHex,
+    result: ForkchoiceUpdatedResult
+  ): void {
+    const {status, latestValidHash, validationError} = result.payloadStatus;
+    const executionStatus = this.forkChoice.getBlockHexAndBlockHash(headBlockRoot, headBlockHash)?.executionStatus;
+    try {
+      if (status === ExecutionPayloadStatus.INVALID) {
+        if (executionStatus === ExecutionStatus.Invalid) {
+          return;
+        }
+        this.logger.error("Execution engine reported INVALID forkchoice head", {
+          headBlockRoot,
+          headBlockHash,
+          latestValidHash: latestValidHash ?? "null",
+          validationError: validationError ?? "",
+        });
+        this.invalidateExecutionPayloads(
+          {
+            executionStatus: ExecutionStatus.Invalid,
+            latestValidExecHash: latestValidHash,
+            invalidateFromParentBlockRoot: headBlockRoot,
+            invalidateFromParentBlockHash: headBlockHash,
+          },
+          ExecutionInvalidSource.forkchoiceUpdated
+        );
+      } else if (status === ExecutionPayloadStatus.VALID && executionStatus === ExecutionStatus.Syncing) {
+        this.forkChoice.validateLatestHash(
+          {executionStatus: ExecutionStatus.Valid, latestValidExecHash: headBlockHash, blockRoot: headBlockRoot},
+          {strict: false}
+        );
+      }
+    } catch (e) {
+      this.logger.error("Error applying forkchoice update result", {headBlockRoot, headBlockHash, status}, e as Error);
+    }
+  }
+}

package/src/chain/interface.ts

@@ -25,7 +25,7 @@ import {
 } from "@lodestar/types";
 import {Logger} from "@lodestar/utils";
 import {BuilderApiClient} from "../execution/builder/apiClient.js";
-import {IExecutionBuilder, IExecutionEngine} from "../execution/index.js";
+import {IExecutionBuilder} from "../execution/index.js";
 import {Metrics} from "../metrics/metrics.js";
 import {BufferPool} from "../util/bufferPool.js";
 import {IClock} from "../util/clock.js";
@@ -42,6 +42,7 @@ import {BuilderCircuitBreaker} from "./builderCircuitBreaker.js";
 import {ColumnReconstructionTracker} from "./ColumnReconstructionTracker.js";
 import {ChainEventEmitter} from "./emitter.js";
 import {ForkchoiceCaller} from "./forkChoice/index.js";
+import {ForkChoiceExecutionEngine} from "./forkChoiceExecutionEngine.js";
 import {GetBlobsTracker} from "./GetBlobsTracker.js";
 import {LightClientServer} from "./lightClient/index.js";
 import {AggregatedAttestationPool} from "./opPools/aggregatedAttestationPool.js";
@@ -98,7 +99,7 @@ export interface IBeaconChain {
   readonly genesisTime: UintNum64;
   readonly genesisValidatorsRoot: Root;
   earliestAvailableSlot: Slot;
-  readonly executionEngine: IExecutionEngine;
+  readonly executionEngine: ForkChoiceExecutionEngine;
   readonly executionBuilder?: IExecutionBuilder;
   readonly builderCircuitBreaker: BuilderCircuitBreaker;
   readonly builderApiClient: BuilderApiClient;

package/src/chain/produceBlock/produceBlockBody.ts

@@ -72,12 +72,13 @@ import {
 } from "@lodestar/utils";
 import {ZERO_HASH_HEX} from "../../constants/index.js";
 import {numToQuantity} from "../../execution/engine/utils.js";
-import {IExecutionBuilder, IExecutionEngine, PayloadAttributes, PayloadId} from "../../execution/index.js";
+import {IExecutionBuilder, PayloadAttributes, PayloadId} from "../../execution/index.js";
 import {getShufflingDependentRoot} from "../../util/dependentRoot.js";
 import {fromGraffitiBytes} from "../../util/graffiti.js";
 import {kzg} from "../../util/kzg.js";
 import {BeaconProposerCache} from "../beaconProposerCache.js";
 import type {BeaconChain} from "../chain.js";
+import {ForkChoiceExecutionEngine} from "../forkChoiceExecutionEngine.js";
 import {CommonBlockBody} from "../interface.js";
 import {InclusionListStore, ProposerPreferencesPool} from "../opPools/index.js";
 import {validateBlobsAndKzgCommitments, validateCellsAndKzgCommitments} from "./validateBlobsAndKzgCommitments.js";
@@ -742,7 +743,7 @@ export async function produceBlockBody<T extends BlockType>(
  */
 export async function prepareExecutionPayload(
   chain: {
-    executionEngine: IExecutionEngine;
+    executionEngine: ForkChoiceExecutionEngine;
     config: ChainForkConfig;
     forkChoice: IForkChoice;
     proposerPreferencesPool: ProposerPreferencesPool;
@@ -807,6 +808,7 @@ export async function prepareExecutionPayload(
 
     payloadId = await chain.executionEngine.notifyForkchoiceUpdate(
       fork,
+      toRootHex(parentBlockRoot),
       toRootHex(parentBlockHash),
       safeBlockHash,
       finalizedBlockHash,

package/src/chain/regen/interface.ts

@@ -52,7 +52,7 @@ export interface IStateRegenerator extends IStateRegeneratorInternal {
   onCheckpoint(finalizedEpoch: Epoch, justifiedEpoch: Epoch, headStateRoot: RootHex): void;
   processState(blockRootHex: RootHex, postState: IBeaconStateView): void;
   addCheckpointState(cp: phase0.Checkpoint, item: IBeaconStateView): void;
-  updateHeadState(newHead: ProtoBlock, maybeHeadState: IBeaconStateView): void;
+  updateHeadState(newHead: ProtoBlock, maybeHeadState?: IBeaconStateView): void;
   updatePreComputedCheckpoint(rootHex: RootHex, epoch: Epoch): number | null;
 }
 

package/src/chain/regen/queued.ts

@@ -154,18 +154,20 @@ export class QueuedStateRegenerator implements IStateRegenerator {
     this.checkpointStateCache.add(cp, item);
   }
 
-  updateHeadState(newHead: ProtoBlock, maybeHeadState: IBeaconStateView): void {
+  updateHeadState(newHead: ProtoBlock, maybeHeadState?: IBeaconStateView): void {
     const {stateRoot: newHeadStateRoot, blockRoot: newHeadBlockRoot, slot: newHeadSlot} = newHead;
-    const maybeHeadStateRoot = toRootHex(maybeHeadState.hashTreeRoot());
+    const maybeHeadStateRoot = maybeHeadState ? toRootHex(maybeHeadState.hashTreeRoot()) : undefined;
     const logCtx = {
       newHeadSlot,
       newHeadBlockRoot,
       newHeadStateRoot,
-      maybeHeadSlot: maybeHeadState.slot,
+      maybeHeadSlot: maybeHeadState?.slot,
       maybeHeadStateRoot,
     };
     const headState =
-      newHeadStateRoot === maybeHeadStateRoot ? maybeHeadState : this.blockStateCache.get(newHeadStateRoot);
+      maybeHeadState && newHeadStateRoot === maybeHeadStateRoot
+        ? maybeHeadState
+        : this.blockStateCache.get(newHeadStateRoot);
 
     if (headState) {
       this.blockStateCache.setHeadState(headState);

package/src/execution/engine/http.ts

@@ -22,9 +22,11 @@ import {
   ExecutePayloadResponse,
   ExecutionEngineState,
   ExecutionPayloadStatus,
+  ForkchoiceUpdatedResult,
   IExecutionEngine,
   PayloadAttributes,
   PayloadId,
+  PayloadStatusResult,
   VersionedHashes,
 } from "./interface.js";
 import {ErrorJsonRpcResponse, HttpRpcError, JsonRpcHttpClientEvent} from "./jsonRpcHttpClient.js";
@@ -32,7 +34,7 @@ import {PayloadIdCache} from "./payloadIdCache.js";
 import {EngineRestError, EngineRestResponseError, isRetryableEngineRestError} from "./restHttpClient.js";
 import {EngineCapabilities, RestEngineTransport} from "./restTransport.js";
 import {executionForkName} from "./sszTypes.js";
-import {IEngineTransport, PayloadStatusResult} from "./transport.js";
+import {IEngineTransport} from "./transport.js";
 import {ExecutionPayloadBodyV2, serializePayloadAttributes} from "./types.js";
 import {getExecutionEngineState} from "./utils.js";
 
@@ -342,15 +344,16 @@ export class ExecutionEngineHttp implements IExecutionEngine {
     safeBlockHash: RootHex,
     finalizedBlockHash: RootHex,
     payloadAttributes?: PayloadAttributes
-  ): Promise<PayloadId | null> {
-    const {
-      payloadStatus: {status, validationError},
-      payloadId,
-    } = await this.enqueue(() =>
+  ): Promise<ForkchoiceUpdatedResult> {
+    const result = await this.enqueue(() =>
       this.withTransport(fork, undefined, (transport) =>
         transport.forkchoiceUpdated(fork, headBlockHash, safeBlockHash, finalizedBlockHash, payloadAttributes)
       )
     );
+    const {
+      payloadStatus: {status},
+      payloadId,
+    } = result;
 
     this.updateEngineState(getExecutionEngineState({payloadStatus: status, oldState: this.state}));
     this.metrics?.engineNotifyForkchoiceUpdateResult.inc({result: status});
@@ -374,21 +377,17 @@ export class ExecutionEngineHttp implements IExecutionEngine {
           );
           void this.prunePayloadIdCache();
         }
-        return payloadId;
+        return result;
 
       case ExecutionPayloadStatus.SYNCING:
         // Throw error on syncing if requested to produce a block, else silently ignore
         if (payloadAttributes) {
           throw Error("Execution Layer Syncing");
         }
-        return null;
+        return result;
 
       case ExecutionPayloadStatus.INVALID:
-        throw Error(
-          `Invalid ${payloadAttributes ? "prepare payload" : "forkchoice request"}, validationError=${
-            validationError ?? ""
-          }`
-        );
+        return result;
 
       default:
         throw Error(`Unknown status ${status}`);

package/src/execution/engine/interface.ts

@@ -99,6 +99,19 @@ export type ExecutePayloadResponse =
       validationError: string;
     };
 
+export type PayloadStatusResult = {
+  status: ExecutionPayloadStatus;
+  latestValidHash: RootHex | null;
+  validationError: string | null;
+  /** PayloadStatusV2: whether a VALID payload satisfied the inclusion list constraints, null otherwise */
+  inclusionListSatisfied?: boolean | null;
+};
+
+export type ForkchoiceUpdatedResult = {
+  payloadStatus: PayloadStatusResult;
+  payloadId: PayloadId | null;
+};
+
 export type ForkChoiceUpdateStatus =
   | ExecutionPayloadStatus.VALID
   | ExecutionPayloadStatus.INVALID
@@ -166,7 +179,10 @@ export interface IExecutionEngine {
    * The call of the notify_forkchoice_updated function maps on the POS_FORKCHOICE_UPDATED event defined in the EIP-3675.
    * https://github.com/ethereum/consensus-specs/blob/v1.1.7/specs/merge/fork-choice.md#notify_forkchoice_updated
    *
-   * Should be called in response to fork-choice head and finalized events
+   * Should be called in response to fork-choice head and finalized events.
+   *
+   * An INVALID verdict is returned, not thrown: the caller feeds it back into fork choice together with the
+   * `latestValidHash`. Only SYNCING while building a payload is an error.
    */
   notifyForkchoiceUpdate(
     fork: ForkName,
@@ -174,7 +190,7 @@ export interface IExecutionEngine {
     safeBlockHash: RootHex,
     finalizedBlockHash: RootHex,
     payloadAttributes?: PayloadAttributes
-  ): Promise<PayloadId | null>;
+  ): Promise<ForkchoiceUpdatedResult>;
 
   /**
    * Given the payload_id, get_payload returns the most recent version of the execution payload that has been built

package/src/execution/engine/jsonRpcTransport.ts

@@ -3,9 +3,17 @@ import {ExecutionPayload, ExecutionRequests, Root, RootHex, bellatrix} from "@lo
 import {BlobAndProof} from "@lodestar/types/deneb";
 import {BlobAndProofV2} from "@lodestar/types/fulu";
 import {strip0xPrefix} from "@lodestar/utils";
-import {ClientCode, ClientVersion, PayloadAttributes, PayloadId, VersionedHashes} from "./interface.js";
+import {
+  ClientCode,
+  ClientVersion,
+  ForkchoiceUpdatedResult,
+  PayloadAttributes,
+  PayloadId,
+  PayloadStatusResult,
+  VersionedHashes,
+} from "./interface.js";
 import {IJsonRpcHttpClient, JsonRpcHttpClientEventEmitter, ReqOpts} from "./jsonRpcHttpClient.js";
-import {ForkchoiceUpdatedResult, GetPayloadResult, IEngineTransport, PayloadStatusResult} from "./transport.js";
+import {GetPayloadResult, IEngineTransport} from "./transport.js";
 import {
   BLOB_AND_PROOF_V2_RPC_BYTES,
   EngineApiRpcParamTypes,

package/src/execution/engine/restTransport.ts

@@ -19,8 +19,10 @@ import {
   ClientCode,
   ClientVersion,
   ExecutionPayloadStatus,
+  ForkchoiceUpdatedResult,
   PayloadAttributes,
   PayloadId,
+  PayloadStatusResult,
   VersionedHashes,
 } from "./interface.js";
 import {JsonRpcHttpClientEventEmitter, ReqOpts} from "./jsonRpcHttpClient.js";
@@ -57,7 +59,7 @@ import {
   PayloadStatusSsz,
   executionForkName,
 } from "./sszTypes.js";
-import {ForkchoiceUpdatedResult, GetPayloadResult, IEngineTransport, PayloadStatusResult} from "./transport.js";
+import {GetPayloadResult, IEngineTransport} from "./transport.js";
 import {EngineTransportMetrics} from "./transportMetrics.js";
 import {
   ExecutionPayloadBodyV2,

package/src/execution/engine/transport.ts

@@ -2,23 +2,17 @@ import {ForkName} from "@lodestar/params";
 import {BlobsBundle, ExecutionPayload, ExecutionRequests, Root, RootHex, Wei, bellatrix} from "@lodestar/types";
 import {BlobAndProof} from "@lodestar/types/deneb";
 import {BlobAndProofV2} from "@lodestar/types/fulu";
-import {ClientVersion, ExecutionPayloadStatus, PayloadAttributes, PayloadId, VersionedHashes} from "./interface.js";
+import {
+  ClientVersion,
+  ForkchoiceUpdatedResult,
+  PayloadAttributes,
+  PayloadId,
+  PayloadStatusResult,
+  VersionedHashes,
+} from "./interface.js";
 import {JsonRpcHttpClientEventEmitter} from "./jsonRpcHttpClient.js";
 import {ExecutionPayloadBodyV2} from "./types.js";
 
-export type PayloadStatusResult = {
-  status: ExecutionPayloadStatus;
-  latestValidHash: RootHex | null;
-  validationError: string | null;
-  /** PayloadStatusV2: whether a VALID payload satisfied the inclusion list constraints, null otherwise */
-  inclusionListSatisfied?: boolean | null;
-};
-
-export type ForkchoiceUpdatedResult = {
-  payloadStatus: PayloadStatusResult;
-  payloadId: PayloadId | null;
-};
-
 export type GetPayloadResult = {
   executionPayload: ExecutionPayload;
   executionPayloadValue: Wei;

package/src/index.ts

@@ -7,7 +7,7 @@ export {DbCPStateDatastore} from "./chain/stateCache/datastore/db.js";
 export {FileCPStateDatastore} from "./chain/stateCache/datastore/file.js";
 export {BeaconDb, type IBeaconDb} from "./db/index.js";
 // Export execution engine to make it usable by builder
-export {initializeExecutionEngine} from "./execution/index.js";
+export {ExecutionPayloadStatus, initializeExecutionEngine} from "./execution/index.js";
 // Export metrics utilities to de-duplicate validator metrics
 export {
   type HttpMetricsServer,