Last updated
Last updated
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.
Variables
debtBalance[user: address]
- unbacked coins (system debt, not belonging to any cdp
).
collateralTypes[collateralType: bytes32]
- a mapping of CollateralType
s.
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 .
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, modifyCollateralBalance
s, 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 canModifySAFE
for a pair of addresses.
denySAFEModification(account: address)
- disable canModifySAFE
for 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 debtBalance
s (the total quantity of system debt).
CollateralType.debtAmount
the sum of all generatedDebt
in the safe
s for that CollateralType
.
The SAFEEngine
is in charge with two main system functions:
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
.
confiscateSAFECollateralAndDebt
is 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
.
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
.
The SAFE, system coin and collateral database