Contract Name: Vat.sol
Type/Category: DSS —> Core System Accounting
Vat is the core Vault engine of
dss. It stores Vaults and tracks all the associated Dai and Collateral balances. It also defines the rules by which Vaults and balances can be manipulated. The rules defined in the
Vat are immutable, so in some sense, the rules in the
Vat can be viewed as the constitution of
gem: collateral tokens.
dai: stablecoin tokens.
sin: unbacked stablecoin (system debt, not belonging to any
ilk: a collateral type.
rate: stablecoin debt multiplier (accumulated stability fees).
take: collateral balance multiplier.
Ink: total collateral balance.
Art: total normalized stablecoin debt.
init: create a new collateral type.
urn: a specific Vault.
ink: collateral balance.
art: normalized outstanding stablecoin debt.
slip: modify a user's collateral balance.
flux: transfer collateral between users.
move: transfer stablecoin between users.
grab: liquidate a Vault.
heal: create / destroy equal quantities of stablecoin and system debt (
fold: modify the debt multiplier, creating / destroying corresponding debt.
toll: modify the collateral multiplier, creating / destroying corresponding collateral.
suck: mint unbacked stablecoin (accounted for with
spot: collateral price with safety margin, i.e. the maximum stablecoin allowed per unit of collateral.
line: the debt ceiling for a specific collateral type.
Line: the total debt ceiling for all collateral types.
dust: the minimum possible debt of a Vault.
frob: modify a Vault.
lock: transfer collateral into a Vault.
free: transfer collateral from a Vault.
draw: increase Vault debt, creating Dai.
wipe: decrease Vault debt, destroying Dai.
dink: change in collateral.
dart: change in debt.
calm: true when the Vault remains under both collateral and total debt ceilings.
cool: true when the stablecoin debt does not increase.
firm: true when the collateral balance does not decrease.
safe: true when the Vault's ratio of collateral to debt is above the collateral's liquidation ratio.
fork: to split a Vault - binary approval or splitting/merging Vaults.
dink: amount of collateral to exchange.
dart: amount of stablecoin debt to exchange.
wish: check whether an address is allowed to modify another address's gem or dai balance.
wish for a pair of addresses.
wish for a pair of addresses.
Art represent normalized debt, i.e. a value that when multiplied by the correct rate gives the up-to-date, current stablecoin debt.
debt is the sum of all
dai (the total quantity of dai issued).
vice is the sum of all
sin (the total quantity of system debt).
ilk.Art the sum of all
art in the
urns for that
vice plus the sum of
ilk.Art * ilk.rate across all
gem can always be transferred to any address by it's owner.
dai can only move with the consent of it's owner.
dai can always be transferred to any address by it's owner.
The core Vault, Dai, and collateral state is kept in the
Vat contract has no external dependencies and maintains the central "Accounting Invariants" of Dai. The core principles that apply to the
vat are as follows:
Dai cannot exist without collateral:
ilk is a particular type of collateral.
gem is assigned to users with
gem is transferred between users with
2. The Vault data structure is the
ink - encumbered collateral
art - encumbered, normalized debt
3. Similarly, a collateral is an
Ink - encumbered collateral
Art - encumbered, normalized debt
take - collateral scaling factor (discussed further below)
rate - debt scaling factor (discussed further below)
Note: Above, when using the term "encumbered", this refers to being "locked in a Vault".
Vaults are managed via
frob(i, u, v, w, dink, dart), which modifies the Vault of user
gem from user
dai for user
Vaults are confiscated via
grab(i, u, v, w, dink, dart), which modifies the Vault of user
gem to user
sin for user
grab is the means by which Vaults are liquidated, transferring debt from the Vault to a users
Sin represents "seized" or "bad" debt and can be canceled out with an equal quantity of Dai using
heal(uint rad where
msg.sender is used as the address for the
Note: Only the Vow will ever have
sin, so only the Vow can successfully call
heal. This is because whenever
suck are called, the Vow's address is passed as the recipient of
sin. Note that this is contingent on the current design and implementation of the system.
heal can only be called with a positive number (uint) and will
sub(dai[u]) along with
dai can be transferred between users with
rate is the conversion factor between any normalized debt (
art) drawn against it and the present value of that debt with accrued fees. The
rate parameter to
fold is actually the change in the
Ilk.rate value, i.e. a difference of scaling factors (new - old). It is a signed integer, and hence current account values may increase or decrease. The quantity
Ilk.Art*rate is added to the
dai balance of the address
u (representing an increase or decrease in system surplus); the debt balances of all CDPs collateralized with the specified
ilk are updated implicitly via the addition of
For more information on Rates and System Stabilization, see the Rates Module and System Stabilizer Module documentation below:
The methods in the
Vat are written to be as generic as possible and as such have interfaces that can be quite verbose. Care should be taken that you have not mixed the order of parameters.
Any module that is
authed against the
Vat has full root access, and can therefore steal all collateral in the system. This means that the addition of a new collateral type (and associated adapter) carries considerable risk.
A bug in the
Vat could be catastrophic and could lead to the loss (or locking) of all Dai and Collateral in the system. It could become impossible to modify Vault's or to transfer Dai. Auctions could cease to function. Shutdown could fail.
Vat relies upon a set of trusted oracles to provide price data. Should these price feeds fail, it would become possible for unbacked Dai to be minted, or safe Vaults could be unfairly liquidated.
Governance can authorize new modules against the
Vat. This allows them to steal collateral (
slip) or mint unbacked Dai (
suck / addition of worthless collateral types). Should the cryptoeconomic protections that make doing so prohibitively expensive fail, the system may be vulnerable and left open for bad actors to drain collateral.
Vat relies on external Adapter contracts to ensure that the collateral balances in the
Vat represent real external collateral balances. Adapter contracts are authorized to make arbitrary modifications to all collateral balances. A faulty collateral adapter could result in the loss of all collateral in the system.