Soloseng/Natspec_and_cleanup

packages/protocol/contracts-0.8/common/CeloUnreleasedTreasury.sol

@@ -28,6 +28,9 @@ contract CeloUnreleasedTreasury is
 
   event Released(address indexed to, uint256 amount);
 
+  /**
+   * @notice Only allows EpochManager to call.
+   */
   modifier onlyEpochManager() {
     require(
       msg.sender == registry.getAddressForOrDie(EPOCH_MANAGER_REGISTRY_ID),
@@ -45,7 +48,6 @@ contract CeloUnreleasedTreasury is
   /**
    * @notice A constructor for initialising a new instance of a CeloUnreleasedTreasury contract.
    * @param registryAddress The address of the registry core smart contract.
-
    */
   function initialize(address registryAddress) external initializer {
     _transferOwnership(msg.sender);

packages/protocol/contracts-0.8/common/EpochManager.sol

@@ -14,6 +14,12 @@ import "../../contracts/common/interfaces/IEpochManager.sol";
 import "../../contracts/common/interfaces/ICeloVersionedContract.sol";
 import "./interfaces/IEpochManagerInitializer.sol";
 
+/**
+ * @title Contract used for managing CELO L2 epoch and elections.
+ * @notice DESIGN_DESICION: we assume that the first epoch on the L2 starts as soon as the system is initialized
+ * to minimize amount of "limbo blocks" the network should stop relatively close to an epoch number (but with enough time)
+ * to have time to call the function `EpochInitializer.migrateEpochAndValidators()`
+ */
 contract EpochManager is
   Initializable,
   UsingRegistry,
@@ -105,6 +111,9 @@ contract EpochManager is
     uint256 delegatedPayment
   );
 
+  /**
+   * @notice Throws if called by other than EpochManagerEnabler contract.
+   */
   modifier onlyEpochManagerEnabler() {
     require(
       msg.sender == registry.getAddressForOrDie(EPOCH_MANAGER_ENABLER_REGISTRY_ID),
@@ -113,6 +122,9 @@ contract EpochManager is
     _;
   }
 
+  /**
+   * @notice Throws if called when EpochManager system has not yet been initalized.
+   */
   modifier onlySystemAlreadyInitialized() {
     require(systemAlreadyInitialized(), "Epoch system not initialized");
     _;
@@ -136,10 +148,6 @@ contract EpochManager is
     setOracleAddress(registry.getAddressForOrDie(SORTED_ORACLES_REGISTRY_ID));
   }
 
-  // DESIGNDESICION(XXX): we assume that the first epoch on the L2 starts as soon as the system is initialized
-  // to minimize amount of "limbo blocks" the network should stop relatively close to an epoch number (but with enough time)
-  // to have time to call the function EpochInitializer.migrateEpochAndValidators()
-
   /**
    * @notice Initializes the EpochManager system, allowing it to start processing epoch
    * and distributing the epoch rewards.
@@ -398,7 +406,7 @@ contract EpochManager is
   }
 
   /**
-   * @notice Returns the epoch info of the specified epoch, for current epoch.
+   * @notice Returns the epoch info of the specified epoch, for the current epoch.
    */
   function getCurrentEpoch()
     external

packages/protocol/contracts-0.8/common/EpochManagerEnabler.sol

@@ -10,6 +10,9 @@ import "../../contracts/governance/interfaces/IEpochRewards.sol";
 import "../../contracts/common/interfaces/IEpochManagerEnabler.sol";
 import "./interfaces/IEpochManagerEnablerInitializer.sol";
 
+/**
+ * @title Contract Used to initialize the EpochManager system after L2 transition.
+ */
 contract EpochManagerEnabler is
   Initializable,
   UsingRegistry,
@@ -66,7 +69,6 @@ contract EpochManagerEnabler is
     _setFirstBlockOfEpoch();
 
     for (uint256 i = 0; i < numberElectedValidators; i++) {
-      // TODO: document how much gas this takes for 110 signers
       address validatorAccountAddress = getAccounts().validatorSignerToAccount(
         validatorSignerAddressFromCurrentSet(i)
       );
@@ -93,6 +95,10 @@ contract EpochManagerEnabler is
     return (1, 1, 0, 0);
   }
 
+  /**
+   * @notice Sets the first block of the current epoch.
+   * @dev Only callable on L1.
+   */
   function _setFirstBlockOfEpoch() internal onlyL1 {
     uint256 blocksSinceEpochBlock = block.number % getEpochSize();
     uint256 epochBlock = block.number - blocksSinceEpochBlock;

packages/protocol/contracts-0.8/common/GasPriceMinimum.sol

@@ -23,7 +23,6 @@ contract GasPriceMinimum is
   IsL2Check,
   CalledByVm
 {
-  // TODO add IGasPriceMinimum
   using FixidityLib for FixidityLib.Fraction;
 
   uint256 private deprecated_gasPriceMinimum;
@@ -165,6 +164,10 @@ contract GasPriceMinimum is
     emit GasPriceMinimumFloorSet(_gasPriceMinimumFloor);
   }
 
+  /**
+   * @notice Returns the gas price minimum.
+   * @return The gas price minimum.
+   */
   function gasPriceMinimum() public view onlyL1 returns (uint256) {
     if (
       deprecated_baseFeeOpCodeActivationBlock > 0 &&

packages/protocol/contracts-0.8/common/IsL2Check.sol

@@ -6,18 +6,28 @@ pragma solidity >=0.5.13 <0.8.20;
 contract IsL2Check {
   address constant proxyAdminAddress = 0x4200000000000000000000000000000000000018;
 
+  /**
+   * @notice Throws if called on L2.
+   */
   modifier onlyL1() {
     allowOnlyL1();
     _;
   }
 
+  /**
+   * @notice Throws if called on L1.
+   */
   modifier onlyL2() {
     if (!isL2()) {
       revert("This method is not supported in L1.");
     }
     _;
   }
 
+  /**
+   * @notice Checks to see if current network is CELO L2.
+   * @return Whether or not the current network is a CELO L2.
+   */
   function isL2() internal view returns (bool) {
     uint32 size;
     address _addr = proxyAdminAddress;
@@ -27,6 +37,10 @@ contract IsL2Check {
     return (size > 0);
   }
 
+  /**
+   * @notice Used to restrict usage of the parent function to L1 execution.
+   * @dev Reverts if called on a CELO L2 network.
+   */
   function allowOnlyL1() internal view {
     if (isL2()) {
       revert("This method is no longer supported in L2.");

packages/protocol/contracts-0.8/common/PrecompilesOverride.sol

@@ -54,7 +54,6 @@ contract PrecompilesOverride is UsingPrecompiles, UsingRegistry {
    * @param index Index of requested validator in the validator set.
    * @return Address of validator at the requested index.
    */
-
   function validatorAddressFromCurrentSet(uint256 index) public view onlyL2 returns (address) {
     return getEpochManager().getElectedAccountByIndex(index);
   }

packages/protocol/contracts-0.8/common/ScoreManager.sol

@@ -8,6 +8,12 @@ import "@openzeppelin/contracts8/access/Ownable.sol";
 import "../../contracts/common/interfaces/IScoreManagerGovernance.sol";
 import "../../contracts/common/interfaces/IScoreManager.sol";
 
+/**
+ * @title ScoreManager contract
+ * @notice This contract updates the score of validators and validator groups on L2.
+ * This replaces the previous method of calculating scores based on validator uptime
+ * with a governable score.
+ **/
 contract ScoreManager is
   Initializable,
   Ownable,
@@ -31,6 +37,9 @@ contract ScoreManager is
   event ValidatorScoreSet(address indexed validator, uint256 score);
   event ScoreManagerSetterSet(address indexed scoreManagerSetter);
 
+  /**
+   * @notice Reverts if msg.sender is not authorized to update score.
+   **/
   modifier onlyAuthorizedToUpdateScore() {
     require(
       msg.sender == owner() || scoreManagerSetter == msg.sender,
@@ -52,7 +61,14 @@ contract ScoreManager is
     _transferOwnership(msg.sender);
   }
 
+  /**
+   * @notice Sets the group score for a specified group.
+   * @param group The address of the group wich score needs to be updated.
+   * @param score The new score of the group to be updated.
+   * @dev Set value to `ZERO_FIXED1_UINT` to set score to zero.
+   **/
   function setGroupScore(address group, uint256 score) external onlyAuthorizedToUpdateScore {
+    require(score > 0, "Score must be greater than ZERO.");
     require(
       score <= ZERO_FIXED1_UINT,
       "Score must be less than or equal to 1e24 or ZERO_FIXED1_UINT."
@@ -62,10 +78,17 @@ contract ScoreManager is
     emit GroupScoreSet(group, score);
   }
 
+  /**
+   * @notice Sets the score for a specified validator.
+   * @param validator The address of the validator wich score needs to be updated.
+   * @param score The new score of the validator to be updated.
+   * @dev Set value to `ZERO_FIXED1_UINT` to set score to zero.
+   **/
   function setValidatorScore(
     address validator,
     uint256 score
   ) external onlyAuthorizedToUpdateScore {
+    require(score > 0, "Score must be greater than ZERO.");
     require(
       score <= ZERO_FIXED1_UINT,
       "Score must be less than or equal to 1e24 or ZERO_FIXED1_UINT."
@@ -75,19 +98,34 @@ contract ScoreManager is
     emit ValidatorScoreSet(validator, score);
   }
 
+  /**
+   * @notice Sets the whitelisted address allowed to set validator and group scores.
+   * @param _scoreManagerSetter Address of whitelisted score setter.
+   **/
   function setScoreManagerSetter(address _scoreManagerSetter) external onlyOwner {
     scoreManagerSetter = _scoreManagerSetter;
     emit ScoreManagerSetterSet(_scoreManagerSetter);
   }
 
+  /**
+   * @notice Returns the score of the specified group.
+   * @param group The address of the group of interest.
+   **/
   function getGroupScore(address group) external view returns (uint256) {
     return getScore(groupScores[group]);
   }
 
+  /**
+   * @notice Returns the score of the specified validator.
+   * @param validator The address of the validator of interest.
+   **/
   function getValidatorScore(address validator) external view returns (uint256) {
     return getScore(validatorScores[validator]);
   }
 
+  /**
+   * @notice Returns the address of the whitelisted score setter.
+   **/
   function getScoreManagerSetter() external view returns (address) {
     return scoreManagerSetter;
   }
@@ -103,6 +141,10 @@ contract ScoreManager is
     return (1, 1, 0, 0);
   }
 
+  /**
+   * @notice Returns the actual score based on the input value.
+   * @param score The value from `validatorScores` or `groupScores` mappings .
+   **/
   function getScore(uint256 score) internal pure returns (uint256) {
     if (score == 0) {
       return FIXED1_UINT;

packages/protocol/contracts-0.8/governance/Validators.sol

@@ -250,17 +250,13 @@ contract Validators is
    * @return True upon success.
    * @dev Fails if the account is already a validator or validator group.
    * @dev Fails if the account does not have sufficient Locked Gold.
+   * @dev Fails on L2. Use registerValidatorNoBls instead.
    */
   function registerValidator(
     bytes calldata ecdsaPublicKey,
     bytes calldata blsPublicKey,
     bytes calldata blsPop
-  )
-    external
-    nonReentrant
-    onlyL1 // For L2, use registerValidatorNoBls
-    returns (bool)
-  {
+  ) external nonReentrant onlyL1 returns (bool) {
     address account = getAccounts().validatorSignerToAccount(msg.sender);
     _isRegistrationAllowed(account);
     require(!isValidator(account) && !isValidatorGroup(account), "Already registered");
@@ -652,7 +648,7 @@ contract Validators is
   // to allow `EpochManager` to mint.
   /**
    * @notice Allows the EpochManager contract to mint stable token for itself.
-   * @param amount The amount to be minted.
+   * @param amount The amount of stableToken to be minted.
    */
   function mintStableToEpochManager(
     uint256 amount
@@ -733,6 +729,12 @@ contract Validators is
     return topValidators;
   }
 
+  /**
+   * @notice Retreives the top validator accounts of the specified group.
+   * @param account The address of the validator group.
+   * @param n The number of members to return.
+   * @return The accounts of the top n group members for a particular group.
+   */
   function getTopGroupValidatorsAccounts(
     address account,
     uint256 n

packages/protocol/contracts/common/Accounts.sol

@@ -132,6 +132,9 @@ contract Accounts is
     _setEip712DomainSeparator();
   }
 
+  /**
+   * @notice Sets the EIP712 domain separator for the Celo Accounts abstraction.
+   */
   function setEip712DomainSeparator() external {
     _setEip712DomainSeparator();
   }

packages/protocol/contracts/common/Blockable.sol

@@ -15,20 +15,27 @@ contract Blockable is IBlockable {
 
   event BlockedBySet(address indexed _blockedBy);
 
-  /// @notice Modifier to ensure the function is only executed when the contract is not blocked.
-  /// @dev Reverts with an error if the contract is blocked.
+  /**
+   * @notice Modifier to ensure the function is only executed when the contract is not blocked.
+   * @dev Reverts with an error if the contract is blocked.
+   **/
   modifier onlyWhenNotBlocked() {
     require(!_isBlocked(), "Contract is blocked from performing this action");
     _;
   }
 
-  /// @notice Checks if the contract is currently blocked.
-  /// @return Returns true if the contract is blocked, otherwise false.
-  /// @dev The function returns false if no blocking contract has been set.
+  /**
+   * @notice Checks if the contract is currently blocked.
+   * @return Returns true if the contract is blocked, otherwise false.
+   * @dev The function returns false if no blocking contract has been set.
+   **/
   function isBlocked() external view returns (bool) {
     return _isBlocked();
   }
 
+  /**
+   * @notice Returns the address of the contract imposing the block.
+   **/
   function getBlockedbyContract() public view returns (address blockedBy) {
     bytes32 blockedByPosition = BLOCKEDBY_POSITION;
     assembly {
@@ -37,6 +44,10 @@ contract Blockable is IBlockable {
     return blockedBy;
   }
 
+  /**
+   * @notice Sets the address of the contract allowed to impose a block.
+   * @param _blockedBy The address of the contract that will impose a block.
+   **/
   function _setBlockedBy(address _blockedBy) internal {
     bytes32 blockedByPosition = BLOCKEDBY_POSITION;
     assembly {
@@ -46,6 +57,9 @@ contract Blockable is IBlockable {
     emit BlockedBySet(_blockedBy);
   }
 
+  /**
+   * @notice Checks if the contract is currently blocked.
+   **/
   function _isBlocked() internal view returns (bool) {
     if (getBlockedbyContract() == address(0)) {
       return false;

packages/protocol/contracts/common/PrecompilesOverride.sol

@@ -51,7 +51,6 @@ contract PrecompilesOverride is UsingPrecompiles, UsingRegistry {
    * @param index Index of requested validator in the validator set.
    * @return Address of validator at the requested index.
    */
-
   function validatorAddressFromCurrentSet(uint256 index) public view onlyL2 returns (address) {
     return getEpochManager().getElectedAccountByIndex(index);
   }