🗡️Settlement - Closing VaultManager contracts

Settlement - Closing VaultManager contracts

• Contract Name: Settlement

• Contract Source: https://github.com/AngleProtocol/borrow-contracts/tree/main/contracts/settlement

1. Introduction

The Settlement contract is a side contract of the Angle Borrowing Module which can be used to end the operations of a VaultManager contract. It is designed so that there is one Settlement per VaultManager. A global settlement of Angle Borrowing Module could be activated if settlement contracts are activated at the same time.

The settlement process works in two steps. It first allows owners of over-collateralized vaults to recover their full collateral upon repaying all their debt. It then allows owners of the concerned stablecoin to redeem collateral at oracle value.

More precisely, if after owners of over-collateralized vaults come to claim their collateral:

• The value of the collateral is less than the amount of stablecoins that have been issued from the associated VaultManager contract: then stablecoins could be used to redeem a pro rata portion of the leftover collateral. For instance, if the leftover debt is 100 and there is only 90 of collateral left, then with 1 of stablecoin you can redeem 9/10 of collateral

• The value of the leftover collateral is greater than the debt: then you can only with your stablecoins the corresponding value of collateral, and leftover collateral will be usable by governance. Given that the module is going to be over-collateralized, we expect that settlement situations, if they are triggered, will lead to this second scenario.

A Settlement contract should be activated and launched after the following operations have been performed in a VaultManager contract:

1. Interest have been accrued in the contract

2. The contract has been paused

3. All the collateral available in the VaultManager contract has been recovered and deposited in the Settlement contract either through a contract upgrade or through a recoverERC20 method if supported

Stablecoins to redeem collateral are simply transferred to this contract and can be burnt later by governance.

2. Contract Details

Constant

• OVER_COLLATERALIZED_CLAIM_DURATION: Duration of the claim period for over-collateralized vaults

References

• vaultManager: VaultManager of this settlement contract

• stablecoin: Reference to the stablecoin supported by the VaultManager contract

• collateral: Reference to the collateral supported by the VaultManager

Variables frozen at settlement activation

• oracleValue: Value of the oracle for the collateral/stablecoin pair at settlement activation

• interestAccumulator: Value of the interest accumulator in the VaultManager at settlement activation

• activationTimestamp: Timestamp at which settlement was activated

• collateralFactor: Collateral factor of the VaultManager

Variables updated during the process

• collateralStablecoinExchangeRate: How much collateral you can get from stablecoins after owners of over-collateralized vaults have claimed their collateral

• leftOverCollateral: Amount of collateral that will be left over at the end of the process

• exchangeRateComputed: Whether the collateralStablecoinExchangeRate has been computed

• vaultCheck: Maps a vault to whether it was claimed or not by its owner

3. Key Mechanisms & Concepts

Governance Activation Functions

The following functions can only be called by governance of the contract to activate the different periods of the settlement process.

activateSettlement

function activateSettlement() external;

This function activates the settlement contract. It should only be called after all the necessary steps described above to launch settlement have been performed by governance.

activateGlobalClaimPeriod

function activateGlobalClaimPeriod() external;

Activates the global claim period by setting the collateralStablecoinExchangeRate which is going to dictate how much of collateral will be recoverable for each stablecoin. It can only be called when the OVER_COLLATERALIZED_CLAIM_DURATION period has passed.

This function can only be called by the governor in order to allow it in case multiple settlements happen across different VaultManager to rebalance the amount of stablecoins on each to make sure that across all settlement contracts a similar value of collateral can be obtained against a similar value of stablecoins.

This function computes the leftover debt of the contract by removing what has already been redeemed during the first period of claims, compares it with the collateral in reserves and the oracle value and then deduces from this the collateralStablecoinExchangeRate.

This function also computes the amount of collateral that could be leftover if only stablecoins issued thanks to this VaultManager contract came to be claimed in the process. To avoid the situations where more stablecoins are claimed than what has been issued if there is an excess amount of collateral, governance can call the recoverERC20 function right after calling the activateGlobalClaimPeriod function.

External User Interaction Methods

All the claim methods in this contract leave the opportunity for capital-efficiency: and if collateral is claimed, then the contract first sends the collateral for it to be possibly swapped to stablecoins for the repayment.

More details on capital-efficiency within Angle Borrowing Module can be found here.

Addresses interacting with this method should make sure to have approved the Settlement contract for the stablecoin.

claimOverCollateralizedVault

    function claimOverCollateralizedVault(
        uint256 vaultID,
        address to,
        address who,
        bytes memory data
    ) external returns (uint256, uint256)

Allows the owner of an over-collateralized vault to claim its collateral upon bringing back all owed stablecoins. This function can only be called in the OVER_COLLATERALIZED_CLAIM_DURATION after settlement activation. Owners of over-collateralized vaults therefore have a limited amount of time to claim their collateral back after settlement is activated.

A vault cannot be claimed twice and only the owner of the vault can claim it (regardless of the approval logic). On top of that, only over-collateralized vaults can be claimed from this medium and the contract checks that the vaults that are being claimed are healthy vaults that cannot be liquidated.

Parameters:

• vaultID: ID of the vault to claim

• to: Address to which collateral should be sent

• who: Address which should be notified if needed of the transfer of stablecoins and collateral

• data: Data to pass to the who contract for it to successfully give the correct amount of stablecoins to the msg.sender address. Like the who parameter, this parameter is optional though.

Return Values:

• Amount of collateral sent to the to address

• Amount of stablecoins sent to the contract by the msg.sender

claimCollateralFromStablecoins

    function claimCollateralFromStablecoins(
        uint256 stablecoinAmount,
        address to,
        address who,
        bytes memory data
    ) external returns (uint256, uint256)

Allows to claim collateral from stablecoins. Anyone can call this function provided that it owns stablecoins. The amount of collateral that can be claimed for this function is capped by the collateral balance of the Settlement contract.

If there is 100 of collateral after the first claim period, then up to 100 of stablecoins could be used to redeem collateral (and even if less than a 100 of stablecoins have been minted through this contract).

If settlement was activated in a period in which there was no under-collateralized vault and if they all claimed their vault in the allocated period, then this function is useless as there's no collateral that can be claimed.

Parameters:

• stablecoinAmount: Amount of stablecoins to repay

• to: Address to which collateral should be sent

• who: Address which should be notified if needed of the transfer of stablecoins and collateral

• data: Data to pass to the who contract for it to successfully give the correct amount of stablecoins to the msg.sender address. Like the who parameter, this parameter is optional though.

Return Values:

• Amount of collateral sent to the to address

• Amount of stablecoins sent to the contract by the msg.sender

Governance Function

The contract has a recoverERC20 to recover any token mistakenly sent to the contract, or collateral from the contract. In case it's collateral, it can only happen during the global claim period, and governors cannot recover more collateral than what would be leftover from the contract.

This function can be used to rebalance stablecoin balances across different settlement contracts to make sure every stablecoin can be redeemed for the same value of collateral.