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

Signed-off-by: Usman Saleem <usman@usmans.info>

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.Option;
 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 class B11rSubCommand implements Runnable {
     }
   }
 
+  /** 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.Option;
 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 @@ public class BenchmarkSubCommand implements Runnable {
 
   @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.Module;
 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,6 +40,11 @@ import org.apache.tuweni.bytes.Bytes;
 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,
@@ -47,6 +52,10 @@ import picocli.CommandLine.ParentCommand;
     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 @@ public class CodeValidateSubCommand implements Runnable {
     }
   }
 
+  /**
+   * 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 com.google.common.base.Suppliers;
 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 com.fasterxml.jackson.databind.ObjectMapper;
 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 @@ public class EOFTestSubCommand implements Runnable {
     }
   }
 
+  /**
+   * 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 @@ package org.hyperledger.besu.evmtool;
 
 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;
 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 @@ public class EvmToolCommand implements Runnable {
   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 @@ public class EvmToolCommand implements Runnable {
     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 class EvmToolCommand implements Runnable {
     }
   }
 
+  /**
+   * 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 dagger.Provides;
 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 @@ public class EvmToolCommandOptionsModule {
   EvmConfiguration provideEvmConfiguration() {
     return new EvmConfiguration(jumpDestCacheWeightKilobytes, worldstateUpdateMode);
   }
+
+  /** Default constructor for the EvmToolCommandOptionsModule class. */
+  public EvmToolCommandOptionsModule() {}
 }

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

@@ -26,6 +26,22 @@ import javax.inject.Singleton;
 
 import dagger.Component;
 
+/**
+ * This is a Dagger component interface for the EVM (Ethereum Virtual Machine) tool. It is annotated
+ * with @Singleton to ensure that only a single instance of this component exists within the Dagger
+ * component graph.
+ *
+ * <p>The component is composed of several modules that provide the necessary dependencies for the
+ * EVM tool: - ProtocolModule: Provides the protocol specification. - GenesisFileModule: Provides
+ * the genesis file for the blockchain. - DataStoreModule: Provides the data store for blockchain
+ * data. - BlockchainModule: Provides the blockchain instance. - EvmToolCommandOptionsModule:
+ * Provides the command options for the EVM tool. - MetricsConfigurationModule and
+ * MetricsSystemModule: Provide the metrics system and its configuration.
+ *
+ * <p>The interface defines methods to get instances of key classes like ProtocolSpec, EVM,
+ * WorldUpdater, MutableWorldState, and Blockchain. These methods are used by Dagger to inject the
+ * returned instances where needed.
+ */
 @Singleton
 @Component(
     modules = {
@@ -39,13 +55,44 @@ import dagger.Component;
     })
 public interface EvmToolComponent {
 
+  /**
+   * Retrieves the ProtocolSpec instance. ProtocolSpec defines the Ethereum protocol specifications,
+   * which includes the precompiled contracts, the gas calculator, the EVM, and the private nonce
+   * calculator.
+   *
+   * @return The ProtocolSpec instance.
+   */
   ProtocolSpec getProtocolSpec();
 
+  /**
+   * Retrieves the EVM instance. EVM (Ethereum Virtual Machine) is responsible for executing the
+   * bytecode of smart contracts in Ethereum.
+   *
+   * @return The EVM instance.
+   */
   EVM getEVM();
 
+  /**
+   * Retrieves the WorldUpdater instance. WorldUpdater is used to modify the world state, which
+   * includes the accounts and their associated storage and code.
+   *
+   * @return The WorldUpdater instance.
+   */
   WorldUpdater getWorldUpdater();
 
+  /**
+   * Retrieves the MutableWorldState instance. MutableWorldState represents the world state of
+   * Ethereum, which includes all accounts, their balances, nonces, codes, and storage.
+   *
+   * @return The MutableWorldState instance.
+   */
   MutableWorldState getWorldState();
 
+  /**
+   * Retrieves the Blockchain instance. Blockchain represents the Ethereum blockchain, which
+   * includes blocks, transactions, and the world state.
+   *
+   * @return The Blockchain instance.
+   */
   Blockchain getBlockchain();
 }

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

@@ -36,11 +36,26 @@ import dagger.Module;
 import dagger.Provides;
 import io.vertx.core.json.JsonObject;
 
+/**
+ * This class, GenesisFileModule, is a Dagger module that provides dependencies for the GenesisFile.
+ * It contains options for setting up the GenesisFile, such as the genesis configuration, genesis
+ * state, block header functions, and the genesis block.
+ *
+ * <p>The class uses Dagger 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.
+ */
 @Module
 public class GenesisFileModule {
 
   private final String genesisConfig;
 
+  /**
+   * Constructs a new GenesisFileModule with the specified genesis configuration.
+   *
+   * @param genesisConfig The configuration for the genesis file. This is typically a JSON string
+   *     that specifies various parameters for the genesis block of the blockchain.
+   */
   protected GenesisFileModule(final String genesisConfig) {
     this.genesisConfig = genesisConfig;
   }

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

@@ -24,6 +24,12 @@ import com.fasterxml.jackson.databind.module.SimpleModule;
 import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
 import org.apache.tuweni.bytes.Bytes;
 
+/**
+ * Utility class for JSON related operations. This class provides a method to create an ObjectMapper
+ * with standard configurations needed for evmtool. The ObjectMapper is configured to match the
+ * standard JSON output of Go, and it does not auto close the source. It also registers serializers
+ * for Address and Bytes classes. This class is not meant to be instantiated.
+ */
 public class JsonUtils {
 
   private JsonUtils() {}

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

@@ -30,13 +30,31 @@ import java.util.List;
 import org.apache.tuweni.bytes.Bytes;
 import picocli.CommandLine;
 
+/**
+ * This class, PrettyPrintSubCommand, is a command-line interface (CLI) command that pretty prints
+ * EOF (Ethereum Object Format) code. It implements the Runnable interface, meaning it can be used
+ * in a thread of execution.
+ *
+ * <p>The class is annotated with {@code @CommandLine.Command}, which is a PicoCLI annotation that
+ * designates this class as a command-line command. The annotation parameters define the command's
+ * name, description, whether it includes standard help options, and the version provider.
+ *
+ * <p>The command's functionality is defined in the run() method, which is overridden from the
+ * Runnable interface.
+ */
 @CommandLine.Command(
     name = COMMAND_NAME,
     description = "Pretty Prints EOF Code",
     mixinStandardHelpOptions = true,
     versionProvider = VersionProvider.class)
 public class PrettyPrintSubCommand implements Runnable {
+  /**
+   * The name of the command for the PrettyPrintSubCommand. This constant is used as the name
+   * parameter in the @CommandLine.Command annotation. It defines the command name that users should
+   * enter on the command line to invoke this command.
+   */
   public static final String COMMAND_NAME = "pretty-print";
+
   @CommandLine.ParentCommand private final EvmToolCommand parentCommand;
 
   @CommandLine.Option(
@@ -48,10 +66,20 @@ public class PrettyPrintSubCommand implements Runnable {
   // picocli does it magically
   @CommandLine.Parameters private final List<String> codeList = new ArrayList<>();
 
+  /**
+   * Default constructor for the PrettyPrintSubCommand class. This constructor initializes the
+   * parentCommand to null.
+   */
   public PrettyPrintSubCommand() {
     this(null);
   }
 
+  /**
+   * Constructs a new PrettyPrintSubCommand with the specified parent command.
+   *
+   * @param parentCommand The parent command for this subcommand. This is typically an instance of
+   *     EvmToolCommand.
+   */
   public PrettyPrintSubCommand(final EvmToolCommand parentCommand) {
     this.parentCommand = parentCommand;
   }

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

@@ -24,10 +24,25 @@ import javax.inject.Singleton;
 import dagger.Module;
 import dagger.Provides;
 
+/**
+ * This class, ProtocolModule, is a Dagger module that provides dependencies for the ProtocolSpec
+ * and EVM. It includes the GenesisFileModule, which provides the genesis configuration for the
+ * blockchain.
+ *
+ * <p>The class uses Dagger annotations to define these dependencies, which can be provided via the
+ * command line when running the EVM tool. Each dependency has a corresponding provider method that
+ * Dagger uses to inject the dependency's value where needed.
+ */
 @SuppressWarnings("WeakerAccess")
 @Module(includes = GenesisFileModule.class)
 public class ProtocolModule {
 
+  /**
+   * Default constructor for the ProtocolModule class. This constructor doesn't take any arguments
+   * and doesn't perform any initialization.
+   */
+  public ProtocolModule() {}
+
   @Provides
   @Singleton
   ProtocolSpec getProtocolSpec(final ProtocolSchedule protocolSchedule) {

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

@@ -65,12 +65,29 @@ import picocli.CommandLine.Option;
 import picocli.CommandLine.Parameters;
 import picocli.CommandLine.ParentCommand;
 
+/**
+ * This class, StateTestSubCommand, is a command-line interface (CLI) command that executes an
+ * Ethereum State Test. It implements the Runnable interface, meaning it can be used in a thread of
+ * execution.
+ *
+ * <p>The class is annotated with @CommandLine.Command, which is a PicoCLI annotation that
+ * designates this class as a command-line command. The annotation parameters define the command's
+ * name, description, whether it includes standard help options, and the version provider.
+ *
+ * <p>The command's functionality is defined in the run() method, which is overridden from the
+ * Runnable interface.
+ */
 @Command(
     name = COMMAND_NAME,
     description = "Execute an Ethereum State Test.",
     mixinStandardHelpOptions = true,
     versionProvider = VersionProvider.class)
 public class StateTestSubCommand implements Runnable {
+  /**
+   * The name of the command for the StateTestSubCommand. This constant is used as the name
+   * parameter in the @CommandLine.Command annotation. It defines the command name that users should
+   * enter on the command line to invoke this command.
+   */
   public static final String COMMAND_NAME = "state-test";
 
   static final Supplier<ReferenceTestProtocolSchedules> referenceTestProtocolSchedules =
@@ -112,6 +129,10 @@ public class StateTestSubCommand implements Runnable {
   // picocli does it magically
   @Parameters private final List<Path> stateTestFiles = new ArrayList<>();
 
+  /**
+   * Default constructor for the StateTestSubCommand class. This constructor doesn't take any
+   * arguments and initializes the parentCommand to null. PicoCLI requires this constructor.
+   */
   @SuppressWarnings("unused")
   public StateTestSubCommand() {
     // PicoCLI requires this

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

@@ -86,12 +86,43 @@ import org.apache.tuweni.bytes.Bytes;
 import org.apache.tuweni.bytes.Bytes32;
 import org.apache.tuweni.units.bigints.UInt256;
 
+/**
+ * The T8nExecutor class is responsible for executing transactions in the context of the Ethereum
+ * Virtual Machine (EVM). It extracts transactions from a given input, runs tests on them, and
+ * generates results including stateRoot, txRoot, receiptsRoot, and logsHash. It also handles block
+ * rewards and withdrawal processing. This class is part of the EVM tooling within the Hyperledger
+ * Besu project.
+ */
 public class T8nExecutor {
 
   private static final Set<Address> EMPTY_ADDRESS_SET = Set.of();
 
+  /**
+   * A record that represents a transaction that has been rejected. It contains the index of the
+   * transaction and the error message explaining why it was rejected.
+   *
+   * @param index The index of the rejected transaction.
+   * @param error The error message explaining why the transaction was rejected.
+   */
   public record RejectedTransaction(int index, String error) {}
 
+  /**
+   * Default constructor for the T8nExecutor class. This constructor does not perform any
+   * operations.
+   */
+  public T8nExecutor() {}
+
+  /**
+   * Extracts transactions from a given JSON iterator and adds them to the provided transactions
+   * list. If a transaction cannot be parsed or is invalid, it is added to the rejections list with
+   * its index and error message.
+   *
+   * @param out PrintWriter used for outputting information or errors.
+   * @param it Iterator over JSON nodes, each representing a transaction.
+   * @param transactions List of transactions to which parsed transactions are added.
+   * @param rejections List of RejectedTransaction records to which rejected transactions are added.
+   * @return The updated list of transactions after parsing and validation.
+   */
   protected static List<Transaction> extractTransactions(
       final PrintWriter out,
       final Iterator<JsonNode> it,
@@ -547,12 +578,45 @@ public class T8nExecutor {
     return new T8nResult(allocObject, bodyBytes, resultObject);
   }
 
-  interface TracerManager {
+  /**
+   * The TracerManager interface provides methods for managing OperationTracer instances. It is used
+   * in the context of Ethereum Virtual Machine (EVM) execution to trace operations.
+   *
+   * <p>The interface defines two methods: - getManagedTracer: This method is used to get a managed
+   * OperationTracer instance for a specific transaction. - disposeTracer: This method is used to
+   * dispose of an OperationTracer instance when it is no longer needed.
+   */
+  public interface TracerManager {
+
+    /**
+     * Retrieves a managed OperationTracer instance for a specific transaction.
+     *
+     * @param txIndex The index of the transaction for which the tracer is to be retrieved.
+     * @param txHash The hash of the transaction for which the tracer is to be retrieved.
+     * @return The managed OperationTracer instance.
+     * @throws Exception If an error occurs while retrieving the tracer.
+     */
     OperationTracer getManagedTracer(int txIndex, Hash txHash) throws Exception;
 
+    /**
+     * Disposes of an OperationTracer instance when it is no longer needed.
+     *
+     * @param tracer The OperationTracer instance to be disposed.
+     * @throws IOException If an error occurs while disposing the tracer.
+     */
     void disposeTracer(OperationTracer tracer) throws IOException;
   }
 
+  /**
+   * A record that represents the result of a transaction test run in the Ethereum Virtual Machine
+   * (EVM). It contains the final state of the accounts (allocObject), the raw bytes of the
+   * transactions (bodyBytes), and the result of the test run (resultObject).
+   *
+   * @param allocObject The final state of the accounts after the test run.
+   * @param bodyBytes The raw bytes of the transactions that were run.
+   * @param resultObject The result of the test run, including stateRoot, txRoot, receiptsRoot,
+   *     logsHash, and other details.
+   */
   @SuppressWarnings("unused")
   record T8nResult(ObjectNode allocObject, TextNode bodyBytes, ObjectNode resultObject) {}
 }

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

@@ -55,6 +55,19 @@ import io.vertx.core.http.HttpServerRequest;
 import picocli.CommandLine;
 import picocli.CommandLine.ParentCommand;
 
+/**
+ * The T8nServerSubCommand class is responsible for running an Ethereum State Test server. It reads
+ * the initial state, transactions, and environment from input files or stdin, executes the
+ * transactions in the Ethereum Virtual Machine (EVM), and writes the final state, transaction
+ * results, and traces to output files or stdout.
+ *
+ * <p>The class uses the Vert.x library for handling HTTP requests and the picocli library for
+ * command line argument parsing. It includes options for specifying the host and port to bind to,
+ * and the base directory for output.
+ *
+ * <p>The class also includes a TracerManager for managing OperationTracer instances, which are used
+ * to trace EVM operations when the --json flag is specified.
+ */
 @SuppressWarnings("java:S106") // using standard output is the point of this class
 @CommandLine.Command(
     name = "t8n-server",
@@ -80,6 +93,10 @@ public class T8nServerSubCommand implements Runnable {
 
   @ParentCommand private final EvmToolCommand parentCommand;
 
+  /**
+   * Default constructor for the T8nServerSubCommand class. This constructor is required by PicoCLI
+   * and assigns null to parentCommand.
+   */
   @SuppressWarnings("unused")
   public T8nServerSubCommand() {
     // PicoCLI requires this

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

@@ -59,6 +59,19 @@ import picocli.CommandLine.ParameterException;
 import picocli.CommandLine.Parameters;
 import picocli.CommandLine.ParentCommand;
 
+/**
+ * The T8nSubCommand class is responsible for executing an Ethereum State Test. It reads the initial
+ * state, transactions, and environment from input files or stdin, executes the transactions in the
+ * Ethereum Virtual Machine (EVM), and writes the final state, transaction results, and traces to
+ * output files or stdout.
+ *
+ * <p>The class uses the picocli library for command line argument parsing and includes options for
+ * specifying the input and output files, the fork to run the transition against, the chain ID, and
+ * the block reward.
+ *
+ * <p>The class also includes a TracerManager for managing OperationTracer instances, which are used
+ * to trace EVM operations when the --json flag is specified.
+ */
 @Command(
     name = COMMAND_NAME,
     aliases = COMMAND_ALIAS,
@@ -154,12 +167,22 @@ public class T8nSubCommand implements Runnable {
     }
   }
 
+  /**
+   * Default constructor for the T8nSubCommand class. This constructor is required by PicoCLI and
+   * assigns parent command to 'null'.
+   */
   @SuppressWarnings("unused")
   public T8nSubCommand() {
     // PicoCLI requires this
     parentCommand = null;
   }
 
+  /**
+   * Constructor for the T8nSubCommand class with a parent command. This constructor is required by
+   * PicoCLI.
+   *
+   * @param parentCommand The parent command for this sub command.
+   */
   @SuppressWarnings("unused")
   public T8nSubCommand(final EvmToolCommand parentCommand) {
     // PicoCLI requires this too

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

@@ -18,8 +18,26 @@ import org.hyperledger.besu.BesuInfo;
 
 import picocli.CommandLine;
 
+/**
+ * The VersionProvider class is responsible for providing the version of the Hyperledger Besu EVM
+ * tool. It implements the IVersionProvider interface from the picocli library.
+ *
+ * <p>The getVersion method returns a string array containing the version of the Hyperledger Besu
+ * EVM tool.
+ */
 public class VersionProvider implements CommandLine.IVersionProvider {
 
+  /**
+   * Default constructor for the VersionProvider class. This constructor does not perform any
+   * operations.
+   */
+  public VersionProvider() {}
+
+  /**
+   * This method returns the version of the Hyperledger Besu EVM tool.
+   *
+   * @return A string array containing the version of the Hyperledger Besu EVM tool.
+   */
   @Override
   public String[] getVersion() {
     return new String[] {"Hyperledger Besu evm " + BesuInfo.shortVersion()};