@lodestar/beacon-node 1.42.0-dev.4411584fd8 → 1.42.0-dev.70938e1eec

package/src/api/impl/beacon/blocks/index.ts

@@ -35,6 +35,7 @@ import {
 } from "@lodestar/types";
 import {fromHex, sleep, toHex, toRootHex} from "@lodestar/utils";
 import {BlockInputSource, isBlockInputBlobs, isBlockInputColumns} from "../../../../chain/blocks/blockInput/index.js";
+import {PayloadEnvelopeInputSource} from "../../../../chain/blocks/payloadEnvelopeInput/index.js";
 import {ImportBlockOpts} from "../../../../chain/blocks/types.js";
 import {verifyBlocksInEpoch} from "../../../../chain/blocks/verifyBlock.js";
 import {BeaconChain} from "../../../../chain/chain.js";
@@ -48,6 +49,7 @@ import {
   ProduceFullGloas,
 } from "../../../../chain/produceBlock/index.js";
 import {validateGossipBlock} from "../../../../chain/validation/block.js";
+import {validateApiExecutionPayloadEnvelope} from "../../../../chain/validation/executionPayloadEnvelope.js";
 import {OpSource} from "../../../../chain/validatorMonitor.js";
 import {
   computePreFuluKzgCommitmentsInclusionProof,
@@ -659,6 +661,8 @@ export function getBeaconBlockApi({
         throw new ApiError(400, `Envelope slot ${slot} does not match block slot ${block.slot}`);
       }
 
+      await validateApiExecutionPayloadEnvelope(chain, signedExecutionPayloadEnvelope);
+
       const isSelfBuild = envelope.builderIndex === BUILDER_INDEX_SELF_BUILD;
       let dataColumnSidecars: gloas.DataColumnSidecars = [];
 
@@ -676,6 +680,7 @@ export function getBeaconBlockApi({
         }
 
         if (cachedResult.cells && cachedResult.blobsBundle.commitments.length > 0) {
+          const timer = metrics?.peerDas.dataColumnSidecarComputationTime.startTimer();
           const cellsAndProofs = cachedResult.cells.map((rowCells, rowIndex) => ({
             cells: rowCells,
             proofs: cachedResult.blobsBundle.proofs.slice(
@@ -685,24 +690,42 @@ export function getBeaconBlockApi({
           }));
 
           dataColumnSidecars = getDataColumnSidecarsForGloas(slot, envelope.beaconBlockRoot, cellsAndProofs);
+          timer?.();
         }
       } else {
         // TODO GLOAS: will this api be used by builders or only for self-building?
       }
 
-      // TODO GLOAS: Verify execution payload envelope signature
-      // For self-builds, the proposer signs with their own validator key
-      // For external builders, verify using the builder's registered pubkey
-      // Use verify_execution_payload_envelope_signature(state, signed_envelope)
+      // If called near a slot boundary (e.g. late in slot N-1), hold briefly so gossip aligns with slot N.
+      const msToBlockSlot = computeTimeAtSlot(config, slot, chain.genesisTime) * 1000 - Date.now();
+      if (msToBlockSlot <= MAX_API_CLOCK_DISPARITY_MS && msToBlockSlot > 0) {
+        await sleep(msToBlockSlot);
+      }
 
-      // TODO GLOAS: Process execution payload via state transition
-      // Call process_execution_payload(state, signed_envelope, execution_engine)
+      // TODO GLOAS: if block and payload are submitted in parallel, payloadInput may not yet exist.
+      // A queuing mechanism is needed to handle this case. See https://github.com/ChainSafe/lodestar/issues/8915
+      const payloadInput = chain.seenPayloadEnvelopeInputCache.get(blockRootHex);
+      if (!payloadInput) {
+        throw new ApiError(404, `PayloadEnvelopeInput not found for block root ${blockRootHex}`);
+      }
 
-      // TODO GLOAS: Update fork choice with the execution payload
-      // Call on_execution_payload(store, signed_envelope) to update fork choice state
+      payloadInput.addPayloadEnvelope({
+        envelope: signedExecutionPayloadEnvelope,
+        source: PayloadEnvelopeInputSource.api,
+        seenTimestampSec,
+        peerIdStr: undefined,
+      });
 
-      // TODO GLOAS: Add envelope and data columns to block input via seenBlockInputCache
-      // and trigger block import (Gloas block import requires both beacon block and envelope)
+      if (dataColumnSidecars.length > 0) {
+        for (const columnSidecar of dataColumnSidecars) {
+          payloadInput.addColumn({
+            columnSidecar,
+            source: PayloadEnvelopeInputSource.api,
+            seenTimestampSec,
+            peerIdStr: undefined,
+          });
+        }
+      }
 
       const valLogMeta = {
         slot,
@@ -712,23 +735,19 @@ export function getBeaconBlockApi({
         dataColumns: dataColumnSidecars.length,
       };
 
-      // If called near a slot boundary (e.g. late in slot N-1), hold briefly so gossip aligns with slot N.
-      const msToBlockSlot = computeTimeAtSlot(config, slot, chain.genesisTime) * 1000 - Date.now();
-      if (msToBlockSlot <= MAX_API_CLOCK_DISPARITY_MS && msToBlockSlot > 0) {
-        await sleep(msToBlockSlot);
-      }
-
       const delaySec = seenTimestampSec - computeTimeAtSlot(config, slot, chain.genesisTime);
       metrics?.gossipExecutionPayloadEnvelope.elapsedTimeTillReceived.observe({source: OpSource.api}, delaySec);
+      chain.validatorMonitor?.registerExecutionPayloadEnvelope(OpSource.api, delaySec, signedExecutionPayloadEnvelope);
 
       chain.logger.info("Publishing execution payload envelope", valLogMeta);
 
-      // Publish envelope and data columns
       const publishPromises = [
         // Gossip the signed execution payload envelope first
         () => network.publishSignedExecutionPayloadEnvelope(signedExecutionPayloadEnvelope),
         // For self-builds, publish all data column sidecars
         ...dataColumnSidecars.map((dataColumnSidecar) => () => network.publishDataColumnSidecar(dataColumnSidecar)),
+        // Import execution payload. Signature already verified above
+        () => chain.processExecutionPayload(payloadInput, {validSignature: true}),
       ];
 
       const sentPeersArr = await promiseAllMaybeAsync<number | void>(publishPromises);

package/src/chain/blocks/blockInput/types.ts

@@ -1,5 +1,5 @@
 import {ForkName} from "@lodestar/params";
-import {ColumnIndex, RootHex, SignedBeaconBlock, Slot, deneb, fulu} from "@lodestar/types";
+import {ColumnIndex, DataColumnSidecars, RootHex, SignedBeaconBlock, Slot, deneb, fulu} from "@lodestar/types";
 import {VersionedHashes} from "../../../execution/index.js";
 
 export enum DAType {
@@ -107,9 +107,9 @@ export type MissingColumnMeta = {
 export interface IDataColumnsInput {
   readonly slot: Slot;
   readonly blockRootHex: string;
-  getCustodyColumns(): fulu.DataColumnSidecars;
+  getCustodyColumns(): DataColumnSidecars;
   hasComputedAllData(): boolean;
-  waitForComputedAllData(timeout: number, signal?: AbortSignal): Promise<fulu.DataColumnSidecars>;
+  waitForComputedAllData(timeout: number, signal?: AbortSignal): Promise<DataColumnSidecars>;
 }
 
 /**

package/src/chain/blocks/importBlock.ts

@@ -9,7 +9,14 @@ import {
   getSafeExecutionBlockHash,
   isGloasBlock,
 } from "@lodestar/fork-choice";
-import {ForkPostAltair, ForkPostElectra, ForkSeq, MAX_SEED_LOOKAHEAD, SLOTS_PER_EPOCH} from "@lodestar/params";
+import {
+  ForkPostAltair,
+  ForkPostElectra,
+  ForkPostGloas,
+  ForkSeq,
+  MAX_SEED_LOOKAHEAD,
+  SLOTS_PER_EPOCH,
+} from "@lodestar/params";
 import {
   CachedBeaconStateAltair,
   EpochCache,
@@ -21,7 +28,17 @@ import {
   isStartSlotOfEpoch,
   isStateValidatorsNodesPopulated,
 } from "@lodestar/state-transition";
-import {Attestation, BeaconBlock, altair, capella, electra, isGloasBeaconBlock, phase0, ssz} from "@lodestar/types";
+import {
+  Attestation,
+  BeaconBlock,
+  SignedBeaconBlock,
+  altair,
+  capella,
+  electra,
+  isGloasBeaconBlock,
+  phase0,
+  ssz,
+} from "@lodestar/types";
 import {isErrorAborted, toRootHex} from "@lodestar/utils";
 import {ZERO_HASH_HEX} from "../../constants/index.js";
 import {callInNextEventLoop} from "../../util/eventLoop.js";
@@ -123,6 +140,23 @@ export async function importBlock(
   // processState manages both block state and payload state variants together for memory/disk management
   this.regen.processBlockState(blockRootHex, postState);
 
+  // For Gloas blocks, create PayloadEnvelopeInput so it's available for later payload import
+  if (fork >= ForkSeq.gloas) {
+    this.seenPayloadEnvelopeInputCache.add({
+      blockRootHex,
+      block: block as SignedBeaconBlock<ForkPostGloas>,
+      sampledColumns: this.custodyConfig.sampledColumns,
+      custodyColumns: this.custodyConfig.custodyColumns,
+      timeCreatedSec: fullyVerifiedBlock.seenTimestampSec,
+    });
+    this.logger.debug("Created PayloadEnvelopeInput for block", {
+      slot: blockSlot,
+      root: blockRootHex,
+      source: source.source,
+      ...(opts.seenTimestampSec !== undefined ? {recvToImport: Date.now() / 1000 - opts.seenTimestampSec} : {}),
+    });
+  }
+
   this.metrics?.importBlock.bySource.inc({source: source.source});
   this.logger.verbose("Added block to forkchoice and state cache", {slot: blockSlot, root: blockRootHex});
 

package/src/chain/blocks/importExecutionPayload.ts

@@ -0,0 +1,241 @@
+import {routes} from "@lodestar/api";
+import {ForkName} from "@lodestar/params";
+import {
+  BeaconStateView,
+  CachedBeaconStateGloas,
+  getExecutionPayloadEnvelopeSignatureSet,
+} from "@lodestar/state-transition";
+import {processExecutionPayloadEnvelope} from "@lodestar/state-transition/block";
+import {byteArrayEquals, fromHex, toRootHex} from "@lodestar/utils";
+import {ExecutionPayloadStatus} from "../../execution/index.js";
+import {isQueueErrorAborted} from "../../util/queue/index.js";
+import {BeaconChain} from "../chain.js";
+import {RegenCaller} from "../regen/interface.js";
+import {PayloadEnvelopeInput} from "../seenCache/seenPayloadEnvelopeInput.js";
+import {ImportPayloadOpts} from "./types.js";
+
+const EVENTSTREAM_EMIT_RECENT_EXECUTION_PAYLOAD_SLOTS = 64;
+
+export enum PayloadErrorCode {
+  EXECUTION_ENGINE_INVALID = "PAYLOAD_ERROR_EXECUTION_ENGINE_INVALID",
+  EXECUTION_ENGINE_ERROR = "PAYLOAD_ERROR_EXECUTION_ENGINE_ERROR",
+  BLOCK_NOT_IN_FORK_CHOICE = "PAYLOAD_ERROR_BLOCK_NOT_IN_FORK_CHOICE",
+  STATE_TRANSITION_ERROR = "PAYLOAD_ERROR_STATE_TRANSITION_ERROR",
+  INVALID_SIGNATURE = "PAYLOAD_ERROR_INVALID_SIGNATURE",
+}
+
+export type PayloadErrorType =
+  | {
+      code: PayloadErrorCode.EXECUTION_ENGINE_INVALID;
+      execStatus: ExecutionPayloadStatus;
+      errorMessage: string;
+    }
+  | {
+      code: PayloadErrorCode.EXECUTION_ENGINE_ERROR;
+      execStatus: ExecutionPayloadStatus;
+      errorMessage: string;
+    }
+  | {
+      code: PayloadErrorCode.BLOCK_NOT_IN_FORK_CHOICE;
+      blockRootHex: string;
+    }
+  | {
+      code: PayloadErrorCode.STATE_TRANSITION_ERROR;
+      message: string;
+    }
+  | {
+      code: PayloadErrorCode.INVALID_SIGNATURE;
+    };
+
+export class PayloadError extends Error {
+  type: PayloadErrorType;
+
+  constructor(type: PayloadErrorType, message?: string) {
+    super(message ?? type.code);
+    this.type = type;
+  }
+}
+
+/**
+ * Import an execution payload envelope after all data is available.
+ *
+ * This function:
+ * 1. Gets the ProtoBlock from fork choice
+ * 2. Applies write-queue backpressure (waitForSpace) early, before verification
+ * 3. Regenerates the block state
+ * 4. Runs EL verification (notifyNewPayload) in parallel with signature verification and processExecutionPayloadEnvelope
+ * 5. Persists verified payload envelope to hot DB
+ * 6. Updates fork choice
+ * 7. Caches the post-execution payload state
+ * 8. Records metrics for column sources
+ *
+ */
+export async function importExecutionPayload(
+  this: BeaconChain,
+  payloadInput: PayloadEnvelopeInput,
+  opts: ImportPayloadOpts = {}
+): Promise<void> {
+  const envelope = payloadInput.getPayloadEnvelope();
+  const blockRootHex = payloadInput.blockRootHex;
+
+  // 1. Get ProtoBlock for parent root lookup
+  const protoBlock = this.forkChoice.getBlockHexDefaultStatus(blockRootHex);
+  if (!protoBlock) {
+    throw new PayloadError({
+      code: PayloadErrorCode.BLOCK_NOT_IN_FORK_CHOICE,
+      blockRootHex,
+    });
+  }
+
+  // 2. Apply backpressure from the write queue early, before doing verification work.
+  // The actual DB write is deferred until after verification succeeds.
+  await this.unfinalizedPayloadEnvelopeWrites.waitForSpace();
+
+  // 3. Get pre-state for processExecutionPayloadEnvelope
+  // We need the block state (post-block, pre-payload) to process the envelope
+  const blockState = (await this.regen.getBlockSlotState(
+    protoBlock,
+    protoBlock.slot,
+    {dontTransferCache: true},
+    RegenCaller.processBlock
+  )) as CachedBeaconStateGloas;
+
+  // 4. Run verification steps in parallel
+  // Note: No data availability check needed here - importExecutionPayload is only
+  // called when payloadInput.isComplete() is true, so all data is already available.
+  const [execResult, signatureValid, postPayloadResult] = await Promise.all([
+    this.executionEngine.notifyNewPayload(
+      ForkName.gloas,
+      envelope.message.payload,
+      payloadInput.getVersionedHashes(),
+      fromHex(protoBlock.parentRoot),
+      envelope.message.executionRequests
+    ),
+
+    opts.validSignature === true
+      ? Promise.resolve(true)
+      : (async () => {
+          const signatureSet = getExecutionPayloadEnvelopeSignatureSet(
+            this.config,
+            blockState.epochCtx.pubkeyCache,
+            new BeaconStateView(blockState),
+            envelope,
+            payloadInput.proposerIndex
+          );
+          return this.bls.verifySignatureSets([signatureSet]);
+        })(),
+
+    // Signature verified separately above.
+    // State root check is done separately below with better error typing (matching block pipeline pattern).
+    (async () => {
+      try {
+        return {
+          postPayloadState: processExecutionPayloadEnvelope(blockState, envelope, {
+            verifySignature: false,
+            verifyStateRoot: false,
+          }),
+        };
+      } catch (e) {
+        throw new PayloadError(
+          {
+            code: PayloadErrorCode.STATE_TRANSITION_ERROR,
+            message: (e as Error).message,
+          },
+          `State transition error: ${(e as Error).message}`
+        );
+      }
+    })(),
+  ]);
+
+  // 4b. Check signature verification result
+  if (!signatureValid) {
+    throw new PayloadError({code: PayloadErrorCode.INVALID_SIGNATURE});
+  }
+
+  // 5. Handle EL response
+  switch (execResult.status) {
+    case ExecutionPayloadStatus.VALID:
+      break;
+
+    case ExecutionPayloadStatus.INVALID:
+      throw new PayloadError({
+        code: PayloadErrorCode.EXECUTION_ENGINE_INVALID,
+        execStatus: execResult.status,
+        errorMessage: execResult.validationError ?? "",
+      });
+
+    case ExecutionPayloadStatus.ACCEPTED:
+    case ExecutionPayloadStatus.SYNCING:
+      // TODO GLOAS: Handle optimistic import for payload - for now treat as error
+      throw new PayloadError({
+        code: PayloadErrorCode.EXECUTION_ENGINE_ERROR,
+        execStatus: execResult.status,
+        errorMessage: execResult.validationError ?? "EL syncing, payload not yet validated",
+      });
+
+    case ExecutionPayloadStatus.INVALID_BLOCK_HASH:
+    case ExecutionPayloadStatus.ELERROR:
+    case ExecutionPayloadStatus.UNAVAILABLE:
+      throw new PayloadError({
+        code: PayloadErrorCode.EXECUTION_ENGINE_ERROR,
+        execStatus: execResult.status,
+        errorMessage: execResult.validationError ?? "",
+      });
+  }
+
+  // 5b. Verify envelope state root matches post-state
+  const postPayloadState = postPayloadResult.postPayloadState;
+  const postPayloadStateRoot = postPayloadState.hashTreeRoot();
+  if (!byteArrayEquals(envelope.message.stateRoot, postPayloadStateRoot)) {
+    throw new PayloadError({
+      code: PayloadErrorCode.STATE_TRANSITION_ERROR,
+      message: `Envelope state root mismatch expected=${toRootHex(envelope.message.stateRoot)} actual=${toRootHex(postPayloadStateRoot)}`,
+    });
+  }
+
+  // 5c. Persist payload envelope to hot DB (performed asynchronously to avoid blocking)
+  this.unfinalizedPayloadEnvelopeWrites.push(payloadInput).catch((e) => {
+    if (!isQueueErrorAborted(e)) {
+      this.logger.error(
+        "Error pushing payload envelope to unfinalized write queue",
+        {slot: payloadInput.slot, root: blockRootHex},
+        e as Error
+      );
+    }
+  });
+
+  // 6. Update fork choice
+  this.forkChoice.onExecutionPayload(
+    blockRootHex,
+    payloadInput.getBlockHashHex(),
+    envelope.message.payload.blockNumber,
+    toRootHex(postPayloadStateRoot)
+  );
+
+  // 7. Cache payload state
+  // TODO GLOAS: Enable when PR #8868 merged (adds processPayloadState)
+  // this.regen.processPayloadState(postPayloadState);
+  // if epoch boundary also call
+  // this.regen.addCheckpointState(cp, checkpointState, true);
+
+  // 8. Record metrics for payload envelope and column sources
+  this.metrics?.importPayload.bySource.inc({source: payloadInput.getPayloadEnvelopeSource().source});
+  for (const {source} of payloadInput.getSampledColumnsWithSource()) {
+    this.metrics?.importPayload.columnsBySource.inc({source});
+  }
+
+  this.logger.verbose("Execution payload imported", {
+    slot: payloadInput.slot,
+    root: blockRootHex,
+    blockHash: payloadInput.getBlockHashHex(),
+  });
+
+  // 9. Emit event after payload is fully verified and imported to fork choice, only for recent enough payloads
+  const currentSlot = this.clock.currentSlot;
+  if (currentSlot - payloadInput.slot < EVENTSTREAM_EMIT_RECENT_EXECUTION_PAYLOAD_SLOTS) {
+    this.emitter.emit(routes.events.EventType.executionPayloadAvailable, {
+      slot: payloadInput.slot,
+      blockRoot: blockRootHex,
+    });
+  }
+}

package/src/chain/blocks/payloadEnvelopeInput/index.ts

@@ -0,0 +1,2 @@
+export * from "./payloadEnvelopeInput.js";
+export * from "./types.js";