Fix javadoc for ethereum:core top level package (#7270)

* javadoc - Apply javadoc to ethereum core top level package

---------

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

build.gradle

@@ -366,7 +366,6 @@ allprojects {
       '-org.hyperledger.besu.tests.acceptance.*,' +
       '-org.hyperledger.besu.tests.web3j.generated,' +
       // TODO: these are temporary disabled (ethereum and sub modules), it should be removed in a future PR.
-      '-org.hyperledger.besu.ethereum,' +
       '-org.hyperledger.besu.ethereum.*,' +
       '-org.hyperledger.besu.evmtool',
       true)

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/BlockProcessingOutputs.java

@@ -21,17 +21,31 @@ import org.hyperledger.besu.ethereum.core.TransactionReceipt;
 import java.util.List;
 import java.util.Optional;
 
+/** Contains the outputs of processing a block. */
 public class BlockProcessingOutputs {
 
   private final MutableWorldState worldState;
   private final List<TransactionReceipt> receipts;
   private final Optional<List<Request>> maybeRequests;
 
+  /**
+   * Creates a new instance.
+   *
+   * @param worldState the world state after processing the block
+   * @param receipts the receipts produced by processing the block
+   */
   public BlockProcessingOutputs(
       final MutableWorldState worldState, final List<TransactionReceipt> receipts) {
     this(worldState, receipts, Optional.empty());
   }
 
+  /**
+   * Creates a new instance.
+   *
+   * @param worldState the world state after processing the block
+   * @param receipts the receipts produced by processing the block
+   * @param maybeRequests the requests produced by processing the block
+   */
   public BlockProcessingOutputs(
       final MutableWorldState worldState,
       final List<TransactionReceipt> receipts,
@@ -41,14 +55,29 @@ public class BlockProcessingOutputs {
     this.maybeRequests = maybeRequests;
   }
 
+  /**
+   * Returns the world state after processing the block.
+   *
+   * @return the world state after processing the block
+   */
   public MutableWorldState getWorldState() {
     return worldState;
   }
 
+  /**
+   * Returns the receipts produced by processing the block.
+   *
+   * @return the receipts produced by processing the block
+   */
   public List<TransactionReceipt> getReceipts() {
     return receipts;
   }
 
+  /**
+   * Returns the requests produced by processing the block.
+   *
+   * @return the requests produced by processing the block
+   */
   public Optional<List<Request>> getRequests() {
     return maybeRequests;
   }

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/BlockProcessingResult.java

@@ -20,24 +20,43 @@ import java.util.ArrayList;
 import java.util.List;
 import java.util.Optional;
 
+/** Contains the outputs of processing a block. */
 public class BlockProcessingResult extends BlockValidationResult {
 
   private final Optional<BlockProcessingOutputs> yield;
   private final boolean isPartial;
 
+  /** A result indicating that processing failed. */
   public static final BlockProcessingResult FAILED = new BlockProcessingResult("processing failed");
 
+  /**
+   * A result indicating that processing was successful but incomplete.
+   *
+   * @param yield the outputs of processing a block
+   */
   public BlockProcessingResult(final Optional<BlockProcessingOutputs> yield) {
     this.yield = yield;
     this.isPartial = false;
   }
 
+  /**
+   * A result indicating that processing was successful but incomplete.
+   *
+   * @param yield the outputs of processing a block
+   * @param isPartial whether the processing was incomplete
+   */
   public BlockProcessingResult(
       final Optional<BlockProcessingOutputs> yield, final boolean isPartial) {
     this.yield = yield;
     this.isPartial = isPartial;
   }
 
+  /**
+   * A result indicating that processing was successful but incomplete.
+   *
+   * @param yield the outputs of processing a block
+   * @param errorMessage the error message if any
+   */
   public BlockProcessingResult(
       final Optional<BlockProcessingOutputs> yield, final String errorMessage) {
     super(errorMessage);
@@ -45,6 +64,12 @@ public class BlockProcessingResult extends BlockValidationResult {
     this.isPartial = false;
   }
 
+  /**
+   * A result indicating that processing was successful but incomplete.
+   *
+   * @param yield the outputs of processing a block
+   * @param cause the cause of the error if any
+   */
   public BlockProcessingResult(
       final Optional<BlockProcessingOutputs> yield, final Throwable cause) {
     super(cause.getLocalizedMessage(), cause);
@@ -52,6 +77,13 @@ public class BlockProcessingResult extends BlockValidationResult {
     this.isPartial = false;
   }
 
+  /**
+   * A result indicating that processing was successful but incomplete.
+   *
+   * @param yield the outputs of processing a block
+   * @param errorMessage the error message if any
+   * @param isPartial whether the processing was incomplete
+   */
   public BlockProcessingResult(
       final Optional<BlockProcessingOutputs> yield,
       final String errorMessage,
@@ -61,20 +93,40 @@ public class BlockProcessingResult extends BlockValidationResult {
     this.isPartial = isPartial;
   }
 
+  /**
+   * A result indicating that processing failed.
+   *
+   * @param errorMessage the error message
+   */
   public BlockProcessingResult(final String errorMessage) {
     super(errorMessage);
     this.isPartial = false;
     this.yield = Optional.empty();
   }
 
+  /**
+   * Gets the block processing outputs of the result.
+   *
+   * @return the block processing outputs of the result
+   */
   public Optional<BlockProcessingOutputs> getYield() {
     return yield;
   }
 
+  /**
+   * Checks if the processing was incomplete.
+   *
+   * @return true if the processing was incomplete, false otherwise
+   */
   public boolean isPartial() {
     return isPartial;
   }
 
+  /**
+   * Gets the transaction receipts of the result.
+   *
+   * @return the transaction receipts of the result
+   */
   public List<TransactionReceipt> getReceipts() {
     if (yield.isEmpty()) {
       return new ArrayList<>();

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/BlockValidationResult.java

@@ -16,38 +16,78 @@ package org.hyperledger.besu.ethereum;
 
 import java.util.Optional;
 
+/**
+ * Represents the result of a block validation. This class holds the success status, error message,
+ * and cause of the validation.
+ */
 public class BlockValidationResult {
 
+  /** The error message of the failed validation, if any. */
   public final Optional<String> errorMessage;
+
+  /** The cause of the failed validation, if any. */
   public final Optional<Throwable> cause;
+
+  /**
+   * The success status of the validation. True if the validation was successful, false otherwise.
+   */
   public final boolean success;
 
+  /** Constructs a new BlockValidationResult indicating a successful validation. */
   public BlockValidationResult() {
     this.success = true;
     this.errorMessage = Optional.empty();
     this.cause = Optional.empty();
   }
 
+  /**
+   * Constructs a new BlockValidationResult indicating a failed validation with the given error
+   * message.
+   *
+   * @param errorMessage the error message of the failed validation
+   */
   public BlockValidationResult(final String errorMessage) {
     this.success = false;
     this.errorMessage = Optional.of(errorMessage);
     this.cause = Optional.empty();
   }
 
+  /**
+   * Constructs a new BlockValidationResult indicating a failed validation with the given error
+   * message and cause.
+   *
+   * @param errorMessage the error message of the failed validation
+   * @param cause the cause of the failed validation
+   */
   public BlockValidationResult(final String errorMessage, final Throwable cause) {
     this.success = false;
     this.errorMessage = Optional.of(errorMessage);
     this.cause = Optional.of(cause);
   }
 
+  /**
+   * Checks if the validation was successful.
+   *
+   * @return true if the validation was successful, false otherwise
+   */
   public boolean isSuccessful() {
     return this.success;
   }
 
+  /**
+   * Checks if the validation failed.
+   *
+   * @return true if the validation failed, false otherwise
+   */
   public boolean isFailed() {
     return !isSuccessful();
   }
 
+  /**
+   * Gets the cause of the failed validation.
+   *
+   * @return the cause of the failed validation
+   */
   public Optional<Throwable> causedBy() {
     return cause;
   }

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/BlockValidator.java

@@ -22,14 +22,39 @@ import org.hyperledger.besu.ethereum.mainnet.HeaderValidationMode;
 import java.util.List;
 import java.util.Optional;
 
+/**
+ * The BlockValidator interface defines the methods for validating and processing blocks in the
+ * Ethereum protocol.
+ */
 public interface BlockValidator {
 
+  /**
+   * Validates and processes a block with the given context, block, header validation mode, and
+   * ommer validation mode.
+   *
+   * @param context the protocol context
+   * @param block the block to validate and process
+   * @param headerValidationMode the header validation mode
+   * @param ommerValidationMode the ommer validation mode
+   * @return the result of the block processing
+   */
   BlockProcessingResult validateAndProcessBlock(
       final ProtocolContext context,
       final Block block,
       final HeaderValidationMode headerValidationMode,
       final HeaderValidationMode ommerValidationMode);
 
+  /**
+   * Validates and processes a block with the given context, block, header validation mode, ommer
+   * validation mode, and persistence flag.
+   *
+   * @param context the protocol context
+   * @param block the block to validate and process
+   * @param headerValidationMode the header validation mode
+   * @param ommerValidationMode the ommer validation mode
+   * @param shouldPersist flag indicating whether the block should be persisted
+   * @return the result of the block processing
+   */
   BlockProcessingResult validateAndProcessBlock(
       final ProtocolContext context,
       final Block block,
@@ -37,6 +62,18 @@ public interface BlockValidator {
       final HeaderValidationMode ommerValidationMode,
       final boolean shouldPersist);
 
+  /**
+   * Validates and processes a block with the given context, block, header validation mode, ommer
+   * validation mode, persistence flag, and bad block recording flag.
+   *
+   * @param context the protocol context
+   * @param block the block to validate and process
+   * @param headerValidationMode the header validation mode
+   * @param ommerValidationMode the ommer validation mode
+   * @param shouldPersist flag indicating whether the block should be persisted
+   * @param shouldRecordBadBlock flag indicating whether bad blocks should be recorded
+   * @return the result of the block processing
+   */
   BlockProcessingResult validateAndProcessBlock(
       final ProtocolContext context,
       final Block block,
@@ -45,6 +82,18 @@ public interface BlockValidator {
       final boolean shouldPersist,
       final boolean shouldRecordBadBlock);
 
+  /**
+   * Performs fast block validation with the given context, block, transaction receipts, requests,
+   * header validation mode, and ommer validation mode.
+   *
+   * @param context the protocol context
+   * @param block the block to validate
+   * @param receipts the transaction receipts
+   * @param requests the requests
+   * @param headerValidationMode the header validation mode
+   * @param ommerValidationMode the ommer validation mode
+   * @return true if the block is valid, false otherwise
+   */
   boolean fastBlockValidation(
       final ProtocolContext context,
       final Block block,

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/ConsensusContext.java

@@ -14,7 +14,19 @@
  */
 package org.hyperledger.besu.ethereum;
 
+/**
+ * The ConsensusContext interface defines a method for casting the consensus context to a specific
+ * class.
+ */
 @FunctionalInterface
 public interface ConsensusContext {
+
+  /**
+   * Casts the consensus context to the specified class.
+   *
+   * @param <C> the type of the class to cast the consensus context to
+   * @param klass the class to cast the consensus context to
+   * @return the consensus context cast to the specified class
+   */
   <C extends ConsensusContext> C as(final Class<C> klass);
 }

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/ConsensusContextFactory.java

@@ -18,9 +18,19 @@ import org.hyperledger.besu.ethereum.chain.Blockchain;
 import org.hyperledger.besu.ethereum.mainnet.ProtocolSchedule;
 import org.hyperledger.besu.ethereum.worldstate.WorldStateArchive;
 
+/** The ConsensusContextFactory interface defines a method for creating a consensus context. */
 @FunctionalInterface
 public interface ConsensusContextFactory {
 
+  /**
+   * Creates a consensus context with the given blockchain, world state archive, and protocol
+   * schedule.
+   *
+   * @param blockchain the blockchain
+   * @param worldStateArchive the world state archive
+   * @param protocolSchedule the protocol schedule
+   * @return the created consensus context
+   */
   ConsensusContext create(
       Blockchain blockchain,
       WorldStateArchive worldStateArchive,

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/GasLimitCalculator.java

@@ -14,16 +14,37 @@
  */
 package org.hyperledger.besu.ethereum;
 
+/** The GasLimitCalculator interface defines methods for calculating the gas limit. */
 public interface GasLimitCalculator {
 
-  static final long BLOB_GAS_LIMIT = 786432;
+  /** The constant BLOB_GAS_LIMIT represents the gas limit for blob data. */
+  long BLOB_GAS_LIMIT = 786432;
 
+  /**
+   * Calculates the next gas limit based on the current gas limit, target gas limit, and new block
+   * number.
+   *
+   * @param currentGasLimit the current gas limit
+   * @param targetGasLimit the target gas limit
+   * @param newBlockNumber the new block number
+   * @return the calculated next gas limit
+   */
   long nextGasLimit(long currentGasLimit, long targetGasLimit, long newBlockNumber);
 
+  /**
+   * Returns a GasLimitCalculator that always returns the current gas limit.
+   *
+   * @return a GasLimitCalculator that always returns the current gas limit
+   */
   static GasLimitCalculator constant() {
     return (currentGasLimit, targetGasLimit, newBlockNumber) -> currentGasLimit;
   }
 
+  /**
+   * Returns the current blob gas limit.
+   *
+   * @return the current blob gas limit
+   */
   default long currentBlobGasLimit() {
     return BLOB_GAS_LIMIT;
   }

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/MainnetBlockValidator.java

@@ -36,14 +36,36 @@ import java.util.Optional;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * The MainnetBlockValidator class implements the BlockValidator interface for the Mainnet Ethereum
+ * network. It validates and processes blocks according to the rules of the Mainnet Ethereum
+ * network.
+ */
 public class MainnetBlockValidator implements BlockValidator {
 
   private static final Logger LOG = LoggerFactory.getLogger(MainnetBlockValidator.class);
+
+  /** The BlockHeaderValidator used to validate block headers. */
   protected final BlockHeaderValidator blockHeaderValidator;
+
+  /** The BlockBodyValidator used to validate block bodies. */
   protected final BlockBodyValidator blockBodyValidator;
+
+  /** The BlockProcessor used to process blocks. */
   protected final BlockProcessor blockProcessor;
+
+  /** The BadBlockManager used to manage bad blocks. */
   protected final BadBlockManager badBlockManager;
 
+  /**
+   * Constructs a new MainnetBlockValidator with the given BlockHeaderValidator, BlockBodyValidator,
+   * BlockProcessor, and BadBlockManager.
+   *
+   * @param blockHeaderValidator the BlockHeaderValidator used to validate block headers
+   * @param blockBodyValidator the BlockBodyValidator used to validate block bodies
+   * @param blockProcessor the BlockProcessor used to process blocks
+   * @param badBlockManager the BadBlockManager used to manage bad blocks
+   */
   public MainnetBlockValidator(
       final BlockHeaderValidator blockHeaderValidator,
       final BlockBodyValidator blockBodyValidator,

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/ProtocolContext.java

@@ -35,6 +35,15 @@ public class ProtocolContext {
 
   private Optional<Synchronizer> synchronizer;
 
+  /**
+   * Constructs a new ProtocolContext with the given blockchain, world state archive, consensus
+   * context, and bad block manager.
+   *
+   * @param blockchain the blockchain of the protocol context
+   * @param worldStateArchive the world state archive of the protocol context
+   * @param consensusContext the consensus context of the protocol context
+   * @param badBlockManager the bad block manager of the protocol context
+   */
   public ProtocolContext(
       final MutableBlockchain blockchain,
       final WorldStateArchive worldStateArchive,
@@ -47,6 +56,17 @@ public class ProtocolContext {
     this.badBlockManager = badBlockManager;
   }
 
+  /**
+   * Initializes a new ProtocolContext with the given blockchain, world state archive, protocol
+   * schedule, consensus context factory, and bad block manager.
+   *
+   * @param blockchain the blockchain of the protocol context
+   * @param worldStateArchive the world state archive of the protocol context
+   * @param protocolSchedule the protocol schedule of the protocol context
+   * @param consensusContextFactory the consensus context factory of the protocol context
+   * @param badBlockManager the bad block manager of the protocol context
+   * @return the initialized ProtocolContext
+   */
   public static ProtocolContext init(
       final MutableBlockchain blockchain,
       final WorldStateArchive worldStateArchive,
@@ -60,30 +80,69 @@ public class ProtocolContext {
         badBlockManager);
   }
 
+  /**
+   * Gets the synchronizer of the protocol context.
+   *
+   * @return the synchronizer of the protocol context
+   */
   public Optional<Synchronizer> getSynchronizer() {
     return synchronizer;
   }
 
+  /**
+   * Sets the synchronizer of the protocol context.
+   *
+   * @param synchronizer the synchronizer to set
+   */
   public void setSynchronizer(final Optional<Synchronizer> synchronizer) {
     this.synchronizer = synchronizer;
   }
 
+  /**
+   * Gets the blockchain of the protocol context.
+   *
+   * @return the blockchain of the protocol context
+   */
   public MutableBlockchain getBlockchain() {
     return blockchain;
   }
 
+  /**
+   * Gets the world state archive of the protocol context.
+   *
+   * @return the world state archive of the protocol context
+   */
   public WorldStateArchive getWorldStateArchive() {
     return worldStateArchive;
   }
 
+  /**
+   * Gets the bad block manager of the protocol context.
+   *
+   * @return the bad block manager of the protocol context
+   */
   public BadBlockManager getBadBlockManager() {
     return badBlockManager;
   }
 
+  /**
+   * Gets the consensus context of the protocol context.
+   *
+   * @param <C> the type of the consensus context
+   * @param klass the klass
+   * @return the consensus context of the protocol context
+   */
   public <C extends ConsensusContext> C getConsensusContext(final Class<C> klass) {
     return consensusContext.as(klass);
   }
 
+  /**
+   * Gets the safe consensus context of the protocol context.
+   *
+   * @param <C> the type of the consensus context
+   * @param klass the klass
+   * @return the consensus context of the protocol context
+   */
   public <C extends ConsensusContext> Optional<C> safeConsensusContext(final Class<C> klass) {
     return Optional.ofNullable(consensusContext)
         .filter(c -> klass.isAssignableFrom(c.getClass()))