Merge pull request #79 from aave/mike/improve/rounding-comments

Mike/improve/rounding comments

Author: mpsc0x

aave-core/sources/aave-logic/flashloan_logic.move

@@ -748,9 +748,6 @@ module aave_pool::flashloan_logic {
         let a_token_total_supply = a_token_factory::total_supply(a_token_address);
         let reserve_accrued_to_treasury =
             pool::get_reserve_accrued_to_treasury(reserve_data);
-        // Note: Use ray_mul_down for conservative liquidity calculation
-        // Ensures available flashloan liquidity is not overestimated
-        // Prevents protocol from lending more than actually available
         let total_liquidity =
             a_token_total_supply
                 + wad_ray_math::ray_mul_down(
@@ -765,9 +762,6 @@ module aave_pool::flashloan_logic {
         pool_logic::set_next_liquidity_index(&mut reserve_cache, next_liquidity_index);
 
         // update accrued to treasury
-        // Note: Use ray_div_down for conservative treasury accrual
-        // Ensures protocol treasury doesn't accumulate optimistic amounts
-        // Aligns with mint_to_treasury's conservative minting approach
         let new_reserve_accrued_to_treasury =
             reserve_accrued_to_treasury
                 + wad_ray_math::ray_div_down(premium_to_protocol, next_liquidity_index);

aave-core/sources/aave-logic/generic_logic.move

@@ -34,14 +34,9 @@ module aave_pool::generic_logic {
 
         if (user_total_debt != 0) {
             let normalized_debt = pool::get_normalized_debt_by_reserve_data(reserve_data);
-            // Note: Use ray_mul_up for conservative debt calculation
-            // Ensures user debt is never underestimated in health factor calculations
             user_total_debt = wad_ray_math::ray_mul_up(user_total_debt, normalized_debt);
         };
 
-        // Note: Use ceil_div for conservative debt conversion to base currency
-        // Prevents rounding down small debt amounts to zero
-        // Critical for accurate debt tracking in low-price or small-amount scenarios
         math_utils::ceil_div(asset_price * user_total_debt, asset_unit)
     }
 
@@ -59,8 +54,6 @@ module aave_pool::generic_logic {
         asset_unit: u256
     ): u256 {
         let normalized_income = pool::get_normalized_income_by_reserve_data(reserve_data);
-        // Note: Use ray_mul_down for conservative collateral calculation
-        // Ensures user collateral is never overestimated in health factor calculations
         let balance =
             wad_ray_math::ray_mul_down(
                 a_token_factory::scaled_balance_of(

aave-core/sources/aave-logic/liquidation_logic.move

@@ -268,7 +268,7 @@ module aave_pool::liquidation_logic {
             vars.actual_collateral_to_liquidate,
             index,
             vars.collateral_a_token,
-            true // Round up, consistent with burn path, ensure complete liquidation without dust
+            true
         );
 
         // For the special case of account_address == params.user (self-liquidation) the liquidator_previous_a_token_balance
@@ -625,16 +625,11 @@ module aave_pool::liquidation_logic {
             10, reserve_config::get_decimals(&debt_reserve_cache_config)
         );
 
-        // Note: Use ceil_div for conservative liquidation debt calculation
-        // Ensures debt is never underestimated during liquidation
-        // Critical for accurate liquidation bonus and collateral seizure calculations
         vars.user_reserve_debt_in_base_currency = math_utils::ceil_div(
             vars.user_reserve_debt * vars.debt_asset_price,
             vars.debt_asset_unit
         );
 
-        // Note: Keep normal division for collateral (rounds down conservatively)
-        // Ensures collateral is never overestimated during liquidation
         vars.user_reserve_collateral_in_base_currency =
             (vars.user_collateral_balance * vars.collateral_asset_price)
                 / vars.collateral_asset_unit;

aave-core/sources/aave-logic/supply_logic.move

@@ -196,9 +196,6 @@ module aave_pool::supply_logic {
         // update pool state
         pool_logic::update_state(reserve_data, &mut reserve_cache);
 
-        // Note: Use ray_mul_down for conservative withdrawal balance calculation
-        // Ensures user cannot withdraw more than their actual balance
-        // Consistent with a_token_factory::balance_of behavior
         let user_balance =
             wad_ray_math::ray_mul_down(
                 a_token_factory::scaled_balance_of(account_address, a_token_address),

aave-core/sources/aave-pool/pool_logic.move

@@ -92,9 +92,6 @@ module aave_pool::pool_logic {
         liquidity_added: u256,
         liquidity_taken: u256
     ) {
-        // Note: Use ray_mul_up for conservative interest rate calculation input
-        // Ensures debt is not underestimated when calculating utilization rate
-        // Higher debt estimation → higher rates → encourages repayment → safer protocol
         let total_variable_debt =
             wad_ray_math::ray_mul_up(
                 reserve_cache.next_scaled_variable_debt,
@@ -440,9 +437,6 @@ module aave_pool::pool_logic {
             math_utils::percent_mul(total_debt_accrued, reserve_cache.reserve_factor);
 
         if (amount_to_mint != 0) {
-            // Note: Use ray_div_down for conservative treasury accrual
-            // Ensures protocol treasury doesn't accumulate optimistic amounts
-            // Consistent with mint_to_treasury and flashloan treasury accrual
             let new_accrued_to_treasury =
                 pool::get_reserve_accrued_to_treasury(reserve_data)
                     + wad_ray_math::ray_div_down(

aave-core/sources/aave-pool/pool_token_logic.move

@@ -93,10 +93,6 @@ module aave_pool::pool_token_logic {
 
                 let normalized_income =
                     pool::get_reserve_normalized_income(asset_address);
-                // Note: Use ray_mul_down for conservative treasury minting
-                // When converting scaled treasury accrual to actual amount,
-                // round down to ensure protocol doesn't overestimate mintable amount
-                // This aligns with the principle of favoring protocol safety
                 let amount_to_mint =
                     wad_ray_math::ray_mul_down(accrued_to_treasury, normalized_income);
 
@@ -133,19 +129,12 @@ module aave_pool::pool_token_logic {
             a_token_factory::get_underlying_asset_address(a_token_address);
         let index = pool::get_reserve_normalized_income(underlying_asset);
 
-        // Note: Calculate sender's actual balance using ray_mul_down (consistent with balance_of)
-        // This ensures proper detection of "full withdrawal" scenario for collateral flag updates
-        // Atomic snapshot: reuses pre-fetched index to guarantee all balance calculations
-        // are based on the same reserve state (prevents inconsistency if index updates mid-execution)
         let from_balance_before =
             wad_ray_math::ray_mul_down(
                 a_token_factory::scaled_balance_of(sender_address, a_token_address),
                 index
             );
 
-        // Note: Calculate recipient's actual balance using ray_mul_down (consistent with balance_of)
-        // This ensures proper detection of "first-time receipt" scenario for collateral flag enabling
-        // Atomic snapshot: reuses pre-fetched index to guarantee consistency with sender balance calculation
         let to_balance_before =
             wad_ray_math::ray_mul_down(
                 a_token_factory::scaled_balance_of(recipient, a_token_address),
@@ -157,7 +146,7 @@ module aave_pool::pool_token_logic {
             amount,
             index,
             a_token_address,
-            false // Use round half up for user-to-user transfers
+            false
         );
 
         finalize_transfer(

aave-core/sources/aave-tokens/a_token_factory.move

@@ -212,7 +212,7 @@ module aave_pool::a_token_factory {
         };
         let underlying_token_address = get_underlying_asset_address(metadata_address);
 
-        wad_ray_math::ray_mul_down(// Round down: count less asset (conservative)
+        wad_ray_math::ray_mul_down(
             current_scaled_balance,
             pool::get_reserve_normalized_income(underlying_token_address)
         )
@@ -240,7 +240,7 @@ module aave_pool::a_token_factory {
 
         let underlying_token_address = get_underlying_asset_address(metadata_address);
 
-        wad_ray_math::ray_mul_down(// Round down: count less total supply (conservative)
+        wad_ray_math::ray_mul_down(
             current_supply_scaled,
             pool::get_reserve_normalized_income(underlying_token_address)
         )
@@ -492,7 +492,7 @@ module aave_pool::a_token_factory {
             amount,
             index,
             metadata_address,
-            false // Round down: mint less aToken (safer for protocol)
+            false
         )
     }
 
@@ -519,7 +519,7 @@ module aave_pool::a_token_factory {
             amount,
             index,
             metadata_address,
-            true // Round up: burn more aToken scaled balance (safer for protocol)
+            true
         );
 
         let token_data = get_token_data(metadata_address);
@@ -550,9 +550,6 @@ module aave_pool::a_token_factory {
         // Early return if amount is 0 to avoid unnecessary computation
         if (amount == 0) { return };
 
-        // Pre-calculate scaled amount to check for dust
-        // Treasury accrued fees can be tiny (1-2 octa), which round down to 0
-        // We must skip these dust amounts to prevent assert failure in token_base::mint_scaled
         let amount_scaled = wad_ray_math::ray_div_down(amount, index);
 
         if (amount_scaled != 0) {
@@ -566,7 +563,7 @@ module aave_pool::a_token_factory {
                 amount,
                 index,
                 metadata_address,
-                false // Round down: mint less to treasury (conservative)
+                false
             );
         }
     }
@@ -621,23 +618,13 @@ module aave_pool::a_token_factory {
     ) acquires TokenMap {
         assert_token_exists(metadata_address);
 
-        // Pre-calculate scaled amount using directional rounding based on rounding_up parameter
-        // Reasons for pre-calculation:
-        // 1. Event accuracy: Must match the actual transferred scaled amount for event consistency
-        // 2. Dust handling: Liquidation protocol fees can be tiny (1-2 octa), which may round to 0
-        //    We must check and skip these dust transfers to prevent assert failure in token_base::transfer
-        // 3. Directional rounding: rounding_up=true for collateral transfer (favor protocol, consistent with burn),
-        //    rounding_up=false for protocol fees (conservative charging, favor user)
         let amount_scaled =
             if (rounding_up) {
-                wad_ray_math::ray_div_up(amount, index) // Round up, consistent with burn path
+                wad_ray_math::ray_div_up(amount, index)
             } else {
-                wad_ray_math::ray_div(amount, index) // Round half up, conservative charging
+                wad_ray_math::ray_div(amount, index)
             };
 
-        // Skip transfer if scaled amount is 0 (dust)
-        // This prevents assertion failure in token_base::transfer
-        // Dust amounts are acceptable to skip as they are too small to be meaningful
         if (amount_scaled == 0) { return };
 
         token_base::transfer(
@@ -649,8 +636,6 @@ module aave_pool::a_token_factory {
             rounding_up
         );
 
-        // Emit event with the actual transferred scaled amount
-        // This ensures event accurately reflects the on-chain state change
         events::emit_balance_transfer(
             from,
             to,
@@ -772,6 +757,6 @@ module aave_pool::a_token_factory {
         index: u256,
         metadata_address: address
     ) acquires TokenMap {
-        transfer_on_liquidation(from, to, amount, index, metadata_address, false) // Use round half up, conservative handling
+        transfer_on_liquidation(from, to, amount, index, metadata_address, false)
     }
 }

aave-core/sources/aave-tokens/variable_debt_token_factory.move

@@ -131,7 +131,7 @@ module aave_pool::variable_debt_token_factory {
         };
         let underlying_token_address = get_underlying_asset_address(metadata_address);
 
-        wad_ray_math::ray_mul_up(// Round up: count more debt (conservative)
+        wad_ray_math::ray_mul_up(
             current_scaled_balance,
             pool::get_reserve_normalized_variable_debt(underlying_token_address)
         )
@@ -159,7 +159,7 @@ module aave_pool::variable_debt_token_factory {
 
         let underlying_token_address = get_underlying_asset_address(metadata_address);
 
-        wad_ray_math::ray_mul_up(// Round up: count more total debt (conservative)
+        wad_ray_math::ray_mul_up(
             current_supply_scaled,
             pool::get_reserve_normalized_variable_debt(underlying_token_address)
         )
@@ -345,7 +345,7 @@ module aave_pool::variable_debt_token_factory {
             amount,
             index,
             metadata_address,
-            true // Round up: mint more debt token (safer for protocol)
+            true
         )
     }
 
@@ -383,7 +383,7 @@ module aave_pool::variable_debt_token_factory {
             amount,
             index,
             metadata_address,
-            false // Round down: burn less debt token scaled balance (safer for protocol)
+            false
         );
     }