Vault Module
High Level Overview
Vault module is a core component that manages the collateral backing the stablecoin, ensuring its stability and value.
Collateral Management:
The vault module securely holds the collateral assets (e.g., cryptocurrencies, fiat tokens) that back the stablecoin
It tracks the value of these assets and ensures they meet or exceed the required thresholds to maintain the stablecoin’s peg.
It manages user debt by time
User Interaction
Users deposit collateral into the vault module to mint new stablecoins and create new vaults
To redeem their collateral, users burn (destroy) the stablecoins they previously minted, and the vault releases the corresponding collateral.
Users can transfer ownership of their vaults
Liquidation Mechanism:
If the collateral value drops below a critical threshold, the vault may trigger an automated liquidation, selling off the collateral to maintain system stability.
Detailed Design
Objects
Vault Factory: The VaultFactory's purpose is to make it possible for users to deposit valuable tokens and mint $oUSD. They will pay interest on the total outstanding balance, and have to pay off the debt or deposit additional collateral to ensure that the ratio of debt to collateral stays above a threshold.
Vault Manager: Calculates user debt and tracks if the vault should be liquidated by a period of time.
Vault: A record present user debt, collateral asset locked.
Params
Minting fee: Fee that user have to pay when create new vault or mint more stable tokens.
Stability Fee: Fee charged for maintaining an open Vault. Expressed as an annual percentage but charged more frequently.
Liquidation Penalty: Penalty charged if vault is liquidated.
Minimum liquidation threshold: If collateral ratio at this time is below threshold, the vault is liquidated.
Minimum Initial Debt: New vault must mint at least this minimum amount of debt.
Max Debt Limit: Max debt of a collateral type.
Flows
Active Collateral Asset
In order for users to deposit a type of collateral to mint stablecoins, we first need to activate that type of asset with a proposal. After voting, the Vault Manager will add the asset to the tracking list.
Create Vault
After a collateral type was activated, users can create new vaults by depositing collateral assets. Assets deposited will be locked by the Vault Factory. From assets amount & price at that time, $oUSD minted to users should be calculated. In addition, fees will also be minted based on the minting fee and transferred to the Reserve.
Create vault record with user debt:
There some cases that debt less than Minimum Initial Debt or total debt of asset greater than Max Debt Limit, vault will not be created.
User Interacts with Vault: After creating vault, user can interact with their vaults.
Deposit More Collateral Assets
User can deposit more collateral assets to increase the vault collateral ratio. This action will not effect to debt. Note: No limit on asset deposits.
Withdraw Collateral Assets
User can withdraw their locked collateral assets. It will decrease the collateral ratio of vault. If new ratio is below min ratio, an error is returned. This action will not effect the debt.
Mint more $oUSD
User can mint more $oUSD. It will increase debt and decrease collateral ratio. If the ratio is below the min ratio, an error is returned. A minting fee will be charged on the newly minted $oUSD amount and added to your overall debt.
Repay $oUSD
User can repay $oUSD to guard their vault from liquidation by reduce debt and increase collateral ratio.
Transfer Vault Ownership
Manage Debt by Period
Every given period, Vault Manager will recalculate the debt of all vaults based on current debt and stability fees (compound):
Liquidation
Every given period, Vault Manager (inside Vault Factory) will check if any vault should be liquidated. If so, all collateral assets of the vault are transferred to the auction module. Should we have a successful bid, remaining collateral assets are returned.
The amount will be transferred to the vault module then the module will handle it internally.
There are two cases below:
Auction raises enough $oUSD to cover debt
The following steps occur in this order
$oUSD raised by the auction is burned to reduce debt in 1:1 ratio.
From any remaining collateral, the liquidation penalty is taken and transferred to the reserve.
Excess collateral - if any - is returned to vault holders
Auction does not raise enough to cover $oUSD debt
This flow further bifurcates based on whether the auction has sold all its collateral asset and still has not covered the debt or has collateral remaining (which simply did not receive bidders)
All collateral is sold and the debt is not covered
$oUSD raised by the auction is burned to reduce debt in 1:1 ratio.
Remaining debt is recorded in the reserve as a shortfall
Collateral remains but debt is still not covered by $NOM raised by the end of the auction
$NOM raised by the auction is burned to reduce debt in 1:1 ratio.
From any remaining collateral, the liquidation penalty is taken and transferred to the Reserve.
The vault manager now iterates through the vaults that were liquidated and attempts to reconstitute them (minus collateral from the liquidation penalty) starting from the best collateral ratio to worst.
When the vault manager reaches a vault it cannot fully reconstitute (both full debt and collateral as described above), it marks that vault as liquidated. It then marks all other lower CR vaults as liquidated.
Any remaining collateral is transferred to the Reserve.
Any remaining debt is transferred to the reserve as shortfall.
Last updated
