🏦VaultManager - Borrowing AgTokens

Angle's Borrowing Module User-Facing Contract

Contract Name: VaultManager
Contract Source: https://github.com/AngleProtocol/borrow-contracts/tree/main/contracts/vaultManager

1. Introduction

The VaultManager contract is the main contract of Angle Borrowing Module. It is one of the only user-facing contracts. This contract allows people to deposit collateral and open up loans of a given AgToken. It handles all the loan logic (fees and interest rate) as well as the liquidation logic.

There is one VaultManager contract per collateral type for a given stablecoin. You may have for instance two different VaultManager contract for ETH as a collateral, with for instance two different set of parameters.

This contract is also a standard NFT contract on the ERC721MetadataUpgradeable standard. Vaults (name of the tokens in this contract) are non fungible, but they can be transferred from one address to another, you can also approve another address to interact with you vault or simply check the number of vaults you own.

2. Contract Details

Interfaces

Implements IERC721MetadataUpgradeable, IVaultManager, ReentrancyGuardUpgradeable and Initializable. This contract is upgradeable. This contract implements a version of ERC721Permit which allows to grant allowance to an address for an ensemble of vautlts through a permit signature.

References

treasury: Reference to the Treasury contract associated to this VaultManager
collateral: Reference to the collateral handled by this VaultManager
stablecoin: Stablecoin handled by this contract. Another VaultManager contract could have the same rights as this VaultManager on the stablecoin contract
oracle: Oracle contract to get access to the price of the collateral with respect to the stablecoin
veBoostProxy: Reference to the contract which computes adjusted veANGLE balances for liquidators boosts

Parameters

dust: Minimum amount of debt a vault can have
_dustCollateral: Minimum amount of collateral (in stablecoin value) that can be left in a vault during a liquidation where the health factor function is decreasing
debtCeiling: Maximum amount of stablecoins that can be issued with this contract
xLiquidationBoost, yLiquidationBoost: Threshold veANGLE balance values and value of the boost for liquidators at these threshold values: the length of these arrays should be 2
collateralFactor: Encodes the maximum ratio stablecoin/collateral a vault can have before being liquidated. It's what determines the minimum collateral ratio of a position
targetHealthFactor: Maximum Health factor at which a vault can end up after a liquidation (unless it's fully liquidated)
borrowFee: Upfront fee taken when borrowing stablecoins
repayFee: Fee taken when repaying a stablecoin debt
interestRate: Per second interest taken to borrowers taking agToken loans
liquidationSurcharge: Fee taken by the protocol during a liquidation. Technically, this value is not the fee per se, it's 1 - fee. For instance for a 2% fee, liquidationSurcharge should be 98%.
maxLiquidationDiscount: Maximum discount given to liquidators
whitelistingActivated: Whether whitelisting is required to own a vault or not
paused: Whether the contract is paused or not

Variables

lastInterestAccumulatorUpdated: Timestamp at which the interestAccumulator was updated
interestAccumulator: Keeps track of the interest that should accrue to the protocol. The stored value is not necessarily the true value: this one is recomputed every time an action takes place within the protocol.
totalNormalizedDebt: Total normalized amount of stablecoins borrowed
surplus: Surplus accumulated by the contract: surplus is always in stablecoins, and is then reset when the value is communicated to the treasury contract
badDebt: Bad debt made from liquidated vaults which ended up having no collateral and a positive amount of stablecoins

Mappings

vaultData: Maps a vaultID to its data (namely collateral amount and normalized debt)
isWhitelisted: Maps an address to whether it's whitelisted and can open or own a vault

ERC721 Data

This contract has all the mappings and data associated to ERC721 Contracts. Most of them are internal variables which are not accessible externally (like _vaultApprovals, _owners, _balances or _operatorApprovals). The only publicly available is the vaultIDCount which is a counter to generate a unique vaultID for each vault: vaultID acts as tokenID in basic ERC721 contracts.

There is also a _nonces mapping to used to check permit signatures to the contract.

Access Control

Like in all contracts of this Borrowing Module, restricted functions are checked upon calling the Treasury contract which then calls its associated CoreBorrow contract.

3. Key Mechanisms & Concepts

EIP721 Methods

All standard EIP721 methods are implemented, such as balanceOf(), ownerOf(), approve(), transferFrom, etc.

The implementation of these methods is derived from OpenZeppelin's library.

A getControlledVaults function was also added. It allows to check all the vaults controlled by an address. This is an expensive function that should never be called on-chain as it iterates over all vaultIDs. It is here to reduce dependency on an external graph to link a vaultID ID to its owner.

permit

Beyond these base methods, the contract includes a permit method to grant (or revoke) approval to an address for all the associated vaults of the contract.

    function permit(
        address owner,
        address spender,
        bool approved,
        uint256 deadline,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) external

Parameters:

owner: Address which signed the message
spender: Address to grant or revoke allowance to
approved: Whether to grant or revoke allowance
deadline: Timestamp till which the signature is valid
v, r, s: Signature data

Examples of how to sign can be found in the open-source borrow-contracts repo.

Main Vault Interaction Methods

Everything in the VaultManager contract was designed to be composable in a single transaction: this can be done with the angle() functions.

There are two different versions of the function, performing in the end the same actions.

    function angle(
        ActionType[] memory actions,
        bytes[] memory datas,
        address from,
        address to,
        address who,
        bytes memory repayData
    ) external payable returns (PaymentData memory paymentData);

And:

    function angle(
        ActionType[] memory actions,
        bytes[] memory datas,
        address from,
        address to
    ) external payable returns (PaymentData memory paymentData);

These functions allow composability between calls to the different entry points of this module. Any user calling this function can perform any of the allowed actions in the order of their choice.

This function is optimized to reduce gas cost due to payment from or to the user and that expensive calls or computations (like oracleValue) are done only once

Parameters:

actions: Set of actions to perform. Each action corresponds to a different integer.
datas: Array of data to be decoded for each action. Each item in this array is the abi-encoded version of different parameters for each version: parameters can include like the vaultID or the stablecoinAmount to borrow for instance. Each action expects particular data to be given (more detail below). The datas array should have the same length as the actions array.
from: Address from which stablecoins will be taken if one action includes burning stablecoins. This address should either be the msg.sender or be approved by the latter
to: Address to which stablecoins and/or collateral will be sent in case of

The following parameters are optional and can be avoided if you are using the second version of the function. For about how to use these parameters correctly, you can look at this guide we have built on auto-leverage and capital-efficiency within Angle Borrowing Module.

who: Address of the contract to handle in case of repayment of stablecoins from received collateral
repayData: Data to pass to the repayment contract in case of

Return Value:

paymentData: Struct containing the final transfers executed. This struct contains four different fields (named from the protocol's perspective):
- stablecoinAmountToGive: Stablecoin amount the contract has given to the to address
- stablecoinAmountToReceive: Stablecoin amount taken from the from address to be burnt by the contract
- collateralAmountToGive: Collateral amount the contract has given to the to address
- collateralAmountToReceive: Collateral amount taken from the msg.sender address Any contract interfacing with the vaultManager

Below, we detail the list of different actions, their corresponding integers and the data that should be passed for actions to be correctly processed. Note that for all actions requiring a vaultID, specifiying a vaultID = 0 will automatically process the last vault created.

createVault - Action 0

This action enables vault creation within the protocol. It just creates the structure without any collateral or stablecoins with it. It should be combined with other actions to borrow (like an addCollateral and a borrow action to get stablecoins).

Type of the parameter:

address: address for which the vault should be created

closeVault - Action 1

This action enables vault closing within the protocol. An address closing a vault is expected to reimburse its full debt, and gets in exchange the value of the collateral in it. The protocol is coded so that vault closing can be done capital-efficiently. For more details about this, you can look at this guide.

Only the address that owns the vault or addresses that are approved for it can close a vault.

Type of the parameter:

uint256: ID of the vault to close

addCollateral - Action 2

Adds collateral in an existing vault. This function can be done in conjunction with a borrow action to collateralize a vault and get stablecoins in just a single transaction.

Any address can add collateral on any vault.