Add configuration options for BAL-related parameters

app/src/main/java/org/hyperledger/besu/RunnerBuilder.java

@@ -70,6 +70,7 @@
 import org.hyperledger.besu.ethereum.eth.manager.EthPeers;
 import org.hyperledger.besu.ethereum.eth.manager.EthScheduler;
 import org.hyperledger.besu.ethereum.eth.transactions.TransactionPool;
+import org.hyperledger.besu.ethereum.mainnet.BalConfiguration;
 import org.hyperledger.besu.ethereum.mainnet.ProtocolSchedule;
 import org.hyperledger.besu.ethereum.p2p.config.DiscoveryConfiguration;
 import org.hyperledger.besu.ethereum.p2p.config.NetworkingConfiguration;
@@ -170,6 +171,7 @@ public class RunnerBuilder {
   private WebSocketConfiguration webSocketConfiguration;
   private InProcessRpcConfiguration inProcessRpcConfiguration;
   private ApiConfiguration apiConfiguration;
+  private BalConfiguration balConfiguration = BalConfiguration.DEFAULT;
   private Path dataDir;
   private Optional<Path> pidPath = Optional.empty();
   private MetricsConfiguration metricsConfiguration;
@@ -393,6 +395,17 @@ public RunnerBuilder apiConfiguration(final ApiConfiguration apiConfiguration) {
     return this;
   }
 
+  /**
+   * Sets the block access list configuration.
+   *
+   * @param balConfiguration the BAL configuration
+   * @return the runner builder
+   */
+  public RunnerBuilder balConfiguration(final BalConfiguration balConfiguration) {
+    this.balConfiguration = balConfiguration;
+    return this;
+  }
+
   /**
    * Add Permissioning configuration.
    *
@@ -1260,6 +1273,7 @@ private Map<String, JsonRpcMethod> jsonRpcMethods(
                 besuController.getProtocolManager().ethContext().getEthPeers(),
                 consensusEngineServer,
                 apiConfiguration,
+                balConfiguration,
                 enodeDnsConfiguration,
                 transactionSimulator,
                 ethScheduler);

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

@@ -42,6 +42,7 @@
 import org.hyperledger.besu.cli.error.BesuExecutionExceptionHandler;
 import org.hyperledger.besu.cli.error.BesuParameterExceptionHandler;
 import org.hyperledger.besu.cli.options.ApiConfigurationOptions;
+import org.hyperledger.besu.cli.options.BalConfigurationOptions;
 import org.hyperledger.besu.cli.options.ChainPruningOptions;
 import org.hyperledger.besu.cli.options.DebugTracerOptions;
 import org.hyperledger.besu.cli.options.DnsOptions;
@@ -122,6 +123,7 @@
 import org.hyperledger.besu.ethereum.eth.sync.SynchronizerConfiguration;
 import org.hyperledger.besu.ethereum.eth.transactions.ImmutableTransactionPoolConfiguration;
 import org.hyperledger.besu.ethereum.eth.transactions.TransactionPoolConfiguration;
+import org.hyperledger.besu.ethereum.mainnet.BalConfiguration;
 import org.hyperledger.besu.ethereum.p2p.config.DiscoveryConfiguration;
 import org.hyperledger.besu.ethereum.p2p.discovery.P2PDiscoveryConfiguration;
 import org.hyperledger.besu.ethereum.p2p.peers.EnodeDnsConfiguration;
@@ -601,6 +603,9 @@ void setUserName(final String userName) {
   @CommandLine.ArgGroup(validate = false, heading = "@|bold API Configuration Options|@%n")
   ApiConfigurationOptions apiConfigurationOptions = new ApiConfigurationOptions();
 
+  @CommandLine.ArgGroup(validate = false, heading = "@|bold Block Access List Options|@%n")
+  BalConfigurationOptions balConfigurationOptions = new BalConfigurationOptions();
+
   @CommandLine.Option(
       names = {"--static-nodes-file"},
       paramLabel = MANDATORY_FILE_FORMAT_HELP,
@@ -1241,6 +1246,7 @@ private Runner buildRunner() {
         jsonRpcIpcConfiguration,
         inProcessRpcConfiguration,
         apiConfigurationSupplier.get(),
+        balConfigurationOptions.toDomainObject(),
         metricsConfiguration,
         permissioningConfiguration,
         staticNodes,
@@ -1811,6 +1817,9 @@ public BesuControllerBuilder setupControllerBuilder() {
         .withMiningParameters(miningParametersSupplier.get())
         .withJsonRpcHttpOptions(jsonRpcHttpOptions);
     final KeyValueStorageProvider storageProvider = keyValueStorageProvider(keyValueStorageName);
+    final ApiConfiguration apiConfiguration = apiConfigurationSupplier.get();
+    final BalConfiguration balConfiguration = balConfigurationOptions.toDomainObject();
+
     BesuControllerBuilder besuControllerBuilder =
         controllerBuilder
             .fromEthNetworkConfig(updateNetworkConfig(network), getDefaultSyncModeIfNotSet())
@@ -1839,16 +1848,15 @@ public BesuControllerBuilder setupControllerBuilder() {
             .cacheLastBlockHeaders(numberOfBlockHeadersToCache)
             .isCacheLastBlockHeadersPreloadEnabled(isCacheLastBlockHeadersPreloadEnabled)
             .genesisStateHashCacheEnabled(genesisStateHashCacheEnabled)
-            .apiConfiguration(apiConfigurationSupplier.get())
+            .apiConfiguration(apiConfiguration)
+            .balConfiguration(balConfiguration)
             .besuComponent(besuComponent);
     if (DataStorageFormat.BONSAI.equals(getDataStorageConfiguration().getDataStorageFormat())) {
       final PathBasedExtraStorageConfiguration subStorageConfiguration =
           getDataStorageConfiguration().getPathBasedExtraStorageConfiguration();
       besuControllerBuilder.isParallelTxProcessingEnabled(
           subStorageConfiguration.getParallelTxProcessingEnabled());
     }
-    besuControllerBuilder.isBlockAccessListEnabled(
-        apiConfigurationOptions.apiConfiguration().isBlockAccessListEnabled());
     return besuControllerBuilder;
   }
 
@@ -2112,6 +2120,7 @@ private Runner synchronize(
       final JsonRpcIpcConfiguration jsonRpcIpcConfiguration,
       final InProcessRpcConfiguration inProcessRpcConfiguration,
       final ApiConfiguration apiConfiguration,
+      final BalConfiguration balConfiguration,
       final MetricsConfiguration metricsConfiguration,
       final Optional<PermissioningConfiguration> permissioningConfiguration,
       final Collection<EnodeURL> staticNodes,
@@ -2140,6 +2149,7 @@ private Runner synchronize(
             .jsonRpcIpcConfiguration(jsonRpcIpcConfiguration)
             .inProcessRpcConfiguration(inProcessRpcConfiguration)
             .apiConfiguration(apiConfiguration)
+            .balConfiguration(balConfiguration)
             .pidPath(pidPath)
             .dataDir(dataDir())
             .bannedNodeIds(p2PDiscoveryConfig.bannedNodeIds())
@@ -2587,6 +2597,9 @@ private Boolean getDefaultVersionCompatibilityProtectionIfNotSet() {
   private String generateConfigurationOverview() {
     final ConfigurationOverviewBuilder builder = new ConfigurationOverviewBuilder(logger);
 
+    final BalConfiguration balConfiguration = balConfigurationOptions.toDomainObject();
+    builder.setBalConfiguration(balConfiguration);
+
     if (environment != null) {
       builder.setEnvironment(environment);
     }

app/src/main/java/org/hyperledger/besu/cli/ConfigurationOverviewBuilder.java

@@ -15,6 +15,7 @@
 package org.hyperledger.besu.cli;
 
 import org.hyperledger.besu.ethereum.eth.transactions.TransactionPoolConfiguration;
+import org.hyperledger.besu.ethereum.mainnet.BalConfiguration;
 import org.hyperledger.besu.evm.internal.EvmConfiguration;
 import org.hyperledger.besu.plugin.services.storage.rocksdb.configuration.RocksDBCLIOptions;
 import org.hyperledger.besu.services.BesuPluginContextImpl;
@@ -23,6 +24,7 @@
 import org.hyperledger.besu.util.platform.PlatformDetector;
 
 import java.math.BigInteger;
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
@@ -69,6 +71,10 @@ public class ConfigurationOverviewBuilder {
   private boolean isParallelTxProcessingEnabled = false;
   private RocksDBCLIOptions.BlobDBSettings blobDBSettings;
   private Long targetGasLimit;
+  private boolean isBalOptimizationEnabled = true;
+  private boolean isBalLenientOnMismatch = false;
+  private boolean isBalApiEnabled = false;
+  private Duration balStateRootTimeout = Duration.ofSeconds(1);
 
   /**
    * Create a new ConfigurationOverviewBuilder.
@@ -381,6 +387,20 @@ public ConfigurationOverviewBuilder setTargetGasLimit(final Long targetGasLimit)
     return this;
   }
 
+  /**
+   * Sets the BAL configuration.
+   *
+   * @param balConfiguration the BAL configuration
+   * @return the builder
+   */
+  public ConfigurationOverviewBuilder setBalConfiguration(final BalConfiguration balConfiguration) {
+    this.isBalOptimizationEnabled = balConfiguration.isBalOptimisationEnabled();
+    this.isBalLenientOnMismatch = balConfiguration.isBalLenientOnMismatch();
+    this.isBalApiEnabled = balConfiguration.isBalApiEnabled();
+    this.balStateRootTimeout = balConfiguration.getBalStateRootTimeout();
+    return this;
+  }
+
   /**
    * Build configuration overview.
    *
@@ -453,6 +473,11 @@ public String build() {
       lines.add("Parallel transaction processing disabled");
     }
 
+    lines.add("BAL optimizations " + (isBalOptimizationEnabled ? "enabled" : "disabled"));
+    lines.add("BAL mismatch leniency " + (isBalLenientOnMismatch ? "enabled" : "disabled"));
+    lines.add("BAL API " + (isBalApiEnabled ? "enabled" : "disabled"));
+    lines.add("BAL state root timeout: " + balStateRootTimeout.toMillis() + " ms");
+
     if (isLimitTrieLogsEnabled) {
       final StringBuilder trieLogPruningString = new StringBuilder();
       trieLogPruningString

app/src/main/java/org/hyperledger/besu/cli/options/ApiConfigurationOptions.java

@@ -60,13 +60,6 @@ public ApiConfigurationOptions() {}
           "Set to enable gas price and minimum priority fee limit in eth_getGasPrice and eth_feeHistory (default: ${DEFAULT-VALUE})")
   private final Boolean apiGasAndPriorityFeeLimitingEnabled = false;
 
-  @CommandLine.Option(
-      names = {"--Xapi-block-access-list-enabled"},
-      hidden = true,
-      description =
-          "Set to enable eth_getBlockAccessListByNumber method and Block Access Lists in simulation results")
-  private final Boolean apiBlockAccessListEnabled = false;
-
   @CommandLine.Option(
       names = {"--api-gas-and-priority-fee-lower-bound-coefficient"},
       hidden = true,
@@ -144,8 +137,7 @@ public ApiConfiguration apiConfiguration() {
             .maxLogsRange(rpcMaxLogsRange)
             .gasCap(rpcGasCap)
             .isGasAndPriorityFeeLimitingEnabled(apiGasAndPriorityFeeLimitingEnabled)
-            .maxTraceFilterRange(maxTraceFilterRange)
-            .isBlockAccessListEnabled(apiBlockAccessListEnabled);
+            .maxTraceFilterRange(maxTraceFilterRange);
     if (apiGasAndPriorityFeeLimitingEnabled) {
       builder
           .lowerBoundGasAndPriorityFeeCoefficient(apiGasAndPriorityFeeLowerBoundCoefficient)

app/src/main/java/org/hyperledger/besu/cli/options/BalConfigurationOptions.java

@@ -0,0 +1,69 @@
+/*
+ * Copyright contributors to Hyperledger Besu.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.cli.options;
+
+import org.hyperledger.besu.ethereum.mainnet.BalConfiguration;
+import org.hyperledger.besu.ethereum.mainnet.ImmutableBalConfiguration;
+
+import java.time.Duration;
+
+import picocli.CommandLine;
+
+/** Command-line options for configuring Block Access List behaviour. */
+public class BalConfigurationOptions {
+  /** Default constructor. */
+  public BalConfigurationOptions() {}
+
+  @CommandLine.Option(
+      names = {"--Xbal-optimization-enabled"},
+      hidden = true,
+      description = "Allows disabling BAL-based optimizations.")
+  boolean balOptimizationEnabled = true;
+
+  @CommandLine.Option(
+      names = {"--Xbal-lenient-on-mismatch"},
+      hidden = true,
+      description =
+          "Log an error instead of throwing when the BAL-computed state root does not match the synchronously computed root.")
+  boolean balLenientOnMismatch = true;
+
+  @CommandLine.Option(
+      names = {"--Xbal-api-enabled"},
+      hidden = true,
+      description =
+          "Set to enable eth_getBlockAccessListByNumber method and Block Access Lists in simulation results")
+  private final Boolean balApiEnabled = false;
+
+  @CommandLine.Option(
+      names = {"--Xbal-state-root-timeout"},
+      hidden = true,
+      paramLabel = "<INTEGER>",
+      description = "Timeout in milliseconds when waiting for the BAL-computed state root.")
+  private long balStateRootTimeoutMs = Duration.ofSeconds(1).toMillis();
+
+  /**
+   * Builds the immutable {@link BalConfiguration} corresponding to the parsed CLI options.
+   *
+   * @return an immutable BAL configuration reflecting the current option values
+   */
+  public BalConfiguration toDomainObject() {
+    return ImmutableBalConfiguration.builder()
+        .isBalApiEnabled(balApiEnabled)
+        .isBalOptimisationEnabled(balOptimizationEnabled)
+        .isBalLenientOnMismatch(balLenientOnMismatch)
+        .balStateRootTimeout(Duration.ofMillis(balStateRootTimeoutMs))
+        .build();
+  }
+}

app/src/main/java/org/hyperledger/besu/controller/BesuControllerBuilder.java

@@ -78,6 +78,7 @@
 import org.hyperledger.besu.ethereum.eth.transactions.TransactionPoolConfiguration;
 import org.hyperledger.besu.ethereum.eth.transactions.TransactionPoolFactory;
 import org.hyperledger.besu.ethereum.forkid.ForkIdManager;
+import org.hyperledger.besu.ethereum.mainnet.BalConfiguration;
 import org.hyperledger.besu.ethereum.mainnet.ProtocolSchedule;
 import org.hyperledger.besu.ethereum.mainnet.ProtocolSpec;
 import org.hyperledger.besu.ethereum.p2p.config.NetworkingConfiguration;
@@ -214,8 +215,8 @@ public abstract class BesuControllerBuilder implements MiningParameterOverrides
   /** whether parallel transaction processing is enabled or not */
   protected boolean isParallelTxProcessingEnabled;
 
-  /** whether block access list functionality was enabled via CLI feature flag */
-  protected boolean isBlockAccessListEnabled;
+  /** Configuration flags related to block access lists. */
+  protected BalConfiguration balConfiguration = BalConfiguration.DEFAULT;
 
   /** The API configuration */
   protected ApiConfiguration apiConfiguration;
@@ -566,15 +567,13 @@ public BesuControllerBuilder isParallelTxProcessingEnabled(
   }
 
   /**
-   * Sets whether functionality related to testing block-level access list implementation should be
-   * enabled. This includes caching of block-level access lists produced during block processing and
-   * enabling an RPC endpoint serving those cached BALs.
+   * Sets configuration for functionality related to block-level access lists.
    *
-   * @param isBlockAccessListEnabled true to enable block-level access list testing functionality
+   * @param balConfiguration configuration related to block access lists
    * @return the besu controller
    */
-  public BesuControllerBuilder isBlockAccessListEnabled(final boolean isBlockAccessListEnabled) {
-    this.isBlockAccessListEnabled = isBlockAccessListEnabled;
+  public BesuControllerBuilder balConfiguration(final BalConfiguration balConfiguration) {
+    this.balConfiguration = balConfiguration;
     return this;
   }
 

app/src/main/java/org/hyperledger/besu/controller/CliqueBesuControllerBuilder.java

@@ -136,7 +136,7 @@ protected ProtocolSchedule createProtocolSchedule() {
         miningConfiguration,
         badBlockManager,
         isParallelTxProcessingEnabled,
-        isBlockAccessListEnabled,
+        balConfiguration,
         metricsSystem);
   }
 

app/src/main/java/org/hyperledger/besu/controller/ConsensusScheduleBesuControllerBuilder.java

@@ -46,6 +46,7 @@
 import org.hyperledger.besu.ethereum.eth.transactions.TransactionPool;
 import org.hyperledger.besu.ethereum.eth.transactions.TransactionPoolConfiguration;
 import org.hyperledger.besu.ethereum.forkid.ForkIdManager;
+import org.hyperledger.besu.ethereum.mainnet.BalConfiguration;
 import org.hyperledger.besu.ethereum.mainnet.ProtocolSchedule;
 import org.hyperledger.besu.ethereum.p2p.config.SubProtocolConfiguration;
 import org.hyperledger.besu.ethereum.storage.StorageProvider;
@@ -379,11 +380,9 @@ public BesuControllerBuilder isParallelTxProcessingEnabled(
   }
 
   @Override
-  public BesuControllerBuilder isBlockAccessListEnabled(final boolean isBlockAccessListEnabled) {
-    besuControllerBuilderSchedule
-        .values()
-        .forEach(b -> b.isBlockAccessListEnabled(isBlockAccessListEnabled));
-    return super.isBlockAccessListEnabled(isBlockAccessListEnabled);
+  public BesuControllerBuilder balConfiguration(final BalConfiguration balConfiguration) {
+    besuControllerBuilderSchedule.values().forEach(b -> b.balConfiguration(balConfiguration));
+    return super.balConfiguration(balConfiguration);
   }
 
   @Override

app/src/main/java/org/hyperledger/besu/controller/IbftBesuControllerBuilder.java

@@ -306,7 +306,7 @@ protected ProtocolSchedule createProtocolSchedule() {
         miningConfiguration,
         badBlockManager,
         isParallelTxProcessingEnabled,
-        isBlockAccessListEnabled,
+        balConfiguration,
         metricsSystem);
   }
 

app/src/main/java/org/hyperledger/besu/controller/MainnetBesuControllerBuilder.java

@@ -101,7 +101,7 @@ protected ProtocolSchedule createProtocolSchedule() {
         super.miningConfiguration,
         badBlockManager,
         isParallelTxProcessingEnabled,
-        isBlockAccessListEnabled,
+        balConfiguration,
         metricsSystem);
   }
 

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

@@ -181,7 +181,7 @@ protected ProtocolSchedule createProtocolSchedule() {
         miningConfiguration,
         badBlockManager,
         isParallelTxProcessingEnabled,
-        isBlockAccessListEnabled,
+        balConfiguration,
         metricsSystem,
         evmConfiguration);
   }

app/src/main/java/org/hyperledger/besu/controller/QbftBesuControllerBuilder.java

@@ -368,7 +368,7 @@ protected ProtocolSchedule createProtocolSchedule() {
         miningConfiguration,
         badBlockManager,
         isParallelTxProcessingEnabled,
-        isBlockAccessListEnabled,
+        balConfiguration,
         metricsSystem);
   }