Merge pull request #841 from morpho-org/docs/burn-shares

docs: burn shares

Author: MathisGD

src/adapters/MorphoMarketV1Adapter.sol

@@ -26,6 +26,13 @@ import {
 /// @dev Markets get removed from the marketIds when the allocation is zero, but it doesn't mean that the adapter has
 /// zero shares on the market.
 /// @dev This adapter can only be used for markets with the adaptive curve irm.
+/// @dev Donated shares are lost forever.
+///
+/// BURN SHARES
+/// @dev When submitting burnShares, it's recommended to put the caps of the market to zero to avoid losing more.
+/// @dev Burning shares takes time, so reactive depositors might be able to exit before the share price reduction.
+/// @dev It is possible to burn the shares of a market whose IRM reverts.
+/// @dev Burnt shares are lost forever.
 contract MorphoMarketV1Adapter is IMorphoMarketV1Adapter {
     using MarketParamsLib for MarketParams;
     using SharesMathLib for uint256;
@@ -106,7 +113,6 @@ contract MorphoMarketV1Adapter is IMorphoMarketV1Adapter {
         emit BurnShares(marketId, supplySharesBefore);
     }
 
-    /// @dev Does not log anything because the ids (logged in the parent vault) are enough.
     /// @dev Returns the ids of the allocation and the change in allocation.
     function allocate(bytes memory data, uint256 assets, bytes4, address) external returns (bytes32[] memory, int256) {
         MarketParams memory marketParams = abi.decode(data, (MarketParams));
@@ -133,7 +139,6 @@ contract MorphoMarketV1Adapter is IMorphoMarketV1Adapter {
         return (ids(marketParams), int256(newAllocation) - int256(oldAllocation));
     }
 
-    /// @dev Does not log anything because the ids (logged in the parent vault) are enough.
     /// @dev Returns the ids of the deallocation and the change in allocation.
     function deallocate(bytes memory data, uint256 assets, bytes4, address)
         external

src/adapters/interfaces/IMorphoMarketV1Adapter.sol

@@ -10,9 +10,9 @@ interface IMorphoMarketV1Adapter is IAdapter {
 
     event SetSkimRecipient(address indexed newSkimRecipient);
     event Skim(address indexed token, uint256 assets);
-    event SubmitBurnShares(bytes32 indexed id, uint256 executableAt);
-    event RevokeBurnShares(bytes32 indexed id);
-    event BurnShares(bytes32 indexed id, uint256 supplyShares);
+    event SubmitBurnShares(bytes32 indexed marketId, uint256 executableAt);
+    event RevokeBurnShares(bytes32 indexed marketId);
+    event BurnShares(bytes32 indexed marketId, uint256 supplyShares);
     event Allocate(bytes32 indexed marketId, uint256 newAllocation, uint256 mintedShares);
     event Deallocate(bytes32 indexed marketId, uint256 newAllocation, uint256 burnedShares);
 
@@ -40,14 +40,14 @@ interface IMorphoMarketV1Adapter is IAdapter {
     function marketIdsLength() external view returns (uint256);
     function allocation(MarketParams memory marketParams) external view returns (uint256);
     function expectedSupplyAssets(bytes32 marketId) external view returns (uint256);
-    function burnSharesExecutableAt(bytes32 id) external view returns (uint256);
+    function burnSharesExecutableAt(bytes32 marketId) external view returns (uint256);
     function ids(MarketParams memory marketParams) external view returns (bytes32[] memory);
 
     /* NON-VIEW FUNCTIONS */
 
-    function submitBurnShares(bytes32 id) external;
-    function revokeBurnShares(bytes32 id) external;
-    function burnShares(bytes32 id) external;
+    function submitBurnShares(bytes32 marketId) external;
+    function revokeBurnShares(bytes32 marketId) external;
+    function burnShares(bytes32 marketId) external;
     function setSkimRecipient(address newSkimRecipient) external;
     function skim(address token) external;
 }