chore: improve comments and some bits

contracts/0.4.24/Lido.sol

@@ -130,16 +130,16 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     // Staking limit was removed
     event StakingLimitRemoved();
 
-    // Emits when validators number delivered by the oracle
+    // Emitted when validators number delivered by the oracle
     event CLValidatorsUpdated(uint256 indexed reportTimestamp, uint256 preCLValidators, uint256 postCLValidators);
 
-    // Emits when external shares changed during the report
+    // Emitted when external shares changed during the report
     event ExternalSharesChanged(uint256 indexed reportTimestamp, uint256 preCLValidators, uint256 postCLValidators);
 
-    // Emits when var at `DEPOSITED_VALIDATORS_POSITION` changed
+    // Emitted when var at `DEPOSITED_VALIDATORS_POSITION` changed
     event DepositedValidatorsChanged(uint256 depositedValidators);
 
-    // Emits when oracle accounting report processed
+    // Emitted when oracle accounting report processed
     // @dev principalCLBalance is the balance of the validators on previous report
     // plus the amount of ether that was deposited to the deposit contract
     event ETHDistributed(
@@ -151,7 +151,7 @@ contract Lido is Versioned, StETHPermit, AragonApp {
         uint256 postBufferedEther
     );
 
-    // Emits when token rebased (total supply and/or total shares were changed)
+    // Emitted when token is rebased (total supply and/or total shares were changed)
     event TokenRebased(
         uint256 indexed reportTimestamp,
         uint256 timeElapsed,
@@ -237,8 +237,6 @@ contract Lido is Versioned, StETHPermit, AragonApp {
      *
      * @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.
      */
     function pauseStaking() external {
         _auth(STAKING_PAUSE_ROLE);
@@ -361,7 +359,7 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     }
 
     /**
-     * @return the maximum allowed external shares ratio as basis points of total shares
+     * @return the maximum allowed external shares ratio as basis points of total shares [0-10000]
      */
     function getMaxExternalRatioBP() external view returns (uint256) {
         return MAX_EXTERNAL_RATIO_POSITION.getStorageUint256();
@@ -618,13 +616,13 @@ contract Lido is Versioned, StETHPermit, AragonApp {
 
     /**
      * @notice Mint shares backed by external vaults
-     * @param _receiver Address to receive the minted shares
+     * @param _recipient Address to receive the minted shares
      * @param _amountOfShares Amount of shares to mint
      * @dev Can be called only by accounting (authentication in mintShares method).
      *      NB: Reverts if the the external balance limit is exceeded.
      */
-    function mintExternalShares(address _receiver, uint256 _amountOfShares) external {
-        require(_receiver != address(0), "MINT_RECEIVER_ZERO_ADDRESS");
+    function mintExternalShares(address _recipient, uint256 _amountOfShares) external {
+        require(_recipient != address(0), "MINT_RECEIVER_ZERO_ADDRESS");
         require(_amountOfShares != 0, "MINT_ZERO_AMOUNT_OF_SHARES");
 
         // TODO: separate role and flag for external shares minting pause
@@ -637,9 +635,9 @@ contract Lido is Versioned, StETHPermit, AragonApp {
 
         EXTERNAL_SHARES_POSITION.setStorageUint256(newExternalShares);
 
-        mintShares(_receiver, _amountOfShares);
+        mintShares(_recipient, _amountOfShares);
 
-        emit ExternalSharesMinted(_receiver, _amountOfShares, getPooledEthByShares(_amountOfShares));
+        emit ExternalSharesMinted(_recipient, _amountOfShares, getPooledEthByShares(_amountOfShares));
     }
 
     /**
@@ -816,7 +814,7 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     ////////////////////////////////////////////////////////////////////////////
 
     /**
-     * @notice DEPRECATED:Returns current withdrawal credentials of deposited validators
+     * @notice DEPRECATED: Returns current withdrawal credentials of deposited validators
      * @dev DEPRECATED: use StakingRouter.getWithdrawalCredentials() instead
      */
     function getWithdrawalCredentials() external view returns (bytes32) {
@@ -975,6 +973,7 @@ contract Lido is Versioned, StETHPermit, AragonApp {
     ///
     ///      Special cases:
     ///      - Returns 0 if maxBP is 0 (external minting is disabled) or external shares already exceed the limit
+    ///      - Returns 2^256-1 if maxBP is 100% (external minting is unlimited)
     function _getMaxMintableExternalShares() internal view returns (uint256) {
         uint256 maxRatioBP = MAX_EXTERNAL_RATIO_POSITION.getStorageUint256();
         uint256 externalShares = EXTERNAL_SHARES_POSITION.getStorageUint256();

contracts/0.4.24/lib/Packed64x4.sol

@@ -1,6 +1,8 @@
 // SPDX-FileCopyrightText: 2023 Lido <[email protected]>
 // SPDX-License-Identifier: MIT
 
+// Copied from: https://github.com/OpenZeppelin/openzeppelin-contracts/blob/0457042d93d9dfd760dbaa06a4d2f1216fdbe297/contracts/utils/math/Math.sol
+
 // See contracts/COMPILERS.md
 // solhint-disable-next-line
 pragma solidity ^0.4.24;

contracts/0.8.25/vaults/VaultHub.sol

@@ -54,7 +54,7 @@ abstract contract VaultHub is AccessControlEnumerableUpgradeable {
         uint16 treasuryFeeBP;
         /// @notice if true, vault is disconnected and fee is not accrued
         bool isDisconnected;
-        // ### we have 104 bytes left in this slot
+        // ### we have 104 bits left in this slot
     }
 
     // keccak256(abi.encode(uint256(keccak256("VaultHub")) - 1)) & ~bytes32(uint256(0xff))
@@ -289,10 +289,10 @@ abstract contract VaultHub is AccessControlEnumerableUpgradeable {
 
     /// @notice separate burn function for EOA vault owners; requires vaultHub to be approved to transfer stETH
     /// @dev msg.sender should be vault's owner
-    function transferAndBurnStethBackedByVault(address _vault, uint256 _tokens) external {
-        STETH.transferFrom(msg.sender, address(this), _tokens);
+    function transferAndBurnSharesBackedByVault(address _vault, uint256 _amountOfShares) external {
+        STETH.transferSharesFrom(msg.sender, address(this), _amountOfShares);
 
-        burnSharesBackedByVault(_vault, _tokens);
+        burnSharesBackedByVault(_vault, _amountOfShares);
     }
 
     /// @notice force rebalance of the vault to have sufficient reserve ratio
@@ -443,7 +443,7 @@ abstract contract VaultHub is AccessControlEnumerableUpgradeable {
 
         // TODO: optimize potential rewards calculation
         uint256 potentialRewards = ((chargeableValue * (_postTotalPooledEther * _preTotalShares)) /
-            (_postTotalSharesNoFees * _preTotalPooledEther) -chargeableValue);
+            (_postTotalSharesNoFees * _preTotalPooledEther) - chargeableValue);
         uint256 treasuryFee = (potentialRewards * _socket.treasuryFeeBP) / TOTAL_BASIS_POINTS;
 
         treasuryFeeShares = (treasuryFee * _preTotalShares) / _preTotalPooledEther;