feat: add option to force checkpoint sync (#5652)

docs/usage/beacon-management.md

@@ -120,6 +120,15 @@ In case you really trust `checkpointSyncUrl` then you may skip providing `wssChe
 If possible, validate your `wssCheckpoint` from multiple places (e.g. different client distributions) or from other trusted sources. This will highly reduce the risk of starting off on a malicious chain.
 <!-- prettier-ignore-end -->
 
+**Taking too long to sync?**
+
+After your node has been offline for a while, it might be the case that it takes a long time to sync even though a `checkpointSyncUrl` is specified.
+This is due to the fact that the last db state is still within the weak subjectivity period (~15 days on mainnet) which causes the node
+to sync from the db state instead of the checkpoint state.
+
+It is possible to force syncing from checkpoint state by supplying the `--forceCheckpointSync` flag. This option is only recommended if it is absolutely
+necessary for the node to be synced right away to fulfill its duties as there is an inherent risk each time the state is obtained from an external source.
+
 ### Guide to the sync logs
 
 Lodestar beacon sync log aims to provide information of utmost importance  about your node and yet be suucint at the same time. You may see the sync logs in the following format:

packages/cli/src/cmds/beacon/initBeaconState.ts

@@ -84,22 +84,36 @@ export async function initBeaconState(
   logger: Logger,
   signal: AbortSignal
 ): Promise<{anchorState: BeaconStateAllForks; wsCheckpoint?: Checkpoint}> {
+  if (args.forceCheckpointSync && !(args.checkpointState || args.checkpointSyncUrl)) {
+    throw new Error("Forced checkpoint sync without specifying a checkpointState or checkpointSyncUrl");
+  }
   // fetch the latest state stored in the db which will be used in all cases, if it exists, either
   //   i)  used directly as the anchor state
   //   ii) used during verification of a weak subjectivity state,
   const lastDbState = await db.stateArchive.lastValue();
   if (lastDbState) {
     const config = createBeaconConfig(chainForkConfig, lastDbState.genesisValidatorsRoot);
     const wssCheck = isWithinWeakSubjectivityPeriod(config, lastDbState, getCheckpointFromState(lastDbState));
-    // All cases when we want to directly use lastDbState as the anchor state:
-    //  - if no checkpoint sync args provided, or
-    //  - the lastDbState is within weak subjectivity period:
-    if ((!args.checkpointState && !args.checkpointSyncUrl) || wssCheck) {
-      const anchorState = await initStateFromAnchorState(config, db, logger, lastDbState, {
-        isWithinWeakSubjectivityPeriod: wssCheck,
-        isCheckpointState: false,
-      });
-      return {anchorState};
+
+    // Explicitly force syncing from checkpoint state
+    if (args.forceCheckpointSync) {
+      // Forcing to sync from checkpoint is only recommended if node is taking too long to sync from last db state.
+      // It is important to remind the user to remove this flag again unless it is absolutely necessary.
+      if (wssCheck) {
+        logger.warn("Forced syncing from checkpoint even though db state is within weak subjectivity period");
+        logger.warn("Please consider removing --forceCheckpointSync flag unless absolutely necessary");
+      }
+    } else {
+      // All cases when we want to directly use lastDbState as the anchor state:
+      //  - if no checkpoint sync args provided, or
+      //  - the lastDbState is within weak subjectivity period:
+      if ((!args.checkpointState && !args.checkpointSyncUrl) || wssCheck) {
+        const anchorState = await initStateFromAnchorState(config, db, logger, lastDbState, {
+          isWithinWeakSubjectivityPeriod: wssCheck,
+          isCheckpointState: false,
+        });
+        return {anchorState};
+      }
     }
   }
 

packages/cli/src/cmds/beacon/options.ts

@@ -12,6 +12,7 @@ type BeaconExtraArgs = {
   checkpointSyncUrl?: string;
   checkpointState?: string;
   wssCheckpoint?: string;
+  forceCheckpointSync?: boolean;
   beaconDir?: string;
   dbDir?: string;
   persistInvalidSszObjectsDir?: string;
@@ -66,6 +67,13 @@ export const beaconExtraOptions: CliCommandOptions<BeaconExtraArgs> = {
     group: "weak subjectivity",
   },
 
+  forceCheckpointSync: {
+    description:
+      "Force syncing from checkpoint state even if db state is within weak subjectivity period. This helps to avoid long sync times after node has been offline for a while.",
+    type: "boolean",
+    group: "weak subjectivity",
+  },
+
   beaconDir: {
     description: "Beacon root directory",
     defaultDescription: defaultBeaconPaths.beaconDir,