@chainsafe/lodestar 1.50.0-dev.53ad0a2af7 → 1.50.0-dev.56f65bd6e9

package/src/cmds/beacon/initBeaconState.ts

@@ -10,13 +10,16 @@ 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 {
   prepareArchivedStateInitialization,
-  prepareCheckpointOrGenesisInitialization,
+  prepareCheckpointSourceInitialization,
 } from "./stateInitialization/prepareStateInitialization.js";
 import {
   ArchivedStateBytes,
@@ -25,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)
@@ -65,11 +74,23 @@ 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
+      );
     }
   }
-  const stateInit = await prepareCheckpointOrGenesisInitialization(options, archived, context);
-  return executeStateInitialization(stateInit, useNative);
+  let stateInit = await prepareCheckpointSourceInitialization(options, archived, context);
+  if (stateInit === null) {
+    // Without a usable checkpoint state, resume from the db as if no checkpoint source was set instead of genesis
+    stateInit =
+      archived !== null
+        ? prepareArchivedStateInitialization(archived, context)
+        : await prepareGenesisInitialization(options, context);
+  }
+  return executeStateInitialization(stateInit, nativeStateTransition, pubkeysFile, logger);
 }
 
 /**
@@ -97,7 +118,7 @@ async function readLatestArchivedStateBytes({
   if (weakSubjectivity === null) {
     throw new StateInitializationError(
       {code: StateInitializationErrorCode.MALFORMED_STATE_BYTES},
-      "Cannot extract weak subjectivity summary from archived state bytes"
+      `Cannot extract weak subjectivity summary from archived state bytes, expected ${chainForkConfig.getForkName(metadata.slot)} state at slot ${metadata.slot}, possible fork or network mismatch`
     );
   }
   return {
@@ -114,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);
@@ -129,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

@@ -4,7 +4,6 @@ import {LogArgs, logOptions} from "../../options/logOptions.js";
 import {BeaconPaths, defaultBeaconPaths} from "./paths.js";
 
 type BeaconExtraArgs = {
-  forceGenesis?: boolean;
   genesisStateFile?: string;
   configFile?: string;
   bootnodesFile?: string;
@@ -22,6 +21,7 @@ type BeaconExtraArgs = {
   persistInvalidSszObjectsRetentionHours?: number;
   persistOrphanedBlocksDir?: string;
   peerStoreDir?: string;
+  pubkeysFile?: string;
   persistNetworkIdentity?: boolean;
   private?: boolean;
   validatorMonitorLogs?: boolean;
@@ -30,12 +30,6 @@ type BeaconExtraArgs = {
 };
 
 export const beaconExtraOptions: CliCommandOptions<BeaconExtraArgs> = {
-  forceGenesis: {
-    description: "Force beacon to create genesis without file",
-    type: "boolean",
-    hidden: true,
-  },
-
   genesisStateFile: {
     description: "Path or URL to download a genesis state file in ssz-encoded format",
     type: "string",
@@ -148,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

@@ -178,7 +178,7 @@ function prepareCheckpointInitialization(
   if (weakSubjectivity === null) {
     throw new StateInitializationError(
       {code: StateInitializationErrorCode.MALFORMED_STATE_BYTES},
-      `Cannot extract weak subjectivity summary from ${candidate.source}`
+      `Cannot extract weak subjectivity summary from ${candidate.source}, expected ${chainForkConfig.getForkName(metadata.slot)} state at slot ${metadata.slot}, possible fork or network mismatch`
     );
   }
   const expectedCheckpoint = useArchived ? null : candidate.expectedCheckpoint;
@@ -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,17 +205,8 @@ 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) {
-        assertAnchorStateForkMatchesConfig(config, state);
         const source = useArchived ? "db" : "checkpoint";
         const logData = {
           slot: state.slot,
@@ -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

@@ -15,11 +15,11 @@ import {StateInitialization, StateInitializationOptions, StatePreparationContext
 import {assertAnchorStateForkMatchesConfig} from "./validation.js";
 
 export async function prepareGenesisInitialization(
-  options: Pick<StateInitializationOptions, "genesisStateFile" | "network" | "forceGenesis">,
+  options: Pick<StateInitializationOptions, "genesisStateFile" | "network">,
   {chainForkConfig, db, logger}: StatePreparationContext
 ): Promise<StateInitialization> {
   const source = options.genesisStateFile || getGenesisFileUrl(options.network || defaultNetwork);
-  if (!source || options.forceGenesis) {
+  if (!source) {
     throw new StateInitializationError(
       {code: StateInitializationErrorCode.MISSING_INITIALIZATION_SOURCE},
       "Failed to initialize beacon state, please provide a genesis state file or use checkpoint sync"
@@ -40,7 +40,7 @@ export async function prepareGenesisInitialization(
   if (weakSubjectivity === null) {
     throw new StateInitializationError(
       {code: StateInitializationErrorCode.MALFORMED_STATE_BYTES},
-      "Cannot extract weak subjectivity summary from genesis state bytes"
+      `Cannot extract weak subjectivity summary from genesis state bytes, expected ${chainForkConfig.getForkName(metadata.slot)} state at slot ${metadata.slot}, possible fork or network mismatch`
     );
   }
   const config = createBeaconConfig(chainForkConfig, metadata.genesisValidatorsRoot);
@@ -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

@@ -6,13 +6,12 @@ import {
   prepareCheckpointFileInitialization,
   prepareUnfinalizedCheckpointInitialization,
 } from "./checkpointState.js";
-import {prepareGenesisInitialization} from "./genesisState.js";
 import {ArchivedStateBytes, StateInitialization, StateInitializationOptions, StatePreparationContext} from "./types.js";
 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 {
@@ -35,23 +34,38 @@ 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,
       });
     },
   };
 }
 
-export async function prepareCheckpointOrGenesisInitialization(
+export async function prepareCheckpointSourceInitialization(
   options: StateInitializationOptions,
   archived: ArchivedStateBytes | null,
   context: StatePreparationContext
-): Promise<StateInitialization> {
+): Promise<StateInitialization | null> {
   if (options.checkpointState) {
     return prepareCheckpointFileInitialization(options.checkpointState, options, archived, context);
   }
@@ -59,8 +73,7 @@ export async function prepareCheckpointOrGenesisInitialization(
     return prepareCheckpointApiInitialization(options.checkpointSyncUrl, options, archived, context);
   }
   if (options.lastPersistedCheckpointState || options.unsafeCheckpointState) {
-    const stateInit = await prepareUnfinalizedCheckpointInitialization(options, archived, context);
-    if (stateInit !== null) return stateInit;
+    return prepareUnfinalizedCheckpointInitialization(options, archived, context);
   }
-  return prepareGenesisInitialization(options, context);
+  return null;
 }

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";
@@ -16,10 +17,9 @@ export type StateInitializationOptions = Pick<
   | "wssCheckpoint"
   | "forceCheckpointSync"
   | "ignoreWeakSubjectivityCheck"
-  | "forceGenesis"
   | "network"
   | "chain.nHistoricalStatesFileDataStore"
-  | "chain.nativeStateView"
+  | "chain.nativeStateTransition"
 >;
 
 export type StatePreparationContext = {
@@ -54,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/networks/index.ts

@@ -182,11 +182,20 @@ export async function fetchWeakSubjectivityStateBytes(
       GET_STATE_LOG_INTERVAL
     );
     const wsStateBytes = response.ssz();
+    const {version} = response.meta();
 
     const wsSlot = getStateSlotFromBytes(wsStateBytes);
     const logData = {stateId, size: formatBytes(wsStateBytes.length)};
     logger.info("Download completed", typeof stateId === "number" ? logData : {...logData, slot: wsSlot});
 
+    const expectedFork = config.getForkName(wsSlot);
+    if (version !== expectedFork) {
+      throw new LodestarError(
+        {code: "CHECKPOINT_FORK_MISMATCH"},
+        `Checkpoint sync server returned ${version} state at slot ${wsSlot} but local config expects ${expectedFork}, verify --network or the chain config`
+      );
+    }
+
     return {
       stateBytes: new Uint8Array(wsStateBytes.buffer, wsStateBytes.byteOffset, wsStateBytes.byteLength),
       expectedCheckpoint: wsCheckpoint,

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",
   },