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