Multi Collateral Dai

This repository contains the core smart contract code for Multi Collateral Dai. This is a high level description of the system, assuming familiarity with the basic economic mechanics as described in the whitepaper.

Additional Documentation

dss is also documented in the wiki and in DEVELOPING.md

Design Considerations

Token agnostic
- system doesn't care about the implementation of external tokens
- can operate entirely independently of other systems, provided an authority assigns initial collateral to users in the system and provides price data.
Verifiable
- designed from the bottom up to be amenable to formal verification
- the core cdp and balance database makes no external calls and contains no precision loss (i.e. no division)
Modular
- multi contract core system is made to be very adaptable to changing requirements.
- allows for implementations of e.g. auctions, liquidation, CDP risk conditions, to be altered on a live system.
- allows for the addition of novel collateral types (e.g. whitelisting)

Collateral, Adapters and Wrappers

Collateral is the foundation of Dai and Dai creation is not possible without it. There are many potential candidates for collateral, whether native ether, ERC20 tokens, other fungible token standards like ERC777, non-fungible tokens, or any number of other financial instruments.

Token wrappers are one solution to the need to standardise collateral behaviour in Dai. Inconsistent decimals and transfer semantics are reasons for wrapping. For example, the WETH token is an ERC20 wrapper around native ether.

In MCD, we abstract all of these different token behaviours away behind Adapters.

Adapters manipulate a single core system function: slip, which modifies user collateral balances.

Adapters should be very small and well defined contracts. Adapters are very powerful and should be carefully vetted by MKR holders. Some examples are given in join.sol. Note that the adapter is the only connection between a given collateral type and the concrete on-chain token that it represents.

There can be a multitude of adapters for each collateral type, for different requirements. For example, ETH collateral could have an adapter for native ether and also for WETH.

The Dai Token

The fundamental state of a Dai balance is given by the balance in the core (vat.dai, sometimes referred to as D).

Given this, there are a number of ways to implement the Dai that is used outside of the system, with different trade offs.

Fundamentally, "Dai" is any token that is directly fungible with the core.

In the Kovan deployment, "Dai" is represented by an ERC20 DSToken. After interacting with CDPs and auctions, users must exit from the system to gain a balance of this token, which can then be used in Oasis etc.

It is possible to have multiple fungible Dai tokens, allowing for the adoption of new token standards. This needs careful consideration from a UX perspective, with the notion of a canonical token address becoming increasingly restrictive. In the future, cross-chain communication and scalable sidechains will likely lead to a proliferation of multiple Dai tokens. Users of the core could exit into a Plasma sidechain, an Ethereum shard, or a different blockchain entirely via e.g. the Cosmos Hub.

Price Feeds

Price feeds are a crucial part of the Dai system. The code here assumes that there are working price feeds and that their values are being pushed to the contracts.

Specifically, the price that is required is the highest acceptable quantity of CDP Dai debt per unit of collateral.

Liquidation and Auctions

An important difference between SCD and MCD is the switch from fixed price sell offs to auctions as the means of liquidating collateral.

The auctions implemented here are simple and expect liquidations to occur in fixed size lots (say 10,000 ETH).

Settlement

Another important difference between SCD and MCD is in the handling of System Debt. System Debt is debt that has been taken from risky CDPs. In SCD this is covered by diluting the collateral pool via the PETH mechanism. In MCD this is covered by dilution of an external token, namely MKR.

As in collateral liquidation, this dilution occurs by an auction (flop), using a fixed-size lot.

In order to reduce the collateral intensity of large CDP liquidations, MKR dilution is delayed by a configurable period (e.g 1 week).

Similarly, System Surplus is handled by an auction (flap), which sells off Dai surplus in return for the highest bidder in MKR.

Authentication

The contracts here use a very simple multi-owner authentication system, where a contract totally trusts multiple other contracts to call its functions and configure it.

It is expected that modification of this state will be via an interface that is used by the Governance layer.

Dai - Detailed DocumentationThe Dai Token Contract

Contract Name: dai.sol
Type/Category: DSS —> Dai Module
Associated MCD System Diagram
Contract Source
Etherscan

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.

Dai Interactions with the Maker Protocol

https://docs.makerdao.com/~gitbook/image?url=https%3A%2F%2F4167714931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-legacy-files%2Fo%2Fassets%252F-LtJ1VeNJVW-jiKH0xoL%252F-LtukSxQ9uXGoKuAIxqZ%252F-Ltul-FozOkkL3LBSeLT%252FScreen%2520Shot%25202019-11-17%2520at%25202.08.05%2520PM.png%3Falt%3Dmedia%26token%3D1a097906-20ce-40e2-9dcc-76537b10d493&width=768&dpr=4&quality=100&sign=ad3dccad&sv=1

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

For the most part, dai.sol functions as a typical ERC20 token. These tokens have been already been heavily documented here and it is recommended to read through that documentation for the core functions of an ERC20 token.

Differences From ERC20:

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

DAI is also susceptible to the known ERC20 race condition, 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 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.

Maker DAO -- Multi Collateral Dai