Aave-v3.5-features.md

Aave v3.5 features

Rounding improvements

Historically Aave has used half-up, or so called bankers rounding, for rounding operations. This has been a source of confusion and bugs in the past as it makes the rounding somewhat chaotic.

The aave protocol handles balances & yield by storing a scaledBalance and an index. The actual balance is then derived by multiplying the scaledBalance by the index or by dividing the amount by the index. The index has 1e27 precision, which means that the rounding error usually applies on the least significant digit of the asset. In practice that means that when e.g. depositing 1e18 of an asset, your balance might be 1e18 +-1. The rounding depends on time & index accrual, so it's difficult to exactly predict the outcome. The stata tokens and similar systems built on top therefore use a custom rounding function to ensure that the rounding is always in favor of the protocol (like it is done on the 4626 spec).

It's important to note that the rounding error is still technically unbounded. The index can grow almost(uint128.max) infinitely and the shares and the underlying share the same decimal precision. The intention of this change is to always round in favor of the protocol, to avoid insolvency situations.

This upgrade aligns the rounding methods by:

Rounding down when minting aTokens

When users supply(amount) to the protocol, the amount is rounded down. This means that from now on a supply will always be less than or equal to the amount the user supplied. A supply(n) will always yield m = n / index scaled balance.

Example: supply(1e18) would previously have resulted in an aToken balance equal to scaledAmount = halfUp(amount / index), so that amount' = halfUp(scaledAmount * index) = amount (+-precision loss). After the change the variance is limited to amount' = halfUp(scaledAmount * index) = amount (-precision loss).

Rounding up when burning aTokens

When users withdraw(amount) from the protocol, the amount is rounded up. This is done to ensure that the user always receives at least the amount they requested.

Example: withdraw(amount) would previously have resulted in releasing amount of underlying and burning scaledAmount = halfUp(amount / index) shares, so that amount' = halfUp(scaledAmount * index) = amount (+-precision loss).

Rounding down for aToken balance operations

balanceOf and totalSupply are now rounded down. Currently these methods sometimes overaccount by 1 wei, and sometimes underaccount by 1 wei. From now on they will no longer overaccount. This is done to ensure correct behavior in regards to user operations, so that e.g. withdraw(aToken.balanceOf(user)) will always redeem the full user balance.

Rounding up when minting vTokens

When users borrow(amount) from the protocol, the amount is rounded up. This is done to ensure that the protocol never underaccounts the user debt.

Rounding down when burning vTokens

When users repay(amount) or are being liquidated, the protocol must ensure that the repayment covers the full debt.

Rounding up for vToken balance operations

balanceOf and totalSupply are now rounded up. Currently these methods sometimes overaccount by 1 wei, and sometimes underaccount by 1 wei. From now on they will no longer underaccount. This is done to ensure correct behavior in regards to user operations, so that e.g. repay(vToken.balanceOf(user)) will always repay the full debt.

Transfers

On transfers, the scaled amount is rounded up. While for other methods the rational is obvious(and well specified on ERC4626), on transfers the "correct" path is more debatable. We think that currently the more "problematic" code-path is, if you pull x funds, but you get x-1. Therefore by rounding up the scaled amount, we ensure that the contract pulling receives at least the amount it requested.

Rounding for User Position Valuation in Base Currency

When calculating a user's health factor, the protocol must convert their asset and debt balances into a common base currency (e.g., USD). To ensure the protocol's safety, these conversions are rounded pessimistically.

• 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. As a result of this change, the health factor of a user may be lower than in previous versions of the protocol.

Internal scaledAccounting

A lot of the precision loss is caused by having multiple conversions from unscaled to scaled and back. To name a few examples:

• when validating caps, for the validation the scaledAmount * index + input.amount were considered to be the total supply - this is not accurate though as the conversion from input.amount to scaledAmount will always have a precision loss.
• when minting tokens to the treasury, the protocol stores the scaledAmount in accruedToTreasury. When the protocol mints to the treasury, the accruedToTreasury is scaled up and then scaled down again, which can lead to precision loss.

While these problems are not critical, for the most part, they can be mitigated by consistently working with the scaled values throughout the protocol. Therefore, mint and burn now accept scaledAmount as an additional input, which allows avoiding repeated roundings. As a side effect, this also slightly reduces gas consumption across the board.

Improved flag logic

In v3.4 we increased the robustness of the flag logic for borrow operations, by switching validations from unscaled to scaled comparisons to checks against the actual balance (e.g. balanceZeroAfterBurn).

In v3.5 we decided to double down on these robustness improvements:

• on repayWithAToken and withdraw, the collateral flag is now properly set to false when burning all aTokens in the process. In previous versions of the protocol, there were edge cases in which the collateral flag was not properly updated.

Improved allowance

Aave historically has never accurately tracked allowance. The reason for this is that in practice most operations are performed with the desired amount of assets, but the a/v token converting these amounts to shares. For allowance / approval, this means that the consumed allowance is not always equal to the amount transferred. While this problem is not perfectly solvable without breaking changes, in v3.5 the protocol ensures that the exact consumed allowance is burned if available.

Example: When a user calls transferFrom(sender, recipient, 100) in most cases the transfer will transfer slightly more than 100 tokens (e.g 101). This is due to precision loss between assets/shares conversion. In Aave versions < 3.5 this action would always result in burning 100 allowance. On Aave v3.5, the transfer will check the balance difference on the sender and discount up to the difference from the allowance. Example: The user transfers 100, but due to rounding he loses 102 balance. The allowance is reduced by up to 102. If the original allowance was only 100, the transaction will still pass for backwards compatibility.

Misc changes

• smaller refactoring in LiquidationLogic making the code more consistent
• 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 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.

Changelog

• General changes:
  • Changed conversions between scaled and unscaled amounts:
    • In the AToken contract:
      • The balanceOf and totalSupply functions now round down (from scaled to unscaled).
      • The mint function now rounds down (from unscaled to scaled).
      • The burn function now rounds up (from unscaled to scaled).
      • Calculations of a transfer's scaled amount now round up in AToken (from unscaled to scaled).
    • In the VariableDebtToken contract:
      • The balanceOf and totalSupply functions now round up (from scaled to unscaled).
      • The mint function now rounds up (from unscaled to scaled).
      • The burn function now rounds down (from unscaled to scaled).
• Pool contract:
  • The finalizeTransfer function now accepts scaled amounts instead of unscaled amounts. This avoids the precision loss caused by rounding the unscaled parameters.
  • The eliminateReserveDeficit function now returns the actual amount of deficit that was covered.
• AToken contract:
  • The following functions now accept a scaledAmount parameter instead of the amount parameter, which avoids the precision loss caused by rounding the amount parameter:
    • mint
    • mintToTreasury
    • transferOnLiquidation
  • The burn function now accepts a new scaledAmount argument, which is the scaled amount of tokens to be burned. This avoids the precision loss caused by rounding the amount parameter.
  • Changed the logic and math of the allowance decrease in the transferFrom function.
• VariableDebtToken contract:
  • The mint function now accepts a new scaledAmount argument, which is the scaled amount of tokens to be minted. This avoids the precision loss caused by rounding the amount parameter.
  • The burn function now accepts a scaledAmount parameter instead of the amount parameter, which avoids the precision loss caused by rounding the amount parameter.
  • Added new state variables __unusedGap and __DEPRECATED_AND_NEVER_TO_BE_REUSED.
  • Changed the logic and math of the borrow allowance decrease in the mint function.
• DebtTokenBase contract:
  • Changed the logic and math of the borrow allowance decrease in the _decreaseBorrowAllowance function.
• IncentivizedERC20 contract:
  • Added a new _spendAllowance function, which is used to decrease the allowance of a spender.
• ScaledBalanceTokenBase contract:
  • The following functions now accept scaled amounts instead of unscaled amounts:
    • _mintScaled
    • _burnScaled
  • Changed the math of the amountToMint variable in the _mintScaled function.
  • Changed the math of the amountToBurn and amountToMint variables in the _burnScaled function.
• Libraries:
  • BorrowLogic library:
    • The executeBorrow function now checks the health factor and the LTV of a user after the borrow operation by calling the new ValidationLogic.validateHFAndLtv function.
    • In the executeRepay function, the contract now checks the health factor of a user (user, not onBehalfOf) after the repay operation when the user is repaying with ATokens.
  • FlashLoanLogic library:
    • The executeFlashLoan function now rounds up the protocol fees for flash loans of type 0.
  • GenericLogic library:
    • In the calculateUserAccountData function, the precision in health factor calculations has been improved.
    • In the calculateAvailableBorrows function, the availableBorrowsInBaseCurrency variable is now rounded down.
    • In the _getUserDebtInBaseCurrency function, the amount in the base currency is now rounded up.
  • LiquidationLogic library:
    • The executeEliminateDeficit function now returns the actual amount of deficit that was covered.
    • In the executeLiquidationCall function, some rounding behavior has been changed:
      • The borrowerReserveDebtInBaseCurrency variable is now rounded up.
      • The isDebtMoreThanLeftoverThreshold variable is now rounded up.
    • In the _calculateAvailableCollateralToLiquidate function, the debtAmountNeeded variable is now rounded up when maxCollateralToLiquidate > borrowerCollateralBalance.
  • ReserveLogic library:
    • In the _accrueToTreasury function, the totalDebtAccrued variable is now rounded down.
  • SupplyLogic library:
    • The executeFinalizeTransfer function now accepts scaled amounts instead of unscaled amounts.
  • ValidationLogic library:
    • The following functions now accept scaled parameters instead of unscaled parameters, which avoids the precision loss caused by rounding unscaled parameters:
      • validateSupply
      • validateWithdraw
      • validateBorrow
      • validateRepay
    • The validateBorrow function no longer checks the user's health factor and LTV before the borrow operation.
  • A new TokenMath library has been added. It contains functions to perform conversions between scaled and unscaled amounts for A/V tokens.