javadoc - Add missing javadoc for evmtool module (hyperledger#7277)

Signed-off-by: Usman Saleem <[email protected]>

build.gradle

@@ -401,8 +401,6 @@ allprojects {
       '-org.hyperledger.besu.ethereum.eth.*,' +
       '-org.hyperledger.besu.ethereum.eth,' +
       '-org.hyperledger.besu.consensus.merge,' +
-      // evmtool module
-      '-org.hyperledger.besu.evmtool,' +
       // p2p module
       '-org.hyperledger.besu.ethereum.p2p,' +
       '-org.hyperledger.besu.ethereum.p2p.*,' +

ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/B11rSubCommand.java

@@ -51,6 +51,11 @@
 import picocli.CommandLine.Parameters;
 import picocli.CommandLine.ParentCommand;
 
+/**
+ * This class implements the Runnable interface and represents the B11rSubCommand. It is responsible
+ * for handling the block builder subcommand in the EVM tool. It provides methods to read headers,
+ * move fields, and run the command.
+ */
 @Command(
     name = COMMAND_NAME,
     aliases = {COMMAND_ALIAS},
@@ -138,12 +143,18 @@ public void consumeParameters(
     }
   }
 
+  /** Default constructor for the B11rSubCommand class. This is required by PicoCLI. */
   @SuppressWarnings("unused")
   public B11rSubCommand() {
     // PicoCLI requires this
     parentCommand = null;
   }
 
+  /**
+   * Constructs a new B11rSubCommand with the given parent command.
+   *
+   * @param parentCommand the parent command of this subcommand
+   */
   @SuppressWarnings("unused")
   public B11rSubCommand(final EvmToolCommand parentCommand) {
     // PicoCLI requires this too

ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/BenchmarkSubCommand.java

@@ -33,13 +33,22 @@
 import picocli.CommandLine.Parameters;
 import picocli.CommandLine.ParentCommand;
 
+/**
+ * This class represents the BenchmarkSubCommand. It is responsible for executing an Ethereum State
+ * Test.
+ */
 @CommandLine.Command(
     name = COMMAND_NAME,
     description = "Execute an Ethereum State Test.",
     mixinStandardHelpOptions = true,
     versionProvider = VersionProvider.class)
 public class BenchmarkSubCommand implements Runnable {
+  /**
+   * The command name for the BenchmarkSubCommand. This constant is used as the name attribute in
+   * the {@code CommandLine.Command} annotation.
+   */
   public static final String COMMAND_NAME = "benchmark";
+
   private final PrintStream output;
 
   enum Benchmark {
@@ -68,11 +77,17 @@ enum Benchmark {
 
   @ParentCommand EvmToolCommand parentCommand;
 
+  /** Default constructor for the BenchmarkSubCommand class. This is required by PicoCLI. */
   public BenchmarkSubCommand() {
     // PicoCLI requires this
     this(System.out);
   }
 
+  /**
+   * Constructs a new BenchmarkSubCommand with the given output stream.
+   *
+   * @param output the output stream to be used
+   */
   public BenchmarkSubCommand(final PrintStream output) {
     this.output = output;
   }

ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/BlockchainModule.java

@@ -39,10 +39,18 @@
 import dagger.Provides;
 import org.apache.tuweni.bytes.Bytes32;
 
+/**
+ * This class is a Dagger module that provides dependencies related to the blockchain. It includes
+ * the GenesisFileModule and DataStoreModule for providing the genesis block and data store
+ * respectively. The class is annotated with {@code @Module} to indicate that it is a Dagger module.
+ */
 @SuppressWarnings("WeakerAccess")
 @Module(includes = {GenesisFileModule.class, DataStoreModule.class})
 public class BlockchainModule {
 
+  /** Default constructor for the BlockchainModule class. */
+  public BlockchainModule() {}
+
   @Singleton
   @Provides
   Blockchain provideBlockchain(

ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/CodeValidateSubCommand.java

@@ -40,13 +40,22 @@
 import picocli.CommandLine;
 import picocli.CommandLine.ParentCommand;
 
+/**
+ * This class represents the CodeValidateSubCommand. It is responsible for validating EVM code for
+ * fuzzing. It implements the Runnable interface and is annotated with the {@code
+ * CommandLine.Command} annotation.
+ */
 @SuppressWarnings({"ConstantValue", "DataFlowIssue"})
 @CommandLine.Command(
     name = COMMAND_NAME,
     description = "Validates EVM code for fuzzing",
     mixinStandardHelpOptions = true,
     versionProvider = VersionProvider.class)
 public class CodeValidateSubCommand implements Runnable {
+  /**
+   * The command name for the CodeValidateSubCommand. This constant is used as the name attribute in
+   * the CommandLine.Command annotation.
+   */
   public static final String COMMAND_NAME = "code-validate";
 
   @ParentCommand EvmToolCommand parentCommand;
@@ -62,6 +71,7 @@ public class CodeValidateSubCommand implements Runnable {
   @CommandLine.Parameters
   private final List<String> cliCode = new ArrayList<>();
 
+  /** Default constructor for the CodeValidateSubCommand class. This is required by PicoCLI. */
   @SuppressWarnings("unused")
   public CodeValidateSubCommand() {
     // PicoCLI requires this
@@ -111,6 +121,18 @@ private void checkCodeFromBufferedReader(final BufferedReader in) {
     }
   }
 
+  /**
+   * This method is responsible for validating the EVM code. It takes a hexadecimal string
+   * representation of the EVM code as input. The method first converts the hexadecimal string to
+   * Bytes. It then checks if the code follows the EOF layout. If the layout is valid, it retrieves
+   * the code from the EVM. If the code is invalid, it returns an error message with the reason for
+   * the invalidity. If the code is valid, it returns a string with "OK" followed by the hexadecimal
+   * string representation of each code section.
+   *
+   * @param hexCode the hexadecimal string representation of the EVM code
+   * @return a string indicating whether the code is valid or not, and in case of validity, the
+   *     hexadecimal string representation of each code section
+   */
   public String considerCode(final String hexCode) {
     Bytes codeBytes;
     try {

ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/DataStoreModule.java

@@ -38,6 +38,14 @@
 import dagger.Module;
 import dagger.Provides;
 
+/**
+ * This class is a Dagger module that provides dependencies related to the data store. It includes
+ * the GenesisFileModule for providing the genesis block. The class is annotated with
+ * {@code @Module} to indicate that it is a Dagger module. It provides various key-value storages
+ * such as variables, blockchain, world state, world state preimage, and pruning. The type of
+ * key-value storage (e.g., rocksdb, memory) can be specified. The class also provides a
+ * BlockchainStorage which is a prefixed key blockchain storage.
+ */
 @SuppressWarnings({"CloseableProvides"})
 @Module(includes = GenesisFileModule.class)
 public class DataStoreModule {
@@ -50,6 +58,9 @@ public class DataStoreModule {
                   List.of(KeyValueSegmentIdentifier.values()),
                   RocksDBMetricsFactory.PUBLIC_ROCKS_DB_METRICS));
 
+  /** Default constructor for the DataStoreModule class. */
+  public DataStoreModule() {}
+
   @Provides
   @Singleton
   @Named("variables")

ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EOFTestSubCommand.java

@@ -45,13 +45,16 @@
 import org.apache.tuweni.bytes.Bytes;
 import picocli.CommandLine;
 
+/** A PicoCli annotated command for running EOF validation reference tests. */
 @CommandLine.Command(
     name = COMMAND_NAME,
     description = "Runs EOF validation reference tests",
     mixinStandardHelpOptions = true,
     versionProvider = VersionProvider.class)
 public class EOFTestSubCommand implements Runnable {
+  /** The name of the EOF validation reference test command. */
   public static final String COMMAND_NAME = "eof-test";
+
   @CommandLine.ParentCommand private final EvmToolCommand parentCommand;
 
   // picocli does it magically
@@ -65,10 +68,16 @@ public class EOFTestSubCommand implements Runnable {
   EVM evm;
   String fork = null;
 
+  /** Default constructor for the EOFTestSubCommand class. Sets the parent command to null. */
   public EOFTestSubCommand() {
     this(null);
   }
 
+  /**
+   * Constructor for the EOFTestSubCommand class with a parent command.
+   *
+   * @param parentCommand The parent command for this sub command.
+   */
   public EOFTestSubCommand(final EvmToolCommand parentCommand) {
     this.parentCommand = parentCommand;
   }
@@ -199,6 +208,12 @@ private void executeEOFTest(final String fileName, final Map<String, EOFTestCase
     }
   }
 
+  /**
+   * Considers the given hexadecimal code string for EOF validation.
+   *
+   * @param hexCode The hexadecimal string representation of the code to be considered.
+   * @return The result of the EOF validation test.
+   */
   public TestResult considerCode(final String hexCode) {
     Bytes codeBytes;
     try {

ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmTool.java

@@ -16,8 +16,17 @@
 
 import org.hyperledger.besu.util.LogConfigurator;
 
+/** The main entry point for the EVM (Ethereum Virtual Machine) tool. */
 public final class EvmTool {
 
+  /** Default constructor for the EvmTool class. */
+  public EvmTool() {}
+
+  /**
+   * The main entry point for the EVM (Ethereum Virtual Machine) tool.
+   *
+   * @param args The command line arguments.
+   */
   public static void main(final String... args) {
     LogConfigurator.setLevel("", "DEBUG");
     final EvmToolCommand evmToolCommand = new EvmToolCommand();

ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmToolCommand.java

@@ -70,6 +70,21 @@
 import picocli.CommandLine.Command;
 import picocli.CommandLine.Option;
 
+/**
+ * This class, EvmToolCommand, serves as the main command for the EVM (Ethereum Virtual Machine)
+ * tool. The EVM tool is used to execute Ethereum transactions and contracts in a local environment.
+ *
+ * <p>EvmToolCommand implements the Runnable interface, making it the entrypoint for PicoCLI to
+ * execute this command.
+ *
+ * <p>The class provides various options for setting up and executing EVM transactions. These
+ * options include, but are not limited to, setting the gas price, sender address, receiver address,
+ * and the data to be sent with the transaction.
+ *
+ * <p>Key methods in this class include 'run()' for executing the command, 'execute()' for setting
+ * up and running the EVM transaction, and 'dumpWorldState()' for outputting the current state of
+ * the Ethereum world state.
+ */
 @Command(
     description = "This command evaluates EVM transactions.",
     abbreviateSynopsis = true,
@@ -247,12 +262,22 @@ void setBytes(final String optionValue) {
   PrintWriter out;
   InputStream in;
 
+  /**
+   * Default constructor for the EvmToolCommand class. It initializes the input stream with an empty
+   * byte array and the output stream with the standard output.
+   */
   public EvmToolCommand() {
     this(
         new ByteArrayInputStream(new byte[0]),
         new PrintWriter(new BufferedWriter(new OutputStreamWriter(System.out, UTF_8)), true));
   }
 
+  /**
+   * Constructor for the EvmToolCommand class with custom input and output streams.
+   *
+   * @param in The input stream to be used.
+   * @param out The output stream to be used.
+   */
   public EvmToolCommand(final InputStream in, final PrintWriter out) {
     this.in = in;
     this.out = out;
@@ -322,10 +347,21 @@ private static void addForkHelp(final CommandLine subCommandLine) {
     subCommandLine.setHelpSectionKeys(keys);
   }
 
+  /**
+   * Returns the fork name provided by the Dagger options. If no fork is provided, it returns the
+   * name of the default EVM specification version.
+   *
+   * @return The fork name.
+   */
   public String getFork() {
     return daggerOptions.provideFork().orElse(EvmSpecVersion.defaultVersion().getName());
   }
 
+  /**
+   * Checks if a fork is provided in the Dagger options.
+   *
+   * @return True if a fork is provided, false otherwise.
+   */
   public boolean hasFork() {
     return daggerOptions.provideFork().isPresent();
   }
@@ -506,6 +542,13 @@ public void run() {
     }
   }
 
+  /**
+   * Dumps the current state of the Ethereum world state to the provided PrintWriter. The state
+   * includes account balances, nonces, codes, and storage. The output is in JSON format.
+   *
+   * @param worldState The Ethereum world state to be dumped.
+   * @param out The PrintWriter to which the state is dumped.
+   */
   public static void dumpWorldState(final MutableWorldState worldState, final PrintWriter out) {
     out.println("{");
     worldState

ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmToolCommandOptionsModule.java

@@ -32,6 +32,16 @@
 import picocli.CommandLine;
 import picocli.CommandLine.Option;
 
+/**
+ * This class, EvmToolCommandOptionsModule, is a Dagger module that provides dependencies for the
+ * EvmToolCommand. It contains options for setting up the EVM tool, such as whether revert reasons
+ * should be persisted, the fork to evaluate, the key-value storage to be used, the data path, the
+ * block number to evaluate against, and the world state update mode.
+ *
+ * <p>The class uses PicoCLI annotations to define these options, which can be provided via the
+ * command line when running the EVM tool. Each option has a corresponding provider method that
+ * Dagger uses to inject the option's value where needed.
+ */
 @SuppressWarnings("WeakerAccess")
 @Module
 public class EvmToolCommandOptionsModule {
@@ -133,4 +143,7 @@ BlockParameter provideBlockParameter() {
   EvmConfiguration provideEvmConfiguration() {
     return new EvmConfiguration(jumpDestCacheWeightKilobytes, worldstateUpdateMode);
   }
+
+  /** Default constructor for the EvmToolCommandOptionsModule class. */
+  public EvmToolCommandOptionsModule() {}
 }