Post Merge checkpoint sync

besu/src/main/java/org/hyperledger/besu/cli/BesuCommand.java

@@ -84,6 +84,7 @@
 import org.hyperledger.besu.cli.util.CommandLineUtils;
 import org.hyperledger.besu.cli.util.ConfigOptionSearchAndRunHandler;
 import org.hyperledger.besu.cli.util.VersionProvider;
+import org.hyperledger.besu.config.CheckpointConfigOptions;
 import org.hyperledger.besu.config.GenesisConfigFile;
 import org.hyperledger.besu.config.GenesisConfigOptions;
 import org.hyperledger.besu.config.GoQuorumOptions;
@@ -1776,6 +1777,7 @@ private void validateOptions() {
     validateDnsOptionsParams();
     ensureValidPeerBoundParams();
     validateRpcOptionsParams();
+    validatePostMergeCheckpointBlockRequirements();
     p2pTLSConfigOptions.checkP2PTLSOptionsDependencies(logger, commandLine);
     pkiBlockCreationOptions.checkPkiBlockCreationOptionsDependencies(logger, commandLine);
   }
@@ -1988,6 +1990,12 @@ private void issueOptionWarnings() {
         !SyncMode.isFullSync(getDefaultSyncModeIfNotSet(syncMode)),
         singletonList("--fast-sync-min-peers"));
 
+    CommandLineUtils.failIfOptionDoesntMeetRequirement(
+        commandLine,
+        "--Xcheckpoint-post-merge-enabled can only be used with X_CHECKPOINT sync-mode",
+        SyncMode.X_CHECKPOINT.equals(getDefaultSyncModeIfNotSet(syncMode)),
+        singletonList("--Xcheckpoint-post-merge-enabled"));
+
     if (!securityModuleName.equals(DEFAULT_SECURITY_MODULE)
         && nodePrivateKeyFileOption.getNodePrivateKeyFile() != null) {
       logger.warn(
@@ -3328,6 +3336,39 @@ private void setMergeConfigOptions() {
             .isPresent());
   }
 
+  private void validatePostMergeCheckpointBlockRequirements() {
+    final GenesisConfigOptions genesisOptions =
+        Optional.ofNullable(genesisConfigOptions)
+            .orElseGet(
+                () ->
+                    GenesisConfigFile.fromConfig(
+                            genesisConfig(Optional.ofNullable(network).orElse(MAINNET)))
+                        .getConfigOptions(genesisConfigOverrides));
+    final SynchronizerConfiguration synchronizerConfiguration =
+        unstableSynchronizerOptions.toDomainObject().build();
+    final Optional<UInt256> terminalTotalDifficulty = genesisOptions.getTerminalTotalDifficulty();
+    final CheckpointConfigOptions checkpointConfigOptions = genesisOptions.getCheckpointOptions();
+    if (synchronizerConfiguration.isCheckpointPostMergeEnabled()) {
+      if (!checkpointConfigOptions.isValid()) {
+        throw new InvalidConfigurationException(
+            "Near head checkpoint sync requires a checkpoint block configured in the genesis file");
+      }
+      terminalTotalDifficulty.ifPresentOrElse(
+          value -> {
+            if (UInt256.fromHexString(
+                    genesisOptions.getCheckpointOptions().getTotalDifficulty().orElse("0x0"))
+                .lessOrEqualThan(value)) {
+              throw new InvalidConfigurationException(
+                  "Near head checkpoint sync requires a block with total difficulty greater than the TTD");
+            }
+          },
+          () -> {
+            throw new InvalidConfigurationException(
+                "Near head checkpoint sync requires TTD in the genesis file");
+          });
+    }
+  }
+
   private boolean isMergeEnabled() {
     return MergeConfigOptions.isMergeEnabled();
   }

besu/src/main/java/org/hyperledger/besu/cli/options/unstable/SynchronizerOptions.java

@@ -72,6 +72,8 @@ public class SynchronizerOptions implements CLIOptions<SynchronizerConfiguration
   private static final String SNAP_TRIENODE_COUNT_PER_REQUEST_FLAG =
       "--Xsnapsync-synchronizer-trienode-count-per-request";
 
+  private static final String CHECKPOINT_POST_MERGE_FLAG = "--Xcheckpoint-post-merge-enabled";
+
   @CommandLine.Option(
       names = BLOCK_PROPAGATION_RANGE_FLAG,
       hidden = true,
@@ -272,6 +274,13 @@ public void parseBlockPropagationRange(final String arg) {
   private int snapsyncTrieNodeCountPerRequest =
       SnapSyncConfiguration.DEFAULT_TRIENODE_COUNT_PER_REQUEST;
 
+  @CommandLine.Option(
+      names = {CHECKPOINT_POST_MERGE_FLAG},
+      hidden = true,
+      description = "Enable the sync to start from a post-merge block.")
+  private Boolean checkpointPostMergeSyncEnabled =
+      SynchronizerConfiguration.DEFAULT_CHECKPOINT_POST_MERGE_ENABLED;
+
   private SynchronizerOptions() {}
 
   public static SynchronizerOptions create() {
@@ -308,6 +317,7 @@ public static SynchronizerOptions fromConfig(final SynchronizerConfiguration con
         config.getSnapSyncConfiguration().getBytecodeCountPerRequest();
     options.snapsyncTrieNodeCountPerRequest =
         config.getSnapSyncConfiguration().getTrienodeCountPerRequest();
+    options.checkpointPostMergeSyncEnabled = config.isCheckpointPostMergeEnabled();
     return options;
   }
 
@@ -338,6 +348,7 @@ public SynchronizerConfiguration.Builder toDomainObject() {
             .bytecodeCountPerRequest(snapsyncBytecodeCountPerRequest)
             .trienodeCountPerRequest(snapsyncTrieNodeCountPerRequest)
             .build());
+    builder.checkpointPostMergeEnabled(checkpointPostMergeSyncEnabled);
 
     return builder;
   }

besu/src/main/java/org/hyperledger/besu/controller/BesuController.java

@@ -41,6 +41,7 @@
 import java.util.List;
 import java.util.Map;
 
+import org.apache.tuweni.units.bigints.UInt256;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -211,6 +212,10 @@ BesuControllerBuilder fromGenesisConfig(
         throw new IllegalArgumentException("Unknown consensus mechanism defined");
       }
 
+      if (isCheckpointBlockTotalDifficultyGreaterOrEqualThanTTD(configOptions)) {
+        return new MergeBesuControllerBuilder().genesisConfigFile(genesisConfig);
+      }
+
       // wrap with TransitionBesuControllerBuilder if we have a terminal total difficulty:
       if (configOptions.getTerminalTotalDifficulty().isPresent()) {
         // TODO this should be changed to vanilla MergeBesuControllerBuilder and the Transition*
@@ -258,5 +263,13 @@ private Long readQbftStartBlockConfig(final QbftConfigOptions qbftConfigOptions)
 
       return startBlock;
     }
+
+    private boolean isCheckpointBlockTotalDifficultyGreaterOrEqualThanTTD(
+        final GenesisConfigOptions configOptions) {
+      return configOptions.getTerminalTotalDifficulty().isPresent()
+          && configOptions.getCheckpointOptions().isValid()
+          && (UInt256.fromHexString(configOptions.getCheckpointOptions().getTotalDifficulty().get())
+              .greaterOrEqualThan(configOptions.getTerminalTotalDifficulty().get()));
+    }
   }
 }

besu/src/main/java/org/hyperledger/besu/controller/MergeBesuControllerBuilder.java

@@ -183,7 +183,8 @@ protected MergeContext createConsensusContext(
                     .get()
                     .getTerminalTotalDifficulty()
                     .map(Difficulty::of)
-                    .orElse(Difficulty.ZERO));
+                    .orElse(Difficulty.ZERO))
+            .setIsNearHeadCheckpointSync(syncConfig.isCheckpointPostMergeEnabled());
 
     blockchain
         .getFinalized()

besu/src/test/java/org/hyperledger/besu/cli/BesuCommandTest.java

@@ -105,6 +105,7 @@
 import java.net.ServerSocket;
 import java.net.URI;
 import java.net.URL;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
@@ -5441,6 +5442,64 @@ public void portInUseReportsError() throws IOException {
     serverSocket.close();
   }
 
+  @Test
+  public void checkpointPostMergeShouldFailWhenGenesisHasNoTTD() throws IOException {
+    final String configText =
+        Resources.toString(
+            Resources.getResource("invalid_post_merge_near_head_checkpoint.json"),
+            StandardCharsets.UTF_8);
+    final Path genesisFile = createFakeGenesisFile(new JsonObject(configText));
+
+    parseCommand(
+        "--genesis-file",
+        genesisFile.toString(),
+        "--sync-mode",
+        "X_CHECKPOINT",
+        "--Xcheckpoint-post-merge-enabled");
+
+    assertThat(commandOutput.toString(UTF_8)).isEmpty();
+    assertThat(commandErrorOutput.toString(UTF_8))
+        .contains("Near head checkpoint sync requires TTD in the genesis file");
+  }
+
+  @Test
+  public void checkpointPostMergeShouldFailWhenGenesisUsesCheckpointFromPreMerge() {
+    // using the default genesis which has a checkpoint sync block prior to the merge
+    parseCommand("--sync-mode", "X_CHECKPOINT", "--Xcheckpoint-post-merge-enabled");
+
+    assertThat(commandOutput.toString(UTF_8)).isEmpty();
+    assertThat(commandErrorOutput.toString(UTF_8))
+        .contains(
+            "Near head checkpoint sync requires a block with total difficulty greater than the TTD");
+  }
+
+  @Test
+  public void checkpointPostMergeShouldFailWhenSyncModeIsNotCheckpoint() {
+
+    parseCommand("--sync-mode", "X_SNAP", "--Xcheckpoint-post-merge-enabled");
+    assertThat(commandErrorOutput.toString(UTF_8))
+        .contains("--Xcheckpoint-post-merge-enabled can only be used with X_CHECKPOINT sync-mode");
+  }
+
+  @Test
+  public void checkpointPostMergeWithPostMergeBlockSucceeds() throws IOException {
+    final String configText =
+        Resources.toString(
+            Resources.getResource("valid_post_merge_near_head_checkpoint.json"),
+            StandardCharsets.UTF_8);
+    final Path genesisFile = createFakeGenesisFile(new JsonObject(configText));
+
+    parseCommand(
+        "--genesis-file",
+        genesisFile.toString(),
+        "--sync-mode",
+        "X_CHECKPOINT",
+        "--Xcheckpoint-post-merge-enabled");
+
+    assertThat(commandOutput.toString(UTF_8)).isEmpty();
+    assertThat(commandErrorOutput.toString(UTF_8)).isEmpty();
+  }
+
   @Test
   public void presentRequiredOptionShouldPass() {
     parseCommandWithRequiredOption("--accept-terms-and-conditions", "true");