MakerDAO Documentation Overview

Introduction

MakerDAO is a decentralized organization dedicated to bringing stability to the cryptocurrency economy. The Maker Protocol employs a two-token system. The first being, Dai, a collateral-backed stablecoin that offers stability. The Maker Foundation and the MakerDAO community believe that a decentralized stablecoin is required to have any business or individual realize the advantages of digital money. Second, there is MKR, a governance token that is used by stakeholders to maintain the system and manage Dai. MKR token holders are the decision-makers of the Maker Protocol, supported by the larger public community and various other external parties.

Maker is unlocking the power of decentralized finance for everyone by creating an inclusive platform for economic empowerment; enabling everyone with equal access to the global financial marketplace.

With the new version of the Maker Protocol, Multi Collateral Dai (MCD), being released and live on the main Ethereum network, we wanted to go over a few of the changes and features that it comes with. The biggest change to the Maker Protocol is that it now accepts any Ethereum-based asset as collateral to generate Dai given that it has been approved by MKR holders and has been given specific, corresponding Risk Parameters through the Maker decentralized governance process.

Additionally, there are a few other newly introduced features that come with the MCD upgrade. These new features include:

• Support for multiple Vault collateral types (Launching with ETH and BAT)
• More robust peg ensuring mechanisms (MKR acting as backstop)

• Stability fees paid every block, rather than on Dai repayment

• MKR and governance remains the same

The Maker Protocol Smart Contract Modules System

• Module Name: DAI Module

• Type/Category: Proxy —> Dai.sol and DaiJoin.sol

• Contract Sources:

1. Introduction (Summary)

The origin of DAI was designed to represent any token that the core system considers equal in value to its internal debt unit. Thus, the DAI Module contains the DAI token contract and all of the adapters DaiJoin adapters.

2. Module Details

Glossary (DAI)

Key Functionalities (as defined in the smart contract)

Mint - Mint to an address

Burn - Burn at an address

Push - Transfer

Pull - Transfer From

Move - Transfer From

Approve - Allow pulls and moves

Permit - Approve by signature

Other

name - Dai Stablecoin

symbol - DAI

version - 1

decimals - 18

totalSupply - Total DAI Supply

balanceOf(usr: address) - User balance

allowance(src: address, dst: address) - Approvals

nonces(usr: address) - Permit nonce

Glossary (Join)

• vat - storage of the Vat’s address

• ilk - id of the Ilk for which a GemJoin is created for

• gem - the address of the ilk for transferring

• dai - the address of the dai token

• one - a 10^27 uint used for math in DaiJoin

Core Module Components Documentation

3. Key Mechanism and Concepts

Why are these components important to the Multi-Collateral Dai (MCD) System?

The Dai contract is the user facing ERC20 contract maintaining the accounting for external Dai balances. Most functions are standard for a token with changing supply, but it also notably features the ability to issue approvals for transfers based on signed messages.

Join consists of three smart contracts, one of which is the DaiJoin contract. Each join contract is created specifically to allow the given token type to be joined to the vat. Because of this, each join contract has slightly different logic to account for the different types of tokens within the system. The DaiJoin contract allows users to withdraw their Dai from the system into a standard ERC20 token.

4. Gotchas (Potential sources of user error)

• There are limited sources of user error in the join contracts system due to the limited functionality of the system. Barring a contract bug, should a user call join by accident they could always get their tokens back through the corresponding exit call on the given join contract. The main issue to be aware of here would be a well-executed phishing attack. As the system evolves and potentially more join contracts are created, or more user interfaces are made, there is the potential for a user to have their funds stolen by a malicious join contract which does not actually send tokens to the vat, but instead to some other contract or wallet.

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

There could potentially be a vat upgrade that would require new join contracts to be created.

If a gem contract were to go through a token upgrade or have the tokens frozen while a user's collateral was in the system, there could potentially be a scenario in which the users were unable to redeem their collateral after the freeze or upgrade was finished. This seems to be a small risk though because it would seem likely that the token going through this upgrade would want to work alongside the maker community to be sure this was not an issue.

• Contract Name: Vat.sol

• Type/Category: DSS —> Core System Accounting

1. Introduction (Summary)

The 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 dss.

2. Contract Details

Glossary (Vat - Vault Engine)

• gem: collateral tokens.

• dai: stablecoin tokens.

• sin: unbacked stablecoin (system debt, not belonging to any urn).

• ilks: a mapping of Ilk types.

• Ilk: a collateral type.

  • Art: total normalized stablecoin debt.

  • rate: stablecoin debt multiplier (accumulated stability fees).

  • 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.

  • dust: the debt floor for a specific collateral type.

• urns: a mapping of Urn types.

• Urn: a specific Vault.

  • ink: collateral balance.

  • art: normalized outstanding stablecoin debt.

• init: create a new collateral type.

• 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 (vice).

• fold: modify the debt multiplier, creating / destroying corresponding debt.

• suck: mint unbacked stablecoin (accounted for with vice).

• Line: the total debt ceiling for all collateral types.

• 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.

• 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.

  • hope: enable wish for a pair of addresses.

  • nope: disable wish for a pair of addresses.

Note: art and Art represent normalized debt, i.e. a value that when multiplied by the correct rate gives the up-to-date, current stablecoin debt.

Accounting

• 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 Ilk.

• debt is vice plus the sum of Ilk.Art * Ilk.rate across all ilks.

Collateral

• gem can always be transferred to any address by it's owner.

Dai

• dai can only move with the consent of it's owner.

• dai can always be transferred to any address by it's owner.

3. Mechanisms & Concepts

The core Vault, Dai, and collateral state is kept in the Vat. 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:

1. Dai cannot exist without collateral:

• An ilk is a particular type of collateral.

• Collateral gem is assigned to users with slip.

• Collateral gem is transferred between users with flux.

2. The Vault data structure is the Urn:

• has ink - encumbered collateral

• has art - encumbered, normalized debt

3. Similarly, a collateral is an Ilk:

• has Art - encumbered, normalized debt

• has rate - debt scaling factor (discussed further below)

• has spot - price with safety margin

• has line - debt ceiling

• has dust - debt floor

Note: Above, when using the term "encumbered", this refers to being "locked in a Vault".

Vault Management

• Vaults are managed via frob(i, u, v, w, dink, dart), which modifies the Vault of user u, using gem from user vand creating dai for user w.

• Vaults are confiscated via grab(i, u, v, w, dink, dart), which modifies the Vault of user u, giving gem to user vand creating sin for user w. grab is the means by which Vaults are liquidated, transferring debt from the Vault to a users sin balance.

• 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 dai and sin balances.

  • Note: Only the Vow will ever have sin, so only the Vow can successfully call heal. This is because whenever grab and 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.

  • Note: heal can only be called with a positive number (uint) and will sub(dai[u]) along with subing the sin.

• The quantity dai can be transferred between users with move.

Rate Updates via fold(bytes32 ilk, address u, int rate)

An ilk's 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 Vaults collateralized with the specified Ilk are updated implicitly via the addition of rate to Ilk.rate.

For more information on Rates and System Stabilization, see the Rates Module and System Stabilizer Module documentation below:

4. Gotchas

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.

5. Failure Modes

Coding Error

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.

Feeds

The 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

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.

Adapters

The 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.

• Module Name: System Stabilizer

• Type/Category: DSS —> System Stabilizer Module (Vow.sol, Flap.sol, Flop.sol)

• Contract Sources:

1. Introduction (Summary)

The System Stabilizer Module's purpose is to correct the system when the value of the collateral backing Dai drops below the liquidation level (determined by governance) when the stability of the system is at risk. The system stabilizer module creates incentives for Auction Keepers (external actors) to step in and drive the system back to a safe state (system balance) by participating in both debt and surplus auctions and, in turn, earn profits by doing so.

For a better understanding of how the Auction Keepers relate to the System Stabilization Mechanism, read the following resources:

2. Module Details

The System Stabilizer Module has 3 core components consisting of the Vow, Flop, and Flap contracts.

System Stabilizer Components Documentation

3. Key Mechanisms & Concepts

Summary of the System Stabilizer Module Components

1. The Vow represents the overall Maker Protocol's balance (both system surplus and system debt). The purpose of the vow is to cover deficits via debt auctions and discharge surpluses via surplus auctions.

2. The Flopper (Debt Auction) is used to get rid of the Vow’s debt by auctioning off MKR for a fixed amount of internal system Dai. When flop auctions are kicked off, bidders compete with decreasing bids of MKR. After the auction settlement, the Flopper sends received internal Dai to the Vow in order to cancel out its debt. Lastly, the Flopper mints the MKR for the winning bidder.

3. The Flapper (Surplus Auction) is used to get rid of the Vow’s surplus by auctioning off a fixed amount of internal Dai for MKR. When flap auctions are kicked off, bidders compete with increasing amounts of MKR. After auction settlement, the Flapper burns the winning MKR bid and sends internal DAI to the winning bidder.

How the System Stabilizer Module Interacts with the other DSS Modules

How do the Vow, Flop and Flap contracts help the MCD system operate?

Vow

When the Maker Protocol receives system debt and system surplus through collateral auctions and CDP stability fee accumulation, it will deviate from system equilibrium. The job of the Vow is to bring it back to system equilibrium.

The Priority of the Vow

1. To kick-off debt and surplus auctions (Flop and Flap), which in turn, corrects the system’s imbalances.

Flop

The purpose of debt auctions is to cover the system deficit, which is resembled by Sin(the total debt in the queue). It sells an amount of minted MKR and purchases Dai that will be canceled 1-to-1 with Sin.

The Priorities of the Flopper:

1. To raise an amount of Dai equivalent to the amount of bad debt as fast as possible.

2. To minimize the amount of MKR inflation.

Flap

The purpose of the surplus auctions is to release Dai surplus from the Vow while users bid with MKR, which will be burned, thus reducing the overall MKR supply. It will sell a fixed amount of Dai to purchase and burn MKR.

The Priority of the Flapper:

1. To mechanically reduce the MKR supply when auctioning off Dai surplus.

4. Gotchas (Potential Sources of User Error)

Auction Keepers

• This failure mode is due to the fact that there is nothing the system can do to stop a user from paying significantly more than the fair market value for the token in an auction (this goes for all auction types, flip, flop, and flap).

• Keepers that are performing badly are primarily at risk during the dent phase since they could return too much collateral to the original CDP and end up overpaying (i.e. pay too much Dai (bid) for too few gems (lot)).

  • Note: This does not apply to the Flap contract (Flop and Flip only)

When no Auction Keepers Bid:

• For both the Flip and Flap auctions, the tick function will restart an auction if there have been 0 bids and the original end has passed.

• In the case of a Flop auction expiring without receiving any bids, anyone can restart the auction by calling tick. Along with restarting the auction, it also includes a necessary increase of the initial lot size by pad (default to 50%). This extra process is because the lack of bidding for the lot could be due market circumstances, where the lot value is too low and is no longer enough for recovering the bid amount.

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

Governance Trade-offs

• beg

  • If too high, it would discourage bidding and create a less efficient auction mechanism.

  • If too low, it would not be that significant but would encourage small bids and increase the likelihood of the Bid.end being hit before the "true" price was found.

• ttl

  • If too high, it would cause the winning bidder to wait "too long" to collect their winnings (depending on the situation, possibly subjecting them to market volatility).

  • If too low, it would increase the likelihood of bids expiring before other bidders get a chance to respond.

• tau

  • If too high, it would not have that significant of an impact as auctions would still operate normally based on the Bid.tic.

  • If too low, it would increase the chance that an auction will end before the "true" price was found.

Other Non-Obvious Auction Failure Modes (This is for all auction types: Flip, Flop, Flap)

Potential Issues around Network Congestion

When auctioning off collateral tokens, bids are finalized after an interval of time (ttl) has passed. Hence, in the case when extreme network congestion occurs, ttl and auctions are affected because they can take longer than three hours to confirm a transaction. Therefore, due to Ethereum network congestion, this can result in auctions settling for less than the fair market value. Due to this potential issue, bidders need to calculate network congestion risks when making bids.

Example:

When high network congestion occurs, where common APIs can be shut down due to denial of service (DoS), and where high gas prices are present, this can result in bidding becoming extremely expensive regardless of whether bids win or not. Unfortunately, this also results in only enabling those who have the experience and technical knowledge to build their own transactions are able to use and participate in auctions. Therefore, auctions thus settle for less than the fair market value.

Transaction-reordering / Front Running Attacks on Auctions

• Contract Name: join.sol

• Type/Category: DSS —> Token Adapter Module

• Etherscan

1. Introduction (Summary)

Join consists of three smart contracts: GemJoin, ETHJoin, and DaiJoin: GemJoin - allows standard ERC20 tokens to be deposited for use with the system. ETHJoin - allows native Ether to be used with the system. DaiJoin - allows users to withdraw their Dai from the system into a standard ERC20 token.

Each join contract is created specifically to allow the given token type to be join'ed to the vat. Because of this, each join contract has slightly different logic to account for the different types of tokens within the system.

2. Contract Details:

Glossary (Join)

• vat - storage of the Vat’s address.

• ilk - id of the Ilk for which a GemJoin is created for.

• gem - the address of the ilk for transferring.

• dai - the address of the dai token.

• one - a 10^27 uint used for math in DaiJoin.

• live - an access flag for the join adapter.

• dec - decimals for the Gem.

Every join contract has 4 public functions: a constructor, join, exit, and cage. The constructor is used on contract initialization and sets the core variables of that join contract. Join and exit are both true to their names. Join provides a mechanism for users to add the given token type to the vat. It has slightly different logic in each variation, but generally resolves down to a transfer and a function call in the vat. Exit is very similar, but instead allows the the user to remove their desired token from the vat. Cage allows the adapter to be drained (allows tokens to move out but not in).

3. Key Mechanisms & Concepts

The GemJoin contract serves a very specified and singular purpose which is relatively abstracted away from the rest of the core smart contract system. When a user desires to enter the system and interact with the dss contracts, they must use one of the join contracts. After they have finished with the dss contracts, they must call exit to leave the system and take out their tokens. When the GemJoin gets caged by an authed address, it can exit collateral from the Vat but it can no longer join new collateral.

User balances for collateral tokens added to the system via join are accounted for in the Vat as Gem according to collateral type Ilk until they are converted into locked collateral tokens (ink) so the user can draw Dai.

The DaiJoin contract serves a similar purpose. It manages the exchange of Dai that is tracked in the Vat and ERC-20 Dai that is tracked by Dai.sol. After a user draws Dai against their collateral, they will have a balance in Vat.dai. This Dai balance can be exit' ed from the Vat using the DaiJoin contract which holds the balance of Vat.dai and mint's ERC-20 Dai. When a user wants to move their Dai back into the Vat accounting system (to pay back debt, participate in auctions, pack bag's in the End, or utilize the DSR, etc), they must call DaiJoin.join. By calling DaiJoin.join this effectively burn's the ERC-20 Dai and transfers Vat.dai from the DaiJoin's balance to the User's account in the Vat. Under normal operation of the system, the Dai.totalSupply should equal the Vat.dai(DaiJoin) balance. When the DaiJoin contract gets cage'd by an auth'ed address, it can move Dai back into the Vat but it can no longer exit Dai from the Vat.

4. Gotchas (Potential source of user error)

The main source of user error with the Join contract is that Users should never transfer tokens directly to the contracts, they must use the join functions or they will not be able to retrieve their tokens.

There are limited sources of user error in the join contract system due to the limited functionality of the system. Barring a contract bug, should a user call join by accident they could always get their tokens back through the corresponding exit call on the given join contract.

The main issue to be aware of here would be a well-executed phishing attack. As the system evolves and potentially more join contracts are created, or more user interfaces are made, there is the potential for a user to have their funds stolen by a malicious join contract which does not actually send tokens to the vat, but instead to some other contract or wallet.

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

There could potentially be a vat upgrade that would require new join contracts to be created.

If a gem contract were to go through a token upgrade or have the tokens frozen while a user's collateral was in the system, there could potentially be a scenario in which the users were unable to redeem their collateral after the freeze or upgrade was finished. This scenario likely presents little risk though because the token going through this upgrade would more than likely want to work alongside the Maker community to be sure this was not an issue.

• Contract Name: spot.sol

• Type/Category: DSS —> Core Module

1. Introduction

The Spot liaison between the oracles and the core contracts. It functions as an interface contract and only stores the current ilk list.

2. Contract Details

Math

• All mathematical operations will revert on overflow or underflow

Complexity

• All methods execute in constant time

Variables

• ilk a given collateral type

• ilk.pip the contract which holds the current price of a given ilk

• ilk.mat the liquidation ratio for a given ilk

• vat the core of the mcd system

• par value of DAI in the reference asset (e.g. $1 per DAI)

Collateral

• Only authorized users can update any variables in contract

3. Key Mechanisms & Concepts

Poke

poke is the only non-authenticated function in spot. The function takes in a bytes32 of the ilk to be "poked". poke calls two external functions:

2. When calculating the spot, the par is crucial to this calculation as it defines the relationship between DAI and 1 unit of value in the price. The val is then divided by the par(to get a ratio of val to DAI) and then the resulting value is divided by the ilk.mat. This gives us the current spot price for the given ilk.

3. file is then called after calculating the spot. This updates the vat with the current liquidation price of the ilk which the function was called for.

4. Gotchas

The methods in the spotter are relatively basic compared to most other portions of dss. There is not much room for user error in the single unauthed method poke. If an incorrect bytes32 is supplied the call will fail.

Any module that is authed against the spot has full root access, and can, therefore, add and remove which ilks can be "poked". While not completely breaking the system, this could cause considerable risk.

5. Failure Modes

Coding Error

A bug in spot would most likely result in the prices for collaterals not being updated anymore. In this case, the system would need to authorize a new spot which would then be able to update the prices. Overall this is not a catastrophic failure as this would only pause all price fluctuation for some period.

Feeds

The spot 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.

Spot Price Becoming Stale

When poke is not called frequently enough, the Vat's spot price will become stale. This could arise for a few reasons including tragedy of the commons or miner collusion and could lead to negative outcomes such as inappropriate liquidations, or the prevention of liquidations that should be possible.

• Contract Name: dai.sol

• Type/Category: DSS —> Dai Module

1. Introduction (Summary)

The Dai contract is the user-facing ERC20 token contract maintaining the accounting for external Dai balances. Most functions are standard for a token with changing supply, but it also notably features the ability to issue approvals for transfers based on signed messages.

2. Contract Details

DAI (Glossary)

Key Functionalities (as defined in the smart contract)

Mint - Mint to an address

Burn - Burn at an address

Push - Transfer

Pull - Transfer From

Move - Transfer From

Approve - Allow pulls and moves

Permit - Approve by signature

Other

name - Dai Stablecoin

symbol - DAI

version - 1

decimals - 18

totalSupply - Total DAI Supply

balanceOf(usr: address) - User balance

allowance(src: address, dst: address) - Approvals

nonces(usr: address) - Permit nonce

Units

• wad - fixed point decimal with 18 decimals (for basic quantities, e.g. balances).

3. Key Mechanisms & Concepts

Differences From ERC20:

1. transferFrom in the DAI contract works in a slightly different form than the generic transferFrom function. The DAI contract allows for "unlimited approval". Should the user approve an address for the maximum uint256 value, then that address will have unlimited approval until told otherwise.

2. push, pull & move are aliases for transferFrom calls in the form of transferFrom(msg.sender, usr, amount) , transferFrom(usr, msg.sender, amount) & transferFrom(src, dst, amount) .

3. permit is a signature-based approval function. This allows for an end-user to sign a message which can then be relayed by another party to submit their approval. This can be useful for applications in which the end-user does not need to hold ETH.

   • In order to use this functionality, a user's address must sign a message with the holder, spender, nonce, expiry and the allowed amount. This can then be submitted to Permit() to update the user's approval.

4. Gotchas (Potential Source of User Error)

Unlimited allowance is a relatively uncommon practice (though becoming more common). This could be something used to trick a user by a malicious contract into giving access to all their DAI. This is concerning in upgradeable contracts where the contract may appear innocent until upgraded to a malicious contract.

There is a slight deviation in transferFrom functionality: If the src == msg.sender the function does not require approval first and treats it as a normal transfer from the msg.sender to the dst.

Built-in meta-transaction functionality of Dai

The Dai token provides offchain approval, which means that as an owner of an ETH address, you can sign a permission (using the permit() function) which basically grants allowance to another ETH address. The ETH address that you provide permission to can then take care of the execution of the transfer but has an allowance.

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

• N/a

• Contract Name: flop.sol

• Type/Category: DSS —> System Stabilizer Module

1. Introduction (Summary)

Summary: Debt Auctions are used to recapitalize the system by auctioning off MKR for a fixed amount of DAI. In this process, bidders compete by offering to accept decreasing amounts of MKR for the DAI they will end up paying.

2. Contract Details

Flopper (Glossary)

• flop: debt auction (covering debt by inflating MKR and selling for stablecoins)

• lot: quantity up for auction / gems for sale (MKR)

• guy: high bidder (address)

• gal: recipient of auction income / receives dai income (this is the Vow contract)

• ttl: bid lifetime (Max bid duration / single bid lifetime)

• beg: minimum bid decrease

• pad: Increase for lot size during tick (default to 50%)

• tau: maximum auction duration

• end: when the auction will finish / max auction duration

• kick: start an auction / Put up a new MKR bid for auction

• dent: make a bid, decreasing the lot size (Submit a fixed DAI bid with decreasing lot size)

• deal: claim a winning bid / settles a completed auction

• vat - the Vat's address

• gem- MKR Token (address)

• kicks - Total auction count, used to track auction ids

• live - Cage flag

• wards [usr: address], rely/deny/auth - Auth mechanisms

• Bid - State of a specific Auction {bid, lot, guy, tic, end}

• bid - Bid amount inDAI / DAI paid

• tic - Bid expiry

• tick - restarts an auction

Parameters Set By Governance

• The Maker Governance voters determine the debt limit. The Debt auction is triggered when the system has DAI debt above that limit.

• Maker Governance sets the Vow.dump which determines the starting lot for an auction as well as the pad which determines how much that lot can increase during tick.

• The contracts that are auth'ed to call kick() (should only be Vow) and file() to change beg, ttl, tau (should only be governance contracts).

Informational Note: The cage sets the Flop to not be live anymore and the yank is used during Global Settlement in order to return a bid to the bidder since the dent and deal can no longer be called.

3. Key Mechanisms & Concepts

The Flop is a reverse auction, where keepers bid on how little MKR they are willing to accept for the fixed Dai amount they have to pay at auction settlement. The bidders will basically compete with decreasing lot amounts of MKR for a fixed bid amount of Dai. Once kicked, the bid is set to the flop auction bid size (Vow.sump) and lot is set to a sufficiently large number (Vow.dump). The auction will end when the latest bid duration (ttl) has passed OR when the auction duration (tau) has been reached. The payback process begins when the first bid is placed. The first bid will pay back the system debt and each subsequent bid will pay back the previous (no longer winning) bidder. When the auction is over, the process ends by cleaning up the bid and minting MKR for the winning bidder.

If the auction expires without receiving any bids, anyone can restart the auction by calling tick(uint auction_id). This will do two things:

1. It resets bids[id].end to now + tau

2. It resets bids[id].lot to bids[id].lot * pad / ONE

Bidding Requirements during an auction

During an auction, lot amounts will decrease by a percentage with each new dent decreasing the lot by the beg for the same bid of Dai. For example, the beg could be set to 5%, meaning if the current bidder has a lot of 10 (MKR) for a bid of 100 (Dai), then the next bid must pass at most a lot of 9.5 (MKR) for a bid of 100 (Dai).

Placing Bids

When a bid is beaten out by another bidder, the new winner's internal DAI balance is used to refund the previous winning bidder. Once placed, bids cannot be canceled.

Example bidding flow:

1. Vow kicks a new Flop Auction.

2. Bidder 1 makes a bid that decreases the lot size by beg from the initial amount. Bidder 1's DAI balance in the Vat is decreased by bid and the Vow's DAI balance in the Vat is increased by bid.

3. Bidder 2 makes a bid that decreases Bidder 1's lot by beg. Bidder 2's DAI balance in the Vat is decreased by bid and Bidder 1's DAI balance in the Vat is increased by bid (thereby refunding Bidder 1 for their now-losing bid).

4. Bidder 1 makes a bid that decreases Bidder 2's lot by beg. Bidder 1's DAI = Vat.dai[bidder1] - bid; Bidder 2's DAI = Vat.dai[bidder2] + bid.

5. Bidder 2 (and all the other bidders within the auction) decide it is no longer worth it to continue to accept lower lots, so they stop bidding. Once the Bid.tic expires, Bidder 1 calls deal and new MKR tokens are minted to their address (MKR token contract.balances(Bidder1) = MKR.balances(Bidder1) + lot).

Note: During a Flop auction, the beg is actually the minimum decrease amount. In dent the new bid has to have a lot * beg that is less than or equal to the current lot size. Since the theory of the Flop auction is that a bidder’s offer is to take fewer and fewer MKR tokens (lot) for the same amount of dai (bid) then the beg is the amount each bid's offer should decrease by.

4. Gotchas (Potential Source of User Error)

Keepers

• This failure mode is due to the fact that there is nothing the system can do stop a user from paying significantly more than the fair market value for the token in an auction (this goes for all auction types, flip, flop, and flap).

• This means, in the case of Flop, that since the Dai amount is fixed for the entire auction, the risk to the keeper is that they would make a "winning" bid that pays the bid amount in Dai but does not receive any MKR (lot == 0). Subsequent executions of this bad strategy would be limited by the amount of Dai (not MKR) in their vat balance.

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

1. Flopper has the potential to issue an excessively huge amount of MKR and despite the mitigation efforts (the addition of the dump and pad parameters), if dump is not set correctly by governance, the huge issuance of MKR could still occur.

• Contract Name: flap.sol

• Type/Category: DSS —> System Stabilizer Module

1. Introduction (Summary)

Summary: Flapper is a Surplus Auction. These auctions are used to auction off a fixed amount of the surplus Dai in the system for MKR. This surplus Dai will come from the Stability Fees that are accumulated from Vaults. In this auction type, bidders compete with increasing amounts of MKR. Once the auction has ended, the Dai auctioned off is sent to the winning bidder. The system then burns the MKR received from the winning bid.

2. Contract Details

Flapper (Glossary)

• Flap - surplus auction (selling stablecoins for MKR) [contract]

• wards [usr: address] - rely/deny/auth Auth Mechanisms [uint]

• Bid - State of a specific Auction[Bid]

  • bid - quantity being offered for the lot (MKR) [uint]

  • lot - lot amount (DAI) [uint]

  • guy - high bidder [address]

  • tic - Bid expiry [uint48]

  • end - when the auction will finish [uint48]

• bids (id: uint) - storage of all Bids by id [mapping]

• vat - storage of the Vat's address [address]

• ttl - bid lifetime / max bid duration (default: 3 hours) [uint48]

• lot - lot amount (DAI) [uint]

• beg - minimum bid increase (default: 5%) [uint]

• tau - maximum auction duration (default: 2 days) [uint48]

• kick - start an auction / put up a new DAI lot for auction [function]

• tend - make a bid, thus increasing the bid size / submit an MKR bid (increasing bid) [function]

• deal - claim a winning bid / settling a completed auction [function]

• gem - MKR Token [address]

• kicks - total auction count [uint]

• live - cage flag [uint]

• file - used by governance to set beg, ttl, and tau [function]

• yank - is used during Global Settlement to move tend phase auctions to the End by retrieving the collateral and repaying DAI to the highest bidder. [function]

• tick() - resets the end value if there has been 0 bids and the original end has passed.

Parameters Set By Governance

The Maker Governance voters determine the surplus limit. The surplus auction is triggered when the system has an amount of Dai above that set limit.

• Parameters Set through file:

  • beg

  • ttl

  • tau

Note: MKR governance also determines the Vow.bump which sets the Bid.lot for each Flap auction and the Vow.hump which determines the surplus buffer.

Authorizations

auth - check whether an address can call this method [modifier function]

• rely - allow an address to call auth'ed methods [function]

• deny - disallow an address from calling auth'ed methods [function]

3. Key Mechanisms & Concepts

Once the auction has begun, a fixed amount (lot) of DAI is put up for sale. Bidders then complete for a fixed lot amount of DAI with increasing bid amounts of MKR. In other words, this means that bidders will keep placing MKR bid amounts in increments greater than the minimum bid increase amount that has been set (this is the beg in action).

The surplus auction officially ends when the bid duration ends (ttl) without another bid getting placed OR when auction duration (tau) has been reached. At auction end, the MKR received for the surplus DAI is then sent to be burnt thereby contracting the overall MKR supply.

4. Gotchas (Potential source of user error)

Keepers

• This failure mode is due to the fact that there is nothing the system can do to stop a user from paying significantly more than the fair market value for the token in an auction (this goes for all auction types, flip, flop, and flap).

• Keepers that are performing badly in a flap auction run the risk of overpaying MKR for the DAI as there is no upper limit to the bid size other than their MKR balance.

Bid Increments During an Auction

During tend, bid amounts will increase by a beg percentage with each new tend. The bidder must know the auction's id, specify the right amount of lot for the auction, bid at least beg % more than the last bid and must have a sufficient MKR balance.

One risk is "front-running" or malicious miners. In this scenario, an honest keeper's bid of [Past-bid + beg%] would get committed after the dishonest keeper's bid for the same, thereby preventing the honest keeper's bid from being accepted and forcing them to rebid with a higher price ((Past-bid + beg) + beg)). The dishonest keeper would need to pay higher gas fees to try to get a miner to put their transaction in first or collude with a miner to ensure their transaction is first. This could become especially important as the bid reaches the current market rate for MKR<>DAI.

Quick Example:

The beg could be set to 3%, meaning if the current bidder has placed a bid of 1 MKR, then the next bid must be at least 1.03 MKR. Overall, the purpose of the bid increment system is to incentivize early bidding and make the auction process move quickly.

Placing Bids Incorrectly

Bidders send MKR tokens from their addresses to the system/specific auction. If one bid is beat by another, the losing bid is refunded back to that bidder’s address. It’s important to note, however, that once a bid is submitted, there is no way to cancel it. The only possible way to have that bid returned is if it is outbid (or if the system goes into Global Settlement).

Illustration of the bidding flow:

1. Vow kick's a new Flap Auction.

2. Bidder 1 sends a bid (MKR) that increases the bid above the initial 0 value set during the kick. Bidder 1's MKR balance is decreased and the Flap's balance is increased by the bid size. bid.guy is reset from the Vow address to Bidder 1's and bid.tic is reset to now + ttl.

3. Next, Bidder 2 makes a bid that increases Bidder 1's bid by at least beg. Bidder 2's MKR balance is decreased and Bidder 1's balance is increased by Bidder 1's bid. The difference between Bidder 2's and Bidder 1's bid is sent from Bidder 2 to the Flap.

4. Bidder 1 then makes a bid that increases Bidder 2's bid by at least beg. Bidder 1's MKR balance is decreased and Bidder 2's MKR balance is increased by Bidder 2's bid. The amount Bidder 1 increased the bid is then sent from Bidder 1 to the Flap.

5. Bidder 2, as well as all the other bidders participating within the auction, decide it is no longer worth it to continue to bid higher bids, so they stop making bids. Once the Bid.tic expires, Bidder 1 calls deal and the surplus DAI tokens are sent to the winning bidder's address (Bidder 1) in the Vat and the system then burns the MKR received from the winning bidder. gem.burn(address(this), bids[id].bid).

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

2. Other Failure Modes

• Resulting from when MKR is burned

  • There is the possibility where a situation arises where the MKR token makes the transaction revert (e.g. gets stopped or the Vow's permission to call burn() is revoked). In a case like this, deal can't succeed until someone fixes the issue with the MKR token. In the case of stoppage, this could include the deploying of a new MKR token. This new deployment could be completed by any individual using the MCD System but governance would need to add it to the system. Next, it would need to replace the old surplus and debt auctions with the new ones using the new MKR token. Lastly, it is crucial to enable the possibility to vote with the new version as well.

• When there is massive surplus

  • This would result in many Flap auctions occurring as the surplus over bump + hump is always auctioned off in bump increments. However, auctions run concurrently, so this would "flood the keeper market" and possibly result in too few bids being placed on any auction. This could happen through keepers not bidding on multiple auctions at once, which would result in network congestion because all keepers are trying to bid on all of the auctions. This could also lead to possible keeper collusion (if the capital pool is large enough, they may be more willing to work together to split it evenly at the system's expense).

• Contract Name: vow.sol

• Type/Category: DSS —> System Stabilizer Module

1. Introduction (Summary)

The Vow contract represents the Maker Protocol's balance sheet. In particular, the Vow acts 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 (Flap) auctions.

Pictured:

• Inter-contract calls necessary for the module function

Not pictured:

• cage calls from Vow to Flap and Flop

• Auction and user auction interactions

• Governance calls / interactions

2. Contract Details

Vow (Glossary)

• 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 lot/sump

• 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.

Liquidations Manager

• 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 - vow calls heal on the vat contract to cancel out surplus and debt. (Optimize debt buffer (vat.heal)).

• Kiss - Cancels out surplus and on-auction debt. Release on-auction debt and Heal (vat.heal).

• Flap - Trigger a surplus auction (flapper.kick)

• Flop - Trigger a deficit auction (flopper.kick)

Authorization

The vow contract calls kick on flop and flap to start an auction (debt and surplus auctions, respectively).

• Flopper (Debt auctions) - If the deficit is not covered in the forward auction portion of the flip auction, 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 Vow in 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 Data

• 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

Debt (SIN) Queue

The Sin is 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 Vow as recorded in Vat.dai[Vow]. For instance, if Vat.sin[Vow] is greater than the sum of Vow.Sin and the Ash (debt currently on auction), then the difference may be eligible for a Flop auction.

Notes:

• In the case of when a cat.bite / vow.fess is executed, the debt tab is added to sin[now] and Sin, which blocks that tab amount to be sent to the flop auction and all of the DAI is recovered with a flip auction. In theory, unblocking the tab amount in the Sin shouldn'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 flop auction, we might have a big Sin that blocks it. To summarize, this means that each registry of sin[era] that has an amount > 0 should be flog'ed before kicking a flop auction (this is because in order to kick the whole thing, you need every register to be 0, otherwise, it would be blocking debt).

  • Each 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.

  • The auction-keeper will flog every era with positive Sin if the woe+ Sin >= sump, where woe = vat.sin[vow] - vow.Sin - vow.Ash. Where the components within vat.sin(vow) - vow.Sin - vow.Ash are defined as:

    • vat.sin(vow)- total bad debt

    • vow.Sin - debt blocked

    • vow.Ash - debt in auctions

• Vow.sin records individual portions of debt (marked with a timestamp). These are not directly auctioned off, but cleared when flog is called.

• If the Sin is not covered by holding a flip auction within the designated wait time (tau), the 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 lot size). In short, the time between the debt being added to the sin[] queue and becoming "mature" (when it flogs off the queue and is eligible for Flop auction) is the amount of time that Flip auction has to clear that debt. This is due to the fact that when a Flip auction receives DAI, it decreases the Vow's DAI balance in the Vat.

• Note: In this case, there is a risk that a circumstance can occur where the Vow.wait is different than the Flip.tau. The main risk being related to wait < tau, which would result in debt auctions running before the associated seized-collateral auctions could complete.

Overall Sin can affect the system in the following way:

1. There can be separate Vows each with their own sins

2. In the case of an upgrade, if we remove a Vow that has sin, this can create untracked bad debt in the system.

Accounting

Vow.Sin - This calculates the total queued debt in the system. Vow.Ash- This calculates the total on-auction debt.

3. Key Mechanisms & Concepts

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 Vow contract contains the logic to trigger both the debt (flop) and surplus (flap) auctions, which work to correct the system’s monetary imbalances.

Summary

• System Debt: In the case where Vaults are bitten (liquidated), their debt is taken on by the Vow contract as a Sin (the system debt unit). The Sin amount is then placed in the Sin queue. Note: When the Sin is not covered by a flip auction (within the dedicated wait time, the Sin is 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 lot size).

• System Surplus: Occurs from stability fee accumulation, resulting in additional internal Dai in the Vow. This surplus is then discharged through a surplus auction (flap).

4. Gotchas (Potential source of user error)

• When the Vow is upgraded, there are multiple references to it that must be updated at the same time (End, Jug, Pot).

• The Vow is the only user with a non-zero Sin balance (not a vat invariant as there can be multiple Vows).

• Ilk storage is split across the Vat, Jug, Pot and Vow modules. The cat also 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 Sin in the Vow at every Pot.drip( ) call.

• Setting an incorrect value for vow can cause the surplus to be lost or stolen.

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

Vault Liquidation

• A failure mode could arise when no actors call kiss, flog or heal to reconcile/queue the debt.

Auctions

• A failure mode could arise if a user does not call flapor flop to kick off auctions.

• Vow.wait, when set too high (wait is too long), the flop auctions can no longer occur. This provides a risk of undercollateralization.

• Vow.wait, when set too low, can cause too many flop auctions, while preventing flap auctions from occurring.

• Vow.bump, when set too high, can result in no flap auctions being possible. Thus, if no flap auction 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 flap auctions not being profitable for participants (lot size is worth less than gas cost). Thus, no MKR will be bid during a flap auction and, as a result, there will be no automated MKR burn.

• Vow.sump, when set too high, no flop auctions are possible. This results in the system not being able to recover from an undercollateralized state.

• Vow.sump, when set too low, flop auctions are not profitable for participants (where the lot size is worth less than gas cost). This results in MKR inflation due to automated MKR minting.

• Vow.dump, when set too high, flop auctions 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, flop auctions have to be kicked many times before they will be interesting to keepers.

• Vow.hump, when set too high, the flap auctions would never occur. If a flap auction 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 flap auctions before it is used to cancel sin from liquidations, necessitating flop auctions and making the system run inefficiently.

• Contract Name: OSM

• Type/Category: Oracles - Price Feed Module

1. Introduction

Summary

2. Contract Details - Glossary (OSM)

Storage Layout

• stopped : flag (uint256) that disables price feed updates if non-zero

• src : address of DSValue that the OSM will read from

• ONE_HOUR : 3600 seconds (uint16(3600))

• hop : time delay between poke calls (uint16); defaults to ONE_HOUR

• zzz : time of last update (rounded down to nearest multiple of hop)

• cur : Feed struct that holds the current price value

• nxt : Feed struct that holds the next price value

• bud : mapping from address to uint256; whitelists feed readers

Public Methods

Administrative Methods

These functions can only be called by authorized addresses (i.e. addresses usr such that wards[usr] == 1).

• rely/deny : add or remove authorized users (via modifications to the wards mapping)

• stop()/start() : toggle whether price feed can be updated (by changing the value of stopped)

• change(address) : change data source for prices (by setting src)

• step(uint16) : change interval between price updates (by setting hop)

• void() : similar to stop, except it also sets cur and nxt to a Feed struct with zero values

• kiss(address)/diss(address) : add/remove authorized feed consumers (via modifications to the buds mapping)

Feed Reading Methods

These can only be called by whitelisted addresses (i.e. addresses usr such that buds[usr] == 1):

• peek() : returns the current feed value and a boolean indicating whether it is valid

• peep() : returns the next feed value (i.e. the one that will become the current value upon the next poke() call), and a boolean indicating whether it is valid

• read() : returns the current feed value; reverts if it was not set by some valid mechanism

Feed Updating Methods

• poke() : updates the current feed value and reads the next one

Feed struct: a struct with two uint128 members, val and has. Used to store price feed data.

3. Key Mechanisms & Concepts

Other contracts, if whitelisted, may inspect the cur value via the peek() and read() methods (peek() returns an additional boolean indicating whether the value has actually been set; read() reverts if the value has not been set). The nxt value may be inspected via peep().

The contract uses a dual-tier authorization scheme: addresses mapped to 1 in wards may start and stop, set the src, call void(), and add new readers; addresses mapped to 1 in buds may call peek(), peep(), and read().

4. Gotchas (Potential Sources of User Error)

Confusing peek() for peep() (or vice-versa)

The names of these methods differ by only a single character and in current linguistic usage, both "peek" and "peep" have essentially the same meaning. This makes it easy for a developer to confuse the two and call the wrong one. The effects of such an error are naturally context-dependent, but could e.g. completely invalidate the purpose of the OSM if the peep() is called where instead peek() should be used. A mnemonic to help distinguish them: "since 'k' comes before 'p' in the English alphabet, the value returned by peek() comes before the value returned by peep() in chronological order". Or: "peek() returns the kurrent value".

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

poke() is not called promptly, allowing malicious prices to be swiftly uptaken

For several reasons, poke() is always callable as soon as block.timestamp / hop increments, regardless of when the last poke() call occurred (because zzz is rounded down to the nearest multiple of hop). This means the contract does not actually guarantee that a time interval of at least hop seconds has passed since the last poke() call before the next one; rather this is only (approximately) guaranteed if the last poke() call occurred shortly after the previous increase of block.timestamp / hop. Thus, a malicious price value can be acknowledged by the system in a time potentially much less than hop.

This was a deliberate design decision. The arguments that favoured it, roughly speaking, are:

• Providing a predictable time at which MKR holders should check for evidence of oracle attacks (in practice, hop is 1 hour, so checks must be performed at the top of the hour)

• Allowing all OSMs to be reliably poked at the same time in a single transaction

The fact that poke is public, and thus callable by anyone, helps mitigate concerns, though it does not eliminate them. For example, network congestion could prevent anyone from successfully calling poke() for a period of time. If an MKR holder observes that poke has not been promptly called, the actions they can take include:

1. Call poke() themselves and decide if the next value is malicious or not

2. Call stop() or void() (the former if only nxt is malicious; the latter if the malicious value is already in cur)

3. Trigger emergency shutdown (if the integrity of the overall system has already been compromised or if it is believed the rogue oracle(s) cannot be fixed in a reasonable length of time)

In the future, the contract's logic may be tweaked to further mitigate this (e.g. by only allowing poke() calls in a short time window each hop period).

Authorization Attacks and Misconfigurations

Various damaging actions can be taken by authorized individuals or contracts, either maliciously or accidentally:

• Revoking access of core contracts to the methods that read values, causing mayhem as prices fail to update

• Completely revoking all access to the contract

• Changing src to either a malicious contract or to something that lacks a peek() interface, causing transactions that poke() the affected OSM to revert

• Calling disruptive functions like stop and void inappropriately

The only solution to these issues is diligence and care regarding the wards of the OSM.

• Contract Name: median.sol

• Type/Category: Oracles Module

1. Introduction (Summary)

The median provides Maker's trusted reference price. In short, it works by maintaining a whitelist of price feed contracts which are authorized to post price updates. Every time a new list of prices is received, the median of these is computed and used to update the stored value. The median has permissioning logic which is what enables the addition and removal of whitelisted price feed addresses that are controlled via governance. The permissioning logic allows governance to set other parameters that control the Median's behavior—for example, the bar parameter is the minimum number of prices necessary to accept a new median value.

A High-level overview diagram of the components that involve and interact with the median:

Note: All arrows without labels are governance calls.

2. Contract Details

Median (Glossary)

Key Functionalities (as defined in the smart contract)

• read - Gets a non-zero price or fails.

• peek - Gets the price and validity.

• poke - Updates price from whitelisted providers.

• lift- Adds an address to the writers whitelist.

• drop - Removes an address from the writers whitelist.

• setBar - Sets the bar.

• kiss - Adds an address to the reader's whitelist.

• diss - Removes an address from the readers whitelist.

Note: read returns the value or fails if it's invalid & peek gives back the value and if the value is valid or not.

Other

• wards(usr: address) - Auth mechanisms.

• orcl(usr: address) - val writers whitelist / signers of the prices (whitelisted via governance / the authorized parties).

• bud(usr: address) - val readers whitelist.

• val - the price (private) must be read with read() or peek()

• age - the Block timestamp of last price val update.

• wat - the price oracles type (ex: ETHUSD) / tells us what the type of asset is.

• bar - the Minimum writers quorum for poke / min number of valid messages you need to have to update the price.

3. Key Mechanisms & Concepts

As mentioned above, the median is the smart contract that provides Maker's trusted reference price. Authorization (auth) is a key component included in the mechanism of this contract and its interactions. For example, the price (val) is intentionally kept not public because the intention is to only read it from the two functions read and peek, which are whitelisted. This means that you need to be authorized, which is completed through the bud. The bud is modified to get whitelisted authorities to read it on-chain (permissioned), whereas, everything of off-chain is public.

The poke method is not under any kind of auth. This means that anybody can call it. This was designed for the purpose of getting Keepers to call this function and interact with Auctions. The only way to modify its state is if you call it and send it valid data. For example, let's say this oracle needs 15 different sources. This means that we would need it to send 15 different signatures. It will then proceed to go through each of them and validate that whoever sent the the data has been auth'd to do so. In the case of it being an authorized oracle, it will check if it signed the message with a timestamp that is greater than the last one. This is done for the purpose of ensuring that it is not a stale message. The next step is to check for order values, this requires that you send everything in an array that is formatted in ascending order. If not sent in the correct order (ascending), the median is not calculated correctly. This is because if you assume the prices are ordered, it would just grab the middle value which may not be sufficient or work. In order to check for uniqueness, we have implemented the use of a bloom filter. In short, a bloom filter is a data structure designed to tell us, rapidly and memory-efficiently, whether an element is present in a set. This use of the bloom filter helps with optimization. In order to whitelist signers, the first two characters of their addresses (the first byte) have to be unique. For example, let's say that you have 15 different price signers, none of the first two characters of their addresses can be the same. This helps to filter that all 15 signers are different.

Next, there are lift functions. These functions tell us who can sign messages. Multiple messages can be sent or it can just be one but they are put into the authorized oracle). However, there is currently nothing preventing someone from lift'ing two prices signers that start with the same address. This is something for example, that governance needs to be aware of (see an example of what a governance proposal would look like in this case in the Gotchas section).

Due to the mechanism design of how the oracles work, the quorum has to be an odd number. If it is an even number, it will not work. This was designed as an optimization (val = uint128(val_[val_.length >> 1]);); this code snippet outlines how it works, which is by taking the array of values (all the prices that each of the prices signers reported, ordered from 200-215) and then grabbing the one in the middle. This is done by taking the length of the array (15) and shifting it to the right by 1 (which is the same as dividing by 2). This ends up being 7.5 and then the EVM floors it to 7. If we were to accept even numbers this would be less efficient. This presents the issue that you should have a defined balance between how many you require and how many signers you actually have. For example, let's say the oracle needs 15 signatures, you need at least 17-18 signers because if you require 15 and you only have 15 and one of them goes down, you have no way of modifying the price, so you should always have a bit more. However, you should not have too many, as it could compromise the operation.

4. Gotchas

Emergency Oracles

• They can shutdown the price feed but cannot bring it back up. Bringing the price feed back up requires governance to step in.

Price Freeze

• If you void the oracles Ethereum module, the idea is that you cannot interact with any Vault that depends on that ilk.

  • Example: ETHUSD shutdown (can still add collateral and pay back debt - increases safety) but you cannot do anything that increases risk (decreases safety - remove collateral, generate dai, etc.) because the system would not know if you would be undercollateralized.

Oracles Require a lot of Upkeep

• They need to keep all relayers functioning.

• The community would need to self-police (by looking at each price signer, etc.) if any of them needs to be replaced. They would need to make sure they are constantly being called every hour (for every hour, a transaction gets sent to the OSM, which means that a few transactions have already been sent to the median to update it as well. In addition, there would need to be a transaction sent to the spotter, as DSS operates in a pool-type method (doesn't update the system/write to it, you tell it to read it from the OSM).

There is nothing preventing from lift'ing two prices signers that start with the same address

• The only thing that this prevents is that you cannot have more than 256 oracles but we don't expect to ever have that many, so it is a hard limit. However, Governance needs to be sure that whoever they are voting in anyone that they have already voting in before with the same two first characters.

• An example of what a governance proposal would look like in this case:

  • We are adding a new oracle and are proposing (the Foundation) a list of signers (that have been used in the past) and we already have an oracle but want to add someone new (e.g. Dharma or dydx). We would say that they want to be price signers, so these are their addresses and we want to lift those two addresses. They would vote for that, and we would need to keep a list of the already existing addresses and they would need to create an address that doesn't conflict with the existing ones.

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

• By design, there is currently no way right now to turn off the oracle (failure or returns false) if all the oracles come together and sign a price of zero. This would result in the price being invalid and would return false on peek, telling us to not trust the value.

  • We are currently researching (Oracles ETH module) that would invalidate the price but there is no way to do this in the median today. This is due to the separation of concerns that DSS does not read directly from median, it reads from the OSM, but this may end up changing.

• Module Name: Governance Module

• Type/Category: Governance —> Chief.sol, Pause.sol, Spell.sol

• Contract Sources:

1. Introduction (Summary)

The Governance Module contains the contracts that facilitate MKR voting, proposal execution, and voting security of the Maker Protocol.

2. Module Details

The Governance Module has 3 core components consisting of the Chief, Pause and Spell contracts.

Governance Module Components Documentation

3. Key Mechanism and Concepts

Summary of the Governance Module Components

• Chief - The Ds-Chief smart contract provides a method to elect a "chief" contract via an approval voting system. This may be combined with another contract, such as DSAuthority, to elect a ruleset for a smart contract system.

• Pause - The ds-pause is a delegatecall based proxy with an enforced delay. This allows authorized users to schedule function calls that can only be executed once a predetermined waiting period has elapsed. The configurable delay attribute sets the minimum wait time that will be used during the governance of the system.

• Spell - A DS-Spell is an un-owned object that performs one action or series of atomic actions (multiple transactions) one time only. This can be thought of as a one-off DSProxy with no owner (no DSAuth mixing, it is not a DSThing).

4. Gotchas (Potential sources of user error)

• Chief

  • In general, when we refer to the "chief", it can be both addresses or people that represent contracts. Thus, ds-chief can work well as a method for selecting code for execution just as well as it can for realizing political processes.

  • IOU Token: The purpose of the IOU token is to allow for the chaining of governance contracts. In other words, this allows you to have a number of DSChief, DSPrism, or other similar contracts use the same governance token by means of accepting the IOU token of the DSChief contract before it is a governance token.
• Pause

  • Identity & Trust: In order to protect the internal storage of the pause from malicious writes during plan execution, a delegatecall operation is performed in a separate contract with an isolated storage context (DSPauseProxy), where each pause has its own individual proxy. This means that plans are executed with the identity of the proxy. Thus when integrating the pause into some auth scheme, you will want to trust the pause's proxy and not the pause itself.

• Spell

  • The spell is only marked as "done" if the CALL it makes succeeds, meaning it did not end in an exceptional condition and it did not revert. Conversely, contracts that use return values instead of exceptions to signal errors could be successfully called without having the effect you might desire. "Approving" spells to take action on a system after the spell is deployed generally requires the system to use exception-based error handling to avoid griefing.

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

• Chief

  • MKR users moving their votes from one spell to another: One of the biggest potential failure modes occurs when people are moving their votes from one spell to another. This opens up a gap/period of time when only a small amount of MKR is needed to lift a random hat.

• Pause

  • There is no way to bypass the delay.

  • The code executed by the delegatecall cannot directly modify storage on the pause.

  • The pause will always retain ownership of it's proxy.
• Spell

  • The main failure mode of the spell arises when there is an instance of the spell remaining uncast when it has an amount of MKR voting for it that later becomes a target.

• Type/Category: DSS —> Liquidation 2.0 Module​​​

• Etherscan

1. Introduction

Summary: In the context of the Maker protocol, a liquidation is the automatic transfer of collateral from an insufficiently collateralized Vault, along with the transfer of that Vault’s debt to the protocol. In the liquidation contract (the Dog), an auction is started promptly to sell the transferred collateral for DAI in an attempt to cancel out the debt now assigned to the protocol.

2. Features

Instant Settlement

Unlike the old Liquidation 1.2 system which utilized English auctions, in which DAI bids are placed, with a participant's capital remaining locked until they are outbid or until the auction terminates, Liquidation 2.0 uses Dutch auctions which settle instantly. They do so according to a price calculated from the initial price and the time elapsed since the auction began. Price versus time curves are discussed more later. The lack of a lock-up period mitigates much of the price volatility risk for auction participants and allows for faster capital recycling.

Flash Lending of Collateral

This feature, enabled by instant settlement, eliminates any capital requirement for bidders (excepting gas)—in the sense that even a participant with zero DAI (and nothing to trade for DAI) could still purchase from an auction by directing the sale of the auction's collateral into other protocols in exchange for DAI. Thus, all DAI liquidity available across DeFi can be used by any participant to purchase collateral, subject only to gas requirements. The exact mechanics are discussed above, but essentially a participant needs to specify a contract who (which conforms to a particular interface), and calldata to supply to it, and the auction contract will automatically invoke whatever logic is in the external contract.

Price as a Function of Time

Price-versus-time curves are specified through an interface that treats price at the current time as a function of the initial price of an auction and the time at which that price was set. How to determine the most effective price curve for a given collateral is still an active area of research; some initial options (linear, step-wise exponential, and continuous exponential) have been implemented for research purposes and initial deployment. Other candidates besides these include a piecewise linear curve and a piecewise exponential curve. This module is configurable and can be replaced in the course of innovation.

It is important for bidders to take into account that while the price almost always decreases with time, there are infrequent occasions on which the price of an active auction may increase, and this could potentially result in collateral being purchased at a higher price than intended. The most obvious event that would increase the price in a running auction is if that auction is reset (via redo), but changes to the configurable parameters of a price decrease calculator (or even the switching out of one calculator for another) by governance can also increase the price. It is recommended that bidders (or bidding UIs that abstract this detail away from the user) choose the maximum acceptable price (max) argument to take carefully to ensure a desirable outcome if the price should unexpectedly increase.

Resetting an Auction

As mentioned above, auctions can reach a defunct state that requires resetting for two reasons:

• too much time has elapsed since the auction started (controlled by the tail governance parameter)

• the ratio of the current price to the initial price has fallen below a certain level (specified by the cusp governance parameter).

The reset function, when called, first ensures that at least one of these conditions holds. Then it adjusts the starting time of the auction to the current time, and sets the starting price in exactly the same way as is done in the initialization function (i.e. the current OSM price increased percentage-wise by the buf parameter). This process will repeat until all collateral has been sold or the whole debt has been collected (unless the auction is canceled via yank, e.g. during Emergency Shutdown); contrast this behavior with the current auctions, which reset until at least one bid is received.

Improved Keeper Wallet Security

If keepers decide to use the clipperCallee pattern, then they need not store DAI or collateral on that account. This means a keeper need only hold enough ETH to execute transactions that can orchestrate the Clipper.take call, sending collateral to a contract that returns DAI to the msg.sender to pay for the collateral all in one transaction. The contract implementing the clipperCallee interface can send any remaining collateral or DAI beyond owe to a cold wallet address inaccessible to the keeper. NOTE: If the keeper chooses to behave as an EOA address, then the DAI and collateral would be exposed just as in LIQ-1.2 unless special care is taken to create a proxy contract.

3. Contract Details

Parameters Set By Governance (through file)

Abacus/LinearDecrease -- tau [seconds]

Seconds after auction start when the price reaches zero.

Abacus/StairstepExponentialDecrease -- cut [ray]

Per-step multiplicative factor. cut = 0.99 * RAY specifies a 1% drop every step seconds.

Abacus/StairstepExponentialDecrease -- step [seconds]

Length of time between price drops.

Abacus/ExponentialDecrease -- cut [ray]

Per-second multiplicative factor. cut = 0.99 * RAY specifies a 1% drop every second.

Clipper -- buf [ray]

The multiplicative factor to increase the starting price of an auction. E.g. if the current OSM price of an asset is 1,000 and buf = 1.2 * RAY (20% above), then the initial price of that auction will be 1,200.

Clipper -- calc [address]

The contract address of the price calculator function. Adheres to Abacus interface. Some examples of price functions are found in abaci.sol file.

Clipper -- chip [wad]

Percentage of tab to suck from vow to incentivize keepers when liquidating a vault or resetting an already existing auction. chip = 0.02 * WAD is 2%.

Clipper -- cusp [ray]

Percentage price drop that can occur before an auction must be reset. Together with tail, this parameter determines when an auction needs to be reset. E.g. if the initial price of an auction (top) is set to 1,200 and cusp = 0.6 * RAY (60% of the starting price), then the auction will need to be reset when reaching just below the price of 720.

Clipper -- dog [address]

The address of the liquidation module contract.

Clipper -- spotter [address]

The Collateral price module contract address.

Clipper -- tail [seconds]

Seconds that can elapse before an auction must be reset. Together with cusp, this parameter determines when an auction needs to be reset. E.g. if tail is 1800 seconds, then if an auction is not complete after 30 minutes have elapsed, it will need to be reset.

Clipper -- tip [rad]

Flat fee to suck from vow to incentivize keepers when liquidating a vault or resetting an already existing auction. tip = 100 * RAD is 100 DAI.

Clipper -- vow [address]

The address of the accounting system contract. The recipient of DAI raised in auctions.

Dog -- Hole [rad]

Max DAI needed to cover debt + liquidation penalty of active auctions. Hole = 10,000,000 * RAD is 10M DAI.

Dog -- ilk.chop [wad]

Liquidation Penalty per collateral (ilk). E.g. if there is a vault ready to be liquidated that has a debt of 1,000 DAI and chop = 1.13 * WAD (13% above), then the max amount to be raised by the auction will be 1,130 DAI.

Dog -- ilk.clip [address]

The address of the auction module contract. One clip per collateral (ilk).

Dog -- ilk.hole [rad]

Max DAI needed to cover debt + liquidation penalty of active auctions per collateral (ilk). hole = 10,000,000 * RAD is 10M DAI.

Dog -- vow [address]

The address of the accounting system contract. The recipient of the bad debt coming from a vault when it's liquidated.

Vault Liquidation

The Vault liquidation function (Dog.bark) takes three caller supplied arguments:

• ilk: the collateral ilk

• urn: the Vault to be liquidated

• kpr: the address where DAI incentives will be sent

Dog.bark performs several actions:

• confiscates the given Vault urn if it's undercollateralized and

  • sends the collateral to the ilk's Clipper

  • increments the vow's bad debt accumulator

• pushes the bad debt into the debt queue

• adds the bad debt plus the liquidation penalty to the Hole with the Dirt accumulator

• adds the bad debt plus the liquidation penalty to the ilk.hole with the ilk.dirt accumulator

• initiates the auction by calling Clipper.kick()

• fires the Bark() event

In the context of the Maker protocol, a "liquidation" is the automatic transfer of collateral from an insufficiently collateralized Vault, along with the transfer of that Vault's debt to the protocol. In both the Liquidation 1.2 version (the Cat) and the Liquidation 2.0 version (the Dog), an auction is started promptly to sell the transferred collateral for DAI in an attempt to cancel out the debt now assigned to the protocol. This makes the behavior of the new contract very similar to that of the old one, but there are some important differences, explained below.

Partial vs. Total Liquidations

In the current system, in each call to the liquidation function (Cat.bite) transfers a fixed amount of debt (the dunk) from the affected Vault, along with a proportional amount of the Vault's collateral to the protocol. For example, if 50% of a Vault's debt is taken by the protocol, then half of its collateral is taken as well. If the Vault's debt is less than the dunk, then all debt and collateral is taken. In 2.0, all debt is taken when the liquidation function (Dog.bark) is called, and no analogue of the dunk parameter exists. The reasoning behind this change is that because the new auctions allow partial purchases of collateral, the liquidity available to a participant no longer limits their ability to participate in auctions, so instead the total number of auctions should be minimized. Just to emphasize, there is no longer a minimum DAI liquidity requirement for the sale of collateral on a per-participant basis.

Limits on DAI Needed to Cover Debt and Fees of Active Auctions

In situations involving large amounts of collateral at auction, the current and new designs modify the behavior described in the previous section. Both liquidations 1.2 and 2.0 implement a limit on the total amount of DAI needed to cover the summed debt and liquidation penalty associated with all active auctions. In LIQ-1.2 this is called the box, and in LIQ-2.0 we call this the Hole. Whenever the maximum possible addition to this value is less than the amount of debt+fees that would otherwise be sent to auction, a partial liquidation is performed so as not to exceed this amount. In the current system there is only a global limit; in 2.0, in addition to the global limit, there is also a per-collateral limit. Similar to how there is an ilk.line for a collateral's debt ceiling and a Line for the overall system debt ceiling, there is now an ilk.hole to correspond with the Hole. This ensures that typical market depth against DAI can be taken into account on a per-collateral basis by those determining risk parameters. The Dirt accumulator tracks the total DAI needed to cover the debt and penalty fees of all active auctions, and must be less than Hole for a call to bark to succeed. For each collateral type, ilk.dirt tracks the total DAI needed to cover the debt and penalty fees of a all active auctions for that ilk, and must be less than ilk.hole for a call to bark (on a Vault of that ilk) to succeed.

Auction Initiation

The auction initiation function (Clipper.kick) takes four caller supplied arguments:

• tab: the target DAI to raise from the auction (debt + stability fees + liquidation penalty) [rad]

• lot: the amount of collateral available for purchase [wad]

• usr: the address to return any excess collateral to

• kpr: the address where DAI incentives will be sent

Clipper.kick performs several checks and actions:

• checks that the caller is authorized (only the Dog or governance may call Clipper.kick)

• checks that liquidations are enabled in the four-stage circuit breaker

• increments a counter and assigns a unique numerical id to the new auction

• inserts the id into a list tracking active auctions

• creates a structure to record the parameters of the auction; this includes:

  • it's position in the active auctions list

  • the target amount of DAI to raise from bidders (tab)

  • the amount of collateral available for purchase (lot)

  • the Vault that was liquidated to create this auction

    • allows return of collateral if not all of it is sold

    • allows the return of collateral and tab when Clipper.yank is called by End.snip

  • the timestamp of the auctions creation (as a Unix epoch)

  • the initial price of collateral in the auction (top)

• sends an incentive denominated in DAI to the kpr

• fires the Kick() event

Liquidation Incentive Mechanism

In this design, there is less incentive to quickly liquidate Vaults than in the current system, because there is no inherent advantage obtained by doing so. In contrast, the current auction system grants the account triggering a liquidation the privilege of making the first bid in the resulting auction. It is unclear whether this matters significantly in practice, or whether some stronger incentive should be added (for example, a small DAI reward paid to liquidators).

To ensure there was a remedy for this potential issue, an incentive mechanism was added for liquidators. The form of the incentive is, on a per-collateral type basis, a constant amount of DAI plus an amount of DAI that scales linearly with the amount of debt associated with the liquidation. Either contribution can be set to zero. Such a structure is justified by the following:

• The reward is set per-collateral to give maximum flexibility to include not just per-collateral risk parameters like mat (collateralization ratio) and chop (liquidation penalty) in its setting, but also to allow for unique market conditions that might only apply to one or a few collateral types.

• The component of the reward that increases linearly with the total Vault debt is intended to be used to reward liquidators for reducing risk to the system, as risk itself scales with the size of undercollateralized Vaults—a Vault that is twice as big as another represents twice the risk of bad debt accrual. Or viewed another way, liquidating two vaults of size X represents the same risk reduction as liquidating one Vault of size 2X—thus the reward to a liquidator ought to be similar. Further, the system can afford to pay more for larger liquidations, because the liquidation penalty is also proportional to the amount of debt outstanding for a given Vault.

• The constant component of the reward can be used to cover gas costs (which are per-Vault for liquidators) or to allow MKR holders to effectively pay Keepers to clear small Vaults that would otherwise not be attractive for liquidation.

These parameters must be set extremely carefully, lest it be possible to exploit the system by "farming" liquidation rewards (e.g. creating Vaults with the intention of liquidating them and profiting from the too-high rewards). Generally, the liquidation reward should remain less than the minimum liquidation penalty by some margin of safety so that the system is unlikely to accrue a deficit. This doesn't necessarily prevent farming, it just helps ensure the system remains solvent. For example, incentives can be farmed in a capital-efficient way when Dirt is close to Hole or when ilk.dirt is close to ilk.hole for some collateral type. An attacker would purchase a small amount of collateral from a running auction, freeing up a small amount of room relative to either Hole or ilk.hole, then liquidate a small portion of an existing Vault to collect the reward, and repeat the process. This can be done over and over in the same transaction, and the activation of EIP 2929 (scheduled for the Berlin hard fork at the time of writing) will significantly reduce the associated gas costs (due to warm storage reads and writes). Note that since the attacker does not need to create their own Vaults, the size of the liquidation penalty in relation to the incentive value is not a deterrent; only gas costs matter to the attacker. The fact that the Dog prevents partial liquidations that remove less than ilk.dust debt from a Vault helps to mitigate this scenario--so long as the liquidation penalty exceeds the total reward for this minimal liquidation size, and the liquidation penalty is reliably collected by the resulting auction (which may not hold under conditions of market or network perturbation), the system should not on balance accrue bad debt.

Four-Stage Liquidation Circuit Breaker

In this section, we'll cover the four stages of the liquidation circuit breaker. In contrast to LIQ-1.2, Liquidations 2.0 comes with a four-stage circuit breaker built into the Clipper contract. The stages are:

• liquidations enabled(0): This means the breaker is not tripped and the protocol can liquidate new Vaults as well as service old liquidations.

• new liquidations disabled(1): This means no new liquidations (Clipper.kick).

• new liquidations and resets disabled(2): This means no new liquidations (Clipper.kick), and auctions that have reached either a price or time endpoint cannot be reset (Clipper.redo).

• liquidations disabled(3): This means no new liquidations (Clipper.kick), no takes (Clipper.take), and no resets (Clipper.redo).

Just like in LIQ-1.2, the circuit breaker will be available through a ClipperMom contract giving governance the ability to bypass the GSM delay for circuit breaker actions.

Bidding (Purchasing)

The purchasing function (Clipper.take) takes five caller supplied arguments:

• id: the numerical id of the auction to bid on

• amt: the maximum amount of collateral to buy (amt) — a purchase behaves like a limit order [wad]

• max: the maximum acceptable price in DAI per unit collateral (max) [ray]

• who: address that will receive the collateral (who)

• data: an arbitrary bytestring (if provided, the address who, if it is neither the Dog nor Vat address stored by the Clipper, is called as a contract via an interface described below, to which this data is passed) [bytes]

Clipper.take performs several initial checks:

• a reentrancy check to ensure the function is not being recursively invoked

• that the four-stage circuit breaker is not tripped

• that the auction id corresponds to a valid auction

• that the auction does not need to be reset, either due to having experienced too large a percentage decrease in price, or having existed for too long of a time duration

• that the caller's specified maximum price is at least the current auction price

Then, the amount of collateral to attempt to purchase is computed as the minimum of the collateral left in the auction (lot) and the caller's specified quantity (amt)—the resulting value is the slice. This value is then multiplied by the current price of the auction to compute the DAI owed in exchange (owe). If owe exceeds the DAI collection target of the auction (tab), then owe is adjusted to be equal to tab, and slice is set to tab / price (i.e. the auction will not sell more collateral than is needed to cover debt+fees from the liquidated Vault).

To make it less likely that auctions are left in a state that is unattractive to bid on, further logic is applied if there will be both left over DAI target and collateral based on the initial determinations for slice and owe. If the remaining tab in such a case would be less than chost (a value stored by the contract, asynchronously set to ilk.dust * ilk.chop / WAD by the upchost() function), then: 1) If the overall DAI target is less than chost, the function reverts. Callers should be aware of this possibility and account for it when necessary. 2) Otherwise, owe is set to tab - chost, and slice is set to (tab - chost) / price.

This heuristic for preventing a too-small remaining collateral amount and/or DAI target is imperfect and may fail in some situations; if this occurs, there is no serious harm to the protocol; the auction will simply remain uncompleted. However, governance may wish to fully clear such "lost" auctions via take or yank to avoid cluttering the list of active auctions each Clipper maintains, which could impair the performance of DEX and aggregator integrations (and possibly off-chain bots too, depending on how they are written).

clipperCall(
    address,            // recipient of DAI
    uint256,            // owe   [rad]
    uint256,            // slice [wad]
    bytes calldata
)

Lastly, various values are updated to record the changed state of the auction: the DAI needed to cover debt and fees for outstanding auctions, and outstanding auctions of the given collateral type, are reduced (via a callback to the liquidator contract) is reduced by owe, and the tab (DAI collection target) and lot (collateral for sale) of the auction are adjusted as well. If all collateral has been drained from an auction, all its data is cleared and it is removed from the active auctions list. If collateral remains, but the DAI collection target has been reached, the same is done and excess collateral is returned to the liquidated Vault.

Example Liquidation

Figure 1: NOTE: in the above figure, tau is tail.

In this example we can see a linear decrease function (calc), with an ETH-A OSM price of 200 DAI, a buf of 20%, a tail (tau) of 21600 seconds, a tab of *60,000 DAI with a lot of 347.32 ETH. There are two bidders, Alice and Bob. Alice calls take first and is willing to give *50,000 DAI in return for 256.41 ETH collateral, a price of 195 DAI per ETH. The price of ETH continues to fall over time, and Bob picks up the remaining 90.91 ETH for 10,000 DAI, a price of 110 DAI per ETH. If more than tail seconds have elapsed since the start of the auction, or if the price has fallen to less than cusp percent of top, then Clipper.take would revert if called, and the auction would need to be reset with a Clipper.redo call.

Incentive to call redo()

The auction initiation function (Clipper.redo) takes two caller supplied arguments:

• id: the current auction id

• kpr: the address where DAI incentives will be sent

Clipper.redo performs several checks and actions:

• a reentrancy check to ensure the function is not being recursively invoked

• that the four-stage circuit breaker is not tripped

• that the auction id corresponds to a valid auction

• that the auction needs to be reset, either due to having experienced too large a percentage decrease in price, or having existed for too long of a time duration

• updates several fields of the existing auction

  • tic to reset the auction start time

  • top with the current OSM price and buf percent

• vat.sucks DAI to the kpr as an incentive if eligible

• fires the Redo() event

An auction that has expired or which is currently offered at a value higher than the oracle threshold will likely not complete at favorable values. The system therefore provides a direct incentive to Clipper.redo the auction, resetting it's expiration and setting the starting price to match the current oracle price + buf. The redo includes the same Dai incentive to the keeper as the Clipper.kick, which is based on the flat fee plus the governance-defined percentage of collateral. There is one exception to this incentive. If the tab or lot * price remaining is under the Clipper.chost limit, then there will be no incentive paid to redo the auction. This is to help prevent incentive farming attacks where no keepers bid on dusty lots, and Clipper.redo is called repeatedly. If auctions in this state build up, governance may choose to pay a keeper to clean them up.

Emergency Shutdown

A started auction can be reverted via the auth function called yank in Clipper contract. This function requires that the auction exists and executes the following actions:

• calls dog.digs in order to decrease its Dirt and ilk.dirt values by the remaining auction tab

• sends the remaining collateral to its msg.sender

• removes the auction struct data

• fires the Yank() event

This function might be thought of as a general purpose operation to migrate existing auctions to a new contract; however, the only use-case now is in the End module, which takes care of system shutdown.

The End module will be upgraded together with the auction contracts as a new function End.snip is required.

This function End.snip is responsible for calling Clipper.yank for any running auction when shutdown is triggered. It will receive the collateral from Clipper.yank and will send it back to the vault owner together with the remaining debt to recover. One consideration to note is that the debt that the vault owner will receive includes the liquidation penalty part already charged.

Interfaces

Dog Interface

function wards(address) external view returns (uint256);
function rely(address) external;
function deny(address) external;

Standard MakerDAO authorization structure.

function vat() external view returns (address);
function vow() external view returns (address);

DSS core address introspection.

function ilks(bytes32 ilk) external view returns (
    address clip,
    uint256 chop,   // wad
    uint256 hole,   // rad
    uint256 dirt);  // rad

Returns values configured for a given ilk (ex. ETH-A).

function live() external view returns (uint256);

Returns 1 if the system is active.

function Hole() external view returns (uint256);
function Dirt() external view returns (uint256);

Getters for the global Hole and Dirt configuration. Both return a rad-precision value.

function file(bytes32 what, address data) external;
function file(bytes32 what, uint256 data) external;
function file(bytes32 ilk, bytes32 what, address data) external;
function file(bytes32 ilk, bytes32 what, uint256 data) external;

(Authenticated) Parameter modification functions, available to governance. The precision for a numeric argument should match the parameter being set.

function chop(bytes32 ilk) external view returns (uint256);

Getter for the chop value of a given ilk. chop has wad precision.

function bark(bytes32 ilk, address urn, address kpr)
    external returns (uint256 id);

The main liquidation function. Initiates an auction. A keeper calls this function to begin the auction of urn for a particular ilk. kpr is the address where the keeper incentive is sent, allowing keepers to have liquidation rewards sent to a different address than the caller.

function digs(bytes32 ilk, uint256 rad) external;

(Authenticated) Removes collateral from the accumulator. Called by the Clipper. The rad argument has rad precision.

function cage() external;

(Authenticated) Deactivates the Dog and sets live to 0.

Clipper Interface

function wards(address) external view returns (uint256);
function rely(address) external;
function deny(address) external;

Standard MakerDAO authorization structure.

function ilk() external view returns (bytes32);

The ilk that this Clipper is associated with.

function dog() external view returns (address);
function vow() external view returns (address);
function spotter() external view returns (address);

DSS core address introspection.

function calc() external view returns (address);

The address of the pricing function used by this Clipper.

function buf() external view returns (uint256);   // ray
function tail() external view returns (uint256);  // seconds
function cusp() external view returns (uint256);  // ray
function chip() external view returns (uint256);  // wad
function tip() external view returns (uint256);   // rad

Getters for governance-configured auction parameters.

function chost() external view returns (uint256);  // rad

Getter for the stored product of Vat.ilk.dust and Dog.ilk.chop. This value is used as a heuristic for whether a partial purchase will leave an auction with too little collateral and whether incentives should be given out when redo is called.

function kicks() external view returns (uint256);

Auction counter. Increments each time an auction is initiated.

function active(uint256 pos) external view returns (uint256);

Returns the id of the auction at index pos in the list of active auctions.

function sales(uint256) external view returns (
        uint256 pos,
        uint256 tab,   // rad
        uint256 lot,   // wad
        address usr,
        uint96  tic,   // Unix epoch
        uint256 top);  // ray

Returns information on a particular auction. Completed auctions are removed from the mapping.

function stopped() external view returns (uint256);

Returns the current circuit breaker status. 0 for all functions allowed, 1 if kick cannot be called, 2 if kick and redo cannot be called, and 3 if kick, redo and take cannot be called.

function file(bytes32 what, address data) external;
function file(bytes32 what, uint256 data) external;

(Authenticated) Parameter modification functions, available to governance. Numeric arguments should match the precision of the parameter being set.

function kick(uint256 tab, uint256 lot, address usr, address kpr)
    external returns (uint256 id);

(Authenticated) Initiates the auction. Called by the Dog. tab is rad-precion, lot is wad-precision.

function redo(uint256 id, address kpr) external;

Called to reset an auction due to expiry or price deviation.

function take(
    uint256 id,
    uint256 amt,  // wad
    uint256 max,  // ray
    address who,
    bytes calldata data) external;

Called to purchase collateral.

function list() external view returns (uint256[] memory);
function count() external view returns (uint256);

Helpers for iterating the list of active auctions. Use list() to get the unsorted array of auctions. Get the number of active auctions with count(). The function active(uint256 pos) (see above) can be used to access individual entries without needing to call list().

function getStatus(uint256 id) external view returns (bool needsRedo, uint256 price);

Returns a bool if the auction is eligible for redo and the current price.

function upchost() external;

Updates the chost value stored in the contract to equal the product of Vat.ilk.dust and Dog.ilk.chop (the precision of the final value is rad). This allows take and redo to obtain chost with a single SLOAD (reading dust from the Vat requires 5 SLOAD operations due to how the API is structured, and reading chop is an additional SLOAD).

function yank(uint256 id) external;

(Authenticated) Allows an auction to be removed during Emergency Shutdown or via a goveranance action.

4. Known Risks

This section covers some of the known risks with Liquidations 2.0

Incentive Farming

Periodically, governance may increase the ilk.dust amount. When this happens, it's usually because gas has become so expensive it impacts the efficiency of liquidations. That is, the cost of calling Dog.bark(), Clipper.take(), or Clipper.redo() may exceed the collateral offered. Incentives may be used as a remedy to this potential issue and possibly a way for the protocol to keep ilk.dust lower; however, governance must take care when increasing the ilks dust, tip, or chip not to incentivize the creation of many Vaults to farm this incentive. An example of an exploit is as follows:

1. governance decides to increment dust by 1500 DAI at the same time they scale ilk.tip to subsidize auctions.

2. an attacker realizes it would be profitable between gas and the chop to shard (fork) their existing Vault into many Vaults or create many new Vaults.

3. the spell is voted on and passed

4. using one transaction the attacker puts their Vaults at the edge of unsafe, poke()s the OSM when next price is going down, then calls Dog.bark() on all their Vaults to collect the incentive.

5. Using the gains, they can also slightly overbid for their Vaults auctions.

In order to thwart this attack governance must be careful when setting ilk.tip and ilk.chip so as not to create this perverse incentive.

Price Decreases Too Quickly

If the price decreases too quickly it can have the following consequences:

• the auction ends without any bid, then it needs to be reset and possibly this will keep happening

• bidders end up having reverts due the auction ended before tx confirmation

• bidders end up paying much less than what they were willing to pay (possibly generating permanent bad debt)

Price Decreases Too Slowly

If the price decreases too slowly it can have the following consequences:

• Auction price never catches up with the market price, eventually being reset

  • After the reset the price catches up, but is less than an optimal market price

  • After the reset the price catches up, but still leaves bad debt

  • After the reset the auction price still might not catch up, causing more resets and very likely leaving bad debt

Front-Running

In LIQ-1.2 there is limited front-running risk as it requires capital to participate in auctions; however, in liquidations 2.0 if a keeper chooses to participate with no capital, there is substantial front-running risk from generalized front-running bots. The easier it is to replace the from address of the transaction with one's own, the greater the risk. To mitigate this risk keepers are encouraged to used authorized proxy contracts to interact with liquidations 2.0 and provide some amount of their own capital when bidding. More aggressive gas prices may also work. Unfortunately, we found no great way to prevent generalized front-running that preserves single-block composability.

OSM Risk for Start Price

Because Clipper.kick and Clipper.redo consult the OSM for the collateral price, we are vulnerable to an oracle attack that can only be mitigated by the oracle delay, Dog.Hole, and ilk.hole. We must rely on the number of guards in place to prevent price manipulation and oracle attacks. The fact that the price is delayed by one hour, however, prseents a risk of its own: since the price is out-of-date relative to the market, it may be either too high or too low to allow for efficient settlement given other parameters like 'buf' and the price decrease function. The consequences of either case are effectively covered by the sections on the risk of the price decreasing either too quickly or too slowly.

Setting Hole or ilk.hole Too High

While Dog.Hole and ilk.hole can be set much higher in liquidations 2.0, there are still risks to setting this too high. A value for Dog.Hole that's set too high could result in far too much DAI demand, breaking the peg high. This is somewhat mitigated by the PSM and stablecoin collateral types, but should still factor in to how this parameter is set. An ilk.hole that is set too high, may have the additional result of causing a downward spiral as the liquidations push the asset price lower. In addition, if there is an oracle attack, this parameter can be thought of as our maximum exposure.

Setting Hole or ilk.hole Too Low

If we set either Dog.Hole or ilk.hole too low, we run the risk of not being able to liquidate enough collateral at once. This could lead to a buildup of undercollateralized positions in the system, eventually causing the accrual of bad debt.

Auction Parameter Changes Affect Running Auctions

Parameters, e.g. tail, cusp, or the price decrease function or any of its parameters, can be changed at any time by governance and will affect the behavior of running auctions. Integrators should take this possibility into account, reasoning through how sudden changes in parameters would impact their bidding strategies. Governance should endeavor to change parameters infrequently and if possible, only when there are not any auctions that will be affected.

5. Invariants

These invariants have not yet been formally proven, and thus should only be considered intended behavior for now.

Dog Invariants

sum_over_all_ilks(Dog.ilk.dirt) == Dog.Dirt                             (c26.1)

Clipper Invariants

sum_over_auction_ids(Clipper.sales[id].lot) <= Vat.gem(Clipper)         (c27.1)

The above is an inequality (and not an equality) because it is impossible to prevent a user or contract from choosing to send collateral to a Clipper, even though it only makes sense for the Dog to do so. Governance (or a new module) could create a violation of this property by calling kick without transferring appropriate collateral to the Clipper. Thus this is actually a pseudo-invariant that only holds if callers of kick respect the requirement to send collateral to the Clipper, but it should hold for the live system if deployment and authorization is done correctly. It should hold if only active auctions are summed over as well.

Invariants involving quantities from both the Dog and Clipper

sum_over_auctions_ids_and_ilks(Dog.ilk.clip.sales[id].tab) == Dog.Dirt  (c28.1)

The above should hold if only active auctions are summed over as well.

sum_over_auctions_ids(Dog.ilk.clip.sales[id].tab) == Dog.ilk.dirt       (c28.2)

The above should hold if only active auctions are summed over as well.

Note that (c28.1) and (c28.2) together imply (c26.1).

• Contract Name: spell.sol

• Type/Category: Governance Module

1. Introduction (Summary)

A DSSpell is an un-owned object that performs one action or series of atomic actions (multiple transactions) one time only. This can be thought of as a one-off DSProxy with no owner (no DSAuth mix-in, it is not a DSThing).

2. Contract Details

The spell.sol contract contains two main contracts: DSSPELL and DSSpellBook. DSSPELL is the core contract that, with call instructions set in the constructor, can actually perform the one-time action. DSSpellBook is a factory contract designed to make the creation of DSSPELLs easier.

Glossary (Spell)

• whom - is the address the spell is targeting, usually SAI_MOM in SCD.

• mana - is the amount of ETH you are sending, which in spells it is usually 0.

• data - bytes memory calldata.

• done - indicates that the spell has been called successfully.

3. Key Mechanisms & Concepts

• hat - A spell comes into effect as the hat when someone calls the lift function. This is only possible when the spell in question has more MKR voted towards it than the current hat.

• cast - Once a spell has become the hat, it can be cast and its new variables will go into effect as part of the live Maker system. It is worth noting that a spell can only be cast once.

• lift - The process whereby a new spell replaces the old proposal.

Note: the hat and lift have more to do with ds-chief than ds-spell but are important to mention here for context.

Immutable Actions

whom, mana, and data are set in the constructor, so the action a spell is to perform cannot be changed after the contract has been deployed.

4. Gotchas (Potential source of user error)

Note that the spell is only marked as "done" if the CALL it makes succeeds, meaning it did not end in an exceptional condition and it did not revert. Conversely, contracts that use return values instead of exceptions to signal errors could be successfully called without having the effect you might desire. "Approving" spells to take action on a system after the spell is deployed generally requires the system to use exception-based error handling to avoid griefing.

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

• spell - A spell may remain uncast if it did not reach the required amount of MKR in order to pass. If this occurs, the spell may remain available as a later target if enough MKR is voted towards it.

• cast - If, when cast is called, the spell's one-time action fails, done does not get flipped and the spell remains castable.

• Contract Name: token.sol

• Type/Category: MKR Module

1. Introduction (Summary)

2. Contract Details:

Glossary (MKR)

• guy - user address

• wad - a quantity of tokens, usually as a fixed point integer with 10^18 decimal places.

• dst - refers to the destination address.

Key Functionalities (as defined in the smart contract)

mint - credit tokens at an address whilst simultaneously increasing totalSupply (requires auth).

burn - debit tokens at an address whilst simultaneously decreasing totalSupply (requires auth).

Aliases

push - transfer an amount from msg.sender to a given address.

pull - transfer an amount from a given address to msg.sender (requires trust or approval).

move - transfer an amount from a given src address to a given dst address (requires trust or approval).

Standard ERC-20

name - returns the name of the token - e.g. "MyToken".

symbol - token symbol.

decimals - returns the number of decimals the token uses - e.g. 8, means to divide the token amount by 100000000 to get its user representation.

transfer - transfers _value amount of tokens to address _to, and MUST fire the Transfer event. This SHOULD throw if the message caller’s account balance does not have enough tokens to spend.

transferFrom - transfers _value amount of tokens from address _from to address _to, and MUST fire the Transfer event.

approve - allows _spender to withdraw from your account multiple times, up to the _value amount. If this function is called again it overwrites the current allowance with _value.

totalSupply - returns the total token supply.

balanceOf - returns the account balance of another account with address _owner.

allowance - returns the amount which _spender is still allowed to withdraw from _owner.

Important note: there is a transferFrom auto approval when src == msg.sender.

3. Key Mechanisms & Concepts

Along with MKR having a standard ERC20 token interface, it also has the addition of DSAuth-protected mint and burn functions; binary approval via MAX_UINT; as well as a push, pull and move aliases for transferFrom operations.

• As a utility token: As Dai stability fees earned on Vaults accrue within the Maker Protocol, MKR holders can use MKR to vote to enable the Flapper auction house to sell Dai surplus for MKR. Once the auction is complete the Maker protocol burns the MKR.

• As a governance token: MKR is used by MKR holders to vote for the risk management and business logic of the Maker Protocol. Tokens are a simple representation of voting power.

• As a recapitalization resource: MKR can autonomously be minted by the Flopper auction house and sold for DAI, which is used to recap the Maker Protocol in times of insolvency.

4. Gotchas (Potential source of user error)

• The MKR token is an ERC-20 token created using DSToken. A key difference to note between Dai and most other popular ERC20 tokens is that both these fields use bytes32 instead of the string type.

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

• MKR.stop - ES cannot be triggered. MKR in the chief can still vote, but cannot join or exit.

• Contract Name: chief.sol

• Type/Category: Governance Module

1. Introduction (Summary)

The Ds-Chief smart contract provides a method to elect a "chief" contract via an approval voting system. This may be combined with another contract, such as DSAuthority, to elect a ruleset for a smart contract system.

2. Contract Details

Glossary (Chief)

**DSChiefApprovals provides the following public properties:**

• slates: A mapping of bytes32 to address arrays. Represents sets of candidates. Weighted votes are given to slates.

• votes: A mapping of voter addresses to the slate they have voted for.

• approvals: A mapping of candidate addresses to their uint weight.

• deposits: A mapping of voter addresses to uint number of tokens locked.

• GOV: DSToken used for voting.

• IOU: DSToken issued in exchange for locking GOV tokens.

• hat: Contains the address of the current "chief."

• MAX_YAYS: Maximum number of candidates a slate can hold.

• Etch(bytes32 indexed slate): Fired when a slate is created.

3. Key Mechanisms & Concepts

There are two contracts in ds-chief:

1. DSChiefApprovals

2. DSChief, which inherits from DSChiefApprovals.

Key Functionalities (as defined in the smart contract)

DSChiefApprovals

DSChiefApprovals(DSToken GOV_, DSToken IOU_, uint MAX_YAYS_)

• The constructor. Sets GOV, IOU, and MAX_YAYS.

lock(uint wad)

• Charges the user wad GOV tokens, issues an equal amount of IOU tokens to the user, and adds wad weight to the candidates on the user's selected slate. Fires a LogLock event.

free(uint wad)

• Charges the user wad IOU tokens, issues an equal amount of GOV tokens to the user, and subtracts wad weight from the candidates on the user's selected slate. Fires a LogFree event.

etch(address[] yays) returns (bytes32 slate)

• Save a set of ordered addresses as a slate and return a unique identifier for it.

vote(address[] yays) returns (bytes32 slate)

• Save a set of ordered addresses as a slate, moves the voter's weight from their current slate to the new slate, and returns the slate's identifier.

vote(bytes32 slate)

• Removes voter's weight from their current slate and adds it to the specified slate.

lift(address whom)

• Checks the given address and promotes it to s/chief/hat if it has more weight than the current s/chief/hat.

DSChief

DSChief is a combination of DSRoles from the ds-roles package and DSChiefApprovals. It can be used in conjunction with ds-auth (as an authority object) to govern smart contract systems.

Public Functions

DSChief(DSToken GOV_, DSToken IOU_, uint MAX_YAYS_)

• The constructor. Sets GOV, IOU, and MAX_YAYS.

setOwner(address owner_)

• Reverts the transaction. Overridden from DSAuth.

setAuthority(DSAuthority authority_)

• Reverts the transaction. Overridden from DSAuth.

isUserRoot(address who) constant returns (bool)

• Returns true if the given address is the chief.

setRootUser(address who, bool enabled)

• Reverts the transaction. Overridden from DSRoles.

DSRoles

4. Gotchas (Potential source of user error)

In general, when we refer to the "hat", it can be any address — be it a single-use contract like ds-spell, a multi-use contract or an individual's wallet. Thus, ds-chief can work well as a method for selecting code for execution just as well as it can for realizing political processes.

Example:

The ds-chief could be used as a token-weighted voting system governing another set of smart contracts that uses the ds-auth with ds-roles. In a scenario such as this, "candidates" would consist of contracts changing the state of the smart contract set under governance. Such a contract being elected as ”hat" would be granted all of the permissions to execute whatever changes are necessary. The ds-chief could also be used within such a contract set in conjunction with a proxy contract, such as ds-proxy or a name resolution system like ENS for the purpose of voting in new versions of contracts.

Understanding the IOU Token

The purpose of the IOU token is to allow for the chaining of governance contracts. In other words, this allows you to have a number of DSChief or other similar contracts use the same governance token by means of accepting the IOU token of the DSChief contract before it is a governance token.

Example:

Let’s say there are three DSChief contracts (chiefA, chiefB, and chiefC) and a chiefA.GOV that is the MKR token. If we set chiefB.GOV to chiefA.IOU and chiefC.GOV to chiefB.IOU, this allows all three contracts to run using a common group of MKR.

Approval Voting

This type of voting is when each voter selects which candidates they approve of, with the top n "most approved" candidates being then elected. Each voter can cast up to n + k votes, where k equals some non-zero positive integer. This way voters to move their approval from one candidate to another without needing to first withdraw support from the candidate being replaced. Without this in place, moving approval to a new candidate could result in a less-approved candidate moving momentarily into the set of the elected candidates. Note: In the case of ds-chief, n is equal to 1.

In addition, the ds-chief weighs votes according to the quantity of a voting token that has been chosen to lock up in the DSChief or the DSChiefApprovals contract. It's important to note that the voting token used in a ds-chief deployment must be specified at the time of deployment and cannot be changed afterward.

Implementations

If you are writing a front-end UI for this smart contract, please note that the address[] parameters that are passed to the etch and vote functions must be byte-ordered sets.

Example:

Using [0x0, 0x1, 0x2, ...] is valid but using [0x1, 0x0, ...] and [0x0, 0x0, 0x1, ...] is not. This ordering constraint allows the contract to cheaply ensure voters cannot multiply their weights by listing the same candidate on their slate multiple times.

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

• MKR users moving their votes from one spell to another

  • One of the biggest potential failure modes occurs when people are moving their votes from one spell to another. This opens up a gap/period of time when only a small amount of MKR is needed to lift a random hat.

• Lift is not called on spells that have more MKR than the current hat

  • The only way a spell can get the hat is if lift is called on it. So, even if a spell gains much more MKR on it than the hat, if lift is never called on it, the hat will remain on a spell that no longer has the most MKR. This could lower the bar for the amount of MKR needed to pass something, potentially making the system less safe.

• Stray spells without expiration

  • Due to the continuous nature of voting, a spell will remain live in the system even if it was not approved to be the governing proposal. This means that MKR holders can continue to vote on the candidate and in times of lower voter participation there is potential for them to introduce a failure mode by voting for an unexpected and/or older candidate. This illustrates why increased voter participation is important and that a higher amount of MKR on the current governing proposal adds to the stability of the system.

• Unsafe states when migrating to a new chief contract

  • When migrating to a new chief, authority must be transferred to the new contract and revoked from the old. This poses a small coordination problem as the new contract must already have enough MKR on its hat to be safe against governance attacks while the voters enacting the change itself must have enough MKR in the old chief to pass the proposal.

• Contract Name: pot.sol

• Type/Category: DSS —> Rates Module

1. Introduction (Summary)

The Pot is the core of theDai Savings Rate. It allows users to deposit dai and activate the Dai Savings Rate and earning savings on their dai. The DSR is set by Maker Governance, and will typically be less than the base stability fee to remain sustainable. The purpose of Pot is to offer another incentive for holding Dai.

2. Contract Details

Math

• mul(uint, uint), rmul(uint, uint), add(uint, uint)& sub(uint, uint) - will revert on overflow or underflow

• rpow(uint x, uint n, uint base), used for exponentiation in drip, is a fixed-point arithmetic function that raises x to the power n. It is implemented in assembly as a repeated squaring algorithm. x (and the result) are to be interpreted as fixed-point integers with scaling factor base. For example, if base == 100, this specifies two decimal digits of precision and the normal decimal value 2.1 would be represented as 210; rpow(210, 2, 100) should return 441 (the two-decimal digit fixed-point representation of 2.1^2 = 4.41). In the current implementation, 10^27 is passed for base, making x and the rpow result both of type ray in standard MCD fixed-point terminology. rpow’s formal invariants include “no overflow” as well as constraints on gas usage.

Auth

• wards are allowed to call protected functions (Administration)

Storage

• pie - stores the address' Pot balance.

• Pie - stores the total balance in the Pot.

• dsr - the dai savings rate. It starts as 1 (ONE = 10^27), but can be updated by governance.

• chi - the rate accumulator. This is the always increasing value which decides how much dai - given when drip() is called.

• vat - an address that conforms to a VatLike interface. It is set during the constructor and cannot be changed.

• vow - an address that conforms to a VowLike interface. Not set in constructor. Must be set by governance.

• rho - the last time that drip is called.

The values of dsr and vow can be changed by an authorized address in the contract (i.e. Maker Governance). The values of chi, pie, Pie, and rho are updated internally in the contract and cannot be changed manually.

3. Key Mechanisms & Concepts

drip()

• Calculates the most recent chi and pulls dai from the vow (by increasing the Vow's Sin).

• A user should always make sure that this has been called before calling the exit() function.

• drip has to be called before a user joins and it is in their interest to call it again before they exit, but there isn't a set rule for how often drip is called.

join(uint wad)

• uint wad this parameter is based on the amount of dai (since wad = dai/ chi ) that you want to join to the pot. The wad * chi must be present in the vat and owned by the msg.sender.

• the msg.sender's pie amount is updated to include the wad.

• the total Pie amount is also updated to include the wad.

exit(uint wad)

• exit() essentially functions as the exact opposite of join().

• uint wad this parameter is based on the amount of dai that you want to exit the pot. The wad * chi must be present in the vat and owned by the pot and must be less than msg.sender's pie balance.

• The msg.senders pie amount is updated by subtracting the wad.

• The total Pie amount is also updated by subtracting the wad.

Administration

Various file function signatures for administering Pot:

• Setting new dsr (file(bytes32, uint256))

• Setting new vow (file(bytes32, address))

Usage

The primary usage will be for addresses to store their dai in the pot to accumulate interest over time

4. Gotchas / Integration Concerns

• The dsr is set (globally) through the governance system. It can be set to any number > 0%. This includes the possibility of it being set to a number that would cause the DSR to accumulate faster than the collective Stability Fees, thereby accruing system debt and eventually causing MKR to be minted.

• If drip() has not been called recently before an address calls exit() they will not get the full amount they have earned over the time of their deposit.

5. Failure Modes and Impact

Coding Error

A bug in the Pot could lead to locking of dai if the exit() function or the underlying vat.suck() or vat.move() functions were to have bugs.

Governance

The dsr rate initially can be set through the Chief. Governance will be able to change the DSR based on the rules that the DS-Chief employs (which would include a Pause for actions).

One serious risk is if governance chooses to set the dsr to an extremely high rate, this could cause the system's fees to be far too high. Furthermore, if governance allows the dsr to (significantly) exceed the system fees, it would cause debt to accrue and increase the Flop auctions.

• Contract Name: pause.sol

• Type/Category: Governance Module

1. Introduction (Summary)

The ds-pause is a delegatecall based proxy with an enforced delay. This allows authorized users to schedule function calls that can only be executed once a predetermined waiting period has elapsed. The configurable delay attribute sets the minimum wait time that will be used during the governance of the system.

2. Contract Details:

Key Functionalities (as defined in the smart contract)

Plans A plan describes a single delegatecall operation and a unix timestamp eta before which it cannot be executed.

A plan consists of:

• usr: address to delegatecall into

• tag: the expected codehash of usr

• fax: calldata to use

• eta: first possible time of execution (as seconds since unix epoch)

It is important to note that each plan has a unique id, defined as a keccack256(abi.encode(usr, tag, fax, eta)).

Operations

Plans can be manipulated in the following ways:

• plot: schedule a plan

• exec: execute a scheduled plan

• drop: cancel a scheduled plan