@lodestar/beacon-node 1.51.0-dev.aa1ecb7c18 → 1.51.0-dev.ab8f3f6381

package/src/chain/opPools/singleAttestationPool.ts

@@ -0,0 +1,287 @@
+import {ATTESTATION_SUBNET_COUNT, ForkPostElectra} from "@lodestar/params";
+import {EffectiveBalanceIncrements} from "@lodestar/state-transition";
+import {BLSSignature, CommitteeIndex, RootHex, SingleAttestation, Slot, ValidatorIndex, phase0} from "@lodestar/types";
+import {Metrics} from "../../metrics/metrics.js";
+import {ProposerTracker} from "../proposerTracker.js";
+import {InsertOutcome} from "./types.js";
+
+type DataRootHex = string;
+
+/** Position of a validator in its committee, i.e. its bit in `aggregationBits` */
+type ValidatorCommitteeIndex = number;
+
+/** `data` and `committeeIndex` are shared per data root and committee, only keep what packing reads */
+type StoredSingle = {attesterIndex: ValidatorIndex; signature: BLSSignature};
+
+type CommitteeSingles = {
+  /** Bit length of this committee's `aggregationBits` */
+  committeeSize: number;
+  singles: Map<ValidatorCommitteeIndex, StoredSingle>;
+};
+
+type DataRootSingles = {
+  /** Same for every single attestation under this data root */
+  data: phase0.AttestationData;
+  byCommittee: Map<CommitteeIndex, CommitteeSingles>;
+};
+
+/** Single attestations of not yet included committee members, signatures are not aggregated yet */
+export type SinglesForCommittee = {
+  committeeSize: number;
+  singles: {validatorCommitteeIndex: ValidatorCommitteeIndex; single: StoredSingle}[];
+  newSeenEffectiveBalance: number;
+  newSeenAttesters: number;
+};
+
+/** Attesters of an attestation included in a block, `attestingIndices` is not sorted */
+export type IncludedAttesters = {slot: Slot; attDataRootHex: DataRootHex; attestingIndices: ValidatorIndex[]};
+
+/**
+ * Backstop only, single attestations included in a canonical block are deleted (see `onHead`) so the real retention is
+ * far lower. Sized for all subnets during the default 8 slots before a proposal (`slotsToSubscribeBeforeProposalDuty`)
+ * with no block at all and up to 1024 attesters per committee, i.e. ~2M active validators. Earlier slots of the
+ * collected window only add the few subnets the node subscribes to anyway. Beyond it, newer singles are dropped
+ */
+const MAX_SINGLE_ATTESTATIONS_RETAINED = 8 * ATTESTATION_SUBNET_COUNT * 1024;
+
+/**
+ * Single attestations to be packed into a block produced by this node, for votes that no aggregate covers.
+ * Callers only add to it for vote slots of an upcoming local proposal, see `ProposerTracker.shouldCollect()`.
+ * They are kept even if an aggregate covers them since proposers may not include that aggregate, until a canonical
+ * block includes them.
+ */
+export class SingleAttestationPool {
+  private readonly singlesByCommitteeByDataRootBySlot = new Map<Slot, Map<DataRootHex, DataRootSingles>>();
+  private size = 0;
+  /** Attesters included by the head block, deleted once a child of it becomes head */
+  private pendingPrune: {blockRoot: RootHex; included: IncludedAttesters[]} | null = null;
+
+  constructor(metrics: Metrics | null = null) {
+    metrics?.opPool.singleAttestationPool.size.addCollect(() =>
+      metrics.opPool.singleAttestationPool.size.set(this.size)
+    );
+  }
+
+  /**
+   * @param validatorCommitteeIndex position of the attester in its committee, computed by gossip validation
+   */
+  add(
+    attestation: SingleAttestation<ForkPostElectra>,
+    attDataRootHex: DataRootHex,
+    validatorCommitteeIndex: ValidatorCommitteeIndex,
+    committeeSize: number
+  ): InsertOutcome {
+    if (this.size >= MAX_SINGLE_ATTESTATIONS_RETAINED) {
+      return InsertOutcome.ReachLimit;
+    }
+
+    const {data, committeeIndex, attesterIndex, signature} = attestation;
+    let singlesByCommitteeByDataRoot = this.singlesByCommitteeByDataRootBySlot.get(data.slot);
+    if (singlesByCommitteeByDataRoot === undefined) {
+      singlesByCommitteeByDataRoot = new Map();
+      this.singlesByCommitteeByDataRootBySlot.set(data.slot, singlesByCommitteeByDataRoot);
+    }
+
+    let dataRootSingles = singlesByCommitteeByDataRoot.get(attDataRootHex);
+    if (dataRootSingles === undefined) {
+      dataRootSingles = {data, byCommittee: new Map()};
+      singlesByCommitteeByDataRoot.set(attDataRootHex, dataRootSingles);
+    }
+
+    let committee = dataRootSingles.byCommittee.get(committeeIndex);
+    if (committee === undefined) {
+      committee = {committeeSize, singles: new Map()};
+      dataRootSingles.byCommittee.set(committeeIndex, committee);
+    }
+
+    if (committee.singles.has(validatorCommitteeIndex)) {
+      return InsertOutcome.AlreadyKnown;
+    }
+
+    committee.singles.set(validatorCommitteeIndex, {attesterIndex, signature});
+    this.size++;
+    return InsertOutcome.NewData;
+  }
+
+  /**
+   * Delete single attestations included by the parent of the new head. Not the ones of the head itself: a proposer
+   * boost reorg of a weak head must keep them, once a child of it is the head that reorg can no longer happen.
+   * @param included attesters of the attestations included in the new head block
+   * @returns number of deleted single attestations
+   */
+  onHead(blockRoot: RootHex, parentRoot: RootHex, included: IncludedAttesters[]): number {
+    if (this.singlesByCommitteeByDataRootBySlot.size === 0) {
+      this.pendingPrune = null;
+      return 0;
+    }
+
+    // a reorg or a parent imported while the pool was empty drops the pending block without deleting
+    const deleted = this.pendingPrune?.blockRoot === parentRoot ? this.deleteIncluded(this.pendingPrune.included) : 0;
+    this.pendingPrune = {blockRoot, included};
+    return deleted;
+  }
+
+  /** Drop vote slots that no upcoming local proposal can include */
+  prune(proposerTracker: ProposerTracker): void {
+    for (const [slot, singlesByCommitteeByDataRoot] of this.singlesByCommitteeByDataRootBySlot) {
+      if (proposerTracker.shouldCollect(slot)) {
+        continue;
+      }
+
+      for (const dataRootSingles of singlesByCommitteeByDataRoot.values()) {
+        for (const committee of dataRootSingles.byCommittee.values()) {
+          this.size -= committee.singles.size;
+        }
+      }
+      this.singlesByCommitteeByDataRootBySlot.delete(slot);
+    }
+
+    if (this.singlesByCommitteeByDataRootBySlot.size === 0) {
+      this.pendingPrune = null;
+    }
+  }
+
+  isEmpty(): boolean {
+    return this.singlesByCommitteeByDataRootBySlot.size === 0;
+  }
+
+  getStoredSlots(): Slot[] {
+    return Array.from(this.singlesByCommitteeByDataRootBySlot.keys());
+  }
+
+  getDataRoots(slot: Slot): Map<DataRootHex, phase0.AttestationData> {
+    const dataRoots = new Map<DataRootHex, phase0.AttestationData>();
+    for (const [attDataRootHex, dataRootSingles] of this.singlesByCommitteeByDataRootBySlot.get(slot) ?? []) {
+      dataRoots.set(attDataRootHex, dataRootSingles.data);
+    }
+    return dataRoots;
+  }
+
+  getCommitteeIndices(slot: Slot, attDataRootHex: DataRootHex): CommitteeIndex[] {
+    return Array.from(this.singlesByCommitteeByDataRootBySlot.get(slot)?.get(attDataRootHex)?.byCommittee.keys() ?? []);
+  }
+
+  /**
+   * Single attestations of a committee whose attesters are in `notSeenCommitteeMembers`, i.e. not on chain and not
+   * covered by the aggregates picked for the block. `notSeenCommitteeMembers` is only read.
+   * Returns at most `maxCount` single attestations with the highest effective balances, without removing them from the
+   * pool.
+   */
+  getUncovered(
+    slot: Slot,
+    attDataRootHex: DataRootHex,
+    committeeIndex: CommitteeIndex,
+    notSeenCommitteeMembers: ReadonlySet<ValidatorCommitteeIndex>,
+    effectiveBalanceIncrements: EffectiveBalanceIncrements,
+    maxCount: number
+  ): SinglesForCommittee | null {
+    const committee = this.singlesByCommitteeByDataRootBySlot
+      .get(slot)
+      ?.get(attDataRootHex)
+      ?.byCommittee.get(committeeIndex);
+    if (committee === undefined) {
+      return null;
+    }
+
+    const singles: SinglesForCommittee["singles"] = [];
+    // walk the smaller side, notSeenCommitteeMembers is usually tiny but close to the committee size if no aggregate
+    if (notSeenCommitteeMembers.size <= committee.singles.size) {
+      for (const validatorCommitteeIndex of notSeenCommitteeMembers) {
+        const single = committee.singles.get(validatorCommitteeIndex);
+        if (single !== undefined) {
+          singles.push({validatorCommitteeIndex, single});
+        }
+      }
+    } else {
+      for (const [validatorCommitteeIndex, single] of committee.singles) {
+        if (notSeenCommitteeMembers.has(validatorCommitteeIndex)) {
+          singles.push({validatorCommitteeIndex, single});
+        }
+      }
+    }
+    if (singles.length > maxCount) {
+      singles.sort(
+        (a, b) =>
+          effectiveBalanceIncrements[b.single.attesterIndex] - effectiveBalanceIncrements[a.single.attesterIndex]
+      );
+      singles.length = maxCount;
+    }
+    if (singles.length === 0) {
+      return null;
+    }
+
+    let newSeenEffectiveBalance = 0;
+    for (const {single} of singles) {
+      newSeenEffectiveBalance += effectiveBalanceIncrements[single.attesterIndex];
+    }
+    return {committeeSize: committee.committeeSize, singles, newSeenEffectiveBalance, newSeenAttesters: singles.length};
+  }
+
+  /**
+   * Delete single attestations whose votes are already on chain, they add nothing to a block built on top of it.
+   * @param includedAttestations one entry per attestation in the body of a canonical block (the parent of the new
+   * head): the attestation slot and data root, and the validators it covers. A single attestation is included if its
+   * attester is in `attestingIndices` of an entry with the same slot and data root.
+   * @returns number of deleted single attestations
+   */
+  private deleteIncluded(includedAttestations: IncludedAttesters[]): number {
+    // a block may include several attestations of the same data, merge their attesters per data root
+    const includedAttestersByDataRootBySlot = new Map<Slot, Map<DataRootHex, Set<ValidatorIndex>>>();
+    for (const {slot, attDataRootHex, attestingIndices} of includedAttestations) {
+      if (this.singlesByCommitteeByDataRootBySlot.get(slot)?.has(attDataRootHex) !== true) {
+        continue;
+      }
+      let includedAttestersByDataRoot = includedAttestersByDataRootBySlot.get(slot);
+      if (includedAttestersByDataRoot === undefined) {
+        includedAttestersByDataRoot = new Map();
+        includedAttestersByDataRootBySlot.set(slot, includedAttestersByDataRoot);
+      }
+      let includedAttesters = includedAttestersByDataRoot.get(attDataRootHex);
+      if (includedAttesters === undefined) {
+        includedAttesters = new Set();
+        includedAttestersByDataRoot.set(attDataRootHex, includedAttesters);
+      }
+      for (const attesterIndex of attestingIndices) {
+        includedAttesters.add(attesterIndex);
+      }
+    }
+
+    let deleted = 0;
+    for (const [slot, includedAttestersByDataRoot] of includedAttestersByDataRootBySlot) {
+      const singlesByCommitteeByDataRoot = this.singlesByCommitteeByDataRootBySlot.get(slot);
+      if (singlesByCommitteeByDataRoot === undefined) {
+        continue;
+      }
+
+      for (const [attDataRootHex, includedAttesters] of includedAttestersByDataRoot) {
+        const dataRootSingles = singlesByCommitteeByDataRoot.get(attDataRootHex);
+        if (dataRootSingles === undefined) {
+          continue;
+        }
+
+        for (const [committeeIndex, committee] of dataRootSingles.byCommittee) {
+          for (const [validatorCommitteeIndex, {attesterIndex}] of committee.singles) {
+            if (includedAttesters.has(attesterIndex)) {
+              committee.singles.delete(validatorCommitteeIndex);
+              deleted++;
+            }
+          }
+          if (committee.singles.size === 0) {
+            dataRootSingles.byCommittee.delete(committeeIndex);
+          }
+        }
+
+        if (dataRootSingles.byCommittee.size === 0) {
+          singlesByCommitteeByDataRoot.delete(attDataRootHex);
+        }
+      }
+
+      if (singlesByCommitteeByDataRoot.size === 0) {
+        this.singlesByCommitteeByDataRootBySlot.delete(slot);
+      }
+    }
+
+    this.size -= deleted;
+    return deleted;
+  }
+}

package/src/chain/options.ts

@@ -90,6 +90,11 @@ export type PoolOpts = {
    * Only preaggregate attestation/sync committee message since clockSlot - preaggregateSlotDistance
    */
   preaggregateSlotDistance?: number;
+  /**
+   * Dev only: collect single attestations of every vote slot a block at the clock slot can include regardless of
+   * proposal duties, so that any produced block can pack them. Combine with `subscribeAllSubnets`
+   */
+  singleAttestationIgnoreProposalDuty?: boolean;
 };
 
 export type SeenCacheOpts = {

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,
@@ -1125,11 +1127,13 @@ export async function produceCommonBlockBody<T extends BlockType>(
     this.opPool.getSlashingsAndExits(currentState, blockType, this.metrics);
 
   const endAttestations = stepsMetrics?.startTimer();
+  // TODO: extract to a separate BeaconChain method to coordinate the 2 op-pools
   const attestations = this.aggregatedAttestationPool.getAttestationsForBlock(
     fork,
     this.forkChoice,
     this.shufflingCache,
-    currentState
+    currentState,
+    this.singleAttestationPool
   );
   endAttestations?.({
     step: BlockProductionStep.attestations,

package/src/chain/proposerTracker.ts

@@ -0,0 +1,94 @@
+import {MIN_ATTESTATION_INCLUSION_DELAY} from "@lodestar/params";
+import {computeEpochAtSlot, computeStartSlotAtEpoch} from "@lodestar/state-transition";
+import {Slot} from "@lodestar/types";
+import {Metrics} from "../metrics/metrics.js";
+
+/**
+ * Track upcoming block proposals of validators connected to this node, and the vote slots those blocks can include,
+ * to only then insert single attestations into the SingleAttestationPool
+ */
+export class ProposerTracker {
+  /** Local proposal slots that have not passed yet */
+  private readonly proposalSlots = new Set<Slot>();
+  /** Vote slots of tracked proposals, see `getFirstIncludableVoteSlot` */
+  private readonly collectableSlots = new Set<Slot>();
+  private clockSlot = 0;
+
+  /**
+   * @param ignoreProposalDuty dev only, collect every vote slot a block at the clock slot can include regardless of
+   * local proposals
+   */
+  constructor(
+    private readonly ignoreProposalDuty = false,
+    metrics: Metrics | null = null
+  ) {
+    metrics?.proposerTracker.proposalSlots.addCollect(() =>
+      metrics.proposerTracker.proposalSlots.set(this.proposalSlots.size)
+    );
+    metrics?.proposerTracker.collectableSlot.addCollect(() =>
+      metrics.proposerTracker.collectableSlot.set(this.shouldCollect(this.clockSlot) ? 1 : 0)
+    );
+  }
+
+  /**
+   * Idempotent, a known proposal is ignored
+   * @returns true if the proposal was not tracked before
+   */
+  addProposal(proposalSlot: Slot): boolean {
+    if (this.proposalSlots.has(proposalSlot)) {
+      return false;
+    }
+
+    this.proposalSlots.add(proposalSlot);
+    for (
+      let voteSlot = getFirstIncludableVoteSlot(proposalSlot);
+      voteSlot <= proposalSlot - MIN_ATTESTATION_INCLUSION_DELAY;
+      voteSlot++
+    ) {
+      this.collectableSlots.add(voteSlot);
+    }
+    return true;
+  }
+
+  shouldCollect(attestationSlot: Slot): boolean {
+    if (this.ignoreProposalDuty) {
+      // to test block production without proposal duties
+      return attestationSlot >= getFirstIncludableVoteSlot(this.clockSlot);
+    }
+    return this.collectableSlots.has(attestationSlot);
+  }
+
+  /**
+   * Drop proposals that have passed. A proposal is kept during its own slot so that its single attestations stay
+   * available until the block is produced. Vote slots are dropped once no remaining proposal can include them.
+   */
+  prune(clockSlot: Slot): void {
+    this.clockSlot = clockSlot;
+    for (const proposalSlot of this.proposalSlots) {
+      if (proposalSlot < clockSlot) {
+        this.proposalSlots.delete(proposalSlot);
+      }
+    }
+
+    if (this.proposalSlots.size === 0) {
+      this.collectableSlots.clear();
+      return;
+    }
+
+    // Each remaining proposal covers its own vote slots, so a vote slot below the lowest one is covered by none
+    const lowestCollectableVoteSlot = getFirstIncludableVoteSlot(Math.min(...this.proposalSlots));
+    for (const voteSlot of this.collectableSlots) {
+      if (voteSlot < lowestCollectableVoteSlot) {
+        this.collectableSlots.delete(voteSlot);
+      }
+    }
+  }
+}
+
+/**
+ * Since deneb (EIP-7045) a block includes attestations of its current and previous epoch, so the first vote slot it can
+ * include is the start of the previous epoch, 32 to 63 slots before it on mainnet
+ */
+function getFirstIncludableVoteSlot(blockSlot: Slot): Slot {
+  return computeStartSlotAtEpoch(Math.max(computeEpochAtSlot(blockSlot) - 1, 0));
+}

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,