@chainsafe/lodestar 1.50.0-dev.1f38fe79fb → 1.50.0-dev.26076bcd3f

package/src/cmds/beacon/handler.ts

@@ -27,6 +27,7 @@ import {initBeaconState} from "./initBeaconState.js";
 import {initPrivateKeyAndEnr} from "./initPeerIdAndEnr.js";
 import {BeaconArgs} from "./options.js";
 import {getBeaconPaths} from "./paths.js";
+import {savePubkeysFile} from "./pubkeysFile.js";
 
 const DEFAULT_RETENTION_SSZ_OBJECTS_HOURS = 15 * 24;
 const HOURS_TO_MS = 3600 * 1000;
@@ -78,7 +79,8 @@ export async function beaconHandler(args: BeaconArgs & GlobalArgs): Promise<void
       anchorState,
       config: beaconConfig,
       isFinalized,
-    } = await initBeaconState(args, beaconPaths.dataDir, config, db, logger);
+      earliestAvailableSlot,
+    } = await initBeaconState(args, beaconPaths.dataDir, beaconPaths.pubkeysFile, config, db, logger);
 
     const node = await BeaconNode.init({
       opts: options,
@@ -93,6 +95,7 @@ export async function beaconHandler(args: BeaconArgs & GlobalArgs): Promise<void
       peerStoreDir: beaconPaths.peerStoreDir,
       anchorState,
       isAnchorStateFinalized: isFinalized,
+      earliestAvailableSlot,
     });
 
     // dev debug option to have access to the BN instance
@@ -139,21 +142,21 @@ export async function beaconHandler(args: BeaconArgs & GlobalArgs): Promise<void
     abortController.signal.addEventListener(
       "abort",
       async () => {
+        let exitCode = 0;
         try {
           await node.close();
           logger.debug("Beacon node closed");
-          // Explicitly exit until active handles issue is resolved
-          // See https://github.com/ChainSafe/lodestar/issues/5642
-          process.exit(0);
         } catch (e) {
           // If we start from unfinalized state, we don't have checkpoint state so there is this error
           // "No state in cache for finalized checkpoint state epoch"
           logger.warn("Error closing beacon node", {}, e as Error);
           // Make sure db is always closed gracefully
           await db.close();
-          // Must explicitly exit process due to potential active handles
-          process.exit(1);
+          exitCode = 1;
         }
+        savePubkeysFile(pubkeyCache, beaconPaths.pubkeysFile, logger);
+        // Explicitly exit process due to potential active handles
+        process.exit(exitCode);
       },
       {once: true}
     );
@@ -229,6 +232,12 @@ export async function beaconHandlerInit(args: BeaconArgs & GlobalArgs) {
   // Render final options
   const options = beaconNodeOptions.getWithDefaults();
 
+  if (options.chain.nativeStateTransition && config.GLOAS_FORK_EPOCH !== Infinity) {
+    throw Error(
+      `--chain.nativeStateTransition does not support Gloas, which is scheduled at epoch ${config.GLOAS_FORK_EPOCH}`
+    );
+  }
+
   return {config, options, beaconPaths, network, version, commit, privateKey, logger};
 }
 

package/src/cmds/beacon/initBeaconState.ts

@@ -10,9 +10,11 @@ import {
   isWithinWeakSubjectivityPeriodFromSummary,
   readBeaconStateBytesMetadata,
 } from "@lodestar/state-transition";
+import {Slot} from "@lodestar/types";
 import {Logger, formatBytes} from "@lodestar/utils";
 import {GlobalArgs} from "../../options/globalOptions.js";
 import {BeaconArgs} from "./options.js";
+import {loadPubkeysFile} from "./pubkeysFile.js";
 import {StateInitializationError, StateInitializationErrorCode} from "./stateInitialization/errors.js";
 import {prepareGenesisInitialization} from "./stateInitialization/genesisState.js";
 import {
@@ -26,21 +28,27 @@ import {
   StatePreparationContext,
 } from "./stateInitialization/types.js";
 
-type InitBeaconStateResult = {anchorState: IBeaconStateView; config: BeaconConfig; isFinalized: boolean};
+type InitBeaconStateResult = {
+  anchorState: IBeaconStateView;
+  config: BeaconConfig;
+  isFinalized: boolean;
+  earliestAvailableSlot: Slot;
+};
 
 /**
  * Select serialized anchor bytes before constructing the state used for validation, persistence, and return.
- * Populates the global `pubkeyCache` with the anchor state's validators.
+ * Populates the global `pubkeyCache` with the anchor state's validators, reusing `pubkeysFile` if it matches.
  */
 export async function initBeaconState(
   args: BeaconArgs & GlobalArgs,
   dataDir: string,
+  pubkeysFile: string,
   chainForkConfig: ChainForkConfig,
   db: IBeaconDb,
   logger: Logger
 ): Promise<InitBeaconStateResult> {
   const options: StateInitializationOptions = args;
-  const useNative = options["chain.nativeStateView"] ?? false;
+  const nativeStateTransition = options["chain.nativeStateTransition"] ?? false;
   if (
     options.forceCheckpointSync &&
     !(options.checkpointState || options.checkpointSyncUrl || options.unsafeCheckpointState)
@@ -66,7 +74,12 @@ export async function initBeaconState(
         options.lastPersistedCheckpointState
     );
     if (!options.forceCheckpointSync && (!hasCheckpointSource || archived.isWithinWeakSubjectivityPeriod)) {
-      return executeStateInitialization(prepareArchivedStateInitialization(archived, context), useNative);
+      return executeStateInitialization(
+        prepareArchivedStateInitialization(archived, context),
+        nativeStateTransition,
+        pubkeysFile,
+        logger
+      );
     }
   }
   let stateInit = await prepareCheckpointSourceInitialization(options, archived, context);
@@ -77,7 +90,7 @@ export async function initBeaconState(
         ? prepareArchivedStateInitialization(archived, context)
         : await prepareGenesisInitialization(options, context);
   }
-  return executeStateInitialization(stateInit, useNative);
+  return executeStateInitialization(stateInit, nativeStateTransition, pubkeysFile, logger);
 }
 
 /**
@@ -122,7 +135,9 @@ async function readLatestArchivedStateBytes({
  */
 async function executeStateInitialization(
   stateInit: StateInitialization,
-  useNative: boolean
+  nativeStateTransition: boolean,
+  pubkeysFile: string,
+  logger: Logger
 ): Promise<InitBeaconStateResult> {
   const {config, stateBytes} = stateInit;
   const validatorCount = getValidatorCountFromStateBytes(config, stateBytes);
@@ -137,10 +152,14 @@ async function executeStateInitialization(
   // by its native lock; if this headroom is exceeded, it grows by the same fixed step.
   // The view syncs pubkeys during construction, so capacity must be reserved first.
   const headroomEpochs = (90 * 24 * 60 * 60) / (config.SECONDS_PER_SLOT * SLOTS_PER_EPOCH);
-  pubkeyCache.ensureCapacity(validatorCount + MAX_PENDING_DEPOSITS_PER_EPOCH * Math.ceil(headroomEpochs));
-  const anchorState = createBeaconStateView({useNative, config, stateBytes});
+  const pubkeyCacheCapacity = validatorCount + MAX_PENDING_DEPOSITS_PER_EPOCH * Math.ceil(headroomEpochs);
+  loadPubkeysFile(pubkeyCache, pubkeysFile, pubkeyCacheCapacity, config, stateBytes, validatorCount, logger);
+  // unilaterally expand capacity after best-effort pubkey file loading
+  pubkeyCache.ensureCapacity(pubkeyCacheCapacity);
+  const anchorState = createBeaconStateView({nativeStateTransition, config, stateBytes});
   stateInit.validate(anchorState);
+  const earliestAvailableSlot = await stateInit.initializeEarliestAvailableSlot(anchorState);
   await stateInit.persist?.(anchorState, stateBytes);
-  stateInit.log(anchorState);
-  return {anchorState, config, isFinalized: stateInit.isFinalized};
+  stateInit.log(anchorState, nativeStateTransition);
+  return {anchorState, config, isFinalized: stateInit.isFinalized, earliestAvailableSlot};
 }

package/src/cmds/beacon/options.ts

@@ -21,6 +21,7 @@ type BeaconExtraArgs = {
   persistInvalidSszObjectsRetentionHours?: number;
   persistOrphanedBlocksDir?: string;
   peerStoreDir?: string;
+  pubkeysFile?: string;
   persistNetworkIdentity?: boolean;
   private?: boolean;
   validatorMonitorLogs?: boolean;
@@ -141,6 +142,13 @@ export const beaconExtraOptions: CliCommandOptions<BeaconExtraArgs> = {
     type: "string",
   },
 
+  pubkeysFile: {
+    hidden: true,
+    description: "Pubkey cache file, loaded on startup and saved on graceful shutdown",
+    defaultDescription: defaultBeaconPaths.pubkeysFile,
+    type: "string",
+  },
+
   persistNetworkIdentity: {
     description:
       "Whether to reuse the same peer-id across restarts. Validator custody requires custody group count to persist relative to a given ENR. Setting to false will reset ENR and validator custody requirements on restarts.",

package/src/cmds/beacon/paths.ts

@@ -9,6 +9,7 @@ export type BeaconPathsPartial = Partial<{
   dataColumnDir: string;
   persistInvalidSszObjectsDir: string;
   persistOrphanedBlocksDir?: string;
+  pubkeysFile: string;
 }>;
 
 export type BeaconPaths = {
@@ -18,6 +19,7 @@ export type BeaconPaths = {
   dataColumnDir: string;
   persistInvalidSszObjectsDir: string;
   persistOrphanedBlocksDir: string;
+  pubkeysFile: string;
 };
 
 /**
@@ -29,6 +31,7 @@ export type BeaconPaths = {
  *     ├── beacon.config.json
  *     ├── peer-id.json
  *     ├── enr
+ *     ├── pubkeys
  *     ├── chain-db
  *     └── beacon.log
  * ```
@@ -48,6 +51,7 @@ export function getBeaconPaths(
   const persistInvalidSszObjectsDir = args.persistInvalidSszObjectsDir ?? path.join(beaconDir, "invalidSszObjects");
   const peerStoreDir = args.peerStoreDir ?? path.join(beaconDir, "peerstore");
   const persistOrphanedBlocksDir = args.persistOrphanedBlocksDir ?? path.join(beaconDir, "orphaned_blocks");
+  const pubkeysFile = args.pubkeysFile ?? path.join(beaconDir, "pubkeys");
 
   return {
     ...globalPaths,
@@ -57,6 +61,7 @@ export function getBeaconPaths(
     persistInvalidSszObjectsDir,
     peerStoreDir,
     persistOrphanedBlocksDir,
+    pubkeysFile,
   };
 }
 

package/src/cmds/beacon/pubkeysFile.ts

@@ -0,0 +1,50 @@
+import {type PubkeyCache} from "@chainsafe/lodestar-z/pubkeys";
+import {ChainForkConfig} from "@lodestar/config";
+import {getValidatorPubkeyFromStateBytes} from "@lodestar/state-transition";
+import {Logger, byteArrayEquals} from "@lodestar/utils";
+
+/**
+ * Best effort load of a trusted pubkey cache saved by a previous run, to skip decompressing every validator
+ * pubkey on boot. Must be called before any worker uses the cache.
+ */
+export function loadPubkeysFile(
+  pubkeyCache: PubkeyCache,
+  filepath: string,
+  maxCapacity: number,
+  config: ChainForkConfig,
+  anchorStateBytes: Uint8Array,
+  anchorValidatorCount: number,
+  logger: Logger
+): void {
+  const start = Date.now();
+  try {
+    pubkeyCache.load(filepath, maxCapacity);
+  } catch (e) {
+    logger.debug("Unable to load pubkeys file", {filepath}, e as Error);
+    return;
+  }
+
+  // load() only checks framing and checksum, so reject a file from another chain. Checking the endpoints
+  // suffices since the registry is append-only.
+  const overlap = Math.min(pubkeyCache.size, anchorValidatorCount);
+  for (const index of overlap > 0 ? [0, overlap - 1] : []) {
+    const anchorPubkey = getValidatorPubkeyFromStateBytes(config, anchorStateBytes, index);
+    if (anchorPubkey === null || !byteArrayEquals(pubkeyCache.getPubkeyBytesOrThrow(index), anchorPubkey)) {
+      pubkeyCache.reset();
+      logger.debug("Discarded pubkeys file not matching anchor state", {filepath, index});
+      return;
+    }
+  }
+
+  logger.debug("Loaded pubkeys file", {filepath, count: pubkeyCache.size, durationMs: Date.now() - start});
+}
+
+export function savePubkeysFile(pubkeyCache: PubkeyCache, filepath: string, logger: Logger): void {
+  const start = Date.now();
+  try {
+    pubkeyCache.save(filepath);
+    logger.debug("Saved pubkeys file", {filepath, count: pubkeyCache.size, durationMs: Date.now() - start});
+  } catch (e) {
+    logger.debug("Unable to save pubkeys file", {filepath}, e as Error);
+  }
+}

package/src/cmds/beacon/stateInitialization/checkpointState.ts

@@ -186,6 +186,16 @@ function prepareCheckpointInitialization(
   const {isFinalized, ignoreWeakSubjectivityCheck} = policy;
   const config = createBeaconConfig(chainForkConfig, metadata.genesisValidatorsRoot);
   const archivedWithinWeakSubjectivityPeriod = useArchived ? archived.isWithinWeakSubjectivityPeriod : null;
+  const passedValidation =
+    archivedWithinWeakSubjectivityPeriod ?? isWithinWeakSubjectivityPeriodFromSummary(config, weakSubjectivity);
+  // Fast-fail stale checkpoints before deserializing the state or reserving pubkey-cache capacity.
+  if (!passedValidation && !ignoreWeakSubjectivityCheck) {
+    const clockEpoch = computeEpochAtSlot(getCurrentSlot(config, weakSubjectivity.genesisTime));
+    throw new StateInitializationError(
+      {code: StateInitializationErrorCode.STALE_CHECKPOINT},
+      `The selected state with epoch ${weakSubjectivity.checkpointEpoch} is not within weak subjectivity period of ${weakSubjectivity.period} epochs from the current epoch ${clockEpoch}. Please verify your checkpoint source`
+    );
+  }
   // DB-selected anchors need no persistence, including at slot zero.
   const shouldPersist = isFinalized && !useArchived;
   return {
@@ -195,15 +205,6 @@ function prepareCheckpointInitialization(
     validate(state) {
       // A supplied checkpoint must match even when the period check is ignored.
       if (expectedCheckpoint !== null) assertStateMatchesCheckpoint(state, expectedCheckpoint);
-      const passedValidation =
-        archivedWithinWeakSubjectivityPeriod ?? isWithinWeakSubjectivityPeriodFromSummary(config, weakSubjectivity);
-      if (!passedValidation && !ignoreWeakSubjectivityCheck) {
-        const clockEpoch = computeEpochAtSlot(getCurrentSlot(config, weakSubjectivity.genesisTime));
-        throw new StateInitializationError(
-          {code: StateInitializationErrorCode.STALE_CHECKPOINT},
-          `The selected state with epoch ${weakSubjectivity.checkpointEpoch} is not within weak subjectivity period of ${weakSubjectivity.period} epochs from the current epoch ${clockEpoch}. Please verify your checkpoint source`
-        );
-      }
       assertAnchorStateForkMatchesConfig(config, state);
       if (isFinalized) {
         const source = useArchived ? "db" : "checkpoint";
@@ -222,8 +223,22 @@ function prepareCheckpointInitialization(
         }
       }
     },
+    async initializeEarliestAvailableSlot(state) {
+      const stored = await db.earliestAvailableSlot.get();
+      const floor = useArchived ? (stored ?? state.slot) : Math.max(stored ?? 0, state.slot);
+      if (stored !== floor) {
+        await db.earliestAvailableSlot.set(floor);
+      }
+      logger.verbose("Initialized earliest available slot", {
+        source,
+        anchorSlot: state.slot,
+        previousSlot: stored,
+        earliestAvailableSlot: floor,
+      });
+      return floor;
+    },
     persist: shouldPersist ? (state, bytes) => persistAnchorState(config, db, state, bytes) : null,
-    log(state) {
+    log(state, nativeStateTransition) {
       const {checkpoint} = state.computeAnchorCheckpoint();
       logger.info("Initialized checkpoint state", {
         source,
@@ -233,6 +248,7 @@ function prepareCheckpointInitialization(
         stateRoot: toRootHex(state.hashTreeRoot()),
         checkpointRoot: toRootHex(checkpoint.root),
         isFinalized,
+        nativeStateTransition,
         ...(isFinalized ? {} : {lastProcessedSlot: state.latestBlockHeader.slot}),
       });
     },

package/src/cmds/beacon/stateInitialization/genesisState.ts

@@ -73,12 +73,26 @@ export async function prepareGenesisInitialization(
         logger.warn("Checkpoint sync recommended, please use --help to see checkpoint sync options");
       }
     },
+    async initializeEarliestAvailableSlot(state) {
+      const stored = await db.earliestAvailableSlot.get();
+      if (stored !== null && stored !== state.slot) {
+        logger.warn("Resetting earliest available slot for genesis initialization", {
+          previousSlot: stored,
+          earliestAvailableSlot: state.slot,
+        });
+      }
+      if (stored !== state.slot) {
+        await db.earliestAvailableSlot.set(state.slot);
+      }
+      return state.slot;
+    },
     persist: (state, bytes) => persistAnchorState(config, db, state, bytes),
-    log(state) {
+    log(state, nativeStateTransition) {
       logger.info("Initialized genesis state", {
         slot: state.slot,
         stateRoot: toRootHex(state.hashTreeRoot()),
         isFinalized: true,
+        nativeStateTransition,
       });
     },
   };

package/src/cmds/beacon/stateInitialization/prepareStateInitialization.ts

@@ -11,7 +11,7 @@ import {assertAnchorStateForkMatchesConfig} from "./validation.js";
 
 export function prepareArchivedStateInitialization(
   {stateBytes, metadata, isWithinWeakSubjectivityPeriod}: ArchivedStateBytes,
-  {chainForkConfig, logger}: StatePreparationContext
+  {chainForkConfig, db, logger}: StatePreparationContext
 ): StateInitialization {
   const config = createBeaconConfig(chainForkConfig, metadata.genesisValidatorsRoot);
   return {
@@ -34,13 +34,28 @@ export function prepareArchivedStateInitialization(
         logger.warn("Checkpoint sync recommended, please use --help to see checkpoint sync options");
       }
     },
+    async initializeEarliestAvailableSlot(state) {
+      const stored = await db.earliestAvailableSlot.get();
+      // we bootstrap the node with archived db, use the previous earliestAvailableSLot
+      if (stored !== null) {
+        logger.verbose("Reusing persisted earliest available slot", {
+          anchorSlot: state.slot,
+          earliestAvailableSlot: stored,
+        });
+        return stored;
+      }
+      // legacy db: blockArchive.firstKey() is not a safe floor, a past checkpoint sync may have left a gap.
+      await db.earliestAvailableSlot.set(state.slot);
+      return state.slot;
+    },
     persist: null,
-    log(state) {
+    log(state, nativeStateTransition) {
       logger.info("Initialized state from db", {
         slot: state.slot,
         epoch: computeEpochAtSlot(state.slot),
         stateRoot: toRootHex(state.hashTreeRoot()),
         isFinalized: true,
+        nativeStateTransition,
       });
     },
   };

package/src/cmds/beacon/stateInitialization/types.ts

@@ -1,6 +1,7 @@
 import {IBeaconDb} from "@lodestar/beacon-node";
 import {BeaconConfig, ChainForkConfig} from "@lodestar/config";
 import {IBeaconStateView, StateBytesMetadata, WeakSubjectivitySummary} from "@lodestar/state-transition";
+import {Slot} from "@lodestar/types";
 import {Checkpoint} from "@lodestar/types/phase0";
 import {Logger} from "@lodestar/utils";
 import {GlobalArgs} from "../../../options/globalOptions.js";
@@ -18,7 +19,7 @@ export type StateInitializationOptions = Pick<
   | "ignoreWeakSubjectivityCheck"
   | "network"
   | "chain.nHistoricalStatesFileDataStore"
-  | "chain.nativeStateView"
+  | "chain.nativeStateTransition"
 >;
 
 export type StatePreparationContext = {
@@ -53,6 +54,7 @@ export type StateInitialization = {
   config: BeaconConfig;
   isFinalized: boolean;
   validate: (state: IBeaconStateView) => void;
+  initializeEarliestAvailableSlot: (state: IBeaconStateView) => Promise<Slot>;
   persist: ((state: IBeaconStateView, stateBytes: Uint8Array) => Promise<void>) | null;
-  log: (state: IBeaconStateView) => void;
+  log: (state: IBeaconStateView, nativeStateTransition: boolean) => void;
 };

package/src/cmds/dev/handler.ts

@@ -31,7 +31,7 @@ export async function devHandler(args: IDevArgs & GlobalArgs): Promise<void> {
 
   // Note: defaults to network "dev", to all paths are custom and don't conflict with networks.
   // Flag --reset cleans up the custom dirs on dev stop
-  const beaconDbDir = getBeaconPaths(args, network).dbDir;
+  const {dbDir: beaconDbDir, pubkeysFile} = getBeaconPaths(args, network);
   const validatorsDbDir = getValidatorPaths(args, network).validatorsDbDir;
 
   // Remove slashing protection db. Otherwise the validators won't be able to propose nor attest
@@ -39,6 +39,8 @@ export async function devHandler(args: IDevArgs & GlobalArgs): Promise<void> {
   if (args.genesisTime === undefined) {
     await rimraf(beaconDbDir);
     await rimraf(validatorsDbDir);
+    // Validators deposited in the previous run do not exist on the new chain
+    await rimraf(pubkeysFile);
   }
 
   mkdir(beaconDbDir);

package/src/cmds/validator/handler.ts

@@ -300,6 +300,17 @@ function getProposerConfigFromArgs(
     }
   }
 
+  const configs = [valProposerConfig.defaultConfig, ...Object.values(valProposerConfig.proposerConfig ?? {})];
+  if (
+    configs.some(
+      (config) =>
+        config.builder?.selection === routes.validator.BuilderSelection.ExecutionOnly &&
+        (config.builder.builders ?? []).length > 0
+    )
+  ) {
+    throw new YargsError("Builder selection executiononly can not be combined with builders");
+  }
+
   return valProposerConfig;
 }
 

package/src/cmds/validator/options.ts

@@ -267,7 +267,7 @@ export const validatorOptions: CliCommandOptions<IValidatorCliArgs> = {
   "builder.selection": {
     type: "string",
     description:
-      "Builder block selection strategy `default`, `maxprofit`, `builderalways`, `executionalways`, or pre-Gloas `executiononly`",
+      "Builder block selection strategy `default`, `maxprofit`, `builderalways`, `executionalways`, or `executiononly`",
     defaultDescription: `${defaultOptions.builderSelection}`,
     group: "builder",
   },

package/src/options/beaconNodeOptions/chain.ts

@@ -12,6 +12,7 @@ export type ChainArgs = {
   "chain.blsVerifyAllMainThread"?: boolean;
   "chain.disableBlsBatchVerify"?: boolean;
   "chain.persistProducedBlocks"?: boolean;
+  "chain.persistProducedPayloadEnvelopes"?: boolean;
   "chain.persistInvalidSszObjects"?: boolean;
   // No need to define chain.persistInvalidSszObjects as part of ChainArgs
   // as this is defined as part of BeaconPaths
@@ -35,7 +36,7 @@ export type ChainArgs = {
   "chain.archiveDataEpochs"?: number;
   "chain.archiveMode": ArchiveMode;
   "chain.nHistoricalStatesFileDataStore"?: boolean;
-  "chain.nativeStateView"?: boolean;
+  "chain.nativeStateTransition"?: boolean;
   "chain.maxBlockStates"?: number;
   "chain.maxCPStateEpochsInMemory"?: number;
   "chain.maxCPStateEpochsOnDisk"?: number;
@@ -53,6 +54,7 @@ export function parseArgs(args: ChainArgs & CircuitBreakerArgs): IBeaconNodeOpti
     blsVerifyAllMainThread: args["chain.blsVerifyAllMainThread"],
     disableBlsBatchVerify: args["chain.disableBlsBatchVerify"],
     persistProducedBlocks: args["chain.persistProducedBlocks"],
+    persistProducedPayloadEnvelopes: args["chain.persistProducedPayloadEnvelopes"],
     persistInvalidSszObjects: args["chain.persistInvalidSszObjects"],
     // biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
     persistInvalidSszObjectsDir: undefined as any,
@@ -79,7 +81,7 @@ export function parseArgs(args: ChainArgs & CircuitBreakerArgs): IBeaconNodeOpti
     archiveMode: args["chain.archiveMode"] ?? defaultOptions.chain.archiveMode,
     nHistoricalStatesFileDataStore:
       args["chain.nHistoricalStatesFileDataStore"] ?? defaultOptions.chain.nHistoricalStatesFileDataStore,
-    nativeStateView: args["chain.nativeStateView"] ?? defaultOptions.chain.nativeStateView,
+    nativeStateTransition: args["chain.nativeStateTransition"] ?? defaultOptions.chain.nativeStateTransition,
     maxBlockStates: args["chain.maxBlockStates"] ?? defaultOptions.chain.maxBlockStates,
     maxCPStateEpochsInMemory: args["chain.maxCPStateEpochsInMemory"] ?? defaultOptions.chain.maxCPStateEpochsInMemory,
     maxCPStateEpochsOnDisk: args["chain.maxCPStateEpochsOnDisk"] ?? defaultOptions.chain.maxCPStateEpochsOnDisk,
@@ -170,6 +172,13 @@ Will double processing times. Use only for debugging purposes.",
     group: "chain",
   },
 
+  "chain.persistProducedPayloadEnvelopes": {
+    hidden: true,
+    type: "boolean",
+    description: "Persist produced execution payload envelopes as SSZ files for debugging",
+    group: "chain",
+  },
+
   "chain.persistInvalidSszObjects": {
     hidden: true,
     type: "boolean",
@@ -318,11 +327,11 @@ Will double processing times. Use only for debugging purposes.",
     group: "chain",
   },
 
-  "chain.nativeStateView": {
+  "chain.nativeStateTransition": {
     hidden: true,
-    description: "Use native (Zig) BeaconStateView instead of JS implementation",
+    description: "Use native (Zig) state transition instead of JS implementation",
     type: "boolean",
-    default: defaultOptions.chain.nativeStateView,
+    default: defaultOptions.chain.nativeStateTransition,
     group: "chain",
   },
 

package/src/options/beaconNodeOptions/execution.ts

@@ -1,5 +1,5 @@
 import fs from "node:fs";
-import {IBeaconNodeOptions, defaultExecutionEngineHttpOpts} from "@lodestar/beacon-node";
+import {EngineApiMode, IBeaconNodeOptions, defaultExecutionEngineHttpOpts, engineApiModes} from "@lodestar/beacon-node";
 import {CliCommandOptions} from "@lodestar/utils";
 import {extractJwtHexSecret} from "../../util/index.js";
 
@@ -8,6 +8,7 @@ export type ExecutionEngineArgs = {
   "execution.timeout"?: number;
   "execution.retries": number;
   "execution.retryDelay": number;
+  "execution.engineApi"?: EngineApiMode;
   "execution.engineMock"?: boolean;
   jwtSecret?: string;
   jwtId?: string;
@@ -26,6 +27,7 @@ export function parseArgs(args: ExecutionEngineArgs): IBeaconNodeOptions["execut
     timeout: args["execution.timeout"],
     retries: args["execution.retries"],
     retryDelay: args["execution.retryDelay"],
+    engineApi: args["execution.engineApi"],
     /**
      * jwtSecret is parsed as hex instead of bytes because the merge with defaults
      * in beaconOptions messes up the bytes array as as index => value object
@@ -69,6 +71,15 @@ export const options: CliCommandOptions<ExecutionEngineArgs> = {
     group: "execution",
   },
 
+  "execution.engineApi": {
+    description:
+      "Engine API transport. 'auto' negotiates REST with SSZ for a single execution URL and uses JSON-RPC for multiple URLs or unsupported features. 'ssz' requires a single REST-capable execution URL without JSON-RPC fallback. 'json-rpc' always uses JSON-RPC",
+    type: "string",
+    choices: engineApiModes,
+    default: defaultExecutionEngineHttpOpts.engineApi,
+    group: "execution",
+  },
+
   "execution.engineMock": {
     description: "Set the execution engine to mock mode (development only)",
     type: "boolean",