FlashLoan

Overview

Venus Protocol has natively integrated a sophisticated flash loan mechanism directly into its Core Pool, enabling users to borrow assets without collateral, provided the loan is repaid within the same transaction. This feature unlocks powerful DeFi strategies including arbitrage, self-liquidation, and portfolio rebalancing, while maintaining the protocol's security and capital efficiency.

The system is designed for seamless integration with existing Venus markets, offering a trustless and composable foundation for advanced financial operations.

Key Features and Technical Architecture

  • Multi-Asset Support – Borrow single or multiple assets in a single atomic transaction, enabling complex strategies across different markets without intermediate steps.

  • Adaptive Repayment Logic:

    • Instant Full Repayment: Repay the full principal plus flashLoan fees to complete the transaction (standard flash loan model).

    • Partial Repayment Conversion: If a user has existing supplied collateral and repays partially, the outstanding balance automatically converts to a traditional borrow position secured by their collateral, preventing liquidation and failed transactions.

  • Streamlined Fee Mechanism:

    • A single configurable flashLoanFeeMantissa determines the total cost of the loan.

    • The protocol's share (flashLoanProtocolShare) is automatically calculated and routed to the Protocol Share Reserve, ensuring proper incentive alignment for the ecosystem.

  • Robust Security Model:

    • Governance Controlled: Critical parameters (fee structure, activation) are managed through Venus's governance system.

    • Upgradeable Design: Built using modular architecture for future improvements and maintenance.

    • Non-Custodial: Funds never leave the protocol's control during the transaction, eliminating counterparty risk.

This architecture positions Venus as a capital-efficient platform for both simple flash loans and sophisticated multi-step strategies, all while maintaining the protocol's security guarantees and economic sustainability.

Understanding Flash Loans

A flash loan is an uncollateralized loan that must be initiated and repaid within the boundaries of a single atomic transaction. This atomicity is enforced by the blockchain itself; if the borrowed amount plus fees is not returned to the protocol by the end of the transaction, the entire operation reverts as if it never happened. This mechanism eliminates credit risk for the protocol while granting users unprecedented capital efficiency.

The Venus Innovation: Flexible Repayment & Debt Conversion

Venus Protocol significantly enhances the basic flash loan model by introducing a partial repayment system, adding a crucial layer of flexibility and user safety.

1. Instant Full Repayment (Classic Model): The borrower repays the entire principal plus the accrued fee within the transaction. This is the standard flash loan model used for strategies like arbitrage and liquidation, where the profit is guaranteed to cover the cost.

2. Partial Repayment & Automatic Debt Conversion (Venus Model): This is a unique fail-safe mechanism. The user must repay at least the flash loan fee; otherwise, the transaction will revert. However, if a borrower repays the fee but cannot fully repay the principal and has existing supplied collateral on Venus, the protocol does not force a full revert. Instead, the unpaid principal shortfall is automatically converted into a standard borrow position against the user's existing collateral. This prevents immediate liquidation from a failed flash loan and allows for more complex, multi-block strategy planning. Crucially, for users with no collateral, full repayment of both principal and fee remains mandatory. Any shortfall will cause the transaction to revert, protecting the protocol from unsecured debt.

Example: A Practical Use Case

Let's imagine a user, Alice, who has supplied 10 ETH as collateral on Venus.

  1. Objective: Alice uses a flash loan to perform a complex arbitrage trade that she expects will take several transactions to complete.

  2. Action: She takes a flash loan of 100,000 USDC.

  3. Outcome A (Success): Her arbitrage is successful within the single transaction. She repays the 100,000 USDC plus a 0.09% fee (90 USDC). The transaction completes, and she keeps her profit.

  4. Outcome B (Partial Success - Venus's Advantage):

    • Her strategy only partially works. By the end of the transaction, she has only generated 80,000 USDC, leaving a shortfall of 20,000 USDC plus the fee.

    • On another protocol, her transaction would revert, she'd lose her gas fees, and potentially miss her profit opportunity.

    • On Venus, because she has 10 ETH as collateral and she has repaid the flashLoan fee amount, the protocol does not revert. Instead, it automatically converts the 20,000 USDC shortfall into a standard borrow position against her 10 ETH. Her flash loan is settled, and she now has a regular debt to manage over time, potentially still allowing her to profit from the 80,000 USDC she successfully generated.

  5. Outcome C (Failure):

    • Her strategy fails completely. She is only able to repay 50 USDC of the 90 USDC fee, leaving both a fee shortfall and the full principal unpaid.

    • In this scenario, the transaction will revert. The protocol's safety mechanism triggers because the user must repay at least the full flash loan fee, regardless of their collateral position. This protects the protocol from accumulating bad debt.

This innovative approach makes Venus flash loans both more powerful and more accessible, enabling a wider range of financial strategies while maintaining robust protocol security.

Core Smart Contracts

1. FlashLoanFacet.sol – FlashLoan Execution & Validation

Handles core flash loan operations including:

  • Asset transfers

  • Fee calculations

  • Repayment logic

  • Event emissions

Key Function

function executeFlashLoan(
    address payable onBehalf,
    address payable receiver,
    VToken[] memory vTokens,
    uint256[] memory underlyingAmounts,
    bytes memory param
) external nonReentrant {
    // Validation, asset transfer, fee calculation, repayment logic...
}

Explanation: This function serves as the main entry point for initiating both single or multi-asset flash loans. It orchestrates the complete flash loan lifecycle through a phased approach: validating request parameters, transferring multiple assets, executing the user's custom logic via a callback, and enforcing repayment with fee distribution. The entire operation is atomic; if any condition fails (e.g., insufficient repayment or unauthorized access), the transaction reverts, ensuring protocol safety.

Step-by-Step Workflow:

1. Validation & Initial Checks

  • Array Integrity: Ensures the vTokens and underlyingAmounts arrays are non-empty and of identical length to prevent parameter mismatches.

  • Asset Checks: For each vToken, verifies that:

    • The vToken is listed.

    • Flash loans are enabled for the asset (isFlashLoanEnabled()).

    • The requested loan amount is non-zero.

  • Authorization:

    • Initiator Authorization: Validates that the initiating contract (msg.sender) is pre-authorized (authorizedFlashLoan[msg.sender]) by the protocol to execute flash loans. This ensures only whitelisted, secure contracts can perform these operations.

    • Delegate Authorization: If the flash loan is executed on behalf of another user (onBehalf), it additionally validates that the initiator is an approved delegate (approvedDelegates[onBehalf][msg.sender]) for that specific user. This enables delegated trading strategies while maintaining security.

  • Address Validation: Ensures the receiver contract is a non-zero address.

2. Phased Execution

The core logic is delegated to an internal function that structures the process into three distinct phases:

Phase 1: Pre-Transfer Setup & Asset Disbursement

  • Fee Calculation: Computes the total fee and protocol fee for each asset using the vToken's fee parameters.

  • Asset Transfer: Calls transferOutUnderlying on each vToken contract to disburse the underlying assets to the receiver contract.

  • Balance Snapshot: Records the cash balance of each vToken market after transfer for subsequent repayment verification.

Phase 2: User Logic Execution

  • Callback Invocation: Calls executeOperation on the receiver contract, passing the loan details (assets, amounts, fees, initiator, onBehalf) and the param data. This is where the user's custom strategy (e.g., arbitrage, liquidation) is executed.

  • Approval Tracking: Returns an array (tokensApproved) indicating whether the receiver approved each asset for repayment transfer.

Phase 3: Repayment Handling & Settlement

  • Repayment Processing: For each asset, handles repayment based on the receiver's approval and the amount transferred back:

    • Full Repayment: If the receiver approved and transferred the full amount (principal + fees), the loan is settled.

    • Debt Conversion: If the receiver did not approve or only partially repaid(atleast the fees), the shortfall is converted into a standard borrow position for the onBehalf (requires existing collateral).

  • Fee Distribution: Routes the protocol's share of fees to the Protocol Share Reserve (PSR) and credits supplier fees to the respective vToken markets.

  • Balance Verification: Ensures the final vToken balances reflect the correct repayment amounts, reverting if discrepancies are detected.

3. Event Emission

  • Upon successful completion, a FlashLoanExecuted event is emitted, logging the receiver address, the vTokens involved, and the amounts loaned.

Critical Security Features:

  • Non-Reentrancy: The function and its internal phases are protected against reentrancy attacks (implied by nonReentrant modifier or equivalent checks).

  • Atomicity: The entire operation succeeds or reverts entirely, preventing partial state changes.

  • Authorization Enforcement: Strict access control ensures only whitelisted initiators can trigger flash loans.

  • Collateral Checks: For debt conversion, the initiator must have sufficient collateral to cover the converted borrow position; otherwise, the transaction reverts.

2. SetterFacet.sol - Setter Functions For Flashloan

This file contains administrative functions to manage flash loan permissions.

Functions

setWhiteListFlashLoanAccount

function setWhiteListFlashLoanAccount(address account, bool _isWhiteListed) external;

Explanation: This function is a central access control mechanism. In its initial phase, flash loans might be permissioned to prevent unknown or potentially malicious contracts from using the system until it's battle-tested. This function allows the admin or governance approved address to explicitly grant or revoke permission for a specific address (account) to call the executeFlashLoan function.

  • Whitelisting (_isWhiteListed = true) : Adds the account to a mapping of allowed addresses. This account can now initiate flash loans for itself.

  • Blacklisting/Removing (_isWhiteListed = false) : Removes the account from the whitelist, revoking its permission to initiate flash loans.

This is a temporary measure often used during a phased rollout before opening the system to permissionless access.

3. VToken.sol – Asset Transfer & Fee Calculation

Manages the underlying asset transfers, flash loan fee calculations, and creation of debt positions.

Key Functions

1.transferOutUnderlyingFlashLoan

function transferOutUnderlyingFlashLoan(address payable to, uint256 amount) external nonReentrant;

Explanation: This function is the work horse for moving assets during flash loan operations. When FlashLoanFacet.sol calls this during a flash loan, it performs several critical actions:

  1. Authorization Check: Ensures only the Comptroller contract can call this function.

  2. Flash Loan State Management: Sets the flashLoanAmount to track the active flashloan and prevents concurrent flash loans.

  3. Asset Transfer: Performs the low-level transfer of the underlying asset to the receiver address.

  4. Event Emission: Emits TransferOutUnderlyingFlashLoan event for tracking.

2. calculateFlashLoanFee

function calculateFlashLoanFee(uint256 amount) public view returns (uint256, uint256);

Explanation: This function computes the cost of a flash loan by calculating the total fee and the protocol's share. It uses fixed-point arithmetic to ensure precision in fee calculations, which is critical for maintaining protocol economics and ensuring accurate revenue distribution between suppliers and the protocol.

  1. Total Fee Calculation : Multiplies the loan amount by the global flashLoanFeeMantissa (a scaled value, e.g., 0.09% represented as 9e14).

  2. Protocol Fee Allocation : Calculates the protocol's portion by multiplying the totalFee by flashLoanProtocolShare (a scaled value representing the protocol's percentage share).

3. transferInUnderlyingFlashLoan

function transferInUnderlyingFlashLoan(
    address payable from,
    uint256 repaymentAmount,
    uint256 totalFee,
    uint256 protocolFee
) external nonReentrant returns (uint256);

Explanation: This function handles the repayment phase of flash loans with enhanced parameter validation. When called by the Comptroller, it performs several critical operations:

  1. Authorization Check: Ensures only the Comptroller contract can call this function.

  2. Asset Collection: Transfers the repayment amount from the receiver contract to the vToken.

  3. Repayment Validation: Validates that the actual transferred amount meets the minimum fee requirement.

  4. Protocol Fee Distribution: Automatically transfers the protocol fee portion to the Protocol Share Reserve.

  5. State Management: Resets the flashLoanAmount to 0, completing the flash loan cycle.

  6. Event Emission: Emits TransferInUnderlyingFlashLoan event with detailed repayment information.

3. setFlashLoanEnabled

function setFlashLoanEnabled(bool enabled) external returns (uint256);

Explanation: An administrative function that allows governance to explicitly enable or disable flash loan functionality for a specific vToken market. Unlike a toggle function, this takes a boolean parameter to set the exact desired state, preventing accidental state changes. This would be used to disable flash loans if a vulnerability is suspected in a particular asset's market or to enable them after security verification.

4. setFlashLoanFeeMantissa

function setFlashLoanFeeMantissa(
    uint256 flashLoanFeeMantissa_,
    uint256 flashLoanProtocolShare_
) external returns (uint256);

Explanation: This governance-controlled function updates the core economic parameters for flash loans. It allows the protocol to adjust both the total fee charged for flash loans and how that fee is distributed between the protocol treasury and liquidity suppliers. These parameters directly impact the protocol's revenue generation and the attractiveness of providing liquidity.

  1. flashLoanFeeMantissa_ : This is the total fee rate charged for flash loans (scaled by 1e18).

  2. flashLoanProtocolShare_ : This is the percentage of the total fee allocated to the Protocol Share Reserve (scaled by 1e18).

5. getCash

function getCash() external view override returns (uint);

Explanation: This function provides cash balance reporting with modified behavior during active flash loan operations. During normal operations, it returns the actual underlying token balance held by the vToken contract. However, during active flash loans (flashLoanAmount > 0), it returns the reduced cash balance reflecting funds temporarily transferred out.

The protocol now internally uses _getCashPriorWithFlashLoan() which returns getCashPrior() + flashLoanAmount to calculate total available liquidity including active flash loans. This design ensures accurate accounting while maintaining protocol stability through consistent interest rate and exchange rate calculations.

4. Flash Loan Receiver Standards

There is a standardized interface for contracts wishing to receive and handle flash loans from Venus Protocol:

1. IFlashLoanReceiver - Multi-Asset Standard

Purpose: For complex strategies requiring multiple assets in a single flash loan operation.

Interface: IFlashLoanReceiver

    function executeOperation(
        VToken[] calldata vTokens,
        uint256[] calldata amounts,
        uint256[] calldata premiums,
        address initiator,
        address onBehalf,
        bytes calldata param
    ) external returns (bool success, uint256[] memory repayAmounts);

Key Parameters:

  • vTokens: Array of VToken addresses borrowed

  • amounts: Corresponding amounts for each asset

  • premiums: Fee amounts for each asset

  • initiator: Address that initiated the flash loan

  • onBehalf: Address whose debt position will be used for any unpaid balance

  • param: Custom encoded data for strategy execution

Return Value:

  • success: Success status (must return true for transaction to complete)

  • repayAmounts: Array of actual repayment amounts for each asset

Base Contract: FlashLoanReceiverBase

  • Provides immutable Comptroller reference

  • Inherited by multi-asset receiver contracts

  • Ensures protocol governance integration

Use Cases: Cross-protocol arbitrage, multi-asset liquidations, complex portfolio rebalancing.

Core Requirements for the Standard

Receiver Contracts Must:

  1. Receive Assets: Acknowledge and handle the received flash-loaned assets.

  2. Execute Strategy: Perform intended operations (arbitrage, liquidation, etc.)

  3. Ensure Repayment: Ensure sufficient funds are available and approved for repayment:

    • Must approve at least the fee amount to each vToken contract

    • Return actual repayment amounts in the repayAmounts array

    • For partial repayment: unpaid balance becomes debt against onBehalf address

  4. Return Success: Return true to signal successful operation.

  5. Handle Reversion: If operation fails, return false or revert to unwind the entire transaction.

Critical Security Note: The entire flash loan transaction is atomic. If executeOperation returns false or reverts, the entire transaction reverts, ensuring protocol safety while allowing complex strategies to fail gracefully.

Key Events

  • TransferOutUnderlyingFlashLoan - Emitted on successful transfer of amount to receiver during flash loan initiation.

  • TransferInUnderlyingFlashLoan - Emitted on successful transfer of repayment amount from receiver to vToken.

  • FlashLoanExecuted – Emitted after a flash loan is executed successfully.

  • FlashLoanStatusChanged – Emitted when flash loan status is changed for a market.

  • IsAccountFlashLoanWhitelisted – Emitted when trying to set whitelist flashloan account.

Key Errors

  • FlashLoanNotEnabled - Thrown if flash loan is not enabled for the asset.

  • InvalidAmount - Thrown when the requested flash loan amount is zero.

  • SenderNotAuthorizedForFlashLoan - Thrown when the sender is not authorized to use flash loan.

  • NoAssetsRequested - Thrown if no assets are requested for the flash loan.

  • InvalidFlashLoanParams - Thrown if the flash loan params are invalid.

  • ExecuteFlashLoanFailed - Thrown when executeOperation on the receiver contract fails.

  • NotEnoughRepayment - Thrown if the repayment amount is less than the required total fee.

  • FailedToCreateDebtPosition - Thrown when failing to create a debt position.

  • InvalidComptroller - Thrown if the caller is not the Comptroller contract.

  • FlashLoanAlreadyActive - Thrown if a flash loan is already in progress.

  • NotAnApprovedDelegate - Thrown when the sender is not an approved delegate for the onBehalf address.

  • MarketNotListed - Thrown when trying to flash loan from a market that is not listed in the core pool.

  • InsufficientRepayment - Thrown when the actual transferred amount is less than the required total fee.

Example FlashLoan Flow: Alice's Arbitrage

User: Alice (has 10 ETH collateral on Venus)

Goal: Arbitrage 100,000 USDC between DEXs

1. Full Repayment (Successful Trade)

  1. Request: Alice's ArbitrageContract calls executeFlashLoan() requesting 100000 USDC.

  2. Transfer: Venus sends 100,000 USDC to Alice's contract + calculates fee (e.g., 90 USDC)

  3. Execution:

    • Venus calls executeOperation() on Alice's contract

    • Contract performs arbitrage (buy low, sell high)

    • Profits 100,200 USDC

    • Approves full repayment of 100,090 USDC

  4. Repayment: Venus pulls the approved 100,090 USDC

  5. Result: Alice keeps 110 USDC profit. Transaction completes.

2. Partial Repayment (Failed Trade → Debt Conversion)

  1. Request: Alice's ArbitrageContract calls executeFlashLoan() requesting 100000 USDC.

  2. Transfer: Venus sends 100,000 USDC + calculates fee (90 USDC)

  3. Execution:

    • Arbitrage fails due to slippage → only gets 99,500 USDC

    • Approves partial repayment of 99,500 USDC

  4. Debt Conversion:

    • Venus pulls 99,500 USDC

    • Shortfall detected: 590 USDC (100,090 required - 99,500 paid)

    • Converts shortfall into a borrow position against Alice's 10 ETH collateral

  5. Result: Transaction does not revert. Alice now owes 590 USDC to Venus.

3. Fee Not Paid (Critical Failure → Transaction Reverts)

  1. Request: Alice's ArbitrageContract calls executeFlashLoan() requesting 100,000 USDC.

  2. Transfer: Venus sends 100,000 USDC + calculates fee (90 USDC)

  3. Execution:

    • Arbitrage fails completely → only gets 50 USDC

    • Approves insufficient amount of 50 USDC (less than the 90 USDC fee)

  4. Validation Failure:

    • Venus attempts to pull funds but detects fee shortfall

    • Protocol requires at minimum the full flash loan fee to be repaid 5 Result: Transaction reverts completely. No debt conversion occurs. Alice loses gas fees but protocol remains secure.

Key Mechanism

  • Full Repayment: Strategy must profit enough to cover principal + fees.

  • Partial Repayment: Unique Venus feature. Requires existing collateral and atleast fees repayment.

  • Fee Not Paid: Transaction always reverts - critical safety mechanism.

  • No Collateral? Full repayment mandatory; otherwise transaction reverts.

  • Auto-Conversion: Shortfall automatically becomes secured debt, preventing liquidation.

Conclusion

Venus Protocol’s flash loan implementation provides a secure, composable, and flexible foundation for advanced DeFi strategies. It enables atomic transactions, multi-asset borrowing, and deep composability with Venus and other DeFi protocols.

Last updated