Merge pull request #558 from morpho-org/fix/document-conversions-63

Document possible conversion reverts

src/interfaces/IMorpho.sol

@@ -177,6 +177,8 @@ interface IMorpho {
     /// @dev Either `assets` or `shares` should be zero. To withdraw max, pass the `shares`'s balance of `onBehalf`.
     /// @dev `msg.sender` must be authorized to manage `onBehalf`'s positions.
     /// @dev Withdrawing an amount corresponding to more shares than supplied will revert for underflow.
+    /// @dev It is advised to use the `shares` input when withdrawing the full position to avoid reverts due to
+    /// conversion roundings between shares and assets.
     /// @param marketParams The market to withdraw assets from.
     /// @param assets The amount of assets to withdraw.
     /// @param shares The amount of shares to burn.
@@ -217,6 +219,8 @@ interface IMorpho {
     /// `onMorphoReplay` function with the given `data`.
     /// @dev Either `assets` or `shares` should be zero. To repay max, pass the `shares`'s balance of `onBehalf`.
     /// @dev Repaying an amount corresponding to more shares than borrowed will revert for underflow.
+    /// @dev It is advised to use the `shares` input when repaying the full position to avoid reverts due to conversion
+    /// roundings between shares and assets.
     /// @param marketParams The market to repay assets to.
     /// @param assets The amount of assets to repay.
     /// @param shares The amount of shares to burn.

src/libraries/periphery/MorphoBalancesLib.sol

@@ -93,6 +93,8 @@ library MorphoBalancesLib {
 
     /// @notice Returns the expected supply assets balance of `user` on a market after having accrued interest.
     /// @dev Warning: Wrong for `feeRecipient` because their supply shares increase is not taken into account.
+    /// @dev Warning: Withdrawing a supply position using the expected assets balance can lead to a revert due to
+    /// conversion roundings between shares and assets.
     function expectedSupplyAssets(IMorpho morpho, MarketParams memory marketParams, address user)
         internal
         view
@@ -106,6 +108,8 @@ library MorphoBalancesLib {
     }
 
     /// @notice Returns the expected borrow assets balance of `user` on a market after having accrued interest.
+    /// @dev Warning: repaying a borrow position using the expected assets balance can lead to a revert due to
+    /// conversion roundings between shares and assets.
     function expectedBorrowAssets(IMorpho morpho, MarketParams memory marketParams, address user)
         internal
         view