@chainsafe/lodestar 1.50.0-dev.ebecebb9ba → 1.50.0-dev.f0a5c36612

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

@@ -0,0 +1,272 @@
+import {DbCPStateDatastore, FileCPStateDatastore, persistAnchorState} from "@lodestar/beacon-node";
+import {createBeaconConfig} from "@lodestar/config";
+import {
+  IBeaconStateView,
+  computeEpochAtSlot,
+  computeWeakSubjectivitySummaryFromStateBytes,
+  getCurrentSlot,
+  isWithinWeakSubjectivityPeriodFromSummary,
+  readBeaconStateBytesMetadata,
+} from "@lodestar/state-transition";
+import {ssz} from "@lodestar/types";
+import {Checkpoint} from "@lodestar/types/phase0";
+import {formatBytes, toRootHex} from "@lodestar/utils";
+import {fetchWeakSubjectivityStateBytes, getCheckpointFromArg} from "../../../networks/index.js";
+import {downloadOrLoadFile} from "../../../util/index.js";
+import {StateInitializationError, StateInitializationErrorCode} from "./errors.js";
+import {
+  ArchivedStateBytes,
+  CheckpointStartupPolicy,
+  CheckpointStateBytesCandidate,
+  StateInitialization,
+  StateInitializationOptions,
+  StatePreparationContext,
+} from "./types.js";
+import {assertAnchorStateForkMatchesConfig} from "./validation.js";
+
+type CheckpointOptions = Pick<
+  StateInitializationOptions,
+  "wssCheckpoint" | "forceCheckpointSync" | "ignoreWeakSubjectivityCheck"
+>;
+
+export async function prepareCheckpointFileInitialization(
+  checkpointState: string,
+  options: CheckpointOptions,
+  archived: ArchivedStateBytes | null,
+  context: StatePreparationContext
+): Promise<StateInitialization> {
+  context.logger.info("Loading checkpoint state", {checkpointState});
+  const bytes = await downloadOrLoadFile(checkpointState);
+  const stateBytes = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  context.logger.info("Loaded checkpoint state", {checkpointState, size: formatBytes(stateBytes.length)});
+  return prepareCheckpointInitialization(
+    {
+      stateBytes,
+      expectedCheckpoint: options.wssCheckpoint ? getCheckpointFromArg(options.wssCheckpoint) : null,
+      source: "checkpoint file",
+    },
+    archived,
+    {
+      isFinalized: true,
+      forceCheckpointSync: Boolean(options.forceCheckpointSync),
+      ignoreWeakSubjectivityCheck: Boolean(options.ignoreWeakSubjectivityCheck),
+    },
+    context
+  );
+}
+
+export async function prepareCheckpointApiInitialization(
+  checkpointSyncUrl: string,
+  options: CheckpointOptions,
+  archived: ArchivedStateBytes | null,
+  context: StatePreparationContext
+): Promise<StateInitialization> {
+  const {chainForkConfig, logger} = context;
+  try {
+    const url = new URL(checkpointSyncUrl);
+    logger.info("Fetching checkpoint state", {checkpointSyncUrl: url.origin});
+  } catch (error) {
+    logger.error("Invalid checkpoint sync URL", {checkpointSyncUrl}, error as Error);
+    throw error;
+  }
+  const {stateBytes, expectedCheckpoint} = await fetchWeakSubjectivityStateBytes(chainForkConfig, logger, {
+    checkpointSyncUrl,
+    wssCheckpoint: options.wssCheckpoint,
+  });
+  return prepareCheckpointInitialization(
+    {stateBytes, expectedCheckpoint, source: "checkpointSyncUrl"},
+    archived,
+    {
+      isFinalized: true,
+      forceCheckpointSync: Boolean(options.forceCheckpointSync),
+      ignoreWeakSubjectivityCheck: Boolean(options.ignoreWeakSubjectivityCheck),
+    },
+    context
+  );
+}
+
+export async function prepareUnfinalizedCheckpointInitialization(
+  options: CheckpointOptions &
+    Pick<
+      StateInitializationOptions,
+      "lastPersistedCheckpointState" | "unsafeCheckpointState" | "chain.nHistoricalStatesFileDataStore"
+    >,
+  archived: ArchivedStateBytes | null,
+  context: StatePreparationContext
+): Promise<StateInitialization | null> {
+  const {db, dataDir, logger} = context;
+  let bytes: Uint8Array | null = null;
+  if (options.lastPersistedCheckpointState && !options.forceCheckpointSync) {
+    const store = options["chain.nHistoricalStatesFileDataStore"]
+      ? new FileCPStateDatastore(dataDir)
+      : new DbCPStateDatastore(db);
+    logger.verbose(`Finding last persisted checkpoint state from ${store.constructor.name}`);
+    bytes = await store.readLatestSafe();
+    if (bytes === null) {
+      logger.warn("Last persisted checkpoint state not found");
+    } else {
+      logger.info("Found last persisted checkpoint state", {size: formatBytes(bytes.length)});
+    }
+  }
+  if (bytes === null && options.unsafeCheckpointState) {
+    logger.info("Loading checkpoint state", {unsafeCheckpointState: options.unsafeCheckpointState});
+    bytes = await downloadOrLoadFile(options.unsafeCheckpointState);
+    logger.info("Loaded checkpoint state", {size: formatBytes(bytes.length)});
+  }
+  if (bytes === null) return null;
+  logger.warn(
+    "Initializing from unfinalized checkpoint state is unsafe and may cause the node to follow a minority chain"
+  );
+  const stateBytes = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return prepareCheckpointInitialization(
+    {
+      stateBytes,
+      expectedCheckpoint: options.wssCheckpoint ? getCheckpointFromArg(options.wssCheckpoint) : null,
+      source: "unfinalized source",
+    },
+    archived,
+    {
+      isFinalized: false,
+      forceCheckpointSync: Boolean(options.forceCheckpointSync),
+      ignoreWeakSubjectivityCheck: Boolean(options.ignoreWeakSubjectivityCheck),
+    },
+    context
+  );
+}
+
+function prepareCheckpointInitialization(
+  candidate: CheckpointStateBytesCandidate,
+  archived: ArchivedStateBytes | null,
+  policy: CheckpointStartupPolicy,
+  {chainForkConfig, db, logger}: StatePreparationContext
+): StateInitialization {
+  const candidateMetadata = readBeaconStateBytesMetadata(candidate.stateBytes);
+  if (candidateMetadata === null) {
+    throw new StateInitializationError(
+      {code: StateInitializationErrorCode.MALFORMED_STATE_BYTES},
+      `Cannot read state metadata from ${candidate.source}`
+    );
+  }
+  if (
+    archived !== null &&
+    (archived.metadata.genesisTime !== candidateMetadata.genesisTime ||
+      !ssz.Root.equals(archived.metadata.genesisValidatorsRoot, candidateMetadata.genesisValidatorsRoot))
+  ) {
+    throw new StateInitializationError(
+      {code: StateInitializationErrorCode.INCOMPATIBLE_GENESIS},
+      "Db state and checkpoint state are not compatible, either clear the db or verify your checkpoint source"
+    );
+  }
+  const useArchived =
+    archived !== null && archived.metadata.slot > candidateMetadata.slot && !policy.forceCheckpointSync;
+  if (useArchived) {
+    logger.verbose(
+      "Db state is ahead of the provided checkpoint state, using the db state to initialize the beacon chain"
+    );
+  }
+  const {stateBytes, metadata, weakSubjectivity} = useArchived
+    ? archived
+    : {
+        stateBytes: candidate.stateBytes,
+        metadata: candidateMetadata,
+        weakSubjectivity: computeWeakSubjectivitySummaryFromStateBytes(
+          chainForkConfig,
+          candidate.stateBytes,
+          candidateMetadata
+        ),
+      };
+  if (weakSubjectivity === null) {
+    throw new StateInitializationError(
+      {code: StateInitializationErrorCode.MALFORMED_STATE_BYTES},
+      `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;
+  const source = useArchived ? "db" : candidate.source;
+  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 {
+    stateBytes,
+    config,
+    isFinalized,
+    validate(state) {
+      // A supplied checkpoint must match even when the period check is ignored.
+      if (expectedCheckpoint !== null) assertStateMatchesCheckpoint(state, expectedCheckpoint);
+      assertAnchorStateForkMatchesConfig(config, state);
+      if (isFinalized) {
+        const source = useArchived ? "db" : "checkpoint";
+        const logData = {
+          slot: state.slot,
+          epoch: computeEpochAtSlot(state.slot),
+          stateSize: formatBytes(stateBytes.length),
+          stateRoot: toRootHex(state.hashTreeRoot()),
+          isWithinWeakSubjectivityPeriod: passedValidation,
+        };
+        if (passedValidation) {
+          logger.info(`Initializing beacon from a valid ${source} state`, logData);
+        } else {
+          logger.warn(`Initializing from a stale ${source} state vulnerable to long range attacks`, logData);
+          logger.warn("Checkpoint sync recommended, please use --help to see checkpoint sync options");
+        }
+      }
+    },
+    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, nativeStateTransition) {
+      const {checkpoint} = state.computeAnchorCheckpoint();
+      logger.info("Initialized checkpoint state", {
+        source,
+        slot: state.slot,
+        epoch: checkpoint.epoch,
+        stateSize: formatBytes(stateBytes.length),
+        stateRoot: toRootHex(state.hashTreeRoot()),
+        checkpointRoot: toRootHex(checkpoint.root),
+        isFinalized,
+        nativeStateTransition,
+        ...(isFinalized ? {} : {lastProcessedSlot: state.latestBlockHeader.slot}),
+      });
+    },
+  };
+}
+
+function assertStateMatchesCheckpoint(state: IBeaconStateView, checkpoint: Checkpoint): void {
+  const {root: blockRoot, epoch: stateEpoch} = state.computeAnchorCheckpoint().checkpoint;
+  if (!ssz.Root.equals(blockRoot, checkpoint.root)) {
+    throw new StateInitializationError(
+      {code: StateInitializationErrorCode.CHECKPOINT_ROOT_MISMATCH},
+      `Roots do not match.  expected=${toRootHex(checkpoint.root)}, actual=${toRootHex(blockRoot)}`
+    );
+  }
+  if (!ssz.Epoch.equals(stateEpoch, checkpoint.epoch)) {
+    throw new StateInitializationError(
+      {code: StateInitializationErrorCode.CHECKPOINT_EPOCH_MISMATCH},
+      `Epochs do not match.  expected=${checkpoint.epoch}, actual=${stateEpoch}`
+    );
+  }
+}

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

@@ -0,0 +1,15 @@
+import {LodestarError} from "@lodestar/utils";
+
+export enum StateInitializationErrorCode {
+  INVALID_CHECKPOINT_SOURCE = "INVALID_CHECKPOINT_SOURCE",
+  MALFORMED_STATE_BYTES = "MALFORMED_STATE_BYTES",
+  INCOMPATIBLE_GENESIS = "INCOMPATIBLE_GENESIS",
+  CHECKPOINT_ROOT_MISMATCH = "CHECKPOINT_ROOT_MISMATCH",
+  CHECKPOINT_EPOCH_MISMATCH = "CHECKPOINT_EPOCH_MISMATCH",
+  STALE_CHECKPOINT = "STALE_CHECKPOINT",
+  ANCHOR_STATE_FORK_MISMATCH = "ANCHOR_STATE_FORK_MISMATCH",
+  GENESIS_ROOT_MISMATCH = "GENESIS_ROOT_MISMATCH",
+  MISSING_INITIALIZATION_SOURCE = "MISSING_INITIALIZATION_SOURCE",
+}
+
+export class StateInitializationError extends LodestarError<{code: StateInitializationErrorCode}> {}

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

@@ -0,0 +1,99 @@
+import {persistAnchorState} from "@lodestar/beacon-node";
+import {createBeaconConfig} from "@lodestar/config";
+import {
+  computeEpochAtSlot,
+  computeWeakSubjectivitySummaryFromStateBytes,
+  isWithinWeakSubjectivityPeriodFromSummary,
+  readBeaconStateBytesMetadata,
+} from "@lodestar/state-transition";
+import {formatBytes, toRootHex} from "@lodestar/utils";
+import {getGenesisFileUrl, getGenesisStateRoot} from "../../../networks/index.js";
+import {defaultNetwork} from "../../../options/globalOptions.js";
+import {downloadOrLoadFile} from "../../../util/index.js";
+import {StateInitializationError, StateInitializationErrorCode} from "./errors.js";
+import {StateInitialization, StateInitializationOptions, StatePreparationContext} from "./types.js";
+import {assertAnchorStateForkMatchesConfig} from "./validation.js";
+
+export async function prepareGenesisInitialization(
+  options: Pick<StateInitializationOptions, "genesisStateFile" | "network">,
+  {chainForkConfig, db, logger}: StatePreparationContext
+): Promise<StateInitialization> {
+  const source = options.genesisStateFile || getGenesisFileUrl(options.network || defaultNetwork);
+  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"
+    );
+  }
+  logger.info("Loading genesis state", {genesisStateFile: source});
+  const bytes = await downloadOrLoadFile(source);
+  const stateBytes = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  logger.info("Loaded genesis state", {size: formatBytes(stateBytes.length)});
+  const metadata = readBeaconStateBytesMetadata(stateBytes);
+  if (metadata === null) {
+    throw new StateInitializationError(
+      {code: StateInitializationErrorCode.MALFORMED_STATE_BYTES},
+      "Cannot read metadata from genesis state bytes"
+    );
+  }
+  const weakSubjectivity = computeWeakSubjectivitySummaryFromStateBytes(chainForkConfig, stateBytes, metadata);
+  if (weakSubjectivity === null) {
+    throw new StateInitializationError(
+      {code: StateInitializationErrorCode.MALFORMED_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);
+  const expectedRoot = getGenesisStateRoot(options.network);
+  return {
+    stateBytes,
+    config,
+    isFinalized: true,
+    validate(state) {
+      const stateRoot = toRootHex(state.hashTreeRoot());
+      if (expectedRoot !== null && stateRoot !== expectedRoot) {
+        throw new StateInitializationError(
+          {code: StateInitializationErrorCode.GENESIS_ROOT_MISMATCH},
+          `Genesis state root mismatch expected=${expectedRoot} received=${stateRoot}`
+        );
+      }
+      assertAnchorStateForkMatchesConfig(config, state);
+      const passedValidation = isWithinWeakSubjectivityPeriodFromSummary(config, weakSubjectivity);
+      const logData = {
+        slot: state.slot,
+        epoch: computeEpochAtSlot(state.slot),
+        stateSize: formatBytes(stateBytes.length),
+        stateRoot,
+        isWithinWeakSubjectivityPeriod: passedValidation,
+      };
+      if (passedValidation) {
+        logger.info("Initializing beacon from a valid checkpoint state", logData);
+      } else {
+        logger.warn("Initializing from a stale checkpoint state vulnerable to long range attacks", logData);
+        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, nativeStateTransition) {
+      logger.info("Initialized genesis state", {
+        slot: state.slot,
+        stateRoot: toRootHex(state.hashTreeRoot()),
+        isFinalized: true,
+        nativeStateTransition,
+      });
+    },
+  };
+}

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

@@ -0,0 +1,79 @@
+import {createBeaconConfig} from "@lodestar/config";
+import {computeEpochAtSlot} from "@lodestar/state-transition";
+import {formatBytes, toRootHex} from "@lodestar/utils";
+import {
+  prepareCheckpointApiInitialization,
+  prepareCheckpointFileInitialization,
+  prepareUnfinalizedCheckpointInitialization,
+} from "./checkpointState.js";
+import {ArchivedStateBytes, StateInitialization, StateInitializationOptions, StatePreparationContext} from "./types.js";
+import {assertAnchorStateForkMatchesConfig} from "./validation.js";
+
+export function prepareArchivedStateInitialization(
+  {stateBytes, metadata, isWithinWeakSubjectivityPeriod}: ArchivedStateBytes,
+  {chainForkConfig, db, logger}: StatePreparationContext
+): StateInitialization {
+  const config = createBeaconConfig(chainForkConfig, metadata.genesisValidatorsRoot);
+  return {
+    stateBytes,
+    config,
+    isFinalized: true,
+    validate(state) {
+      assertAnchorStateForkMatchesConfig(config, state);
+      const logData = {
+        slot: state.slot,
+        epoch: computeEpochAtSlot(state.slot),
+        stateSize: formatBytes(stateBytes.length),
+        stateRoot: toRootHex(state.hashTreeRoot()),
+        isWithinWeakSubjectivityPeriod,
+      };
+      if (isWithinWeakSubjectivityPeriod) {
+        logger.info("Initializing beacon from a valid db state", logData);
+      } else {
+        logger.warn("Initializing from a stale db state vulnerable to long range attacks", logData);
+        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, nativeStateTransition) {
+      logger.info("Initialized state from db", {
+        slot: state.slot,
+        epoch: computeEpochAtSlot(state.slot),
+        stateRoot: toRootHex(state.hashTreeRoot()),
+        isFinalized: true,
+        nativeStateTransition,
+      });
+    },
+  };
+}
+
+export async function prepareCheckpointSourceInitialization(
+  options: StateInitializationOptions,
+  archived: ArchivedStateBytes | null,
+  context: StatePreparationContext
+): Promise<StateInitialization | null> {
+  if (options.checkpointState) {
+    return prepareCheckpointFileInitialization(options.checkpointState, options, archived, context);
+  }
+  if (options.checkpointSyncUrl) {
+    return prepareCheckpointApiInitialization(options.checkpointSyncUrl, options, archived, context);
+  }
+  if (options.lastPersistedCheckpointState || options.unsafeCheckpointState) {
+    return prepareUnfinalizedCheckpointInitialization(options, archived, context);
+  }
+  return null;
+}

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

@@ -0,0 +1,60 @@
+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";
+import {BeaconArgs} from "../options.js";
+
+export type StateInitializationOptions = Pick<
+  BeaconArgs & GlobalArgs,
+  | "checkpointState"
+  | "checkpointSyncUrl"
+  | "unsafeCheckpointState"
+  | "lastPersistedCheckpointState"
+  | "genesisStateFile"
+  | "wssCheckpoint"
+  | "forceCheckpointSync"
+  | "ignoreWeakSubjectivityCheck"
+  | "network"
+  | "chain.nHistoricalStatesFileDataStore"
+  | "chain.nativeStateTransition"
+>;
+
+export type StatePreparationContext = {
+  chainForkConfig: ChainForkConfig;
+  db: IBeaconDb;
+  dataDir: string;
+  logger: Logger;
+};
+
+export type ArchivedStateBytes = {
+  stateBytes: Uint8Array;
+  metadata: StateBytesMetadata;
+  weakSubjectivity: WeakSubjectivitySummary;
+  isWithinWeakSubjectivityPeriod: boolean;
+};
+
+export type CheckpointStateBytesCandidate = {
+  stateBytes: Uint8Array;
+  expectedCheckpoint: Checkpoint | null;
+  source: "checkpoint file" | "checkpointSyncUrl" | "unfinalized source";
+};
+
+export type CheckpointStartupPolicy = {
+  isFinalized: boolean;
+  forceCheckpointSync: boolean;
+  ignoreWeakSubjectivityCheck: boolean;
+};
+
+/** Selected state bytes and source-specific initialization steps. */
+export type StateInitialization = {
+  stateBytes: Uint8Array;
+  config: BeaconConfig;
+  isFinalized: boolean;
+  validate: (state: IBeaconStateView) => void;
+  initializeEarliestAvailableSlot: (state: IBeaconStateView) => Promise<Slot>;
+  persist: ((state: IBeaconStateView, stateBytes: Uint8Array) => Promise<void>) | null;
+  log: (state: IBeaconStateView, nativeStateTransition: boolean) => void;
+};

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

@@ -0,0 +1,16 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {IBeaconStateView, computeStartSlotAtEpoch} from "@lodestar/state-transition";
+import {toHex} from "@lodestar/utils";
+import {StateInitializationError, StateInitializationErrorCode} from "./errors.js";
+
+export function assertAnchorStateForkMatchesConfig(config: ChainForkConfig, anchorState: IBeaconStateView): void {
+  const expectedFork = config.getForkInfo(computeStartSlotAtEpoch(anchorState.fork.epoch));
+  const expectedForkVersion = toHex(expectedFork.version);
+  const stateFork = toHex(anchorState.fork.currentVersion);
+  if (stateFork !== expectedForkVersion) {
+    throw new StateInitializationError(
+      {code: StateInitializationErrorCode.ANCHOR_STATE_FORK_MISMATCH},
+      `State current fork version ${stateFork} not equal to current config ${expectedForkVersion}. Maybe caused by importing a state from a different network`
+    );
+  }
+}