diff --git a/contracts/0.8.9/WithdrawalQueue.sol b/contracts/0.8.9/WithdrawalQueue.sol index 733c4a830..a1474d0eb 100644 --- a/contracts/0.8.9/WithdrawalQueue.sol +++ b/contracts/0.8.9/WithdrawalQueue.sol @@ -92,7 +92,9 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit } /// @notice Resume withdrawal requests placement and finalization - /// Contract is deployed in paused state and should be resumed explicitly + /// @dev The contract is deployed in paused state and should be resumed explicitly + /// @dev Reverts if sender has no `RESUME_ROLE` + /// @dev Reverts if contract is already resumed function resume() external { _checkRole(RESUME_ROLE, msg.sender); _resume(); @@ -101,7 +103,7 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit /// @notice Pause withdrawal requests placement and finalization. Claiming finalized requests will still be available /// @param _duration pause duration in seconds (use `PAUSE_INFINITELY` for unlimited) /// @dev Reverts if contract is already paused - /// @dev Reverts reason if sender has no `PAUSE_ROLE` + /// @dev Reverts if sender has no `PAUSE_ROLE` /// @dev Reverts if zero duration is passed function pauseFor(uint256 _duration) external onlyRole(PAUSE_ROLE) { _pauseFor(_duration); @@ -192,7 +194,7 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit return requestWithdrawalsWstETH(_amounts, _owner); } - /// @notice Returns all withdrawal requests that belongs to the `_owner` address + /// @notice Returns all withdrawal requests that belong to the `_owner` address /// /// WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed /// to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that @@ -202,7 +204,7 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit return _getRequestsByOwner()[_owner].values(); } - /// @notice Returns status for requests with provided ids + /// @notice Returns status of requests with provided ids /// @param _requestIds array of withdrawal request ids function getWithdrawalStatus(uint256[] calldata _requestIds) external @@ -215,7 +217,7 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit } } - /// @notice Returns amount of ether available for claim for each provided request id + /// @notice Returns the amount of ether available for claiming for each provided request id /// @param _requestIds array of request ids /// @param _hints checkpoint hints. can be found with `findCheckpointHints(_requestIds, 1, getLastCheckpointIndex())` /// @return claimableEthValues amount of claimable ether for each request, amount is equal to 0 if request @@ -311,10 +313,10 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit } /// @notice Update bunker mode state and last report timestamp on oracle report - /// @dev should be called by oracle + /// @dev Reverts if sender has no `RESUME_ROLE` /// - /// @param _isBunkerModeNow is bunker mode reported by oracle - /// @param _bunkerStartTimestamp timestamp of start of the bunker mode + /// @param _isBunkerModeNow is bunker mode reported by the oracle + /// @param _bunkerStartTimestamp timestamp of the bunker mode activation /// @param _currentReportTimestamp timestamp of the current report ref slot function onOracleReport(bool _isBunkerModeNow, uint256 _bunkerStartTimestamp, uint256 _currentReportTimestamp) external @@ -342,12 +344,12 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit } } - /// @notice Check if bunker mode is active + /// @notice Returns `true` if bunker mode is active function isBunkerModeActive() public view returns (bool) { return bunkerModeSinceTimestamp() < BUNKER_MODE_DISABLED_TIMESTAMP; } - /// @notice Get bunker mode activation timestamp + /// @notice Returns bunker mode activation timestamp /// @dev returns `BUNKER_MODE_DISABLED_TIMESTAMP` if bunker mode is disable (i.e., protocol in turbo mode) function bunkerModeSinceTimestamp() public view returns (uint256) { return BUNKER_MODE_SINCE_TIMESTAMP_POSITION.getStorageUint256(); diff --git a/contracts/0.8.9/WithdrawalQueueBase.sol b/contracts/0.8.9/WithdrawalQueueBase.sol index bd443abc4..3ec3222b3 100644 --- a/contracts/0.8.9/WithdrawalQueueBase.sol +++ b/contracts/0.8.9/WithdrawalQueueBase.sol @@ -111,30 +111,30 @@ abstract contract WithdrawalQueueBase { error InvalidHint(uint256 _hint); error CantSendValueRecipientMayHaveReverted(); - /// @notice id of the last request - /// NB! requests are indexed from 1, so it returns 0 if there is no requests in the queue + /// @notice Returns the id of the last request in the queue + /// NB! requests are indexed from 1, so it returns 0 if there are no requests in the queue function getLastRequestId() public view returns (uint256) { return LAST_REQUEST_ID_POSITION.getStorageUint256(); } - /// @notice id of the last finalized request - /// NB! requests are indexed from 1, so it returns 0 if there is no finalized requests in the queue + /// @notice Returns the id of the last finalized request in the queue + /// NB! requests are indexed from 1, so it returns 0 if there are no finalized requests in the queue function getLastFinalizedRequestId() public view returns (uint256) { return LAST_FINALIZED_REQUEST_ID_POSITION.getStorageUint256(); } - /// @notice amount of ETH on this contract balance that is locked for withdrawal and available to claim + /// @notice Returns the amount of ether on the balance locked for withdrawal and available to claim function getLockedEtherAmount() public view returns (uint256) { return LOCKED_ETHER_AMOUNT_POSITION.getStorageUint256(); } - /// @notice length of the checkpoint array. Last possible value for the hint. - /// NB! checkpoints are indexed from 1, so it returns 0 if there is no checkpoints + /// @notice Returns the length of the checkpoint array. Last possible value for the hint. + /// NB! checkpoints are indexed from 1, so it returns 0 if there are no checkpoints yet function getLastCheckpointIndex() public view returns (uint256) { return LAST_CHECKPOINT_INDEX_POSITION.getStorageUint256(); } - /// @notice return the number of unfinalized requests in the queue + /// @notice Returns the number of unfinalized requests in the queue function unfinalizedRequestNumber() external view returns (uint256) { return getLastRequestId() - getLastFinalizedRequestId(); } @@ -183,15 +183,15 @@ abstract contract WithdrawalQueueBase { uint256 remainingEthBudget; /// @notice flag that is set to `true` if returned state is final and `false` if more calls are required bool finished; - /// @notice static array to store last request id in each batch + /// @notice the resulting array of batches, represented by the id of the last request in the batch uint256[MAX_BATCHES_LENGTH] batches; /// @notice length of the filled part of `batches` array uint256 batchesLength; } /// @notice Offchain view for the oracle daemon that calculates how many requests can be finalized within - /// the given budget, time period and share rate limits. Returned requests are split into batches. - /// Each batch consist of the requests that all have the share rate below the `_maxShareRate` or above it. + /// the given budget, time period, and share rate limits. Returned requests are split into batches. + /// All requests belonging to one batch must have their share rate above or below (or equal) to the `_maxShareRate`. /// Below you can see an example how 14 requests with different share rates will be split into 5 batches by /// this method /// @@ -285,11 +285,11 @@ abstract contract WithdrawalQueueBase { return _state; } - /// @notice Checks finalization batches, calculates required ether and the amount of shares to burn + /// @notice Checks finalization batches, calculates required amount of ether to lock and the number of shares to burn /// @param _batches finalization batches calculated offchain using `calculateFinalizationBatches()` - /// @param _maxShareRate max share rate that will be used for request finalization (1e27 precision) - /// @return ethToLock amount of ether that should be sent with `finalize()` method - /// @return sharesToBurn amount of shares that belongs to requests that will be finalized + /// @param _maxShareRate the max share rate (ETH per share) for the request finalization (1e27 precision) + /// @return ethToLock the amount of ether to be sent with `finalize()` method + /// @return sharesToBurn the number of shares to be burnt to match this finalization call function prefinalize(uint256[] calldata _batches, uint256 _maxShareRate) external view diff --git a/contracts/0.8.9/WithdrawalQueueERC721.sol b/contracts/0.8.9/WithdrawalQueueERC721.sol index ecaeef17d..ebe41c1e1 100644 --- a/contracts/0.8.9/WithdrawalQueueERC721.sol +++ b/contracts/0.8.9/WithdrawalQueueERC721.sol @@ -124,7 +124,7 @@ contract WithdrawalQueueERC721 is IERC721Metadata, IERC4906, WithdrawalQueue { } /// @notice Sets the Base URI for computing {tokenURI}. It does not expect the ending slash in provided string. - /// @dev If NFTDescriptor address isn't set the `baseURI` would be used for generating erc721 tokenURI. In case + /// @dev If NFTDescriptor address isn't set the `baseURI` would be used for generating the ERC-721 token URI. In case /// NFTDescriptor address is set it would be used as a first-priority method. function setBaseURI(string calldata _baseURI) external onlyRole(MANAGE_TOKEN_URI_ROLE) { _getBaseURI().value = _baseURI; @@ -144,8 +144,10 @@ contract WithdrawalQueueERC721 is IERC721Metadata, IERC4906, WithdrawalQueue { emit NftDescriptorAddressSet(_nftDescriptorAddress); } - /// @notice Finalize requests from last finalized one up to `_lastRequestIdToBeFinalized` + /// @notice Finalize requests from the last finalized one up to `_lastRequestIdToBeFinalized` /// @dev ether to finalize all the requests should be calculated using `prefinalize()` and sent along + /// @param _lastRequestIdToBeFinalized the last request id to finalize + /// @param _maxShareRate the max share rate (ETH per share) for the request finalization (1e27 precision) function finalize(uint256 _lastRequestIdToBeFinalized, uint256 _maxShareRate) external payable { _checkResumed(); _checkRole(FINALIZE_ROLE, msg.sender);