feat: update Burner docs after V2 upgrade

Author: arwer13

docs/contracts/burner.md

@@ -11,17 +11,17 @@ user balance using the following equation:
 `balanceOf(account) = shares[account] * totalPooledEther / totalShares`.
 Therefore, burning shares (e.g. decreasing the `totalShares` amount) increases stETH holders' balances.
 
-It's presumed that actual shares burning happens inside the `Lido` contract as a part of the `AccountingOracleReport`.
+It's presumed that actual shares burning happens inside the `Lido` contract as a part of the `AccountingOracle` report.
 `Burner` provides a safe and deterministic way to incur a positive stETH token rebase by gradually
 decreasing `totalShares` that can be correctly handled by 3rd party protocols integrated with stETH.
 
-`Burner` accepts burning requests by the following two ways:
+`Burner` accepts burning requests in the following two ways:
 
-- Locking pre-approved stETH tokens by the caller with an assigned role.
+- Locking pre-approved stETH tokens by the caller with an assigned role;
 - Locking caller-provided stETH tokens.
 
 Those burn requests are initially set by the contract to a pending state.
-Actual burning happens as part of an oracle (`AccountinOracle`) report handling by `Lido` to prevent
+Actual burning happens as part of an oracle (`AccountingOracle`) report handling by `Lido` to prevent
 additional fluctuations of the existing stETH token rebase period (~24h).
 
 We also distinguish two types of shares burn requests:
@@ -30,13 +30,13 @@ between the two consecutive oracle reports);
 * request to burn shares for any other cases (**non-cover**).
 
 The contract has two separate counters for the burnt shares: cover and non-cover ones. The contract is
-exclusive responsible for the stETH shares burning via by `Lido` and burning allowed only from the contract's
+exclusively responsible for the stETH shares burning by `Lido` and burning allowed only from the contract's
 own balance only.
 
 ## Shares burnt counters
 
 The contract keeps count of all shares ever burned by way of maintaining two internal counters:
-`totalCoverSharesBurnt` and `totalNonCoverSharesBurnt` for cover and non-cover burns respectively.
+`totalCoverSharesBurnt` and `totalNonCoverSharesBurnt` for cover and non-cover burns, respectively.
 These counters are increased when actual stETH burn is performed as part of the Lido Oracle report.
 
 This makes it possible to split any stETH rebase into two sub-components: the rewards-induced rebase
@@ -78,12 +78,20 @@ Returns the total non-cover shares ever burnt.
 function getNonCoverSharesBurnt() external view returns (uint256)
 ```
 
-### function getExcessStETH
+### Function: getExcessStETH
 
 Returns the stETH amount belonging to the burner contract address but not marked for burning.
 
 ```sol
-function getExcessStETH() external view return (uint256)
+function getExcessStETH() external view returns (uint256)
+```
+
+### Function: getSharesRequestedToBurn
+
+Returns numbers of cover and non-cover shares requested to burn.
+
+```sol
+function getSharesRequestedToBurn() external view returns (uint256 coverShares, uint256 nonCoverShares)
 ```
 
 ## Methods
@@ -95,47 +103,104 @@ Internally converts tokens amount into underlying shares amount and marks the co
 for cover-backed burning by increasing the internal `coverSharesBurnRequested` counter.
 
 ```sol
-function requestBurnMyStETHForCover(uint256 _stETH2Burn) external
+function requestBurnMyStETHForCover(uint256 _stETHAmountToBurn) external
 ```
 
 :::note
 Reverts if any of the following is true:
-* `msg.sender` is not equal to the set upon construction `voting` address;
-* no stETH provided (`_stETH2Burn == 0`);
+* `msg.sender` is not a holder of `REQUEST_BURN_MY_STETH_ROLE` role;
+* no stETH provided (`_stETHAmountToBurn == 0`);
 * no stETH transferred (allowance exceeded).
 :::
 
 #### Parameters:
 
-| Name          | Type      | Description                                     |
-| ------------- | --------- | ----------------------------------------------- |
-| `_stETH2Burn` | `uint256` | stETH tokens amount (not shares amount) to burn |
+| Name                 | Type      | Description                                     |
+| -------------------- | --------- | ----------------------------------------------- |
+| `_stETHAmountToBurn` | `uint256` | stETH tokens amount (not shares amount) to burn |
+
+### Function: requestBurnSharesForCover
+
+Transfers stETH shares from `_from` and irreversibly locks these on the burner contract address.
+Internally marks the shares amount for cover-backed burning by increasing the internal `coverSharesBurnRequested` counter.
+
+Can be called only by a holder of `REQUEST_BURN_SHARES_ROLE`. After Lido V2 upgrade not actually called by any contract and supposed to be called by Lido DAO Agent in case of a need for cover.
+
+```sol
+function requestBurnSharesForCover(address _from, uint256 _sharesAmountToBurn)
+```
+
+:::note
+Reverts if any of the following is true:
+* `msg.sender` is not a holder of `REQUEST_BURN_SHARES_ROLE` role;
+* no stETH shares provided (`_sharesAmountToBurn == 0`);
+* no stETH shares transferred (allowance exceeded).
+:::
+
+#### Parameters:
+
+| Name                  | Type      | Description                                     |
+| --------------------- | --------- | ----------------------------------------------- |
+|        `_from`        | `address` |         address to transfer shares from         |
+| `_sharesAmountToBurn` | `uint256` | shares amount (not stETH tokens amount) to burn |
 
 ### Function: requestBurnMyStETH
 
 Transfers stETH tokens from the message sender and irreversibly locks these on the burner contract address.
 Internally converts tokens amount into underlying shares amount and marks the converted amount for
-non-cover-backed burning by increasing the internal `nonCoverSharesBurnRequested` counter.
+non-cover backed burning by increasing the internal `nonCoverSharesBurnRequested` counter.
+
+```sol
+function requestBurnMyStETH(uint256 _stETHAmountToBurn) external
+```
 
 :::note
 Reverts if any of the following is true:
-* `msg.sender` is not equal to the set upon construction `voting` address;
-* no stETH provided (`_stETH2Burn == 0`);
+* `msg.sender` is not a holder of `REQUEST_BURN_MY_STETH_ROLE` role;
+* no stETH provided (`_stETHAmountToBurn == 0`);
 * no stETH transferred (allowance exceeded).
 :::
 
 #### Parameters:
 
-| Name          | Type      | Description                                     |
-| ------------- | --------- | ----------------------------------------------- |
-| `_stETH2Burn` | `uint256` | stETH tokens amount (not shares amount) to burn |
+| Name                 | Type      | Description                                     |
+| -------------------- | --------- | ----------------------------------------------- |
+| `_stETHAmountToBurn` | `uint256` | stETH tokens amount (not shares amount) to burn |
 
-### function recoverExcessStETH
+### Function: requestBurnShares
+
+Transfers stETH shares from `_from` and irreversibly locks these on the burner contract address.
+Internally marks the shares amount for non-cover backed burning by increasing the internal `nonCoverSharesBurnRequested` counter.
+
+Can be called only by a holder of `REQUEST_BURN_SHARES_ROLE` role which after
+Lido V2 upgrade is either `Lido` or `NodeOperatorsRegistry` contract.
+`Lido` needs this to request shares locked on the `WithdrawalQueue` and
+`NodeOperatorsRegistry` needs it to request burning shares to penalize the rewards of misbehaving node operators.
+
+```sol
+function requestBurnShares(address _from, uint256 _sharesAmountToBurn)
+```
+
+:::note
+Reverts if any of the following is true:
+* `msg.sender` is not a holder of `REQUEST_BURN_SHARES_ROLE` role;
+* no stETH shares provided (`_sharesAmountToBurn == 0`);
+* no stETH shares transferred (allowance exceeded).
+:::
+
+#### Parameters:
+
+| Name                  | Type      | Description                                     |
+| --------------------- | --------- | ----------------------------------------------- |
+|        `_from`        | `address` |         address to transfer shares from         |
+| `_sharesAmountToBurn` | `uint256` | shares amount (not stETH tokens amount) to burn |
+
+### Function: recoverExcessStETH
 
 Transfers the excess stETH amount (e.g. belonging to the burner contract address but not marked for burning)
 to the Lido treasury address (the `DAO Agent` contract) set upon the contract construction.
 
-Does nothing if the `getExcessStETH` view func returns 0 (zero), e.g. there is no excess stETH
+Does nothing if the `getExcessStETH` view func returns 0 (zero), i.e. there is no excess stETH
 on the contract's balance.
 
 ```sol
@@ -154,7 +219,7 @@ function recoverERC20(address _token, uint256 _amount) external
 Reverts if any of the following is true:
 * `_amount` value is 0 (zero);
 * `_token` address is 0 (zero);
-* `_token` address is equal to the `stETH` address (use `recoverExcessStETH` instead).
+* `_token` address equals to the `stETH` address (use `recoverExcessStETH` instead).
 :::
 
 #### Parameters:
@@ -166,18 +231,48 @@ Reverts if any of the following is true:
 
 ### Function: recoverERC721
 
-Transfers a given ERC721-compatible NFT (defined by the contract address) belonging to the burner contract address
-to the Lido treasury (the `DAO Agent`) address.
+Transfers a given ERC721-compatible NFT (defined by the contract address) belonging
+to the burner contract address to the Lido treasury (the `DAO Agent`) address.
 
 ```sol
 function recoverERC721(address _token, uint256 _tokenId) external
 ```
 
 :::note
-Reverts if `_token` address is 0 (zero).
+Reverts if any of the following is true:
+* `_token` address is 0 (zero);
+* `_token` address equals to the `stETH` address (use `recoverExcessStETH` instead).
 :::
 
+#### Parameters:
+
 | Name       | Type      | Description                                 |
 | ---------- | --------- | ------------------------------------------- |
 | `_token`   | `address` | ERC721-compatible token address to recover  |
 | `_tokenId` | `uint256` | Token id to recover                         |
+
+
+### Function: commitSharesToBurn
+
+Marks previously requested to burn cover and non-cover share as burnt.
+Emits `StETHBurnt` event for the cover and non-cover shares marked as burnt.
+
+This function is called by the `Lido` contract right before performing the actual shares burning.
+
+If `_sharesToBurn` is 0 does nothing.
+
+```sol
+function commitSharesToBurn(uint256 _sharesToBurn) external
+```
+
+:::note
+Reverts if any of the following is true:
+* `msg.sender` address is NOT equal to the `stETH` address;
+* `_sharesToBurn` is greater than the cover plus non-cover shares requested to burn.
+:::
+
+#### Parameters:
+
+| Name            | Type      | Description                                            |
+| --------------- | --------- | ------------------------------------------------------ |
+| `_sharesToBurn` | `uint256` | Amount of cover plus non-cover shares to mark as burnt |