SAFE Engine

The SAFE, system coin and collateral database

1. Summary

The SAFEEngine stores SAFEs and tracks all debt and collateral balances. This contract is the most important system component and thus, in order to minimize the possibility of bugs, it does not have any external dependencies.

2. Contract Variables & Functions

Variables

• debtBalance[user: address] - unbacked coins (system debt, not belonging to any cdp).

• collateralTypes[collateralType: bytes32] - a mapping of CollateralTypes.

• safes[collateralType: bytes32, safeHandler: address] - a mapping of SAFE types.

• tokenCollateral[user: address] - collateral token balances.

• coinBalance[user: address] - how many coins an account has. This number is not reflected in the external ERC20 token contract.

• globalDebt - total amount of debt currently issued.

• globalDebtCeiling - the limit on total amount of debt that can be issued.

• globalUnbackedDebt - amount of bad debt in the system.

• authorizedAccounts[usr: address] - stores addresses that are able to modifyParameters, disable the contract, modifyCollateralBalances, createUnbackedDebt and confiscateSAFECollateralAndDebt.

• contractEnabled - global settlement flag.

Data Structures

• CollateralType:

  • debtAmount - total normalized system coin debt.

  • accumulatedRate - system coin debt multiplier (accumulated stability fees).

  • safetyPrice - collateral price with safety margin. Used to limit the amount of debt that can be generated per one unit of collateral.

  • debtCeiling - the total amount of debt that can be generated using this collateral type.

  • debtFloor - the minimum amount of debt that must be generated by a SAFE with this collateral type.

  • liquidationPrice - collateral price with safety margin. Used only in LiquidationEngine when a SAFE is liquidated.

• SAFE:

  • lockedCollateral - SAFE collateral balance.

  • generatedDebt - normalized outstanding system coin debt.

Modifiers

• canModifySAFE - modifier that checks whether an address is allowed to modify another address's collateral or system coin balance.

• isAuthorized - checks whether an address is part of authorizedAddresses.

Functions

• disableContract() - disable the SAFEEngine.

• modifyParameters(parameter: bytes32, data: uint256) - modify general uint256 parameters.

• modifyParameters(collateralType: bytes32, parameter: bytes32, data: uint256) - modify collateral type uint256 parameters.

• initializeCollateralType(collateralType: bytes32) - create a new collateral type.

• modifyCollateralBalance(parameter: bytes32, usr: address, wad: int256) - modify a user's collateral balance.

• transferCollateral(collateralType: bytes32, src: address, dst: address, wad: uint256) - transfer collateral between users.

• transferInternalCoins(src: address, dst: address, rad: uint256) - transfer system coins between users. This action does not transfer coins between users in the ERC20 contract but only in the CDPEngine.

• confiscateSAFECollateralAndDebt(collateralType: bytes32,cdp: address, collateralCounterparty: address, debtCounterparty: address, deltaCollateral: int256, deltaDebt: int256) - called by the LiquidationEngine when auctioning collateral to cover bad debt.

• settleDebt(rad: uint256) - destroy equal quantities of system coins and system debt (globalUnbackedDebt).

• updateAccumulatedRate(collateralType: bytes32, surplusDst: address, rateMultiplier: int256) - modify a collateral's accumulated interest rates, creating / destroying corresponding debt.

• createUnbackedDebt(debtDestination: address, coinDestination: address, rad: uint256) - mint unbacked system coins (accounted for with globalUnbackedDebt).

• modifySAFECollateralization(collateralType: bytes32, cdp: address, collateralSource: address, debtDestination: address, deltaCollateral: int256, deltaDebt: int256) - modify a SAFE's CRatio by locking/unlocking collateral and/or generating/paying back debt.

• transferSAFECollateralAndDebt(collateralType: bytes32, src: address, dst: address, deltaCollateral: int256, deltaDebt: int256) - splitting/merging SAFEs by transferring collateral and/or debt between them.

• approveSAFEModification(account: address) - enable canModifySAFEfor a pair of addresses.

• denySAFEModification(account: address) - disable canModifySAFEfor a pair of addresses.

Events

• AddAuthorization - emitted when an addAuthorization(address) is successfully executed. Contains:

  • account - the account that is authorized

• RemoveAuthorization - emitted when a removeAuthorization(address) is successfully executed. Contains:

  • account - the account that is de-authorized

• ApproveSAFEModification - emitted when someone successfully approves another address to modify their SAFE. Contains:

  • sender - the transaction's msg.sender

  • account - the account that is being approved

• DenySAFEModification - emitted when someone successfully denies another address to modify their SAFE. Contains:

  • sender - the transaction's msg.sender

  • account - the account that is being denied the permission to modify a SAFE

• InitializeCollateralType - emitted when a new collateral type is initialized. Contains:

  • collateralType - the collateral type identifier (name)

• ModifyParameters - emitted when a parameter is successfully updated

• DisableContract - emitted when the SAFEEngine is disabled

• ModifyCollateralBalance - emitted when a user's collateral balance is modified (add new collateral/remove collateral). Contains:

  • collateralType - the collateral's identifier

  • account - the account that's being credited/debited collateral

  • wad - delta collateral amount

• TransferCollateral - emitted when someone transfers collateral from one account to another. Contains:

  • collateralType - the collateral's identifier

  • src - the source from which collateral is transferred

  • dst - the destination where collateral arrives

  • wad - the amount of collateral transferred

• TransferInternalCoins - emitted when someone transfers system coins internally. Contains:

  • src - the source of the system coins

  • dst - the destination of the system coins

  • rad - amount of internal coins to transfer

• ModifySAFECollateralization - emitted when someone modifies the collateralization ration of their SAFE (add/remove collateral and/or generate/repay debt). Contains:

  • collateralType - the collateral type added/withdrawn from the SAFE

  • safe - the target SAFE

  • collateralSource - the source from which collateral is taken and deposited in the SAFE

  • debtDestination - the destination of the system coins generated

  • deltaCollateral - the amount of collateral added/withdrawn

  • deltaDebt - the amount of system coins borrowed/repaid

  • lockedCollateral - the total amount of collateral locked in the SAFE

  • generatedDebt - the total amount of debt currently generated by the SAFE

  • globalDebt - the amount of global debt after the SAFE's collateralization ratio is modified

• TransferSAFECollateralAndDebt - emitted when someone transfers collateral and/or debt from one SAFE to another. Contains:

  • collateralType - the identifier of the collateral stored in both the source and the destination SAFEs

  • src - the source SAFE

  • dst - the destination SAFE

  • deltaCollateral - the amount of collateral added to/withdrawn from src and added to/withdrawn from dst

  • deltaDebt - the amount of debt added to/withdrawn from src and added to/withdrawn from dst

  • srcLockedCollateral - total amount of collateral locked in the source SAFE

  • srcGeneratedDebt - total amount of debt generated by the source SAFE

  • dstLockedCollateral - total amount of collateral locked in the destination SAFE

  • dstGeneratedDebt - total amount of debt generated by the destination SAFE

• ConfiscateSAFECollateralAndDebt - emitted when an authed address confiscates collateral and/or debt from a SAFE. Contains:

  • collateralType - the identifier of the collateral deposited in the target SAFE

  • safe - the SAFE from which to confiscate collateral/debt

  • collateralCounterparty - the address that will receive the confiscated collateral

  • debtCounterparty - the address that will receive the confiscated debt

  • deltaCollateral - the amount of collateral to confiscate

  • deltaDebt - the amount of debt to confiscate

  • globalUnbackedDebt - the total amount of global bad debt

• SettleDebt - emitted when the contract settles bad debt with an equal amount of coins (surplus). Contains:

  • rad - the amount of bad debt to settle

  • debtBalance - the resulting debt balance of msg.sender

  • coinBalance - the resulting coin balance of msg.sender

  • globalUnbackedDebt - the resulting amount of global bad debt

  • globalDebt - the resulting amount of total global debt

• CreateUnbackedDebt - emitted after creating debt out of thin air. Contains:

  • debtDestination - the address that will receive debt

  • coinDestination - the address that will receive the corresponding amount of coins

  • rad - the amount of debt to issue

  • debtDstBalance - the resulting amount of debt that the debt destination has

  • coinDstBalance - the resulting amount of coins that the coin destination has

  • globalUnbackedDebt - the resulting amount of global bad debt

  • globalDebt - the resulting amount of total global debt

• UpdateAccumulatedRate - emitted after updating the total accrued interest rate for a specific collateral type. Contains:

  • collateralType - the identifier of the collateral type that had its rate accumulated

  • surplusDst - the destination of the surplus accrued as a result of the rate being accumulated

  • rateMultiplier - amount to be accumulated

  • dstCoinBalance - coin balance of the address that received surplus

  • globalDebt - total amount of global debt

Notes

• globalDebt equals globalUnbackedDebt plus the sum of CollateralType.debtAmount * CollateralType.accumulatedRates across all collateralTypes.

• globalUnbackedDebt is the sum of all debtBalances (the total quantity of system debt).

• CollateralType.debtAmount the sum of all generatedDebt in the safes for that CollateralType.

3. Walkthrough

The SAFEEngine is in charge with two main system functions:

1. SAFE Management

• Anyone can manage a SAFE via modifySAFECollateralization, which modifies the SAFE at address safe, using tokenCollateral from user collateralSource and modifying coinBalance for user debtDestination.

• confiscateSAFECollateralAndDebtis usually called by LiquidationEngine and transfers debt from the SAFE to another address' debtBalance.

• debtBalance represents bad debt and can be canceled out with an equal quantity of system coins using settleDebt(uint rad) where msg.sender is used as the address for the coinBalance and debtBalance.

2. Stability Fee Accrual

The accumulatedRates helps convert normalized debt (generatedDebt) drawn against a collateralType to the present value of that debt (actual debt issued + interest). The rate is updated using updateAccumulatedRate (called by the TaxCollector). After every update, the newly accrued stability fees are added to the coinBalance of surplusDst.