Audit: APEX-475 Missing NatSpec

contracts/Gateway.sol

@@ -9,6 +9,9 @@ import {IGatewayStructs} from "./interfaces/IGatewayStructs.sol";
 import {IValidators} from "./interfaces/IValidators.sol";
 import {NativeTokenPredicate} from "./NativeTokenPredicate.sol";
 
+/// @title Gateway Contract
+/// @notice This contract serves as a gateway for managing token deposits, withdrawals, and validator updates.
+/// @dev Inherits functionality from OpenZeppelin's Initializable, OwnableUpgradeable, and UUPSUpgradeable.
 contract Gateway is
     IGateway,
     Initializable,
@@ -49,6 +52,11 @@ contract Gateway is
         validators = IValidators(_validators);
     }
 
+    /// @notice Deposits tokens into the system.
+    /// @param _signature The BLS signature for validation.
+    /// @param _bitmap The bitmap associated with the BLS signature.
+    /// @param _data The deposit data in bytes format.
+    /// @dev Emits either a `Deposit` or `TTLExpired` event based on success.
     function deposit(
         bytes calldata _signature,
         uint256 _bitmap,
@@ -67,6 +75,11 @@ contract Gateway is
         }
     }
 
+    /// @notice Withdraws tokens from the system.
+    /// @param _destinationChainId The ID of the destination chain.
+    /// @param _receivers The array of receivers and their withdrawal amounts.
+    /// @param _feeAmount The fee for the withdrawal process.
+    /// @dev Ensures that the sum of withdrawal amounts matches the value sent.
     function withdraw(
         uint8 _destinationChainId,
         ReceiverWithdraw[] calldata _receivers,
@@ -99,6 +112,11 @@ contract Gateway is
         );
     }
 
+    /// @notice Updates validator chain data.
+    /// @param _signature The BLS signature for validation.
+    /// @param _bitmap The bitmap associated with the BLS signature.
+    /// @param _data The new validator chain data in bytes format.
+    /// @dev Restricted to the owner of the contract.
     function updateValidatorsChainData(
         bytes calldata _signature,
         uint256 _bitmap,
@@ -112,6 +130,9 @@ contract Gateway is
         validators.updateValidatorsChainData(_data);
     }
 
+    /// @notice Transfers an amount to the native token wallet.
+    /// @param value The amount to be transferred.
+    /// @dev Reverts if the transfer fails.
     function transferAmountToWallet(uint256 value) internal {
         address nativeTokenWalletAddress = address(
             nativeTokenPredicate.nativeTokenWallet()
@@ -121,6 +142,10 @@ contract Gateway is
         if (!success) revert TransferFailed();
     }
 
+    /// @notice Sets the minimal amounts for fee and bridging.
+    /// @param _minFeeAmount The minimal fee amount to set
+    /// @param _minBridgingAmount The minimal bridging amount to set
+    /// @dev Restricted to the owner of the contract.
     function setMinAmounts(
         uint256 _minFeeAmount,
         uint256 _minBridgingAmount
@@ -131,6 +156,8 @@ contract Gateway is
         emit MinAmountsUpdated(_minFeeAmount, _minBridgingAmount);
     }
 
+    /// @notice Handles receiving Ether and transfers it to the native token wallet.
+    /// @dev Emits a `FundsDeposited` event upon receiving Ether.
     receive() external payable {
         transferAmountToWallet(msg.value);
 

contracts/NativeTokenPredicate.sol

@@ -14,10 +14,11 @@ import {IGateway} from "./interfaces/IGateway.sol";
 import {IGatewayStructs} from "./interfaces/IGatewayStructs.sol";
 
 /**
-    @title ERC20TokenPredicate
-    @notice Enables ERC20 token deposits and withdrawals across an arbitrary root chain and token chain
+ * @title NativeTokenPredicate
+ * @notice Facilitates deposits and withdrawals of native tokens across chains.
+ * @dev Implements deposit functionality and manages dependencies for native token operations.
+ * Inherits from OpenZeppelin's Initializable, OwnableUpgradeable, UUPSUpgradeable, and ReentrancyGuard.
  */
-// solhint-disable reason-string
 contract NativeTokenPredicate is
     INativeTokenPredicate,
     Initializable,
@@ -31,6 +32,8 @@ contract NativeTokenPredicate is
     INativeTokenWallet public nativeTokenWallet;
     mapping(uint64 => bool) public unused1; // remove it before deploying to production
     uint64 public unused2; // remove it before deploying to production
+
+    /// @notice Tracks the ID of the last processed batch.
     uint64 public lastBatchId;
 
     /// @custom:oz-upgrades-unsafe-allow constructor
@@ -62,9 +65,11 @@ contract NativeTokenPredicate is
     }
 
     /**
-     * @notice Function to be used for token deposits
-     * @param _data Data sent by the sender
-     * @dev Can be extended to include other signatures for more functionality
+     * @notice Handles token deposits.
+     * @param _data Encoded deposit data, including batch ID, TTL, and receiver details.
+     * @param _relayer Address of the relayer initiating the deposit.
+     * @return success Indicates whether the deposit operation succeeded.
+     * @dev Validates batch ID, TTL expiration, and performs deposits for receivers and the relayer.
      */
     function deposit(
         bytes calldata _data,

contracts/NativeTokenWallet.sol

@@ -9,10 +9,10 @@ import {INativeTokenWallet} from "./interfaces/INativeTokenWallet.sol";
 import {NativeTokenPredicate} from "./NativeTokenPredicate.sol";
 
 /**
-    @title NativeToken
-    @notice Native token contract
+ * @title NativeTokenWallet
+ * @notice A wallet contract to manage native token deposits and interactions.
+ * @dev Supports upgradeability using OpenZeppelin's UUPS module and adheres to IGatewayStructs and INativeTokenWallet interfaces.
  */
-// solhint-disable reason-string
 contract NativeTokenWallet is
     Initializable,
     OwnableUpgradeable,
@@ -42,11 +42,12 @@ contract NativeTokenWallet is
     }
 
     /**
-     * @notice Deposits an amount of tokens to a particular address
-     * @dev Can only be called by the predicate or owner address
-     * @param _account Account of the user to mint the tokens to
-     * @param _amount Amount of tokens to mint to the account
-     * @return bool Returns true if function call is successful
+     * @notice Deposits an amount of native tokens to a specific account.
+     * @param _account The address of the account to deposit tokens to.
+     * @param _amount The amount of tokens to deposit.
+     * @return success A boolean indicating whether the deposit was successful.
+     * @dev Can only be called by the predicate contract or the contract owner.
+     * Reverts if the transfer fails.
      */
     function deposit(
         address _account,

contracts/Validators.sol

@@ -8,6 +8,11 @@ import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
 import {IValidators} from "./interfaces/IValidators.sol";
 import {IGatewayStructs} from "./interfaces/IGatewayStructs.sol";
 
+/**
+ * @title Validators
+ * @notice Manages validator chain data and BLS signature verification for the Gateway system.
+ * @dev Supports upgradeability using OpenZeppelin's UUPS module. Implements the IValidators interface.
+ */
 contract Validators is
     IValidators,
     Initializable,
@@ -43,6 +48,11 @@ contract Validators is
         address newImplementation
     ) internal override onlyOwner {}
 
+    /**
+     * @notice Sets the initial validators chain data.
+     * @param _validatorsChainData Array of validator chain data.
+     * @dev Deletes any existing data and replaces it with the provided array.
+     */
     function setValidatorsChainData(
         ValidatorChainData[] calldata _validatorsChainData
     ) external onlyOwner {
@@ -52,6 +62,11 @@ contract Validators is
         }
     }
 
+    /**
+     * @notice Updates the validators chain data with new values.
+     * @param _data Encoded data containing the validators set number, TTL, and new validator chain data.
+     * @dev Reverts if the provided validators set number is invalid. Emits `TTLExpired` if the TTL has expired.
+     */
     function updateValidatorsChainData(
         bytes calldata _data
     ) external onlyGateway {
@@ -88,6 +103,14 @@ contract Validators is
         return validatorsChainData;
     }
 
+    /**
+     * @notice Verifies the validity of a BLS signature.
+     * @param _hash Hash of the data to be verified.
+     * @param _signature BLS signature to validate.
+     * @param _bitmap Bitmap representing validator participation.
+     * @return valid Boolean indicating whether the signature is valid.
+     * @dev Calls the BLS precompile contract for verification. Uses gas limit `VALIDATOR_BLS_PRECOMPILE_GAS`.
+     */
     function isBlsSignatureValid(
         bytes32 _hash,
         bytes calldata _signature,