Lido v2 fix comments

README.md

@@ -3,11 +3,11 @@
 [![Tests](https://github.com/lidofinance/lido-dao/workflows/Tests/badge.svg)](https://github.com/lidofinance/lido-dao/actions)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 
-The Lido Ethereum Liquid Staking Protocol allows their users to earn staking rewards on the Beacon chain without locking Ether or maintaining staking infrastructure.
+The Lido Ethereum Liquid Staking Protocol allows their users to earn staking rewards on the Beacon Chain without locking ether or maintaining staking infrastructure.
 
-Users can deposit Ether to the Lido smart contract and receive stETH tokens in return. The smart contract then stakes tokens with the DAO-picked node operators. Users' deposited funds are pooled by the DAO, node operators never have direct access to the users' assets.
+Users can deposit ether to the Lido smart contract and receive stETH tokens in return. The smart contract then stakes tokens with the DAO-picked node operators. Users' deposited funds are pooled by the DAO, node operators never have direct access to the users' assets.
 
-Unlike staked ether, the stETH token is free from the limitations associated with a lack of liquidity and can be transferred at any time. The stETH token balance corresponds to the amount of Ether that the holder could request to withdraw.
+Unlike staked ether, the stETH token is free from the limitations associated with a lack of liquidity and can be transferred at any time. The stETH token balance corresponds to the amount of ether that the holder could request to withdraw.
 
 Before getting started with this repo, please read:
 

contracts/0.4.24/Lido.sol

@@ -179,7 +179,7 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     /// @dev storage slot position of the staking rate limit structure
     bytes32 internal constant STAKING_STATE_POSITION =
         0xa3678de4a579be090bed1177e0a24f77cc29d181ac22fd7688aca344d8938015; // keccak256("lido.Lido.stakeLimit");
-    /// @dev amount of Ether (on the current Ethereum side) buffered on this smart contract balance
+    /// @dev amount of ether (on the current Ethereum side) buffered on this smart contract balance
     bytes32 internal constant BUFFERED_ETHER_POSITION =
         0xed310af23f61f96daefbcd140b306c0bdbf8c178398299741687b90e794772b0; // keccak256("lido.Lido.bufferedEther");
     /// @dev number of deposited validators (incrementing counter of deposit operations).
@@ -314,9 +314,9 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     }
 
     /**
-     * @notice Stops accepting new Ether to the protocol
+     * @notice Stops accepting new ether to the protocol
      *
-     * @dev While accepting new Ether is stopped, calls to the `submit` function,
+     * @dev While accepting new ether is stopped, calls to the `submit` function,
      * as well as to the default payable function, will revert.
      *
      * Emits `StakingPaused` event.
@@ -328,7 +328,7 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     }
 
     /**
-     * @notice Resumes accepting new Ether to the protocol (if `pauseStaking` was called previously)
+     * @notice Resumes accepting new ether to the protocol (if `pauseStaking` was called previously)
      * NB: Staking could be rate-limited by imposing a limit on the stake amount
      * at each moment in time, see `setStakingLimit()` and `removeStakingLimit()`
      *
@@ -397,7 +397,7 @@ contract Lido is Versioned, StETHPermit, AragonApp {
 
 
     /**
-     * @notice Returns how much Ether can be staked in the current block
+     * @notice Returns how much ether can be staked in the current block
      * @dev Special return values:
      * - 2^256 - 1 if staking is unlimited;
      * - 0 if staking is paused or if limit is exhausted.
@@ -444,10 +444,10 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     }
 
     /**
-    * @notice Send funds to the pool
-    * @dev Users are able to submit their funds by transacting to the fallback function.
+    * @notice Sends funds to the pool and mints `StETH` tokens to the `msg.sender` address
+    * @dev Users are able to submit their funds by sending ether to the contract address.
     * Unlike vanilla Ethereum Deposit contract, accepting only 32-Ether transactions, Lido
-    * accepts payments of any size. Submitted Ethers are stored in Buffer until someone calls
+    * accepts payments of any size. Submitted ether are stored in the buffer until someone calls
     * deposit() and pushes them to the Ethereum Deposit contract.
     */
     // solhint-disable-next-line no-complex-fallback
@@ -458,8 +458,8 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     }
 
     /**
-     * @notice Send funds to the pool with optional _referral parameter
-     * @dev This function is alternative way to submit funds. Supports optional referral address.
+     * @notice Sends funds to the pool with the optional `_referral` parameter and mints `StETH` tokens to the `msg.sender` address
+     * @param _referral optonal referral address. See https://lido.fi/referral for details.
      * @return Amount of StETH shares generated
      */
     function submit(address _referral) external payable returns (uint256) {
@@ -602,13 +602,12 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     }
 
     /**
-     * @notice Unsafely change deposited validators
+     * @notice Unsafely change deposited validators counter
      *
-     * The method unsafely changes deposited validator counter.
-     * Can be required when onboarding external validators to Lido
+     * @dev Can be required when onboarding external validators to Lido
      * (i.e., had deposited before and rotated their type-0x00 withdrawal credentials to Lido)
      *
-     * @param _newDepositedValidators new value
+     * @param _newDepositedValidators new value for deposited validators counter
      */
     function unsafeChangeDepositedValidators(uint256 _newDepositedValidators) external {
         _auth(UNSAFE_CHANGE_DEPOSITED_VALIDATORS_ROLE);
@@ -626,7 +625,7 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     }
 
     /**
-    * @notice Get the amount of Ether temporary buffered on this contract balance
+    * @notice Get the amount of ether temporary buffered on this contract balance
     * @dev Buffered balance is kept on the contract from the moment the funds are received from user
     * until the moment they are actually sent to the official Deposit contract.
     * @return amount of buffered funds in wei
@@ -637,17 +636,16 @@ contract Lido is Versioned, StETHPermit, AragonApp {
 
     /**
      * @notice Get total amount of execution layer rewards collected to Lido contract
-     * @dev Ether got through LidoExecutionLayerRewardsVault is kept on this contract's balance the same way
-     * as other buffered Ether is kept (until it gets deposited)
+     * @dev ether got through LidoExecutionLayerRewardsVault is kept on this contract's balance the same way
+     * as other buffered ether is kept (until it gets deposited)
      * @return amount of funds received as execution layer rewards in wei
      */
     function getTotalELRewardsCollected() public view returns (uint256) {
         return TOTAL_EL_REWARDS_COLLECTED_POSITION.getStorageUint256();
     }
 
     /**
-     * @notice Gets authorized oracle address
-     * @return address of oracle contract
+     * @notice address of LidoLocator
      */
     function getLidoLocator() public view returns (ILidoLocator) {
         return ILidoLocator(LIDO_LOCATOR_POSITION.getStorageAddress());
@@ -668,16 +666,16 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     }
 
     /**
-     * @dev Check that Lido allows depositing buffered ether to the consensus layer
-     * Depends on the bunker state and protocol's pause state
+     * @return true if  depositing buffered ether to the consensus layer is allowed
+     * @dev Depends on the bunker state and protocol's pause state
      */
     function canDeposit() public view returns (bool) {
         return !_withdrawalQueue().isBunkerModeActive() && !isStopped();
     }
 
     /**
-     * @dev Returns depositable ether amount.
-     * Takes into account unfinalized stETH required by WithdrawalQueue
+     * @return the amount of ether available to deposit
+     * @dev Takes into account unfinalized stETH on WithdrawalQueue
      */
     function getDepositableEther() public view returns (uint256) {
         uint256 bufferedEther = _getBufferedEther();
@@ -686,7 +684,7 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     }
 
     /**
-     * @dev Invokes a deposit call to the Staking Router contract and updates buffered counters
+     * @notice Deposit buffered ether to StakingRouter's module with id of `_stakingModuleId`
      * @param _maxDepositsCount max deposits count
      * @param _stakingModuleId id of the staking module to be deposited
      * @param _depositCalldata module calldata
@@ -1078,7 +1076,7 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     }
 
     /**
-     * @dev Gets the amount of Ether temporary buffered on this contract balance
+     * @dev Gets the amount of ether temporary buffered on this contract balance
      */
     function _getBufferedEther() internal view returns (uint256) {
         return BUFFERED_ETHER_POSITION.getStorageUint256();
@@ -1100,7 +1098,7 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     }
 
     /**
-     * @dev Gets the total amount of Ether controlled by the system
+     * @dev Gets the total amount of ether controlled by the system
      * @return total balance in wei
      */
     function _getTotalPooledEther() internal view returns (uint256) {

contracts/0.4.24/StETH.sol

@@ -17,7 +17,7 @@ import "./utils/Pausable.sol";
  * the `_getTotalPooledEther` function.
  *
  * StETH balances are dynamic and represent the holder's share in the total amount
- * of Ether controlled by the protocol. Account shares aren't normalized, so the
+ * of ether controlled by the protocol. Account shares aren't normalized, so the
  * contract also stores the sum of all shares to calculate each account's token balance
  * which equals to:
  *
@@ -37,11 +37,11 @@ import "./utils/Pausable.sol";
  * Since balances of all token holders change when the amount of total pooled Ether
  * changes, this token cannot fully implement ERC20 standard: it only emits `Transfer`
  * events upon explicit transfer between holders. In contrast, when total amount of
- * pooled Ether increases, no `Transfer` events are generated: doing so would require
+ * pooled ether increases, no `Transfer` events are generated: doing so would require
  * emitting an event for each token holder and thus running an unbounded loop.
  *
  * The token inherits from `Pausable` and uses `whenNotStopped` modifier for methods
- * which change `shares` or `allowances`. `_stop` and `_resume` functions are overridden
+ * which change `shares`. `_stop` and `_resume` functions are overridden
  * in `Lido.sol` and might be called by an account with the `PAUSE_ROLE` assigned by the
  * DAO. This is useful for emergency scenarios, e.g. a protocol bug, where one might want
  * to freeze all token transfers and approvals until the emergency is resolved.
@@ -55,7 +55,7 @@ contract StETH is IERC20, Pausable {
 
     /**
      * @dev StETH balances are dynamic and are calculated based on the accounts' shares
-     * and the total amount of Ether controlled by the protocol. Account shares aren't
+     * and the total amount of ether controlled by the protocol. Account shares aren't
      * normalized, so the contract also stores the sum of all shares to calculate
      * each account's token balance which equals to:
      *
@@ -142,14 +142,14 @@ contract StETH is IERC20, Pausable {
      * @return the amount of tokens in existence.
      *
      * @dev Always equals to `_getTotalPooledEther()` since token amount
-     * is pegged to the total amount of Ether controlled by the protocol.
+     * is pegged to the total amount of ether controlled by the protocol.
      */
     function totalSupply() external view returns (uint256) {
         return _getTotalPooledEther();
     }
 
     /**
-     * @return the entire amount of Ether controlled by the protocol.
+     * @return the entire amount of ether controlled by the protocol.
      *
      * @dev The sum of all ETH balances in the protocol, equals to the total supply of stETH.
      */
@@ -161,7 +161,7 @@ contract StETH is IERC20, Pausable {
      * @return the amount of tokens owned by the `_account`.
      *
      * @dev Balances are dynamic and equal the `_account`'s share in the amount of the
-     * total Ether controlled by the protocol. See `sharesOf`.
+     * total ether controlled by the protocol. See `sharesOf`.
      */
     function balanceOf(address _account) external view returns (uint256) {
         return getPooledEthByShares(_sharesOf(_account));
@@ -176,7 +176,7 @@ contract StETH is IERC20, Pausable {
      *
      * Requirements:
      *
-     * - `_recipient` cannot be the zero address.
+     * - `_recipient` cannot be the zero address or the stETH contract itself.
      * - the caller must have a balance of at least `_amount`.
      * - the contract must not be paused.
      *
@@ -200,6 +200,9 @@ contract StETH is IERC20, Pausable {
     /**
      * @notice Sets `_amount` as the allowance of `_spender` over the caller's tokens.
      *
+     * @dev allowance can be set to "infinity" (INFINITE_ALLOWANCE).
+     * In this case allowance is not to be spent on transfer, that can save some gas.
+     *
      * @return a boolean value indicating whether the operation succeeded.
      * Emits an `Approval` event.
      *
@@ -217,17 +220,18 @@ contract StETH is IERC20, Pausable {
     /**
      * @notice Moves `_amount` tokens from `_sender` to `_recipient` using the
      * allowance mechanism. `_amount` is then deducted from the caller's
-     * allowance.
+     * allowance if the allowance is not infinite.
      *
      * @return a boolean value indicating whether the operation succeeded.
      *
      * Emits a `Transfer` event.
      * Emits a `TransferShares` event.
-     * Emits an `Approval` event indicating the updated allowance.
+     * Emits an `Approval` event if allowance is updated.
      *
      * Requirements:
      *
-     * - `_sender` and `_recipient` cannot be the zero addresses.
+     * - `_sender` cannot be the zero addresses.
+     * - `_recipient` cannot be the zero addresses or stETH contract itself.
      * - `_sender` must have a balance of at least `_amount`.
      * - the caller must have allowance for `_sender`'s tokens of at least `_amount`.
      * - the contract must not be paused.
@@ -304,7 +308,7 @@ contract StETH is IERC20, Pausable {
     }
 
     /**
-     * @return the amount of Ether that corresponds to `_sharesAmount` token shares.
+     * @return the amount of ether that corresponds to `_sharesAmount` token shares.
      */
     function getPooledEthByShares(uint256 _sharesAmount) public view returns (uint256) {
         return _sharesAmount
@@ -321,7 +325,7 @@ contract StETH is IERC20, Pausable {
      *
      * Requirements:
      *
-     * - `_recipient` cannot be the zero address.
+     * - `_recipient` cannot be the zero address or the stETH contract itself.
      * - the caller must have at least `_sharesAmount` shares.
      * - the contract must not be paused.
      *
@@ -335,15 +339,19 @@ contract StETH is IERC20, Pausable {
     }
 
     /**
-     * @notice Moves `_sharesAmount` token shares from the `_sender` account to the `_recipient` account.
+     * @notice Moves `_sharesAmount` token shares from the `_sender` account to the `_recipient` using
+     * the allowance mechanism. The amount of tokens equivalent to `_sharesAmount` is then deducted
+     * from the caller's allowance if the allowance is not infinite.
      *
      * @return amount of transferred tokens.
      * Emits a `TransferShares` event.
      * Emits a `Transfer` event.
+     * Emits an `Approval` event if allowance is updated.
      *
      * Requirements:
      *
-     * - `_sender` and `_recipient` cannot be the zero addresses.
+     * - `_sender` cannot be the zero address.
+     * - `_recipient` cannot be the zero address or stETH contract itself.
      * - `_sender` must have at least `_sharesAmount` shares.
      * - the caller must have allowance for `_sender`'s tokens of at least `getPooledEthByShares(_sharesAmount)`.
      * - the contract must not be paused.
@@ -361,7 +369,7 @@ contract StETH is IERC20, Pausable {
     }
 
     /**
-     * @return the total amount (in wei) of Ether controlled by the protocol.
+     * @return the total amount (in wei) of ether controlled by the protocol.
      * @dev This is used for calculating tokens from shares and vice versa.
      * @dev This function is required to be implemented in a derived contract.
      */

contracts/0.4.24/StETHPermit.sol

@@ -17,7 +17,7 @@ import {StETH} from "./StETH.sol";
  *
  * Adds the {permit} method, which can be used to change an account's ERC20 allowance (see {IERC20-allowance}) by
  * presenting a message signed by the account. By not relying on {IERC20-approve}, the token holder account doesn't
- * need to send a transaction, and thus is not required to hold Ether at all.
+ * need to send a transaction, and thus is not required to hold ether at all.
  */
 interface IERC2612 {
     /**