javadoc, javadoc, javadoc

Signed-off-by: garyschulte <garyschulte@gmail.com>

besu/src/main/java/org/hyperledger/besu/cli/options/unstable/ChainPruningOptions.java

@@ -109,6 +109,11 @@ public Long getChainDataPruningBlocksRetained() {
     return chainDataPruningBlocksRetained;
   }
 
+  /**
+   * Get the configured number of retained blocks for chain pruning.
+   *
+   * @return the number of retained blocks
+   */
   public Long getChainDataPruningBlocksRetainedLimit() {
     return chainDataPruningBlocksRetainedLimit;
   }

besu/src/main/java/org/hyperledger/besu/services/BesuConfigurationImpl.java

@@ -41,6 +41,7 @@ public class BesuConfigurationImpl implements BesuConfiguration {
    * @param dataPath The Path representing data folder
    * @param storagePath The path representing storage folder
    * @param dataStorageConfiguration The data storage configuration
+   * @return BesuConfigurationImpl instance
    */
   public BesuConfigurationImpl init(
       final Path dataPath,
@@ -52,11 +53,23 @@ public BesuConfigurationImpl init(
     return this;
   }
 
+  /**
+   * Set the mining parameters
+   *
+   * @param miningParameters configured mining parameters
+   * @return BesuConfigurationImpl instance
+   */
   public BesuConfigurationImpl withMiningParameters(final MiningParameters miningParameters) {
     this.miningParameters = miningParameters;
     return this;
   }
 
+  /**
+   * Set the RPC http options
+   *
+   * @param rpcHttpOptions configured rpc http options
+   * @return BesuConfigurationImpl instance
+   */
   public BesuConfigurationImpl withJsonRpcHttpOptions(final JsonRpcHttpOptions rpcHttpOptions) {
     this.rpcHttpHost = Optional.ofNullable(rpcHttpOptions.getRpcHttpHost());
     this.rpcHttpPort = Optional.ofNullable(rpcHttpOptions.getRpcHttpPort());

besu/src/main/java/org/hyperledger/besu/services/BesuPluginContextImpl.java

@@ -231,6 +231,7 @@ public void startPlugins() {
     state = Lifecycle.BEFORE_MAIN_LOOP_FINISHED;
   }
 
+  /** Execute all plugin setup code after external services. */
   public void afterExternalServicesMainLoop() {
     checkState(
         state == Lifecycle.BEFORE_MAIN_LOOP_FINISHED,

besu/src/main/java/org/hyperledger/besu/services/P2PServiceImpl.java

@@ -17,14 +17,21 @@
 import org.hyperledger.besu.ethereum.p2p.network.P2PNetwork;
 import org.hyperledger.besu.plugin.services.p2p.P2PService;
 
+/** Service to enable and disable P2P discovery. */
 public class P2PServiceImpl implements P2PService {
 
   private final P2PNetwork p2PNetwork;
 
+  /**
+   * Creates a new P2PServiceImpl.
+   *
+   * @param p2PNetwork the P2P network to enable and disable.
+   */
   public P2PServiceImpl(final P2PNetwork p2PNetwork) {
     this.p2PNetwork = p2PNetwork;
   }
 
+  /** Enables P2P discovery. */
   @Override
   public void enableDiscovery() {
     p2PNetwork.start();

besu/src/main/java/org/hyperledger/besu/services/RlpConverterServiceImpl.java

@@ -25,10 +25,16 @@
 
 import org.apache.tuweni.bytes.Bytes;
 
+/** RLP Serialiaztion/Deserialization service. */
 public class RlpConverterServiceImpl implements RlpConverterService {
 
   private final BlockHeaderFunctions blockHeaderFunctions;
 
+  /**
+   * Constructor for RlpConverterServiceImpl.
+   *
+   * @param protocolSchedule the protocol schedule.
+   */
   public RlpConverterServiceImpl(final ProtocolSchedule protocolSchedule) {
     this.blockHeaderFunctions = ScheduleBasedBlockHeaderFunctions.create(protocolSchedule);
   }

besu/src/main/java/org/hyperledger/besu/services/SynchronizationServiceImpl.java

@@ -37,6 +37,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/** Synchronization service. */
 public class SynchronizationServiceImpl implements SynchronizationService {
 
   private static final Logger LOG = LoggerFactory.getLogger(SynchronizationServiceImpl.class);
@@ -47,6 +48,14 @@ public class SynchronizationServiceImpl implements SynchronizationService {
   private final SyncState syncState;
   private final Optional<BonsaiWorldStateProvider> worldStateArchive;
 
+  /**
+   * Constructor for SynchronizationServiceImpl.
+   *
+   * @param protocolContext protocol context
+   * @param protocolSchedule protocol schedule
+   * @param syncState sync state
+   * @param worldStateArchive world state archive
+   */
   public SynchronizationServiceImpl(
       final ProtocolContext protocolContext,
       final ProtocolSchedule protocolSchedule,

besu/src/main/java/org/hyperledger/besu/services/TransactionPoolServiceImpl.java

@@ -17,10 +17,16 @@
 import org.hyperledger.besu.ethereum.eth.transactions.TransactionPool;
 import org.hyperledger.besu.plugin.services.transactionpool.TransactionPoolService;
 
+/** Service to enable and disable the transaction pool. */
 public class TransactionPoolServiceImpl implements TransactionPoolService {
 
   private final TransactionPool transactionPool;
 
+  /**
+   * Creates a new TransactionPoolServiceImpl.
+   *
+   * @param transactionPool the transaction pool to control
+   */
   public TransactionPoolServiceImpl(final TransactionPool transactionPool) {
     this.transactionPool = transactionPool;
   }

plugin-api/build.gradle

@@ -69,7 +69,7 @@ Calculated : ${currentHash}
 tasks.register('checkAPIChanges', FileStateChecker) {
   description = "Checks that the API for the Plugin-API project does not change without deliberate thought"
   files = sourceSets.main.allJava.files
-  knownHash = 'gAtsoRQwpjyGxKlNA0ijy+gk04/UDGQVmIq+nAVw7bI='
+  knownHash = 'VbV2egL1JujUb7b9iG8CbMeyuOsgwL6P/5elq9/75Dw='
 }
 check.dependsOn('checkAPIChanges')
 

plugin-api/src/main/java/org/hyperledger/besu/plugin/BesuPlugin.java

@@ -63,8 +63,8 @@ default void beforeExternalServices() {}
    */
   void start();
 
+  /** Hook to execute plugin setup code after external services */
   default void afterExternalServicePostMainLoop() {}
-  ;
 
   /**
    * Called when the plugin is being reloaded. This method will be called through a dedicated JSON

plugin-api/src/main/java/org/hyperledger/besu/plugin/services/BesuEvents.java

@@ -91,6 +91,12 @@ public interface BesuEvents extends BesuService {
    */
   void removeBlockReorgListener(long listenerIdentifier);
 
+  /**
+   * Add an initial sync completion listener.
+   *
+   * @param listener to subscribe to initial sync completion events
+   * @return id of listener subscription
+   */
   long addInitialSyncCompletionListener(final InitialSyncCompletionListener listener);
 
   /**

plugin-api/src/main/java/org/hyperledger/besu/plugin/services/BlockchainService.java

@@ -43,8 +43,21 @@ public interface BlockchainService extends BesuService {
    */
   Hash getChainHeadHash();
 
+  /**
+   * Get the receipts for a block by block hash
+   *
+   * @param blockHash the block hash
+   * @return the transaction receipts
+   */
   Optional<List<TransactionReceipt>> getReceiptsByBlockHash(Hash blockHash);
 
+  /**
+   * Store a block
+   *
+   * @param blockHeader the block header
+   * @param blockBody the block body
+   * @param receipts the transaction receipts
+   */
   void storeBlock(BlockHeader blockHeader, BlockBody blockBody, List<TransactionReceipt> receipts);
 
   /**
@@ -61,7 +74,17 @@ public interface BlockchainService extends BesuService {
    */
   Optional<Wei> getNextBlockBaseFee();
 
+  /**
+   * Get the block hash of the safe block
+   *
+   * @return the block hash of the safe block
+   */
   Optional<Hash> getSafeBlock();
 
+  /**
+   * Get the block hash of the finalized block
+   *
+   * @return the block hash of the finalized block
+   */
   Optional<Hash> getFinalizedBlock();
 }

plugin-api/src/main/java/org/hyperledger/besu/plugin/services/p2p/P2PService.java

@@ -16,9 +16,12 @@
 
 import org.hyperledger.besu.plugin.services.BesuService;
 
+/** Service to enable and disable P2P service. */
 public interface P2PService extends BesuService {
 
+  /** Enables P2P discovery. */
   void enableDiscovery();
 
+  /** Disables P2P discovery. */
   void disableDiscovery();
 }

plugin-api/src/main/java/org/hyperledger/besu/plugin/services/rlp/RlpConverterService.java

@@ -21,17 +21,54 @@
 
 import org.apache.tuweni.bytes.Bytes;
 
+/** RLP Serialiaztion/Deserialization service. */
 public interface RlpConverterService extends BesuService {
 
+  /**
+   * Builds a block header from RLP.
+   *
+   * @param rlp the RLP to build the block header from.
+   * @return the block header.
+   */
   BlockHeader buildHeaderFromRlp(final Bytes rlp);
 
+  /**
+   * Builds a block body from RLP.
+   *
+   * @param rlp the RLP to build the block body from.
+   * @return the block body.
+   */
   BlockBody buildBodyFromRlp(final Bytes rlp);
 
+  /**
+   * Builds a transaction receipt from RLP.
+   *
+   * @param rlp the RLP to build the transaction receipt from.
+   * @return the transaction receipt.
+   */
   TransactionReceipt buildReceiptFromRlp(final Bytes rlp);
 
+  /**
+   * RLP encodes a block header.
+   *
+   * @param blockHeader the block header to build RLP from.
+   * @return the RLP.
+   */
   Bytes buildRlpFromHeader(final BlockHeader blockHeader);
 
+  /**
+   * RLP encodes a block body.
+   *
+   * @param blockBody the block body to build RLP from.
+   * @return the RLP.
+   */
   Bytes buildRlpFromBody(final BlockBody blockBody);
 
+  /**
+   * RLP encodes a transaction receipt.
+   *
+   * @param receipt the transaction receipt to build RLP from.
+   * @return the RLP.
+   */
   Bytes buildRlpFromReceipt(final TransactionReceipt receipt);
 }

plugin-api/src/main/java/org/hyperledger/besu/plugin/services/sync/SynchronizationService.java

@@ -19,15 +19,44 @@
 import org.hyperledger.besu.plugin.data.BlockHeader;
 import org.hyperledger.besu.plugin.services.BesuService;
 
+/** Synchronization service wraps the sync state and sync event lifecycle. */
 public interface SynchronizationService extends BesuService {
 
+  /**
+   * Enables P2P discovery.
+   *
+   * @param head the head of the chain.
+   * @param safeBlock the safe block.
+   * @param finalizedBlock the finalized block.
+   */
   void fireNewUnverifiedForkchoiceEvent(Hash head, Hash safeBlock, Hash finalizedBlock);
 
+  /**
+   * Set the head of the chain.
+   *
+   * @param blockHeader the block header
+   * @param blockBody the block body
+   * @return true if the head was set, false otherwise.
+   */
   boolean setHead(final BlockHeader blockHeader, final BlockBody blockBody);
 
+  /**
+   * Adds the block header and body to the head of the chain directly, without using a block
+   * importer or validation.
+   *
+   * @param blockHeader the block header
+   * @param blockBody the block body
+   * @return true if the head was set, false otherwise.
+   */
   boolean setHeadUnsafe(BlockHeader blockHeader, BlockBody blockBody);
 
+  /**
+   * Returns whether the initial chain and worldstate sync is complete.
+   *
+   * @return true if the initial sync phase is done, false otherwise.
+   */
   boolean isInitialSyncPhaseDone();
 
+  /** Disables the worldstate trie for update. */
   void disableWorldStateTrie();
 }

plugin-api/src/main/java/org/hyperledger/besu/plugin/services/sync/WorldStateConfiguration.java

@@ -14,7 +14,13 @@
  */
 package org.hyperledger.besu.plugin.services.sync;
 
+/** interface for worldstate configuration * */
 public interface WorldStateConfiguration {
 
+  /**
+   * Returns whether the trie is disabled.
+   *
+   * @return true if the trie is disabled, false otherwise.
+   */
   boolean isTrieDisabled();
 }

plugin-api/src/main/java/org/hyperledger/besu/plugin/services/transactionpool/TransactionPoolService.java

@@ -16,8 +16,11 @@
 
 import org.hyperledger.besu.plugin.services.BesuService;
 
+/** Service to enable and disable the transaction pool. */
 public interface TransactionPoolService extends BesuService {
+  /** Enables the transaction pool. */
   void disableTransactionPool();
 
+  /** Disables the transaction pool. */
   void enableTransactionPool();
 }

plugin-api/src/main/java/org/hyperledger/besu/plugin/services/trielogs/TrieLogProvider.java

@@ -23,6 +23,13 @@
 
 /** Trielog provider interface for a given block hash. */
 public interface TrieLogProvider {
+  /**
+   * Saves the TrieLog layer for the given block hash.
+   *
+   * @param blockHash the block hash
+   * @param blockNumber the block number
+   * @param trieLog the associated TrieLog layer
+   */
   void saveRawTrieLogLayer(final Hash blockHash, final long blockNumber, final Bytes trieLog);
 
   /**
@@ -34,6 +41,12 @@ public interface TrieLogProvider {
    */
   <T extends TrieLog.LogTuple<?>> Optional<TrieLog> getTrieLogLayer(final Hash blockHash);
 
+  /**
+   * Get the raw TrieLog layer for the given block hash.
+   *
+   * @param blockHash the block hash
+   * @return the raw TrieLog layer bytes for the given block hash
+   */
   Optional<Bytes> getRawTrieLogLayer(final Hash blockHash);
 
   /**
@@ -45,6 +58,12 @@ public interface TrieLogProvider {
    */
   <T extends TrieLog.LogTuple<?>> Optional<TrieLog> getTrieLogLayer(final long blockNumber);
 
+  /**
+   * Get the raw TrieLog layer for the given block number.
+   *
+   * @param blockNumber the block number
+   * @return the raw TrieLog layer bytes for the given block number
+   */
   Optional<Bytes> getRawTrieLogLayer(final long blockNumber);
 
   /**