diff --git a/build.gradle b/build.gradle index 1adc3b992c..7d2293b61e 100644 --- a/build.gradle +++ b/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.*,' + diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/B11rSubCommand.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/B11rSubCommand.java index 9a27a8a40d..0bb7949754 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/B11rSubCommand.java +++ b/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 diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/BenchmarkSubCommand.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/BenchmarkSubCommand.java index 05d90a7b35..829bf2d58e 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/BenchmarkSubCommand.java +++ b/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; } diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/BlockchainModule.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/BlockchainModule.java index b3a1531133..7b463fe08e 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/BlockchainModule.java +++ b/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( diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/CodeValidateSubCommand.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/CodeValidateSubCommand.java index 10e167f406..e16d4014f0 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/CodeValidateSubCommand.java +++ b/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 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 { diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/DataStoreModule.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/DataStoreModule.java index 28b212024c..7629b31847 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/DataStoreModule.java +++ b/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") diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EOFTestSubCommand.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EOFTestSubCommand.java index ab53b41e1d..bfa873e61c 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EOFTestSubCommand.java +++ b/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 { diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmTool.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmTool.java index 43c1a666d6..dec0555640 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmTool.java +++ b/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(); diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmToolCommand.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmToolCommand.java index 90afdcdebb..a3bed6b54b 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmToolCommand.java +++ b/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. + * + *

EvmToolCommand implements the Runnable interface, making it the entrypoint for PicoCLI to + * execute this command. + * + *

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. + * + *

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 diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmToolCommandOptionsModule.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmToolCommandOptionsModule.java index fe229dc3cf..820b11442e 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmToolCommandOptionsModule.java +++ b/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. + * + *

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() {} } diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmToolComponent.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmToolComponent.java index 176700ee8e..cc84b59480 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/EvmToolComponent.java +++ b/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. + * + *

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. + * + *

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(); } diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/GenesisFileModule.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/GenesisFileModule.java index 506c3911d8..1283ec039f 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/GenesisFileModule.java +++ b/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. + * + *

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; } diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/JsonUtils.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/JsonUtils.java index 42da8fd950..7af31054a6 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/JsonUtils.java +++ b/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() {} diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/PrettyPrintSubCommand.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/PrettyPrintSubCommand.java index 10d31960a8..465f2c4895 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/PrettyPrintSubCommand.java +++ b/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. + * + *

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. + * + *

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 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; } diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/ProtocolModule.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/ProtocolModule.java index 1b8f557b3b..a196a35f5b 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/ProtocolModule.java +++ b/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. + * + *

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) { diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/StateTestSubCommand.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/StateTestSubCommand.java index 60a09b26e8..064a093e84 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/StateTestSubCommand.java +++ b/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. + * + *

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. + * + *

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 = @@ -112,6 +129,10 @@ public class StateTestSubCommand implements Runnable { // picocli does it magically @Parameters private final List 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 diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/T8nExecutor.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/T8nExecutor.java index caa5cb3672..40c73e383f 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/T8nExecutor.java +++ b/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

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 extractTransactions( final PrintWriter out, final Iterator 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. + * + *

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) {} } diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/T8nServerSubCommand.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/T8nServerSubCommand.java index 1c0a49438e..ffa6e67b72 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/T8nServerSubCommand.java +++ b/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. + * + *

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. + * + *

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 diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/T8nSubCommand.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/T8nSubCommand.java index 95dabb3183..d6db1a1e8d 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/T8nSubCommand.java +++ b/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. + * + *

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. + * + *

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 diff --git a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/VersionProvider.java b/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/VersionProvider.java index d97fded882..6f3ff33071 100644 --- a/ethereum/evmtool/src/main/java/org/hyperledger/besu/evmtool/VersionProvider.java +++ b/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. + * + *

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()};