[VEN-2985] : Technical Documentation of Flashloan

technical-reference/reference-core-pool/comptroller/diamond/facets/policy-facet.md

@@ -341,3 +341,38 @@ function _setVenusSpeeds(contract VToken[] vTokens, uint256[] supplySpeeds, uint
 
 - - -
 
+### executeFlashLoan
+
+The executeFlashLoan function facilitates a flash loan — a type of uncollateralized loan where assets are borrowed and repaid within the same transaction block. It is commonly used in DeFi for arbitrage, refinancing, liquidations, and other advanced operations.
+
+```solidity
+function executeFlashLoan(
+    address payable initiator,
+    address payable receiver,
+    VToken[] calldata vTokens,
+    uint256[] calldata underlyingAmounts,
+    uint256[] calldata modes,
+    address onBehalfOf,
+    bytes calldata param
+) external 
+```
+
+#### Parameters
+| Name              | Type                |Description                                                      |
+|-------------------|---------------------------------------------------------------------------------------|
+| initiator         | address payable     | The address initiating the flashloan                            |
+| receiver          | address payable     | The contract receiving theassets                                |
+| vTokens           | VToken[] calldata   | Array of vToken markets to borrowfrom                           |
+| underlyingAmounts | uint256[] calldata  | Amounts of each asset toborrow                                  |
+| modes             | uint256[] calldata  | Repayment modes (0: Classic, 1: DebtPosition)                   |
+| onBehalfOf        | address             | Address for which the loan is executed (fordelegation)          |
+| param             | bytes calldata      | Arbitrary data for customlogic                                  |
+
+#### Return Values
+| Name | Type | Description |
+|------|------|-------------|
+| None |      |             |
+
+---
+
+

technical-reference/reference-core-pool/comptroller/diamond/facets/setter-facet.md

@@ -365,3 +365,45 @@ function _setForcedLiquidationForUser(address borrower, address vTokenBorrowed,
 
 - - -
 
+#### setWhiteListFlashLoanAccount
+
+```solidity
+function setWhiteListFlashLoanAccount(address account, bool _isWhiteListed) external 
+```
+**Explanation:**  
+Allows an admin or governance role to whitelist or revoke access for specific accounts to initiate flash loans.
+
+#### Parameters
+| Name        | Type    | Description                                 |
+|-------------|---------|---------------------------------------------|
+| account     | address | The account to whitelist or remove          |
+| _isWhiteListed | bool | True to whitelist, false to remove          |
+
+#### Return Values
+| Name | Type | Description |
+|------|------|-------------|
+| None |      |             |
+
+---
+
+#### setDelegateAuthorizationFlashloan
+
+```solidity
+function setDelegateAuthorizationFlashloan(address market, address delegate, bool approved) external 
+```
+
+#### Parameters
+| Name     | Type    | Description                                 |
+|----------|---------|---------------------------------------------|
+| market   | address | The market for which to set delegation      |
+| delegate | address | The delegate account                        |
+| approved | bool    | True to approve, false to revoke            |
+
+#### Return Values
+| Name | Type | Description |
+|------|------|-------------|
+| None |      |             |
+
+---
+
+

technical-reference/reference-core-pool/vtoken.md

@@ -572,3 +572,90 @@ function borrowBalanceStored(address account) public view returns (uint256)
 | [0]  | uint256 | The calculated balance |
 
 ---
+
+### transferOutUnderlying
+
+```solidity
+function transferOutUnderlying(address receiver, uint256 amount)
+    external
+    returns (uint256);
+```
+
+#### Parameters
+| Name     | Type    |Description                                 |
+|----------|------------------------------------------------------|
+| receiver | address | The address toreceive the underlying asset |
+| amount   | uint256 | The amount of theunderlying asset to send  |
+
+#### Return Values
+| Name | Type    |Description                                 |
+|------|------------------------------------------------------|
+| [0]  | uint256 | The actual amounttransferred               |
+
+---
+
+### calculateFlashLoanFee
+
+```solidity
+function calculateFlashLoanFee(uint256 amount)
+    public
+    view
+    returns (uint256 protocolFee, uint256 supplierFee);
+```   
+#### Parameters
+| Name   | Type    | Description                          |
+|--------|---------|--------------------------------------|
+| amount | uint256 | The amount for which to calculate fee|
+
+#### Return Values
+| Name          | Type     | Description                                 |
+|---------------|----------|---------------------------------------------|
+| protocolFee   | uint256  | The protocol fee for the flash loan         |
+| supplierFee   | uint256  | The supplier fee for the flash loan         |
+
+---
+
+### _toggleFlashLoan
+
+```solidity
+function _toggleFlashLoan()
+    external
+    returns (uint256);
+```   
+
+#### Parameters
+| Name | Type | Description |
+|------|------|-------------|
+| None |      |             |
+
+#### Return Values
+| Name | Type    | Description                                 |
+|------|---------|---------------------------------------------|
+| [0]  | uint256 | Status code (e.g., success/failure)         |
+
+---
+
+### _setFlashLoanFeeMantissa
+
+```solidity
+function _setFlashLoanFeeMantissa(
+    uint256 protocolFeeMantissa_,
+    uint256 supplierFeeMantissa_
+)
+    external
+    returns (uint256);
+```
+
+#### Parameters
+| Name                  | Type    | Description                                 |
+|-----------------------|---------|---------------------------------------------|
+| protocolFeeMantissa_  | uint256 | New protocol fee mantissa                   |
+| supplierFeeMantissa_  | uint256 | New supplier fee mantissa                   |
+
+#### Return Values
+| Name | Type    | Description                                 |
+|------|---------|---------------------------------------------|
+| [0]  | uint256 | Status code (e.g., success/failure)         |
+
+---
+

technical-reference/reference-technical-articles/flashloan-core-pool.md

@@ -0,0 +1,223 @@
+# Venus Protocol's FlashLoan Implementation
+
+## Overview
+
+Venus Protocol introduces **native multi-asset flash loans** in its **core-pool**, enabling advanced DeFi strategies such as **arbitrage, liquidation, and composable leverage**. 
+The flash loan system is designed for **security, flexibility, and seamless integration** with Venus’s vToken markets.
+
+### Key Benefits
+
+- **Multi-Asset Support** – Borrow multiple assets in a single transaction.
+- **Flexible Repayment Modes** – Classic (full repayment) and Debt Position (partial repayment becomes borrow).
+- **Permissioned Delegation** – Flash loans can be executed on behalf of other users with explicit authorization.
+- **Integrated Fee Routing** – Protocol and supplier fees are distributed to the correct recipients, including the **Protocol Share Reserve (PSR)**.
+- **Upgradeable & Secure** – Built with diamond facets for upgradeability and access-controlled by governance.
+
+---
+
+## Understanding Flash Loans
+
+A flash loan allows users to borrow assets **without collateral**, provided the loan is repaid **within the same transaction**.  
+If not repaid, the transaction **reverts**.
+
+Venus extends this model by allowing **debt positions**: if a user cannot fully repay, the unpaid amount automatically becomes a borrow against their account.
+
+---
+
+## Core Smart Contracts
+
+### **1. PolicyFacet.sol – FlashLoan Execution & Validation**
+
+Handles core flash loan operations including:
+- Asset transfers
+- Fee calculations
+- Repayment logic
+- Event emissions
+
+#### Key Function
+
+```solidity
+function executeFlashLoan(
+    address payable initiator,
+    address payable receiver,
+    VToken[] calldata vTokens,
+    uint256[] calldata underlyingAmounts,
+    uint256[] calldata modes,
+    address onBehalfOf,
+    bytes calldata param
+) external {
+    // Validation, asset transfer, fee calculation, repayment logic...
+}
+```
+**Explanation:**  
+This is the primary entry point for initiating a flash loan. It orchestrates the entire process: validating the request, transferring funds, executing the user's logic, ensuring repayment, and handling fees. The function is designed to be atomic; if any step fails (e.g., insufficient repayment), the entire transaction reverts, ensuring the protocol's safety.
+
+### Step-by-Step Workflow:
+1. **Validation**
+   * it ensures the `initiator` is either the transaction sender (`msg.sender`) or a whitelisted account authorized to perform flash loans on behalf of others.
+   * it checks that the arrays `vTokens`, `underlyingAmounts`, and `modes` are of the same length to prevent mismatches.
+   * It verifies that the onBehalfOf parameter has explicitly delegated flash loan permissions to the initiator for each market involved, unless the initiator is acting on their own behalf.
+   * Received wrapped native tokens are unwrapped to obtain native currency.
+   * Native currency is transferred to the user.
+2. **Pre-Transaction Accounting**
+   * For each vToken market, it calculates the protocol and supplier fees based on the borrowed amount. It then records the protocol's total fee balance before the transfer. This snapshot is crucial for later verification.
+3. **Asset Transfer**
+   * The function calls `transferOutUnderlying` on each vToken contract. This instructs the vToken to send the requested amount of the underlying asset (e.g., USDT, BUSD) to the `receiver` contract. This is where the user's capital to execute their strategy comes from.
+4. **User Logic Execution**
+   * The function calls the `executeOperation` function on the `receiver` contract. This is a callback function that must be implemented by any contract that wishes to receive a flash loan. The `param` data is passed to this function, allowing the user to encode any custom logic (e.g., arbitrage routes, liquidation targets). This is where the user's complex DeFi strategy is executed.
+5. **Repayment & Post-Transaction Accounting**
+   * After the user's logic completes, the function checks the repayment:
+     * For each asset, it calculates the total amount that must be returned to the vToken. This is the sum of the original borrowed amount and the calculated fees.
+     * It checks the vToken contract's balance to see if the required amount has been repaid. The repayment could happen inside the user's `executeOperation` or via a separate transfer approved by the user.
+     * Based on the mode selected for each asset:
+       * `Mode 0 (Classic)`: The full amount (principal + fees) must be present in the vToken contract. If it is not, the transaction reverts.
+       * `Mode 1 (Debt Position)`: The function checks how much of the principal + fees was repaid. Any shortfall is automatically converted into a regular borrow position for the `onBehalfOf` address. This requires that the address has sufficient collateral to cover this new debt, otherwise the transaction will revert.
+6. **Fee Distribution**
+   * Finally, the collected protocol fees are automatically routed to the Protocol Share Reserve (PSR), and the supplier fees are distributed to the liquidity providers in the respective vToken market.
+
+**Critical Security Feature**: The entire function is typically wrapped in a nonReentrant modifier, which prevents any reentrancy attacks that could be launched from within the user's executeOperation callback.
+
+---
+
+### **2. SetterFacet.sol - Setter Functions For Flashloan
+
+This file contains administrative functions to manage flash loan permissions.
+
+#### **Functions**
+
+#### `setWhiteListFlashLoanAccount`
+```solidity
+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 to explicitly grant or revoke permission for a specific Ethereum 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.
+
+#### `setDelegateAuthorizationFlashloan`
+```solidity
+function setDelegateAuthorizationFlashloan(address market, address delegate, bool approved) external 
+```
+**Explanation:**  
+This function enables a powerful feature: flash loan delegation. It allows a user (`msg.sender`) to grant a third-party contract or service (the `delegate`) permission to take out flash loans on their behalf (`onBehalfOf` would be the user's address).
+
+ * **Use Case** : A user might want to use a sophisticated liquidation bot but doesn't want to give the bot their private keys. Instead, they can delegate flash loan authority to the bot's contract for specific market(s). The bot can then perform liquidations using the user's collateralized assets to back the flash loan debt (in Mode 1), without ever having direct control over the user's funds.
+ * **Parameters** : The authorization is granular, set per market (vToken address). A user can authorize a delegate for one market but not another.
+ * **Security** : The function emits an event (DelegateAuthorizationFlashloanChanged) that allows users and off-chain services to track delegation changes transparently.
+
+---
+
+### **3. VToken.sol – Asset Transfer & Fee Calculation**
+
+Manages the underlying asset transfers, flash loan fee calculations, and creation of debt positions.
+
+#### Key Functions
+
+```solidity
+function transferOutUnderlying(address receiver, uint256 amount)
+    external
+    returns (uint256);
+```
+**Explanation:** 
+This function is the workhorse for moving assets. When PolicyFacet.sol calls this during a flash loan, it performs two main actions:
+
+ 1. **Balance Check** : It ensures the vToken contract holds at least the requested `amount` of the underlying asset (e.g., the actual BUSD in the contract).
+ 2. **Asset Transfer** : It performs the low-level `transfer` call to send the underlying asset to the `receiver` address. It returns the actual amount transferred, which should equal the requested amount unless there's a miscalculation or a fee-on-transfer mechanism (which most underlying assets in Venus do not have).
+
+```solidity
+function calculateFlashLoanFee(uint256 amount)
+    public
+    view
+    returns (uint256 protocolFee, uint256 supplierFee);
+```   
+**Explanation:** 
+This is a view function (it doesn't change the blockchain state) that calculates the cost of a flash loan. It takes the requested amount and multiplies it by two stored fee rates:
+
+ 1. **protocolFeeMantissa** : A fraction (e.g., 0.0009 for 0.09%) representing the fee that goes to the Venus protocol treasury (PSR).
+ 2. **supplierFeeMantissa** : A fraction representing the fee that is distributed to the users who supplied liquidity to this specific vToken market. The sum of these two fees is the total cost of the flash loan. This function allows users to simulate the cost of a loan before executing it.
+
+```solidity
+function _toggleFlashLoan()
+    external
+    returns (uint256);
+```   
+**Explanation:**  
+An emergency or administrative function that allows the protocol admin to instantly enable or disable flash loan functionality for a specific vToken market. This would be used in a scenario where a vulnerability is suspected in a particular asset's market or in the flash loan mechanism itself. Toggling it off would halt all flash loan activity for that market while the issue is investigated.
+
+```solidity
+function _setFlashLoanFeeMantissa(
+    uint256 protocolFeeMantissa_,
+    uint256 supplierFeeMantissa_
+)
+    external
+    returns (uint256);
+```
+**Explanation:** 
+This is a critical administrative setter function that allows governance to configure the fee structure for flash loans for this specific vToken market. It updates the two key parameters that determine the cost of borrowing assets via a flash loan: the protocol fee and the supplier fee.
+
+ 1. **Protocol Fee (protocolFeeMantissa_)** : This is the fee paid to the Venus Protocol treasury (the Protocol Share Reserve or PSR). It is a revenue mechanism for the protocol itself.
+ 2. **Supplier Fee (supplierFeeMantissa_)** : This is the fee paid to the liquidity providers who have supplied assets to this vToken market. It serves as an incentive for users to provide liquidity.
+
+---
+
+### **4. FlashLoanReceiverBase.sol – Receiver Base**
+
+This is not a contract that holds funds but an abstract contract or interface that defines a standard which any flash loan receiver contract must follow.
+
+It mandates the presence of a function named `executeOperation`. This function is the callback target that `PolicyFacet.sol` calls in step 4 of the flash loan process.
+
+A typical `executeOperation` function must:
+  1. **Receive the Assets** : Acknowledge that it has received the flash loaned assets.
+  2. **Execute Strategy** : Perform its intended operations (e.g., arbitrage, liquidation).
+  3. **Approve Repayment** : Ensure that the vToken contract is approved to pull back the full amount (principal + fees) from the receiver contract's balance.
+  4. **Return true** : Signal to the `PolicyFacet` that the operation was successful. If it returns `false` or throws an error, the entire flash loan transaction reverts.
+
+---
+
+## Events
+
+- **`FlashLoanExecuted`** – Emitted after a flash loan is executed.
+- **`FlashLoanFeePaid`** – Emitted when fees are distributed.
+- **`DebtPositionCreated`** – Emitted when unpaid amounts are converted to debt.
+- **`IsAccountFlashLoanWhitelisted`** – Emitted when trying to set whitelist flashloan account.
+- **`DelegateAuthorizationFlashloanChanged`** – Emitted when delegate authorization for flash loans is changed
+
+---
+
+## Security Features
+
+### **1. Access Control**
+- Delegation is **ACM-protected** to prevent unauthorized flash loans.
+
+### **2. Input Validation**
+- Non-zero address checks.
+- Array length validation for consistency.
+
+### **3. Attack Surface Mitigation**
+| Threat Vector | Mitigation |
+|---------------|------------|
+| Reentrancy | `nonReentrant` modifiers |
+| Unauthorized Delegation | Access Control Manager checks |
+| Fee Misrouting | Explicit fee routing logic |
+| Upgrade Risks | Governance-controlled diamond upgrades |
+
+---
+
+## Example FlashLoan Flow
+
+**Scenario**: Alice requests a flash loan of **USDT using **Mode 0 (Classic Flashloan)** and BUSD**, using **Mode 1 (Debt Position)** for BUSD.
+
+1. Alice receives **both assets**.  
+2. Repays **USDT in full** (Mode 0).  
+3. Remaining **BUSD becomes a borrow** (Mode 1).  
+4. Fees are routed correctly to PSR and vToken contracts.
+
+---
+
+## 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.