GlobalSettlement

Git Source

Inherits: Authorizable, Modifiable, Disableable, IGlobalSettlement

This contract is responsible for processing the system settlement, a stateful process that takes place over nine steps.

System shutdown:

We must freeze the system and start the cooldown period before we can process any system state. In particular, oracle prices are frozen, and no more debt can be generated from the SAFEEngine.

1. shutdownSystem()

• freeze the system and start the cooldown period

2. freezeCollateralType(_cType)

• reads and store the final price for each collateral type
• initializes collateralTotalDebt to the total debt registered in safe engine

Cooldown period:

We must process some system state before it is possible to calculate the final coin / collateral price. In particular, we need to determine:

• (a) collateralShortfall (considers under-collateralized SAFEs)
• (b) outstandingCoinSupply (after including system surplus / deficit)

• We determine (a) by processing all under-collateralized SAFEs.
• We determine (b) by processing ongoing coin generating processes, i.e. auctions. We need to ensure that auctions will not generate any further coin income.

3. processSAFE(_cType, _safe)

• confiscates SAFE debt and backing collateral (excess of collateral remains).

4. Auctions at SAH and DAH can be terminated prematurely, while CAH auctions are handled by this contract

• 4.a. SAH.terminateAuctionPrematurely(_id)

• settles the auction
• transfers the surplus to the highest bidder

• 4.b. DAH.terminateAuctionPrematurely(_id)

• settles the auction
• returns the coins to the highest bidder
• registers the unbacked debt at the accounting engine

• 4.c. this.fastTrackAuction(_cType, _id)

• settles the auction: returns collateral and debt to the SAFE
• registers returned debt in collateralTotalDebt

When an overcollateralized SAFE has been processed and has no debt remaining, the remaining collateral can be withdrawn:

5. freeCollateral(_cType)

• remove collateral from the caller's SAFE (requires SAFE to have no debt)

After cooldown period:

We enable calculation of the final price for each collateral type. Requires accounting engine to have no surplus.

7. setOutstandingCoinSupply()

• fixes the total outstanding supply of coin

6. calculateCashPrice(_cType)

• calculate collateralCashPrice adjusted in the case of deficit / surplus

Redeeming:

At this point we have computed the final price for each collateral type and coin holders can now turn their coin into collateral.

8. prepareCoinsForRedeeming(_wad)

• deposit the amount of coins to redeem in caller's accountance
• Each unit of coin can claim a proportional amount of all of the system's collateral
• At any point a user can get and prepare more coins to redeem for more collateral

9. redeemCollateral(_cType, _wad)

• claim tokens from a specific collateral type given the amount of coins caller has deposited
• The amount of collateral to redeem depends exclusively in the state variables calculated in the previous steps
• The amount of collaterals left when all circulating coins are redeemed should be 0

State Variables

shutdownTime

The timestamp when settlement was triggered

uint256 public shutdownTime;

outstandingCoinSupply

The outstanding coin supply computed during the settlement process [rad]

uint256 public outstandingCoinSupply;

finalCoinPerCollateralPrice

The final coin per collateral price computed during the settlement process

mapping(bytes32 _cType => uint256 _ray) public finalCoinPerCollateralPrice;

collateralShortfall

The total amount of bad debt for a collateral type computed during the settlement process

mapping(bytes32 _cType => uint256 _wad) public collateralShortfall;

collateralTotalDebt

The total amount of debt for a collateral type computed during the settlement process

mapping(bytes32 _cType => uint256 _wad) public collateralTotalDebt;

collateralCashPrice

Final collateral cash price computed during the settlement process, accounting for surplus / shortfall

mapping(bytes32 _cType => uint256 _ray) public collateralCashPrice;

coinBag

Mapping containing the total amount of coins a user has prepared for redeeming

mapping(address _usr => uint256 _wad) public coinBag;

coinsUsedToRedeem

Mapping containing the total amount of coins a user has used to redeem collateral

mapping(bytes32 _cType => mapping(address _usr => uint256 _wad)) public coinsUsedToRedeem;

safeEngine

Address of the SAFEEngine contract

ISAFEEngine public safeEngine;

liquidationEngine

Address of the LiquidationEngine contract

ILiquidationEngine public liquidationEngine;

oracleRelayer

Address of the OracleRelayer contract

IOracleRelayer public oracleRelayer;

coinJoin

Address of the CoinJoin contract

IDisableable public coinJoin;

collateralJoinFactory

Address of the CollateralJoinFactory contract

IDisableable public collateralJoinFactory;

collateralAuctionHouseFactory

Address of the CollateralAuctionHouseFactory contract

IDisableable public collateralAuctionHouseFactory;

stabilityFeeTreasury

Address of the StabilityFeeTreasury contract

IDisableable public stabilityFeeTreasury;

accountingEngine

Address of the AccountingEngine contract

IDisableable public accountingEngine;

_params

Getter for the unpacked contract parameters struct

GlobalSettlementParams public _params;

Functions

params

Getter for the contract parameters struct

function params() external view returns (GlobalSettlementParams memory _globalSettlementParams);

Returns

constructor

constructor(
  address _safeEngine,
  address _liquidationEngine,
  address _oracleRelayer,
  address _coinJoin,
  address _collateralJoinFactory,
  address _collateralAuctionHouseFactory,
  address _stabilityFeeTreasury,
  address _accountingEngine,
  GlobalSettlementParams memory _gsParams
) Authorizable(msg.sender) validParams;

Parameters

_onContractDisable

Internal virtual method to be called when the contract is disabled

Method override avoids externally disabling this contract

function _onContractDisable() internal pure override;

shutdownSystem

Freeze the system and start the cooldown period

This function switches the whenEnabled/whenDisabled modifiers across the system contracts

function shutdownSystem() external isAuthorized whenEnabled;

freezeCollateralType

Calculate a collateral type's final price according to the latest system coin redemption price

function freezeCollateralType(bytes32 _cType) external whenDisabled;

Parameters

fastTrackAuction

Fast track an ongoing collateral auction

function fastTrackAuction(bytes32 _cType, uint256 _auctionId) external;

Parameters

processSAFE

Cancel a SAFE's debt and leave any extra collateral in it

function processSAFE(bytes32 _cType, address _safe) external;

Parameters

freeCollateral

Remove collateral from the caller's SAFE (requires SAFE to have no debt)

function freeCollateral(bytes32 _cType) external whenDisabled;

Parameters

setOutstandingCoinSupply

Set the final outstanding supply of system coins

There must be no remaining surplus in the accounting engine

function setOutstandingCoinSupply() external whenDisabled;

calculateCashPrice

Calculate a collateral's price taking into consideration system surplus/deficit and the finalCoinPerCollateralPrice

function calculateCashPrice(bytes32 _cType) external;

Parameters

prepareCoinsForRedeeming

Add coins into a 'bag' so that you can use them to redeem collateral

function prepareCoinsForRedeeming(uint256 _coinAmount) external;

Parameters

redeemCollateral

Redeem a specific collateral type using an amount of internal system coins from your bag

function redeemCollateral(bytes32 _cType, uint256 _coinsAmount) external;

Parameters

_modifyParameters

Internal function to be overriden with custom logic to modify parameters

This function is set to revert if not overriden

function _modifyParameters(bytes32 _param, bytes memory _data) internal override whenEnabled;

_validateParameters

Internal function to be overriden with custom logic to validate parameters

function _validateParameters() internal view override;