## Understanding the Funding Fee Vault Architecture This lesson explores the architecture of a system designed to generate yield by collecting funding fees from a perpetual futures exchange, specifically GMX. The system utilizes user-deposited Wrapped Ether (WETH) which is strategically deployed into a short position on GMX under the management of an Admin. Users interact primarily with a Vault contract for deposits and withdrawals, while the underlying investment logic is handled by a separate Strategy contract. ## Core Components and Interactions The architecture relies on several distinct components working together. Understanding the role and interactions of each is crucial. **The User** Users are the depositors providing capital to the system. Their interaction is focused on the `Vault` contract. * **`deposit`:** Users send WETH to the `Vault` contract to participate in the yield strategy. * **`withdraw`:** Users request their WETH back from the `Vault`. If the withdrawal requires interacting with the GMX protocol (i.e., closing part of the position), the user must include an execution fee (`exec fee`) with their request. * **`cancel`:** Users can cancel a pending withdrawal request, likely before it triggers an interaction with GMX. * **Receipts:** Upon successful withdrawal, users receive WETH. If an execution fee was paid for a GMX interaction, any refunded portion (`exec fee refund`) is sent back to the user via the `WithdrawCallback` contract. **The Vault Contract** This contract serves as the primary interface for users and holds the main pool of deposited WETH. * **Fund Management:** Receives WETH deposits from users and holds liquid WETH. * **Withdrawal Processing:** Handles user withdrawal requests. * If sufficient WETH is available within the Vault itself, it sends the WETH directly back to the User. * If funds must be retrieved from the GMX position, the Vault forwards the withdrawal request and the user-provided `exec fee` to the `Strategy` contract. * **State Management:** Stores data related to pending user withdrawal orders. * **Admin Interaction:** Allows the `Admin` to `transfer` WETH from the Vault to the `Strategy` for deployment. It also receives WETH transferred back from the `Strategy` (initiated by the Admin). * **Callback Interaction:** Interacts with the `WithdrawCallback` contract to `remove withdraw order` data once a withdrawal involving GMX is successfully processed. * **Control:** Managed by an `Admin`. **The Strategy Contract** This contract encapsulates the logic for interacting with GMX and managing the investment strategy (the short position). * **Fund Deployment:** Receives WETH from the `Vault` (via Admin transfer) to be deployed into the GMX strategy. Holds WETH actively deployed or awaiting deployment. * **GMX Interaction:** * `create orders`: Initiated by the `Admin` to establish, increase, or decrease the size of the short position on GMX. Requires an execution fee. * `claim funding fees`: Claims accumulated funding fees from the GMX short position. This function is typically public, allowing anyone to trigger it to ensure regular fee collection. * **Withdrawal Handling:** Receives withdrawal requests forwarded from the `Vault` when the Vault lacks sufficient liquid WETH. It translates these requests into `decrease` orders sent to GMX. * **Admin Commands:** Executes commands from the `Admin`: * `increase + exec fee`: Increases GMX position size. * `decrease + exec fee`: Decreases GMX position size. * `cancel`: Cancels pending GMX orders. * `claim`: Initiates funding fee collection (can also be called publicly). * **Fund Return:** Sends WETH back to the `Vault` upon Admin instruction. * **Fee Handling:** Receives execution fee refunds (`exec fee refund`) from GMX for Admin-initiated orders that are executed or cancelled. * **Control:** Managed by an `Admin`. **The Admin** A privileged address or entity responsible for overseeing the strategy and fund movements. * **Responsibilities:** * Transfers WETH between the `Vault` and `Strategy` contracts. * Manages the GMX position size by calling `increase`, `decrease`, and `cancel` functions on the `Strategy` contract, paying the necessary `exec fees`. * Can initiate funding fee claims via the `Strategy` contract's `claim` function. * **Assumptions:** The system assumes the `Admin` possesses sufficient trading expertise to manage the short position effectively, balancing potential gains from funding fees against market risks and borrowing costs, thereby safeguarding user funds. **The WithdrawCallback Contract** This intermediary contract manages asynchronous responses (callbacks) from GMX, particularly for withdrawals that necessitate decreasing the GMX position. * **Callback Handling:** Receives `execute order callback` and `cancel order callback` notifications from GMX, triggered by orders initiated via the `Strategy`. * **Fund Routing (Withdrawals):** Receives the WETH withdrawn from GMX resulting from a user-initiated `decrease` order. It also receives the associated `exec fee refund` from GMX. * **State Update:** Calls the `remove withdraw order` function on the `Vault` to clear the record of the completed withdrawal request. * **User Payout:** Sends the withdrawn WETH and any `exec fee refund` directly to the User who initiated the withdrawal. **GMX Protocol** The external decentralized perpetual exchange where the yield strategy is executed. * **Order Execution:** Receives `create orders` (increase/decrease position) and `claim funding fees` requests from the `Strategy` contract. Executes or cancels these orders based on market conditions and protocol rules. * **Callbacks & Funds:** * Sends callbacks (`execute order callback`, `cancel order callback`) to the `WithdrawCallback` contract after processing orders related to user withdrawals. * Sends claimed funding fees to the `Strategy` contract. * Sends withdrawn WETH (from decrease orders for user withdrawals) to the `WithdrawCallback` contract. * Sends execution fee refunds (`exec fee refund`) back to the appropriate contract: `Strategy` for Admin-initiated orders, or `WithdrawCallback` for user withdrawal-related orders. ## Key Architectural Principles This design incorporates several important web3 architectural patterns and concepts: * **Vault/Strategy Pattern:** This pattern promotes separation of concerns. The `Vault` focuses solely on user fund management (deposits, withdrawals, accounting), while the `Strategy` encapsulates the complex logic of interacting with the external protocol (GMX) and executing the specific investment approach. * **Admin-Controlled System:** The architecture relies on a centralized `Admin` role for critical functions like fund allocation and strategy management (position sizing). This introduces an element of trust in the Admin's capabilities and intentions. * **Handling Asynchronous Operations:** Interactions with external protocols like GMX are often asynchronous. Order creation doesn't guarantee immediate execution. The use of execution fees (`exec fee`) to initiate GMX actions and a dedicated `WithdrawCallback` contract to handle responses from GMX demonstrates a robust mechanism for managing this asynchronicity. * **Yield Generation Mechanism:** The core purpose is yield generation through the collection of funding fees earned by maintaining a short position on GMX, as managed by the `Strategy` contract. ## The Withdrawal Flow The system handles user withdrawals through two distinct paths, depending on the Vault's liquidity: 1. **Direct Withdrawal (Sufficient Vault Liquidity):** If the `Vault` contract holds enough liquid WETH to fulfill a user's withdrawal request, it directly transfers the WETH to the user without needing to interact with the `Strategy` or GMX. 2. **Indirect Withdrawal (Insufficient Vault Liquidity):** If the `Vault` lacks sufficient WETH, the withdrawal requires retrieving funds from the GMX position. * The User initiates `withdraw` on the `Vault`, providing the required `exec fee`. * The `Vault` forwards the request and fee to the `Strategy`. * The `Strategy` creates a `decrease` position order on GMX. * GMX processes the order asynchronously. * Upon execution (or cancellation), GMX sends a callback, the withdrawn WETH (if any), and the `exec fee refund` to the `WithdrawCallback` contract. * The `WithdrawCallback` contract sends the withdrawn WETH and refund to the original User. * The `WithdrawCallback` contract notifies the `Vault` to remove the pending withdrawal order record. ## Managing Fees The architecture explicitly accounts for different types of fees: * **Execution Fees:** Interactions with GMX (like creating or cancelling orders initiated by the Admin or required for user withdrawals) incur gas costs and potentially protocol fees. These are covered by an `exec fee`, provided either by the Admin (for position management) or the User (for withdrawals needing GMX interaction). GMX refunds unused portions of this fee (`exec fee refund`), which are routed back to the `Strategy` or the `WithdrawCallback` (and subsequently the User). * **Funding Fees:** These are the primary source of yield for the vault. They are periodically collected from GMX by calling the `claim` function on the `Strategy` contract. The Admin must strategically manage the GMX position, considering both the potential funding fees to be earned and any borrowing fees associated with maintaining the short position.