ERC-4626 Vault
Last updated
Last updated
Fuji’s vaults are pools of assets and/or debt that are managed according to a predefined strategy. A vault is an abstraction on top of money markets or yield venues that puts together users’ funds intending to optimize management efforts and maximize assets’ productivity.
A vault can consist of 1) a single asset or 2) a pair of collateral and borrow assets. The goal with the former is to seek the highest yield on users’ deposits. In the latter case, vaults can be seen as isolated debt pools meant to minimize debt costs. Users select a vault according to their goal and profile, from, and to the chain of their wish.
Fuji’s Borrowing Vault is an extension of ERC-4626. It can handle yield-bearing tokens, as well as debt-accruing ones (think of Aave’s “aTokens” and “debtTokens” combined into a single interface). For that reason, next to the standard ERC-4626 “deposit” and “withdraw” functions, we implemented “borrow” and “payback” with mirrored semantics, responsible for the debt operations.
Furthermore, ERC-4626 makes Himalaya interoperable with other protocols that also build on top of this standard which empowers users to batch and perform complex operations in a single run thanks to a Router contract.
Asset and Debt Shares
Users deposit an ERC-20 asset into the vault and in return receive the corresponding number of Asset Shares depending on the current Share Price. A share is a token receipt that represents the user’s ownership of the vault’s pooled assets. Received shares from a deposit are always in proportion to the user’s deposited assets relative to the current pool size. Accruing interest is the only operation that can change the Share Price. Because interest accrual is always positive, the number of ERC-20 assets that each Asset Share is redeemable for cannot decrease.
Example:
Alice has deposited 10 WETH as collateral, the initial Share Price was 1.00, and she received 10 receipt tokens. Since her initial deposit, the vault has accumulated 1 WETH of interest. So the Asset Amount shows 11 (10 deposited WETH + 1 WETH earned as interest). The current Share Price is 1.10 (11 WETH / 10 receipt tokens).
If Bob now deposits 10 WETH, we will see the following changes. First, the Asset Amount in the vault will increase by 10. The current Share Price for receipt tokens is 1.10. Therefore Bob will receive 90.91 (10 / 1.10) receipt tokens for his deposit.
Over time, as more interest accrues, Alice and Bob can redeem their receipt tokens for an ever-increasing amount of the underlying asset.
In a similar way, borrowing vaults issue Debt Shares for users who take out loans. A Debt Share represents the user’s debt ownership of the vault’s debt pool. In contrast with the collateral, borrowers do not receive receipts representing their debt. As long as borrowers have an open position, interest accrues and is capitalized. This means that over time the amount a borrower owes increases by an amount equal to the interest they owe. For a borrower to receive their collateral back, they must return the original loan amount plus all accrued interest.
Deployment
New vaults are getting deployed through the Chief with the help of a Factory contract. See below “Chief” and “Vault Factories” for more details.
Rebalance
Fuji vaults are a layer on top of money markets and yield venues (such as yield aggregators). The vault contains a list of providers (other protocols) between which the collateral and/or the debt can be rebalanced. At any given moment, the vault is connected to at least one underlying protocol (called the active provider) from which the liquidity gets sourced.
The yield generated by the supplied assets or the interest accrued by the owed debt, both vary over time. Depending on the vault’s type and its pre-defined strategy, the liquidity allocation can be changed. The vault gets rebalanced to ensure the most optimal cost/yield for the users’ funds.
This is done through an external contract (“RebalancerManager”) that’s pre-approved and assigned with a special role. The manager moves the vault’s collateral and debt from the current active provider to another one that’s contained in the list of providers. In the case of a borrowing vault, the manager uses a flashloan to accomplish the debt migration.
Harvest
Some protocols distribute rewards in their own tokens in what’s called a liquidity mining program. When a Fuji vault is eligible for such rewards, it collects them on a regular basis. Depending on the vault’s pre-defined strategy, the received tokens can be swapped to partially repay the debt of all users or to increase the share price of the deposited collateral. (This functionality is yet to be implemented).
Liquidations
Specific to borrowing vaults only, there is the need to liquidate users when the value of the collateral falls below a specific threshold with respect to the size of their debt.
To determine if a debt position is due for liquidation we compute the user’s health factor. The health factor is defined below:
Due to the limitations of decimal number usage in Solidity, the health factor is scaled up by 1e18. This means that a position with a health factor below 1e18 is considered “unhealthy” and is due to liquidation.
Fuji V2 implements what’s called a “soft-liquidation” process. This means that if a user’s health factor is between 1e18 (1) and 0.95e18 (0.95) (not too risky), only 50% of the user’s debt position can be liquidated. Otherwise, if the health factor is equal to or less than 0.95e18 (0.95), a full liquidation is possible. To control this possibility during a liquidation, we introduce the close factor. The close factor is defined as:
To perform a liquidation, a liquidator has to repay the amount of the required debt. In exchange for their service, the liquidator receives asset shares from the user being liquidated.
The benefit of the liquidator is that the asset shares are sold to them at a discounted price. As default, we have determined this discounted price to be 90% of the oracle price at the time of liquidation. Said in other words, the liquidated user is being penalized by a 10% discount in price for their asset shares.
There could be cases in which a liquidation is not profitable. Such cases are when the value of the collateral and the discount price result in an amount of asset shares that the liquidated user does not own. In these situations, the maximum amount of asset shares the liquidator user will receive is equal to the amount of shares the liquidated user has.
It is important that a liquidator simulates any liquidation transaction before executing it.
To avoid MEV of the liquidation opportunities (front-running), Fuji V2 implements a system of allowed liquidators.
Allowances and Permits
To allow for assets and debt to be moved on behalf of a user, without requiring the user to be the function caller, the vault implements an allowance mechanism for both assets and debt. This allowance mechanism is already part of ERC-4626, but in the context of a borrowing vault, it is extended for debt.
In addition, permit functions have been defined that allow a user to sign a message that can later be used to either withdraw or borrow on behalf of the signer. These permit functions follow EIP-712 and are inspired by ERC-2612.
Users can interact directly with the vault contract; however, it is recommended they use a router to simplify combo transactions, and save gas.
