For a fully comprehensive overview of the smart contracts within the Maker Protocol, please download the Maker Protocol 101 Slide Deck (PDF) below or visit the view-only link here.

MakerDAO Documentation Overview

• Introductory @ MakerDAO.world

• @ manual.makerdao.com

• @ docs.makerdao.com ← You are here

• @ collateral.makerdao.com

• @ mips.makerdao.com

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)

  • To open a Vault, head to

The Maker Protocol Smart Contract Modules System

• Module Name: Vault Core Module

• Type/Category: Vault Core Module —> ( Vat.sol, Spot.sol )

• Associated MCD System Diagram

• Contract Sources:

1. Introduction (Summary)

The Core Module is crucial to the system as it contains the entire state of the Maker Protocol and controls the central mechanisms of the system while it is in the expected normal state of operation.

2. Module Details

Core Module Components Documentation

3. Key Mechanism and Concepts

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

• Spot - poke is the only non-authenticated function in spot. The function takes in a bytes32 of the

4. Gotchas (Potential sources of user error)

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

• When the Cat is upgraded, there are multiple references to it that must be updated at the same time (End, Vat.rely

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

Coding Errors

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

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

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

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

Governance

• Vat - 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 crypto economic protections that make doing so prohibitively expensive fail, the system may be vulnerable and left open for bad actors to drain collateral.

• Module Name: Collateral Module

• Type/Category: DSS —> join.sol, clip.sol

• Associated MCD System Diagram

• Contract Sources:

1. Introduction (Summary)

The collateral module is deployed for every new ilk (collateral type) added to Vat. It contains all the adapters and auction contracts for one specific collateral type.

For other information related to the collateral module, read the following resources:

2. Module Details

The Collateral Module has 3 core components consisting of the join, and flip contracts.

The Collateral Module is built up of the following components:

2. Clipper Contract - see

3. Key Mechanism and Concepts

Summary of the Collateral Module Components

• Join - adapters that are used to deposit/withdraw unlocked collateral into the Vat. Join contains three smart contracts:

  1. GemJoin

  2. ETHJoin

How exactly do the Join contracts help the MCD system operate?

• Join - the purpose of join adapters is to retain the security of the system, allowing only trusted smart contracts to add/remove value to/from the Vat. The location of collateral deposited/locked in Vaults is in the respective Join adapter.

4. Gotchas (Potential sources of user error)

• When a user desires to enter the system and interact with the dss contracts, they must use one of the join contracts.

• If there was a contract bug in a join contract and a user was to call join by accident, they can still retrieve their tokens back through the corresponding exit call on the given join contract.

5. Failure Modes

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.

Potential Phishing Attacks

As the MCD system evolves, we will see many more join contracts, user interfaces, etc. This surfaces the potential for a user to have their funds stolen by a malicious join contract which would send tokens to an external contract or wallet, instead of the vat.

• Contract Name: spot.sol

• Type/Category: DSS —> Core Module

Summary

This page applies only to Single-Collateral Dai.

Retrieve the ETH CDP Service through Maker.service('cdp'). The ETH CDP Service exposes risk parameter information for the Ether CDP type (in single-collateral Dai, this is the only CDP Type).

For a quick overview of Emergency Shutdown within the Maker Protocol and the process to follow as an integration partner, please download and read the ES Partner Integration Slide Deck (PDF) below.

Introduction

is a JavaScript library that makes it easy to build applications on top of MakerDAO's platform of smart contracts. You can use Maker's contracts to open Vaults (formerly known as CDPs), deposit collateral and generate Dai, trade tokens on decentralized exchanges, and more.

The library features a pluggable, service-based architecture, which allows users to easily integrate Maker functionality into their own apps. It also includes convenient configuration presets for out-of-the-box usability and support for both front-end and back-end applications, plus plugins for integrating with Maker governance, hardware wallets, and both Single-Collateral and Multi-Collateral Dai.

Introduction

A big part of the Maker Protocol is the incentivization of external agents, called Keepers (which can be human but are typically automated bots). Market Maker Keepers work by creating a series of orders in so-called bands (defined later), which are configured with a JSON file containing parameters like spreads, maximum engagement, etc. In short, the market-maker-keeper repository is a set of Keepers that facilitate market making on exchanges. For example, trading Dai motivated by the expected long-term convergence toward the indicated Target Price. This guide is dedicated to showing you how to create your very own Market Maker Keeper Bot as well as educate the community and help both users and developers understand the value of this incredible software. We are proud to say that all of the code needed to get a Market Maker Keeper bot up and running is open-sourced.

Summary

Retrieve the PriceService through Maker.service('price'). The PriceService exposes the collateral and governance tokens' price information that is reported by the oracles in the Maker system.

getEthPrice

To override the address of one of the contracts used by Dai.js or a plugin, you can pass the smartContract.addressOverrides option. You need to know the key of the contract in the addresses file to override it.

List of mainnet addresses

const service = Maker.create('test' {
  smartContract: {
    addressOverrides: {
      PROXY_REGISTRY: '0xYourAddress'
    }
  } 
});

• Module Name: DAI Module

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

• Associated MCD System Diagram

• 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

Core Module Components Documentation

2. (referenced in Join - Detailed 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)

• DAI is also susceptible to the known , but should not normally be an issue with unlimited approval. We recommend any users using the approval for a specific amount be aware of this particular issue and use caution when authorizing other contracts to perform transfers on their behalf.

• 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: join.sol

• Type/Category: DSS —> Token Adapter Module

• Associated MCD System Diagram

• 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

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

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

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.

Find all Maker Protocol contract addresses and ABIs at chainlog.makerdao.com

The Chainlog provides valuable information for developers interacting with Maker Protocol deployments. This includes deployments on the following networks:

• Ethereum Mainnet (latest release)

• Ethereum Goerli Testnet ()

Each release includes the following information:

• Contract addresses with link to Etherscan

• ABIs

Onchain Contract Address Directory

The Chainlog is also available as an onchain smart contract directory () that allows developers to programatically fetch Maker Protocol contract addresses directly in a smart contract. This is useful for integrators that want to future-proof implementations in case a Maker module is updated. You can

Use the mcd:systemData service to look up system-wide parameters. In the code, this is called SystemDataService.

const service = maker.service('mcd:systemData');

Instance methods

getAnnualBaseRate()

Returns the base rate applied to all collateral types, in addition to their individual risk premiums.

getSystemWideDebtCeiling()

Returns the debt ceiling for the entire system.

isGlobalSettlementInvoked()

Returns a boolean that is true if emergency shutdown has been triggered.

Dai.js supports plugins, which allow a developer to add functionality (hardware wallet support, exchange support, etc.) for specific needs without increasing the size and dependency list of the core library.

Available Plugins

1. Trezor Plugin for using Trezor with dai.js in a browser environment.

2. for using Ledger in a browser environment.

3. for working with the governance contracts.

4. for atomic trading on maker OTC (Oasis).

5. for interacting with the maker OTC contract (Oasis).

6. for interacting with the multi-collateral dai contracts.

7. for interacting with the single-collateral dai contracts.

Building your own plugin

Check out the .

Use the 'mcd:savings' service to work with the Dai Savings Rate system. In the code, this is called SavingsService.

Instance methods

All the methods below are asynchronous. join, exit, and exitAll use a proxy contract.

join(amount)

Deposit the specified amount of Dai into the Dai Savings Rate (DSR) contract.

exit(amount)

Withdraw the specified amount of Dai from the DSR contract.

exitAll()

Withdraw all Dai owned by the current account from the DSR contract.

balance()

Return the amount of Dai in the DSR contract owned by the . Strictly speaking, this method returns the amount of Dai owned by the proxy contract for the current address. to work with the methods above.

balanceOf(address)

Return the amount of Dai in the DSR contract owned by the specified address.

getTotalDai()

Get the total amount of Dai in the DSR contract for all users.

getYearlyRate()

Get the current annual savings rate.

Introduction

The Maker Protocol, which powers Multi Collateral Dai, is a smart-contract system that backs and stabilizes the value of Dai through a dynamic combination of Vaults, autonomous system of smart contracts, and appropriately incentivized external actors. The Dai Target Price is 1 US Dollar, translating to a 1:1 US Dollar soft peg. Shutdown is a process that can be used as a last resort to directly enforce the Target Price to holders of Dai and Vaults, and protect the Maker Protocol against attacks on its infrastructure.

Shutdown stops and gracefully settles the Maker Protocol while ensuring that all users, both Dai holders and Vault holders, receive the net value of assets they are entitled to.

In short, it allows Dai holders to directly redeem Dai for collateral after an Emergency Shutdown processing period.

Overview of the Shutdown Process

• The process of initiating Emergency Shutdown is decentralized and controlled by MKR voters, who can trigger it by depositing MKR into the Emergency Shutdown Module.

• Emergency Shutdown is triggered in the case of serious emergencies, such as long-term market irrationality, hacks, or security breaches.

• Emergency Shutdown stops and gracefully settles the Maker Protocol while ensuring that all users, both Dai holders and Vault users, receive the net value of assets they are entitled to.

For more information about the Shutdown of the Maker Protocol, read the below End - Detailed Documentation as well as the

Summary

To access system status information, retrieve the ETH CDP Service through Maker.service('cdp').

const service = maker.service('cdp');

getSystemCollateralization

• Params: none

• Returns: promise (resolves to system collateralization ratio)

getSystemCollateralization() returns the collateralization ratio for the entire system, e.g. 2.75

getTargetPrice

• Params: none

• Returns: promise (resolves to target price)

getTargetPrice() returns the target price of Sai in USD, that is, the value to which Sai is soft-pegged, which historically has been 1. It returns a USD_SAI .

Introduction

is dedicated to providing transparency to our community with respect to the results of our MCD Audits, our Bug Bounty Program, and Formal Verification. It is important to note that this release is the first version and we will continue to add information as it becomes available.

The transactionManager service is used to track a transaction's status as it propagates through the blockchain.

Methods in Dai.js that start transactions are asynchronous, so they return promises. These promises can be passed as arguments to the transaction manager to set up callbacks when transactions change their status to pending, mined, confirmed or error.

Pass the promise to transactionManager.listen with callbacks, as shown below.

Note that the confirmed event will not fire unless transactionManager.confirm

Summary

Dai.js supports the use of multiple accounts (i.e. private keys) with a single Maker instance. Accounts can be specified in the options for Maker.create or with the addAccount method.

Call useAccount to switch to using an account by its name, or useAccountWithAddress to switch to using an account by its address, and subsequent calls will use that account as the transaction signer.

When the Maker instance is first created, it will use the account named

Introduction

The Maker Protocol, which powers Multi Collateral Dai (MCD), is a smart contract based system that backs and stabilizes the value of Dai through a dynamic combination of Vaults (formerly known as CDPs), autonomous feedback mechanisms, and incentivized external actors. To keep the system in a stable financial state, it is important to prevent both debt and surplus from building up beyond certain limits. This is where Auctions and Auction Keepers come in. The system has been designed so that there are three types of Auctions in the system: Surplus Auctions, Debt Auctions, and Collateral Auctions. Each auction is triggered as a result of specific circumstances.

Auction Keepers are external actors that are incentivized by profit opportunities to contribute to decentralized systems. In the context of the Maker Protocol, these external agents are incentivized to automate certain operations around the Ethereum blockchain. This includes:

Methods that take numerical values as input can also take instances of token classes that the library provides. These are useful for managing precision, keeping track of units, and passing in wei values. Most methods that return numerical values return them wrapped in one of these classes. There are two types:

• currency units, which represent an amount of a type of currency

• price units, aka currency ratios, which represent an exchange rate between two currencies.

The classes that begin with USD are price units; e.g. USD_ETH represents the price of ETH in USD. Useful instance methods:

Get the token conversion service with maker.service('conversion').

The token conversion service offers functions to convert between Eth, Weth and Peth, handling allowances when necessary.

convertEthToWeth

• Params: amount of Eth to convert

Summary

Retrieve the OasisExchangeService (or alternative implementation) through maker.service('exchange'). The exchange service allows to buy and sell DAI, MKR, and other tokens. The default OasisExchangeService implementation uses the OasisDEX OTC market for this.

Requires one of the exchange to be in use.

Use the 'mcd:cdpType' service to look up parameters for different collateral types in the system. In the code, this is called CdpTypeService.

Properties

cdpTypes

This is a list of , initialized during Maker.create.

Instance methods

getCdpType()

Return the for the specified currency and/or .

Collateral type instances

Properties

ilk

The name of the collateral type as a string, e.g. "ETH-A".

totalCollateral

The total amount of collateral locked in all vaults of this collateral type.

totalDebt

The total Dai debt drawn against all vaults of this collateral type.

debtCeiling

The debt ceiling for this collateral type.

liquidationRatio

Vaults of this type become unsafe (subject to liquidation) when their ratio between USD value of collateral and Dai drawn is less than or equal to this amount.

price

The USD price of this collateral type's token, using recent price feed data, as a . (See "A note on caching" above).

liquidationPenalty

The penalty added to the Dai amount to be raised at auction when a vault is liquidated, as a percentage. e.g. if the penalty is 13%, this value will be BigNumber(0.13).

annualStabilityFee

The annual stability fee (risk premium) of the collateral type, not including the , as a BigNumber. e.g. if the rate is 5%, this value will be BigNumber(0.05).

Caching

When a vault instance is created, its data is pre-fetched from the blockchain, allowing the properties below to be read synchronously. This data is cached in the instance. To refresh this data, do the following:

To refresh the data for all collateral type instances at once:

Get a token object through the getToken(tokenSymbol) function on the tokenService.

The list of tokens that can be passed into getToken() are: SAI, MKR, WETH, PETH, ETH.

This list can also be obtained with tokenService.getTokens(). This function returns a string representation of the token symbol, e.g. 'SAI', which can also be passed into getToken.

When the Multi-Collateral Dai plugin is in use, getToken('DAI') will return a token object for Dai.

Most of the methods below can be called on any token object. deposit and withdraw are for WETH only, and join and exit are for PETH only.

allowance

• Params:

• tokenOwner - address of token owner

• spender - address of token spender

• Returns: promise (resolves to token allowance)

allowance returns a representing the token allowance.

balance

• Params: none

• Returns: promise (resolves balance of current account)

balance returns a representing the token balance of the current account

balanceOf

• Params: address to check

• Returns: promise (resolves balance of address)

balanceOf returns a representing the token balance of the supplied account.

totalSupply

• Params: none

• Returns: promise (resolves total supply of token)

totalSupply returns a representing the total token supply

approve

• Params:

• spender - address of token spender

• amount - amount of token to allow

• Returns: promise (resolves to once mined)

approve approves the spending address to spend up to amount of msg.sender's tokens.

approveUnlimited

• Params: address of token spender

• Returns: promise (resolves to once mined)

approveUnlimited approves the spending address to spend the maximum amount of msg.sender's tokens.

transfer

• Params:

• to - address to send to

• amount - amount of token to send

• Returns: promise (resolves to once mined)

transfer transfers amount of token to to address.

transferFrom

• Params:

• from - address to send tokens from

• to - address to send to

• amount - amount of token to send

transferFrom() transfers amount of token from from address to to address. Transaction will fail if msg.sender does not have allowance to transfer the amount of tokens from the from address.

deposit (WETH only)

• Params: amount of Eth to deposit

• Returns: promise (resolves to once mined)

deposit converts amount of Eth to amount of Weth.

withdraw (WETH only)

• Params: amount of Weth to withdraw

• Returns: promise (resolves to once mined)

withdraw converts amount of Weth to amount of Eth.

join (PETH only)

• Params: amount of Weth to join

• Returns: promise (resolves to once mined)

join converts amount of Weth to Peth, at the .

exit (PETH only)

• Params: amount of Peth to exit

• Returns: promise (resolves to once mined)

withdraw converts amount of Peth to Weth, at the .

• Module Name: Oracle Module

• Type/Category: Oracles —> OSM.sol & Median.sol

Installation

Single-Collateral Dai support in Dai.js is implemented as a . The SCD plugin is also available as an package and its source code can be found on .

npm install @makerdao/dai-plugin-scd

Summary

The event pipeline allows developers to easily create real-time applications by letting them listen for important state changes and lifecycle events.

Wildcards

Summary

You can take advantage of the pluggable architecture of this library by choosing different implementations for services, and/or adding new service roles altogether. A service is just a Javascript class that inherits from either PublicService, PrivateService, or LocalService, and contains public method(s).

It can depend on other services through our built-in , and can also be configured through the Maker config file / config options.

Introduction

Understanding the various terms used in our smart contracts can involve a significant time investment for developers looking at the codebase for the first time. Due to this fact, we need resources in various formats to ensure they can get up and running quickly. We believe, in order to complement the technical documentation on docs.makerdao.com, that highlighting sections of the codebase and annotating it with comments can surface relevant information developers need while reading the raw contracts in order to understand the contracts better.

Examples of how annotations may be useful for developers:

Maker.create

You can configure the behavior of Dai.js by passing different arguments to Maker.create. The first argument is the name of a preset, and the second is an options object.

• Contract Name: VoteProxy.sol

• Type/Category: Proxy Module

• Contract Name: Vat.sol

• Type/Category: DSS —> Core System Accounting

• Associated MCD System Diagram

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

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

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

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

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.

• Contract Name: esm.sol

• Type/Category: Emergency Shutdown Module

• Associated MCD System Diagram

1. Introduction (Summary)

The Emergency Shutdown Module (ESM) is a contract with the ability to call End.cage() to trigger the Shutdown of the Maker Protocol.

2. Contract Details

ESM (Glossary)

Key Functionalities (as defined in the smart contract)

rely - Grant an address admin powers

deny - Revoke admin powers from an address

file - Allow admin to update threshold min and address of end

cage - Permanently disable the shutdown module

fire - Trigger shutdown by calling End.cage

denyProxy - Following the wards rely/deny pattern, calls deny on a given contract

join - Deposit MKR to the shutdown module

burn - Burn any MKR deposited into the shutdown module

Other

gem - MKR Token contract [address]

wards(admin: address) - Whether an address has admin powers [address: uint]

sum(usr: address) - MKR join balance by user [address: uint]

Sum - Total MKR deposited [uint]

min - Minimum MKR amount required for fire and denyProxy [uint]

end - The End contract [address]

live - Whether the contract is live (not caged) [uint]

3. Key Mechanisms & Concepts

MKR holders that wish to trigger Shutdown must join MKR into the ESM. When the ESM's internal Sum variable is equal to or greater than the minimum threshold (min), the ESM's fire() and denyProxy() methods may be called by anyone. The fire() method, in turn, calls End.cage(), which starts the Shutdown process.

The ESM is intended to be used in a few potential scenarios:

• To mitigate malicious governance

• To prevent the exploitation of a critical bug (for example one that allows collateral to be stolen)

In the case of a malicious governance attack, the joiners will have no expectation of recovering their funds (as that would require a malicious majority to pass the required vote), and their only option is to set up an alternative fork in which the majority's funds are slashed and their funds are restored.

In other cases, the remaining MKR holders may choose to refund the ESM joiners by minting new tokens.

Note: Governance can disarm the ESM by calling cage() (this is distinct from End.cage()).

4. Gotchas (Potential Source of User Error)

Unrecoverable of Funds

It is important for users to keep in mind that joining MKR into the ESM is irreversible—they lose it forever, regardless of whether they successfully trigger Shutdown. While it is possible that the remaining MKR holders may vote to mint new tokens for those that lose them triggering the ESM, there is no guarantee of this.

Game Theory of Funding and Firing the ESM

An entity wishing to trigger the ESM but possessing insufficient MKR to do so independently must proceed with caution. The entity could simply send MKR to the ESM to signal its desire and hope others join in; this, however, is poor strategy. Governance, whether honest or malicious, will see this, and likely move to de-authorize the ESM before the tipping point can be reached. It is clear why malicious governance would do so, but honest governance might act in a similar fashion—e.g. to prevent the system from being shut down by trolls or simply to maintain a constant threshold for ESM activation. (Honest governance, or even deceptive malicious governance, would be expected to then replace the ESM.) If governance succeeds in this, the entity has simply lost MKR without accomplishing anything.

If an entity with insufficient MKR wishes to trigger the ESM, it is better off first coordinating with others either off-chain or ideally via a trustless smart contract.. If a smart contract is used, it would be best if it employed zero-knowledge cryptography and other privacy-preserving techniques (such as transaction relayers) to obscure information such as the current amount of MKR committed and the addresses of those in support.

If an entity thinks others will join in before governance can react (e.g. if the delay for governance actions is very long), it is still possible that directly sending insufficient MKR to the ESM may work, but it carries a high degree of risk. Governance could even collude with miners to prevent cage calls, etc if they suspect an ESM triggering is being organized and wish to prevent it.

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

Authorization Misconfigurations

The ESM itself does not have an isolated failure mode, but if the other parts of the system do not have proper authorization configurations (e.g. the End contract does not authorize the ESM to call cage()), then the ESM's fire() method may be unable to trigger the Shutdown process even if sufficient MKR has been committed to the contract.

Introduction

The chief-keeper monitors and interacts with DSChief and DSSSpells, which is the executive voting contract and a type of proposal object of the Maker Protocol.

Its purpose is to lift the hat in DSChief as well as streamline executive actions.

To lift a spell, that spell must have more approvals than the current hat. The approvals of this spell can fluctuate and be surpassed by other spells, some of which could be malicious. This keeper "guards" the hat by ensuring the spell with the most approval is always the hat. The chief-keeper does this in order to maximize the barrier of entry (approval) to lift a spell to the hat, thus acting as a "guard" against malicious governance actions.

While in operation, the chief-keeper:

• Monitors each new block for a change in the state of executive votes

• lifts the hat for the spell (yay) most favored (approvals[yay])

• Schedules spells in the GSM by calling DSSSpell.schedule()

Review

The following section assumes familiarity with the , DSSSpells, and (Governance Security Module), as well as the processes within .

Architecture

chief-keeper interacts directly with the DS-Chief and DSSSpells.

Operation

This keeper is run continuously, and saves a local database of yays (spell addresses) and an yay:eta dictionary to reduce chain state reads. If you'd like to create your own database from scratch, first delete src/database/db_mainnet.json before running bin/chief-keeper; the initial query could take up to 15 minutes.

Installation

Prerequisites:

• • This project requires virtualenv to be installed if you want to use Maker's python tools. This helps with making sure that you are running the right version of python and checks that all of the pip packages that are installed in the install.sh are in the right place and have the right versions.

In order to clone the project and install required third-party packages please execute:

If tinydb isn't visible/installed through ./install.sh, simply run pip3 install tinydb after the commands above.

For some known Ubuntu and macOS issues see the README.

Sample Startup Script

Make a run-chief-keeper.sh to easily spin up the chief-keeper.

Testing

• Download

This project uses for unit testing. Testing of Multi-collateral Dai is performed on a Dockerized local testchain included in tests\config.

In order to be able to run tests, please install development dependencies first by executing:

You can then run all tests with:

Roadmap

License

See file.

Support

If you have questions regarding Cage Keepers, please reach out to us on the channel on .

Introduction

The cage-keeper is used to help facilitate Emergency Shutdown of the Maker Protocol. Emergency shutdown is an involved, deterministic process, requiring interaction from all user types: Vault owners, Dai holders, Redemption keepers, MKR governors, and other Maker Protocol Stakeholders. A high level overview is as follows:

1. System Caged - The Emergency Security Module calls End.cage() function, which freezes the USD price for each collateral type as well as many parts of the system.

2. Processing Period - Next, Vault owners interact with End to settle their Vault and withdraw excess collateral. Auctions are left to conclude or are yanked before Dai redemption.

3. Dai Redemption - After the processing period duration End.wait has elapsed, Vault settlement and all Dai generating processes (auctions) are assumed to have concluded. At this point, Dai holders can begin to claim a proportional amount of each collateral type at a fixed rate.

To prevent a race-condition for Dai holders during Step 3, it's imperative that any Vaults having a collateralization ratio of less than 100% at Step 1 must be processed during Step 2. The owner of an underwater Vault would not receive excess collateral, so they lack an incentive to skim their position in the End contract. Thus, it is the responsibility of a MakerDAO Stakeholder (MKR holders, large Dai holders, etc) to ensure the system facilitates a Dai redemption phase without a time variable. The cage-keeper is a tool to help stakeholders carry out this responsibility.

Prerequisites

The following section assumes familiarity with Emergency Shutdown. Good places to start is the Emergency Shutdown Module in Section 3 and Section 4 of the as well as a more thorough, . Functions mentioned are from the implementation contained by the End contract, which is .

To be consistent with the Protocol's technical terminology for the rest of this description:

• urn = Vault

• ilk = Collateral Type

Architecture

The cage-keeper directly interacts with the End, Flopper and Flapper contracts.

The central goal of the cage-keeper is to process all under-collateralized urns. This accounting step is performed within End.skim(), and since it is surrounded by other required/important steps in the Emergency Shutdown, a first iteration of this keeper will help to call most of the other public function calls within the End contract.

As can be seen in the above flowchart, the keeper checks if the system has been caged before attempting to skim all underwater urns and skip all flip auctions. After the processing period has been facilitated and the End.wait wait time has been reached, it will transition the system into the Dai redemption phase of Emergency Shutdown by calling End.thaw() and End.flow(). This first iteration of this keeper is naive, as it assumes it's the only keeper and attempts to account for all urns, ilks, and auctions. Because of this, it's important that the keeper's address has enough ETH to cover the gas costs involved with sending numerous transactions. Any transaction that attempts to call a function that's already been invoked by another Keeper/user would simply fail.

Operation

This keeper can either run continuously on a local/virtual machine or be run when the operator becomes aware of Emergency Shutdown. A sample startup script is shown below. The keeper's Ethereum address should have enough ETH to cover gas costs and is a function of the protocol's state at the time of shutdown (i.e. more urns to skim means more required ETH to cover gas costs). When new collateral types are added to the protocol, the operator should pull the latest version of the keeper, which would include contracts associated with the aforementioned collateral types.

After the cage-keeper facilitates the processing period, it can be turned off until End.wait is nearly reached. Then, at that point, the operator would pass in the --previous-cage argument during keeper start in order to bypass the feature that supports the processing period.

Installation

This project uses Python 3.6.2.

In order to clone the project and install required third-party packages please execute:

For some known Ubuntu and macOS issues see the README.

Sample Startup Script

Make a run-cage-keeper.sh to easily spin up the cage-keeper.

Testing

Prerequisites:

• Download

This project uses for unit testing. Testing of Multi-collateral Dai is performed on a Dockerized local testchain included in tests\config.

In order to be able to run tests, please install development dependencies first by executing:

You can then run all tests with:

License

See file

Support

If you have questions regarding Cage Keepers, please reach out to us on the channel on .

• Contract Name: token.sol

• Type/Category: MKR Module

• Associated MCD System Diagram

1. Introduction (Summary)

The MKR Module contains the MKR token, which is a deployed contract. It is an ERC20 token that provides a standard ERC20 token interface. It also contains logic for burning and authorized minting of MKR.

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.

Further information about the ERC20 Token standard can be found .

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.

The MKR token has 3 methods of use within the Maker Protocol (reference ):

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

Installation

Install the package with npm in your terminal:

npm install @makerdao/dai

Once it's installed, import the module into your project as shown below.

Multi-Collateral Dai support in Dai.js is implemented as a plugin. This may change in the future. The MCD Plugin is also available as an npm package and its source code can be found on Github.

npm install @makerdao/dai-plugin-mcd

(Note the .default at the end of the line when using require.)

UMD

This library is also usable as a , which you can build with npm run build:frontend.

Quick Examples

Look up information about a vault

This code uses to look up a vault that was created in the UI. Since this code is only reading data, not creating any transactions, it is not necessary to provide a private key or connect a wallet.

Create a vault

The code below opens a Vault, locks ETH into it, and draws out Dai.

Since this code sends transactions, it requires an account that can sign transactions. The simplest way to do this is to provide a privateKey configuration option as shown below, but you can also connect to Metamask or other browser-based providers, or connect to hardware wallets.

In the next section, learn more about how to configure the Maker instance with Maker.create. Or jump to learning more about , , , and .

Integration Examples

For larger examples of integrating this library, check out this and the .

The DsrManager provides an easy to use smart contract that allows service providers to deposit/withdraw dai into the DSR contract , and activate/deactivate the Dai Savings Rate to start earning savings on a pool of dai in a single function call. To understand the DsrManager, it is necessary to have an understanding of the first. The DSR is set by Maker Governance, and will typically be less than the base stability fee to remain sustainable. The purpose of DSR is to offer another incentive for holding Dai.

Deployment Details

• Module Name: Governance Module

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

• Contract Name: scd-mcd-migration.sol

• Type/Category: Migration

💡Note that this page applies only to Single-Collateral Sai.

After or , you can use the returned cdp object to call functions on it.

Properties

• Contract Name: dai.sol

• Type/Category: DSS —> Dai Module