Aave V3 Flash Loans

Flash Loans are a hallmark feature of DeFi protocols like Aave, enabling users (typically smart contracts) to borrow large amounts of assets without providing any upfront collateral, provided the loan amount plus a premium (fee) is returned within the same transaction. This atomic guarantee makes them powerful tools for arbitrage, liquidations, collateral swaps, debt refinancing, and other complex strategies.

Aave V3 offers two main flash loan functions exposed via the Pool.sol contract:

1. flashLoanSimple(receiverAddress, asset, amount, params, referralCode): Borrows a single asset.
2. flashLoan(receiverAddress, assets[], amounts[], interestRateModes[], onBehalfOf, params, referralCode): Borrows multiple assets simultaneously, with an option to open debt positions instead of repaying immediately (Mode 2).

We'll primarily trace the flashLoanSimple flow for clarity, as flashLoan builds upon the same core principles but adds iteration and the debt-opening mode.

The Entry Point: Pool.flashLoanSimple()

A flash loan is initiated by calling flashLoanSimple (or flashLoan) on the Pool.sol contract.

// File: /src/contracts/protocol/pool/Pool.sol

/// @inheritdoc IPool
function flashLoanSimple(
  address receiverAddress,  // The contract that will receive funds and execute logic
  address asset,            // The asset being borrowed
  uint256 amount,           // The amount of the asset to borrow
  bytes calldata params,    // Arbitrary data passed to the receiver's callback
  uint16 referralCode      // Optional referral code
) public virtual override {
  // Prepare parameters for the logic library
  DataTypes.FlashloanSimpleParams memory flashParams = DataTypes.FlashloanSimpleParams({
    receiverAddress: receiverAddress,
    asset: asset,
    amount: amount,
    params: params,
    referralCode: referralCode,
    flashLoanPremiumToProtocol: _flashLoanPremiumToProtocol, // Get premium % from storage
    flashLoanPremiumTotal: _flashLoanPremiumTotal         // Get total premium % from storage
  });
  // Delegate execution to the FlashLoanLogic library, passing the specific reserve data
  FlashLoanLogic.executeFlashLoanSimple(_reserves[asset], flashParams);
}

Similar to other Pool functions, flashLoanSimple acts mainly as a dispatcher:

1. It receives the request parameters.
2. It retrieves the current flash loan premium percentages (_flashLoanPremiumTotal, _flashLoanPremiumToProtocol) from PoolStorage.
3. It packages these, along with the function arguments, into a DataTypes.FlashloanSimpleParams struct.
4. It fetches the specific ReserveData for the requested asset from the _reserves mapping (defined in PoolStorage).
5. It delegates the entire operation to the static executeFlashLoanSimple function within the FlashLoanLogic library, passing the reserve data and the parameters struct.

Core Execution: FlashLoanLogic.executeFlashLoanSimple()

This function within FlashLoanLogic.sol orchestrates the main steps of the flash loan.

// File: /src/contracts/protocol/libraries/logic/FlashLoanLogic.sol (Conceptual Structure)

function executeFlashLoanSimple(
  DataTypes.ReserveData storage reserve,
  DataTypes.FlashloanSimpleParams memory params
) internal {
  // 1. Validation
  ValidationLogic.validateFlashloanSimple(reserve, params.amount);

  // 2. Calculate Premiums
  uint256 totalPremium = params.amount.percentMul(params.flashLoanPremiumTotal);
  uint256 premiumToProtocol = totalPremium.percentMul(params.flashLoanPremiumToProtocol);

  // 3. Transfer Funds to Receiver
  IAToken(reserve.aTokenAddress).transferUnderlyingTo(params.receiverAddress, params.amount);

  // 4. Execute Receiver's Logic (Callback)
  bool success = IFlashLoanSimpleReceiver(params.receiverAddress).executeOperation(
    params.asset,
    params.amount,
    totalPremium,
    msg.sender, // initiator
    params.params   // pass through user-provided data
  );
  require(success, Errors.INVALID_FLASHLOAN_EXECUTOR_RETURN);

  // 5. Handle Repayment
  _handleFlashLoanRepayment(
    reserve,
    DataTypes.FlashLoanRepaymentParams({
      amount: params.amount,
      totalPremium: totalPremium,
      flashLoanPremiumToProtocol: premiumToProtocol,
      asset: params.asset,
      receiverAddress: params.receiverAddress,
      referralCode: params.referralCode
    })
  );
}

Let's break down these steps:

1. Validation (ValidationLogic.validateFlashloanSimple):

   • Checks basic conditions using ValidationLogic.sol:
     • Is the reserve active, not paused? (ReserveConfiguration.sol)
     • Is flash lending enabled for this asset? (ReserveConfiguration.sol)
     • Is the requested amount valid (e.g., does the reserve have enough liquidity if virtual accounting isn't active)? Checks IERC20(aTokenAddress).totalSupply().

2. Calculate Premiums:

   • The totalPremium is calculated as a percentage (flashLoanPremiumTotal) of the borrowed amount using PercentageMath.percentMul.
   • The portion of the premium destined for the Aave Treasury (premiumToProtocol) is calculated as a percentage (flashLoanPremiumToProtocol) of the totalPremium.

3. Transfer Funds to Receiver:

   • The core transfer happens here. The function calls transferUnderlyingTo on the reserve's AToken contract (IAToken.sol, implemented in AToken.sol).
   • The AToken contract holds the actual underlying liquidity and transfers the requested amount to the params.receiverAddress.

4. Execute Receiver's Logic (Callback):

   • Crucially, the FlashLoanLogic now calls the executeOperation function on the params.receiverAddress.
   • This receiver contract must implement the IFlashLoanSimpleReceiver (or IFlashLoanReceiver for multi-asset loans) interface.
   • The executeOperation function receives the asset, amount, calculated premium, the original initiator's address, and the arbitrary params data provided in the initial flashLoanSimple call.
   • This is where the user's custom flash loan logic resides (e.g., execute arbitrage trades, interact with other protocols, etc.).
   • The executeOperation must return true to signal successful execution and readiness to repay. If it returns false or reverts, the entire flash loan transaction reverts.

5. Handle Repayment (_handleFlashLoanRepayment):

   • After the receiver's executeOperation successfully returns true, FlashLoanLogic proceeds to secure repayment. This is handled by the internal _handleFlashLoanRepayment function.
   • This function only handles the standard repayment case (Mode 0) because flashLoanSimple doesn't support opening debt positions.
   • Pull Repayment: It transfers amount + totalPremium of the underlying asset from the params.receiverAddress back to the reserve's AToken contract. This is done using IERC20(asset).safeTransferFrom. Important: The receiver contract must have approved the Pool's AToken address to spend at least amount + totalPremium before executeOperation returns.
   • Notify AToken: It calls IAToken(aTokenAddress).handleRepayment(receiverAddress, receiverAddress, amount + totalPremium) to inform the aToken that the funds have been returned. The aToken can then update its internal accounting.
   • Update Reserve State: It calls reserve.updateState(reserveCache) (using ReserveLogic.sol) to accrue any interest that might have occurred during the flash loan execution (though typically negligible within a single transaction).
   • Distribute Premium to Suppliers: It calculates the premium portion for suppliers (totalPremium - premiumToProtocol). It then uses reserve.cumulateToLiquidityIndex (in ReserveLogic.sol) to effectively increase the liquidityIndex based on this supplier premium, distributing the fee proportionally among all aToken holders over time.
   • Send Premium to Treasury: It calls IAToken(aTokenAddress).mintToTreasury(premiumToProtocol, reserve.liquidityIndex) to mint new aTokens representing the protocol's share of the premium directly to the treasury address associated with the aToken.
   • Emit Event: Finally, back in Pool.sol (after FlashLoanLogic returns), the FlashLoan event is emitted.

The Receiver Contract (IFlashLoanSimpleReceiver)

Any contract intending to receive a simple flash loan must implement this interface:

// File: /src/contracts/misc/flashloan/interfaces/IFlashLoanSimpleReceiver.sol

interface IFlashLoanSimpleReceiver {
  function executeOperation(
    address asset,
    uint256 amount,
    uint256 premium,
    address initiator,
    bytes calldata params
  ) external returns (bool);

  // Helper functions to get context
  function ADDRESSES_PROVIDER() external view returns (IPoolAddressesProvider);
  function POOL() external view returns (IPool);
}

The developer's core task is implementing executeOperation:

1. Perform desired actions using the received amount of asset.
2. Use the params data if needed for context.
3. Critically: Ensure the contract has enough asset (either from the flash loan proceeds or pre-existing balance) to cover amount + premium.
4. Critically: Ensure the contract approves the reserve's AToken address (obtainable via IPool(POOL()).getReserveData(asset).aTokenAddress) to spend amount + premium of the asset. This approval must happen before returning true.
5. Return true.

The FlashLoanReceiverBase.sol contract provides a convenient base, pre-populating ADDRESSES_PROVIDER and POOL.

Multi-Asset Flash Loans (Pool.flashLoan)

The flashLoan function follows a similar pattern but iterates through arrays (assets, amounts, interestRateModes).

• Validation: ValidationLogic.validateFlashloan checks each asset individually.
• Transfers: Transfers happen sequentially for each asset.
• Callback: Calls IFlashLoanReceiver.executeOperation, passing arrays of assets, amounts, and premiums.
• Repayment:
  • Mode 0: Handles repayment similarly to flashLoanSimple but iterates through the assets, pulling back amounts[i] + premiums[i] for each.
  • Mode 2 (Open Variable Debt): If interestRateModes[i] == 2, instead of pulling repayment for that specific asset/amount, it calls BorrowLogic.executeBorrow with releaseUnderlying: false and onBehalfOf set to the address provided in the initial flashLoan call. This performs standard borrow validation (HF, LTV, etc.) and mints debt tokens for the onBehalfOf user. No premium is paid for assets where debt is opened. The onBehalfOf address must not be the receiverAddress in this mode to prevent contracts from assigning debt to themselves unexpectedly.

Security & Conclusion

Flash Loans are incredibly powerful but require careful implementation in the receiver contract. The primary risks are:

• Reentrancy: While Aave V3 core contracts are generally protected, the receiver's executeOperation must be wary of reentering the Aave Pool or other protocols in unsafe ways.
• Incorrect Repayment: Failing to have sufficient funds or approve the repayment will cause the entire transaction to revert.
• Logic Errors: Any bug in the receiver's executeOperation could lead to loss of funds or failed operations.

In summary, Aave V3's flash loan mechanism provides temporary, uncollateralized liquidity by transferring funds to a receiver, invoking the receiver's custom logic via executeOperation, and then atomically reclaiming the funds plus a premium (or opening a debt position). The Pool acts as the entry point, delegating the complex orchestration of validation, transfer, callback, and repayment/debt creation to the FlashLoanLogic library and interacting with AToken, ValidationLogic, ReserveLogic, and potentially BorrowLogic.