ISAFEEngine

Git Source

Inherits: IAuthorizable, IDisableable, IModifiable, IModifiablePerCollateral

Functions

params

Getter for the contract parameters struct

function params() external view returns (SAFEEngineParams memory _safeEngineParams);

Returns

NameTypeDescription
_safeEngineParamsSAFEEngineParamsThe active SAFEEngineParams

_params

Getter for the unpacked contract parameters struct

function _params() external view returns (uint256 _safeDebtCeiling, uint256 _globalDebtCeiling);

Returns

NameTypeDescription
_safeDebtCeilinguint256Total amount of debt that a single safe can generate [wad]
_globalDebtCeilinguint256Maximum amount of debt that can be issued [rad]

cParams

Getter for the collateral parameters struct

function cParams(bytes32 _cType) external view returns (SAFEEngineCollateralParams memory _safeEngineCParams);

Parameters

NameTypeDescription
_cTypebytes32Bytes32 representation of the collateral type

Returns

NameTypeDescription
_safeEngineCParamsSAFEEngineCollateralParamsSAFEEngineCollateralParams for the collateral type

_cParams

Getter for the unpacked collateral parameters struct

function _cParams(bytes32 _cType) external view returns (uint256 _debtCeiling, uint256 _debtFloor);

Parameters

NameTypeDescription
_cTypebytes32Bytes32 representation of the collateral type

Returns

NameTypeDescription
_debtCeilinguint256Maximum amount of debt that can be generated with this collateral type
_debtFlooruint256Minimum amount of debt that must be generated by a SAFE using this collateral

cData

Getter for the collateral data struct

function cData(bytes32 _cType) external view returns (SAFEEngineCollateralData memory _safeEngineCData);

Parameters

NameTypeDescription
_cTypebytes32Bytes32 representation of the collateral type

Returns

NameTypeDescription
_safeEngineCDataSAFEEngineCollateralDataSAFEEngineCollateralData for the collateral type

_cData

Getter for the unpacked collateral data struct

function _cData(bytes32 _cType)
  external
  view
  returns (
    uint256 _debtAmount,
    uint256 _lockedAmount,
    uint256 _accumulatedRate,
    uint256 _safetyPrice,
    uint256 _liquidationPrice
  );

Parameters

NameTypeDescription
_cTypebytes32Bytes32 representation of the collateral type

Returns

NameTypeDescription
_debtAmountuint256Total amount of debt issued by a collateral type [wad]
_lockedAmountuint256Total amount of collateral locked in all SAFEs of the collateral type [wad]
_accumulatedRateuint256Accumulated rate of a collateral type [ray]
_safetyPriceuint256Floor price at which a SAFE is allowed to generate debt [ray]
_liquidationPriceuint256Price at which a SAFE gets liquidated [ray]

safes

Data about each SAFE

function safes(bytes32 _cType, address _safeAddress) external view returns (SAFE memory _safeData);

Parameters

NameTypeDescription
_cTypebytes32Bytes32 representation of the collateral type
_safeAddressaddressAddress of the SAFE

Returns

NameTypeDescription
_safeDataSAFESAFE data for the specified collateral type of the specified safe.

_safes

Unpacked data about each SAFE

function _safes(
  bytes32 _cType,
  address _safeAddress
) external view returns (uint256 _lockedCollateral, uint256 _generatedDebt);

Parameters

NameTypeDescription
_cTypebytes32Bytes32 representation of the collateral type
_safeAddressaddressAddress of the SAFE

Returns

NameTypeDescription
_lockedCollateraluint256Total amount of collateral locked in a SAFE [wad]
_generatedDebtuint256Total amount of debt generated by a SAFE [wad]

safeRights

Who can transfer collateral & debt in/out of a SAFE

function safeRights(address _caller, address _account) external view returns (bool _safeRights);

Parameters

NameTypeDescription
_calleraddressAddress to check for SAFE permissions for
_accountaddressAccount to check if caller has permissions for

Returns

NameTypeDescription
_safeRightsboolBoolean representation of the SAFE rights (0/1)

tokenCollateral

Balance of each collateral type

function tokenCollateral(bytes32 _cType, address _account) external view returns (uint256 _collateralBalance);

Parameters

NameTypeDescription
_cTypebytes32Bytes32 representation of the collateral type to check balance for
_accountaddressAccount to check balance for

Returns

NameTypeDescription
_collateralBalanceuint256Collateral balance of the account [wad]

coinBalance

Internal balance of system coins held by an account

function coinBalance(address _account) external view returns (uint256 _balance);

Parameters

NameTypeDescription
_accountaddressAccount to check balance for

Returns

NameTypeDescription
_balanceuint256Internal coin balance of the account [rad]

debtBalance

Amount of debt held by an account

function debtBalance(address _account) external view returns (uint256 _debtBalance);

Parameters

NameTypeDescription
_accountaddressAccount to check balance for

Returns

NameTypeDescription
_debtBalanceuint256Debt balance of the account [rad]

globalDebt

Total amount of debt (coins) currently issued

function globalDebt() external returns (uint256 _globalDebt);

Returns

NameTypeDescription
_globalDebtuint256Global debt [rad]

globalUnbackedDebt

'Bad' debt that's not covered by collateral

function globalUnbackedDebt() external view returns (uint256 _globalUnbackedDebt);

Returns

NameTypeDescription
_globalUnbackedDebtuint256Global unbacked debt [rad]

transferCollateral

Transfer collateral between accounts

function transferCollateral(bytes32 _cType, address _source, address _destination, uint256 _wad) external;

Parameters

NameTypeDescription
_cTypebytes32Collateral type transferred
_sourceaddressCollateral source
_destinationaddressCollateral destination
_waduint256Amount of collateral transferred

transferInternalCoins

Transfer internal coins (does not affect external balances from Coin.sol)

function transferInternalCoins(address _source, address _destination, uint256 _rad) external;

Parameters

NameTypeDescription
_sourceaddressCoins source
_destinationaddressCoins destination
_raduint256Amount of coins transferred

modifyCollateralBalance

Join/exit collateral into and and out of the system

function modifyCollateralBalance(bytes32 _cType, address _account, int256 _wad) external;

Parameters

NameTypeDescription
_cTypebytes32Collateral type to join/exit
_accountaddressAccount that gets credited/debited
_wadint256Amount of collateral

modifySAFECollateralization

Add/remove collateral or put back/generate more debt in a SAFE

function modifySAFECollateralization(
  bytes32 _cType,
  address _safe,
  address _collateralSource,
  address _debtDestination,
  int256 _deltaCollateral,
  int256 _deltaDebt
) external;

Parameters

NameTypeDescription
_cTypebytes32Type of collateral to withdraw/deposit in and from the SAFE
_safeaddressTarget SAFE
_collateralSourceaddressAccount we take collateral from/put collateral into
_debtDestinationaddressAccount from which we credit/debit coins and debt
_deltaCollateralint256Amount of collateral added/extracted from the SAFE [wad]
_deltaDebtint256Amount of debt to generate/repay [wad]

transferSAFECollateralAndDebt

Transfer collateral and/or debt between SAFEs

function transferSAFECollateralAndDebt(
  bytes32 _cType,
  address _src,
  address _dst,
  int256 _deltaCollateral,
  int256 _deltaDebt
) external;

Parameters

NameTypeDescription
_cTypebytes32Collateral type transferred between SAFEs
_srcaddressSource SAFE
_dstaddressDestination SAFE
_deltaCollateralint256Amount of collateral to take/add into src and give/take from dst [wad]
_deltaDebtint256Amount of debt to take/add into src and give/take from dst [wad]

confiscateSAFECollateralAndDebt

Normally used by the LiquidationEngine in order to confiscate collateral and debt from a SAFE and give them to someone else

function confiscateSAFECollateralAndDebt(
  bytes32 _cType,
  address _safe,
  address _collateralSource,
  address _debtDestination,
  int256 _deltaCollateral,
  int256 _deltaDebt
) external;

Parameters

NameTypeDescription
_cTypebytes32Collateral type the SAFE has locked inside
_safeaddressTarget SAFE
_collateralSourceaddressWho we take/give collateral to
_debtDestinationaddressWho we take/give debt to
_deltaCollateralint256Amount of collateral taken/added into the SAFE [wad]
_deltaDebtint256Amount of debt taken/added into the SAFE [wad]

settleDebt

Nullify an amount of coins with an equal amount of debt

Coins & debt are like matter and antimatter, they nullify each other

function settleDebt(uint256 _rad) external;

Parameters

NameTypeDescription
_raduint256Amount of debt & coins to destroy

createUnbackedDebt

Allows an authorized contract to create debt without collateral

Usually called by DebtAuctionHouse in order to terminate auctions prematurely post settlement

function createUnbackedDebt(address _debtDestination, address _coinDestination, uint256 _rad) external;

Parameters

NameTypeDescription
_debtDestinationaddressThe account that will receive the newly created debt
_coinDestinationaddressThe account that will receive the newly created coins
_raduint256Amount of debt to create

updateAccumulatedRate

Allows an authorized contract to accrue interest on a specific collateral type

The rateMultiplier is usually calculated by the TaxCollector contract

function updateAccumulatedRate(bytes32 _cType, address _surplusDst, int256 _rateMultiplier) external;

Parameters

NameTypeDescription
_cTypebytes32Collateral type we accrue interest for
_surplusDstaddressDestination for the newly created surplus
_rateMultiplierint256Multiplier applied to the debtAmount in order to calculate the surplus [ray]

updateCollateralPrice

Allows an authorized contract to update the safety price and liquidation price of a collateral type

function updateCollateralPrice(bytes32 _cType, uint256 _safetyPrice, uint256 _liquidationPrice) external;

Parameters

NameTypeDescription
_cTypebytes32Collateral type we update the prices for
_safetyPriceuint256New safety price [ray]
_liquidationPriceuint256New liquidation price [ray]

approveSAFEModification

Allow an address to modify your SAFE

function approveSAFEModification(address _account) external;

Parameters

NameTypeDescription
_accountaddressAccount to give SAFE permissions to

denySAFEModification

Deny an address the rights to modify your SAFE

function denySAFEModification(address _account) external;

Parameters

NameTypeDescription
_accountaddressAccount that is denied SAFE permissions

canModifySAFE

Checks whether an account has the right to modify a SAFE

function canModifySAFE(address _safe, address _account) external view returns (bool _allowed);

Parameters

NameTypeDescription
_safeaddressThe safe to check
_accountaddressThe account to check

Returns

NameTypeDescription
_allowedboolWhether the account can modify the safe

Events

ApproveSAFEModification

Emitted when an address authorizes another address to modify its SAFE

event ApproveSAFEModification(address _sender, address _account);

Parameters

NameTypeDescription
_senderaddressAddress that sent the authorization
_accountaddressAddress that is authorized to modify the SAFE

DenySAFEModification

Emitted when an address denies another address to modify its SAFE

event DenySAFEModification(address _sender, address _account);

Parameters

NameTypeDescription
_senderaddressAddress that sent the denial
_accountaddressAddress that is denied to modify the SAFE

TransferCollateral

Emitted when collateral is transferred between accounts

event TransferCollateral(bytes32 indexed _cType, address indexed _src, address indexed _dst, uint256 _wad);

Parameters

NameTypeDescription
_cTypebytes32Bytes32 representation of the collateral type
_srcaddressAddress that sent the collateral
_dstaddressAddress that received the collateral
_waduint256Amount of collateral transferred

TransferInternalCoins

Emitted when internal coins are transferred between accounts

event TransferInternalCoins(address indexed _src, address indexed _dst, uint256 _rad);

Parameters

NameTypeDescription
_srcaddressAddress that sent the coins
_dstaddressAddress that received the coins
_raduint256Amount of coins transferred

ModifySAFECollateralization

Emitted when the SAFE state is modified by the owner or authorized accounts

event ModifySAFECollateralization(
  bytes32 indexed _cType,
  address indexed _safe,
  address _collateralSource,
  address _debtDestination,
  int256 _deltaCollateral,
  int256 _deltaDebt
);

Parameters

NameTypeDescription
_cTypebytes32Bytes32 representation of the collateral type
_safeaddressAddress of the SAFE
_collateralSourceaddressAddress that sent/receives the collateral
_debtDestinationaddressAddress that sent/receives the debt
_deltaCollateralint256Amount of collateral added/extracted from the SAFE [wad]
_deltaDebtint256Amount of debt to generate/repay [wad]

TransferSAFECollateralAndDebt

Emitted when collateral and/or debt is transferred between SAFEs

event TransferSAFECollateralAndDebt(
  bytes32 indexed _cType, address indexed _src, address indexed _dst, int256 _deltaCollateral, int256 _deltaDebt
);

Parameters

NameTypeDescription
_cTypebytes32Bytes32 representation of the collateral type
_srcaddressAddress that sent the collateral
_dstaddressAddress that received the collateral
_deltaCollateralint256Amount of collateral to take/add into src and give/take from dst [wad]
_deltaDebtint256Amount of debt to take/add into src and give/take from dst [wad]

ConfiscateSAFECollateralAndDebt

Emitted when collateral and debt is confiscated from a SAFE

event ConfiscateSAFECollateralAndDebt(
  bytes32 indexed _cType,
  address indexed _safe,
  address _collateralSource,
  address _debtDestination,
  int256 _deltaCollateral,
  int256 _deltaDebt
);

Parameters

NameTypeDescription
_cTypebytes32Bytes32 representation of the collateral type
_safeaddressAddress of the SAFE
_collateralSourceaddressAddress that sent/receives the collateral
_debtDestinationaddressAddress that sent/receives the debt
_deltaCollateralint256Amount of collateral added/extracted from the SAFE [wad]
_deltaDebtint256Amount of debt to generate/repay [wad]

SettleDebt

Emitted when an account's debt is settled with coins

Accounts (not SAFEs) can only settle unbacked debt

event SettleDebt(address indexed _account, uint256 _rad);

Parameters

NameTypeDescription
_accountaddressAddress of the account
_raduint256Amount of debt & coins to destroy

CreateUnbackedDebt

Emitted when an unbacked debt is created to an account

event CreateUnbackedDebt(address indexed _debtDestination, address indexed _coinDestination, uint256 _rad);

Parameters

NameTypeDescription
_debtDestinationaddressAddress that received the newly created debt
_coinDestinationaddressAddress that received the newly created coins
_raduint256Amount of debt to create

UpdateAccumulatedRate

Emit when the accumulated rate of a collateral type is updated

event UpdateAccumulatedRate(bytes32 indexed _cType, address _surplusDst, int256 _rateMultiplier);

Parameters

NameTypeDescription
_cTypebytes32Bytes32 representation of the collateral type
_surplusDstaddressAddress that received the newly created surplus
_rateMultiplierint256Delta of the accumulated rate [ray]

UpdateCollateralPrice

Emitted when the safety price and liquidation price of a collateral type is updated

event UpdateCollateralPrice(bytes32 indexed _cType, uint256 _safetyPrice, uint256 _liquidationPrice);

Parameters

NameTypeDescription
_cTypebytes32Bytes32 representation of the collateral type
_safetyPriceuint256New price at which a SAFE is allowed to generate debt [ray]
_liquidationPriceuint256New price at which a SAFE gets liquidated [ray]

Errors

SAFEEng_CollateralTypeNotInitialized

Throws when trying to modify parameters of an uninitialized collateral type

error SAFEEng_CollateralTypeNotInitialized();

SAFEEng_SAFENotSafe

Throws when trying to modify a SAFE into an unsafe state

error SAFEEng_SAFENotSafe();

SAFEEng_DustySAFE

Throws when trying to modify a SAFE into a dusty safe (debt non-zero and below debtFloor)

error SAFEEng_DustySAFE();

SAFEEng_GlobalDebtCeilingHit

Throws when trying to generate debt that would put the system over the global debt ceiling

error SAFEEng_GlobalDebtCeilingHit();

SAFEEng_CollateralDebtCeilingHit

Throws when trying to generate debt that would put the system over the collateral debt ceiling

error SAFEEng_CollateralDebtCeilingHit();

SAFEEng_SAFEDebtCeilingHit

Throws when trying to generate debt that would put the SAFE over the SAFE debt ceiling

error SAFEEng_SAFEDebtCeilingHit();

SAFEEng_NotSAFEAllowed

Throws when an account tries to modify a SAFE without the proper permissions

error SAFEEng_NotSAFEAllowed();

SAFEEng_NotCollateralSrcAllowed

Throws when an account tries to pull collateral from a SAFE without the proper permissions

error SAFEEng_NotCollateralSrcAllowed();

SAFEEng_NotDebtDstAllowed

Throws when an account tries to push debt to a SAFE without the proper permissions

error SAFEEng_NotDebtDstAllowed();

Structs

SAFE

struct SAFE {
  uint256 lockedCollateral;
  uint256 generatedDebt;
}

SAFEEngineParams

struct SAFEEngineParams {
  uint256 safeDebtCeiling;
  uint256 globalDebtCeiling;
}

SAFEEngineCollateralData

struct SAFEEngineCollateralData {
  uint256 debtAmount;
  uint256 lockedAmount;
  uint256 accumulatedRate;
  uint256 safetyPrice;
  uint256 liquidationPrice;
}

SAFEEngineCollateralParams

struct SAFEEngineCollateralParams {
  uint256 debtCeiling;
  uint256 debtFloor;
}