From b1e3e4889e33114ae4c37e94e9409028d3b13bfd Mon Sep 17 00:00:00 2001 From: Sergey <2901744+evercoinx@users.noreply.github.com.> Date: Tue, 17 Sep 2024 18:02:25 +0200 Subject: [PATCH] Add natspec comments to ValidatorRegistry contract --- contracts/ValidatorRegistry.sol | 49 +++++++++------------ contracts/interfaces/IValidatorRegistry.sol | 43 +++++++++++++++++- 2 files changed, 64 insertions(+), 28 deletions(-) diff --git a/contracts/ValidatorRegistry.sol b/contracts/ValidatorRegistry.sol index c4818a37..f86250c7 100644 --- a/contracts/ValidatorRegistry.sol +++ b/contracts/ValidatorRegistry.sol @@ -9,7 +9,7 @@ import { IValidatorShare } from "./interfaces/IValidatorShare.sol"; import { IValidatorRegistry } from "./interfaces/IValidatorRegistry.sol"; /// @title ValidatorRegistry contract -/// @notice ValidatorRegistry is the main contract that manages validators +/// @notice ValidatorRegistry is the main contract that manages validators. contract ValidatorRegistry is IValidatorRegistry, PausableUpgradeable, @@ -30,15 +30,10 @@ contract ValidatorRegistry is uint256[] private validators; address private polToken; - /// -------------------------------modifiers----------------------------------- + /// ------------------------------ Modifiers ------------------------------- - /** - * @dev Modifier to make a function callable only when the validator id exists in our registry. - * @param _validatorId the validator id. - * Requirements: - * - * - The validator id must exist in our registry. - */ + /// @notice Checks if the given validator id exists in the registry. + /// @param _validatorId - Validator id modifier whenValidatorIdExists(uint256 _validatorId) { require( validatorIdExists[_validatorId], @@ -47,14 +42,8 @@ contract ValidatorRegistry is _; } - /** - * @dev Modifier to make a function callable only when the validator id doesn't exist in our registry. - * @param _validatorId the validator id. - * - * Requirements: - * - * - The validator id must not exist in our registry. - */ + /// @notice Checks if the given validator id doesn't exist in the registry. + /// @param _validatorId - Validator id modifier whenValidatorIdDoesNotExist(uint256 _validatorId) { require( !validatorIdExists[_validatorId], @@ -63,13 +52,19 @@ contract ValidatorRegistry is _; } - /// -------------------------- Initialize ---------------------------------- + /// -------------------------- Initializers -------------------------------- + + /// @dev The constructor is disabled for a proxy upgrade. + /// @custom:oz-upgrades-unsafe-allow constructor + constructor() { + _disableInitializers(); + } /// @notice Initialize the ValidatorRegistry contract. - /// @param _stakeManager address of the polygon stake manager. - /// @param _maticToken address of the polygon ERC20 contract. - /// @param _maticX address of the MaticX contract. - /// @param _manager address of the manager. + /// @param _stakeManager address of the polygon stake manager + /// @param _maticToken address of the polygon ERC20 contract + /// @param _maticX address of the MaticX contract + /// @param _manager address of the manager function initialize( address _stakeManager, address _maticToken, @@ -107,8 +102,8 @@ contract ValidatorRegistry is /// ----------------------------- API -------------------------------------- - /// @notice Allows a validator that was already staked on the stake manager - /// to join the MaticX protocol. + /// @notice Allows a validator that has been already staked on the stake + /// manager contract to join the MaticX protocol. /// @param _validatorId - Validator id function addValidator( uint256 _validatorId @@ -139,7 +134,7 @@ contract ValidatorRegistry is } /// @notice Removes a validator from the registry. - /// @param _validatorId - Validator id. + /// @param _validatorId - Validator id // slither-disable-next-line pess-multiple-storage-read function removeValidator( uint256 _validatorId @@ -182,7 +177,7 @@ contract ValidatorRegistry is emit RemoveValidator(_validatorId); } - /// -------------------------------Setters----------------------------------- + /// ------------------------------ Setters --------------------------------- /// @notice Sets the prefered validator id for deposits. /// @param _validatorId - Validator id for deposits @@ -242,7 +237,7 @@ contract ValidatorRegistry is paused() ? _unpause() : _pause(); } - /// -------------------------------Getters----------------------------------- + /// ------------------------------ Getters --------------------------------- /// @notice Returns the contract addresses used on the current contract. /// @return _stakeManager - Address of the stake manager diff --git a/contracts/interfaces/IValidatorRegistry.sol b/contracts/interfaces/IValidatorRegistry.sol index a7a8ae4b..d89a031a 100644 --- a/contracts/interfaces/IValidatorRegistry.sol +++ b/contracts/interfaces/IValidatorRegistry.sol @@ -2,44 +2,80 @@ pragma solidity 0.8.7; /// @title IValidatorRegistry -/// @notice Node validator registry interface +/// @notice Defines a public interface for the ValidatorRegistry contract. interface IValidatorRegistry { + /// @notice Emitted when a validator is joined the MaticX protocol. + /// @param _validatorId - Validator id event AddValidator(uint256 indexed _validatorId); + /// @notice Emitted when a validator is removed from the registry. + /// @param _validatorId - Validator id event RemoveValidator(uint256 indexed _validatorId); + /// @notice Emitted when the preferred validator is set for deposits. + /// @param _validatorId - Validator id event SetPreferredDepositValidatorId(uint256 indexed _validatorId); + /// @notice Emitted when the preferred validator is set for withdrawals. + /// @param _validatorId - Validator id event SetPreferredWithdrawalValidatorId(uint256 indexed _validatorId); + /// @notice Emitted when MaticX is set. + /// @param _address - Address of MaticX event SetMaticX(address _address); + /// @notice Emitted when the new version of the current contract is set. + /// @param _version - Version of the current contract event SetVersion(string _version); + /// @notice Allows a validator that has been already staked on the stake + /// manager contract to join the MaticX protocol. + /// @param _validatorId - Validator id function addValidator(uint256 _validatorId) external; + /// @notice Removes a validator from the registry. + /// @param _validatorId - Validator id function removeValidator(uint256 _validatorId) external; + /// @notice Sets the prefered validator id for deposits. + /// @param _validatorId - Validator id for deposits function setPreferredDepositValidatorId(uint256 _validatorId) external; + /// @notice Set the prefered validator id for withdrawals. + /// @param _validatorId - Validator id for withdrawals function setPreferredWithdrawalValidatorId(uint256 _validatorId) external; + /// @notice Sets the address of MaticX. + /// @param _address - Address of MaticX function setMaticX(address _address) external; + /// @notice Sets a new version of this contract + /// @param _version - New version of this contract function setVersion(string memory _version) external; + /// @notice Toggles the paused status of this contract. function togglePause() external; + /// @notice Returns the version of the current contract. function version() external view returns (string memory); + /// @notice Returns the id of the preferred validator for deposits. function preferredDepositValidatorId() external view returns (uint256); + /// @notice Returns the id of the preferred validator for withdrawals. function preferredWithdrawalValidatorId() external view returns (uint256); + /// @notice Checks if the given validator is joined the MaticX protocol. + /// @param _validatorId - Validator id function validatorIdExists( uint256 _validatorId ) external view returns (bool); + /// @notice Returns the contract addresses used on the current contract. + /// @return _stakeManager - Address of the stake manager + /// @return _maticToken - Address of the Matic token + /// @return _maticX - Address of MaticX + /// @return _polToken - Address of the POL token function getContracts() external view @@ -50,7 +86,12 @@ interface IValidatorRegistry { address _polToken ); + /// @notice Returns the validator id by index. + /// @param _index - Validator index + /// @return Validator id function getValidatorId(uint256 _index) external view returns (uint256); + /// @notice Returns all the validator addresses joined the MaticX protocol. + /// @return List of validator addresses function getValidators() external view returns (uint256[] memory); }