Vow - Detailed Documentation
The Maker Protocol's Balance Sheet
Vowcontract represents the Maker Protocol's balance sheet. In particular, the
Vowacts as the recipient of both the system surplus and system debt. Its main functions are to cover deficits via debt (
Flop) auctions and discharge surpluses via surplus (
Vow.sol Contract Interaction
- Inter-contract calls necessary for the module function
- Auction and user auction interactions
- Governance calls / interactions
sin: the system debt queue.
Sin: the total amount of debt in the queue.
Ash: the total amount of on-auction debt.
wait: length of the debt queue
sump: debt auction bid size, i.e. the fixed debt quantity to be covered by any one debt auction
dump: debt auction lot size, i.e. the starting amount of MKR offered to cover the
bump: surplus auction lot size, i.e. the fixed surplus quantity to be sold by any one surplus auction
hump: surplus buffer, must be exceeded before surplus auctions are possible
Other terms included in the above diagram:
move: transfers stablecoin between users.
kick: starts an auction.
- Fess - Pushes bad debt to the auctions queue (add debt to the queue).
- Flog - Release queued debt for auction (realize debt from the queue).
- Heal -
vatcontract to cancel out surplus and debt. (Optimize debt buffer (
- Kiss - Cancels out surplus and on-auction debt. Release on-auction debt and Heal (
- Flap - Trigger a surplus auction (
- Flop - Trigger a deficit auction (
flapto start an auction (debt and surplus auctions, respectively).
Flopper(Debt auctions) - If the deficit is not covered in the forward auction portion of the
flipauction, then debt auctions are used for getting rid of the Vow’s debt by auctioning off MKR for a fixed amount of Dai. Once the auction ends, the
Flopper will then send the received Dai to the
Vowin order to cancel its debt. Lastly, the
Flopper will mint the MKR for the winning bidder.
Flapper(Surplus auctions) - These are used for getting rid of the
Vow’s surplus by auctioning off a fixed amount of internal Dai for MKR. Once the auction ends, the
Flapper burns the winning MKR bid and sends internal Dai to the winning bidder.
- System config
Vow.wait- Flop delay
Vow.sump- Flop fixed bid size
Vow.dump- Flop starting lot size
Vow.bump- Flap fixed lot size
Vow.hump- Surplus buffer
When a Vault is liquidated (
bite- documentation), the seized debt is put in a queue for an auction in a
sin[timestamp]- the system debt unit). This occurs at the block timestamp of the
biteaction. It can be released for auction via
flogreleases queued debt for the auction) once the allotted
Vow.wait(the flop delay) time has expired.
Sinis stored when it's in the debt queue, but the debt available to auction isn't explicitly stored anywhere. This is because the debt that is eligible for auction is derived by comparing the
Sin(i.e. debt on the holding queue) with the dai balance of the
Vowas recorded in
Vat.dai[Vow]. For instance, if
Vat.sin[Vow]is greater than the sum of
Ash(debt currently on auction), then the difference may be eligible for a
- In the case of when a
vow.fessis executed, the debt
tabis added to
Sin, which blocks that
tabamount to be sent to the
flopauction and all of the DAI is recovered with a
flipauction. In theory, unblocking the
tabamount in the
Sinshouldn't be necessary, but in practice it actually is. If this debt is not unblocked, then when we have a real need to send a
flopauction, we might have a big
Sinthat blocks it. To summarize, this means that each registry of
sin[era]that has an amount > 0 should be
flog'ed before kicking a
flopauction (this is because in order to kick the whole thing, you need every register to be 0, otherwise, it would be blocking debt).
sin[era]isn’t required to be a single
bite, it will group all the
bite’s that are in the same Ethereum block together.
vow.Ash. Where the components within
vow.Ashare defined as:
vat.sin(vow)- total bad debt
vow.Sin- debt blocked
vow.Ash- debt in auctions
Vow.sinrecords individual portions of debt (marked with a timestamp). These are not directly auctioned off, but cleared when
- If the
Sinis not covered by holding a
flipauction within the designated wait time (
Sin“matures” and gets marked as bad debt to the
Vow. This bad debt can be covered through a debt auction (
flop) when it exceeds a minimum value (the
lotsize). In short, the time between the debt being added to the
sinqueue and becoming "mature" (when it
flogs off the queue and is eligible for
Flopauction) is the amount of time that
Flipauction has to clear that debt. This is due to the fact that when a
Flipauction receives DAI, it decreases the
Vow's DAI balance in the
- Note: In this case, there is a risk that a circumstance can occur where the
Vow.waitis different than the
Flip.tau. The main risk being related to
tau, which would result in debt auctions running before the associated seized-collateral auctions could complete.
Sincan affect the system in the following way:
- 1.There can be separate
Vows each with their own
- 2.In the case of an upgrade, if we remove a
sin, this can create untracked bad debt in the system.
Vow.Sin- This calculates the total queued debt in the system.
Vow.Ash- This calculates the total on-auction debt.
It is important to note that the Maker Protocol will deviate from its equilibrium. This occurs when it receives system debt and system surplus through the collateral auctions and Vault stability fee accumulation. The
Vowcontract contains the logic to trigger both the debt (
flop) and surplus (
flap) auctions, which work to correct the system’s monetary imbalances.
- System Debt: In the case where Vaults are bitten (liquidated), their debt is taken on by the
Vowcontract as a
Sin(the system debt unit). The
Sinamount is then placed in the
Sinqueue. Note: When the
Sinis not covered by a
flipauction (within the dedicated
Sinis considered to have bad debt to the
Vow. This bad debt is then covered through a debt auction (
flop) when it exceeds a minimum value (the
- System Surplus: Occurs from stability fee accumulation, resulting in additional internal Dai in the
Vow. This surplus is then discharged through a surplus auction (
- When the
Vowis upgraded, there are multiple references to it that must be updated at the same time (
Vowis the only user with a non-zero
Sinbalance (not a
vatinvariant as there can be multiple
- Ilk storage is split across the
catalso stores the liquidation penalty and maximum auction size.
- A portion of the Stability Fee is allocated for the Dai Savings Rate (DSR) by increasing the amount of
- Setting an incorrect value for
vowcan cause the surplus to be lost or stolen.
- A failure mode could arise when no actors call
healto reconcile/queue the debt.
- A failure mode could arise if a user does not call
flopto kick off auctions.
Vow.wait, when set too high (
waitis too long), the
flopauctions can no longer occur. This provides a risk of undercollateralization.
Vow.wait, when set too low, can cause too many
flopauctions, while preventing
flapauctions from occurring.
Vow.bump, when set too high, can result in no
flapauctions being possible. Thus, if no
flapauction takes place, there will be no MKR bidding as part of that process and, accordingly, no automated MKR burn as a result of a successful auction.
Vow.bump, when set too low, results in
flapauctions not being profitable for participants (
lotsize is worth less than gas cost). Thus, no MKR will be bid during a
flapauction and, as a result, there will be no automated MKR burn.
Vow.sump, when set too high, no
flopauctions are possible. This results in the system not being able to recover from an undercollateralized state.
Vow.sump, when set too low,
flopauctions are not profitable for participants (where the
lotsize is worth less than gas cost). This results in MKR inflation due to automated MKR minting.
Vow.dump, when set too high,
flopauctions risk not being able to close or mint a large amount of MKR, creating a risk of MKR dilution and the possibility of a governance attack.
Vow.dump, when set too low,
flopauctions have to be
kicked many times before they will be interesting to keepers.
Vow.hump, when set too high, the
flapauctions would never occur. If a
flapauction does not occur, there is no sale of surplus, and thus, no burning of bid MKR.
Vow.hump, if set too low, can cause surplus to be auctioned off via
flapauctions before it is used to cancel
sinfrom liquidations, necessitating
flopauctions and making the system run inefficiently.