Merge remote-tracking branch 'upstream/master' into Coverage

contracts/Core/CollectionManager.sol

@@ -347,6 +347,9 @@ contract CollectionManager is Initializable, CollectionStorage, StateManager, Co
         return (medians[index], power);
     }
 
+    /**
+     * @dev updates the idToIndexRegistry and indexToIdRegistry everytime a collection has been activated/deactivated/created
+     */
     function _updateRegistry() internal {
         uint16 j = 0;
         for (uint16 i = 1; i <= numCollections; i++) {
@@ -360,12 +363,18 @@ contract CollectionManager is Initializable, CollectionStorage, StateManager, Co
         }
     }
 
+    /**
+     * @dev hashes the name of the collection and the hashed value is mapped to its corresponding collection ID
+     */
     function _setIDName(string calldata name, uint16 _id) internal {
         bytes32 _name = keccak256(abi.encodePacked(name));
         require(ids[_name] == 0, "Collection exists with same name");
         ids[_name] = _id;
     }
 
+    /**
+     * @dev calculates the current depth of the merkle tree that stakers have to submit at the time of commit/reveal
+     */
     function _getDepth() internal view returns (uint256 n) {
         // numActiveCollection is uint16, so further range not needed
         // Inspired and modified from : https://medium.com/coinmonks/math-in-solidity-part-5-exponent-and-logarithm-9aef8515136e

contracts/Core/RewardManager.sol

@@ -21,9 +21,11 @@ contract RewardManager is Initializable, Constants, RewardManagerParams, IReward
     IBlockManager public blockManager;
     ICollectionManager public collectionManager;
 
-    /** @param stakeManagerAddress The address of the VoteManager contract
+    /**
+     * @param stakeManagerAddress The address of the StakeManager contract
      * @param voteManagersAddress The address of the VoteManager contract
      * @param blockManagerAddress The address of the BlockManager contract
+     * @param collectionManagerAddress The address of the CollectionManager contract
      */
     function initialize(
         address stakeManagerAddress,
@@ -53,6 +55,11 @@ contract RewardManager is Initializable, Constants, RewardManagerParams, IReward
         _giveInactivityPenalties(epoch, stakerId);
     }
 
+    /**
+     * @dev inactivity penalties are given to stakers if they have been inactive for more than the grace period.
+     * For each inactive epoch, stakers lose their age by 1*10000 and their stake by penaltyNotRevealNum.
+     * Activity is calculated based on the epoch the staker last revealed in.
+     */
     function _giveInactivityPenalties(uint32 epoch, uint32 stakerId) internal {
         uint32 epochLastRevealed = voteManager.getEpochLastRevealed(stakerId);
         Structs.Staker memory thisStaker = stakeManager.getStaker(stakerId);
@@ -81,6 +88,12 @@ contract RewardManager is Initializable, Constants, RewardManagerParams, IReward
         }
     }
 
+    /**
+     * @dev Penalties are given to stakers based their activity if they have been inactive for more than the grace period
+     * and their votes in the previous epoch compared to the medians confirmed. Penalties on votes depend upon how far were
+     * the staker's votes from the median value. There is tolerance being added for each collection thereby not penalizing
+     * stakers of their vote was within the tolerance limits of the collection
+     */
     function _givePenalties(uint32 epoch, uint32 stakerId) internal {
         _giveInactivityPenalties(epoch, stakerId);
         Structs.Staker memory thisStaker = stakeManager.getStaker(stakerId);

contracts/Core/StakeManager.sol

@@ -581,9 +581,7 @@ contract StakeManager is Initializable, StakeStorage, StateManager, Pause, Stake
         return stakers[stakerId].epochFirstStakedOrLastPenalized;
     }
 
-    /**
-     * @return length of maturities array
-     */
+    /// @inheritdoc IStakeManager
     function maturitiesLength() external view override returns (uint32) {
         return uint32(maturities.length);
     }

contracts/Core/interface/IStakeManager.sol

@@ -98,5 +98,8 @@ interface IStakeManager {
      */
     function getEpochFirstStakedOrLastPenalized(uint32 stakerId) external view returns (uint32);
 
+    /**
+     * @return length of maturities array
+     */
     function maturitiesLength() external view returns (uint32);
 }

contracts/Core/parameters/ACL.sol

@@ -4,6 +4,9 @@ pragma solidity ^0.8.0;
 import "@openzeppelin/contracts/access/AccessControl.sol";
 
 contract ACL is AccessControl {
+    /**
+     * @dev the deployer of the network is given to the default admin role which gives other roles to contracts
+     */
     constructor() {
         _setupRole(DEFAULT_ADMIN_ROLE, msg.sender);
     }

contracts/Core/parameters/Governance.sol

@@ -24,9 +24,22 @@ contract Governance is Initializable, ACL, Constants {
 
     bytes32 public constant GOVERNER_ROLE = 0x704c992d358ec8f6051d88e5bd9f92457afedcbc3e2d110fcd019b5eda48e52e;
 
-    //event to be emitted when any governance parameter value changes.
+    /**
+     * @notice emitted when any governance parameter value changes.
+     * @param admin address of the admin
+     * @param parameterName the parameter that is changing
+     * @param valueChangedTo new value of the parameter
+     * @param timestamp the exact time the parameter change took place
+     */
     event ParameterChanged(address admin, string parameterName, uint256 valueChangedTo, uint256 timestamp);
 
+    /**
+     * @param blockManagerAddress The address of the BlockManager contract
+     * @param rewardManagerAddress The address of the RewardManager contract
+     * @param stakeManagerAddress The address of the StakeManager contract
+     * @param voteManagerAddress The address of the VoteManager contract
+     * @param collectionManagerAddress The address of the CollectionManager contract
+     */
     function initialize(
         address blockManagerAddress,
         address rewardManagerAddress,
@@ -42,11 +55,23 @@ contract Governance is Initializable, ACL, Constants {
         stakeManager = IStakeManager(stakeManagerAddress);
     }
 
+    /**
+     * @notice changing the percentage stake penalty to be given out for inactivity
+     * @dev can be called only by the the address that has the governer role
+     * @param _penaltyNotRevealNumerator updated value to be set for penaltyNotRevealNumerator
+     */
     function setPenaltyNotRevealNum(uint16 _penaltyNotRevealNumerator) external initialized onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "penaltyNotRevealNum", _penaltyNotRevealNumerator, block.timestamp);
         rewardManagerParams.setPenaltyNotRevealNum(_penaltyNotRevealNumerator);
     }
 
+    /**
+     * @notice changing slashing parameters
+     * @dev can be called only by the the address that has the governer role
+     * @param _bounty updated percent value to be set for bounty
+     * @param _burn updated percent value to be set for burn
+     * @param _keep updated percent value to be set for keep
+     */
     function setSlashParams(
         uint32 _bounty,
         uint32 _burn,
@@ -59,82 +84,157 @@ contract Governance is Initializable, ACL, Constants {
         stakeManagerParams.setSlashParams(_bounty, _burn, _keep);
     }
 
+    /**
+     * @notice changing the number of epochs for which the sRZRs are locked for calling unstake()
+     * @dev can be called only by the the address that has the governer role
+     * @param _unstakeLockPeriod updated value to be set for unstakeLockPeriod
+     */
     function setUnstakeLockPeriod(uint8 _unstakeLockPeriod) external initialized onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "unstakeLockPeriod", _unstakeLockPeriod, block.timestamp);
         stakeManagerParams.setUnstakeLockPeriod(_unstakeLockPeriod);
     }
 
+    /**
+     * @notice changing the number of epochs for which the RAZORs are locked after initiating withdraw
+     * @dev can be called only by the the address that has the governer role
+     * @param _withdrawLockPeriod updated value to be set for withdrawLockPeriod
+     */
     function setWithdrawLockPeriod(uint8 _withdrawLockPeriod) external initialized onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "withdrawLockPeriod", _withdrawLockPeriod, block.timestamp);
         stakeManagerParams.setWithdrawLockPeriod(_withdrawLockPeriod);
     }
 
+    /**
+     * @notice changing the number of epochs where staker/delegator needs to initiate withdraw
+     * @dev can be called only by the the address that has the governer role
+     * @param _withdrawInitiationPeriod updated value to be set for withdrawInitiationPeriod
+     */
     function setWithdrawInitiationPeriod(uint8 _withdrawInitiationPeriod) external initialized onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "withdrawInitiationPeriod", _withdrawInitiationPeriod, block.timestamp);
         stakeManagerParams.setWithdrawInitiationPeriod(_withdrawInitiationPeriod);
     }
 
+    /**
+     * @notice changing percentage stake penalty from the locked amount for extending unstake lock
+     * incase withdrawInitiationPeriod was missed
+     * @dev can be called only by the the address that has the governer role
+     * @param _extendLockPenalty updated value to be set for extendLockPenalty
+     */
     function setExtendUnstakeLockPenalty(uint8 _extendLockPenalty) external initialized onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "extendLockPenalty", _extendLockPenalty, block.timestamp);
         stakeManagerParams.setExtendUnstakeLockPenalty(_extendLockPenalty);
     }
 
+    /**
+     * @notice changing the maximum number of best proposed blocks to be considered for dispute
+     * @dev can be called only by the the address that has the governer role
+     * @param _maxAltBlocks updated value to be set for maxAltBlocks
+     */
     function setMaxAltBlocks(uint8 _maxAltBlocks) external initialized onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "maxAltBlocks", _maxAltBlocks, block.timestamp);
         blockManagerParams.setMaxAltBlocks(_maxAltBlocks);
     }
 
+    /**
+     * @notice changing minimum amount that to be staked for participation
+     * @dev can be called only by the the address that has the governer role
+     * @param _minStake updated value to be set for minStake
+     */
     function setMinStake(uint256 _minStake) external initialized onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "minStake", _minStake, block.timestamp);
         stakeManagerParams.setMinStake(_minStake);
         voteManagerParams.setMinStake(_minStake);
         blockManagerParams.setMinStake(_minStake);
     }
 
+    /**
+     * @notice changing minimum amount that to be staked to become a staker
+     * @dev can be called only by the the address that has the governer role
+     * @param _minSafeRazor updated value to be set for minSafeRazor
+     */
     function setMinSafeRazor(uint256 _minSafeRazor) external initialized onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "minSafeRazor", _minSafeRazor, block.timestamp);
         stakeManagerParams.setMinSafeRazor(_minSafeRazor);
     }
 
+    /**
+     * @notice changing the block reward given out to stakers
+     * @dev can be called only by the the address that has the governer role
+     * @param _blockReward updated value to be set for blockReward
+     */
     function setBlockReward(uint256 _blockReward) external initialized onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "blockReward", _blockReward, block.timestamp);
         blockManagerParams.setBlockReward(_blockReward);
         rewardManagerParams.setBlockReward(_blockReward);
     }
 
+    /**
+     * @notice changing number of epochs for which the staker wont be given inactivity penalties
+     * @dev can be called only by the the address that has the governance role
+     * @param _gracePeriod updated value to be set for gracePeriod
+     */
     function setGracePeriod(uint16 _gracePeriod) external initialized onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "gracePeriod", _gracePeriod, block.timestamp);
         rewardManagerParams.setGracePeriod(_gracePeriod);
         stakeManagerParams.setGracePeriod(_gracePeriod);
     }
 
+    /**
+     * @notice changing the maximum age a staker can have
+     * @dev can be called only by the the address that has the governer role
+     * @param _maxAge updated value to be set for maxAge
+     */
     function setMaxAge(uint32 _maxAge) external initialized onlyRole(GOVERNER_ROLE) {
         require(_maxAge <= stakeManager.maturitiesLength() * 10000, "Invalid Max Age Update");
         emit ParameterChanged(msg.sender, "maxAge", _maxAge, block.timestamp);
         rewardManagerParams.setMaxAge(_maxAge);
     }
 
+    /**
+     * @notice changing maximum commission stakers can charge from delegators on their profits
+     * @dev can be called only by the the address that has the governance role
+     * @param _maxCommission updated value to be set for maxCommission
+     */
     function setMaxCommission(uint8 _maxCommission) external initialized onlyRole(GOVERNER_ROLE) {
         require(_maxCommission <= 100, "Invalid Max Commission Update");
         emit ParameterChanged(msg.sender, "maxCommission", _maxCommission, block.timestamp);
         stakeManagerParams.setMaxCommission(_maxCommission);
     }
 
+    /**
+     * @notice sets escape hatch to false permanently
+     * @dev can be called only by the the address that has the governer role
+     */
     function disableEscapeHatch() external initialized onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "escapeHatchEnabled", 0, block.timestamp);
         stakeManagerParams.disableEscapeHatch();
     }
 
+    /**
+     * @notice changing maximum commission change a staker can do
+     * @dev can be called only by the the address that has the governance role
+     * @param _deltaCommission updated value to be set for deltaCommission
+     */
     function setDeltaCommission(uint8 _deltaCommission) external onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "deltaCommission", _deltaCommission, block.timestamp);
         stakeManagerParams.setDeltaCommission(_deltaCommission);
     }
 
+    /**
+     * @notice changing the number of epochs for which a staker cant change commission once set/change
+     * @dev can be called only by the the address that has the governance role
+     * @param _epochLimitForUpdateCommission updated value to be set for epochLimitForUpdateCommission
+     */
     function setEpochLimitForUpdateCommission(uint16 _epochLimitForUpdateCommission) external onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "epochLimitForUpdateCommission", _epochLimitForUpdateCommission, block.timestamp);
         stakeManagerParams.setEpochLimitForUpdateCommission(_epochLimitForUpdateCommission);
     }
 
+    /**
+     * @notice changing the maximum percentage deviation allowed from medians for all collections
+     * @dev can be called only by the the address that has the governance role
+     * @param _maxTolerance updated value for maxTolerance
+     */
     function setMaxTolerance(uint32 _maxTolerance) external onlyRole(GOVERNER_ROLE) {
         // slither-disable-next-line too-many-digits
         require(_maxTolerance <= BASE_DENOMINATOR, "maxTolerance exceeds 10000000");
@@ -143,6 +243,11 @@ contract Governance is Initializable, ACL, Constants {
         rewardManagerParams.setMaxTolerance(_maxTolerance);
     }
 
+    /**
+     * @notice changing maximum number of collections that can be assigned to the staker
+     * @dev can be called only by the the address that has the governance role
+     * @param _toAssign updated value to be set for toAssign
+     */
     function setToAssign(uint16 _toAssign) external onlyRole(GOVERNER_ROLE) {
         emit ParameterChanged(msg.sender, "toAssign", _toAssign, block.timestamp);
         voteManagerParams.setToAssign(_toAssign);

contracts/Core/parameters/child/BlockManagerParams.sol

@@ -5,20 +5,26 @@ import "../ACL.sol";
 import "../../storage/Constants.sol";
 
 abstract contract BlockManagerParams is ACL, IBlockManagerParams, Constants {
+    /// @notice maximum number of best proposed blocks to be considered for dispute
     uint8 public maxAltBlocks = 5;
+    /// @notice reward given to staker whose block is confirmed
     uint256 public blockReward = 100 * (10**18);
+    /// @notice minimum amount of stake required to participate
     uint256 public minStake = 20000 * (10**18);
 
+    /// @inheritdoc IBlockManagerParams
     function setMaxAltBlocks(uint8 _maxAltBlocks) external override onlyRole(GOVERNANCE_ROLE) {
         // slither-disable-next-line events-maths
         maxAltBlocks = _maxAltBlocks;
     }
 
+    /// @inheritdoc IBlockManagerParams
     function setBlockReward(uint256 _blockReward) external override onlyRole(GOVERNANCE_ROLE) {
         // slither-disable-next-line events-maths
         blockReward = _blockReward;
     }
 
+    /// @inheritdoc IBlockManagerParams
     function setMinStake(uint256 _minStake) external override onlyRole(GOVERNANCE_ROLE) {
         // slither-disable-next-line events-maths
         minStake = _minStake;

contracts/Core/parameters/child/CollectionManagerParams.sol

@@ -5,9 +5,11 @@ import "../ACL.sol";
 import "../../storage/Constants.sol";
 
 abstract contract CollectionManagerParams is ACL, ICollectionManagerParams, Constants {
+    /// @notice maximum percentage deviation allowed from medians for all collections
     // slither-disable-next-line too-many-digits
     uint32 public maxTolerance = 1000000;
 
+    /// @inheritdoc ICollectionManagerParams
     function setMaxTolerance(uint32 _maxTolerance) external override onlyRole(GOVERNANCE_ROLE) {
         // slither-reason: Disabled across all params childs
         // as they are being called by governance contract only