Merge pull request #48 from lidofinance/feature/review

Review

Author: arwer13

script/HarnessCore.s.sol

@@ -168,14 +168,11 @@ contract HarnessCore is Script {
         return (true, abi.decode(ret, (address)));
     }
 
-    function _arr6(
-        string memory a,
-        string memory b,
-        string memory c,
-        string memory d,
-        string memory e,
-        string memory f
-    ) private pure returns (string[] memory r) {
+    function _arr6(string memory a, string memory b, string memory c, string memory d, string memory e, string memory f)
+        private
+        pure
+        returns (string[] memory r)
+    {
         r = new string[](6);
         r[0] = a;
         r[1] = b;

src/Factory.sol

@@ -247,7 +247,7 @@ contract Factory {
                 timelock,
                 abi.encodeCall(
                     WithdrawalQueue.initialize,
-                    (vaultConfig.nodeOperatorManager, vaultConfig.nodeOperator) // (admin, finalizerRoleHolder)
+                    (timelock, vaultConfig.nodeOperator) // (admin, finalizerRoleHolder)
                 )
             )
         );
@@ -318,10 +318,10 @@ contract Factory {
         }
 
         pool.grantRole(DEFAULT_ADMIN_ROLE, timelock);
-        pool.renounceRole(DEFAULT_ADMIN_ROLE, tempAdmin);
+        pool.revokeRole(DEFAULT_ADMIN_ROLE, tempAdmin);
 
         dashboard.grantRole(DEFAULT_ADMIN_ROLE, timelock);
-        dashboard.renounceRole(DEFAULT_ADMIN_ROLE, tempAdmin);
+        dashboard.revokeRole(DEFAULT_ADMIN_ROLE, tempAdmin);
 
         deployment = StvPoolDeployment({
             poolType: poolType,

src/StvPool.sol

@@ -8,6 +8,7 @@ import {IDashboard} from "./interfaces/IDashboard.sol";
 import {IStETH} from "./interfaces/IStETH.sol";
 import {IStakingVault} from "./interfaces/IStakingVault.sol";
 import {IVaultHub} from "./interfaces/IVaultHub.sol";
+import {FeaturePausable} from "./utils/FeaturePausable.sol";
 import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
 import {ERC20Upgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
 import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
@@ -17,23 +18,23 @@ import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
  * @notice ERC20 staking vault token pool that accepts ETH deposits and manages withdrawals through a queue
  * @dev Implements a tokenized staking pool where users deposit ETH and receive STV tokens representing their share
  */
-contract StvPool is Initializable, ERC20Upgradeable, AllowList {
+contract StvPool is Initializable, ERC20Upgradeable, AllowList, FeaturePausable {
     // Custom errors
     error ZeroDeposit();
-    error InvalidReceiver();
+    error InvalidRecipient();
     error NotWithdrawalQueue();
     error NotEnoughToRebalance();
     error UnassignedLiabilityOnVault();
     error VaultInBadDebt();
 
-    bytes32 public constant REQUEST_VALIDATOR_EXIT_ROLE = keccak256("REQUEST_VALIDATOR_EXIT_ROLE");
-    bytes32 public constant TRIGGER_VALIDATOR_WITHDRAWAL_ROLE = keccak256("TRIGGER_VALIDATOR_WITHDRAWAL_ROLE");
+    bytes32 public constant DEPOSITS_FEATURE = keccak256("DEPOSITS_FEATURE");
+    bytes32 public constant DEPOSITS_PAUSE_ROLE = keccak256("DEPOSITS_PAUSE_ROLE");
+    bytes32 public constant DEPOSITS_RESUME_ROLE = keccak256("DEPOSITS_RESUME_ROLE");
 
     uint256 public constant TOTAL_BASIS_POINTS = 100_00;
 
     uint256 private constant DECIMALS = 27;
     uint256 private constant ASSET_DECIMALS = 18;
-    uint256 private constant EXTRA_DECIMALS_BASE = 10 ** (DECIMALS - ASSET_DECIMALS);
 
     IStETH public immutable STETH;
     IDashboard public immutable DASHBOARD;
@@ -44,7 +45,7 @@ contract StvPool is Initializable, ERC20Upgradeable, AllowList {
     Distributor public immutable DISTRIBUTOR;
 
     event Deposit(
-        address indexed sender, address indexed receiver, address indexed referral, uint256 assets, uint256 stv
+        address indexed sender, address indexed recipient, address indexed referral, uint256 assets, uint256 stv
     );
 
     event UnassignedLiabilityRebalanced(uint256 stethShares, uint256 ethFunded);
@@ -61,6 +62,9 @@ contract StvPool is Initializable, ERC20Upgradeable, AllowList {
 
         // Disable initializers since we only support proxy deployment
         _disableInitializers();
+
+        // Pause features in implementation
+        _pauseFeature(DEPOSITS_FEATURE);
     }
 
     function poolType() external view virtual returns (bytes32) {
@@ -83,8 +87,10 @@ contract StvPool is Initializable, ERC20Upgradeable, AllowList {
         uint256 initialVaultBalance = address(STAKING_VAULT).balance;
         uint256 connectDeposit = VAULT_HUB.CONNECT_DEPOSIT();
         assert(initialVaultBalance >= connectDeposit);
+        assert(totalSupply() == 0);
 
-        _mint(address(this), _convertToStv(initialVaultBalance, Math.Rounding.Floor));
+        uint256 stvToMint = initialVaultBalance * 10 ** (DECIMALS - ASSET_DECIMALS);
+        _mint(address(this), stvToMint);
     }
 
     // =================================================================================
@@ -132,27 +138,22 @@ contract StvPool is Initializable, ERC20Upgradeable, AllowList {
     // CONVERSION
     // =================================================================================
 
-    function _convertToStv(uint256 _assetsE18, Math.Rounding _rounding) internal view returns (uint256 stv) {
-        uint256 totalAssetsE18 = totalAssets();
-        uint256 totalSupplyE27 = totalSupply();
-
-        if (totalSupplyE27 == 0) return _assetsE18 * EXTRA_DECIMALS_BASE; // 1:1 for the first deposit
-        if (totalAssetsE18 == 0) return 0;
+    function _convertToStv(uint256 _assets, Math.Rounding _rounding) internal view returns (uint256 stv) {
+        uint256 totalAssets_ = totalAssets();
+        if (totalAssets_ == 0) return 0;
 
-        stv = Math.mulDiv(_assetsE18, totalSupplyE27, totalAssetsE18, _rounding);
+        stv = Math.mulDiv(_assets, totalSupply(), totalAssets_, _rounding);
     }
 
     function _convertToAssets(uint256 _stv) internal view returns (uint256 assets) {
         assets = _getAssetsShare(_stv, totalAssets());
     }
 
-    function _getAssetsShare(uint256 _stv, uint256 _assetsE18) internal view returns (uint256 assets) {
-        uint256 supplyE27 = totalSupply();
-        if (supplyE27 == 0) return 0;
+    function _getAssetsShare(uint256 _stv, uint256 _assets) internal view returns (uint256 assets) {
+        uint256 totalSupply_ = totalSupply();
+        if (totalSupply_ == 0) return 0;
 
-        // TODO: review this Math.Rounding.Ceil
-        uint256 assetsShare = Math.mulDiv(_stv * EXTRA_DECIMALS_BASE, _assetsE18, supplyE27, Math.Rounding.Ceil);
-        assets = assetsShare / EXTRA_DECIMALS_BASE;
+        assets = Math.mulDiv(_stv, _assets, totalSupply_, Math.Rounding.Floor);
     }
 
     // =================================================================================
@@ -207,7 +208,8 @@ contract StvPool is Initializable, ERC20Upgradeable, AllowList {
 
     function _deposit(address _recipient, address _referral) internal returns (uint256 stv) {
         if (msg.value == 0) revert ZeroDeposit();
-        if (_recipient == address(0)) revert InvalidReceiver();
+        if (_recipient == address(0)) revert InvalidRecipient();
+        _checkFeatureNotPaused(DEPOSITS_FEATURE);
         _checkAllowList();
 
         stv = previewDeposit(msg.value);
@@ -375,4 +377,26 @@ contract StvPool is Initializable, ERC20Upgradeable, AllowList {
     function _checkOnlyWithdrawalQueue() internal view {
         if (address(WITHDRAWAL_QUEUE) != msg.sender) revert NotWithdrawalQueue();
     }
+
+    // =================================================================================
+    // PAUSE / RESUME DEPOSITS
+    // =================================================================================
+
+    /**
+     * @notice Pause deposits
+     * @dev Can only be called by accounts with the DEPOSITS_PAUSE_ROLE
+     */
+    function pauseDeposits() external {
+        _checkRole(DEPOSITS_PAUSE_ROLE, msg.sender);
+        _pauseFeature(DEPOSITS_FEATURE);
+    }
+
+    /**
+     * @notice Resume deposits
+     * @dev Can only be called by accounts with the DEPOSITS_RESUME_ROLE
+     */
+    function resumeDeposits() external {
+        _checkRole(DEPOSITS_RESUME_ROLE, msg.sender);
+        _resumeFeature(DEPOSITS_FEATURE);
+    }
 }

src/StvStETHPool.sol

@@ -17,8 +17,9 @@ contract StvStETHPool is StvPool {
     event StethSharesMinted(address indexed account, uint256 stethShares);
     event StethSharesBurned(address indexed account, uint256 stethShares);
     event StethSharesRebalanced(address indexed account, uint256 stethShares, uint256 stvBurned);
-    event SocializedLoss(uint256 stv, uint256 assets);
+    event SocializedLoss(uint256 stv, uint256 assets, uint256 maxLossSocializationBP);
     event VaultParametersUpdated(uint256 newReserveRatioBP, uint256 newForcedRebalanceThresholdBP);
+    event MaxLossSocializationUpdated(uint256 newMaxLossSocializationBP);
 
     error InsufficientMintingCapacity();
     error InsufficientStethShares();
@@ -31,6 +32,13 @@ contract StvStETHPool is StvPool {
     error VaultReportStale();
     error UndercollateralizedAccount();
     error CollateralizedAccount();
+    error ExcessiveLossSocialization();
+    error SameValue();
+    error InvalidValue();
+
+    bytes32 public constant MINTING_FEATURE = keccak256("MINTING_FEATURE");
+    bytes32 public constant MINTING_PAUSE_ROLE = keccak256("MINTING_PAUSE_ROLE");
+    bytes32 public constant MINTING_RESUME_ROLE = keccak256("MINTING_RESUME_ROLE");
 
     bytes32 public constant LOSS_SOCIALIZER_ROLE = keccak256("LOSS_SOCIALIZER_ROLE");
 
@@ -47,6 +55,7 @@ contract StvStETHPool is StvPool {
         uint256 totalMintedStethShares;
         uint16 reserveRatioBP;
         uint16 forcedRebalanceThresholdBP;
+        uint16 maxLossSocializationBP;
     }
 
     // keccak256(abi.encode(uint256(keccak256("pool.storage.StvStETHPool")) - 1)) & ~bytes32(uint256(0xff))
@@ -67,10 +76,14 @@ contract StvStETHPool is StvPool {
         address _distributor,
         bytes32 _poolType
     ) StvPool(_dashboard, _allowListEnabled, _withdrawalQueue, _distributor) {
+        if (_reserveRatioGapBP >= TOTAL_BASIS_POINTS) revert InvalidValue();
+
         RESERVE_RATIO_GAP_BP = _reserveRatioGapBP;
+        POOL_TYPE = _poolType;
         WSTETH = IWstETH(DASHBOARD.WSTETH());
 
-        POOL_TYPE = _poolType;
+        // Pause features in implementation
+        _pauseFeature(MINTING_FEATURE);
     }
 
     function poolType() external view override returns (bytes32) {
@@ -301,7 +314,9 @@ contract StvStETHPool is StvPool {
      * on WSTETH contract during unwrapping. The dust from rounding accumulates on the WSTETH contract during unwrapping
      */
     function mintWsteth(uint256 _wsteth) public {
+        _checkFeatureNotPaused(MINTING_FEATURE);
         _checkRemainingMintingCapacityOf(msg.sender, _wsteth);
+
         _increaseMintedStethShares(msg.sender, _wsteth);
         DASHBOARD.mintWstETH(msg.sender, _wsteth);
     }
@@ -311,7 +326,9 @@ contract StvStETHPool is StvPool {
      * @param _stethShares The amount of stETH shares to mint
      */
     function mintStethShares(uint256 _stethShares) public {
+        _checkFeatureNotPaused(MINTING_FEATURE);
         _checkRemainingMintingCapacityOf(msg.sender, _stethShares);
+
         _increaseMintedStethShares(msg.sender, _stethShares);
         DASHBOARD.mintShares(msg.sender, _stethShares);
     }
@@ -453,7 +470,6 @@ contract StvStETHPool is StvPool {
      * @notice Sync reserve ratio and forced rebalance threshold from VaultHub
      * @dev Permissionless method to keep reserve ratio and forced rebalance threshold in sync with VaultHub
      * @dev Adds a gap defined by RESERVE_RATIO_GAP_BP to VaultHub's values
-     * @dev Reverts if the new reserve ratio or forced rebalance threshold is invalid (>= TOTAL_BASIS_POINTS)
      */
     function syncVaultParameters() public {
         IVaultHub.VaultConnection memory connection = DASHBOARD.vaultConnection();
@@ -656,9 +672,14 @@ contract StvStETHPool is StvPool {
 
         if (remainingStethShares > 0) DASHBOARD.rebalanceVaultWithShares(remainingStethShares);
 
-        // TODO: Add sanity check for loss socialization
         if (stvToBurn > _maxStvToBurn) {
-            emit SocializedLoss(stvToBurn - _maxStvToBurn, ethToRebalance - _convertToAssets(_maxStvToBurn));
+            _checkAllowedLossSocializationPortion(stvToBurn, _maxStvToBurn);
+
+            emit SocializedLoss(
+                stvToBurn - _maxStvToBurn,
+                ethToRebalance - _convertToAssets(_maxStvToBurn),
+                _getStvStETHPoolStorage().maxLossSocializationBP
+            );
             stvToBurn = _maxStvToBurn;
         }
 
@@ -681,10 +702,60 @@ contract StvStETHPool is StvPool {
         isBreached = _assets < assetsThreshold;
     }
 
+    function _checkAllowedLossSocializationPortion(uint256 stvRequired, uint256 stvAvailable) internal view {
+        // It's guaranteed that stvRequired > stvAvailable here
+        uint256 portionToSocializeBP =
+            Math.mulDiv(stvRequired - stvAvailable, TOTAL_BASIS_POINTS, stvRequired, Math.Rounding.Ceil);
+
+        if (portionToSocializeBP > _getStvStETHPoolStorage().maxLossSocializationBP) {
+            revert ExcessiveLossSocialization();
+        }
+    }
+
     function _checkFreshReport() internal view {
         if (!VAULT_HUB.isReportFresh(address(STAKING_VAULT))) revert VaultReportStale();
     }
 
+    // =================================================================================
+    // LOSS SOCIALIZATION LIMITER
+    // =================================================================================
+
+    // During rebalancing, it's possible that the stv available for burning is not sufficient to cover the entire liability.
+    // This may be due to a sharp drop in the stv price, which has resulted in an individual account or a request in Withdrawal Queue
+    // no longer being collateralized (assets < liability).
+    //
+    // The limiter on loss socialization is introduced to prevent excessive losses from being socialized to all pool participants.
+    // The limiter is defined as a maximum portion of the loss that can be socialized, expressed in basis points (BP).
+    //
+    // The default value is set to 0 BP, meaning that no loss socialization is allowed without explicit permission.
+
+    /**
+     * @notice Maximum allowed loss socialization in basis points
+     * @return maxSocializablePortionBP The maximum allowed portion of loss to be socialized in basis points
+     * @dev Used to limit the portion of loss that can be socialized to all pool participants during rebalance
+     */
+    function maxLossSocializationBP() external view returns (uint256 maxSocializablePortionBP) {
+        maxSocializablePortionBP = uint256(_getStvStETHPoolStorage().maxLossSocializationBP);
+    }
+
+    /**
+     * @notice Set the maximum allowed loss socialization in basis points
+     * @param _maxSocializablePortionBP The new maximum allowed loss socialization in basis points
+     * @dev Sets the maximum portion of loss that can be socialized to all pool participants during rebalance
+     * @dev Can only be called by accounts with the DEFAULT_ADMIN_ROLE
+     */
+    function setMaxLossSocializationBP(uint16 _maxSocializablePortionBP) external {
+        _checkRole(DEFAULT_ADMIN_ROLE, msg.sender);
+
+        if (_maxSocializablePortionBP > TOTAL_BASIS_POINTS) revert InvalidValue();
+
+        StvStETHPoolStorage storage $ = _getStvStETHPoolStorage();
+        if (_maxSocializablePortionBP == $.maxLossSocializationBP) revert SameValue();
+        $.maxLossSocializationBP = _maxSocializablePortionBP;
+
+        emit MaxLossSocializationUpdated(_maxSocializablePortionBP);
+    }
+
     // =================================================================================
     // TRANSFER WITH LIABILITY
     // =================================================================================
@@ -727,4 +798,26 @@ contract StvStETHPool is StvPool {
 
         if (balanceOf(_from) < stvToLock) revert InsufficientReservedBalance();
     }
+
+    // =================================================================================
+    // PAUSE / RESUME MINTING
+    // =================================================================================
+
+    /**
+     * @notice Pause (w)stETH minting
+     * @dev Can only be called by accounts with the MINTING_PAUSE_ROLE
+     */
+    function pauseMinting() external {
+        _checkRole(MINTING_PAUSE_ROLE, msg.sender);
+        _pauseFeature(MINTING_FEATURE);
+    }
+
+    /**
+     * @notice Resume (w)stETH minting
+     * @dev Can only be called by accounts with the MINTING_RESUME_ROLE
+     */
+    function resumeMinting() external {
+        _checkRole(MINTING_RESUME_ROLE, msg.sender);
+        _resumeFeature(MINTING_FEATURE);
+    }
 }