fix: informal issues

Author: TepNik

docs/3.5/Aave-v3.5-features.md

@@ -54,7 +54,7 @@ When calculating a user's health factor, the protocol must convert their asset a
 - **Collateral (aToken) Value:** The value of a user's supplied assets in the base currency is always rounded **down**. This ensures the protocol never overestimates the value of a user's collateral.
 - **Debt (vToken) Value:** The value of a user's borrowed assets in the base currency is always rounded **up**. This ensures the protocol never underestimates a user's debt. A key consequence of this is that any non-zero debt, no matter how small, will be valued as at least 1 wei in the base currency. This prevents situations where tiny "dust" debts could round down to zero after conversion, making them invisible to Health Factor calculations.
 
-This approach of always rounding in favor of the protocol during health factor calculations is a critical security measure that protects it from potential insolvencies arising from rounding discrepancies.
+This approach of always rounding in favor of the protocol during health factor calculations is a critical security measure that protects it from potential insolvencies arising from rounding discrepancies. As a result of this change, the health factor of a user may be lower than in previous versions of the protocol.
 
 ### Internal scaledAccounting
 
@@ -88,5 +88,5 @@ In Aave versions `< 3.5` this action would always result in burning `100` allowa
 - `repayWithAToken` is only allowed when the user is still healthy **after** the repayment. This is done in order to prevent some edge cases where the user would have debt, but no collateral or now with the adjustments on rounding, bringing himself into liquidation area through selfRepayment.
 - `eliminateReserveDeficit` return value: The `eliminateReserveDeficit` function has been updated to return the `uint256` amount of deficit that was actually covered. This returned value represents the lesser of the input `amount` and the actual `deficit` of the reserve at the time of the call. This provides clarity to the caller on the exact amount that was successfully written off.
   - Note: This is a non-breaking change. The migration from no return value to a `uint256` return value is not expected to break any existing integrations.
-- In previous versions of the protocol, `Mint` and `Burn` events did not always perfectly reflect the amount minted and burned due to imprecision in the calculation of the `amountToMint` and `amountToBurn` variables. In v3.5, the amount emitted now always accurately reflects the difference between the previous upscaled balance and the new upscaled balance.
+- In previous versions of the protocol, `Mint` and `Burn` events on `AToken` and `VariableDebtToken` did not always perfectly reflect the amount minted and burned due to imprecision in the calculation of the `amountToMint` and `amountToBurn` variables. In v3.5, the `value` emitted in `Mint` and `Burn` events now always accurately reflects the difference between the previous upscaled balance and the new upscaled balance. For `AToken` transfers, the `Transfer` event emits the input amount, while the `BalanceTransfer` event emits the precise scaled amount being transferred. Due to the new rounding logic, the actual change in unscaled balance might differ slightly from the input amount.
 - The control flow of `borrow` has been altered. While in previous versions of the protocol the `borrow` function would first check the hf limitations, from v3.5.0 the healthfactor check is performed at the end. Moving the check allows to de-duplicate the healthfactor related calculations and avoids issues due to non-equivalence in some edge cases.

docs/3.5/Aave-v3.5-properties.md

@@ -16,7 +16,7 @@ In the following properties `shares` refers to the `scaled balance`, while `asse
 - when evaluating the vToken balance of a user, the balance should be calculated as `balance = ceil(shares * index)`
 - when calculating the `liquidationProtocolFeeAmount` and the fee distributed to the treasury, the received shares should be rounded up
 - the flashLoanPremium is always rounded up, meaning that even when flashing just 1 wei of an asset, you will pay 1 wei of fee (where in previous versions of the protocol, the fee would be rounded to zero)
-- when calculating the value of a user's collateral (aTokens) in the base currency, the result of `(balanceInAssetUnits * assetPrice) / assetUnit` is rounded down.
+- when calculating the value of a user's collateral (aTokens) in the base currency, the result of `(balanceInAssetUnits * assetPrice) / assetUnit` is rounded down. (this was already the case in previous versions of the protocol for `GenericLogic._getUserBalanceInBaseCurrency`)
 - when calculating the totalSupply of the aToken, `totalScaledSupply * index` is rounded down.
 - when calculating the value of a user's total debt (vTokens) in the base currency, the result of `(debtInAssetUnits * assetPrice) / assetUnit` is rounded up.
 - when calculating the totalSupply of the vToken, `totalScaledSupply * index` is rounded up.

src/contracts/protocol/libraries/logic/BorrowLogic.sol

@@ -73,7 +73,6 @@ library BorrowLogic {
       })
     );
 
-    // As vDebt.mint rounds up, we ensure an equivalent of >= params.amount debt is created.
     reserveCache.nextScaledVariableDebt = IVariableDebtToken(reserveCache.variableDebtTokenAddress)
       .mint(
         params.user,

src/contracts/protocol/libraries/logic/GenericLogic.sol

@@ -153,10 +153,10 @@ library GenericLogic {
 
     // @note At this point, `avgLiquidationThreshold` represents
     // `SUM(collateral_base_value_i * liquidation_threshold_i)` for all collateral assets.
-    // It has 8 decimals (base currency) + 4 decimals (percentage) = 12 decimals.
+    // It has 8 decimals (base currency) + 2 decimals (percentage) = 10 decimals.
     // healthFactor has 18 decimals
     // healthFactor = (avgLiquidationThreshold * WAD / totalDebtInBaseCurrency) / 100_00
-    // 18 decimals = (12 decimals * 18 decimals / 8 decimals) / 4 decimals = 18 decimals
+    // 18 decimals = (10 decimals * 18 decimals / 8 decimals) / 2 decimals = 18 decimals
     vars.healthFactor = (vars.totalDebtInBaseCurrency == 0)
       ? type(uint256).max
       : vars.avgLiquidationThreshold.wadDiv(vars.totalDebtInBaseCurrency) / 100_00;
@@ -220,7 +220,6 @@ library GenericLogic {
     uint256 assetPrice,
     uint256 assetUnit
   ) private view returns (uint256) {
-    // Replicate vDebt.balanceOf (round up), to always overestimate the debt.
     uint256 userTotalDebt = IScaledBalanceToken(reserve.variableDebtTokenAddress)
       .scaledBalanceOf(user)
       .getVTokenBalance(reserve.getNormalizedDebt());

src/contracts/protocol/libraries/logic/LiquidationLogic.sol

@@ -72,6 +72,7 @@ library LiquidationLogic {
    * @param reservesData The state of all the reserves
    * @param userConfig The user configuration mapping that tracks the supplied/borrowed assets
    * @param params The additional parameters needed to execute the eliminateDeficit function
+   * @return The amount of deficit covered
    */
   function executeEliminateDeficit(
     mapping(address => DataTypes.ReserveData) storage reservesData,
@@ -108,7 +109,6 @@ library LiquidationLogic {
       userConfig.setUsingAsCollateral(reserve.id, params.asset, params.user, false);
     }
 
-    // As aToken.burn rounds up the burned shares, we ensure at least an equivalent of >= balanceWriteOff is burned.
     IAToken(reserveCache.aTokenAddress).burn({
       from: params.user,
       receiverOfUnderlying: reserveCache.aTokenAddress,
@@ -200,11 +200,9 @@ library LiquidationLogic {
       })
     );
 
-    // Replicate aToken.balanceOf (round down), to always underestimate the collateral.
     vars.borrowerCollateralBalance = IAToken(vars.collateralReserveCache.aTokenAddress)
       .scaledBalanceOf(params.borrower)
       .getATokenBalance(vars.collateralReserveCache.nextLiquidityIndex);
-    // Replicate vDebt.balanceOf (round up), to always overestimate the debt.
     vars.borrowerReserveDebt = IVariableDebtToken(vars.debtReserveCache.variableDebtTokenAddress)
       .scaledBalanceOf(params.borrower)
       .getVTokenBalance(vars.debtReserveCache.nextVariableBorrowIndex);

src/contracts/protocol/libraries/logic/ValidationLogic.sol

@@ -177,7 +177,6 @@ library ValidationLogic {
     }
 
     if (vars.borrowCap != 0) {
-      // Replicate vDebt.totalSupply (round up), to always overestimate the debt.
       vars.totalDebt = (params.reserveCache.currScaledVariableDebt + params.amountScaled)
         .getVTokenBalance(params.reserveCache.nextVariableBorrowIndex);
 
@@ -457,8 +456,8 @@ library ValidationLogic {
    * @param userConfig The state of the user for the specific reserve
    * @param asset The asset for which the ltv will be validated
    * @param from The user from which the aTokens are being transferred
-   * @param userEModeCategory The users active efficiency mode category
    * @param oracle The price oracle
+   * @param userEModeCategory The users active efficiency mode category
    */
   function validateHFAndLtvzero(
     mapping(address => DataTypes.ReserveData) storage reservesData,

src/contracts/protocol/tokenization/AToken.sol

@@ -203,7 +203,7 @@ abstract contract AToken is VersionedInitializable, ScaledBalanceTokenBase, EIP7
       // As an example: transferFrom(..., 1) at a liquidity index of 1.1 where the recipient has a "scaled up" balance of `9 * 1.1 = 9.9 = 9` before the transfer, will have a balance of `10 * 1.1. = 11` after the Transfer.
       // While this problem is not solvable without introducing breaking changes, on Aave v3.5 the situation is improved in the following way:
       // - The `correct` amount to be deducted is considered to be `scaledUpFloor(scaledDownCeil(input.amount))`. This replicates the behavior on transfer, followed by a balanceOf.
-      // - In order to not introduce a breaking change for existing integrations, the deducted allowance is based on the available allowance as `Max(availableAllowance, (amount, correctAmount))`
+      // - To avoid breaking existing integrations, the amount deducted from the allowance is the minimum of the available allowance and the actual up-scaled asset amount.
       amount.getATokenTransferScaledAmount(index).getATokenBalance(index)
     );
     _transfer(sender, recipient, amount.toUint120());

src/contracts/protocol/tokenization/VariableDebtToken.sol

@@ -23,15 +23,16 @@ abstract contract VariableDebtToken is DebtTokenBase, ScaledBalanceTokenBase, IV
   using TokenMath for uint256;
   using SafeCast for uint256;
 
-  // @note This gap is made only to add the `__deprecated_ghoUserState` variable
+  // @note This gap is made only to add the `__DEPRECATED_AND_NEVER_TO_BE_REUSED` variable
   // The length of this gap can be decreased in order to add new variables
-  uint[3] private __unusedGap;
+  uint256[3] private __unusedGap;
 
   // @note deprecated in v3.4.0 upgrade in the GHO vToken.
   // This storage slot can't be used in all vTokens, because the GHO vToken
   // had a mapping here (before v3.4.0) and right now has some non-zero mapping values in this slot.
   // old version: mapping(address => GhoUserState) internal _ghoUserState
-  bytes32 private __deprecated_ghoUserState;
+  // This storage slot MUST NOT be reused to avoid storage layout conflicts.
+  bytes32 private __DEPRECATED_AND_NEVER_TO_BE_REUSED;
 
   /**
    * @dev Constructor.
@@ -66,7 +67,10 @@ abstract contract VariableDebtToken is DebtTokenBase, ScaledBalanceTokenBase, IV
 
   /// @inheritdoc IERC20
   function balanceOf(address user) public view virtual override returns (uint256) {
-    return super.balanceOf(user).getVTokenBalance(POOL.getReserveNormalizedVariableDebt(_underlyingAsset));
+    return
+      super.balanceOf(user).getVTokenBalance(
+        POOL.getReserveNormalizedVariableDebt(_underlyingAsset)
+      );
   }
 
   /// @inheritdoc IVariableDebtToken
@@ -88,7 +92,7 @@ abstract contract VariableDebtToken is DebtTokenBase, ScaledBalanceTokenBase, IV
       // Similar to the aToken `transferFrom` function, handling this scenario exactly is impossible.
       // While this problem is not solvable without introducing breaking changes, on Aave v3.5 the situation is improved in the following way:
       // - The `correct` amount to be deducted is considered to be `scaledUpCeil(scaledAmount)`. This replicates the behavior on borrow followed by a balanceOf.
-      // - In order to not introduce a breaking change for existing integrations, the deducted allowance is based on the available allowance as `Max(availableAllowance, (amount, correctAmount))`
+      // - To avoid breaking existing integrations, the amount deducted from the allowance is the minimum of the available allowance and the actual up-scaled debt amount.
       uint256 scaledUp = scaledAmount.getVTokenBalance(index);
       _decreaseBorrowAllowance(
         onBehalfOf,

src/contracts/protocol/tokenization/base/IncentivizedERC20.sol

@@ -208,8 +208,10 @@ abstract contract IncentivizedERC20 is Context, IERC20Detailed {
     uint256 correctedAmount
   ) internal virtual {
     uint256 currentAllowance = _allowances[owner][spender];
-    if (currentAllowance < amount)
+    if (currentAllowance < amount) {
       revert ERC20InsufficientAllowance(spender, currentAllowance, amount);
+    }
+
     uint256 consumption = currentAllowance >= correctedAmount ? correctedAmount : currentAllowance;
     _approve(owner, spender, currentAllowance - consumption);
   }