chore: Add more HSCS javadocs (#16600)

Signed-off-by: Petar Tonev <petar.tonev@limechain.tech>

hedera-node/hedera-smart-contract-service-impl/src/main/java/com/hedera/node/app/service/contract/impl/exec/gas/DispatchGasCalculator.java

@@ -21,6 +21,10 @@
 import com.hedera.node.app.service.contract.impl.hevm.HederaWorldUpdater.Enhancement;
 import edu.umd.cs.findbugs.annotations.NonNull;
 
+/**
+ * A {@link DispatchGasCalculator} that calculates the gas requirement for the dispatch, given the transaction body,
+ * payer, {@link SystemContractGasCalculator} and the {@link Enhancement} in the dispatch context
+ */
 @FunctionalInterface
 public interface DispatchGasCalculator {
     /**

hedera-node/hedera-smart-contract-service-impl/src/main/java/com/hedera/node/app/service/contract/impl/exec/systemcontracts/hts/DispatchForResponseCodeHtsCall.java

@@ -130,6 +130,7 @@ public DispatchForResponseCodeHtsCall(
      * @param attempt the attempt to translate to a dispatching
      * @param syntheticBody the synthetic body to dispatch
      * @param dispatchGasCalculator the dispatch gas calculator to use
+     * @param failureCustomizer the status customizer to use
      */
     public DispatchForResponseCodeHtsCall(
             @NonNull final HtsCallAttempt attempt,
@@ -153,6 +154,7 @@ public DispatchForResponseCodeHtsCall(
      * @param attempt the attempt to translate to a dispatching
      * @param syntheticBody the synthetic body to dispatch
      * @param dispatchGasCalculator the dispatch gas calculator to use
+     * @param outputFn the output function to use
      */
     public DispatchForResponseCodeHtsCall(
             @NonNull final HtsCallAttempt attempt,
@@ -174,6 +176,7 @@ public DispatchForResponseCodeHtsCall(
      * More general constructor, for cases where perhaps a custom {@link VerificationStrategy} is needed.
      *
      * @param enhancement the enhancement to use
+     * @param gasCalculator the gas calculator for the system contract
      * @param senderId the id of the spender
      * @param syntheticBody the synthetic body to dispatch
      * @param verificationStrategy the verification strategy to use

hedera-node/hedera-smart-contract-service-impl/src/main/java/com/hedera/node/app/service/contract/impl/exec/systemcontracts/hts/allowance/GetAllowanceCall.java

@@ -41,6 +41,9 @@
 import javax.inject.Inject;
 import javax.inject.Singleton;
 
+/**
+ * Implements the token redirect {@code allowance()} call of the HTS system contract.
+ */
 @Singleton
 public class GetAllowanceCall extends AbstractCall {
 
@@ -53,6 +56,16 @@ public class GetAllowanceCall extends AbstractCall {
     @Nullable
     private final Token token;
 
+    /**
+     * @param addressIdConverter the address ID converter for this call
+     * @param gasCalculator the gas calculator to be used
+     * @param enhancement the enhancement to be used
+     * @param token the token id that the token allowance pertains to
+     * @param owner the account id of the token owner
+     * @param spender the account id of the token allowance spender
+     * @param isERCCall whether this is an ERC call
+     * @param isStaticCall whether this is a static call
+     */
     @Inject
     public GetAllowanceCall(
             @NonNull final AddressIdConverter addressIdConverter,

hedera-node/hedera-smart-contract-service-impl/src/main/java/com/hedera/node/app/service/contract/impl/exec/systemcontracts/hts/create/CreateDecoder.java

@@ -516,6 +516,16 @@ private TokenCreateWrapper getTokenCreateWrapper(
         return tokenCreateWrapper;
     }
 
+    /**
+     * @param tokenCreateStruct the token struct to use
+     * @param isFungible whether the token is fungible
+     * @param initSupply the initial supply of the token
+     * @param decimals decimals of the token
+     * @param senderId the sender account id
+     * @param nativeOperations the Hedera native operation
+     * @param addressIdConverter the address ID converter for this call
+     * @return a token create wrapper object
+     */
     public TokenCreateWrapper getTokenCreateWrapperWithMetadata(
             @NonNull final Tuple tokenCreateStruct,
             final boolean isFungible,

hedera-node/hedera-smart-contract-service-impl/src/main/java/com/hedera/node/app/service/contract/impl/exec/systemcontracts/hts/create/CreateDecoderFunction.java

@@ -21,9 +21,19 @@
 import com.hedera.node.app.service.contract.impl.exec.scope.HederaNativeOperations;
 import com.hedera.node.app.service.contract.impl.exec.systemcontracts.hts.AddressIdConverter;
 
+/**
+ * A decoder function used for decoding create calls to HTS system contract.
+ */
 @FunctionalInterface
 public interface CreateDecoderFunction {
 
+    /**
+     * @param input the raw input of thе call to decode
+     * @param senderID the account id of the sender account
+     * @param nativeOps the native Hedera operations
+     * @param converter the address id converter
+     * @return the transaction body of the call
+     */
     TransactionBody decode(
             byte[] input, AccountID senderID, HederaNativeOperations nativeOps, AddressIdConverter converter);
 }

hedera-node/hedera-smart-contract-service-impl/src/main/java/com/hedera/node/app/service/contract/impl/exec/systemcontracts/hts/create/CreateTranslator.java

@@ -138,9 +138,10 @@ public class CreateTranslator extends AbstractCallTranslator<HtsCallAttempt> {
                     + ARRAY_BRACKETS
                     + ")",
             "(int64,address)");
-
+    /** Selector for createFungibleTokenWithCustomFees(HEDERA_TOKEN_WITH_METADATA,int64,int32) method. */
     public static final Function CREATE_FUNGIBLE_TOKEN_WITH_METADATA =
             new Function("createFungibleToken(" + HEDERA_TOKEN_WITH_METADATA + ",int64,int32)", "(int64,address)");
+    /** Selector for createFungibleTokenWithCustomFees(HEDERA_TOKEN_WITH_METADATA,int64,int32,FIXED_FEE_2[],FRACTIONAL_FEE_2[]) method. */
     public static final Function CREATE_FUNGIBLE_TOKEN_WITH_METADATA_AND_CUSTOM_FEES = new Function(
             "createFungibleTokenWithCustomFees("
                     + HEDERA_TOKEN_WITH_METADATA
@@ -152,8 +153,10 @@ public class CreateTranslator extends AbstractCallTranslator<HtsCallAttempt> {
                     + ARRAY_BRACKETS
                     + ")",
             "(int64,address)");
+    /** Selector for createNonFungibleToken(HEDERA_TOKEN_WITH_METADATA) method. */
     public static final Function CREATE_NON_FUNGIBLE_TOKEN_WITH_METADATA =
             new Function("createNonFungibleToken(" + HEDERA_TOKEN_WITH_METADATA + ")", "(int64,address)");
+    /** Selector for createNonFungibleTokenWithCustomFees(HEDERA_TOKEN_WITH_METADATA,FIXED_FEE_2[],FRACTIONAL_FEE_2[]) method. */
     public static final Function CREATE_NON_FUNGIBLE_TOKEN_WITH_METADATA_AND_CUSTOM_FEES = new Function(
             "createNonFungibleTokenWithCustomFees("
                     + HEDERA_TOKEN_WITH_METADATA

hedera-node/hedera-smart-contract-service-impl/src/main/java/com/hedera/node/app/service/contract/impl/infra/EthTxSigsCache.java

@@ -25,6 +25,9 @@
 import javax.inject.Inject;
 import javax.inject.Singleton;
 
+/**
+ * A class that is used for easy access of Ethereum signatures.
+ */
 @Singleton
 public class EthTxSigsCache {
     private static final int ETH_SIGS_CACHE_TTL_SECS = 15;
@@ -34,11 +37,18 @@ public class EthTxSigsCache {
             .softValues()
             .build(EthTxSigs::extractSignatures);
 
+    /**
+     * Default constructor for injection
+     */
     @Inject
     public EthTxSigsCache() {
         // Dagger2
     }
 
+    /**
+     * @param data the Ethereum data that we want to sign
+     * @return return the Ethereum signature
+     */
     public EthTxSigs computeIfAbsent(@NonNull final EthTxData data) {
         // Since preHandle() is multi-threaded, we are happy to synchronously load the signatures
         // for this EthTxData if they are not already cached; with a 15s TTL, this should make the

hedera-node/hedera-smart-contract-service-impl/src/main/java/com/hedera/node/app/service/contract/impl/records/ContractOperationStreamBuilder.java

@@ -29,7 +29,7 @@
 import java.util.Set;
 
 /**
- * A {@code StreamBuilder} specialization for tracking the side effects of any transaction that can delete accounts or contracts.
+ * A {@code StreamBuilder} specialization for tracking the side effects of any transaction related to contracts.
  * These include:
  * <ol>
  *     <li>{@link HederaFunctionality#CRYPTO_DELETE}</li>

hedera-node/hedera-smart-contract-service-impl/src/main/java/com/hedera/node/app/service/contract/impl/records/EthereumTransactionStreamBuilder.java

@@ -17,12 +17,16 @@
 package com.hedera.node.app.service.contract.impl.records;
 
 import com.hedera.hapi.node.base.ContractID;
+import com.hedera.hapi.node.base.HederaFunctionality;
 import com.hedera.hapi.node.base.ResponseCodeEnum;
 import com.hedera.hapi.node.contract.ContractFunctionResult;
 import com.hedera.pbj.runtime.io.buffer.Bytes;
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 
+/**
+ * A {@code StreamBuilder} specialization for tracking the side effects of {@link HederaFunctionality#ETHEREUM_TRANSACTION} transaction.
+ */
 public interface EthereumTransactionStreamBuilder extends ContractOperationStreamBuilder {
     /**
      * Tracks the final status of a HAPI Ethereum transaction.

hedera-node/hedera-smart-contract-service-impl/src/main/java/com/hedera/node/app/service/contract/impl/state/DispatchingEvmFrameState.java

@@ -115,6 +115,10 @@ public class DispatchingEvmFrameState implements EvmFrameState {
     private final HederaNativeOperations nativeOperations;
     private final ContractStateStore contractStateStore;
 
+    /**
+     * @param nativeOperations the Hedera native operation
+     * @param contractStateStore the contract store that manages the key/value states
+     */
     public DispatchingEvmFrameState(
             @NonNull final HederaNativeOperations nativeOperations,
             @NonNull final ContractStateStore contractStateStore) {

hedera-node/hedera-smart-contract-service-impl/src/main/java/com/hedera/node/app/service/contract/impl/state/EvmFrameState.java

@@ -96,6 +96,8 @@ Optional<ExceptionalHaltReason> tryTransfer(
     /**
      * Returns whether the account with the given address is a "hollow account"; that is, an account
      * created by a value transfer to a 20-byte alias, without an explicit cryptographic key given.
+     * @param address the address of the account which should be checked if it is a hollow account
+     * @return true if the account is hollow
      */
     boolean isHollowAccount(@NonNull Address address);
 
@@ -197,6 +199,10 @@ Optional<ExceptionalHaltReason> tryTrackingSelfDestructBeneficiary(
     @NonNull
     Bytes getTokenRedirectCode(@NonNull Address address);
 
+    /**
+     * @param contractID the contract to extract its code hash
+     * @return the code hash of the contract
+     */
     @NonNull
     Hash getCodeHash(ContractID contractID);
 

hedera-node/hedera-smart-contract-service-impl/src/test/java/com/hedera/node/app/service/contract/impl/test/exec/systemcontracts/CallAttemptHelpers.java

@@ -177,6 +177,7 @@ public static HtsCallAttempt prepareHtsAttemptWithSelectorAndCustomConfig(
      * @param enhancement the enhancement that is used
      * @param addressIdConverter the address ID converter for this call
      * @param verificationStrategies the verification strategy currently used
+     * @param signatureVerifier a function that verifies a signature
      * @param gasCalculator the gas calculator used for the system contract
      * @return the call attempt
      */
@@ -199,6 +200,17 @@ public static HasCallAttempt prepareHasAttemptWithSelector(
                 DEFAULT_CONFIG);
     }
 
+    /**
+     * @param function the selector to match against
+     * @param translator the translator for this specific call attempt
+     * @param enhancement the enhancement that is used
+     * @param addressIdConverter the address ID converter for this call
+     * @param verificationStrategies the verification strategy currently used
+     * @param signatureVerifier a function that verifies a signature
+     * @param gasCalculator the gas calculator used for the system contract
+     * @param config the configuration being used
+     * @return the call attempt
+     */
     public static HasCallAttempt prepareHasAttemptWithSelectorAndCustomConfig(
             final Function function,
             final CallTranslator<HasCallAttempt> translator,
@@ -220,6 +232,18 @@ public static HasCallAttempt prepareHasAttemptWithSelectorAndCustomConfig(
                 config);
     }
 
+    /**
+     * @param function the selector to match against
+     * @param input the input in bytes
+     * @param translator the translator for this specific call attempt
+     * @param enhancement the enhancement that is used
+     * @param addressIdConverter the address ID converter for this call
+     * @param verificationStrategies the verification strategy currently used
+     * @param signatureVerifier a function that verifies a signature
+     * @param gasCalculator the gas calculator used for the system contract
+     * @param config the configuration being used
+     * @return the call attempt
+     */
     public static HasCallAttempt prepareHasAttemptWithSelectorAndInputAndCustomConfig(
             final Function function,
             final Bytes input,