A JavaScript library that makes it easy to build applications on top of MakerDAO's platform of smart contracts

Introduction

# Dai.js

## Introduction

[Dai.js](https://github.com/makerdao/dai.js) 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.

If you have questions regarding Dai.js that are not answered in the following pages, please reach out to us on the [\#dev](https://chat.makerdao.com/channel/dev) channel on [**chat.makerdao.com**](http://chat.makerdao.com/) or create a [Github issue](https://github.com/makerdao/dai.js/issues).


Smart Contracts

Auctions

Keepers

SDKs

CLIs

Glossary

MakerDAO is a decentralized organization dedicated to bringing stability to the cryptocurrency economy

Introduction to the Maker Protocol


# Introduction to the Maker Protocol

## 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:**

* [New Dai token ($DAI)](https://blog.makerdao.com/creating-the-brand-identity-for-the-worlds-first-unbiased-currency-dai/)
* Support for multiple Vault collateral types (Launching with ETH and BAT)
  * To open a Vault, head to [**Oasis Borrow**](https://oasis.app/borrow)
* [Dai Savings Rate (DSR)](https://blog.makerdao.com/why-the-dai-savings-rate-is-a-game-changer-for-the-defi-ecosystem-and-beyond/) 
  * To use the DSR, head to [**Oasis Save**](https://oasis.app/save)
* More robust peg ensuring mechanisms (MKR acting as backstop)
* Stability fees paid every block, rather than on Dai repayment
* [New Maker Terminology](https://blog.makerdao.com/say-goodbye-to-cdps-and-hello-to-maker-vaults/)
* MKR and governance remains the same
* [Oasis Trade](https://oasis.app/trade)

## The Maker Protocol Smart Contract Modules System

![The Maker Protocol System Diagram](/images/documentation/mcd-system-2.0%20%282%29.png)


Maker Protocol 101


# Maker Protocol 101

**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**](https://drive.google.com/file/d/1bEOlNk2xUXgwy0I_UlB_8tPPZ8mH1gy9/view?usp=sharing)**.**

[Maker Protocol 101 Slide Deck](/images/documentation/maker_protocol_101-2.pdf)

![](/images/documentation/screen-shot-2019-11-17-at-11.24.44-pm.png)


A Python API for the Maker Smart Contracts

Pymaker


# Pymaker

## Introduction

The Maker Protocol incentivizes external agents, called _keepers_, to automate certain operations around the Ethereum blockchain. In order to ease their development, an API around most of the Maker contracts has been created. It can be used not only by keepers, but may also be found useful by authors of some other, unrelated utilities aiming to interact with these contracts.

Based on the [Pymaker API](https://github.com/makerdao/pymaker), a set of reference Maker keepers is being developed. They all used to reside in this repository, but now each of them has an individual one: [bite-keeper](https://github.com/makerdao/bite-keeper) (SCD only), [arbitrage-keeper](https://github.com/makerdao/arbitrage-keeper), [auction-keeper](https://github.com/makerdao/auction-keeper) (MCD only), [cdp-keeper](https://github.com/makerdao/cdp-keeper) (SCD only), [market-maker-keeper](https://github.com/makerdao/market-maker-keeper).

You only need to install this project directly if you want to build your own keepers, or if you want to play with this API library itself. If you just want to install one of reference keepers, go to one of the repositories linked above and start from there. Each of these keepers references some version of `pymaker` via a Git submodule.

## Installation

This project uses _Python 3.6.6_.

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

```bash
git clone https://github.com/makerdao/pymaker.git
cd pymaker
pip3 install -r requirements.txt
```

#### Known Ubuntu issues

In order for the `secp256k` Python dependency to compile properly, following packages will need to be installed:

```bash
sudo apt-get install build-essential automake libtool pkg-config libffi-dev python-dev python-pip libsecp256k1-dev
```

(for Ubuntu 18.04 Server)

#### Known macOS issues

In order for the Python requirements to install correctly on _macOS_, please install `openssl`, `libtool`, `pkg-config` and `automake` using [Homebrew](https://brew.sh/):

```bash
brew install openssl libtool pkg-config automake
```

and set the `LDFLAGS` environment variable before you run `pip3 install -r requirements.txt`:

```bash
export LDFLAGS="-L$(brew --prefix openssl)/lib" CFLAGS="-I$(brew --prefix openssl)/include"
```

## Available APIs

**The current version provides APIs around:**

- `ERC20Token`,
- `Tub`, `Tap`,`Top` and `Vox` ([https://github.com/makerdao/sai](https://github.com/makerdao/sai)),
- `Vat`, `Cat`, `Vow`, `Jug`, `Flipper`, `Flapper`, `Flopper` ([https://github.com/makerdao/dss](https://github.com/makerdao/dss))
- `SimpleMarket`, `ExpiringMarket` and `MatchingMarket` ([https://github.com/makerdao/maker-otc](https://github.com/makerdao/maker-otc)),
- `TxManager` ([https://github.com/makerdao/tx-manager](https://github.com/makerdao/tx-manager)),
- `DSGuard` ([https://github.com/dapphub/ds-guard](https://github.com/dapphub/ds-guard)),
- `DSToken` ([https://github.com/dapphub/ds-token](https://github.com/dapphub/ds-token)),
- `DSEthToken` ([https://github.com/dapphub/ds-eth-token](https://github.com/dapphub/ds-eth-token)),
- `DSValue` ([https://github.com/dapphub/ds-value](https://github.com/dapphub/ds-value)),
- `DSVault` ([https://github.com/dapphub/ds-vault](https://github.com/dapphub/ds-vault)),
- `EtherDelta` ([https://github.com/etherdelta/etherdelta.github.io](https://github.com/etherdelta/etherdelta.github.io)),
- `0x v1` ([https://etherscan.io/address/0x12459c951127e0c374ff9105dda097662a027093\#code](https://etherscan.io/address/0x12459c951127e0c374ff9105dda097662a027093#code), [https://github.com/0xProject/standard-relayer-api](https://github.com/0xProject/standard-relayer-api)),
- `0x v2`
- `Dai Savings Rate (Pot)`([https://github.com/makerdao/pymaker/blob/master/tests/manual_test_dsr.py\#L29](https://github.com/makerdao/pymaker/blob/master/tests/manual_test_dsr.py#L29))

**APIs around the following functionality have not been implemented:**

- `Global Settlement (End)`
- `Governance (DSAuth, DSChief, DSGuard, DSSpell, Mom)`

Contributions from the community are much appreciated!

### Code samples

Below you can find some code snippets demonstrating how the API can be used both for developing your own keepers and for creating some other utilities interacting with the Maker Protocol ecosystem contracts.

#### Token transfer

This snippet demonstrates how to transfer some SAI from our default address. The SAI token address is discovered by querying the `Tub`, so all we need as a `Tub` address:

```python
from web3 import HTTPProvider, Web3

from pymaker import Address
from pymaker.token import ERC20Token
from pymaker.numeric import Wad
from pymaker.sai import Tub


web3 = Web3(HTTPProvider(endpoint_uri="http://localhost:8545"))

tub = Tub(web3=web3, address=Address(' 0xb7ae5ccabd002b5eebafe6a8fad5499394f67980'))
sai = ERC20Token(web3=web3, address=tub.sai())

sai.transfer(address=Address(' 0x0000000000111111111100000000001111111111'),
             value=Wad.from_number(10)).transact()
```

#### Updating a DSValue

This snippet demonstrates how to update a `DSValue` with the ETH/USD rate pulled from _CryptoCompare_:

```python
import json
import urllib.request

from web3 import HTTPProvider, Web3

from pymaker import Address
from pymaker.feed import DSValue
from pymaker.numeric import Wad


def cryptocompare_rate() -> Wad:
    with urllib.request.urlopen("https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD") as url:
        data = json.loads(url.read().decode())
        return Wad.from_number(data['USD'])


web3 = Web3(HTTPProvider(endpoint_uri="http://localhost:8545"))

dsvalue = DSValue(web3=web3, address=Address(' 0x038b3d8288df582d57db9be2106a27be796b0daf'))
dsvalue.poke_with_int(cryptocompare_rate().value).transact()
```

#### SAI introspection

This snippet demonstrates how to fetch data from `Tub` and `Tap` contracts:

```python
from web3 import HTTPProvider, Web3

from pymaker import Address
from pymaker.token import ERC20Token
from pymaker.numeric import Ray
from pymaker.sai import Tub, Tap


web3 = Web3(HTTPProvider(endpoint_uri="http://localhost:8545"))

tub = Tub(web3=web3, address=Address(' 0x448a5065aebb8e423f0896e6c5d525c040f59af3'))
tap = Tap(web3=web3, address=Address(' 0xbda109309f9fafa6dd6a9cb9f1df4085b27ee8ef'))
sai = ERC20Token(web3=web3, address=tub.sai())
skr = ERC20Token(web3=web3, address=tub.skr())
gem = ERC20Token(web3=web3, address=tub.gem())

print(f"")
print(f"Token summary")
print(f"-------------")
print(f"SAI total supply       : {sai.total_supply()} SAI")
print(f"SKR total supply       : {skr.total_supply()} SKR")
print(f"GEM total supply       : {gem.total_supply()} GEM")
print(f"")
print(f"Collateral summary")
print(f"------------------")
print(f"GEM collateral         : {tub.pie()} GEM")
print(f"SKR collateral         : {tub.air()} SKR")
print(f"SKR pending liquidation: {tap.fog()} SKR")
print(f"")
print(f"Debt summary")
print(f"------------")
print(f"Debt ceiling           : {tub.cap()} SAI")
print(f"Good debt              : {tub.din()} SAI")
print(f"Bad debt               : {tap.woe()} SAI")
print(f"Surplus                : {tap.joy()} SAI")
print(f"")
print(f"Feed summary")
print(f"------------")
print(f"REF per GEM feed       : {tub.pip()}")
print(f"REF per SKR price      : {tub.tag()}")
print(f"GEM per SKR price      : {tub.per()}")
print(f"")
print(f"Tub parameters")
print(f"--------------")
print(f"Liquidation ratio      : {tub.mat()*100} %")
print(f"Liquidation penalty    : {tub.axe()*100 - Ray.from_number(100)} %")
print(f"Stability fee          : {tub.tax()} %")
print(f"")
print(f"All cups")
print(f"--------")
for cup_id in range(1, tub.cupi()+1):
    cup = tub.cups(cup_id)
    print(f"Cup #{cup_id}, lad={cup.lad}, ink={cup.ink} SKR, tab={tub.tab(cup_id)} SAI, safe={tub.safe(cup_id)}")
```

#### Multi-collateral Dai

This snippet demonstrates how to create a CDP and draw Dai.

```python
import sys
from web3 import Web3, HTTPProvider

from pymaker import Address
from pymaker.deployment import DssDeployment
from pymaker.keys import register_keys
from pymaker.numeric import Wad


web3 = Web3(HTTPProvider(endpoint_uri="https://localhost:8545",
                         request_kwargs={"timeout": 10}))
web3.eth.defaultAccount = sys.argv[1]   # ex:  0x0000000000000000000000000000000aBcdef123
register_keys(web3, [sys.argv[2]])      # ex: key_file=~keys/default-account.json,pass_file=~keys/default-account.pass

mcd = DssDeployment.from_json(web3=web3, conf=open("tests/config/kovan-addresses.json", "r").read())
our_address = Address(web3.eth.defaultAccount)


# Choose the desired collateral; in this case we'll wrap some Eth
collateral = mcd.collaterals['ETH-A']
ilk = collateral.ilk
collateral.gem.deposit(Wad.from_number(3)).transact()

# Add collateral and allocate the desired amount of Dai
collateral.approve(our_address)
collateral.adapter.join(our_address, Wad.from_number(3)).transact()
mcd.vat.frob(ilk, our_address, dink=Wad.from_number(3), dart=Wad.from_number(153)).transact()
print(f"CDP Dai balance before withdrawal: {mcd.vat.dai(our_address)}")

# Mint and withdraw our Dai
mcd.approve_dai(our_address)
mcd.dai_adapter.exit(our_address, Wad.from_number(153)).transact()
print(f"CDP Dai balance after withdrawal:  {mcd.vat.dai(our_address)}")

# Repay (and burn) our Dai
assert mcd.dai_adapter.join(our_address, Wad.from_number(153)).transact()
print(f"CDP Dai balance after repayment:   {mcd.vat.dai(our_address)}")

# Withdraw our collateral
mcd.vat.frob(ilk, our_address, dink=Wad(0), dart=Wad.from_number(-153)).transact()
mcd.vat.frob(ilk, our_address, dink=Wad.from_number(-3), dart=Wad(0)).transact()
collateral.adapter.exit(our_address, Wad.from_number(3)).transact()
print(f"CDP Dai balance w/o collateral:    {mcd.vat.dai(our_address)}")
```

#### Asynchronous invocation of Ethereum transactions

This snippet demonstrates how multiple token transfers can be executed asynchronously:

```python
from web3 import HTTPProvider
from web3 import Web3

from pymaker import Address, synchronize
from pymaker.numeric import Wad
from pymaker.sai import Tub
from pymaker.token import ERC20Token


web3 = Web3(HTTPProvider(endpoint_uri="http://localhost:8545"))

tub = Tub(web3=web3, address=Address(' 0x448a5065aebb8e423f0896e6c5d525c040f59af3'))
sai = ERC20Token(web3=web3, address=tub.sai())
skr = ERC20Token(web3=web3, address=tub.skr())

synchronize([sai.transfer(Address(' 0x0101010101020202020203030303030404040404'), Wad.from_number(1.5)).transact_async(),
             skr.transfer(Address(' 0x0303030303040404040405050505050606060606'), Wad.from_number(2.5)).transact_async()])
```

#### Multiple invocations in one Ethereum transaction

This snippet demonstrates how multiple token transfers can be executed in one Ethereum transaction. A `TxManager` instance has to be deployed and owned by the caller.

```python
from web3 import HTTPProvider
from web3 import Web3

from pymaker import Address
from pymaker.approval import directly
from pymaker.numeric import Wad
from pymaker.sai import Tub
from pymaker.token import ERC20Token
from pymaker.transactional import TxManager


web3 = Web3(HTTPProvider(endpoint_uri="http://localhost:8545"))

tub = Tub(web3=web3, address=Address(' 0x448a5065aebb8e423f0896e6c5d525c040f59af3'))
sai = ERC20Token(web3=web3, address=tub.sai())
skr = ERC20Token(web3=web3, address=tub.skr())

tx = TxManager(web3=web3, address=Address(' 0x57bFE16ae8fcDbD46eDa9786B2eC1067cd7A8f48'))
tx.approve([sai, skr], directly())

tx.execute([sai.address, skr.address],
           [sai.transfer(Address(' 0x0101010101020202020203030303030404040404'), Wad.from_number(1.5)).invocation(),
            skr.transfer(Address(' 0x0303030303040404040405050505050606060606'), Wad.from_number(2.5)).invocation()]).transact()
```

#### Ad-hoc increasing of gas price for asynchronous transactions

```python
import asyncio
from random import randint

from web3 import Web3, HTTPProvider

from pymaker import Address
from pymaker.gas import FixedGasPrice
from pymaker.oasis import SimpleMarket


web3 = Web3(HTTPProvider(endpoint_uri=f"http://localhost:8545"))
otc = SimpleMarket(web3=web3, address=Address(' 0x375d52588c3f39ee7710290237a95C691d8432E7'))


async def bump_with_increasing_gas_price(order_id):
    gas_price = FixedGasPrice(gas_price=1000000000)
    task = asyncio.ensure_future(otc.bump(order_id).transact_async(gas_price=gas_price))

    while not task.done():
        await asyncio.sleep(1)
        gas_price.update_gas_price(gas_price.gas_price + randint(0, gas_price.gas_price))

    return task.result()


bump_task = asyncio.ensure_future(bump_with_increasing_gas_price(otc.get_orders()[-1].order_id))
event_loop = asyncio.get_event_loop()
bump_result = event_loop.run_until_complete(bump_task)

print(bump_result)
print(bump_result.transaction_hash)
```

## Testing

Prerequisites:

- [docker and docker-compose](https://www.docker.com/get-started)
- [ganache-cli](https://github.com/trufflesuite/ganache-cli) 6.2.5 (using npm, `sudo npm install -g ganache-cli@6.2.5`)

This project uses [pytest](https://docs.pytest.org/en/latest/) 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:

```bash
pip3 install -r requirements-dev.txt
```

You can then run all tests with:

```bash
./test.sh
```

If you have questions regarding Pymaker, please reach out to us on the [\#keeper](https://chat.makerdao.com/channel/keeper) channel on [**chat.makerdao.com**](http://chat.makerdao.com/).


Learn how to integrate your wallet into the Dai.js library

How to build a Dai.js wallet plugin

# How to build a Dai.js wallet plugin

**Level:** Intermediate  
**Estimated Time:** 30 - 45 min

* [How to build a Dai.js wallet plugin](#how-to-build-a-daijs-wallet-plugin)
  * [Overview](#overview)
  * [Learning Objectives](#learning-objectives)
  * [Pre-requisites](#pre-requisites)
  * [Sections](#sections)
    * [Understand Dai.js wallet provider requirements](#understand-daijs-wallet-provider-requirements)
  * [Examples of partners integrating with the plugin](#examples-of-partners-integrating-with-the-plugin)
    * [Tier 1](#tier-1)
    * [Tier 2](#tier-2)
    * [Tier 3](#tier-3)
  * [Front-End Dai.js plugin implementation](#front-end-daijs-plugin-implementation)
  * [Summary](#summary)
  * [Additional Resources](#additional-resources)
  * [Help](#help)

## Overview

In this guide, we’ll walk you through building your own Dai.js plugin that integrates a wallet provider. As we know, there are many wallet providers out there. In order for these wallet providers to interact with the Maker suite of dapps (oasis.app, governance dashboard, migration app), they have to integrate through the Dai.js SDK. As this SDK is used in the Maker dapps, your wallet can be used to interact with the Maker Protocol.

## Learning Objectives

Here you’ll learn how to integrate your wallet into the Dai.js SDK by creating a Dai.js wallet plugin.

* Understand Dai.js wallet provider requirements
* Example of partners integrating with the plugin
* Front-End Dai.js plugin implementation

## Pre-requisites

Knowledge in:

* [Web3 wallets](https://ethereum.org/use/#3-what-is-a-wallet-and-which-one-should-i-use)
* Javascript
* [Dai.js](/documentation/introduction-to-dai-js)

## Sections

### Understand Dai.js wallet provider requirements

There are a few types of plugins the Dai.js SDK can accept or parse through. One type we are going to use in this guide is a **callback function**. This callback function needs to pass to the SDK an object with properties such as **subprovider**, user’s wallet **address** and in some cases a **handleRequest** function from the provided wallet plugin.

To start with, below you’ll see an example of how you can structure your **index.js** file in your plugin repository. This is the core function that needs to be in your index.js file. In addition, you’ll have to add extra logic from your own wallet provider to fill the below function’s requirements.

```javascript
export default function (maker) {
  const MYWALLETNAME = 'mywalletname';
  maker.service('accounts', true).addAccountType(MYWALLETNAME, (settings) => {
    // YOUR WALLET PROVIDER LOGIC
    // Invoke the web3 provider from the wallet - subprovider
    // Get user's wallet address
    return { subprovider, address };
  });
}
```

The above example is a function that takes a callback function as its parameter that will invoke the logic for providing the subprovider and address to the Dai.js SDK.

When this function is invoked in the SDK, it can access different kinds of services the SDK provides. Invoking a service in Dai.js is done by calling the [service()](https://github.com/makerdao/dai.js/blob/dev/packages/dai/src/Maker.js#L67) function with the desired service name you require. In this example, the callback function will use the accounts service to add a new account type by using the [addAccountType()](https://github.com/makerdao/dai.js/blob/dev/packages/dai/src/eth/AccountsService.js#L51) function.

In this **addAccountType** function, you add two parameters. First one is the name of the account type (**MYWALLETNAME**) and the second is a callback function that will be used as a factory in the SDK.

Anytime the user will choose your account type to initialise the wallet from the frontend application, the SDK will call the function to invoke the logic for connecting the third party wallet.

This is the main pattern for how to integrate a third party wallet into the Dai.js SDK. Next, you will see some examples of how different partners have integrated.

## Examples of partners integrating with the plugin

There are different levels of complexity with which a third wallet provider could integrate with the Dai.js SDK. The level of complexity depends on the compatibility of this third party wallet provider with the SDK. The more compatible the easier it is to integrate.

The compatibility depends on the web3 provider engine. Dai.js mostly works with the [Hooked Wallet Provider](https://github.com/MetaMask/web3-provider-engine/blob/master/subproviders/hooked-wallet.js) engine from Metamask. Below, you’ll see three examples of web3 engine providers that are and aren’t compatible with the SDK and how they have been integrated. Tier 1 is the easiest example, while tier 2 and 3 grow in complexity.

### Tier 1

[WalletConnect](https://walletconnect.org/) is an open protocol for connecting wallets to Dapps. [The Dai Plugin WalletConnect repo](https://github.com/makerdao/dai-plugin-walletconnect) contains the code logic for connecting the wallet to Dai.js.

Below you can see the code from the [index.js](https://github.com/makerdao/dai-plugin-walletconnect/blob/master/src/index.js) file:

```javascript
import WalletConnectSubprovider from '@walletconnect/web3-subprovider';

export default function (maker) {
  const WALLETCONNECT = 'walletconnect';
  maker.service('accounts', true).addAccountType(WALLETCONNECT, async (settings) => {
    const subprovider = new WalletConnectSubprovider({
      bridge: 'https://bridge.walletconnect.org',
    });
    const { accounts } = await subprovider.getWalletConnector();
    const [address] = accounts;
    return { subprovider, address };
  });
}
```

As can be seen in the code example, this looks to be a straightforward solution. WalletConnect has its own web3-subprovider package that is compatible with the Dai.js SDK, which can be seen in the import:

```javascript
import WalletConnectSubprovider from '@walletconnect/web3-subprovider';
```

This subprovider is then used in the main export function to invoke the connection to the user’s wallet to obtain the address and provide it in the return function.

The `subprovider` already has the default **handleRequest** function that is needed by Dai.js to invoke transactions to the user. Hence, there’s no need to define it.

### Tier 2

[Ledger Wallet](https://www.ledger.com/) - a hardware wallet provider. The [Dai Plugin Ledger Web](https://github.com/makerdao/dai-plugin-ledger-web) repo contains the logic connecting the ledger wallet to Dai.js.

Below you can see the code from the [index.js](https://github.com/makerdao/dai-plugin-ledger-web/blob/master/src/index.js) file:

```javascript
import LedgerSubProvider, { setChosenAddress } from './vendor/ledger-subprovider';
import Transport from '@ledgerhq/hw-transport-u2f';

const legacyDerivationPath = "44'/60'/0'/0/0";
const defaultDerivationPath = "44'/60'/0'";

export default function (maker) {
  maker.service('accounts', true).addAccountType('ledger', async (settings) => {
    const subprovider = LedgerSubProvider(() => Transport.create(), {
      // options: networkId, path, accountsLength, accountsOffset
      accountsOffset: settings.accountsOffset || 0,
      accountsLength: settings.accountsLength || 1,
      networkId: maker.service('web3').networkId(),
      path: settings.path || (settings.legacy ? legacyDerivationPath : defaultDerivationPath),
    });

    let address;

    if (settings.accountsLength && settings.accountsLength > 1) {
      if (!settings.choose) {
        throw new Error('If accountsLength > 1, "choose" must be defined in account options.');
      }

      const addresses = await new Promise((resolve, reject) =>
        subprovider.getAccounts((err, addresses) => (err ? reject(err) : resolve(addresses)))
      );

      address = await new Promise((resolve, reject) => {
        const callback = (err, address) => (err ? reject(err) : resolve(address));

        // this chooser function allows the app using the plugin to display the
        // list of addresses to a human user and let them make a choice.
        settings.choose(
          Object.keys(addresses).map((k) => addresses[k]),
          callback
        );
      });
      setChosenAddress(address);
    } else {
      address = await new Promise((resolve, reject) =>
        subprovider.getAccounts((err, addresses) => (err ? reject(err) : resolve(addresses[0])))
      );
    }

    return { subprovider, address };
  });
}
```

In this example, the ledger subprovider is also compatible with the Dai.js SDK. Here, the code logic seems larger but it does the same function as compared to the WalletConnect. All the extra code is for setting up the Ledger provider to extract the user’s address and pass it down in the return object.

### Tier 3

[WalletLink](https://www.walletlink.org/#/) - link your Dapp to mobile wallets.

The [Dai Plugin WalletLink](https://github.com/makerdao/dai-plugin-walletlink) contains the logic connecting walletLink to Dai.js.

Below you can see the code from the index.js file.

```javascript
import WalletLink from 'walletlink';

export default function (maker) {
  const WALLETLINK = 'walletlink';

  maker.service('accounts', true).addAccountType(WALLETLINK, async (settings) => {
    const web3Service = maker.service('web3');
    const CHAIN_ID = web3Service.networkId();
    const ETH_JSONRPC_URL = web3Service.rpcUrl;

    const appName = 'MCD Portal';
    const walletLink = new WalletLink({ appName });
    const walletLinkProvider = walletLink.makeWeb3Provider(ETH_JSONRPC_URL, CHAIN_ID);

    const accounts = await walletLinkProvider.enable();
    const address = accounts[0];
    if (settings.callback && typeof settings.callback === 'function') {
      settings.callback(address);
    }

    // setEngine and handleRequest are expected by the web3ProviderEngine
    function setEngine(engine) {
      const self = this;
      if (self.engine) return;
      self.engine = engine;
      engine.on('block', function (block) {
        self.currentBlock = block;
      });

      engine.on('start', function () {
        self.start();
      });

      engine.on('stop', function () {
        self.stop();
      });
    }

    function handleRequest(payload, next, end) {
      const self = this;
      // Including the nonce throws an error "couldn't find tx for nonce"
      if (Array.isArray(payload.params)) delete payload.params[0].nonce;
      self.sendAsync(payload, (err, result) => {
        return result ? end(null, result.result) : end(err);
      });
    }

    walletLinkProvider.setEngine = setEngine;
    walletLinkProvider.handleRequest = handleRequest;

    return { subprovider: walletLinkProvider, address };
  });
}
```

In this example, walletLink’s web3 provider is not compatible with Dai.js, so there were added two extra functions in the callback to wrap walletLink’s provider. These functions are **setEngine()** and **handleRequest()**. Both these functions are added as an extra property to the **walletLinkProvider** object so it can become compatible with the Dai.js SDK. These functions are used to sign transactions from the SDK.

The **setEngine()** function sets the **walletLinkProvider** as the current web3 provider in the SDK.

The **handleRequest** function is used by the SDK to invoke transactions by providing the **payload** parameter. The payload parameter holds all the necessary data for the transaction to be signed. In other words, the payload is the data for the RPC call. This data has identifiers such as: **to address**, **from address**, **gas**, **nonce** and specific function data that might be used if it’s used to call smart contracts.

Inside the **handleRequest** function, we adapt it to call the walletLink **sendAsync** function with the provided **payload** from the SDK, so walletLink could process and display the transaction to the user.

After this, we return the **walletLinkProvider** and **address** for the Dai.js SDK to consume when **walletLink** account type is invoked by the user.

Next, you’ll see how to invoke the plugin in your front-end application.

## Front-End Dai.js plugin implementation

To see the live implementation of these plugins, head to [oasis.app](https://oasis.app/).

Oasis.app is a good example of how Dai.js works in handling all the plugins that it supports. The [oasis.app/borrow](https://oasis.app/borrow) feature is stored in this [repo](https://github.com/makerdao/mcd-cdp-portal) that you can clone on your machine. In the cloned repo, you can see how the plugins are instantiated and used throughout the application.

In the [/src/maker.js](https://github.com/makerdao/mcd-cdp-portal/blob/develop/src/maker.js) file you can see how the plugins are instantiated into the Dai.js SDK into a maker object that can be used everywhere across the application.

In [/src/utils/constants.js](https://github.com/makerdao/mcd-cdp-portal/blob/develop/src/utils/constants.js#L17) the different account types are defined that can be used in the application.

The [connectToProviderOfType](https://github.com/makerdao/mcd-cdp-portal/blob/develop/src/hooks/useMaker.js#L30) function will be used to invoke the **accountType** the user will choose in order to invoke the web3 engine provider.

Last thing, in [/src/components/AccountSelection.js](https://github.com/makerdao/mcd-cdp-portal/blob/develop/src/components/AccountSelection.js) we define the components that will be displayed for the user with the wallet options he can choose to interact with the application.

## Summary

In this guide we walked you through the process of creating a Dai.js wallet plugin and showed you the general pattern to integrate. As a rule of thumb, the more compatible your web3 provider is with the Dai.js SDK, the easier it will be to build the plugin. If it’s not compatible we showed you how to adapt the plugin to be able to communicate with the SDK. Lastly, we showed you a live implementation of how to integrate your plugin with oasis.app.

## Additional Resources

If you want to dive deeper into the web3 providers, have a look at Metamask’s [web3-provider-engine repo](https://github.com/MetaMask/web3-provider-engine).

## Help

For any help, you can reach us at:

* [#dev](https://chat.makerdao.com/channel/dev) chat in [chat.makerdao.com](https://chat.makerdao.com/channel/dev).
* Contact Integrations Team: [integrate@makerdao.com](mailto:integrate@makerdao.com)

Learn how to add a new collateral type to the Maker Protocol through seth

Add a new collateral type to Maker Protocol - Kovan


# Add a new collateral type to Maker Protocol - Kovan

**Level**: Advanced

**Estimated Time**: 90 - 120 minutes

- [Add a new collateral type to Maker Protocol - Kovan](#add-a-new-collateral-type-to-maker-protocol---kovan)
  - [Overview](#overview)
  - [Learning Objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Guide](#guide)
    - [Setup](#setup)
    - [Collateral Type](#collateral-type)
    - [Setup Spell](#setup-spell)
    - [Price Feeds](#price-feeds)
    - [Deploy Adapter](#deploy-adapter)
    - [Deploy Collateral Auction contract](#deploy-collateral-auction-contract)
    - [Calculate Risk Parameters](#calculate-risk-parameters)
    - [Deploy Spell](#deploy-spell)
    - [Governance actions](#governance-actions)
    - [Execute Spell](#execute-spell)
    - [Test Collateral Type](#test-collateral-type)
  - [Troubleshooting](#troubleshooting)
  - [Summary](#summary)
  - [Additional resources](#additional-resources)
  - [Next Steps](#next-steps)
  - [Help](#help)

## Overview

The Maker Protocol deployed to the Kovan testnet supports multiple collateral types. You can now add a new token as a collateral type, and allow users and developers to test various aspects of this integration. This guide covers the steps involved in setting up various contracts to initialize a new collateral type on the testnet. Adding it to the mainnet deployment will be handled by risk teams and those steps will not be covered in this guide.

## Learning Objectives

After going through this guide you will get a better understanding of,

- Configuring core Maker Protocol contracts
- Additional contracts required: Price Feed, Auction, Adapter.
- Governance steps to initialize the new collateral type.

## Pre-requisites

You will need a good understanding of these concepts to be able to work through this guide,

- [MCD 101](https://github.com/makerdao/developerguides/blob/master/mcd/mcd-101/mcd-101.md).
- Vaults
- Risk parameters of a collateral type
- Solidity
- Dapptools - Dapp, Seth

## Guide

*Before starting this guide please install [dapptools](https://dapp.tools) and [setup seth](https://github.com/makerdao/developerguides/blob/master/devtools/seth/seth-guide-01/seth-guide-01.md) for use with the Kovan testnet.*

The guide below is updated for the [0.2.17](https://changelog.makerdao.com/releases/kovan/0.2.17/index.html) release of Maker Protocol on Kovan.

For this tutorial you will want to set the gas limit to 3,000,000

```bash
export ETH_GAS=3000000
```

### Setup

Execute these commands to initialize environment variables with addresses of the core Maker Protocol contracts.

```bash
export MCD_VAT=0xba987bdb501d131f766fee8180da5d81b34b69d9
export MCD_CAT=0x0511674a67192fe51e86fe55ed660eb4f995bdd6
export MCD_JUG=0xcbb7718c9f39d05aeede1c472ca8bf804b2f1ead
export MCD_SPOT=0x3a042de6413edb15f2784f2f97cc68c7e9750b2d
export MCD_PAUSE=0x8754e6ecb4fe68daa5132c2886ab39297a5c7189
export MCD_PAUSE_PROXY=0x0e4725db88bb038bba4c4723e91ba183be11edf3
export MCD_ADM=0xbbffc76e94b34f72d96d054b31f6424249c1337d
export MCD_END=0x24728acf2e2c403f5d2db4df6834b8998e56aa5f
export MCD_JOIN_DAI=0x5aa71a3ae1c0bd6ac27a1f28e1415fffb6f15b8c
```

Set a variable with the address of the token going to be used for the collateral type. This guide will use the Kovan MKR token as an example.

```bash
export TOKEN=0xaaf64bfcc32d0f15873a02163e7e500671a4ffcd
```

### Collateral Type

Set the `ILK` variable with a name for the collateral type. Each ethereum token in Maker Protocol can have multiple collateral types and each one can be initialized with a different set of risk parameters. Affixing an alphabetical letter to the token symbol will help users differentiate these collateral types.

```bash
export ILK="$(seth --to-bytes32 "$(seth --from-ascii "MKR-A")")"
```

### Setup Spell

Initializing a collateral type involves making changes to various core Maker Protocol contracts using `file()` functions, and updating authorization permissions among contracts using `rely()`. A set of changes to be made at a time are captured in a `Spell` smart contract. Once a Spell is deployed, governance can elect its address as an authority which then lets it execute the changes in Maker Protocol. Although it is strictly not required, spells currently are designed to be used once and will lock up after they are executed.

Spell contracts can be built for various purposes, you will use an existing spell template to create a new collateral type.

Download the `dss-add-ilk-spell` repo and build it locally using the commands below. Please ensure you have `dapp` setup prior to executing this step. The build process is going to take a while!

```bash
git clone https://github.com/makerdao/dss-add-ilk-spell.git
cd dss-add-ilk-spell
dapp update
dapp build --extract
```

### Price Feeds

Off-chain oracles get the pricing data of a token from various exchange APIs and they then submit these updates to an on-chain median contract which computes a median value. The Oracle Security Module(OSM) introduces a delay before the system accepts the newly reported price to give users a chance to add more collateral if their Vault is about to become unsafe, and also for governance to trigger emergency shutdown if compromised oracles have input a malicious price value.

Instead of deploying the full set of these contracts, you will only deploy a single `DSValue` contract without a price feed delay for testing purposes. You can retain admin permissions over it to update the price value manually using a seth command. For example, the command below sets the price of each token to 9000 USD.

```bash
export PIP=$(dapp create DSValue)
seth send $PIP 'poke(bytes32)' $(seth --to-uint256 "$(seth --to-wei 9000 ETH)")
```

You can verify that the value has been set.

```bash
seth call $PIP 'read()'
```

### Deploy Adapter

Vat does not make calls to any external contracts, including tokens. Instead it maintains internal `gem` balances of users for each collateral type. Users deposit tokens into the corresponding adapter contract using `join()` to get this internal `gem` balance.

You can use the `GemJoin` adapter contract without making any modifications if it conforms to the ERC20 token standard, has simple transfer mechanics, and no known issues. Consider making changes to this contract if you need to perform additional checks to validate the token transfers a user makes to the adapter contract.

Examples of some non-standard adapters are available in [`dss`](https://github.com/makerdao/dss/blob/master/src/join.sol) and [`dss-deploy`](https://github.com/makerdao/dss-deploy/blob/master/src/join.sol) for your reference.

Execute this command to create a new `GemJoin` contract and initialize a variable with it's address.

```bash
export JOIN=$(dapp create GemJoin "$MCD_VAT" "$ILK" "$TOKEN")
```

### Deploy Collateral Auction contract

Deploy a new collateral auction contract(Flip) for the token.
Permit `Pause Proxy` address to make changes to the Flip contract using `rely()`, and remove permissions for your own address to make further changes using `deny()`.

```bash
export FLIP=$(dapp create Flipper "$MCD_VAT" "$ILK")
seth send "$FLIP" 'rely(address)' "$MCD_PAUSE_PROXY"
seth send "$FLIP" 'deny(address)' "$ETH_FROM"
```

### Calculate Risk Parameters

All collateral types need risk parameters to set bounds for issuing Dai debt. You'll set the new collateral type with some starting parameters and they can also be updated later by governance through executive votes.

Debt ceiling sets the maximum amount of Dai that can be issued against Vaults of this collateral type. Calculate the uint256 value using the first command to initialize the LINE variable with `5 Million`.

```bash
seth --to-uint256 $(echo "5000000"*10^45 | bc)
export LINE=000000000000000000000d5d238a4abe9806872a4904598d6d88000000000000
```

Collateralization ratio sets the amount of over-collateralization required for the collateral type.
Calculate the uint256 value using the first command to initialize the MAT variable with `150%`.

```bash
seth --to-uint256 $(echo "150"*10^25 | bc)
export MAT=000000000000000000000000000000000000000004d8c55aefb8c05b5c000000
```

Total stability fee accumulated for each collateral type inside its `rate` variable is calculated by adding up DSR `base` which is equal across all collateral types and the Risk Premium `duty` which is specific to each one.
Calculate the uint256 value using the first command to initialize the DUTY variable with an annual rate of `1%`.

```bash
seth --to-uint256 1000000000315522921573372069
export DUTY=0000000000000000000000000000000000000000033b2e3ca43176a9d2dfd0a5
```

*Note: How the number `1000000000315522921573372069` corresponds to a `1%` annual rate is covered in [this guide](https://github.com/makerdao/developerguides/blob/master/mcd/intro-rate-mechanism/intro-rate-mechanism.md)*

A liquidation penalty is imposed on a Vault by increasing its debt by a percentage before a collateral aucion is kicked off. This penalty is imposed to prevent [Auction Grinding Attacks](https://github.com/livnev/auction-grinding/blob/master/grinding.pdf).
Calculate the uint256 value using the first command to initialize the CHOP variable with an additional `10%`.  E.g. you can pass `110%` here so when you start an auction it will be for the amount of the outstanding debt plus `10%`.

```bash
seth --to-uint256 $(echo "110"*10^25 | bc)
export CHOP=0000000000000000000000000000000000000000038de60f7c988d0fcc000000
```

Vaults with locked collateral amounts greater than liquidation quantity of their collateral type are processed with multiple collateral auctions. Only one collateral auction is required if the amount of collateral locked in a Vault is below the liquidation quantity.

Calculate and initialize the LUMP variable with `1000`.

```bash
seth --to-uint256 $(echo "1000"*10^18 | bc)
export LUMP=00000000000000000000000000000000000000000000003635c9adc5dea00000
```

### Deploy Spell

You have everything setup to deploy a new spell contract that captures the steps that need to be executed to initialize a new collateral type.

Execute the command below to deploy this spell and capture its address in a variable.

```bash
export SPELL=$(seth send --create out/DssAddIlkSpell.bin 'DssAddIlkSpell(bytes32,address,address[8] memory,uint256[5] memory)' $ILK $MCD_PAUSE ["${MCD_VAT#0x}","${MCD_CAT#0x}","${MCD_JUG#0x}","${MCD_SPOT#0x}","${MCD_END#0x}","${JOIN#0x}","${PIP#0x}","${FLIP#0x}"] ["$LINE","$MAT","$DUTY","$CHOP","$LUMP"])
```

### Governance actions

Executing this spell requires control over a majority of the MKR deposited in the governance contract Chief.

Execute this command to add weight to this spell with your MKR deposited in the Chief.

```bash
seth send "$MCD_ADM" 'vote(address[] memory)' ["${SPELL#0x}"]
```

Please notify the [Maker Foundation Integrations team](mailto:integrate@makerdao.com) who can help you garner a majority of votes for this spell before it can be executed.

### Execute Spell

Once your spell reveives a majority of votes in Chief, execute this command to elect it as a `hat`.

```bash
seth send "$MCD_ADM" 'lift(address)' "${SPELL#0x}"
```

Once lifted as an authority, execute this command to schedule the spell for execution.

```bash
seth send "$SPELL" 'schedule()'
```

A Governance Delay is imposed on all new executive proposals before they go live to ensure there is enough time for emergency shutdown to be triggered before a malicious proposal which could potentially steal collateral from users gets executed. This is currently set to 300 seconds on the testnet deployment.

Execute the previously scheduled spell with the `cast()` function after this delay is over with this command.

```bash
seth send "$SPELL" 'cast()'
```

### Test Collateral Type

A collateral type is now initialized and ready for users to open Vaults. Let's test this process to ensure everything was setup correctly.

Deposit tokens into the adapter to receive an internal `gem` balance, and verify this balance.

```bash
seth send $TOKEN 'approve(address,uint256)' $JOIN $(seth --to-uint256 $(seth --to-wei 1000 eth))
seth --from-wei $(seth --to-dec $(seth call $TOKEN 'allowance(address, address)' $ETH_FROM $JOIN)) eth
```

Vaults of a collateral type are identified by the address of the owner itself. Set the `urn` variable to your ethereum address.

```bash
export urn=$ETH_FROM
```

Calculate and set the `wad` variable to deposit 20 tokens into the token adapter.

```bash
export wad=$(seth --to-uint256 $(seth --to-wei 20 eth))
```

Deposit tokens in the adapter contract and verify it by checking your `gem` balance of the collateral type in Vat.

```bash
seth send $JOIN "join(address, uint)" $ETH_FROM $wad

export ilk=$(seth --to-bytes32 $(seth --from-ascii "MKR-A"))
seth --from-wei $(seth --to-dec $(seth call $MCD_VAT 'gem(bytes32,address)(uint256)' $ilk $ETH_FROM)) eth
```

Calculate and set the `dink` variable to lock up 18 tokens in the Vault, and set the `dart` variable to generate 35 Dai from it.

```bash
export dink=$(seth --to-uint256 $(seth --to-hex $(seth --to-wei 18 eth)))
export dart=$(seth --to-uint256 $(seth --to-hex $(seth --to-wei 35 eth)))
```

Call `frob()` directly on Vat to open a Vault by locking up collateral and generating Dai.

```bash
seth send $MCD_VAT "frob(bytes32,address,address,address,int256,int256)" $ilk $ETH_FROM $ETH_FROM $ETH_FROM $dink $dart
```

Execute the command below to withdraw 10 Dai from the internal balance in Vat and receive ERC-20 Dai tokens using the Dai token adapter.

```bash
export wad=$(seth --to-word $(seth --to-wei 10 eth))
seth send $MCD_VAT "hope(address)" $MCD_JOIN_DAI
seth send $MCD_JOIN_DAI "exit(address, uint256)" $ETH_FROM $wad
```

You've now successfully generated Dai with the new collateral type.

## Troubleshooting

## Summary

In this guide you learned how to set up a new collateral type for a token and opened a Vault to generate Dai from it.

## Additional resources

1. [Drawing Dai from the Kovan MCD deployment using Seth](https://github.com/makerdao/developerguides/blob/master/mcd/mcd-seth/mcd-seth-01.md)

## Next Steps

## Help

- Rocket chat - [#dev](https://chat.makerdao.com/channel/dev) channel


Auction Keeper Bot Setup Guide

Learn about CDP Manager and use it to integrate with Maker Protocol

CDP Manager Guide


# CDP Manager Guide

**Level**: Advanced  
**Estimated Time**: 30 minutes

This guide works under the [1.0.7](https://changelog.makerdao.com/releases/kovan/1.0.7/contracts.json) Kovan release of the system

- [CDP Manager Guide](#cdp-manager-guide)
  - [Overview](#overview)
  - [Learning Objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [The Vault Lifecycle](#the-vault-lifecycle)
  - [Guide](#guide)
    - [Setup](#setup)
    - [Locking collateral into the system](#locking-collateral-into-the-system)
    - [Draw Dai](#draw-dai)
    - [Pay back Dai](#pay-back-dai)
    - [Unlock collateral from system](#unlock-collateral-from-system)

## Overview

The [DssCdpManager](https://github.com/makerdao/dss-cdp-manager) as known as the CDP Manager, was created to enable a formalised process to interact with the Maker Protocol. The manager works by having a [dss](https://github.com/makerdao/dss) wrapper that allows users to interact with their Vaults in an easy way, treating them as non-fungible tokens (NFTs).

In addition to the [dss-proxy](https://github.com/makerdao/dss-proxy-actions)-actions, the CDP Manager is the recommended interface to engage with the Maker Protocol as it allows users to easily transfer their Vaults to each other if need be. In addition, each Vault created through this interface gets an ID, which can then be used for purposes such as tracking your Vault positions, or attaching this ID to another reference in your own system.

By using the CDP Manager directly, the msg.sender will be the direct owner of the Vault in comparison to using ds-proxy and dss-proxy-actions, where the ds-proxy address will be the owner of the Vaults and the user will be the owner of the proxy.

## Learning Objectives

This guide will help you understand the functions available in the CDP Manager by walking you through the lifecycle of a Vault.

The lifecycle being:

- Lock collateral in the system
- Draw Dai
- Pay back Dai
- Unlock collateral from system

## Pre-requisites

You will need to have a good understanding of these concepts and tools in order to follow along this guide

- [MCD 101](https://github.com/makerdao/developerguides/blob/master/mcd/mcd-101/mcd-101.md)
- Solidity
- [Seth](https://github.com/dapphub/dapptools/tree/master/src/seth)

## The Vault Lifecycle

The Vault life cycle involves the process of locking some collateral token that is [approved](https://forum.makerdao.com/t/about-the-collateral-onboarding-app-category/1982) by the MKR token holders into the system, drawing Dai against this token, [using Dai](https://makerdao.com/en/ecosystem)[,](https://github.com/makerdao/awesome-makerdao#use-your-dai) paying back Dai into the system and freeing back the locked collateral.

Below are the functions that will be called in the CDP Manager contract. Note that additional functions need to be called in the token adapter contracts for depositing and withdrawing BAT and Dai.

- **Opening a Vault, depositing collateral and generating Dai**
  - `CDP_MANAGER.open()` - Open a CDP with the type of collateral you want to borrow Dai against
  - `BAT.approve()` - Approve BAT adapter to pull BAT from your wallet
  - `MCD_JOIN_BAT_A.join()` - Move BAT to BAT token adapter.
  - `CDP_MANAGER.frob()` - Lock BAT and create new Dai
  - `CDP_MANAGER.move()` - Move Dai from urn address to your wallet address, Dai is still in Vat.
  - `MCD_VAT.hope()` - Approve Dai token adapter in Vat to mint Dai
  - `MCD_JOIN_DAI.exit()` - Mint ERC-20 Dai to your wallet address
- **Paying back Dai, and retrieving collateral**
  - `MCD_DAI.approve()` - Approve Dai token adapter to pull Dai from your wallet
  - `MCD_JOIN_DAI.join()` - Move Dai to Dai token adapter
  - `CDP_MANAGER.frob()` - Pay back Dai debt and unlock BAT tokens
  - `CDP_MANAGER.flux()` - Move BAT tokens to your wallet address
  - `MCD_JOIN_BAT_A.exit()` - Withdraw BAT tokens to your wallet address

## Guide

Before starting this guide please install [dapptools](https://dapp.tools/) and [setup seth](https://github.com/makerdao/developerguides/blob/master/devtools/seth/seth-guide-01/seth-guide-01.md) for use with the Kovan testnet.

### Setup

Execute these commands to initialise environment variables with addresses of the Maker Protocol contracts. In your terminal, execute:

```bash
export CDP_MANAGER=0x1476483dD8C35F25e568113C5f70249D3976ba21
export MCD_VAT=0xbA987bDB501d131f766fEe8180Da5d81b34b69d9
export BAT=0x9f8cFB61D3B2aF62864408DD703F9C3BEB55dff7
export MCD_JOIN_BAT_A=0x2a4C485B1B8dFb46acCfbeCaF75b6188A59dBd0a
export MCD_DAI=0x4F96Fe3b7A6Cf9725f59d353F723c1bDb64CA6Aa
export MCD_JOIN_DAI=0x5AA71a3ae1C0bd6ac27A1f28e1415fFFB6F15B8c
export MCD_JUG=0xcbB7718c9F39d05aEEDE1c472ca8Bf804b2f1EaD
export ETH_GAS=2000000
```

We will use Kovan BAT tokens as our collateral in this guide. If you need to get some Kovan BAT tokens, follow [this guide.](https://github.com/makerdao/developerguides/blob/master/mcd/mcd-seth/mcd-seth-01.md#getting-tokens)

### Locking collateral into the system

As we use the CDP Manager for interacting with the system, first you will need to `open` an empty Vault.

Calling the `open` function, you will receive a `cdpId` of your Vault. When opening a Vault you have to specify the collateral type `(bytes32 ilk)` for the Vault. `address usr` is the address that will own the Vault.

In the CDP Manager code, a Vault is defined as an `urn`. The `urn` has an identifier address just like your wallet address. With this address the CDP Manager can handle the accounting of the urn. For example, when adding collateral to your Vault, the collateral is pulled from your wallet to the collateral token adapter and is registered under the urn address of your Vault. Each Vault has an urn address and an ID that can be easily identified.

Each Vault can only have one type of collateral. Hence, you as a user can open many Vaults with different or same collaterals. This approach gives you flexibility if you want to handle many Vaults.

An example where one would use this method of opening many Vaults, is custodial exchanges that want to integrate Vaults onto their platform. As the users don't have access to their keys to interact with the Vault, the exchange could open each user a Vault and link the cdpId to the userId.

Let's define the ilk before we call the open function.

```bash
export ilk=$(seth --to-bytes32 $(seth --from-ascii "BAT-A"))
```

Now let's call the open function.

```bash
seth send $CDP_MANAGER 'open(bytes32, address)' $ilk $ETH_FROM
```

To get the cdpId, execute:

```bash
export cdpId=$(seth --to-dec $(seth call $CDP_MANAGER 'last(address)' $ETH_FROM))
```

Besides the `cdpId`, we need to get the `urn` address as well. That's where ink(collateral balance) and art(outstanding stablecoin debt) is registered.

```bash
export urn=$(seth call $CDP_MANAGER 'urns(uint)(address)' $cdpId)
```

---

After acquiring the `cdpId` and `urn` address, we can move to the next step. Locking our tokens into the system. This process has two steps:

- Approving MCD_JOIN_BAT_A adapter to withdraw BAT from our wallet
- Send BAT to the urn address.

Let's define the value of collateral that we will lock, `dink`, and the value of Dai that we'll draw, `dart`.

```bash
export dink=$(seth --to-uint256 $(seth --to-wei 300 eth))
export dart=$(seth --to-uint256 $(seth --to-wei 25 eth))
```

Approving `MCD_JOIN_BAT_A` adapter to withdraw `dink` BAT.

```bash
seth send $BAT 'approve(address,uint)' $MCD_JOIN_BAT_A $dink
```

Sending `dink` amount of BAT to the urn.

```bash
seth send $MCD_JOIN_BAT_A 'join(address,uint)' $urn $dink
```

Now we can lock our BAT into the system and draw Dai against it. We can do it all in one function.

```bash
seth send $CDP_MANAGER 'frob(uint,int,int)' $cdpId $dink $dart
```

Let's check the status of our `urn` by calling VAT.

```bash
seth call $MCD_VAT 'urns(bytes32,address)(uint256,uint256)' $ilk $urn
```

Output:

```bash
300000000000000000000
25000000000000000000
```

If converted to decimals we get this:

```bash
300.000000000000000000 <- Dink
25.000000000000000000 <- Dart
```

This tells us that our Vault has 300 BAT as collateral and 25 DAI as outstanding debt.

---

### Draw Dai

What has been covered so far in this guide was the creation of Dai debt in the system. In short, you create a balance of your debt in the system. After, you need to add this balance to your wallet. Now, to actually withdraw it to your own address, we will need to do some functions calls:

```bash
CDP_MANAGER.move(uint,address,uint);
MCD_VAT.hope(address);
MCD_JOIN_DAI.exit(address,uint)
```

`CDP_MANAGER.move()` function moves the Dai from the `urn` to your `ETH_FROM`, your personal address. However, you still won't see the balance on your wallet. In order to see the balance, you'll need to approve the `MCD_JOIN_DAI` adapter in `MCD_VAT` from the system with the `MCD_VAT.hope()` function. After, you call the `MCD_JOIN_DAI.exit()` to finally move the DAI to your wallet. This looks a bit of a complicated process, but this just shows how the system operates.

Moving DAI from `urn` to `ETH_FROM`(your address).
You need to define rad, a high precision number as a variable that will be passed in the `move()` function. In VAT the debt balance is registered with a higher precision number than on your wallet. So to make sure to move all funds, we need to define a `rad` variable that has 45 decimal places.

```bash
export rad=$(seth --to-uint256 $(echo "25"*10^45 | bc))
seth send $CDP_MANAGER 'move(uint,address,uint)' $cdpId $ETH_FROM $rad
```

Approving `MCD_JOIN_DAI` to exit Dai in `MCD_VAT`.

```bash
seth send $MCD_VAT 'hope(address)' $MCD_JOIN_DAI
```

Exiting Dai to own wallet address.

```bash
seth send $MCD_JOIN_DAI 'exit(address,uint)' $ETH_FROM $dart
```

Finally, we have got our new Dai in our wallet. To check the balance, execute the below command.

```bash
seth --from-wei $(seth --to-dec $(seth call $MCD_DAI 'balanceOf(address)' $ETH_FROM))
```

---

### Pay back Dai

Paying back Dai involves calling a set of functions as well. They are:

```bash
MCD_DAI.approve(address,uint);
MCD_JOIN_DAI.join(address,uint);
CDP_MANAGER.frob(uint,int,int)
```

The first one is to approve `MCD_JOIN_DAI` to take Dai from your wallet. Second, you send the Dai to your `urn`. Third, you pay back Dai in the VAT.

When borrowing from Maker Protocol, there's usually a rate that the Vault owner has to pay for borrowing Dai. When paying all debt back, the debt should consider the Dai + the accrued debt for the Dai that has been borrowed. Below, you calculate the debt and rate from the system:

```bash
export art=$(seth --from-wei $(seth call $MCD_VAT 'urns(bytes32,address)(uint256,uint256)' $ilk $urn | sed -n 2p))

export rate=$(seth --to-fix 27 $(seth call $MCD_VAT 'ilks(bytes32)(uint256,uint256,uint256,uint256,uint256)' $ilk | sed -n 2p))

export debt=$(bc<<<"$art*$rate")

export debtWadRound=$(seth --to-uint256 $(bc<<<"$art*$rate*10^18/1+1"))
```

Approving `MCD_JOIN_DAI` to take the Dai debt (debtWadRound) from your wallet:

```bash
seth send $MCD_DAI 'approve(address,uint)' $MCD_JOIN_DAI $debtWadRound
```

Sending Dai to your urn. By setting the address parameter to urn in join(address, uint) you skip the step of needing to use the move function in the CDP_MANAGER.

```bash
seth send $MCD_JOIN_DAI 'join(address,uint)' $urn $debtWadRound
```

Check if it all worked:

```bash
seth --to-fix 45 $(seth call $MCD_VAT 'dai(address)(uint256)' $urn)
```

Paying back Dai involves calling the `CDP_MANAGER.frob()` function with negative dink and dart values. In other words, we're just changing the balance to 0 in VAT. This of course involves sending the Dai to the system, which gets burned, and unlocking the collateral in your urn.

```bash
export nDink=$(seth --to-int256 $(seth --to-wei -300 eth))
export nDart=$(seth --to-int256 $(seth --to-wei -25 eth))
```

Calling `CDP_MANAGER.frob()`

```bash
seth send $CDP_MANAGER 'frob(uint, int, int)' $cdpId $nDink $nDart
```

---

Alternative to pay back debt is to create the raw transaction data and pass it to the CDP_MANAGER contract. First we prepare all necessary data to transform it into raw data.

```bash
sig="frob(uint256,int256,int256)"

sigBytes=$(seth sig "$sig")

cdpId=$(seth --to-uint256 $cdpId)

cdpIdRaw=${cdpId:2}

nDinkRaw=${nDink:2}

nDartRaw=${nDart:2}

rawData=${sigBytes}${cdpIdRaw}${nDinkRaw}${nDartRaw}
```

Execute raw data:

```bash
seth send $CDP_MANAGER $rawData
```

### Unlock collateral from system

Now we need to take the collateral from the urn and have it sent back to your address.

```bash
seth send $CDP_MANAGER 'flux(uint,address,uint)' $cdpId $ETH_FROM $dink
```

Let's exit the collateral from the BAT adapter.

```bash
seth send $MCD_JOIN_BAT_A 'exit(address,uint)' $ETH_FROM $dink
```

To see if you got your collateral back in your wallet, just check your BAT balance:

```bash
seth --from-wei $(seth --to-dec $(seth call $BAT 'balanceOf(address)' $ETH_FROM))
```

Congratultaions! You have issued and paid back DAI through the CDP Manager.


This guide describes how users can interact with the Maker protocol through proxy contracts to redeem Dai and any excess collateral if the Maker system has entered into emergency shutdown

Dai and Collateral Redemption during Emergency Shutdown


# Dai and Collateral Redemption during Emergency Shutdown

**Level**: Intermediate

**Estimated Time:** 60minutes

### Description

This guide describes how users can interact with the Maker protocol through proxy contracts to redeem Dai and any excess collateral if the Maker system has entered into emergency shutdown. We will define the setup process, including proxy contract setup, followed by seth calls to; redeem collateral as a Dai Holder, and free excess collateral as a Vault Owner.

### Learning Objectives

To redeem Dai and/or excess collateral in the event of Emergency Shutdown

### Table of Contents

**Setup Process**

1. Installation
2. Contract Address Setup

**Dai Holders to Redeem Collateral**

1. Check user Dai holdings
2. Approve a Proxy
3. Create Calldata
4. Execute Calldata using the MYPROXY Contract
5. Call cashETH or cashGEM functions
6. Using cashETH
7. Define calldata for our function
8. Execute cashETHcalldata
9. Alternative from step 6, Using cashGEM
10. Define calldata for our function
11. Call execute in MYPROXY

**Vault Owners to Redeem Excess Collateral**

1. Vault Holder State
2. Redeeming ETH using the freeETH function

   2.1. Set Call Data

   2.2 Execute this calldata

3. Redeeming ETH using the freeGEM function

3.1 Set Calldata

3.2 Execute this calldata

**Conclusion**

### Setup process

#### **1. Installation**

In order to interface with the Ethereum blockchain, the user needs to install seth, a command line tool as part of the [Dapp.Tools](https://dapp.tools/) toolset. We also provide further [installation information here](https://github.com/makerdao/developerguides/blob/master/devtools/seth/seth-guide-01/seth-guide-01.md). Once the user has installed and configured **`[seth](<https://dapp.tools/>)`** correctly to use the main Ethereum network and the address which holds their MKR, they can query contract balances, approvals and transfers.

#### **2. Contract Address Setup**

The user will require the following contract addresses, shown below as mainnet addresses. Rest of mainnet or testnet addresses are accessible at [changelog.makerdao.com](https://changelog.makerdao.com/) which can be verified on [Etherscan](https://etherscan.io/token/0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2). Similarly, additional information on the commands described below can be found in the [End contract](https://github.com/makerdao/dss/blob/master/src/end.sol) and the [Proxy_Actions_End contract](https://github.com/makerdao/dss-proxy-actions/blob/master/src/DssProxyActions.sol#L793). These should be setup in the following manner and pasted into the terminal line by line:

```bash
export DAI=0x6B175474E89094C44Da98b954EedeAC495271d0F
export PROXY_ACTIONS_END=0x069B2fb501b6F16D1F5fE245B16F6993808f1008
export MCD_END=0xaB14d3CE3F733CACB76eC2AbE7d2fcb00c99F3d5
export CDP_MANAGER=0x5ef30b9986345249bc32d8928B7ee64DE9435E39
export PROXY_REGISTRY=0x4678f0a6958e4D2Bc4F1BAF7Bc52E8F3564f3fE4
export MCD_JOIN_ETH=0x2F0b23f53734252Bda2277357e97e1517d6B042A
export MCD_JOIN_BAT=0x3D0B1912B66114d4096F48A8CEe3A56C231772cA
export MCD_JOIN_DAI=0x9759A6Ac90977b93B58547b4A71c78317f391A28

export MYPROXY=$(seth call $PROXY_REGISTRY 'proxies(address)(address)' $ETH_FROM)
# This creates a unique proxy address by calling the proxy registry using the users Ethereum address.

export ilk=$(seth --to-bytes32 $(seth --from-ascii ETH-A))
export ilkBAT=$(seth --to-bytes32 $(seth --from-ascii BAT-A))
# Here we have defined two ilk (collateral types) ETH and BAT.
# The number of ilk types needed will depend on the types of collateral vaults that the user had open.

export ETH_GAS=4000000
export ETH_GAS_PRICE=2500000000
# Typically gas costs are slightly increased when dealing with proxy contracts to prevent failed transactions.

export cdpId=$(seth --to-dec $(seth call $CDP_MANAGER 'last(address)' $MYPROXY))
# This is a call to the CDP Manager responsible for making the users CDP ID.
# Note, if user created multiple vaults they will have multiple CDP IDs, all of which must be referenced to retrieve collateral.
```

### Dai holders to Redeem Collateral

There are two functions to be called in order to retrieve the end collateral. The first step is `pack` and the second step is `cashETH` or `cashGem` depending on the leftover amount of each collateral type in the system.

Depositing Dai tokens into the system can be done using the `PROXY_ACTIONS_END` contract library and the `pack` function. This function efficiently bundles together three parameters, including three parameters; the `Dai(join)` adapter, the `end` contract and the amount of Dai tokens you wish to redeem for allowed collateral in one go.

```solidity
function pack(
        address daiJoin,
        address end,
        uint wad
    ) public {
        daiJoin_join(daiJoin, address(this), wad);
        VatLike vat = DaiJoinLike(daiJoin).vat();
        // Approves the end to take out DAI from the proxy's balance in the vat
        if (vat.can(address(this), address(end)) == 0) {
            vat.hope(end);
        }
        EndLike(end).pack(wad);
    }
```

#### 1. Check user Dai holdings

The user can check their Dai Token balance and subsequently save it in the `wad` variable so that it can be later used in the proxy function.

```bash
export balance=$(seth --from-wei $(seth --to-dec $(seth call $DAI 'balanceOf(address)' $ETH_FROM)))
export wad=$(seth --to-uint256 $(seth --to-wei 13400 eth))
# in the above, 13400 is an example Dai balance
```

#### 2. Approve a Proxy

The user needs to approve `MYPROXY` in order to withdraw Dai from their wallet by using the following function.

```bash
seth send $DAI 'approve(address,uint)' $MYPROXY $(seth --to-uint256 $(mcd --to-hex -1))
```

#### 3. Create Calldata

Next it is necessary to bundle together the function definitions and parameters that the user needs to execute. This is done by preparing a function call to `MYPROXY`, defined as `calldata.`

```bash
export calldata=$(seth calldata 'pack(address,address,uint)' $MCD_JOIN_DAI $MCD_END $wad)
.
.
.
# 0x33ef33d6000000000000000000000000fc0b3b61407cdf5f583b5b1e08514e68ecee4a73000000000000000000000000d9026db5ca822d64a6ba18623d0ff2bb07ad162c0000000000000000000000000000000000000000000002d66a5b4bc1da600000
```

#### 4. Execute calldata using the `MYPROXY` contract

The user is able to call the `execute` function and utilize the `PROXY_ACTIONS_END.pack()` function within the environment of `MYPROXY`. This approves the proxy to take Dai tokens from the user's wallet into the proxy address and deposits it into the `end` contract, where a proportionate amount of collateral can later be claimed. Once the DAI is packed, it cannot be unpacked.

```bash
seth send $MYPROXY 'execute(address,bytes memory)' $PROXY_ACTIONS_END $calldata
# [example](<http://ethtx.info/kovan/0x8f4021e46b1a6889ee7045ba3f3fae69dee7ef130dbb447d4cc724771e04bcd6>) transaction showing actions involved in 'packing' the user's Dai.
```

#### 5. Call `cashETH` or `cashGEM` functions

Users will be able to withdraw collateral depending on the collateral that is in the VAT at the time of shutdown. For example 1 Dai will be able to claim a portion of ETH and BAT and any other accepted collateral which when combined will be approximately worth 1 USD. This process is completed by calling `cashETH` or `cashGEM`.

#### 6. **Using `cashETH`**

The following function `cashETH` is referenced as part of the `calldata` function and should be referenced [here](https:).

```solidity
function cashETH(
        address ethJoin,
        address end,
        bytes32 ilk,
        uint wad
    ) public {
        EndLike(end).cash(ilk, wad);
        uint wadC = mul(wad, EndLike(end).fix(ilk)) / RAY;
        // Exits WETH amount to proxy address as a token
        GemJoinLike(ethJoin).exit(address(this), wadC);
        // Converts WETH to ETH
        GemJoinLike(ethJoin).gem().withdraw(wadC);
        // Sends ETH back to the user's wallet
        msg.sender.transfer(wadC);
    }
```

#### 7. Define calldata for our function

Next, we again define the calldata for our function by bundling together the `cashETH` parameters shown above.

```bash
export cashETHcalldata=$(seth calldata 'cashETH(address,address,bytes32,uint)' $MCD_JOIN_ETH $MCD_END $ilk $wad)
```

#### 8. Execute `cashETHcalldata`

Finally, executing the `cashETHcalldata` in the `execute` function of the user's `MYPROXY` contract will redeem ETH for DAI, and place this ETH into the user's ETH wallet.

```bash
seth send $MYPROXY 'execute(address,bytes memory)' $PROXY_ACTIONS_END $cashETHcalldata
# [example](<http://ethtx.info/kovan/0x323ab9cd9817695089aea31eab369fa9f3c9b1a64743ed4c5c1b3ec4d7218cf8>) successful transaction
```

#### 9. Alternative from step (6), Using **`cashGEM`**

It is also possible to use the `cashGEM` function in order to redeem different collateral types. In the below example we are referencing gemJoin as it relates to BAT.

```solidity
function cashGem(
        address gemJoin,
        address end,
        bytes32 ilk,
        uint wad
    ) public {
        EndLike(end).cash(ilk, wad);
        // Exits token amount to the user's wallet as a token
        GemJoinLike(gemJoin).exit(msg.sender, mul(wad, EndLike(end).fix(ilk)) / RAY);
    }
```

#### 10. Define calldata for our function

Similarly, as done in step 7, the user needs to define the calldata to interact with `cashGEM`

```bash
export cashBATcalldata=$(seth calldata 'cashETH(address,address,bytes32,uint)' $MCD_JOIN_BAT $MCD_END $ilkBAT $wad)
```

#### 11. Call execute in `MYPROXY`

Finally, executing the `cashBATcalldata` in the `execute` function of the user's `MYPROXY` contract will redeem BAT for DAI, and place this BAT into the user's ETH wallet.

```bash
seth send $MYPROXY 'execute(address,bytes memory)' $PROXY_ACTIONS_END $cashBATcalldata
```

### Vault Owners to Redeem Excess Collateral

Likewise, a vault owner can use the `freeETH` or `freeGEM` proxy actions function to retrieve any excess collateral they may have locked in the system.

### 1. Vault Holder State

There are some constraints for vault holders to be aware of. For example, if a user’s Vault is under-collateralised then they will not have any excess collateral to claim. Likewise, if the user’s Vault is currently in a flip auction at the time of emergency shutdown, it will be necessary for the Vault holder to cancel the auction by calling **`skip(ilk, id)`** before calling **`free__()`**.

Similarly, these functions have been completed using Maker proxy contract calls. There may be other scenarios in which 3rd party front ends such as InstaDApp have their own proxies, which will require users to exit from their proxy in order to use the below.

### 2. Redeeming ETH using the `freeETH` function

```solidity
function freeETH(
        address manager,
        address ethJoin,
        address end,
        uint cdp
    ) public {
        uint wad = _free(manager, end, cdp);
        // Exits WETH amount to proxy address as a token
        GemJoinLike(ethJoin).exit(address(this), wad);
        // Converts WETH to ETH
        GemJoinLike(ethJoin).gem().withdraw(wad);
        // Sends ETH back to the user's wallet
        msg.sender.transfer(wad);
    }
```

#### 2.1. Set calldata

Depending on how many vaults the user has, it will be necessary to repeat this process for each vault ID.

```bash
export freeETHcalldata=$(seth calldata 'freeETH(address,address,address,uint)' $CDP_MANAGER $MCD_JOIN_ETH $MCD_END $cdpId )
```

#### 2.2. Execute this calldata

Executing the `MYPROXY` contract will redeem ETH and place it into the users address.

```bash
seth send $MYPROXY 'execute(address,bytes memory)' $PROXY_ACTIONS_END $freeETHcalldata
```

### 3. Redeeming ETH using the `freeGEM` function

```solidity
function freeGem(
        address manager,
        address gemJoin,
        address end,
        uint cdp
    ) public {
        uint wad = _free(manager, end, cdp);
        // Exits token amount to the user's wallet as a token
        GemJoinLike(gemJoin).exit(msg.sender, wad);
    }
```

#### 3.1. Set calldata

Depending on how many vaults the user has, it will be necessary to repeat this process for each vault ID.

```bash
export freeBATcalldata=$(seth calldata 'freeETH(address,address,address,uint)' $CDP_MANAGER $MCD_JOIN_BAT $MCD_END $cdpId )
```

#### 3.2. Execute this calldata

Executing the `MYPROXY` contract will redeem BAT or other collateral types and place them into the users address.

```bash
seth send $MYPROXY 'execute(address,bytes memory)' $PROXY_ACTIONS_END $freeBATcalldata
```

### Conclusion

The above outlines how to redeem Dai and excess Vault collateral using the command line.

In summary, we showed how to check your Dai holdings, how to approve a proxy to withdraw Dai from your wallet and then to use `cashETH/GEM` functions to withdraw collateral into the user’s ETH wallet using the `MYPROXY` contract . For Vault owners, we showed how to redeem collateral by using the `MYPROXY` contract and the `freeGEM` function.

In the event of emergency shutdown we envision that it will still be possible to sell Dai on the open market as well as by making use of economically incentivized redemption keepers to meet market needs for both Dai owners and Vaults holders.


Integrate Dai into your own smart contracts

Dai in Smart Contracts


# Dai in Smart Contracts

**Level**: Beginner  
**Estimated Time**: 30 minuntes

- [Dai in Smart Contracts](#dai-in-smart-contracts)
  - [Overview](#overview)
  - [Learning Objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Sections](#sections)
    - [Setup](#setup)
    - [Write your code](#write-your-code)
      - [Dai Token Interface](#dai-token-interface)
      - [Contract Ownership](#contract-ownership)
      - [Kill Switch](#kill-switch)
      - [Dai Faucet](#dai-faucet)
    - [Deploy Smart Contract](#deploy-smart-contract)
      - [Make sure you have chosen the right compiler](#make-sure-you-have-chosen-the-right-compiler)
      - [Check if there are no errors](#check-if-there-are-no-errors)
      - [Deploy](#deploy)
    - [Use Faucet](#use-faucet)
      - [Verify Contract](#verify-contract)
  - [Summary](#summary)
  - [Additional resources](#additional-resources)
  - [Help](#help)

## Overview

This guide will show you how to integrate Dai into your own smart contracts. Dai is a decentralized stablecoin built on Ethereum. The Dai token is based on the [DS-Token](https://dapp.tools/dappsys/ds-token.html) implementation which follows the ERC-20 token standard with minor additions.

## Learning Objectives

- Learn how to integrate the Dai token into your smart contracts.
- Write a simple Dai Faucet contract.

## Pre-requisites

- Basic knowledge of the Solidity programming language
- Knowledge of the [ERC20 token standard](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md)

## Sections

- [Setup](#setup)
- [Write your code](#write-your-code)
- [Deploy Smart Contract](#deploy-smart-contract)
- [Use Faucet](#use-faucet)

### Setup

To start things off, we will deploy our contract on the Ethereum Kovan network as we have deployed our Dai token on the same network.
In addition, you’ll need:

- [Metamask](https://metamask.io/)
- [Kovan ETH](https://github.com/kovan-testnet/faucet)
- Kovan Dai (lock Kovan-ETH on [oasis.app](http://oasis.app/borrow))

For simplicity, we will use <https://remix.ethereum.org> in browser IDE. Watch this [intro](https://www.youtube.com/watch?v=xxJfQJ5bMfw) in case you are not comfortable with this development environment.

One of the simplest contract examples we can use that can showcase the integration of the Dai token is a contract faucet. As you already used a faucet to get some Kovan ETH, we will work on creating a faucet that will give you some Kovan Dai tokens. It is a great tool to build for your test network when you want to allow many users to test your application before you deploy it on mainnet.

### Write your code

We will build a faucet contract that you will be able to control and terminate in case you desire to do so.
In your [Remix IDE](https://remix.ethereum.org/) browser tab, create a new file named **DaiFaucet.sol**.  
It should look like this:

![Dai Faucet](/images/guides/dai-in-smart-contracts/DaiFaucet.png)

Now we will add our necessary blocks of code that will form our DaiFaucet contract.

#### Dai Token Interface

First, we add the solidity version that the code will be compiled into the EVM.

```solidity
pragma solidity ^0.5.9;
```

To enable our faucet contract to recognize and interact with the Dai token contract we need to write an interface that will map the Dai token functions that we’ll use. In this case, that means the **transfer()** and **balanceOf()** functions, since we will need our contract to transfer Dai to whomever requests it and also to check the balanceOf its Dai holdings to know if it can transfer in the first place. We will need to instantiate this interface later in the codebase.

```solidity
// Adding only the ERC-20 function we need
interface DaiToken {
    function transfer(address dst, uint wad) external returns (bool);
    function balanceOf(address guy) external view returns (uint);
}
```

#### Contract Ownership

Now we will set up supporting contracts that will manage ownership and control of our faucet contract. The **owned** contract sets up the contract creator as the one in control, it sets the **DaiToken daitoken** variable and the **owner** variable. It creates the **onlyOnwer** modifier function that adds restrictions to who can call other functions in our faucet contract.

When we deploy our contract to the Kovan network, the constructor function will set the **owner** variable to the address of the calling Ethereum account, and set the **daitoken** variable to the address of the Dai token contract on the Kovan network, which is [0x4f96fe3b7a6cf9725f59d353f723c1bdb64ca6aa](https://kovan.etherscan.io/token/0x4f96fe3b7a6cf9725f59d353f723c1bdb64ca6aa).
Now the **DaiToken** interface will link to the Dai token address on the kovan network. So when we call the **transfer** or **balanceOf** functions, they will call the functions of the Dai token contract.

```solidity
contract owned {
    DaiToken daitoken;
    address owner;

    constructor() public{
        owner = msg.sender;
        daitoken = DaiToken(0x4F96Fe3b7A6Cf9725f59d353F723c1bDb64CA6Aa);
    }

    modifier onlyOwner {
        require(msg.sender == owner,
        "Only the contract owner can call this function");
        _;
    }
}

```

#### Kill Switch

Moving on, we will add another contract that will inherit the **owned** contract. We will call it **mortal**, as in, we will give our contract a kill switch that will terminate it and return any funds back to the owner. The **destroy()** function can only be called by the owner, hence the **onlyOwner** modifier.
Here you can see that we use the **daitoken** interface. We transfer any remaining Dai funds of the faucet contract to the owner.

```solidity
contract mortal is owned {
    // Only owner can shutdown this contract.
    function destroy() public onlyOwner {
        daitoken.transfer(owner, daitoken.balanceOf(address(this)));
        selfdestruct(msg.sender);
    }
}
```

#### Dai Faucet

Finally, we are writing the faucet contract. We can see that **DaiFaucet** inherits the **mortal** contract, which in turn inherits the **owned** contract. This way, we have modularised our contracts for their specific functions and added our total control over it.
Inside the contract we have two events that will watch and log every time there is a **Withdrawal** and a **Deposit** to/from this contract.

We have added the **withdraw** function that will take care to send Dai to anyone who calls this function. As you can see, we have added 2 conditions for the withdrawal:

- Require that the withdraw_amount is less or equal to 0.1 Dai
- Require that we have more Dai in the faucet than the withdraw_amount.

Only after these conditions are met we can transfer 0.1 Dai to the function caller. And of course, we log this transaction with the Withdrawal event. The way we send Dai to the function caller is by using the above defined DaiToken interface to allow us to make the transfer.

The unnamed function is here to receive any incoming payments our contracts gets and log the Deposit event.

```solidity
contract DaiFaucet is mortal {

    event Withdrawal(address indexed to, uint amount);
    event Deposit(address indexed from, uint amount);

    // Give out Dai to anyone who asks
    function withdraw(uint withdraw_amount) public {
        // Limit withdrawal amount
        require(withdraw_amount <= 0.1 ether);
        require(daitoken.balanceOf(address(this)) >= withdraw_amount,
            "Insufficient balance in faucet for withdrawal request");
        // Send the amount to the address that requested it
        daitoken.transfer(msg.sender, withdraw_amount);
        emit Withdrawal(msg.sender, withdraw_amount);
    }

    // Accept any incoming amount
    function () external payable {
        emit Deposit(msg.sender, msg.value);
    }
}

```

This is how it should look like when all the code blocks are put together:

![Full Contract](/images/guides/dai-in-smart-contracts/FullContract.png)

### Deploy Smart Contract

To deploy this faucet on the Kovan network you need to change the network to Kovan on Metamask, choose the same compiler version as in the contract, compile the contract to see if there’s any errors and then deploy the DaiFaucet contract.

#### Make sure you have chosen the right compiler

![Compile Version](/images/guides/dai-in-smart-contracts/CompileVersion.png)

#### Check if there are no errors

![Compiled](/images/guides/dai-in-smart-contracts/compiled.png)

#### Deploy

Choose **DaiFaucet** from list of contracts to deploy. Make sure you are connected to Kovan and have a wallet with enough ETH. Deploy contract. You will be asked to confirm the transaction with Metamask.

![Deploy](/images/guides/dai-in-smart-contracts/Deploy.png)

You can check the transaction on Etherscan. If everything went well, you will see your new contract address.

### Use Faucet

Now that we have successfully deployed our smart contract on the Kovan network, we can interact with it. The simplest way to interact with the contract is through Etherscan. As you are the deployer of this contract, you have the source code. This means that you can publish the source code to Etherscan and verify the contract. This will allow you to interact with the contract on Etherscan with just your Metamask account. Easy, right?

#### Verify Contract

To verify your contract and publish your source code, navigate to your contract address on Etherscan and click on the **Verify and Publish** link.

![Verify](/images/guides/dai-in-smart-contracts/verify.png)

Select compiler type to be **Single File**, since all your code is in one file.
Make sure to select the right compiler version that your contract has been compiled against and then press continue.

![Verify and Publish](/images/guides/dai-in-smart-contracts/verifyAndPublish.png)

Paste the Solidity code below, and then press **Verify and Publish**.

![Paste Code](/images/guides/dai-in-smart-contracts/pasteCode.png)

If everything went according to plan, you should see something like this:

![Successfull](/images/guides/dai-in-smart-contracts/Successfull.png)

Congratulations! Your contract is verified, now you can interact with it from Etherscan with Metamask.

As you can see, you have two functions that you can interact with, **withdraw** and **destroy**. Before anyone can withdraw any Dai from the contract, make sure to send some to the contract address. After that, anyone would be able to withdraw maximum 0.1 Dai, as per the rule you put in the code. You will be requested to connect Metamask in order to use these functions.

When you think you have had enough with this contract, you can easily call the **destroy** function.

![Interact](/images/guides/dai-in-smart-contracts/Interact.png)

This concludes how you can integrate the Dai token into a Solidity smart contract.

## Summary

In this guide, we showcased how you can integrate the Dai token in a smart contract. We wrote a faucet smart contract that uses the Dai token contract that can send a small amount of Dai to anyone who asks. In addition, we walked through the process of writing, deploying and using this faucet contract.

## Additional resources

1. Knowledge of the [Dai Token](https://github.com/makerdao/developerguides/blob/master/dai/dai-token/dai-token.md)
2. [Integrating Dai Savings Rate](https://github.com/makerdao/developerguides/blob/master/dai/dsr-integration-guide/dsr-integration-guide-01.md)

## Help

- Contact integrations team - integrate@makerdao.com
- Rocket chat - [#dev](https://chat.makerdao.com/channel/dev) channel


Tracking Dai Supply


# Tracking Dai Supply

**Level:** Intermediate  
**Estimated Time:** 20 minutes

- [Tracking Dai Supply](#tracking-dai-supply)
  - [Overview](#overview)
  - [Learning objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Content](#content)
    - [The different states of Dai](#the-different-states-of-dai)
      - [Maker Protocol Dai, or internal-Dai](#maker-protocol-dai-or-internal-dai)
      - [ERC-20 Dai](#erc-20-dai)
      - [Dai in DSR](#dai-in-dsr)
      - [Other Dai](#other-dai)
    - [How to obtain supply numbers](#how-to-obtain-supply-numbers)
      - [Total Maker Protocol Dai, or internal-Dai](#total-maker-protocol-dai-or-internal-dai)
      - [ERC20 Dai](#erc20-dai)
      - [Dai in DSR](#dai-in-dsr-1)
  - [Next steps](#next-steps)
  - [Resources](#resources)

## Overview

The Maker Protocol was designed modularly, which allows Dai to
take multiple forms, and such Dai is not exclusively an ERC20 token. That poses a challenge for token analysis and crypto
trackers because looking at ERC-20 supply and transactions does not provide a
complete picture.

## Learning objectives

Understand the difference between Protocol Dai, ERC20 Dai, and Dai locked in DSR, and know the methods to
determine the total supply.

## Pre-requisites

Some knowledge of Ethereum and ERC20 and of Nodejs to run the code samples.

## Content

### The different states of Dai

Contrary to most tokens available on Ethereum, Dai can take different forms. To correctly
account for the Dai supply, it is important to know the difference so we can
track the applicable supply number for our needs.

![dai supply Venn](/images/guides/dai_venn.png)

#### Maker Protocol Dai, or internal-Dai

At its most basic form, Dai is a balance assigned to an address in [the `vat` contract](https://github.com/makerdao/dss/blob/master/src/vat.sol#L53). The `vat` contract allows Dai to move from one address to the other, akin to an ERC-20 token, using the `move` method. It even has a basic permission mechanism, equivalent to the ERC-20’s `approve`, in the form of the functions `hope` and `nope`.

Internal-Dai could be used to transact between arbitrary addresses, but it lacks the functionality one would expect from a token standard, hence the need for a higher-level contract to wrap the internal-Dai into a more useful form.

#### ERC-20 Dai

Almost every Ethereum token follows the ERC-20 standard, and as such it was natural for Dai to be available on this form.

When a user wants to put its internal-Dai into an ERC-20, the following steps are executed:

- The internal-Dai balance is moved to the Dai Adaptor Contract
- The Dai Adaptor Contract instructs the Dai Token Contract to mint ERC-20 to the benefit of the user

After this change, the user’s internal-Dai balance becomes 0, the Dai Adaptor Contract internal-Dai balance increases, and the user’s ERC20 Dai balance increases.

As such, every ERC-20 Dai is backed by exactly one internal-Dai. We could represent ERC-20 Dai as a wrapped internal-Dai.

#### Dai in DSR

Dai locked in DSR differs from the other two types of Dai in the sense that it is not directly transferable. Dai locked in DSR is a Dai balance held inside [the `pot` contract](/documentation/pot-proxy-detailed-documentation).

When a user activates DSR on its Dai:

- The users’ ERC-20 Dai is burned and he receives an internal-Dai balance
- The internal-Dai is moved to the `pot` contract
- `pot` now has an internal-Dai balance
- User holding is recorded by the `pot` contract. (the `pie`)

#### Other Dai

Other projects in the ecosystem have created other variations of Dai (zkDai, Chai, cDAI, aDai, etc.), which usually derive from either the Dai in DSR or the ERC 20 Dai. Since the supply of these tokens are already included in the total "Maker Protocol Dai" it is not necessary to add their supply to the total.

Also, Dai can be purely internal: anyone can hold its Dai in Internal form, and burn and mint ERC20 Dai when necessary. The Maker Protocol itself keeps internal-Dai balances for its System Surplus and System Debt.

### How to obtain supply numbers

#### Total Maker Protocol Dai, or internal-Dai

As all Dai originates from vault debt, the total supply of Dai can be tracked by looking at the total system debt on the vat contract. The following code snippet will provide the information. (Requires node.js and [web3](https://web3js.readthedocs.io/) module.)

```javascript
const Web3 = require('web3');
const web3 = new Web3('https://mainnet.infura.io/v3/<INFURA_ID>');

const vatAddr = '0x35D1b3F3D7966A1DFe207aa4514C12a259A0492B';
const abi = [
  {
    inputs: [],
    name: 'debt',
    outputs: [{ internalType: 'uint256', name: '', type: 'uint256' }],
    type: 'function',
  },
];

const vat = new web3.eth.Contract(abi, vatAddr);
vat.methods
  .debt()
  .call()
  .then((supply) => console.log(supply / Math.pow(10, 45)));
```

Alternatively, the following API will provide up-to-date information:
[https://api.oasis.app/v1/supply/dai](https://api.oasis.app/v1/supply/dai)

Example:

```JSON
{"data":"111631238.864389825196224371","time":"2020-02-06T15:08:52.088Z","message":"success"}
```

#### ERC20 Dai

The supply of ERC20 Dai is obtained by `totalSupply()`, like all ERC20 tokens.

Note: The ERC20 Dai supply can be less than half of the actual Dai supply. For most applications, it is more useful to track the total Maker Protocol Dai (above).

```javascript
const Web3 = require('web3');
const web3 = new Web3('https://mainnet.infura.io/v3/<INFURA_ID>');

const erc20daiAddr = '0x6B175474E89094C44Da98b954EedeAC495271d0F';
const abi = [
  {
    inputs: [],
    name: 'totalSupply',
    outputs: [{ name: '', type: 'uint256' }],
    type: 'function',
  },
];

const erc20dai = new web3.eth.Contract(abi, erc20daiAddr);
erc20dai.methods
  .totalSupply()
  .call()
  .then((supply) => console.log(supply / Math.pow(10, 18)));
```

#### Dai in DSR

The Dai in DSR can be calculated by looking at the normalized Dai put in the pot DSR contract (`Pie`), multiplied by the accumulated rate (`rate`). This number includes the Dai deposited in DSR and the earned savings rate. [Dai.js](https://github.com/makerdao/dai.js/wiki/Multi-Collateral-Dai-Examples) provides the method `getTotalDai()` to directly obtain the amount of Dai in DSR:

```javascript
const Maker = require('@makerdao/dai');
const McdPlugin = require('@makerdao/dai-plugin-mcd').default;

(async function () {
  const maker = await Maker.create('http', {
    url: 'https://mainnet.infura.io/v3/<INFURA_ID>',
    plugins: [[McdPlugin, {}]],
  });
  console.log((await maker.service('mcd:savings').getTotalDai()).toNumber());
})();
```

You can learn more about how rates are calculated in the Maker Protocol [in this guide](https://github.com/makerdao/developerguides/blob/master/mcd/intro-rate-mechanism/intro-rate-mechanism.md).

## Next steps

- [DSR Integration Guide](https://github.com/makerdao/developerguides/blob/master/dai/dsr-integration-guide/dsr-integration-guide-01.md)
- [Intro to the Rate mechanism](https://github.com/makerdao/developerguides/blob/master/mcd/intro-rate-mechanism/intro-rate-mechanism.md)
- [MCD Docs: Rates Module](documentation/introduction-to-rates-module)
- [MCD Docs: Dai Module](documentation/introduction-to-dai-module)
- [Maker Protocol 101](documentation/maker-protocol-101)

## Resources

- [Web3.js](http://web3js.readthedocs.io/)
- [Dai.js](https://github.com/makerdao/dai.js/wiki/Multi-Collateral-Dai-Examples)


Learm about Dai and integrate it into applications

Dai Token


# Dai Token

**Level**: Beginner

**Estimated Time**: 30 - 60 minutes

- [Dai Token](#dai-token)
  - [Overview](#overview)
  - [Learning Objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Guide](#guide)
    - [Token Info](#token-info)
      - [Addresses](#addresses)
      - [Details](#details)
      - [Token stats](#token-stats)
    - [Getting Dai](#getting-dai)
      - [Mainnet](#mainnet)
      - [Testnet](#testnet)
    - [Token Contract](#token-contract)
      - [Permit](#permit)
      - [Mint and Burn](#mint-and-burn)
      - [Aliases](#aliases)
      - [Authority](#authority)
    - [DaiJoin Adapter](#daijoin-adapter)
    - [**Emergency Shutdown**](#emergency-shutdown)
    - [Deploy on testnet](#deploy-on-testnet)
  - [Summary](#summary)
  - [Additional resources](#additional-resources)
  - [Help](#help)

## Overview

Dai is a decentralized, unbiased, collateral-backed cryptocurrency soft-pegged to the US Dollar. Resistant to hyperinflation due to its low volatility, Dai offers economic freedom and opportunity to anyone, anywhere.

The token contract conforms to the ERC20 token standard which allows wallets, exchanges, and other applications to easily integrate with minimal effort. This guide will be useful to developers integrating Dai in applications like wallets, exchanges, and smart contracts to get a better understanding of the token contract and its functionality.

## Learning Objectives

- You will learn basic information about the token.

- Understand the additional functions supported by the token contract.

- Deploy your own token to an Ethereum testnet.

- Integrate the Dai token effectively with your application.

## Pre-requisites

- Knowledge of the [ERC20](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md) token standard.

- Ability to send ethereum transactions from your preferred dev environment.

## Guide

### Token Info

#### Addresses

Dai is available on the:

- _Ethereum mainnet_ at [0x6B175474E89094C44Da98b954EedeAC495271d0F](https://etherscan.io/token/0x6B175474E89094C44Da98b954EedeAC495271d0F)
- _Kovan testnet_ at [0x4F96Fe3b7A6Cf9725f59d353F723c1bDb64CA6Aa](https://kovan.etherscan.io/token/0x4F96Fe3b7A6Cf9725f59d353F723c1bDb64CA6Aa)

Other deployments are listed on [changelog.makerdao.com](https://changelog.makerdao.com).

#### Details

The _symbol_ field is set to ‘DAI’ and the _name_ field is currently set to ‘Dai Stablecoin’.

Token precision field _decimals_ is set to 18 like most other ERC20 tokens.

In addition, the contract has the `version` field set to 1. This field is a constant, so once the contract is deployed, this field cannot be changed. This field is added for use in the `permit()` function in the contract. And this variable is part of the [EIP-712](<[https://eips.ethereum.org/EIPS/eip-712](https://eips.ethereum.org/EIPS/eip-712)>) signing standard. Read more on the `permit()` function below.

#### Token stats

Multi Collateral Dai has been live on the Ethereum mainnet since November 18, 2019 and its current total supply can be viewed on [DaiStats](https://daistats.com/).

The system internally uses 1 USD as the target price of Dai when new Dai is generated or burned through the Maker Vaults, but the market price of the token could vary based on a variety of conditions like exchange liquidity, trading pair etc.

Care should be taken before using the price of Dai directly reported by sources like [CoinMarketCap](https://coinmarketcap.com/currencies/dai/), because exchange bugs may produce unreasonable price data. In many scenarios, such as displaying the value of Dai in a wallet, it is perfectly fine to hard code the price of a token to 1 USD.

### Getting Dai

#### Mainnet

Dai can be purchased with Ether on many popular exchanges, which many are listed on [https://coinmarketcap.com/currencies/multi-collateral-dai/markets/](https://coinmarketcap.com/currencies/multi-collateral-dai/markets/). It is also available on many decentralized exchanges like [Oasis](https://oasis.app/trade/), [KyberSwap](https://kyberswap.com/), and [Uniswap](https://uniswap.exchange/).

You can also generate Dai by opening a Vault with [https://oasis.app/](https://oasis.app/).

#### Testnet

There are no Dai faucet on testnets, but you can generate your own Dai on the major Ethereum testnets: Goerli, Kovan, Rinkeby and Ropsten. After having obtained testnet-ETH, you can head over to [Oasis](<%5B%3Chttps://oasis.app/?network=kovan%3E%5D(%3Chttps://oasis.app/?network=kovan%3E)>) and open a Vault. Make sure to change the `?network=<networkName>` parameter to your preferred network

Alternatively, if you're more comfortable with cli-tools, then you can the [seth guide](<%5B%3Chttps://github.com/makerdao/developerguides/blob/master/mcd/mcd-seth/mcd-seth-01.md%3E%5D(%3Chttps://github.com/makerdao/developerguides/blob/master/mcd/mcd-seth/mcd-seth-01.md%3E)>).

Another option is to buy Kovan Dai with Kovan ETH on [Oasis Trade](https://oasis.app/trade) if there is sufficient liquidity available.

### Token Contract

The codebase at commit [6fa5581](https://github.com/makerdao/dss/blob/6fa55812a5fcfcfa325ad4d9a4d0ca4033c38cab/src/dai.sol) was used for deployments on mainnet.

The Dai token contract, follows the [ERC-20 standard](<%5B%3Chttps://eips.ethereum.org/EIPS/eip-20%3E%5D(%3Chttps://eips.ethereum.org/EIPS/eip-20%3E)>) with some additional features. The added features are

- The `permit()` function that uses the [EIP-712 signing standard](<%5B%3Chttps://eips.ethereum.org/EIPS/eip-712%3E%5D(%3Chttps://eips.ethereum.org/EIPS/eip-712%3E)>) as defined by [EIP-2612 (draft](https://github.com/ethereum/EIPs/blob/8a34d644aacf0f9f8f00815307fd7dd5da07655f/EIPS/eip-2612.md)).
- The `mint()` and `burn()` functions that the Maker Protocol is authorised to use.

#### Permit

The EIP-712 signing standard allows to sign structured typed data instead of just byte strings. This allows in the creation of the `permit()` function. The `permit()` function allows the user to send Dai without paying gas. This works as follows:

- User signs a `permit` message allowing a `destination` address to withdraw an amount of Dai from his wallet.
- This message is read by a relayer that takes the signed message and processes it by paying the transaction fee for the user. This relayer then takes a Dai cut from the user for processing the transaction.
- The user can send Dai by paying for the transaction fee with Dai, while a relayer in the backend is doing the processing.

Check [https://stablecoin.services/](https://stablecoin.services/) and [https://gasless.mosendo.com/](https://gasless.mosendo.com/) for live examples. The EIP for this functionnality is currently in [draft](https://github.com/ethereum/EIPs/blob/8a34d644aacf0f9f8f00815307fd7dd5da07655f/EIPS/eip-2612.md).

#### Mint and Burn

Tokens are created when a user adds collateral to their Vault and generates new Dai from it. Tokens are burned, when the same user pays back the same amount of Dai they’ve previously issued for the system to remove them from the supply to free their locked collateral back. Also `mint` and `burn` functions are used when user deposits and withdraws Dai from the Dai Savings Rate contract.

The [MCD_DAI_JOIN](https://etherscan.io/address/0x9759a6ac90977b93b58547b4a71c78317f391a28#code) adapter contract in the Maker Protocol is authorized to calls the mint and burn functions of Dai token which to increase or decrease the total supply.

- `mint` has the function signature: `mint(address guy, uint wad)`. It increases the total supply of the token as well as the `guy`’s token balance by the `wad` amount. All calls to `mint()` originate from the `exit()` function on the [DaiJoin](https://etherscan.io/address/0x9759a6ac90977b93b58547b4a71c78317f391a28#code) contract.
- `burn` has the function signature: `burn(address guy, uint wad)`. It decreases the total supply of the token as well as the `guy`’s token balance by the `wad` amount. Calls to `burn()` originate from `join()` function on the [DaiJoin](https://etherscan.io/address/0x9759a6ac90977b93b58547b4a71c78317f391a28#code) contract. Contrary to Mint, Burn is not restricted to DaiJoin, this means that any user if he intends to do so, can burn his Dai. This however is not recommended.

#### Aliases

The `transferFrom()` function has a few aliases available: `push`, `pull`, and `move`. These are available if function caller doesn't want to specify `msg.sender` parameter in the function call.

#### Authority

Some functions in the Dai contract can only be called by an authorized address. This address can be an externally owned account (EOA) or a contract address. In the Dai contract, the only authorized address is the [DaiJoin Adapter](<%5B%3Chttps://etherscan.io/address/0x9759A6Ac90977b93B58547b4A71c78317f391A28#code%3E%5D(%3Chttps://etherscan.io/address/0x9759A6Ac90977b93B58547b4A71c78317f391A28#code%3E)>) that is part of the Maker Protocol. As such, only the DaiJoin Adapter is able to call the `mint` function.

The Dai contract uses a simplified authority for its functions, where only addresses known as `wards` are authorized by the `rely` function, and deauthorized by `deny`. Because `rely` and `deny` can be called only by members of `wards`, and the only address in wards is the DaiJoin adapter, which does not contain instructions to call `rely` or `deny`, the `wards` list is effectively frozen and cannot be modified on the mainnet deployment. The only occasion where rely and deny is expected to be used is during deployment.

### DaiJoin Adapter

The ERC20 Dai Token contract does not represent all Dai supply, as Dai can be in the form of internal balances to the Maker Protocol contracts. For a rundown of the different types of Dai, and the relation between them, please see the guide [Tracking Dai Supply](https://github.com/makerdao/developerguides/blob/master/dai/dai-supply/dai-supply.md)

The DaiJoin Adapter is used to convert internal Dai to a ERC20 token usable by wallets and exchanges. Typically, contracts and users deposit their internal Dai into the DaiJoin Adapter and obtain ERC20 tokens in exchange. Any holder of a ERC20 Dai token can also withdraw internal Dai from the contract by burning ERC20 Dai.

- `exit(address usr, uint wad)`: Transfers an internal Dai balance of the amount `wad` from address `usr` to the DaiJoin contract, and mint new ERC20 in favor of `usr`.
- `join(address usr, uint wad)`: Burns `wad` Dai from address `usr` and transfer the equivalent internal Dai in its favor. Note that join is possible only if the DaiJoin contract is approved.

### **Emergency Shutdown**

MKR holders can through the governance contract vote to shut down the system by executing the `cage()` function on the [ESM](https://etherscan.io/address/0x0581a0abe32aae9b5f0f68defab77c6759100085#code) contract.

After emergency shutdown, all DAI holders are allowed to claim collateral for each token at the last price reported by price feed oracles. Two functions `cash()` and `pack()`, are activated in [END](https://etherscan.io/address/0xaB14d3CE3F733CACB76eC2AbE7d2fcb00c99F3d5#code) contract. `cash()` allows token holders to redeem Dai for ETH at the exchange ratio set at emergency shutdown.

More information about the Emergency Shutdown can be found in the [Emergency Shutdown Guide](https://github.com/makerdao/developerguides/blob/master/mcd/emergency-shutdown/emergency-shutdown-guide.md).

### Deploy on testnet

Dai and the associated MCD contracts are deployed on [various testnets](https://changelog.makerdao.com), but you may want do deploy your own version of the Dai contract to test your ERC20 or `permit` integrations. The following instructions require a working configuration of [dapp.tools](https://dapp.tools), including `dapp` (tested with v0.27.0) and `seth` (v0.8.4) and a provisionned test account with its associated keys.

1. `git clone`[https://github.com/makerdao/dss](https://github.com/makerdao/dss)
2. `cd dss`
3. `dapp update`
4. `dapp build`
5. `export SETH_CHAIN=kovan` :
   Change kovan for your prefered chain
6. `export ETH_KEYSTORE=~/keys` : Define where your keys are store
7. `export ETH_FROM=<address>` : Set your test account
8. `export ETH_RPC_URL=<RPC URL>` : Set the URL for a testnet RPC node (Infura or other)
9. `export chainid= $(seth --to-uint256 42)`: Deploying the contract requires passing the chain id, for use with the permit function. For Kovan, the id is 42.
10. `dapp create Dai $chainid` : To deploy the contract. If successful, this will return the address of your new contract.

If you want to verify your contract on Etherscan, use the output of

`hevm flatten --source-file src/dai.sol --json-file out/dapp.sol.json`

and specify the content of `$chainid` as the ABI formatted constructor.

Once deployed, you may test your contract

1. `export DAIK=<deployed contract address>`
2. `seth call $DAIK 'wards(address)' $ETH_FROM`: Should return 1 because the adress that deployed the contract is part of wards by default.
3. `seth send $DAIK 'mint(address,uint256)' $ETH_FROM $(seth --to-uint256 $(seth --to-wei 100000000 eth))`: Will mint yourself 100,000,000 test-DAI
4. `seth --from-wei $(seth --to-dec $(seth call $DAIK 'balanceOf(address)' $ETH_FROM))`: To see your test-Dai balance

## Summary

In this guide, we briefly discussed the technical details of the Dai token contract as well as a quick summary of its role in the Maker Protocol. Please refer to the links embedded in the document as well as the additional resources section for more information. We also urge you to explore the various tools and services built on top of Dai by our partner ecosystem.

## Additional resources

1. [https://github.com/makerdao/dss/blob/master/src/dai.sol](https://github.com/makerdao/dss/blob/master/src/dai.sol)
2. [Using Dai in smart contracts](https://github.com/makerdao/developerguides/blob/master/dai/dai-in-smart-contracts/README.md)
3. [Emergency Shutdown Guide](https://github.com/makerdao/developerguides/blob/master/mcd/emergency-shutdown/emergency-shutdown-guide.md)
4. [Tracking Dai Supply](https://github.com/makerdao/developerguides/blob/master/dai/dai-supply/dai-supply.md)

## Help

- Contact Integrations team - integrate@makerdao.com
- Rocket chat - #dev channel


Learm how to activate DSR on Dai storend in Gnosis Multisig

Activating Dai Savings Rate on Dai stored in Gnosis Multisig Wallet


# Activating Dai Savings Rate on Dai stored in Gnosis Multisig Wallet

**Level:** Advanced  
**Estimated Time:** 30 minutes

- [Activating Dai Savings Rate on Dai stored in Gnosis Multisig Wallet](#activating-dai-savings-rate-on-dai-stored-in-gnosis-multisig-wallet)
  - [Overview](#overview)
  - [Learning Objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Step 1: Building a DS-Proxy contract for the Multisig](#step-1-building-a-ds-proxy-contract-for-the-multisig)
    - [1.A Create a DS-Proxy for the multisig using Seth](#1a-create-a-ds-proxy-for-the-multisig-using-seth)
    - [1.B Create a DS-Proxy for the multisig through the multisig user interface](#1b-create-a-ds-proxy-for-the-multisig-through-the-multisig-user-interface)
  - [Step 2: Approving DS-Proxy to send Dai from Multisig to DSR contract](#step-2-approving-ds-proxy-to-send-dai-from-multisig-to-dsr-contract)
  - [Step 3: Adding Dai to DSR](#step-3-adding-dai-to-dsr)
  - [Step 4: Retrieving Dai from DSR](#step-4-retrieving-dai-from-dsr)
  - [Additional resources](#additional-resources)
  - [Help](#help)

## Overview

In this guide, we will cover how you can add Dai from the old version of the Gnosis Multisig Wallet, to the DSR, and retrieve it again.

## Learning Objectives

- Learn how to safely move funds from Gnosis Multisig Wallet into the DSR contract of the Maker Protocol.

- Learn how to retrieve Dai and earned savings back into Gnosis Multisig Wallet.

## Pre-requisites

- Basic knowledge of how to execute multisig transactions in the Gnosis Multisig UI.

- Knowledge of [Seth - an Ethereum CLI tool](#https://github.com/makerdao/developerguides/blob/master/devtools/seth/seth-guide-01/seth-guide-01.md)

## Step 1: Building a DS-Proxy contract for the Multisig

Go to [https://wallet.gnosis.pm/](https://wallet.gnosis.pm/) and login with your wallet. This is the old version of Gnosis Multisig.

Navigate to the “Wallets” page, and click on the specific multisig wallet name, to enter the user interface for the specific multisig wallet.

In order to be able to add Dai to DSR, we must first have a DS-Proxy contract created for the multisig wallet to allow us to interact with the Maker Protocol.  

If the multisig wallet already has a DS-Proxy contract deployed, you can retrieve the contract address by using the following seth commands in a terminal ([if you are unfamiliar with seth, go through this guide first](https://github.com/makerdao/developerguides/blob/master/devtools/seth/seth-guide-01/seth-guide-01.md)):

`export PROXY_REGISTRY=0x4678f0a6958e4d2bc4f1baf7bc52e8f3564f3fe4`

`export MULTISIG=<insert multisig wallet address here>`

`seth call $PROXY_REGISTRY 'proxies(address)(address)' $MULTISIG`

If this returns 0, then there is no DS-Proxy deployed, and you must follow the steps below to create one. Follow either step 1.A or 1.B.

### 1.A Create a DS-Proxy for the multisig using Seth

In a terminal use the following commands to create DS-Proxy for the multisig.

`export PROXY_REGISTRY=0x4678f0a6958e4d2bc4f1baf7bc52e8f3564f3fe4`

`export MULTISIG=<insert multisig wallet address here>`

`seth send $PROXY_REGISTRY 'build(address)' $MULTISIG`

Once the transaction has been mined, you should be able to retrieve the DS-Proxy address with the following command:

`seth call $PROXY_REGISTRY 'proxies(address)(address)' $MULTISIG`

### 1.B Create a DS-Proxy for the multisig through the multisig user interface

- Under “Multisig transactions” press “Add”

- In the “Destination” field input the address of ProxyRegistry contract: 0x4678f0a6958e4d2bc4f1baf7bc52e8f3564f3fe4

- In the “ABI string” window copy and insert the entire ABI from this link: [http://api.etherscan.io/api?module=contract&action=getabi&address=0x4678f0a6958e4d2bc4f1baf7bc52e8f3564f3fe4&format=raw](http://api.etherscan.io/api?module=contract&action=getabi&address=0x4678f0a6958e4d2bc4f1baf7bc52e8f3564f3fe4&format=raw)
- In the “Method” dropdown select the first “build” method - there are two “build” options, this one will take no parameters.
- Press “Send multisig transaction.”

Other key holders must now approve this transaction - once it has been approved by they keyholders, a keyholder must execute the function by pressing “Execute” next to the transaction. It can be a gas heavy transaction to build a proxy, so make sure you pass on a gas limit of 400000.

- We need to know the address of this DS-Proxy contract before we can continue. You can navigate to the transaction on Etherscan by inputting the transaction hash of the transaction that was submitted when a keyholder pressed “Execute” into the search bar.
- On Etherscan you can navigate to “Internal transactions and under the type trace "create_0_0_0" you should see a “To” address, which is the proxy contract.

- Verify by navigating to this contract address, clicking on “Contract”, and see that it is in fact a DS-Proxy contract, by verifying the “Contract Name” field. Save the address for this contract.

You can also use the command-line tool seth to retrieve this contract address.

Execute the following commands in a terminal:

`export PROXY_REGISTRY=0x4678f0a6958e4d2bc4f1baf7bc52e8f3564f3fe4`

`export MULTISIG=<insert multisig wallet address here>`

`seth call $PROXY_REGISTRY 'proxies(address)(address)' $MULTISIG`

This should return a string, for example `401f9073f99bd9577c68399c89f270d46e80b65d`

You need to add a “0x” in front so it is for example: `0x401f9073f99bd9577c68399c89f270d46e80b65d`

Save this DS-Proxy contract address as we will need it later.

## Step 2: Approving DS-Proxy to send Dai from Multisig to DSR contract

- Under “Multisig transactions” press “Add”
- In the “Destination” field input the address of the Dai token: `0x6b175474e89094c44da98b954eedeac495271d0f`
- In the “ABI string” window copy and insert the entire ABI text string from the link below: [http://api.etherscan.io/api?module=contract&action=getabi&address=0x6b175474e89094c44da98b954eedeac495271d0f&format=raw](http://api.etherscan.io/api?module=contract&action=getabi&address=0x6b175474e89094c44da98b954eedeac495271d0f&format=raw)
- In the “Method” dropdown select the “approve” method.
- This will generate two input fields below: “usr” and “wad”
- In “usr” you copy paste the address of the DS-Proxy contract we created at the end of step 1.
- In “wad” you enter the amount of Dai you want to let the contract move for you, and add 18 0’s after the number, due to the token having 18 decimal spaces. So if you want to approve 1 Dai, you need to input `1000000000000000000`
- You can also input `-1` to simply allow any size Dai transaction for the future.
- Press “Send multisig transaction.”

- The other key holders must now confirm this transaction, and once the quorum is reached, a keyholder can execute the transaction.
- Once the transaction has been mined you can continue to step 3.

## Step 3: Adding Dai to DSR

- Under “Multisig transactions” press “Add”

- In the “Destination” field input the address of the DS-Proxy contract we created at the end of step 1.
- In the “ABI string” window copy and insert the entire ABI text string from the link below: [http://api-kovan.etherscan.io/api?module=contract&action=getabi&address=0xD0bf0b956f570CdfC0e06f032BfAa0Dc206C56c7&format=raw](http://api-kovan.etherscan.io/api?module=contract&action=getabi&address=0xD0bf0b956f570CdfC0e06f032BfAa0Dc206C56c7&format=raw)
- In the “Method” dropdown select the first “execute” method.
- This will generate to input fields below: **“_target”** and **“_data”**
- In **“_target”** input the contract address of DssProxyActionsDsr: `0x07ee93aeea0a36fff2a9b95dd22bd6049ee54f26`
- In “data” we need to use Seth to create the ABI encoded call data.
- In a terminal post the following commands:

`export POT=0x197e90f9fad81970ba7976f33cbd77088e5d7cf7`

`export DAIJOIN=0x9759a6ac90977b93b58547b4a71c78317f391a28`

`seth calldata 'join(address,address,uint)' $DAIJOIN $POT $(seth --to-uint256 $(seth --to-wei insert amount of Dai here eth))`

- In the command above, in the `<insert amount of Dai here>` you simply pass on the amount you granted approval for in step 2. So if you granted approval for 1000 Dai, you just input 1000 in the above command. For example:

`seth calldata 'join(address,address,uint)' $DAIJOIN $POT $(seth --to-uint256 $(seth --to-wei 1000 eth))`

- This should return a text string in the terminal, which you must copy paste into the “_data” field in the “Send multisig transaction” user interface.

- Example of what a string could look like:

`0x9f6c3dbd0000000000000000000000005aa71a3ae1c0bd6ac27a1f28e1415fffb6f15b8c000000000000000000000000ea190dbdc7adf265260ec4da6e9675fd4f5a78bb0000000000000000000000000000000000000000000000008ac7230489e80000`

- Press “Send multisig transaction.”
- The other key holders must now confirm this transaction, and once the quorum is reached, a keyholder can execute the transaction. This is also a gas intensive transaction, so make sure to set a higher gas limit - try with 400000.
- Once the transaction has been mined the Dai should be added to DSR.

You can verify by inserting the address of the multisig wallet into the search bar of [dsr.fyi](https://dsr.fyi/).

You can also verify by navigating to the DSR contract on Etherscan here: [https://etherscan.io/address/0x197e90f9fad81970ba7976f33cbd77088e5d7cf7#readContract](https://etherscan.io/address/0x197e90f9fad81970ba7976f33cbd77088e5d7cf7#readContract)

Under “Read Contract”, function 5. “Pie” you can insert the DS-Proxy contract address from step 1. It will return a number a little lower than what you added, since this is the normalized internal balance of DSR. To get your Dai balance you must multiply this number with Chi. As long as this is a non-zero number you should be good to go.

## Step 4: Retrieving Dai from DSR

- Under “Multisig transactions” press “Add”
- In the “Destination” field input the address of the DS-Proxy contract we created at the end of step 1.
- In the “ABI string” window copy and insert the entire ABI text string from the link below: [http://api-kovan.etherscan.io/api?module=contract&action=getabi&address=0xD0bf0b956f570CdfC0e06f032BfAa0Dc206C56c7&format=raw](http://api-kovan.etherscan.io/api?module=contract&action=getabi&address=0xD0bf0b956f570CdfC0e06f032BfAa0Dc206C56c7&format=raw)
- In the “Method” dropdown select the first **“execute”** method.
- This will generate to input fields below: **“_target”** and **“_data”**
- In “_target” input the contract address of DssProxyActionsDsr: `0x07ee93aeea0a36fff2a9b95dd22bd6049ee54f26`
- In **“data”** we need to use Seth to create the ABI encoded call data.
- A) If you want to retrieve all Dai in DSR utilize the following seth commands in a terminal to create the data.

`export POT=0x197e90f9fad81970ba7976f33cbd77088e5d7cf7`

`export DAIJOIN=0x9759a6ac90977b93b58547b4a71c78317f391a28`

`seth calldata 'exitAll(address,address)' $DAIJOIN $POT`

- This should return this string, which should always be the same, so verify that you get the same exact string:

`0xc77843b30000000000000000000000009759a6ac90977b93b58547b4a71c78317f391a28000000000000000000000000197e90f9fad81970ba7976f33cbd77088e5d7cf7`

- B) If you just want to retrieve a specific amount, you must utilize the following seth commands in a terminal to create the data:

`export POT=0x197e90f9fad81970ba7976f33cbd77088e5d7cf7`

`export DAIJOIN=0x9759a6ac90977b93b58547b4a71c78317f391a28`

`seth calldata 'exit(address,address,uint)' $DAIJOIN $POT $(seth --to-uint256 $(seth --to-wei insert amount of Dai here eth))`

To create the data for a transfer of 10,000 Dai the last commands would thus be

`seth calldata 'exit(address,address,uint)' $DAIJOIN $POT $(seth --to-uint256 $(seth --to-wei 10000 eth))`

- Copy paste the string for retrieving all Dai, or a specific amount of Dai depending on which of option A) and B) you chose above, into the “_data” field in the “Send multisig transaction” user interface.

- Press “Send multisig transaction.”
- The other key holders must now confirm this transaction, and once the quorum is reached, a keyholder can execute the transaction. This is also a gas intensive transaction, so make sure to set a higher gas limit - try with 400000.
- Once the transaction has been mined the Dai should be retrieved from DSR.

You can verify by inserting the address of the multisig wallet into the search bar of [dsr.fyi](https://dsr.fyi/).

You can also verify by navigating to the DSR contract on Etherscan here: [https://etherscan.io/address/0x197e90f9fad81970ba7976f33cbd77088e5d7cf7#readContract](https://etherscan.io/address/0x197e90f9fad81970ba7976f33cbd77088e5d7cf7#readContract)

Under “Read Contract”, function 5. “Pie” you can insert the DS-Proxy contract address from step 1. It will return a number a little lower than what you should have left or 0 if you retrieved it all, since this is the normalized internal balance of DSR. To get your Dai balance you must multiply this number with Chi. As long as this is a number close to what you would expect you should be good to go.

## Additional resources

- [DSR Integration Guide](https://github.com/makerdao/developerguides/blob/master/dai/dsr-integration-guide/dsr-integration-guide-01.md)

## Help

- Rocket chat - [#dev](https://chat.makerdao.com/channel/dev) channel


Learn about DsrManager and integrate with DSR

DsrManager


# DsrManager

**Level**: Beginner  
**Estimated Time**: 10 minutes

- [DsrManager](#dsrmanager)
  - [Deployment Details](#deployment-details)
  - [Contract Details](#contract-details)
    - [Math](#math)
    - [Storage](#storage)
  - [Functions and mechanics](#functions-and-mechanics)
    - [daiBalance(address usr) returns (uint wad)](#daibalanceaddress-usr-returns-uint-wad)
    - [join(address dst, uint wad)](#joinaddress-dst-uint-wad)
    - [exit(address dst, uint wad)](#exitaddress-dst-uint-wad)
    - [exitAll(address dst)](#exitalladdress-dst)
  - [Gotchas / Integration Concerns](#gotchas--integration-concerns)

The `DsrManager` provides an easy to use smart contract that allows service providers to deposit/withdraw dai into the DSR contract [pot](/documentation/pot-proxy-detailed-documentation), 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 [pot](/documentation/pot-proxy-detailed-documentation) first. The DSR is set by Maker Governance, and the purpose of DSR is to offer another incentive for holding Dai.

## Deployment Details

- Mainnet: [0x373238337Bfe1146fb49989fc222523f83081dDb](https://etherscan.io/address/0x373238337Bfe1146fb49989fc222523f83081dDb#code)
- Kovan: [0x7f5d60432DE4840a3E7AE7218f7D6b7A2412683a](https://kovan.etherscan.io/address/0x7f5d60432DE4840a3E7AE7218f7D6b7A2412683a#code)
- Ropsten: [0x74ddba71e98d26ceb071a7f3287260eda8daa045](https://ropsten.etherscan.io/address/0x74ddba71e98d26ceb071a7f3287260eda8daa045#code)

## Contract Details

### Math

- `wad` - some quantity of tokens, as a fixed point integer with 18 decimal places.
- `ray` - a fixed point integer, with 27 decimal places.
- `rad` - a fixed point integer, with 45 decimal places.
- `mul(uint, uint)`, `rmul(uint, uint)`, `add(uint, uint)` & `sub(uint, uint)` - will revert on overflow or underflow
- `Rdiv` - Divide two `ray`s and return a new `ray`. Always rounds down. A `ray` is a decimal number with 27 digits of precision that is being represented as an integer.
- `Rdivup` - Divide two `ray`s and return a new `ray`. Always rounds up. A `ray` is a decimal number with 27 digits of precision that is being represented as an integer.

### Storage

- `pot` - stores the contract address of the main Dai Savings Rate contract `pot`.
- `dai` - stores the contract address of dai.
- `daiJoin` - stores the contract address of the Dai token adapter.
- `supply` - the supply of Dai in the DsrManager.
- `pieOf` - `mapping (addresses=>uint256)` mapping of user addresses and normalized Dai balances (`amount of dai / chi`) deposited into `pot`.
- `pie` - stores the address' `pot` balance.
- `chi` - the rate accumulator. This is the always increasing value which decides how much dai is given when `drip()` is called.
- `vat` - an address that conforms to a `VatLike` interface.
- `rho` - the last time that `drip` is called.

## Functions and mechanics

### daiBalance(address usr) returns (uint wad)

- Calculates and returns the Dai balance of the specified address usr in the DsrManager contract. (Existing Dai balance + earned dsr)

### join(address dst, uint wad)

- `uint wad` this parameter specifies the amount of Dai that you want to join to the pot. The `wad` amount of Dai must be present in the account of `msg.sender`.
- address `dst` specifies a destination address for the deposited dai in the pot. Allows a hot wallet address (`msg.sender`) to deposit dai into the pot and transfer ownership of that dai to a cold wallet (or any other address for that matter)
- The normalized balance `pie` is calculated by dividing wad with the rate acumulator `chi`.
- the `dst`'s `pieOf` amount is updated to include the `pie`.
- The total supply amount is also updated by adding the `pie`.
- `wad` amount of dai is transferred to the DsrManager contract
- The DsrManager contract joins `wad` amount of dai into the MCD system through the dai token adapter `daiJoin`.
- The DsrManager contract `join`s `pie` amount of dai to the `pot`.

### exit(address dst, 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`.
- address `dst` specifies a destination address for the retrieved dai from the `pot`. Allows a cold wallet address (`msg.sender`) to retrieve dai from the `pot` and transfer ownership of that dai to a hot wallet (or any other address for that matter)
- The normalized balance `pie` is calculated by dividing wad with the rate acumulator `chi`.
- The `msg.sender`’s `pieOf` amount is updated by subtracting the `pie`.
- The total supply amount is also updated by subtracting the `pie`.
- The contract calls exit on the `pot` contract.
- It calculates the amount of dai to retrieve by multiplying `pie` with `chi`.
- Then exits the dai from the dai token adapter `daiJoin` to the destination address `dst`.

### exitAll(address dst)

- `exitAll()` functions like the `exit` function, except it simply looks into the mapping `pieOf`, to determine how much dai the `msg.sender` has, and `exit`s the entire amount of dai, instead of a specified amount.

## Gotchas / Integration Concerns

- In order to use the `join` function, you need to `approve` the contract to transfer Dai from your wallet. You need to call `approve` on the Dai token, specifying the `DsrManager` contract and the amount that the contract should be able to pull (can be set to `-1`, if you want to set an unlimited approval)


Learn how to activate DSR in Dai locked in Gnosis Multisig with DSR Manager

Add Dai to DSR through DsrManager with Gnosis Multisig


# Add Dai to DSR through DsrManager with Gnosis Multisig

**Level:** Advanced  
**Estimated Time:** 20 minutes

- [Add Dai to DSR through DsrManager with Gnosis Multisig](#add-dai-to-dsr-through-dsrmanager-with-gnosis-multisig)
  - [Overview](#overview)
  - [Learning Objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Step 1: Approve DsrManager](#step-1-approve-dsrmanager)
  - [Step 2: Add Dai to DSR](#step-2-add-dai-to-dsr)
  - [Step 3: Retrieve Dai from DSR](#step-3-retrieve-dai-from-dsr)
    - [3.A - Retrieve a portion of Dai from DSR](#3a---retrieve-a-portion-of-dai-from-dsr)
    - [3.B - Retrieve all Dai from DSR](#3b---retrieve-all-dai-from-dsr)
  - [Additional Resources](#additional-resources)
  - [Help](#help)

## Overview

In this guide, we will cover how you can add Dai from the old version of the Gnosis Multisig Wallet, to the DSR, and retrieve it again through the DsrManager contract.

## Learning Objectives

- Learn how to safely move Dai funds from Gnosis Multisig Wallet into the DSR contract of Maker Protocol through [DsrManager contract](https://etherscan.io/address/0x373238337Bfe1146fb49989fc222523f83081dDb#code).

- Learn how to retrieve Dai and earned savings back into Gnosis Multisig Wallet.

## Pre-requisites

- Basic knowledge of how to execute multisig transactions in the Gnosis Multisig UI.

## Step 1: Approve DsrManager

Go to [https://wallet.gnosis.pm](https://wallet.gnosis.pm) and login with your wallet. This is the old version of Gnosis Multisig.

Navigate to the “Wallets” page, and click on the specific multisig wallet name, to enter the user interface for the specific multisig wallet.

In order to be able to add Dai to DSR, we must first have to approve DsrManager to pull funds from your multisig wallet. To approve, you need to approve the DsrManager contract in the Dai token contract.

Approve DsrManager through the multisig user interface

- Under “Multisig transactions” press “Add”
- In the “Destination” field input the address of Dai Token contract: `0x6B175474E89094C44Da98b954EedeAC495271d0F`
- In the “ABI string” window copy and insert the entire ABI from this link: [https://api.etherscan.io/api?module=contract&action=getabi&address=0x6b175474e89094c44da98b954eedeac495271d0f&format=raw](https://api.etherscan.io/api?module=contract&action=getabi&address=0x6b175474e89094c44da98b954eedeac495271d0f&format=raw)
- In the “Method” dropdown select the “approve” method.
- This will generate two input fields below: “usr” and “wad”
- In “usr” you copy paste the address of the DsrManager contract - `0x373238337Bfe1146fb49989fc222523f83081dDb`
- In “wad” you write the amount of Dai you want to allow DsrManager to pull from your wallet. To allow it to withdraw any size of Dai, set “wad” to `-1`. If you want a certain number, set “wad” to your number plus the 18 zero decimals after. For 10 Dai, you’ll input `10000000000000000000`.
- Press “Send multisig transaction.”
- The other key holders must now confirm this transaction, and once the quorum is reached, a keyholder can execute the transaction.
- Once the transaction has been mined, you can continue to step 2.

## Step 2: Add Dai to DSR

- Under “Multisig transactions” press “Add”
- In the “Destination” field input the address of DsrManager contract: `0x373238337Bfe1146fb49989fc222523f83081dDb`
- In the “ABI string” field, copy and insert the entire ABI from this link: [https://api.etherscan.io/api?module=contract&action=getabi&address=0x373238337Bfe1146fb49989fc222523f83081dDb&format=raw](https://api.etherscan.io/api?module=contract&action=getabi&address=0x373238337Bfe1146fb49989fc222523f83081dDb&format=raw)
- In the “Method” dropdown, select the “join” method.
- This will generate two input fields: “dst” and “wad”.
- In “dst”, copy paste your multisig wallet address.
- In “wad”, write the amount of Dai you want to lock in DSR. For example, locking in 10 Dai, you’ll paste in `10000000000000000000`. Make sure to add 18 zeros, as the token has 18 decimal places.
- Press “Send multisig transaction”. This is a gas intensive transaction, so make sure to set a higher gas limit - try with 400000.
- The other key holders must now confirm this transaction, and once the quorum is reached, a keyholder can execute the transaction.
- Once the transaction has been mined the Dai should be added to DSR.

You can verify by pasting your multisig wallet address in the `pieOf` [contract field of DsrManager](https://etherscan.io/address/0x373238337bfe1146fb49989fc222523f83081ddb#readContract). It will return a number a little lower than what you added, since this is the normalized internal balance of DSR. To get your Dai balance you must multiply this number with Chi. As long as this is a non-zero number you should be good to go.

## Step 3: Retrieve Dai from DSR

There are two options to retrieve your Dai from DSR. You could retrieve it all at once or just retrieve a portion of it.

### 3.A - Retrieve a portion of Dai from DSR

- Under “Multisig transactions” press “Add”
- In the “Destination” field input the address of DsrManager contract: `0x373238337Bfe1146fb49989fc222523f83081dDb`
- In the “ABI string” field, copy and insert the entire ABI from this link: [https://api.etherscan.io/api?module=contract&action=getabi&address=0x373238337Bfe1146fb49989fc222523f83081dDb&format=raw](https://api.etherscan.io/api?module=contract&action=getabi&address=0x373238337Bfe1146fb49989fc222523f83081dDb&format=raw)
- In the “Method” dropdown select the “exit” method.
- This will generate two fields: “dst” and “wad”.
- In “dst”, copy paste your multisig wallet address.
- In “wad”, write the amount of Dai you want to retrieve from DSR. To withdraw 5 Dai, you set “wad” to: `5000000000000000000`. Make sure to add 18 zeros, as the token has 18 decimal places.
- Press “Send multisig transaction”. This is also a gas intensive transaction, so make sure to set a higher gas limit - try with `400000`.
- The other key holders must now confirm this transaction, and once the quorum is reached, a keyholder can execute the transaction.
- Once the transaction has been mined the Dai should be in your multisig wallet.

### 3.B - Retrieve all Dai from DSR

- Under “Multisig transactions” press “Add”
- In the “Destination” field input the address of DsrManager contract: `0x373238337Bfe1146fb49989fc222523f83081dDb`
- In the “ABI string” field, copy and insert the entire ABI from this link: [https://api.etherscan.io/api?module=contract&action=getabi&address=0x373238337Bfe1146fb49989fc222523f83081dDb&format=raw](https://api.etherscan.io/api?module=contract&action=getabi&address=0x373238337Bfe1146fb49989fc222523f83081dDb&format=raw)
- In the “Method” dropdown select the “exitAll” method.
- This will generate one field: “dst”.
- In “dst”, copy paste your multisig wallet address.
- Press “Send multisig transaction”. This is also a gas intensive transaction, so make sure to set a higher gas limit - try with 400000.
- The other key holders must now confirm this transaction, and once the quorum is reached, a keyholder can execute the transaction.
- Once the transaction has been mined the Dai should be in your multisig wallet.

## Additional Resources

- [DSR Integration Guide](https://github.com/makerdao/developerguides/blob/master/dai/dsr-integration-guide/dsr-integration-guide-01.md)

## Help

- [chat.makerdao.com - #dev channel](https://chat.makerdao.com/channel/dev)


Learn about design processes for the emergency shutdown process

Emergency Shutdown Design Patterns for Integrations

This guide outlines the steps and procedures necessary to check, interact with and trigger the ESM

Emergency Shutdown (ES) CLI


# Emergency Shutdown (ES) CLI

**Level**: Intermediate

**Estimated-Time**: 30 minutes

## Description

Emergency Shutdown ES is the last resort to protect the Maker Protocol against a serious threat, such as but not limited to governance attacks, long-term market irrationality, hacks and security breaches. The Emergency Shutdown Module ESM is responsible for coordinating emergency shutdown, the process used to gracefully shutdown the Maker Protocol and properly allocate collateral to both Vault users and Dai holders. This guide outlines the steps and procedures necessary to check, interact with and trigger the ESM.

#### **Learning Objectives:** To be able to Check, Deposit and Trigger Emergency Shutdown.

### Table of Contents

1. Installation
2. Contract Address Setup
3. Commands and Explanations
   - Checking your MKR balance
   - Checking and setting your MKR approval
   - Checking the live flag
   - Checking the ESM threshold
   - Deposit a trial amount of MKR into the ESM
   - Depositing MKR into the ESM
   - Checking how much MKR is in the ESM
   - Checking whether the ESM has been triggered
   - Triggering the ESM

## 1. Installation

In order to interface with the Ethereum blockchain, the user needs to install seth, a command line tool as part of the [Dapp.Tools](https://dapp.tools/) toolset. We also provide further [installation information here](https://github.com/makerdao/developerguides/blob/master/devtools/seth/seth-guide-01/seth-guide-01.md). Once the user has installed and configured [`seth`](https://dapp.tools/) correctly to use the main Ethereum network and the address which holds their MKR they can query contract balances, approvals and transfers.

## 2. Contract Address Setup

- The user will require the following contract addresses; MCD_END and MCD_ESM accessible at [Changelog.makerdao.com](https://changelog.makerdao.com) as well as the Maker contract address, to be added in place of MKR_ADR below, which can be verified on [Etherscan](https://etherscan.io/token/0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2).
- These should be setup in the following manner:

```bash
export MCD_END= 0xab14d3ce3f733cacb76ec2abe7d2fcb00c99f3d5
export MCD_ESM= 0x0581a0abe32aae9b5f0f68defab77c6759100085
export MKR_ADR= <MKR ADDRESS from Etherscan.io>
export MY_ADR= <USER ADDRESS>

#example values for depositing into the ESM
export TRIAL_AMOUNT=$(seth --to-uint256 $(seth --to-wei 0.1 eth))
export REMAINING_AMOUNT=$(seth --to-uint256 $(seth --to-wei 50000 eth))
```

## 3. Commands and Explanations

#### Checking your MKR balance

Before depositing your MKR into the ESM contract, first check your address MKR balance:

```bash
seth --from-wei $(seth call $MKR_ADR "balanceOf(address)" $MY_ADR | seth --to-dec)
# 100000.000000000000000000
```

#### Checking and setting your MKR approval

In order to execute the contract functions of the MKR token it is required that approvals be set on the token. The first step is to check if the ESM contract is allowed to withdraw from your address:

```bash
seth call $MKR_ADR "allowance(address,address)" $MY_ADR $MCD_ESM
# 0x0000000000000000000000000000000000000000000000000000000000000000 -> not allowed
```

If the ESM contract is not allowed to withdraw from your address, the following can be used to set the allowance on the MKR token. This will approve the ESM to withdraw from the user's wallet:

```bash
seth send $MKR_ADR "approve(address)" $MCD_ESM
```

Following which we again check to confirm that the ESM is allowed to withdraw from the user's account. This action will return uint256 to confirm the allowance to withdraw.

```bash
seth call $MKR_ADR "allowance(address,address)" $MY_ADR $MCD_ESM
# 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff -> allowed
```

[Reference contract information](https://github.com/dapphub/ds-token/blob/cee36a14685b3f93ffa0332853d3fcd943fe96a5/src/token.sol#L36).

#### Checking the live flag

Live contracts have `live` = 1, indicating that the system is running normally. Thus when `cage()` is invoked, it sets the flag to 0.

```bash
seth call $MCD_END "live()" | seth --to-dec
# 1 -> system is running normally
```

#### Checking the ESM threshold

In order to check the `min` value, you can call:

```bash
seth --from-wei $(seth call $MCD_ESM "min()" | seth --to-dec)
# 50000.000000000000000000
```

#### Deposit a small amount (0.1 MKR) into the ESM

To deposit a small amount of MKR into the esm contract to test correct deposit function, we use the `join` function and specify a small amount.

```bash
seth send $MCD_ESM "join(uint256)" $TRIAL_AMOUNT
```

#### Checking how much MKR is in the ESM

To check for the total amount of MKR that has been added to the ESM we call the `Sum()` function

```bash
seth --from-wei $(seth call $MCD_ESM "Sum()" | seth --to-dec)
# 50050.000000000000000000
```

#### Checking how much MKR you have included in the ESM

To check how much MKR you have included in the ESM we can call lowercase `sum()` with the user address as an argument:

```bash
seth --from-wei $(seth call $MCD_ESM "sum(address)" $MY_ADR | seth --to-dec)
# 50.000000000000000000
```

#### Depositing e.g. 50,000 MKR into the ESM

To deposit MKR into the esm contract we use the `join` function and specify the amount.

```bash
seth send $MCD_ESM "join(uint256)" $REMAINING_AMOUNT
```

Please specify the amount of MKR that you intend to deposit into the ESM.

#### Checking whether the ESM has been triggered

To validate that the Emergency Shutdown has been triggered, the `fired()` function can be called which will return a boolean.

```bash
seth call $MCD_ESM "fired()" | seth --to-dec
# 0 -> ES has not been triggered
```

#### Triggering the ESM

In order for the emergency shutdown to trigger, it is required that the `Sum()` is greater than the `min()` . Only then can the `fire()` function be executed successfully.

```bash
seth send $MCD_ESM "fire()"
```

**Note:** If triggering the ESM is not successful, ensure gas is set at an appropriate level

**Note:** The triggering of the ESM is **not** to be taken lightly; for a full explanation of the implications please review the below documentation.

#### Links

- [ESM.sol](https://github.com/makerdao/esm/blob/master/src/ESM.sol)
- [Further Documentation](https://www.notion.so/makerdao/Emergency-Shutdown-Module-3073acf244404f7f98b5e47d2efc7ba9)
- [End Documentation](https://www.notion.so/makerdao/End-Detailed-Documentation-1874a49064644c51aa34fb9c303eda90)


Learm about the Emergency Shutdown Process of the Maker Protocol

Emergency Shutdown Guide - MCD

How to use permit function and relayers to pay gas for Dai transactions in Dai


# How to use permit function and relayers to pay gas for Dai transactions in Dai

**Level:** Intermediate  
**Estimated Time**: 30 min

- [How to use permit function and relayers to pay gas for Dai transactions in Dai](#how-to-use-permit-function-and-relayers-to-pay-gas-for-dai-transactions-in-dai)
  - [Overview](#overview)
  - [Learning Objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Overview of meta transactions](#overview-of-meta-transactions)
  - [Permit](#permit)
    - [The Typed Signed Data standard](#the-typed-signed-data-standard)
    - [Permit in the Dai contract](#permit-in-the-dai-contract)
      - [Note on security](#note-on-security)
      - [Example with web3js](#example-with-web3js)
    - [Create signed message with web3js](#create-signed-message-with-web3js)
    - [Relay transaction with another wallet account from your Metamask account](#relay-transaction-with-another-wallet-account-from-your-metamask-account)
    - [Transfers](#transfers)
    - [Relaying to Ethereum Network](#relaying-to-ethereum-network)
  - [Notes on Gas Station Network](#notes-on-gas-station-network)
  - [Summary](#summary)
  - [Additional Resources](#additional-resources)
  - [Help](#help)

## Overview

With the deployment of MCD, the Dai token has received an improvement in its token contract. This improvement is the addition of a new function called [permit](https://github.com/makerdao/dss/blob/master/src/dai.sol#L118). This function, which in its own is made possible by the [EIP712](https://eips.ethereum.org/EIPS/eip-712) standard, allows service provider to create integrations that allows Dai holders to pay their transaction fees in Dai, eliminating the need to have Ether to pay for gas on transactions involving Dai.  
Through this feature, we are one step closer to improving user experience and adoption in the crypto ecosystem.

In this guide, you will learn more about how this feature works and how you could implement it in your own dapp.

## Learning Objectives

Understand the permit function and how to use it in your dApp for gasless Dai transactions, where you pay for transaction fees in Dai.

- Permit function
- Relayers
- Creating gasless Dai transactions

## Pre-requisites

Knowledge of:

- [Dai token contract](/documentation/dai-detailed-documentation)
- [Solidity](https://solidity.readthedocs.io/)
- [Web3js](https://web3js.readthedocs.io/)

## Overview of meta transactions

![Meta Transactions Figure](https://lh3.googleusercontent.com/8vjG4YeUPJ3cl802LbrJKaoRLlYBQ04oSPkxyCA7X_ASSoJ0ZIgGdbCKdyHlj_L-8B3k0kHNyo5kV-dl44u8oOE2hP96oQm691iyPGi9O2GI-APABHIfRrfrPNcRWV7rEU9JcxY)

When interacting with smart contracts on the Ethereum blockchain, users always need to make a transaction by paying some gas with their wallet address. The user signs the transaction with his wallet and then relays it to the node that his wallet is connected to.

With meta transactions, the user could make transactions on the Ethereum blockchain without directly paying for the transaction fee in Ether, but in the token that he has in his wallet.

The meta transactions work by having the user sign the transaction and then pass that signed transaction or message to a third party service that will relay his transaction onto the blockchain.

This third party service is called a relayer and since there is no such thing as a free lunch, this relayer has to be incentivized to relay the transaction. The incentive comes as a fee that the user pays in the native token that he wants to transfer in the first place. It is up to the relayer how he designs his fee structure. It can have a pool of Ether ready to be used for broadcasting the incoming signed transactions or do the process on the fly by exchanging the token into Ether and using that to broadcast the transaction. And claiming a small fee on top of the transaction fee for providing the relay service.

## Permit

The Dai permit function allows a spender to move funds from a user wallet by having the user sign an approval message, rather than an approval transaction on the Ethereum blockchain, which eliminates the initial gas cost of approval. The signed approval message can then be broadcasted by a relayer.

By having the permit function use the EIP712 standard, it can sign structured typed data. This allows developers to create transactions that do not simply allow a transfer of tokens from one address to another, but also transactions that involve more complicated smart contract function calls. With the permit function, as an example, now you can exchange your Dai token to another one on Uniswap without the need to have Ether in your wallet to pay for gas.

### The Typed Signed Data standard

Using EIP712, when signing data with your wallet, you will see a JSON like format of the data in your wallet approval window. This enables you to understand what data you are signing.

### Permit in the Dai contract

Constructing the permit function requires some extra parameters defined by the EIP712 standard. These parameters are required for protecting the transaction from a replay attack. This is important as many function calls in smart contracts could have the same signature, so having some parameters that differentiate a signature from another is paramount.

Hence, you might notice some extra variables that are needed in constructing the [permit function](https://github.com/makerdao/dss/blob/master/src/dai.sol#L118).

Below variables are defined in the Dai token contract:

- `chainId`: The ID of the network the contract is deployed. For Mainnet it is 1, for Kovan it is 42.
- `version:` The contract version
- `nonce:` The nonce of the last permit transaction of a user’s wallet.

This variable is defined during function construction:

- `expiry`: How long is the permit function available to be executed. Set in seconds.

The above parameters are verified when calling the permit function in the Dai token contract with the `DOMAIN_SEPARATOR`

The `v`, `r`, and `s` parameters are the result of the cryptographic signature performed when a message is signed. These parameters are used in verifying the signer of the message in the permit function in the Dai token contract.

#### Note on security

With all the aforementioned parameters for signing the permit function, the user is protected against major malicious acts from the relayers or facilitating smart contracts.
With the addition of the expiry variable, you are minimizing the risk of the relayer taking the signed message hostage and not broadcast it to the network. In case this relayer does behave maliciously, he would only be able to keep the message until the expiry value has been reached.  
Another important aspect is to verify the contracts that you are giving allowance to use your funds. If there’s a malicious entry in that contract that could take advantage of a function that has an allowance to use your funds, you are at risk of losing them.

#### Example with web3js

Let’s look at a simple example where you approve another EOA (externally owned account) to withdraw Dai from your wallet with web3.js and the Dai token contract on Kovan.

Make sure you have:

- [Metamask plugin](https://metamask.io/) installed
- Kovan ETH (get ETH from [https://faucet.kovan.network/](https://faucet.kovan.network/))
- Kovan Dai (get Dai from [https://oasis.app/borrow?network=kovan](https://oasis.app/borrow?network=kovan) using ETH)

### Create signed message with web3js

Define permit function parameters

```javascript
const fromAddress = '0x9EE5e175D09895b8E1E28c22b961345e1dF4B5aE';
const expiry = Date.now() + 120;
const nonce = 1;
const spender = '0xE1B48CddD97Fa4b2F960Ca52A66CeF8f1f8A58A5';
```

Define helper function to stringify the message data

```javascript
const createPermitMessageData = function () {
  const message = {
    holder: fromAddress,
    spender: spender,
    nonce: nonce,
    expiry: expiry,
    allowed: true,
  };

  const typedData = JSON.stringify({
    types: {
      EIP712Domain: [
        {
          name: 'name',
          type: 'string',
        },
        {
          name: 'version',
          type: 'string',
        },
        {
          name: 'chainId',
          type: 'uint256',
        },
        {
          name: 'verifyingContract',
          type: 'address',
        },
      ],
      Permit: [
        {
          name: 'holder',
          type: 'address',
        },
        {
          name: 'spender',
          type: 'address',
        },
        {
          name: 'nonce',
          type: 'uint256',
        },
        {
          name: 'expiry',
          type: 'uint256',
        },
        {
          name: 'allowed',
          type: 'bool',
        },
      ],
    },
    primaryType: 'Permit',
    domain: {
      name: 'Dai Stablecoin',
      version: '1',
      chainId: 42,
      verifyingContract: '0x4F96Fe3b7A6Cf9725f59d353F723c1bDb64CA6Aa',
    },
    message: message,
  });

  return {
    typedData,
    message,
  };
};
```

Define signing function that will use the EIP712 for signing the message data and provide the `r`,`s`, and `v` values.

```javascript
const signData = async function (web3, fromAddress, typeData) {
  return new Promise(function (resolve, reject) {
    web3.currentProvider.sendAsync(
      {
        id: 1,
        method: 'eth_signTypedData_v3',
        params: [fromAddress, typeData],
        from: fromAddress,
      },
      function (err, result) {
        if (err) {
          reject(err); //TODO
        } else {
          const r = result.result.slice(0, 66);
          const s = '0x' + result.result.slice(66, 130);
          const v = Number('0x' + result.result.slice(130, 132));
          resolve({
            v,
            r,
            s,
          });
        }
      }
    );
  });
};
```

Define the function to be invoked when creating the permit signature. This function uses the above defined helper functions to create the signature. The signature created from this function can then be sent to a relayer that will relay the transaction on chain. This relayer can be a simple wallet address with Ether or a server that provides API endpoints for retrieving signatures and relaying the transactions for a fee.

```javascript
export const signTransferPermit = async function () {
  const messageData = createPermitMessageData();
  const sig = await signData(web3, fromAddress, messageData.typedData);
  return Object.assign({}, sig, messageData.message);
};
```

Result from `signTransferPermit`

You can get this data by doing a console.log of the function

```javascript
allowed: true;
expiry: 1589205127399;
holder: '0x9EE5e175D09895b8E1E28c22b961345e1dF4B5aE';
nonce: 1;
r: '0xc225220de6c6f5a829c07bf07444435619c98ac95fb5ce82205bc9be1def858b';
s: '0x5924bfb22181c58e4ec4bc26d42ae5b4edb53ffebf9045cad2e275baab4915ba';
spender: '0xE1B48CddD97Fa4b2F960Ca52A66CeF8f1f8A58A5';
v: 27;
```

### Relay transaction with another wallet account from your Metamask account

Using the signed data from above, now you can relay the user’s transaction by calling the `Dai.permit()` function from your second Metamask wallet address.  
For simplicity, this will be shown through etherscan’s [write contract feature](https://kovan.etherscan.io/address/0x4F96Fe3b7A6Cf9725f59d353F723c1bDb64CA6Aa#writeContract).

Connect to to your second Metamask wallet account and make sure you are connected to Etherscan  
![etherscan image](https://lh3.googleusercontent.com/UUJ2oY3onmx6sQlGPcQOQQg6bBWJQExE9tWJ-hLMGUkKUcT1iUDGKlqNVHHXrZngcut6-RiPcstUhDNiP1Z5EglXjXqJSb10Ng_ZKqYD9Cg2nZ1W8Be7H3Meo0LX94D0TfYlPv4)

Fill the permit function with the right parameters from the `signTransferPermit()` result above.

![etherscan image](https://lh3.googleusercontent.com/qSDkUYxiIvr5IsQO_M1tB991L1SSiWNHT0LFFJQvpz17FsxYsJk_Snnyc_RlNdYOlx_1LbMPerUQbJxmpx7pS-x4a0kGOqQHgI6qZeyqeqthbdPOlomYCDfVDchV44U2uZQXVLE)

Widraw Dai amount from aprover account with your second wallet account.

After relaying the permit transaction, the second account can now withdraw Dai from the first account. This can be done by calling the `Dai.transferFrom()` or `Dai.pull()` functions.

This simple example shows you the fundamentals of this permit function. Here, a second wallet account acted as a relayer to broadcast the signed message on the Ethereum blockchain. A true use case is to have a separate entity/service that will do this relay job for you for a small fee.

### Transfers

In order to implement a complete metatransaction, you will have to deploy a contract that implements the permit feature. This contract, when called, will check for the permit approval from the sender and then pull funds from the sender to the receiver with the `transferFrom` function. The sender needs to give approval to the contract to take funds from his wallet by signing a message with the permit function. The actual invoker of the transfer transaction will be a relayer service that listens for incoming signed messages with the respective function call.

A community implementation example of this can be found in the code base of [https://stablecoin.services/](https://stablecoin.services/). **Note: We are simply using this implementation as an example and should not be taken as endorsed code that can be mimicked for production usage.** This service utilizes a relayer service and smart contracts that allows for transferring your Dai and using other services in a gasless manner.  
The [Dai Automated Clearing House (DACH)](https://etherscan.io/address/0x64043a98f097fD6ef0D3ad41588a6B0424723b3a#code) contract implements the gasless transfer function, specifically the [daiCheque](https://github.com/dapphub/ds-dach/blob/49a3ccfd5d44415455441feeb2f5a39286b8de71/src/dach.sol#L114) function. In order for this function to be successful, it has to verify the permit signature the user signed. The user has to give permission to this contract to pull funds from his wallet to transfer to the receiver and also transfer the fee to the relayer that will broadcast the transaction on the Ethereum network.

In the `daiCheque` function, the user will:

- Sign a permit function to approve the DACH contract.

- Have the permit signature broadcasted on the Ethereum network

- Sign the daiCheque function

- Have the daiCheque signature broadcasted on the Ethereum network.

In this situation, the user will have to broadcast both of the signatures individually onto the network.

To solve they need to broadcast two signatures individually, Stablecoin Services have developed a [helper contract](https://etherscan.io/address/0x3238695287924b4b5a32d71653fc6c26b03b5209#code) that implements both permit and transfer signatures in one transaction.  
The function is also called [daiCheque](https://github.com/dapphub/ds-dach/blob/49a3ccfd5d44415455441feeb2f5a39286b8de71/src/withPermit.sol#L57), but is modified to implement the Dai.permit() function as well. In other words, a cheque with permit function. This way, the user will sign the approval to allow the DACH contract pull funds from his wallet through the Dai.permit() function and also sign the transferFrom function to allow the transfer of funds to the receiver. Both signatures will be broadcasted onto the Ethereum network by the relayer.

### Relaying to Ethereum Network

After signing the permit and daiCheque functions, now you can send them to a relay server to broadcast those transactions onto the Ethereum network. Stablecoin Services have implemented a [relayer](https://github.com/MrChico/stablecoin.services/blob/master/api-doc.md#v1daichequewithpermit) that can help you broadcast your signed messages. This relayer takes a fee for doing the broadcasting.

This relayer is a server that accepts API calls for different functions. All calls are done at this endpoint: [https://api.stablecoin.services](https://api.stablecoin.services/).

In the [daiCheque](https://github.com/dapphub/ds-dach/blob/49a3ccfd5d44415455441feeb2f5a39286b8de71/src/dach.sol#L114) function there’s a fee transfer to the relayer as well, `dai.transferFrom(sender,relayer,fee)`, this fee can be calculated by calling the [/v1/daiChequeWithPermit/fee](https://github.com/MrChico/stablecoin.services/blob/master/api-doc.md#v1chaichequewithpermitfee) if you haven’t signed the permit before or calling [/v1/chaiCheque/fee](https://github.com/MrChico/stablecoin.services/blob/master/api-doc.md#v1daichequefee) if you signed permit before and just wish to transfer Dai.  
The server would return a JSON like response with the fee formatted in wei:

```JSON
{
    "success": "true",
    "message": 911480649973500000
}
```

This fee is then added in the construction of the signing message before it being sent to the relay server for broadcasting. Once broadcasted, this fee is then deposited into the relayer’s account for providing the relay service.

To broadcast the message, make a POST api call at [/v1/daiChequeWithPermit](https://github.com/MrChico/stablecoin.services/blob/master/api-doc.md#v1daichequewithpermit) with the permit and daiCheque signatures. Check [this example](https://github.com/MrChico/stablecoin.services/blob/master/ui/src/utils/apiUtils.js#L30) from Stablecoin Services.

It is up to the relayer service to decide how much to charge for a gasless transaction in addition to the Ethereum network fee. The permit function does not include the fee payment by default.

This allows the relayer to define the fee structure in relaying the signed messages.

## Notes on Gas Station Network

[Gas Station Network](https://www.opengsn.org/) is one of the first attempts at creating gasless transactions. Their architecture allows relayers to only accept Ether for gas as there is no provision for them to directly accept Dai. Users can still pay fees in Dai when they use a Token Paymaster contract that brings additional liquidity risk when converting Dai through Uniswap.

In addition, the entire user Dai balance will be at risk while swapping some Dai for Eth to pay fees because users can only set an unlimited balance approval to the Token Paymaster contract using the permit.

If the gasless contract operator wants to avoid this fee conversion using Uniswap, they need to maintain an ETH balance in GSN.

## Summary

In this guide we have shown you the building blocks of the Dai permit function and how it can be used for creating gasless transactions through the Stablecoin Services Dai Automated Clearing House contract and its relayer server.

## Additional Resources

- [Dai Automated Clearing House (DACH) contracts](https://github.com/dapphub/ds-dach/tree/49a3ccfd5d44415455441feeb2f5a39286b8de71)

- [Stablecoin services relayer API](https://github.com/MrChico/stablecoin.services/blob/master/api-doc.md)

- [Mosendo’s Gasless Dai implementation](https://medium.com/mosendo/gasless-by-mosendo-3030f5e99099)

## Help

For any questions reach us at:

- [integrations@makerdao.com](mailto:integrations@makerdao.com)

- #dev channel in [chat.makerdao.com](https://chat.makerdao.com/)


Understand how the Maker Protocol Rate Mechanism works

Intro to the Rate Mechanism


# Intro to the Rate mechanism

**Level**: Intermediate

**Estimated Time**: 45 - 60 minutes

- [Intro to the Rate mechanism](#intro-to-the-rate-mechanism)
  - [Overview](#overview)
  - [Learning Objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Guide](#guide)
    - [Compound Interest](#compound-interest)
    - [Math](#math)
      - [Fixed Point Numbers](#fixed-point-numbers)
      - [Exponentiation](#exponentiation)
    - [Rate Value](#rate-value)
    - [Rate Accumulator](#rate-accumulator)
    - [Tracking Balances](#tracking-balances)
    - [Multi Collateral Dai](#multi-collateral-dai)
      - [Stability Fees](#stability-fees)
      - [Dai Savings Rate](#dai-savings-rate)
    - [Single Collateral Dai](#single-collateral-dai)
  - [Troubleshooting](#troubleshooting)
  - [Summary](#summary)
  - [Help](#help)

## Overview

Maker governance votes on stability fee changes using annual rates, ex: `5.5%`, but the rate mechanism doesn't rely on annual rates in any form to track the interest accrued in Maker Vaults. As a dapp developer you won't be able to find this number stored in the smart contracts but instead you will run into a number like `1000000001697766583380253701`. In this guide, we'll help you understand how the stored rate value corresponds to the annual number, how multiple changes in both rates and debt levels over the lifetime of a Vault are accounted for in the Maker protocol, and how the rate mechanism is used for tracking both stability fees and the Dai Savings Rate.

## Learning Objectives

After going through this guide you will get a better understanding of,

- Rate Mechanism
- Stability fee calculation
- Dai Savings Rate calculation

## Pre-requisites

You will need a good understanding of these concepts to be able to work through this guide,

- [MCD 101](https://github.com/makerdao/developerguides/blob/master/mcd/mcd-101/mcd-101.md).
- Solidity.

## Guide

### Compound Interest

Investopedia defines compound interest as- “Compound interest (or compounding interest) is interest calculated on the initial principal, which also includes all of the accumulated interest of previous periods of a deposit or loan. Thought to have originated in 17th century Italy, compound interest can be thought of as “interest on interest,” and will make a sum grow at a faster rate than simple interest, which is calculated only on the principal amount.”

The formula for calculating compound interest is:

Compound Interest = Total amount of Principal and Interest in future (or Future Value) less Principal amount at present (or Present Value)

= $[P (1 + i)^n ] - P$

(Where P = Principal, i = nominal annual interest rate in percentage terms, and n = number of compounding periods.)

Please read this article to get a quick refresher on how compound interest works, [https://www.mathsisfun.com/money/compound-interest.html](https://www.mathsisfun.com/money/compound-interest.html)

### Math

#### Fixed Point Numbers

Three different types of fixed point decimal numbers are used throughout the Maker protocol,

- a `wad` type (18 decimal fixed point number) is used to track ERC20 token [balances](https://github.com/makerdao/dss/blob/17be7db1c663d8069308c6b78fa5c5f9d71134a3/src/dai.sol#L82).
- a higher precision `ray` type (27 decimal fixed point number) is used to track [interest rates](https://github.com/makerdao/dss/blob/17be7db1c663d8069308c6b78fa5c5f9d71134a3/src/vat.sol#L37) accrued in Vaults and the Dai Savings Rate contract over time.
- a `rad` type(45 decimal fixed point number) is used to store all internal dai [balances](https://github.com/makerdao/dss/blob/17be7db1c663d8069308c6b78fa5c5f9d71134a3/src/vat.sol#L50) within the Vat contract. This is to ensure no precision is lost when storing the result of a `wad` and `ray` multiplication (18 + 27 = 45).

All these numbers are stored as a `uint256` type within smart contracts and it's easy to miss their fixed-point decimal number type when performing a multiplication if care is not taken. Regular integer multiplication functions available in Solidity add orders of magnitude when applied to these fixed-point decimal numbers.

This issue is illustrated very clearly in the documentation of the [DSMath](http://github.com/dapphub/ds-math) library which implements math functions for wad and ray numbers.

```solidity
1.1 * 2.2 == 2.42

//Regular integer arithmetic adds orders of magnitude:
110 * 220 == 24200

// Wad arithmetic does not add orders of magnitude:
wmul(1.1 ether, 2.2 ether) == 2.42 ether
```

You also have to be careful when using external safe math libraries whose functions may not deal with these number types correctly. All the Maker protocol smart contracts that use these number types have special math functions (usually the multiplication operation) to calculate the correct result.

#### Exponentiation

Exponentiation operation is used to calculate the compound interest accrued over a number of time periods. The [rpow](https://github.com/makerdao/dss/blob/effdda3657f71fd6efc3465dc661b375d1bacc3e/src/jug.sol#L40) function implements exponentiation in Solidity and is used to raise a `ray` to the n^th power and return a new `ray` with the correct precision.

### Rate Value

The Maker protocol does not impose any restrictions on the duration a Vault should be open which allows a user to open or close their Vault anytime as long as it stays over-collateralized and safe. The stability fee rate set by Maker governance changes often and it is common for a single Vault to be charged different rates while its open.

To precisely account for the stability fees accrued over the lifetime of a Vault with these constraints, a time period of 1 second is used for all compound interest calculations in the Maker protocol which means that all the rates stored in the system are also for a second instead of a year.

Let's fire up a Python console and enter the following commands to calculate the annual rate that corresponds to the per-second rate stored here in the [fee](https://etherscan.io/address/0x448a5065aebb8e423f0896e6c5d525c040f59af3#readContract) variable. Let's use `31536000` as the number of seconds in a year and add a decimal point for the rate input.

```python
$python
>>> principal=1
>>> rate=1.000000001697766583380253701
>>> seconds=31536000
>>> principal*(rate**seconds)-principal
0.05500000035258168
>>> 0.05500000035258168*100
5.500000035258168
>>>
```

We can now see that the stored rate compounds to a value of `5.5%` over a year.

### Rate Accumulator

Calculating the stability fee owed by the Vault owner would be a simple calculation if the rate applied to it never changes during its lifetime. Since rates are updated frequently in the system and Vaults need to be charged fees accurately, an additional rate accumulator variable is used to track the fee owed.

A function, typically named `drip` in various contracts, is executed to update the value of a rate accumulator over time. It reads the time elapsed in seconds since the last rate accumulator update, and the current rate value stored to calculate the new increased value.

Rate accumulators are able to track the total fee owed by a Vault taking into account all the previous rate changes but the history of the rate changes themselves and the stability fees owed during the previous periods by the Vault are only available through event logs and cannot be retrieved from the smart contract.

### Tracking Balances

Maintaining a rate accumulator to accurately track a balance that increases over time requires frequent drip calls. The Maker protocol makes this process efficient by using a shared rate accumulator to track balances for all Vaults of the same collateral type.

This requires any user balance tied to a rate to be normalized before its stored in lieu of the actual balance. The actual balance at any point in time can be computed by multiplying a normalized balance with the current value of the shared rate accumulator.

Ex: A user deposits collateral and draws `100` dai in debt from a Vault and the rate accumulator of the collateral type currently has the value `1.00083`.

Dividing the actual balance 100 by current the value of the rate accumulator which gives us the result `99.917068832868719`. This is now stored as the normalized balance which will initialize the Vault debt with the principal amount. As the shared rate accumulator continues to increase when `drip` is executed in the future, the debt balance of this Vault will also increase.

Now that we've understood the rate mechanism used by the Maker protocol to maintain user balances that change over time based on a rate, we'll see what the rate mechanism is used for in both [Multi-Collateral Dai](https://github.com/makerdao/dss) and [Single Collateral Dai](https://github.com/makerdao/sai).

### Multi Collateral Dai

Rate mechanisms are used in Multi Collateral Dai (MCD) for maintaining stability fee balances of Vaults and the Dai Savings Rate (DSR) balances of users who've locked dai in the DSR contract.

#### Stability Fees

Vaults with outstanding debt are charged a stability fee by the Maker protocol. The accounting for stability fees: tracking rates, and rate accumulators for all collateral types, are done in the [Jug](https://github.com/makerdao/dss/blob/master/src/jug.sol) and [Vat](https://github.com/makerdao/dss/blob/master/src/vat.sol) contracts. All Vaults in the system are charged the [base](https://github.com/makerdao/dss/blob/17be7db1c663d8069308c6b78fa5c5f9d71134a3/src/jug.sol#L31) rate equally. Each collateral type is charged an additional [duty](https://github.com/makerdao/dss/blob/17be7db1c663d8069308c6b78fa5c5f9d71134a3/src/jug.sol#L24) rate which is called the risk premium. Both the rates `base` and `duty` are accumulated together in a single rate accumulator [rate](https://github.com/makerdao/dss/blob/17be7db1c663d8069308c6b78fa5c5f9d71134a3/src/vat.sol#L37) for each collateral type in the `Vat` contract when [drip](https://github.com/makerdao/dss/blob/17be7db1c663d8069308c6b78fa5c5f9d71134a3/src/jug.sol#L100) is executed for the collateral type.

The debt of a Vault can be calculated anytime by multiplying `art` which is the normalized debt value and `rate` of the collateral type, both stored in the Vat contract. Every time `drip` is executed it increases the value of the rate accumulator which results in additional debt recorded for all Vaults of the collateral type. The dai generated by increasing the debt of all Vaults is collected as surplus first in the [Vow](https://github.com/makerdao/dss/blob/master/src/vow.sol) contract which kicks off a [surplus auction](https://github.com/makerdao/dss/blob/17be7db1c663d8069308c6b78fa5c5f9d71134a3/src/vow.sol#L130) `flap` later once the surplus exceeds a certain threshold. The rate mechanism thus allows the system to continuously collect stability fees from Vaults every block.

Normalized debt values are also maintained for the [total debt](https://github.com/makerdao/dss/blob/17be7db1c663d8069308c6b78fa5c5f9d71134a3/src/vat.sol#L36) of a collateral type `Art` and multiplying it with the same rate accumulator `rate` of the collateral type will give the total debt issued.

#### Dai Savings Rate

MCD introduces a new mechanism which pays dai holders additional dai over time based on a rate called the Dai Savings Rate (DSR). This is a rate with no additional risk because the dai is not lent again to other users. Maker governance uses this rate to increase demand by making it attractive for users to purchase and hold dai.

The DSR contract [Pot](https://github.com/makerdao/dss/blob/master/src/pot.sol) uses the same rate mechanism with one variable to store the savings rate `dsr` and a rate accumulator `chi` to track the rewards that dai holders receive. Currently the savings rate is not natively integrated into the ERC20 DAI token. Ethereum external accounts or smart contracts have to execute a `join` transaction in Pot to earn the savings rate on their dai.

Normalized balances of users are stored in the `pie` variable and the real dai balance of users can be calculated by multiplying `pie` and `chi` anytime.

Rate accumulator `chi` value increases when `drip` function in the Pot contract is called which increases the balance of all locked dai holders. The Pot contract generates additional dai by recording bad debt first in Vow which will most likely get cancelled with surplus that is also being collected continuously as stability fees from Vaults.

The `join` function expects the caller to calculate and input the normalized balance instead of the amount of dai being deposited by the user. It also requires `drip` to be executed to ensure the current dai being deposited doesn't earn additional dai for past time before the actual deposit. These details are handled for you if the [join proxy script](https://github.com/makerdao/dss-proxy-actions/blob/7821a2329bd58f7d94a2de77d75f2371aa2d8342/src/DssProxyActions.sol#L866) is used instead of `join` directly. You can learn more about DSProxy and Proxy Scripts in the [Working with DSProxy](/devtools/working-with-dsproxy/working-with-dsproxy.md) guide.

### Single Collateral Dai

Single Collateral Dai (SCD) uses the rate mechanism for collecting stability fees from Collateralized Debt Position (CDP) owners. Technically there are two different rate mechanisms present in the [Tub](https://github.com/makerdao/sai/blob/master/src/tub.sol) contract to collect two types of fees from CDP owners: governance fee `fee` (sent to MKR holders), and stability fee `tax` (sent to PETH holders). Normalized debt units for `fee` and `tax` are `ire` and `art`, and their rate accumulators are `_rhi` and `_chi` respectively.

One operational fact that you have to consider is that only the governance fee `fee` is activated by Maker governance but it is colloquially referred to by everybody as the stability fee. The technical stability fee `tax` in the system has always been dormant with its rate set to `1` ray. We'll also refer to the governance fee as stability fee for the rest of this guide.

Stability fees are accounted for in dai but collected in MKR when a CDP owner pays back some of their debt at the price reported by the MKR/USD price feed. Some frontend interfaces have automated this MKR payment for users by integrating with decentralized exchange contracts to buy the necessary amount of MKR using DAI or ETH for the address before wiping debt from the CDP. This MKR is immediately sent to the burner contract [Pit](https://etherscan.io/token/0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2?a=0x69076e44a9c70a67d5b79d95795aba299083c275) which removes it from circulation. It can also be removed from total supply when Pit is authorized by the MKR token.

The `drip` call is added to functions that CDP owners execute periodically in SCD to update everyones' stability fees, while in MCD, Maker governance is responsible for executing drip periodically to update the stability fee owed by Vaults instead of Vault owners themselves.

PETH holders receive their compensation through liquidation penalties levied on unsafe CDPs which is a completely different mechanism.

## Troubleshooting

_Exponentiation calculation taking too long?_
Check for a missing decimal point in rate if your python script takes too long to perform the exponentiation calculation.

## Summary

In this guide we reviewed the general rate mechanism and how its used to track the Stability fee and the Dai Savings Rate in the Maker protocol.

## Help

- Contact Integrations team - integrate@makerdao.com
- Rocket chat - #dev channel


Learn about OasisDEX protocol and start trading

Intro to the OasisDEX Protocol


# Intro to the OasisDEX Protocol

**Level**: Beginner  
**Estimated Time**: 45 - 60 minutes

- [Intro to the OasisDEX Protocol](#intro-to-the-oasisdex-protocol)
  - [Overview](#overview)
  - [Learning Objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [OasisDEX Protocol](#oasisdex-protocol)
    - [**High Level Overview**](#high-level-overview)
    - [**Maker-OTC Contract Structure**](#maker-otc-contract-structure)
    - [**Making your first order**](#making-your-first-order)
      - [Approve OasisDEX in DAI & WETH](#approve-oasisdex-in-dai--weth)
      - [Reading the market](#reading-the-market)
      - [**Making a limit buy order**](#making-a-limit-buy-order)
    - [**Making a limit sell order**](#making-a-limit-sell-order)
    - [**Cherry-picking an offer from the order book**](#cherry-picking-an-offer-from-the-order-book)
    - [**Cancelling your order**](#cancelling-your-order)
  - [Summary](#summary)
  - [Troubleshooting](#troubleshooting)
  - [Resources](#resources)

This guide is based on the [Kovan deployed](https://kovan.etherscan.io/address/0xe325acB9765b02b8b418199bf9650972299235F4) [maker-otc contract](https://github.com/makerdao/maker-otc). This guide can also be used with the [mainnet deployment](https://etherscan.io/address/0x794e6e91555438aFc3ccF1c5076A74F42133d08D).

## Overview

The OasisDEX Protocol enables you to trade in a completely decentralised manner. The entire trading process does not require an operator and is non-custodial. Besides the [oasis.app/trade](https://oasis.app/trade) implementation by Maker Foundation, there are other third party Dapps using the OasisDEX protocol contracts, such as:

- <https://dydx.exchange/>
- <https://dex.ag/>
- <https://dexindex.io/>
- <https://forkoasisdex.com>
- <https://forkoasisdex.com/direct/>
- <https://kyberswap.com/swap>

This guide will introduce you to the structure of the maker-otc smart contract that powers the OasisDEX Protocol and show you how you can make trades through the command line.

## Learning Objectives

In this guide, you'll learn the basics of the OasisDEX protocol and trade ETH and DAI through the command line. In addition, this will give you an understanding on how to implement the function calls into your own app or custom smart contract.

## Pre-requisites

You'll need to know these concepts in order to continue with this guide:

- Solidity
- [Dapptools](https://github.com/dapphub/dapptools) - Dapp, Seth
- [What defines a Decentralised Exchange](https://hackernoon.com/the-world-of-decentralised-exchanges-on-the-ethereum-network-an-overview-ee25fc5f9f)
- [OTC Market](https://www.investopedia.com/terms/o/over-the-countermarket.asp)

## OasisDEX Protocol

_Before starting this guide please install [dapptools](https://dapp.tools/) and [setup seth](https://github.com/makerdao/developerguides/blob/master/devtools/seth/seth-guide-01/seth-guide-01.md) for use with the Kovan testnet._

### **High Level Overview**

The OasisDEX protocol uses an on-chain order book and a matching engine. The main advantage to this design is that liquidity is available for other smart contracts to access in one atomic transaction.

An order book for each market is implemented as two double-linked sorted lists, one list for each side of the market (buy and sell). An important feature of the design is that at any point in time, the lists should be sorted accordingly. The second most important design consideration when building the protocol was the use of an Escrow model for Makers. The Escrow model simply means that a given asset is locked within the contract when a new order is placed. Although such an approach locks down the liquidity, it guarantees a zero counterparty risk and instantaneous settlement.

### **Maker-OTC Contract Structure**

The trading engine involves the main contract [matching_market.sol](https://github.com/makerdao/maker-otc/blob/master/src/matching_market.sol) importing [simple_market.sol](https://github.com/makerdao/maker-otc/blob/master/src/simple_market.sol) and [expiring_market.sol](https://github.com/makerdao/maker-otc/blob/master/src/expiring_market.sol).

Through the matching_market.sol contract, you can make all the necessary calls to the maker-otc trading engine.

**Note:** It is recommended to make direct function calls to the maker-otc contract if you are intending to build other smart contracts that communicate with the maker-otc contract or build a trading bot. Example of this is the [dydx exchange](https://dydx.exchange/). However, if you’re integrating this maker-otc engine for wallets or UIs, then it is recommended to use the [Oasis Direct proxy contracts](https://github.com/makerdao/oasis-direct-proxy).

To find all the functions available for this contract, check the source code on [etherscan](https://kovan.etherscan.io/address/0xe325acB9765b02b8b418199bf9650972299235F4#code). Below is a list of the main functions you can use from this contract:

- **offer(pay_amt, pay_gem, buy_amt, buy_gem, pos)** - the main API of the matching engine. This method should be used 99% of the time!
  - uint pay_amt - the maker (ask) sell amount.
  - ERC20 pay_gem - the maker (ask) to sell specified collateral token (address).
  - uint buy_amt - the taker (ask) buy amount.
  - ERC20 buy_gem - the taker (ask) buy of a specified collateral token (address).
  - uint pos - the position to insert an offer.
- **getBestOffer(ERC20 sell_gem, ERC20 buy_gem)** - gets an offer from the top of the order book.
- **getWorseOffer()/getBetterOffer()** - these are both used for the navigation through an order book.
- **getOfferCount()** - returns the size of the order book.
- **getOffer(uint id)** - return information about the order with a given order ID.
- **buy()** - the buy function is used to fill a specific order (“cherrypicks”). By calling this function, it will execute and settle a trade all within one atomic transaction.
  - **Note**: Can be called externally by the user, and is also called internally by the matching engine (see offer() method for more details).
- **cancel()** - cancels an order with a given order ID.

### **Making your first order**

Before starting with the orders, let's setup the necessary env variables in your terminal. You'll need the main [maker-otc](https://kovan.etherscan.io/address/0xe325acB9765b02b8b418199bf9650972299235F4#code) (OASISDEX) contract address, the [DAI](https://kovan.etherscan.io/address/0x4F96Fe3b7A6Cf9725f59d353F723c1bDb64CA6Aa#code) token and the [WETH](https://kovan.etherscan.io/address/0xd0a1e359811322d97991e03f863a0c30c2cf029c#code) token address:

```bash
export OASIS=0xe325acB9765b02b8b418199bf9650972299235F4
export DAI=0x4F96Fe3b7A6Cf9725f59d353F723c1bDb64CA6Aa
export WETH=0xd0A1E359811322d97991E03f863a0C30C2cF029C
export ETH_GAS=3000000
```

#### Approve OasisDEX in DAI & WETH

Now we need to approve the OASISDEX contract to take funds from your wallet, DAI and WETH respectively. This is due to the fact of how OASISDEX is built, you need to allow the OASISDEX contract to take funds from your wallet in order to use the market functions (offer(), buy()...)

Let's define the amount we want to allow OASISDEX to withdraw. We'll set an equal amount for both tokens of 100,000. If you want to trade with higher units, just update the `$ALLOWANCE` to your preferred value.

```bash
export ALLOWANCE=$(seth --to-uint256 $(seth --to-wei 100000 eth))
```

To approve OASISDEX in DAI, execute the below command:

```bash
seth send $DAI 'approve(address,uint256)' $OASIS $ALLOWANCE
```

To approve OASISDEX in WETH, execute the below command:

```bash
seth send $WETH 'approve(address,uint256)' $OASIS $ALLOWANCE
```

#### Reading the market

In order to make an order on the market, you need to inform yourself of the current market prices. There are 2 ways to do this. One is to go to the [oasis.app/trade](https://oasis.app/trade) interface, make sure you're on Kovan, and see the order book. Or, call the OASISDEX contract functions to read the order book.

![order book](/images/guides/intro-to-oasis/order-book-1.png)

If reading from the interface, you can see the order book and the available orders in it. So, you can see that this order book has 3 bids and plenty of asks.

The best bid price to buy WETH is 100 DAI per WETH. The best ask price to buy DAI is 180 Dai per WETH. As seen from the figure, the market at 100 DAI and 180 DAI are very shallow, you can only buy 0.02609 WETH at 100 DAI and sell 0.1 WETH at 180 DAI.

Depending on the urgency of your order, you could fill these available orders or create a new order yourself and add it to the order book waiting for it to be filled.

Now, if you'd like to get the same information as from the interface, we need to read the OasisDEX contract directly.

Say we want to find the best offer on the WETH/DAI market, i.e. we want to purchase WETH with DAI and I want to know the best offer available. We can do this with the `getBestOffer(ERC20 sell_gem, ERC20 buy_gem)` function. This function returns you the best offer available on the order book for your specified market. The return value of this function is an id.

Let's get the id of the best offer of the WETH/DAI market. The command below gets the id of the best offer and converts it to a decimal number.

```bash
seth --to-dec $(seth call $OASIS 'getBestOffer(address,address)' $DAI $WETH)
```

Output: `3411`

**Note**: You will get a different order id, so make sure to change the parameters to the id from your terminal.

Now we can find more information about this order by using the getOffer(uint id) function. This function returns the pay and buy amount of each token respectively. Execute the below command to find order details of order `3411`:

```bash
seth call $OASIS 'getOffer(uint)(uint,address,uint,address)' 3411
```

Output:
`8ac7230489e80000` -> Pay amount in DAI
`4f96fe3b7a6cf9725f59d353f723c1bdb64ca6aa` -> DAI Token Address
`6345785d8a0000` -> Buy amount in WETH
`d0a1e359811322d97991e03f863a0c30c2cf029c` -> WETH Token Address

You can convert the hex outputs of DAI and WETH amounts to decimal:

```bash
seth --from-wei $(seth --to-dec 8ac7230489e80000)
seth --from-wei $(seth --to-dec 16345785d8a0000)
```

Reading from the above output, we can see that the best order offer is 10 DAI per 0.1 WETH. Meaning that you can buy 1 WETH at a price of 100 DAI (10/0.1 = 100) in this offer.

If you'd like to know the best offer for the WETH/DAI market, follow the above instructions but change the parameters in the getBestOffer() function. Instead of `getBestOffer(address,address) $DAI $WETH`, enter `getBestOffer(address,address) $WETH $DAI`.

#### **Making a limit buy order**

Now that you have the right information, you can start making an order. Say you want to buy WETH with DAI at a price of 177 WETH/DAI. Let's say, 15 DAI worth of WETH: `15/177 = 0.084745`. You'll make an order for `15 DAI for 0.084745 WETH`.

To make an order on OasisDEX, we need to call the offer() function.

Let's set the necessary parameters for the offer() function. Besides the pay and buy amounts that we need to define, we also need to add the pos parameter to the function. Position parameter is a number that represents an order id. We use this parameter to tell the trading engine where to place the order. If we know where our order should be placed, then we take the closest order id and use that as as a pos parameter.

In our case, we can set pos parameter to 3411. This way, the engine will know exactly where to place the offer. In addition, you can also set the pos parameter to 0. This will make the engine search the complete order book to find a position for your order. This leads to higher gas usage for your transaction, which could lead to a failed transaction. So, it is recommended to set a position yourself.

With seth, we need to convert our 15 Dai units to eth denomination, i.e. setting the number to 18 decimal points. Hence, you’ll see \$(seth --to-wei 15 eth).

```bash
export pay=$(seth --to-uint256 $(seth --to-wei 15 eth))
export buy=$(seth --to-uint256 $(seth --to-wei 0.084745 eth))
export pos=3411
```

Let's execute the offer function:

```bash
seth send $OASIS 'offer(uint,address,uint,address,uint)' $pay $DAI $buy $WETH $pos
```

We can see the order appear on the oasis.app interface:

![order display](/images/guides/intro-to-oasis/order.png)

However, as you can see, more than half of my order has been filled by the matching engine of Oasis. Now if we look at [etherscan's](https://kovan.etherscan.io/tx/0x21b7267d966f5cf64e684b18aed553d98c946250756a77841ce4232ab9d6f389) transaction overview:

![transaction on etherscan](/images/guides/intro-to-oasis/transaction.png)

(this example uses addresses from a previous deployment)

I can see that I've paid 8.83 DAI for 0.05 ETH, which means a price of 176.6 DAI (8.83/0.05=176.6). The rest of 6.14 DAI has been put in the order book waiting to be filled.

### **Making a limit sell order**

The limit sell order consists of selling WETH for DAI. We can do a sell order with the same offer() function as we did with buy order. Now, we just need to change the pay_amount and buy_amount parameters. Pay_amount is 0.05 WETH and buy_amount is 8.885 DAI, this leads to a price of 177.7 DAI/WETH (8.885/0.05 = 177.7).

Update the env variables:

```bash
export pay=$(seth --to-uint256 $(seth --to-wei 0.05 eth))
export buy=$(seth --to-uint256 $(seth --to-wei 8.885 eth))
export pos=1
```

Execute the below command to set a sell limit order:

```bash
seth send $OASIS 'offer(uint,address,uint,address,uint)' $pay $WETH $buy $DAI $pos
```

![sell order](/images/guides/intro-to-oasis/sell-order.png)

We can see that our order has appeared on the order book.

### **Cherry-picking an offer from the order book**

Making a limit order and letting the contract match you with existing orders as described above is the recommended way of trading on the OasisDEX contract. However, sometimes, you might find a specific offer in the order book that you would like to trade on. A good example is if you want to build a trading bot. When this is the case, you could use the buy(uint id, uint amount) function. The first parameter is the id of the offer, which you can get with getBestOffer() function, and the second parameter is the amount you'd like to buy.

Let's buy some DAI that is being sold at 177 DAI/WETH.
First, let's get the order id of this offer:

```bash
seth --to-dec $(seth call $OASIS 'getBestOffer(address,address)' $DAI $WETH)
```

Output: `3423`

Now, let's define the amount we want to buy. We can see that this order offers 15 Dai. Let's buy 8.885 DAI.

```bash
export buy=$(seth --to-uint256 $(seth --to-wei 8.885 eth))
```

After setting the parameters, now we can invoke the buy() function.

```bash
seth send $OASIS 'buy(uint,uint)' 3423 $buy
```

![transaction](/images/guides/intro-to-oasis/cherry-transaction.png)

![order](/images/guides/intro-to-oasis/cherry-order.png)

We can see from the above figures that we paid 0.0501 WETH for 8.885 DAI. As well, the order in the order book has decreased its offer accordingly.

### **Cancelling your order**

Cancelling your order can be executed by the cancel(uint id) function. So, if we want to cancel the 177 DAI/WETH offer we need the order id, which we already know from above (3423).

Execute bellow command to cancel order 3423

```bash
seth send $OASIS 'cancel(uint id)' 3423
```

If you look at the order book and your transaction on kovan.etherscan.io, you'll see that the remaining Dai was returned to you and the order has disappeared from the order book.

## Summary

In this guide we have introduced you to the OasisDEX Protocol (maker-otc contract) that is live on [oasis.app/trade](https://oasis.app/trade) marketplace. You have been shown commonly used functions within maker-otc contract, and we walked through examples by making some trades.

## Troubleshooting

If you have any questions, feel free to reach to our rocket chat channel at: <https://chat.makerdao.com/channel/dev>

## Resources

- [Maker-otc contract](https://kovan.etherscan.io/address/0x4a6bc4e803c62081ffebcc8d227b5a87a58f1f8f#code)
- [Maker-otc repo](https://github.com/makerdao/maker-otc)
- [Dapptools](https://github.com/dapphub/dapptools)
- [Setup seth](https://github.com/makerdao/developerguides/blob/master/devtools/seth/seth-guide-01/seth-guide-01.md)
- [Overview of Dexes](https://hackernoon.com/the-world-of-decentralised-exchanges-on-the-ethereum-network-an-overview-ee25fc5f9f)
- [What is OTC](https://www.investopedia.com/terms/o/over-the-countermarket.asp)



# Keepers

- [Keepers](#keepers)
  - [Prerequisites](#prerequisites)
  - [Maker Protocol Keepers](#maker-protocol-keepers)
    - [Auction Keeper](#auction-keeper)
    - [Dockerized Auction Keeper](#dockerized-auction-keeper)
    - [Chief Keeper](#chief-keeper)
    - [Cage Keeper](#cage-keeper)
    - [Pymaker](#pymaker)
  - [OasisDex Keepers](#oasisdex-keepers)
    - [Simple Arbitrage Keeper](#simple-arbitrage-keeper)
  - [Additional source code and developer docs](#additional-source-code-and-developer-docs)
  - [Need help](#need-help)

This document contains the necessary resources to implement Keepers.

## Prerequisites

This document assumes familiarity with Ethereum, and in-depth knowledge of the Maker Protocol.

## Maker Protocol Keepers

### [Auction Keeper](https://github.com/makerdao/auction-keeper)

The `auction-keeper` enables automatic interaction with flip auctions, flap auctions, and flop auctions. You can read more about the different auction types [here](/documentation/the-auctions-of-the-maker-protocol).

This is automated by specifying bidding models that define the decision making process, such as when to bid, how high to bid etc.

### [Dockerized Auction Keeper](https://github.com/makerdao/dockerized-auction-keeper)

The `dockerized-auction-keeper` contains a preconfigured `auction-keeper` that follows a simple  pricing model. With docker as the only prerequisite, this instance is well-suited for first-time auction keeper operators.

### [Chief Keeper](https://github.com/makerdao/chief-keeper)

The `chief-keeper` monitors and interacts with [DSChief](https://github.com/dapphub/ds-chief) and DSSSpells, which is the executive voting contract and a type of proposal object of the [Maker Protocol](https://github.com/makerdao/dss).

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

### [Cage Keeper](https://github.com/makerdao/cage-keeper)

The `cage-keeper` is used to help facilitate [Emergency Shutdown](/documentation/the-emergency-shutdown-process-for-multi-collateral-dai-mcd) of the [Maker Protocol](https://github.com/makerdao/dss).

### [Pymaker](https://github.com/makerdao/pymaker)

Pymaker is a Python API which provides endpoints to interact with the Maker Protocol smart contracts. It exposes most of the functionality of the Maker Protocol, but most importantly for this guide it can be used to create Keepers.

## OasisDex Keepers

### [Simple Arbitrage Keeper](https://github.com/makerdao/simple-arbitrage-keeper)

The Simple Arbitrage Keeper executes atomic multi-trade transactions between OasisDEX and Uniswap.

## Additional source code and developer docs

**Running a keeper node:**

- [Infrastructure required for an auction keeper (and most others)](https://github.com/makerdao/auction-keeper#infrastructure)

**Current Dai credit system implementation (Multi Collateral Dai):**

- Docs: [Developer Portal Documentation](/documentation)

- Source: [https://github.com/makerdao/dss](https://github.com/makerdao/dss)

**Single Collateral Dai:**

- Docs: [https://github.com/makerdao/sai/blob/master/DEVELOPING.md](https://github.com/makerdao/sai/blob/master/DEVELOPING.md)

- Source: [https://github.com/makerdao/sai](https://github.com/makerdao/sai)

**Python API:**

- Docs/source: [https://github.com/makerdao/pymaker](https://github.com/makerdao/pymaker)

**Maker platform in general:**

- [Whitepaper](https://makerdao.com/whitepaper/)

## Need help

- Rocket chat - [#dev](https://chat.makerdao.com/channel/dev) channel


Learn how to use mcd-cli to interact with the kovan deployment of MCD

How to use mcd-cli to interact with Kovan deployment of MCD


# How to use mcd-cli to interact with Kovan deployment of MCD

**This guide works under the [0.2.14 Release](https://changelog.makerdao.com/releases/0.2.14/index.html) of the system.**

- [How to use mcd-cli to interact with Kovan deployment of MCD](#how-to-use-mcd-cli-to-interact-with-kovan-deployment-of-mcd)
  - [Installing mcd-cli and seth](#installing-mcd-cli-and-seth)
    - [Setting up variables in seth](#setting-up-variables-in-seth)
  - [Acquiring test tokens](#acquiring-test-tokens)
    - [How to Get Kovan-ETH and K-Collateral Tokens](#how-to-get-kovan-eth-and-k-collateral-tokens)
      - [Getting Kovan ETH](#getting-kovan-eth)
      - [Getting Kovan Collateral Tokens](#getting-kovan-collateral-tokens)
  - [Vault Lifecycle Walkthrough](#vault-lifecycle-walkthrough)
    - [Instructions](#instructions)
  - [Using CDP Manager](#using-cdp-manager)
  - [Help](#help)
  - [Additional resources](#additional-resources)

This guide will show how to use the [mcd-cli](https://github.com/makerdao/mcd-cli) to interact with the Kovan deployment of the MCD smart contracts. The guide will showcase how to go through the following stages of the lifecycle of a Vault position:

- Opening Vault
- Depositing collateral tokens (REP, OMG, ZRX, BAT, DGD, GNT)
- Drawing Dai
- Paying back Dai
- Unlocking collateral

The command-line interface mcd-cli will enable you to easily interact with the Multi-Collateral Dai contracts. In the CLI, you can lock assets such as ETH and many other collateral tokens have been added (REP, OMG, ZRX, BAT, DGD, GNT)), draw Dai against them, check your Vault position, and much more.  

## Installing mcd-cli and seth

**The following link provides you with the necessary instructions to get started with the MCD CLI:**  [https://github.com/makerdao/mcd-cli](https://github.com/makerdao/mcd-cli)  

- First install  [dapp tools](https://dapp.tools/):

  `curl https://dapp.tools/install | sh`

- Then install the  `mcd`  package:

  `dapp pkg install mcd`

### Setting up variables in seth

Configuring Seth can be done with environment variables or command line options. Environment variables can be generally used in two ways: you can save them in a configuration file named `.sethrc` in specific locations, like your home folder, or just set them only for the current terminal session. In this guide you will use environment variables with the latter approach for simplicity’s sake, however for ease-of-use in the future, it is strongly encouraged to save the variables in your project folder. Follow [this example](https://github.com/dapphub/dapptools/tree/master/src/seth#example-sethrc-file) to do so.

Seth can connect to the Kovan Ethereum testnet through a default remote node provided by Infura, by specifying the `SETH_CHAIN` variable in a terminal or the `.sethrc` file:

`export SETH_CHAIN=kovan`

If you decide to create a new account, an easy method is using the "create new wallet" option in MEW: [https://www.myetherwallet.com/](https://www.myetherwallet.com/). It is also possible to use Parity or Geth to create a new account or you can use an existing keystore file for a Parity or Geth account. You are also going to need to save the password of your keystore file in a plain text file (Never use this keystore file for real ether - saving the password for your keystore file in plain text would be very unsafe for a real account! This also goes for the testnet account!).

Then you have to set up account variables:

```bash
export ETH_KEYSTORE=<path to your keystore folder>
export ETH_PASSWORD=<path and filename to the text file containing the password for your account e.g: /home/one1up/MakerDAO/415pass >
export ETH_FROM=<your ethereum account address>
export MCD_CHAIN=kovan
```

## Acquiring test tokens

To start using and interacting with the MCD contracts, you will need to get some Kovan ETH, REP, OMG, ZRX, BAT, DGD and MKR. Please note that MKR holders will eventually confirm the final collateral types through a proposed vote from the Maker Risk Team. Once you have the respective Kovan tokens, you can proceed to the guide below to go through the processes of a Vault lifecycle. This includes locking in some collateral, drawing Dai, paying back the Dai, and then unlocking the collateral.  

In the guide below, everything described above will be performed using the MCD-CLI.

### How to Get Kovan-ETH and K-Collateral Tokens

#### Getting Kovan ETH

There are many sources from which to get Kovan ETH, including:

- **Standard Faucet**  **Method:**  [https://faucet.kovan.network/](https://faucet.kovan.network/)
  - This method requires you to log in with your Github account. You then must paste your ETH address in the input box and request the funds.
- **Gitter Method:**  [https://gitter.im/kovan-testnet/faucet](https://gitter.im/kovan-testnet/faucet)
  - This method also requires you to log in with your GitHub or an existing Gitter account. To receive Kovan ETH through this method, join this Gitter Channel (which you also need to cover gas costs for use of the dApps):  [https://gitter.im/kovan-testnet/faucet](https://gitter.im/kovan-testnet/faucet). Once you join the Gitter Channel, post your ETH address from MetaMask to the main chat. The Kovan faucet will then populate your wallet with the test funds. This could take a couple minutes or a couple of hours, as it is done manually by the channel’s admin.

#### Getting Kovan Collateral Tokens

We have deployed a special faucet that allows you to withdraw testnet collateral tokens that essentially mimic the real tokens that exist on mainnet.  

**K-Collateral Token Faucet Address:** `0x94598157fcf0715c3bc9b4a35450cce82ac57b20`

**Note:**  You can call the  **gulp(address)**  function on it with  **seth**. The **address** parameter is the address of the REP to GNT collateral types we have added to this deployment.  

**Instructions:**  
In order to receive some REP tokens, you must run the following commands in the CLI:

**i. Setting the REP address to env variable:**

`export REP=0xc7aa227823789e363f29679f23f7e8f6d9904a9b`

**ii. Setting the Faucet address to env variable:**

`export FAUCET=0x94598157fcf0715c3bc9b4a35450cce82ac57b20`

**iii. Now, you can call the** **_gulp(address)_** **function:**

`seth send $FAUCET 'gulp(address)' $REP`

**iv. Please verify your REP balance by running:**

`seth --from-wei $(seth --to-dec $(seth call $REP 'balanceOf(address)' $ETH_FROM)) eth`  
or  
`mcd --ilk=REP-A gem balance ext`

**An example of the output you should be viewing when running the above command:**

`50.000000000000000000`

**That’s it! You now have some kovan REP tokens.**  

**Note:**  If you would like to receive some K-MKR tokens, you would need to replace the  **REP** token address with the  K-MKR  token address (0xaaf64bfcc32d0f15873a02163e7e500671a4ffcd) and follow the exact same process as above.
`export MKR=0xaaf64bfcc32d0f15873a02163e7e500671a4ffcd`

After you have successfully received the Kovan collateral tokens, you can continue on and explore the MCD-CLI.

## Vault Lifecycle Walkthrough

The following instructions will guide you through an example of a Vault's lifecycle. You will be creating a loan with the REP token and will then pay it back. Make sure you have set up the env variables outlined above in **Setting up variables in seth** since you will be using those in the following.

**Once set up, you can begin to run through the Vault lifecycle using the commands noted below.**  

For this example, you are going to use the REP token as the first type of collateral in our Vault. Before proceeding, please check that you have already received some REP from the faucet. If you haven’t, please visit the  **‘Getting K Collateral tokens’** section above.  

### Instructions

**1. Add the REP token into the REP adapter. Here, you must change the below value of ’40’ to your own value.**  

**Run:**  
`mcd --ilk=REP-A gem join 40`

**Output Example:**  

```bash
vat 40.000000000000000000 Unlocked collateral (REP)
ink 0.000000000000000000 Locked collateral (REP)
ext 0.000000000000000000 External account balance (REP))
```

----------

**2. Lock your REP collateral tokens and then draw 1 dai from VAT. Again, please don’t forget to change the below value of 40 to your own value.**  

**Run:**

`mcd --ilk=REP-A frob 40 1`

**Example Output:**  

```bash
ilk  REP-A                                      Collateral type
urn  0x16Fb96a5fa0427Af0C8F7cF1eB4870231c8154B6 Urn handler
ink  40.000000000000000000                      Locked collateral (REP)
art  1.000000000000000000                       Issued debt (Dai)
tab  1.000000000000000000000000000              Outstanding debt (Dai)
rap  0.000000000000000000000000000              Accumulated stability fee (Dai)
-->  329.39                                     Collateralization ratio

spot 8.234955555555555555555555555              REP price with safety mat (USD)
rate 1.000000000000000000000000000              REP DAI exchange rate
```

----------

**3. Withdraw Dai and send it to your ETH personal account.**  
**Run:**
`mcd dai exit 1`

**Example Output:**

```bash
vat 0.000000000000000000000000000000000000000000000 Vat Dai balance
ext 1.000000000000000000 ERC20 Dai balance
```

**Note:** When you want to pay back your debt and unlock your collateral, follow these steps again.  

----------
**4. Add your Dai back into the urn.**

**Run:**
`mcd dai join 1`  

**Example Output:**  

```bash
vat 1.000000000000000000000000000000000000000000000 Vat Dai balance
ext 0.000000000000000000 ERC20 Dai balance  
```

----------

**5. Remove your Dai debt and unlock your REP collateral from the internal system (vat).**  

**Run:**

`mcd --ilk=REP-A frob -- -40 -1`

**Example Output:**

```bash
ilk  REP-A                                      Collateral type
urn  0x16Fb96a5fa0427Af0C8F7cF1eB4870231c8154B6 Urn handler
ink  0.000000000000000000                       Locked collateral (REP)
art  0.000000000000000000                       Issued debt (Dai)
tab  0                                          Outstanding debt (Dai)
rap  0                                          Accumulated stability fee (Dai)
-->  0                                          Collateralization ratio

spot 8.234955555555555555555555555              REP price with safety mat (USD)
rate 1.000000000000000000000000000              REP DAI exchange rate
```

----------

**6. Finally, remove your collateral REP token from the REP adapter.**  

**Run:**

`mcd --ilk=REP-A gem exit 40`

**Example Output:**

```bash
vat 0.000000000000000000 Unlocked collateral (REP)
ink 0.000000000000000000 Locked collateral (REP)
ext 40.000000000000000000 External account balance (REP)
```

After running the above commands, please confirm that you have your initial collateral (REP) back in your wallet.

## Using CDP Manager

The `cdp` command provides compatibility with Vaults managed via the CDP Portal as it uses the same proxy contract. This allows Vaults to be managed via a unique integer identifier rather than the I, --ilk and U, --urn options.

To open a `REP-A` type Vault managed by the CDP Manager, execute the following command:

```bash
mcd --ilk=REP-A cdp open
```

Example output:

```bash
mcd-cdp-open: Waiting for transaction receipt....
0xae32e035d927cbb4d54eb0936808d66592b09f75cd11ce5a16df39b2d41a8bcc
Opened: cdp 109
```

In this case, the CDP id is `109`, so this will used as the example id in the following commands. You will have a different id, so you should substitute `109` with your cdp id.

To lock 30 REP tokens into the CDP, execute:

```bash
mcd --ilk=REP-A cdp 109 lock 30
```

Example output:

```bash
ilk  REP-A                                            Collateral type
urn  0x918E6BE35e2F6A91dEa7d1131B875Daa68C47b5F       Urn handler
ink  30.000000000000000000                            Locked collateral (REP)
art  0.000000000000000000                             Issued debt (Dai)
dai  0.000000000000000000000000000000000000000000000  Free Dai (in Vat)
tab  0                                                Outstanding debt (Dai)
rap  0                                                Accumulated stability fee (Dai)
-->  0                                                Collateralization ratio

spot 8.234955555555555555555555555                    REP price with safety mat (USD)
rate 1.002606904973849955810390711                    REP DAI exchange rate
```

To draw 1 Dai, execute:

```bash
mcd --ilk=REP-A cdp 109 draw 1
```

Example output:

```bash
ilk  REP-A                                            Collateral type
urn  0x918E6BE35e2F6A91dEa7d1131B875Daa68C47b5F       Urn handler
ink  30.000000000000000000                            Locked collateral (REP)
art  0.994825352635888385                             Issued debt (Dai)
dai  0.000000000000000000405995433304836217156675125  Free Dai (in Vat)
tab  0                                                Outstanding debt (Dai)
rap  0                                                Accumulated stability fee (Dai)
-->  0                                                Collateralization ratio

spot 8.234955555555555555555555555                    REP price with safety mat (USD)
rate 1.005201563621595362715670325                    REP DAI exchange rate
```

You have now succesfully drawn 1 Dai against your 30 REP collateral.
To pay back the Dai execute this command:

```bash
mcd --ilk=REP-A cdp 109 wipe 1
```

Example output:

```bash
ilk  REP-A                                            Collateral type
urn  0x918E6BE35e2F6A91dEa7d1131B875Daa68C47b5F       Urn handler
ink  30.000000000000000000                            Locked collateral (REP)
art  0.000000000000000000                             Issued debt (Dai)
dai  0.000000000000000000000000000000000000000000000  Free Dai (in Vat)
tab  0                                                Outstanding debt (Dai)
rap  0                                                Accumulated stability fee (Dai)
-->  0                                                Collateralization ratio

spot 8.234955555555555555555555555                    REP price with safety mat (USD)
rate 1.005201563621595362715670325                    REP DAI exchange rate
```

Execute the following command to retrieve the 30 REP tokens:

```bash
mcd --ilk=REP-A cdp 109 free 30
```

Example output:

```bash
ilk  REP-A                                            Collateral type
urn  0x918E6BE35e2F6A91dEa7d1131B875Daa68C47b5F       Urn handler
ink  0.000000000000000000                             Locked collateral (REP)
art  0.000000000000000000                             Issued debt (Dai)
dai  0.000000000000000000000000000000000000000000000  Free Dai (in Vat)
tab  0                                                Outstanding debt (Dai)
rap  0                                                Accumulated stability fee (Dai)
-->  0                                                Collateralization ratio

spot 8.234955555555555555555555555                    REP price with safety mat (USD)
rate 1.005201563621595362715670325                    REP DAI exchange rate
```

If your transaction went through, congratulations, you got back your 30 REP!
If the above command failed, it's because your debt has increased due to the stability fee. Therefore, try to lower the amount of REP you want to retrieve (i.e. 29.5: `$ mcd --ilk=REP-A cdp 109 free 30`), or if you have excess Dai, you can utilize the following command to pay down the full debt:

`mcd --ilk=REP-A cdp 109 wipe-all`

After this command have been executed, you should be able to free all the collateral.

For more commands, simply type `mcd cdp`

This concludes the Vault Lifecycle Walkthrough Guide!

## Help

- Rocket chat - [#dev](https://chat.makerdao.com/channel/dev) channel

## Additional resources

- [mcd-cli](https://github.com/makerdao/mcd-cli)
- [MCD 101](https://github.com/makerdao/developerguides/blob/master/mcd/mcd-101/mcd-101.md)
- Multi Collateral Dai source code: [https://github.com/makerdao/dss](https://github.com/makerdao/dss)
- Multi Colalteral Dai documentation: [https://github.com/makerdao/dss/blob/master/DEVELOPING.md](https://github.com/makerdao/dss/blob/master/DEVELOPING.md) & [https://github.com/makerdao/dss/wiki](https://github.com/makerdao/dss/wiki)
- [Whitepaper](https://makerdao.com/whitepaper/)


Use seth to interact with the Maker Protocol

Drawing Dai from the Kovan Maker Protocol deployment using Seth


# Drawing Dai from the Kovan Maker Protocol deployment using Seth

**This guide works under the Kovan [1.0.2 Release](https://changelog.makerdao.com/releases/kovan/1.0.2/index.html) of the system.**

- [Drawing Dai from the Kovan Maker Protocol deployment using Seth](#drawing-dai-from-the-kovan-maker-protocol-deployment-using-seth)
  - [Prerequisites](#prerequisites)
    - [Setting up Seth](#setting-up-seth)
    - [Other tools](#other-tools)
  - [Getting tokens](#getting-tokens)
  - [Saving contract addresses](#saving-contract-addresses)
  - [Token approval](#token-approval)
  - [Finally interacting with the Maker Protocol contracts](#finally-interacting-with-the-maker-protocol-contracts)
  - [Paying back DAI debt to release collateral](#paying-back-dai-debt-to-release-collateral)

**You can also use the Rinkey, Ropsten and Goerli deployments in this guide. Just make sure to change the contract addresses from the specific network.**

This tutorial will cover how to use the tool `seth` to deposit BAT tokens to draw DAI from the Kovan deployment of MCD as an example, since the process is the same for any other ERC-20 token. You can use the same methodology for any supported token in MCD, by changing the contract addresses to the specific token you want to use.

## Prerequisites

### Setting up Seth

For this guide, we are going to use the tool `seth`, to send transactions and interact with the Ethereum smart contracts.

[Use this guide to install and set up Seth](https://github.com/makerdao/developerguides/blob/master/devtools/seth/seth-guide-01/seth-guide-01.md).

**Note: Complete the above guide to setup your Seth environment variables and getting familiar with the tool before continuing. For this guide, we are using the Kovan Testnet. Ensure that Seth is configured to connect to Kovan by setting the network parameter accordingly in a terminal or config file:**

**If using other networks, make sure to change the `SETH_CHAIN` and `ETH_RPC_URL` variables to your preferred network**

`export SETH_CHAIN=kovan`

### Other tools

- [mcd-cli](https://github.com/makerdao/mcd-cli#installation)
- `bc` ([Arbitrary Precision Calculator](https://www.gnu.org/software/bc/))

## Getting tokens

Even though we are not using it as collateral, we will need Kovan ETH for gas. We can get some by following the guide here: [https://github.com/Kovan-testnet/faucet](https://github.com/kovan-testnet/faucet)

Next, we are going to need some test collateral tokens (BAT) on the Kovan network to draw DAI from them. Luckily, there is a faucet set up just for this. It gives the caller 50 BAT Kovan tokens.

We can only call the faucet once per account address, so if you mess something up in the future or you need more for any reason, you are going to need to create a new account. This is how we can call the faucet with seth:

**BAT ERC-20 token contract:**

`export BAT=0x9f8cFB61D3B2aF62864408DD703F9C3BEB55dff7`

**Token faucet on Kovan:**

`export FAUCET=0x57aAeAE905376a4B1899bA81364b4cE2519CBfB3`

Execute the following to receive test 50 BAT tokens:

`seth send $FAUCET 'gulp(address)' $BAT`

Let's check if we have received the tokens from the faucet. The following conversions are needed, because seth returns data in hexadecimal value, and the contract stores it in wei unit.

Execute:

`seth --from-wei $(seth --to-dec $(seth call $BAT 'balanceOf(address)' $ETH_FROM)) eth`

If everything went according to plan, the output should be this:

`50.000000000000000000`

Note: We will need more than 50 BAT to be able to open a Vault large enough to generate the 20 minimum DAI required. The faucet won't provide more than 50 BAT per address but you may create additional addresses to accumulate the 130-150 BAT necessary.

## Saving contract addresses

For better readability, we are going to save a bunch of contract addresses in variables belonging to the related smart contracts deployed to Kovan. In a terminal, carry out the following commands (in grey):

**Set the gas quantity**  
`export ETH_GAS=2000000`

**BAT ERC-20 token contract:**

`export BAT=0x9f8cFB61D3B2aF62864408DD703F9C3BEB55dff7`

**DAI ERC-20 token contract:**

`export DAI_TOKEN=0x4F96Fe3b7A6Cf9725f59d353F723c1bDb64CA6Aa`

**BAT-A token join adapter:**

`export MCD_JOIN_BAT_A=0x2a4C485B1B8dFb46acCfbeCaF75b6188A59dBd0a`

**Vat contract - Central state storage for MCD:**

`export MCD_VAT=0xbA987bDB501d131f766fEe8180Da5d81b34b69d9`

**DAI token join adapter:**

`export MCD_JOIN_DAI=0x5AA71a3ae1C0bd6ac27A1f28e1415fFFB6F15B8c`

**CDP Manager Contract:**

`export CDP_MANAGER=0x1476483dD8C35F25e568113C5f70249D3976ba21`

**MCD JUG Contract:**

`export MCD_JUG=0xcbB7718c9F39d05aEEDE1c472ca8Bf804b2f1EaD`

## Token approval

We do not transfer ERC-20 tokens manually to the MCD adapters - instead we give approval for the adapters to using some of our ERC-20 tokens. The following section will take us through the necessary steps.

In this example, we are going to use 150 BAT tokens to draw 20 DAI. You may of course use different amounts, just remember to change it accordingly in the function calls of this guide, while ensuring that you are within the accepted collateralization ratio of BAT Vault (150%) and the minimum vault debt (20 DAI). Let’s approve the use of 150 BAT tokens for the adapter, and then call the approve function of the BAT token contract with the right parameters. Again, we have to do some conversions, namely from `eth` unit to `wei`, then from decimal to hexadecimal (the `eth` keyword can be a bit confusing, but we are still dealing with BAT tokens. BAT has similar fraction values to ETH, so the keyword just means conversion to the whole token denomination):

`seth send $BAT 'approve(address,uint256)' $MCD_JOIN_BAT_A $(seth --to-uint256 $(seth --to-wei 150 eth))`

If we want to be sure that our approve transaction succeeded, we can check the results with this command:

`seth --from-wei $(seth --to-dec $(seth call $BAT 'allowance(address, address)' $ETH_FROM $MCD_JOIN_BAT_A)) eth`

Output:

`150.000000000000000000`

## Finally interacting with the Maker Protocol contracts

In order to better understand the MCD contracts, the following provides a brief explanation of relevant terms.

- `wad`: token unit amount
- `gem`: collateral token adapter
- `ilk`: Vault type
- `urn`: Vault record - keeps track of a Vault
- `ink`: rate \* wad represented in collateral
- `dink`: delta ink - a signed difference value to the current value
- `art`: rate \* wad represented in DAI
- `dart`: delta art - a signed difference value to the current value
- `lad`: Vault owner
- `rat`: collateralization ratio

After giving permission to the BAT adapter of MCD to take some of our tokens, it’s time to finally start using the MCD contracts.  
We'll be using the [CDP Manager](https://github.com/makerdao/dss-cdp-manager) as the preferred interface to interact with MCD contracts.

We begin by opening an empty Vault so we can use it to lock collateral into. For this we need to define the type of collateral (BAT-A) we want to lock in this Vault.  
`export ilk=$(seth --to-bytes32 $(seth --from-ascii "BAT-A"))`  
Now let's open the Vault  
`seth send $CDP_MANAGER 'open(bytes32,address)' $ilk $ETH_FROM`

We need the `cdpId` and `urn` address of our open Vault so we can interact with the system.

```bash
export cdpId=$(seth --to-dec $(seth call $CDP_MANAGER 'last(address)' $ETH_FROM))
export urn=$(seth call $CDP_MANAGER 'urns(uint)(address)' $cdpId)
```

After acquiring `cdpId` and `urn` address, we can move to the next step. Locking our tokens into the system.
First we are going to make a transaction to the BAT adapter to actually take 10 of our tokens with the join contract function.

The contract function looks like the following: `join(address urn, uint wad)`

- The first parameter is the `urn`, our vault address.
- The second parameter is the token amount in `wad`.

For the sake of readability, we up the `wadC` parameter representing the amount of collateral:

`export wadC=$(seth --to-uint256 $(seth --to-wei 150 eth))`

Then use the following command to use the join function, thus taking 150 BAT from our account and sending to `urn` address.

`seth send $MCD_JOIN_BAT_A "join(address, uint)" $urn $wadC`

We can check the results with the contract function: `gem(bytes32 ilk,address urn)(uint256)` with.

`seth --from-wei $(seth call $MCD_VAT 'gem(bytes32,address)(uint256)' $ilk $urn) eth`

The output should look like this:

`150.000000000000000000`

An optional, but recommended step is to invoke `jug.drip(ilk)` to make we are not paying undue stability fees. For more detail, please read the guide [Intro to the Rate mechanism](https://github.com/makerdao/developerguides/blob/master/mcd/intro-rate-mechanism/intro-rate-mechanism.md)

`seth send $MCD_JUG 'drip(bytes32)' $ilk`

The next step is adding the collateral into an urn. This is done through the `CDP Manager` contract.
The function is called `frob(uint256,uint256,uint256)`, which receives couple of parameters:

- `uint256 cdp` - the `cdpId`
- `int256 dink` - delta ink (collateral)
- `int256 dart` - delta art (Dai).

If the `frob` operation is successful, it will adjust the corresponding data in the protected `vat` module. When adding collateral to an `urn`, `dink` needs to be the (positive) amount we want to add and `dart` needs to be the (positive) amount of DAI we want to draw. Let’s add our 150 BAT to the urn, and draw 20 DAI ensuring that the position is overcollateralized.

We already set up `cdp` before, so we only need to set up `dink` (BAT deposit) and `dart` (DAI to be drawn):

```bash
dink=$(seth --to-uint256 $(seth --to-wei 150 eth))
rate=$(seth --to-fix 27 $(seth --to-dec $(seth call $MCD_VAT 'ilks(bytes32)(uint256,uint256,uint256,uint256,uint256)' $ilk | sed -n 2p)))
dart=$(seth --to-uint256 $(bc<<<"scale=18; art=(20/$rate*10^18+1); scale=0; art/1"))
```

- The `vat` is using an internal dai representation called "normalised art" that is useful to calculate accrued stability fees. To convert the Dai amount to normalized art, we have to divide it by the current ilk `rate`.

With the variables set, we can call `frob`:  
`seth send $CDP_MANAGER 'frob(uint256,int256,int256)' $cdpId $dink $dart`

Now, let's check out our internal DAI balance to see if we have succeeded. We are going to use the following `vat` function: `dai(address urn)(uint256)`:

`seth --to-fix 45 $(seth --to-dec $(seth call $MCD_VAT 'dai(address)(uint256)' $urn))`

The output should look like this (The result isn't exactly 20 Dai because of number precision):

`20.000000000000000000989957880534621130774523011`

Now this DAI is minted, but the balance is still technically owned by the DAI adapter of MCD. If we actually want to use it, we have to transfer it to our account:

```bash
export rad=$(seth --to-dec $(seth call $MCD_VAT 'dai(address)(uint256)' $urn))
seth send $CDP_MANAGER 'move(uint256,address,uint256)' $cdpId $ETH_FROM $(seth --to-uint256 $rad)
```

- Here, `rad`, is the total amount of DAI available in the `urn`. We are reading this number to get all the DAI possible.

We then permitting the Dai adapter to move Dai from VAT to our address:  
`seth send $MCD_VAT 'hope(address)' $MCD_JOIN_DAI`

An finally we exit the internal dai to the ERC-20 DAI:  
`seth send $MCD_JOIN_DAI "exit(address,uint256)" $ETH_FROM $(seth --to-uint256 $(seth --to-wei 20 eth))`

And to check the DAI balance of our account:

`seth --from-wei $(seth --to-dec $(seth call $DAI_TOKEN 'balanceOf(address)' $ETH_FROM)) eth`

Expected output:

`20.000000000000000000`

If everything checks out, congratulations: you have just acquired some multi-collateral DAI on Kovan!

## Paying back DAI debt to release collateral

To pay back your DAI and release the locked collateral, follow the following steps. Please make sure to obtain some additional Dai (from another account or from another vault) because chances are interest will have accumulated in the meantime. To force stability fee accumulation, anyone can invoke `jug.drip(ilk)`:

`seth send $MCD_JUG 'drip(bytes32)' $ilk`

First thing is to determine what is our debt, including the accrued stability fee:

```bash
art=$(seth --from-wei $(seth --to-dec $(seth call $MCD_VAT 'urns(bytes32,address)(uint256,uint256)' $ilk $urn | sed -n 2p)))
rate=$(seth --to-fix 27 $(seth --to-dec $(seth call $MCD_VAT 'ilks(bytes32)(uint256,uint256,uint256,uint256,uint256)' $ilk | sed -n 2p)))
debt=$(bc<<<"$art*$rate")
debtWadRound=$(seth --to-uint256 $(bc<<<"$art*$rate*10^18/1+1"))
```

- `art`: internal vault debt representation
- `rate`: accumulated stability fee from the system
- `debt`: vault debt in Dai
- `debtWadRound`: vault debt in wad (i.e. multiplied by 10^18), added by 1 wad to avoid rounding issues.

Then we need to approve the transfer of DAI tokens to the adapter. Call the approve function of the DAI ERC-20 token contract with the right parameters:

`seth send $DAI_TOKEN 'approve(address,uint256)' $MCD_JOIN_DAI $debtWadRound`

If we want to be sure that our approve transaction succeeded, we can check the results with this command:

`seth --from-wei $(seth --to-dec $(seth call $DAI_TOKEN 'allowance(address, address)' $ETH_FROM $MCD_JOIN_DAI)) eth`

Output:

`20.000000000000000001`

Now to actually join the Dai to the adapter:

`seth send $MCD_JOIN_DAI "join(address,uint)" $urn $debtWadRound`

To make sure it all worked:

`seth --to-fix 45 $(seth --to-dec $(seth call $MCD_VAT 'dai(address)(uint256)' $urn))`

Output:

`20.000000000000000001000000000000000000000000000`

Now, onto actually getting our collateral back. `dart` and `dink`, as the d in their abbreviation stands for delta, are inputs for changing a value, and thus they can be negative. When we want to lower the amount of DAI drawn from the `urn`, we lower the art parameter of the `urn`. Again, we need to use the `frob` operation to change these parameters: `frob(uint cdpId, address ETH_FROM, int dink, int dart)`

We only need to set up the `dink` and `dart` variables.

Using [mcd-cli](https://github.com/makerdao/mcd-cli#installation), we create our two negative `$dink` and `$dart`.

```bash
dink=$(seth --to-uint256 $(mcd --to-hex $(seth --to-wei -150 eth)))
dart=$(seth --to-uint256 $(mcd --to-hex -$(seth --to-wei $art eth)))
```

And execute:

`seth send $CDP_MANAGER "frob(uint256,int256,int256)" $cdpId $dink $dart`

This doesn’t mean we have already got back your tokens yet. Our account’s BAT balance is not yet back to the original amount:

`seth --from-wei $(seth --to-dec $(seth call $BAT 'balanceOf(address)' $ETH_FROM)) eth`

Output:

`0.000000000000000000`

The BAT is still assigned to the Vault, so we need to move them to our address:
`seth send $CDP_MANAGER 'flux(uint256,address,uint256)' $cdpId $ETH_FROM $wadC`

And from there exit the BAT adapter to get back our tokens:

`seth send $MCD_JOIN_BAT_A "exit(address, uint)" $ETH_FROM $wadC`

If we check the balance again:

`seth --from-wei $(seth --to-dec $(seth call $BAT 'balanceOf(address)' $ETH_FROM)) eth`

Output:

`150.000000000000000000`

Yay, you got back your tokens! If you have come this far, congratulations, you have finished paying back the debt of your Vault in Multi-Collateral Dai and getting back the collateral. Spend those freshly regained test BAT tokens wisely!


Learn how to monitor Maker Protocol State

Monitoring Collateral Types and Vaults


# Monitoring Collateral Types and Vaults

Level: Intermediate  
Estimated Time: 45 minutes

- [Monitoring Collateral Types and Vaults](#monitoring-collateral-types-and-vaults)
  - [Overview](#overview)
  - [Learning objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Guide](#guide)
    - [Collateral Types](#collateral-types)
      - [Example](#example)
    - [Vaults](#vaults)
      - [Example](#example-1)
  - [Summary](#summary)
  - [Troubleshooting](#troubleshooting)
  - [Next steps](#next-steps)
  - [Resources](#resources)

## Overview

Monitoring part of the Maker Protocol state is an important part of servicing users of the protocol, such as Vault owners. Proactive monitoring is recommended and has the potential to save Vault owners from liquidation and high stability fees. This guide will highlight the locations of relevant data as implemented in smart contract Solidity code, so it is up to the reader to choose which API is used to access that data. Some notable APIs are Dai.js and Pymaker; more generalized Web3 libraries can be used, though without the valuable utility functions that are exposed in the former two APIs. Moreover, because they abstract away much of the complexity of data transformation, we strongly recommend trying to work with [Dai.js](/documentation/introduction-to-dai-js) or [Pymaker](/documentation/introduction-to-dai-js) before attempting to read the state directly.

## Learning objectives

After going through this guide, you will gain a better understanding of:

- How to monitor the state and health of a particular Vault
- How to monitor relevant risk parameters

## Pre-requisites

[Maker Protocol 101](https://github.com/makerdao/developerguides/blob/master/mcd/mcd-101/mcd-101.md), especially:

- Vault basics.
- Governance Risk parameters.

## Guide

Mainnet addresses to contracts mentioned below can be found in the [latest release](https://changelog.makerdao.com/) of the Maker Protocol. To see the contract solidity code, go to etherscan.io, click on the `Contract` tab, and finally select the `Code` card. When reading numeric values, remember to account for their magnitudes. Of the fixed point integers:

- `wad` - 18 decimal places
- `ray` - 27 decimal places
- `rad` - 45 decimal places

### Collateral Types

Every [Collateral type](https://github.com/makerdao/developerguides/blob/kenton_dev/vault/vault-integration-guide/vault-integration-guide.md#collateral-types) state is stored in the `Ilk` data structure in the [Vat](https://github.com/makerdao/dss/blob/master/src/vat.sol), the central accounting contract of the Maker Protocol.

```solidity
struct Ilk {
    uint256 Art;   // Total Normalised Debt     [wad]
    uint256 rate;  // Accumulated Rates         [ray]
    uint256 spot;  // Price with Safety Margin  [ray]
    uint256 line;  // Debt Ceiling              [rad]
    uint256 dust;  // Urn Debt Floor            [rad]
}
```

The state of a particular `Ilk` can be found through the `ilks` mapping:

```solidity
mapping (bytes32 => Ilk)                       public ilks;
```

On the mapping, the first argument is a `bytes32` representation of the [collateral type](https://github.com/makerdao/developerguides/blob/kenton_dev/vault/vault-integration-guide/vault-integration-guide.md#collateral-types).
Once you can read the `Ilk` struct in the Vat, you have access to most of its risk parameters. The other important risk parameters, such as the stability fee, liquidation penalty, and liquidation ratio, can be found in similar `Ilk` structs in the [Jug](https://github.com/makerdao/dss/blob/master/src/jug.sol), [Cat](https://github.com/makerdao/dss/blob/master/src/cat.sol), and [Spot](https://github.com/makerdao/dss/blob/master/src/spot.sol) contracts, respectively. Similar to the Vat, each contract has their own `ilks` mapping.

In the Jug:

```solidity
struct Ilk {
    uint256 duty;  // Collateral-specific, per-second stability fee contribution [ray]
    uint256  rho;  // Time of last drip [unix epoch time]
}
```

In the Cat:

```solidity
struct Ilk {
    address flip;  // Liquidator
    uint256 chop;  // Liquidation Penalty   [ray]
    uint256 lump;  // Liquidation Quantity  [wad]
}
```

In the Spot:

```solidity
struct Ilk {
    PipLike pip;  // Price Feed
    uint256 mat;  // Liquidation ratio [ray]
}
```

#### Example

Here's a non-exhaustive example of reading common risk parameters of a collateral type within the Maker Protocol. Data location is shown in pseudocode and follows this format: `Contract.function(...).variable`.

```bash
Collateral Type = Ilk = bytes32(`ETH-A`) = 0x4554482d41000000000000000000000000000000000000000000000000000000
```

The Maker Protocol pulls recent price data from the [Oracle Security Module (OSM)](/documentation/osm-detailed-documentation) to properly value the assets it accepts as collateral. The sole purpose of the OSM is to delay price feed updates and protect the system from oracle attacks. Thus, the price used to evaluate a Vault’s state is delayed by a predetermined amount of time (e.g. 1 hour). Moreover, as was designed, the Liquidation Ratio, which is the minimum Vault Collateralization Ratio before liquidation, is baked into the price and stored in the Vat. As a result, the Collateral Price is delayed, has a “safety margin” that’s in size to the Liquidation Ratio, and is used directly when evaluating a Vault’s health.

```bash
Delayed Collateral Price price w/ safety margin = Vat.ilks(Ilk).spot = 150 x 10^27 ($150)

Liquidation Ratio = Spot.ilks(Ilk).mat = 1.50 x 10^27 (150%)

Delayed Collateral Price = Delayed Collateral Price w/ safety margin * Liquidation Ratio = 150 * 1.5 = 225 ETH / USD

Liquidation Penalty = Cat.ilks(Ilk).chop = 1.13 * 10^27 = 13%
```

All collateral types are charged a stability fee, which is the combination of two fee contributions: a collateral-specific fee and a global fee. The combination of the two results in a “debt multiplier” that when multiplied by a Vault’s normalized internal Dai (`urn.art`) gives the total amount of debt at any time. Each collateral type has a debt multiplier (`ilk.rate`) that continuously, but irregularly, updates in the Vat. This is one of the more important, fundamental mechanisms within the Maker Protocol, so if you have time, we recommend reading more on the [Rates Module](/documentation/introduction-to-rates-module).

```bash
Global, per-second stability fee contribution = Jug.base = 0.0000 x 10^27

Collateral-specific, per-second stability fee contribution  = Jug.ilks(Ilk).duty = 1.000000001847694957439350562 x 10^27
```

Although the total stability fee is the sum of the global and collateral specific fee, the latter (known as "duty") is currently the only contributing factor to the fee, as the global fee is set to 0.

```bash
Stability Fee per second = Global + Collateral-specific, per second stability fee contributions = 0.0000 x 10^27 + 1.000000001847694957439350562 x 10^27

Stability Fee per year = Stability Fee per second ^ 31536000 seconds in a year (365 days x 24 hours x 60 minutes x 60 seconds) = 1.06 or 6% per year
```

### Vaults

Similar to the Ilk, every Vault state is stored in the `Urn` data structure in the [Vat](https://github.com/makerdao/dss/blob/master/src/vat.sol).

```bash
struct Urn {
    uint256 ink;   // Locked Collateral  [wad]
    uint256 art;   // Normalised Debt    [wad]
}
```

Acting as an alias to Vault state, a particular `Urn` state can be found through the `urns` mapping:

```bash
mapping (bytes32 => mapping (address => Urn )) public urns;
```

On the mapping, the first argument is a `bytes32` representation of the [collateral type](https://github.com/makerdao/developerguides/blob/kenton_dev/vault/vault-integration-guide/vault-integration-guide.md#collateral-types), while the second argument is the user's Ethereum address.

You may notice that an Ethereum address only has access to a single `Urn` for each `Ilk` Collateral type. The CDP-Manager exists to circumvent this constraint. The [CDP-Manager](https://github.com/makerdao/dss-cdp-manager/blob/master/src/DssCdpManager.sol) manages a list of `UrnHandlers`, which is a simple contract that has a single goal of being owned by an Ethereum address and holds ownership of an `Urn`. In other words, with the CDP-Manager, one could own multiple `UrnHandlers` and thus `open(...)` multiple `urns` for each `Ilk`. Although CDP-Manager can be used manually, most interactions are conducted through a [DSProxy](https://github.com/makerdao/developerguides/blob/master/devtools/working-with-dsproxy/working-with-dsproxy.md), a proxy contract used to execute atomic transactions, and [DssProxyActions](https://github.com/makerdao/dss-cdp-manager), an atomic transaction library.

#### Example

Since it’s the most complex and more commonly used, the following example for reading the state of an `Urn` with a proxy identity is used; if the proxy identity owns multiple `urns` through the CDPManager, it will read the list through the [GetCDPs contract](https://github.com/makerdao/dss-cdp-manager/blob/master/src/GetCdps.sol). Data location is shown in pseudocode and follows this format: `Contract.function(...).variable`. Assuming that a DSProxy has already been built for a particular User Address:

```bash
UserAddress = ‘0x123ABC….’
DSProxyAddress = ProxyRegistry.proxies(UserAddress)

(CDPIDs, UrnHandlerAddresses, Ilks) = GetCDPs.getCdpsAsc(CDPManager, DSProxyAddress)

urn1 = Vat.urns(UrnHandlerAddresses[0],Ilks[0])
urn2 = Vat.urns(UrnHandlerAddresses[1],Ilks[1])
…

Collateral Debt Multiplier = Ilk.rate = 1.018 x 10^27

Normalized Internal Dai = urn1.art = 18.26 x 10^18

Locked Collateral = urn1.ink = 1 x 10^18

USD Debt = Normalized Internal Dai x Collateral Debt Multiplier = 18.26 x 1.018 = $18.58 (remember to normalize to a common unit)

USD Collateral = Locked Collateral x Delayed Collateral Price (from Ilk example) = 1 x 225 ETH / USD = $225 (remember to normalize to a common unit)

Collateralization Ratio = USD Collateral / USD Debt = $225 / $18.58 = 1210%
```

As supplemental education materials, here’s a [spreadsheet example](https://docs.google.com/spreadsheets/d/1fDwooo9tVftgd9Q7dVbd857Ue8demLVukFnsakl8MHE/edit?usp=sharing) as well as our [Intro to Rates Mechanism Guide](https://github.com/makerdao/developerguides/blob/master/mcd/intro-rate-mechanism/intro-rate-mechanism.md) showing how compounding rates are handled in the Maker Protocol; in addition to the [Rates Module documentation](/documentation/introduction-to-rates-module) we recommend their review when learning more about `Normalized Internal Dai` and the `Collateral Debt Multiplier`.

## Summary

In this guide, you were introduced to the locations of important data structures within the Maker Protocol, ranging from collateral types and their risk parameters to the state of Vaults.

## Troubleshooting

Run into an issue that’s not covered in this guide? Please find our contact information at the end of this guide, and we’ll add it above or to this section.

## Next steps

[Vault Integration Guide](https://github.com/makerdao/developerguides/blob/master/vault/vault-integration-guide/vault-integration-guide.md)

## Resources

[Rates Module Documentation](/documentation/introduction-to-rates-module)
[Guide: Intro to Rates Mechanism in the Maker Protocol](https://github.com/makerdao/developerguides/blob/master/mcd/intro-rate-mechanism/intro-rate-mechanism.md)
[Example: Compounding rates](https://docs.google.com/spreadsheets/d/1fDwooo9tVftgd9Q7dVbd857Ue8demLVukFnsakl8MHE/edit?usp=sharing)

Contact Integrations team - integrate@makerdao.com
Rocket chat - #dev channel


Learn about Oasis Direct Proxy and how it is used in OasisDEX Protocol

How to use Oasis Direct Proxy on OasisDEX Protocol


# How to use Oasis Direct Proxy on OasisDEX Protocol

**Level:** Intermediate  
**Estimated Time:** 30 minutes

- [How to use Oasis Direct Proxy on OasisDEX Protocol](#how-to-use-oasis-direct-proxy-on-oasisdex-protocol)
  - [Overview](#overview)
  - [Learning Objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Sections](#sections)
  - [Set up contract addresses in your terminal](#set-up-contract-addresses-in-your-terminal)
  - [Setting up or retrieve your proxy contract](#setting-up-or-retrieve-your-proxy-contract)
  - [Oasis Direct Proxy Functions](#oasis-direct-proxy-functions)
  - [Making a trade](#making-a-trade)
    - [Creating the calldata](#creating-the-calldata)
    - [Executing the function](#executing-the-function)
  - [Summary](#summary)
  - [Additional Resources](#additional-resources)
  - [Help](#help)

## Overview

Trading on decentralized marketplaces involves signing multiple transactions with your wallet. This leads to having higher chances of having failed transactions. Using a proxy simplifies this process by combining many transactions into one.

This guide will show you how to make trades on the OasisDEX Protocol through the [Oasis Direct Proxy](https://github.com/makerdao/oasis-direct-proxy). The Oasis Direct Proxy allows you to bundle together many function calls into a single transaction. So, when you have to trade some ERC-20 tokens, you will be able to do it all in one transaction.

This can be done through the DS-Proxy contract, which is a generic mechanism that allows for bundling transactions and having allowances setup once for different contracts, or by creating your own proxy contract that can interact with the Oasis Direct Proxy contract. Another example of a proxy contract is the one created by [https://instadapp.io/](https://instadapp.io/), which interacts with many services.

Using a proxy contract is beneficial for you as a user or as a developer that wants to build DApps. The most obvious use case is the front-end applications that interact with the protocol. A good example is the [oasis.app](https://oasis.app/) and the [Dai.js SDK](https://github.com/makerdao/dai.js).

## Learning Objectives

- Learn about the Oasis Direct Proxy functions
- Learn how to use the Oasis Direct Proxy on the OasisDEX Protocol

## Pre-requisites

- [Seth tools](https://github.com/dapphub/dapptools/tree/master/src/seth#installing) - command line tool to interact with the ethereum network
- [Understand how a DSProxy works](https://github.com/makerdao/developerguides/blob/master/devtools/working-with-dsproxy/working-with-dsproxy.md)
- [Understand the OasisDEX protocol](https://github.com/makerdao/developerguides/blob/master/Oasis/intro-to-oasis/intro-to-oasis-maker-otc.md)

## Sections

This guide will demonstrate how to use the Oasis Direct Proxy functions available on the GitHub repository [here](https://github.com/makerdao/oasis-direct-proxy). If you also want to learn the extra details of each function, please also read the README from the mentioned repository.

This guide works with the MCD Dai [0.2.17 Kovan Release](https://changelog.makerdao.com/releases/kovan/0.2.17/contracts.json). Here you will find all the necessary contract addresses.

## Set up contract addresses in your terminal

Export the below environmental variables in your terminal:

`export PROXY_REGISTRY=0x64a436ae831c1672ae81f674cab8b6775df3475c`
`export OASIS_DIRECT_PROXY=0xEE419971E63734Fed782Cfe49110b1544ae8a773`
`export WETH=0xd0a1e359811322d97991e03f863a0c30c2cf029c`
`export DAI=0x4f96fe3b7a6cf9725f59d353f723c1bdb64ca6aa`
`export OTC=0x4A6bC4e803c62081ffEbCc8d227B5a87a58f1F8F`
`export ETH_GAS=4000000`
`export ETH_GAS_PRICE=2500000000`

**Proxy Registry** - Is a map of proxy contracts and their owner addresses. Here you can check if you have a proxy

**Oasis Direct Proxy** - This is a contract with all the available functions that can be used to make a trade on the OasisDEX protocol.

**WETH** - Is the wrapped Ether contract that turns ETH into and ERC-20 compatible token.

**DAI** - Is the Multi-Collateral Dai token address from the [0.2.17 Kovan Deployment](https://changelog.makerdao.com/releases/kovan/0.2.17/contracts.json)

**OTC** - Is the OasisDEX protocol contract address

**ETH Gas** - Is the the gas limit

**ETH Gas Price** - Is the gas price

## Setting up or retrieve your proxy contract

There are many ways to interact with the Oasis Direct Proxy contract. You can:

- Directly call functions in the Oasis Direct Proxy
- Set up a proxy contract that would call functions on your behalf when interacting with the Oasis Direct contract

If you choose to interact directly with the Oasis Direct Proxy, then you’ll have to give allowance to this contract.  
If you choose to use DS-Proxy, then you give allowance only once and this contract can interact with any other proxy actions contract without having to give allowance again.

In this guide, we’ll use the DS-Proxy contract as your proxy that will interact with the Oasis Direct Proxy contract.

First you need to set up a DSProxy contract for your wallet. Or retrieve the address if you already have one.

Execute the command below to verify if you have a proxy contract:

`seth call $PROXY_REGISTRY 'proxies(address)(address)' $ETH_FROM`

If the output is an address (for instance `3704fa2f6234ad5f2da063121496003e999c5312`), then this address is your proxy contract. If you get an output like this: `0000000000000000000000000000000000000000` then you don’t have one.

In case you don’t have the proxy contract, you can set it up through the below command:

`seth send $PROXY_REGISTRY 'build()'`

Now to see your proxy contract address, execute the above command that verifies if you have a proxy address. After executing it. Store your proxy address in an env variable.

`export MYPROXY=$(seth call $PROXY_REGISTRY 'proxies(address)(address)' $ETH_FROM)`

## Oasis Direct Proxy Functions

These functions are used to make instant market orders on the marketplace. If you want to see a frontend example, check out the instant page on [oasis.app/trade/instant](https://oasis.app/trade/instant). If you want to make a simple limit order, then check the OasisDEX protocol [contract](https://github.com/makerdao/maker-otc).

The Oasis Direct Proxy covers 6 functions that you could use. These are:

- [sellAllAmount](https://github.com/makerdao/oasis-direct-proxy/blob/321f63bb33fb534c490e8c56680daeab10608bc1/src/OasisDirectProxy.sol#L27) - Triggering an ERC-20 for ERC-20 trade
- [sellAllAmountPayEth](https://github.com/makerdao/oasis-direct-proxy/blob/321f63bb33fb534c490e8c56680daeab10608bc1/src/OasisDirectProxy.sol#L36) - Triggering an ETH for ERC-20 token trade
- [sellAllAmountBuyEth](https://github.com/makerdao/oasis-direct-proxy/blob/321f63bb33fb534c490e8c56680daeab10608bc1/src/OasisDirectProxy.sol#L45) - Triggering an ERC-20 for ETH trade
- [buyAllAmount](https://github.com/makerdao/oasis-direct-proxy/blob/321f63bb33fb534c490e8c56680daeab10608bc1/src/OasisDirectProxy.sol#L54) - Triggering an ERC-20 for ERC-20 trade
- [buyAllAmountPayEth](https://github.com/makerdao/oasis-direct-proxy/blob/321f63bb33fb534c490e8c56680daeab10608bc1/src/OasisDirectProxy.sol#L65) - Triggering an ETH for ERC-20 token trade
- [buyAllAmountBuyEth](https://github.com/makerdao/oasis-direct-proxy/blob/321f63bb33fb534c490e8c56680daeab10608bc1/src/OasisDirectProxy.sol#L76) - Triggering an ERC-20 for ETH trade

If you want to understand each function in more detail, please do read the provided [README](https://github.com/makerdao/oasis-direct-proxy). For example, if you want to sell exactly 10 BAT for some amount of ETH, you can use sellAllAmountBuyEth(). If you want to sell at least 10 ZRX for some specified amount of DAI, you can use buyAllAmount() as you will be buying specific amount of DAI, paying for it with ZRX.

These functions will wrap/unwrap ETH (if necessary), check the on-chain liquidity (using getBuyAmount() and getPayAmount() OTC methods) and finally call OTC’s buyAllAmount/sellAllAmount() methods if the liquidity and price is within user’s supplied limits.

In addition, you will have to give allowance to the tokens you want to trade to the DS-Proxy contract in order for the trades to succeed. This is due to the majority of functions having a `pull` of funds method from your wallet in order to carry the trade.

So, in the case that you want to sell Dai or WETH, you will have to approve the tokens to DS-Proxy.  
Below is an example of how to do it:

**Approve Dai in MYPROXY:**

`seth send $DAI 'approve(address,uint256)' $MYPROXY $(seth --to-bytes32 $(mcd --to-hex -1))`

**Approve WETH in MYPROXY:**

`seth send $WETH 'approve(address,uint256)' $MYPROXY $(seth --to-bytes32 $(mcd --to-hex -1))`

With DS-Proxy you only have to approve the token contracts once in order to carry as many trades as you want. This is the benefit of using such contract.

## Making a trade

Note: Check the liquidity on the [marketplace](https://oasis.app/trade) on the Kovan network before doing any function calls. If there is no liquidity, then you will have failed transactions.

Let’s assume we want to buy exactly 3 Dai on the Oasis protocol. In order to process this trade, we can use the buyAllAmountPayEth function. In this function, we specify the exact amount of Dai we want to receive and send an approximate amount of ETH. Given that this function does not “pull” any tokens from your wallet, no additional token approval is necessary.

**buyAllAmountPayEth** function parameters are these:

- OasisDEX address (OTC)
- DAI token address (DAI)
- buyAmt (uint256) - the amount that will be purchased
- wethToken (address) - address of WETH token

### Creating the calldata

Before executing the function to the proxy contract, you need to build the calldata with the function name and all its parameters. You can export all this calldata to an environment variable in the terminal.

**Set the buyAmt parameter to 3 Dai:**

`export buyAmt=$(seth --to-uint256 $(seth --to-wei 3 eth))`

‘eth’ in the `seth --to-wei 3 eth` command refers to the ETH conversion unit. It adds 18 zeros to 3. Converting it to the wei format.

**Set the calldata:**

`export calldata=$(seth calldata 'buyAllAmountPayEth(address,address,uint,address)' $OTC $DAI $buyAmt $WETH)`

### Executing the function

To execute the **buyAllAmountPayEth** function, you need to send a transaction to your proxy contract by calling the execute function and adding the Oasis Direct Proxy contract address and calldata as parameters. Depending on the function, you might send ETH as well. In our case, you are sending 0.05 ETH to the contract for purchasing Dai.

`seth send $MYPROXY 'execute(address, bytes memory)' $OASIS_DIRECT_PROXY $calldata --value $(seth --to-wei 0.05 eth)`

[This](https://kovan.etherscan.io/tx/0xd24d388f61b86d3a726df99231d71fae94e0b7c711a43b5f963ada5ba73cba6b) is an example of a successful transaction.  
If you look closely, you’ll notice that that the user sent more ETH than was necessary to the marketplace. For getting 3 Dai he paid 0.037974683544303797 ETH and the rest was returned back to his wallet. This is special to this marketplace function. You define the exact number of Dai you want to receive. Depending on the market liquidity, you might spend more or less ETH for the Dai. So, in your case he bought Dai at the ~ 79 ETH/DAI price.

As you observed, all this has been done through one transaction on the Ethereum blockchain. This leads to improved UX, and less transactions.

So, in order to interact with the OasisDEX protocol through the Oasis Direct Proxy functions you need to have your proxy contract setup through the proxy registry and execute the specific calldata according to your requirements.

## Summary

In this guide you have learned how to use your proxy contract to execute Oasis Direct Proxy actions on the OasisDEX protocol. Using a proxy contract can be beneficial for both the users and developers by limiting the amount of needed transactions, which results in a more seamless UX.

## Additional Resources

- Make sure to read the Oasis Direct Proxy Actions github [repo](https://github.com/makerdao/oasis-direct-proxy), as it explains in detail every function call.
- [OasisDEX Protocol](https://github.com/makerdao/maker-otc)

## Help

- If you need help reach us at the #dev channel in [https://chat.makerdao.com/channel/dev](https://chat.makerdao.com/channel/dev)


Learn how to become a market maker in the OasisDEX protocol.

OasisDEX Market Maker Guide


# OasisDEX Market Maker Guide

**Level:** Intermediate  
**Estimated Time:** 20 minutes

- [OasisDEX Market Maker Guide](#oasisdex-market-maker-guide)
  - [Overview](#overview)
  - [Learning objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Market Makers](#market-makers)
    - [Web3 interface libraries](#web3-interface-libraries)
  - [Summary](#summary)
  - [Additional Resources](#additional-resources)

## Overview

Having strong liquidity is of paramount importance to any market. This applies to OasisDEX Protocol as well. As OasisDEX is a decentralized protocol, anyone can tap into it to exchange their assets and market make.  
Given the high gas price associated with the cost of cancelling orders, Market Makers sometimes place more than one order (with different prices) on each side of the order book. This way, when the market moves, they don't need to create new orders as they are already there. This strategy also increases the chances of a fill with a bigger spread if Taker brings significant trade to the market.

## Learning objectives

In this guide you will learn how to become a market maker in the OasisDEX protocol by understanding which functions to use in the OasisDEX smart contracts.

## Pre-requisites

You will need a [high level understanding of the OasisDEX Protocol](https://oasisdex.com/docs/guides/introduction#high-level-overview)

## Market Makers

A market maker is a type of user that adds liquidity to a market. They set buy and sell limit orders around a given market, with intention to sell assets higher than their purchase price. Their trades are not executed immediately, but rather their offers live on the order book until a market taker fills them.

The OasisDEX protocol uses a so-called escrow model for market makers. The escrow model simply means that a given asset is locked within the contract when a new order is placed. The asset remains under the sole control of the maker until it is filled. Although such an approach locks down the liquidity, it guarantees a zero counterparty risk and instantaneous settlement.

If Market Makers rely on their orders to be placed on the order book, they should make sure that the order is priced so that it does not fill some other orders.

There are two potential strategies: onchain and offchain. With the onchain strategy Market Maker might check the price of the best offer on both sides and set the price so that there is guarantee that the order will not cross. The offchain strategy is a little more complex as the market maker needs to check the current price offchain, and, when offer() is called, there is a risk that price will move and the offer will actually take order from other market maker. The on-chain strategy has additional advantage of potentially using gas tokens - with offchain market making bot this would need to be handled separately (i.e. gas tokens would need to be bought/sold in a different process).

- **offer()** - Through this function you set the offer for the tokens that you are willing to exchange.
- **cancel()** - Through this function you cancel any offer that you previously made.

**offer()** function structure:

```solidity
function offer(
        uint pay_amt,    //maker (ask) sell how much
        ERC20 pay_gem,   //maker (ask) sell which token
        uint buy_amt,    //maker (ask) buy how much
        ERC20 buy_gem,   //maker (ask) buy which token
        uint pos,        //position to insert offer, 0 should be used if unknown
        bool rounding    //match "close enough" orders?
    )
        public
        can_offer
        returns (uint)
    {
        require(!locked, "Reentrancy attempt");
        require(_dust[address(pay_gem)] <= pay_amt);

        if (matchingEnabled) {
          return _matcho(pay_amt, pay_gem, buy_amt, buy_gem, pos, rounding);
        }
        return super.offer(pay_amt, pay_gem, buy_amt, buy_gem);
    }
```

The first four parameters define:

- **pay_amt:** amount of tokens you are willing to sell
- **pay_gem:** token contract address of the token you are willing to sell
- **buy_amt:** amount of tokens you are willing to buy
- **buy_gem:** token contract address of the token you are willing to buy

The last two parameters define:

- **pos:** sets the position in the order book. Each order has an numbered ID, as an offeror, you can decide where to place your order in the order book. If you want your order automatically placed, set the pos value to 0.
- **rounding:** This parameter tells the matching engine to match your order with a close enough taker. By default this value is set to true. If you are willing to only accept your offer, then set the value to false.

**NOTE:** As of this writing, in the [current OasisDEX deployment](https://etherscan.io/address/0x794e6e91555438aFc3ccF1c5076A74F42133d08D#code), there are multiple `offer()` functions that only differ in the amount of parameters they take. **The recommended `offer()` function to call is the aforementioned one that has the additional `pos` parameter.**

**cancel()** function structure:

```solidity
    // Cancel an offer. Refunds offer maker.
    function cancel(uint id)
        public
        can_cancel(id)
        returns (bool success)
    {
        require(!locked, "Reentrancy attempt");
        if (matchingEnabled) {
            if (isOfferSorted(id)) {
                require(_unsort(id));
            } else {
                require(_hide(id));
            }
        }
        return super.cancel(id);    //delete the offer.
    }
```

The only parameter that this function takes, is the `id` parameter. The id is the identifier of an offer (order) in the order book.

Market Makers cancel orders to reuse liquidity when the market moves and maintain the spread. Since creating orders and cancelling is expensive, some market makers place many orders on each side of the order book so, when the market moves, the next order is already placed and there is no need for the market maker to constantly update the order book.

The ID parameter can be extracted from the set of events that are emitted when the `offer` function is submitted on the blockchain. [Here is an example of an offer transaction and its emitted events.](https://kovan.etherscan.io/tx/0xd7104df4a62b550b3708f31762645c240a64e9e914813458df3b26c9b0ae4839#eventlog)

### Web3 interface libraries

There are a number of web3 interface libraries specific for your technology stack that could help you interact with the OasisDEX protocol:

- Using JavaScript:
  - [https://web3js.readthedocs.io/en/v1.2.9/](https://web3js.readthedocs.io/en/v1.2.9/)
  - [https://docs.ethers.io/v5/](https://docs.ethers.io/v5/)
- Using Java
  - [https://github.com/web3j/web3j](https://github.com/web3j/web3j)
- Using Python
  - [https://web3py.readthedocs.io/en/stable/](https://web3py.readthedocs.io/en/stable/)
  - [Pymaker](https://github.com/makerdao/pymaker/blob/master/pymaker/oasis.py) - a library by Maker covering Maker Protocol contracts including OasisDEX
- .NET
  - [https://nethereum.com/](https://nethereum.com/)

## Summary

In this guide, you have learned how to integrate with OasisDEX protocol as a market maker by calling the above mentioned functions in the matching contracts.

## Additional Resources

- [Intro do OasisDEX protocol](https://oasisdex.com/docs/guides/introduction)
- [How to use Oasis Direct Proxy on OasisDEX protocol](https://oasisdex.com/docs/guides/use-proxy)


Learn how to become a market taker in the OasisDEX protocol.

OasisDEX Market Taker Guide


# OasisDEX Market Taker Guide

**Level:** Intermediate  
**Estimated Time:** 45 minutes

- [OasisDEX Market Taker Guide](#oasisdex-market-taker-guide)
  - [Overview](#overview)
  - [Learning Objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Guide](#guide)
  - [Current Deployment](#current-deployment)
  - [Fill or Kill orders](#fill-or-kill-orders)
  - [Support methods](#support-methods)
  - [Oasis Proxy Actions](#oasis-proxy-actions)
  - [Summary](#summary)

## Overview

There are many approaches to integrate the OasisDEX Protocol into your system. Each approach has pros and cons, varying levels of complexity, and different technical requirements. This guide is purposed to help streamline the integration experience for Market Takers, which include but are not limited to DEX Aggregators, Wallets, and Trading Bots.

## Learning Objectives

- Understand the role of a Market Taker
- Learn about ways to read the effective spot prices and orderbooks on OasisDEX
- Learn how to execute Fill-or-Kill orders on OasisDEX

## Pre-requisites

You will need a [high level understanding of the OasisDEX Protocol](https://oasisdex.com/docs/guides/introduction#high-level-overview)

## Guide

A market taker is a type of user that takes liquidity from a market. Their action to trade with the highest bid or lowest ask is a signal of their content with current asset price; in other words, they are willing to trade assets at the present levels and are wishing to fill an existing order. A market maker, the other type of market participant, is described in the OasisDEX Market Makers Integration Guide.

In this guide, you will learn how to read the state of the OasisDEX order book and publish transactions that fill orders with instant settlement. Let’s begin.

## Current Deployment

Note that anyone can launch their own deployment of the OasisDEX Protocol, which is available as open-source software. The below indicated deployments are the most popular ones at the time of publishing this guide. Make sure that you integrate with the right deployment.

```bash
Mainnet:

-   MatchingMarket - 0x794e6e91555438aFc3ccF1c5076A74F42133d08D
-   MakerOtcSupportMethods - 0x9b3F075b12513afe56Ca2ED838613B7395f57839
-   ProxyRegistry - 0x4678f0a6958e4D2Bc4F1BAF7Bc52E8F3564f3fE4
-   ProxyCreationandExecute - 0x793EbBe21607e4F04788F89c7a9b97320773Ec59

Kovan:

-   MatchingMarket - 0xe325acB9765b02b8b418199bf9650972299235F4
-   MakerOtcSupportMethods - 0x303f2bf24d98325479932881657f45567b3e47a8
-   ProxyRegistry - 0x64A436ae831C1672AE81F674CAb8B6775df3475C
-   ProxyCreationandExecute - 0xee419971e63734fed782cfe49110b1544ae8a773  
```

## Fill or Kill orders

The OasisDEX Protocol matching engine is fully on-chain. Therefore, the engine will atomically attempt to fill any orders that are sent through `offer()`. If, however, the offer cannot be completely filled, part of the fill attempt will be placed as a bid/ask offer on the OasisDEX orderbook. As a market taker, it is assumed that you want to completely fill or cancel the order; thus, we will be focusing exclusively on Fill-Or-Kill order types.

Fill or Kill order types:

- `function sellAllAmount(ERC20 pay_gem, uint  pay_amt, ERC20 buy_gem, uint  min_fill_amount)`
  - `pay_gem` - address of token to sell
  - `pay_amt` - uint, wad units (i.e. Wei units, 10^18)
  - `buy_gem` - address of token to purchase
  - `min_fill_amount` - uint, wad units (i.e. Wei units, 10^18)
  - attempts to spend all pay tokens to buy specified minimum buy tokens. More tokens may be bought if it is possible. So, for example, when buying 1 ETH for 300 DAI, all 300 DAI will be spent and possibly 1.034 ETH will be bought if the current market price is 290. Transaction reverts if more than 300 DAI would have to be spent to buy 1 ETH
- `function buyAllAmount(ERC20 buy_gem, uint  buy_amt, ERC20 pay_gem, uint  max_fill_amount)`
  - `buy_gem` - address of token to sell
  - `buy_amt` - uint, wad units (i.e. Wei units, 10^18)
  - `pay_gem` - address of token to purchase
  - `max_fill_amount` - uint, wad units (i.e. Wei units, 10^18)
  - attempts to buy a specified amount of buy tokens for a specified amount of pay tokens up to a certain price. So, for example, when buying 1 ETH for 300 DAI, possibly only 290 DAI will be spent if the current market price is 290. Transaction reverts if more than 300 DAI would have to be spent to buy 1 ETH, similarly to sellAllAmount().
- `function getBuyAmount(ERC20 buy_gem, ERC20 pay_gem, uint  pay_amt)`
  - `buy_gem` - address of token to sell
  - `pay_gem` - address of token to purchase
  - `pay_amt` - uint, wad units (i.e. Wei units, 10^18)
  - returns how much of `buy_gem` can be bought by paying `pay_amt` of `pay_gem` (effective spot price)
- `function getPayAmount(ERC20 pay_gem, ERC20 buy_gem, uint  buy_amt)`
  - `pay_gem` - address of token to purchase
  - `buy_gem` - address of token to sell
  - `buy_amt` - uint, wad units (i.e. Wei units, 10^18)
  - returns how much of `pay_gem` one needs to pay to buy `buy_amt` of `buy_gem` (effective spot price)

Before a Fill-Or-Kill order can be executed, the `msg.sender` or contract executing the subcall must gain awareness of the asset’s price. This will be used in conjunction with a prescribed slippage limit to define a minimum (`min_fill_amount`) or max amount (`max_fill_amount`) to be filled in the trade. The `getBuyAmount( )` and `getPayAmount( )` methods are used to capture the effective spot price of a trade. Since a lot could happen in the order books between publishing a transaction and its confirmation, one needs to set a guardrail to defend against slippage.

## Support methods

There are some integrators that wish to query the entire order book. For example, it could be a DEX front end that wishes to present the state of the orderbook on a UI or a DEX aggregator that wants to calculate the effective spot price off-chain. To support these needs, we offer [MakerOTCSupportMethods.sol](https://github.com/daifoundation/maker-otc-support-methods/blob/master/src/MakerOtcSupportMethods.sol), which is contract that exposes the following getter support method:

- `function getOffers(address otc, address payToken, address buyToken)`
  - `otc` - address of MatchingMarket contract
  - `payToken` - address of token to sell
  - `buyToken` - address of token to purchase
  - Returns the best 100 offers of a given pair

## Oasis Proxy Actions

Integrations that support DSProxies may achieve a few efficiencies, such as bundling order book reads with Fill-Or-Kill calls in single transactions. There exists an Oasis Proxy Action library that is used by some major front-ends. If you’re interested, we recommend going through the [Oasis Proxy Actions guide](https://oasisdex.com/docs/guides/use-proxy) before continuing.

Use of a Proxy Action library in conjunction with one’s DSProxy eliminates Fill-Or-Kill orders made with stale order book data, which could result in reverted transactions. Other advantages include deploying new proxies and executing Fill-or-Kill orders at once, as well as executing Fill-or-Kill orders and exiting into native ETH at once; without the last proxy action, users are required to submit an extra transaction that unwraps their WETH, which adds friction to the user experience and is slightly more gas intensive.

Although the aforementioned efficiencies are captured with the use of DSProxies, the management thereof needs to be considered in the evaluation of such an integration. More information can be found in the [Working with DSProxy Guide](https://github.com/makerdao/developerguides/blob/master/devtools/working-with-dsproxy/working-with-dsproxy.md).

Misc Comments / Reminders

- Remember to approve the OasisDEX / your DSProxy contract to move your tokens before interaction
- Advanced Market Takers (bots, etc) that are looking to save gas would be interested in [Cherry-picking offers from the order book](https://oasisdex.com/docs/guides/introduction#cherry-picking-an-offer-from-the-order-book).

Example Integrations (all w/o Oasis Proxy Actions, but still likely using a custom proxy library)

- Dydx.exchange
  - [Effective spot price read](https://github.com/dydxprotocol/exchange-wrappers/blob/master/contracts/exchange-wrappers/OasisV3MatchingExchangeWrapper.sol#L102)

```solidity
    function getExchangeCost(
        address makerToken,
        address takerToken,
        uint256 desiredMakerToken,
        bytes calldata orderData
    )
        external
        view
        returns (uint256)
    {
        IMatchingMarketV1 market = MATCHING_MARKET;

        // Must add 1 to the maker and taker amounts due to rounding differences in OasisDEX when
        // calling the "pay" functions vs the "buy" functions. This will lock some tokens in this
        // contract, but the value will be less than the sum of the smallest unit of each token.
        uint256 costInTakerToken = market.getPayAmount(
            takerToken,
            makerToken,
            desiredMakerToken.add(1)
        ).add(1);

        // validate results, exclusive to dydx (i.e. 128 bits to prevent overflow when checking bounds)

        requireBelowMaximumPrice(costInTakerToken, desiredMakerToken, orderData);

        return costInTakerToken;
    }
```

- [Fill-or-Kill order](https://github.com/dydxprotocol/exchange-wrappers/blob/master/contracts/exchange-wrappers/OasisV3MatchingExchangeWrapper.sol#L69)

```solidity
function exchange(
        address /*tradeOriginator*/,
        address receiver,
        address makerToken,
        address takerToken,
        uint256 requestedFillAmount,
        bytes calldata orderData
    )
        external
        returns (uint256)
    {
        IMatchingMarketV1 market = MATCHING_MARKET;

        // make sure that the exchange can take the tokens from this contract
        takerToken.ensureAllowance(address(market), requestedFillAmount);

        // do the exchange
        uint256 receivedMakerAmount = market.sellAllAmount(
            takerToken,
            requestedFillAmount,
            makerToken,
            0
        );

        // validate results
        requireBelowMaximumPrice(requestedFillAmount, receivedMakerAmount, orderData);

        // set allowance for the receiver
        makerToken.ensureAllowance(receiver, receivedMakerAmount);

        return receivedMakerAmount;
    }
```

- Instadapp.io - Note that Eth2Dai was a deprecated front end that supported OasisDEX
  - [Effective spot price read](https://github.com/InstaDApp/smart-contract/blob/master/contracts/ProxyLogics/SplitSwap/SplitSwap.sol#L206)
  - [Fill-or-Kill order](https://github.com/InstaDApp/smart-contract/blob/master/contracts/ProxyLogics/SplitSwap/SplitSwap.sol#L235)
- DeFiSaver
  - [Fill-or-Kill order](https://github.com/DecenterApps/defisaver-contracts/blob/a227c4ae19b9c4d47cac5cc1e1a5872bf3255309/contracts/exchange/wrappers/OasisTradeWrapper.sol#L20)

Other than through Solidity and Web3, as seen in the above integrations, here are other API libraries that can be used to interact with OasisDEX:

- [Pymaker](https://github.com/makerdao/pymaker/blob/master/pymaker/oasis.py)
- [Dai.js](/documentation/dai-js-exchange-service)

## Summary

In this guide, you have learned how to read the orderbook and execute Fill-or-Kill orders on the OasisDEX protocol.


Learn about seth command tool and interact with Maker Protocol

Introduction to Seth


# Introduction to Seth

**Level:** Intermediate  
**Estimated Time:** 30 - 45 min

- [Introduction to Seth](#introduction-to-seth)
  - [Overview](#overview)
  - [Getting started](#getting-started)
  - [Installation](#installation)
  - [Manual install](#manual-install)
    - [Errors and a note on macOSX Mojave](#errors-and-a-note-on-macosx-mojave)
    - [Errors and a note on macOSX Catalina](#errors-and-a-note-on-macosx-catalina)
  - [Set up and configuring variables](#set-up-and-configuring-variables)
    - [Using a local private network](#using-a-local-private-network)
    - [Using Kovan](#using-kovan)
  - [Seth operations](#seth-operations)
    - [seth balance - Checking ETH balance](#seth-balance---checking-eth-balance)
    - [seth send - Sending ETH](#seth-send---sending-eth)
    - [seth call - Reading contract storage](#seth-call---reading-contract-storage)
    - [Sending contract transaction with seth send](#sending-contract-transaction-with-seth-send)
    - [Using function parameters](#using-function-parameters)
    - [seth block - Retrieving block information](#seth-block---retrieving-block-information)
    - [seth estimate - Estimating gas cost of a transaction](#seth-estimate---estimating-gas-cost-of-a-transaction)
    - [seth receipt and seth tx](#seth-receipt-and-seth-tx)
  - [Additional Resources](#additional-resources)
  - [Known Issues](#known-issues)

## Overview

Seth is a simple, but powerful command line tool created to interface with the Ethereum blockchain. It is part of the [Dapp.Tools](https://dapp.tools/) toolset along with other tools for Ethereum. Its two main functionalities among others are performing calls (queries of the Ethereum blockchain - a “read” operation) and sending transactions (writing into the blockchain, changing its state). It also provides conversion between data of Ethereum’s own specific formats and the more widespread, usual data formats.

## Getting started

In the following section you will go through the installation and setup of Seth. These steps only work on Unix-based systems (i.e. Linux and macOS), however on Windows, you can try with an emulator, like [cmder](http://cmder.net/) or [cygwin](https://www.cygwin.com/), the [linux subsystem](https://docs.microsoft.com/en-us/windows/wsl/install-win10) in Windows 10, a virtual machine or a container.

## Installation

Seth can be installed as a part of the Dapp Tools suite, which is a collection of blockchain tools created with the Unix philosophy in mind. The most convenient way to do this, is to install Dapp Tools with the one line script provided on the [webpage](https://dapp.tools/). Here is how to do it:

From the Dapp Tools page:

> If you are running GNU/Linux or macOS you can take advantage of the all in one installer.

`$ curl https://dapp.tools/install | sh`

This script downloads the Nix package manager, setups binary cache with Cachix and installs the most used tools.

## Manual install

If you have issues using the script above, you can try the manual installation on the aforementioned website. A this point in time you can do a manual installation by running the following scripts:

    curl https://nixos.org/nix/install | sh

    . "$HOME/.nix-profile/etc/profile.d/nix.sh"

    nix-env -if https://github.com/cachix/cachix/tarball/master --substituters https://cachix.cachix.org --trusted-public-keys cachix.cachix.org-1:eWNHQldwUO7G2VkjpnjDbWwy4KQ/HNxht7H4SSoMckM=  

    cachix use dapp  

    git clone --recursive [https://github.com/dapphub/dapptools](https://github.com/dapphub/dapptools) $HOME/.dapp/dapptools  
    
    nix-env -f $HOME/.dapp/dapptools -iA dapp seth solc hevm ethsign

In order to test if the tools have been installed correctly, check the current version of Seth with the following command:

`$ seth --version`

If Seth has been installed correctly, the command should produce the following output:

`seth 0.7.0`

At the time of writing, seth 0.7.0 is thus the latest version, however in the future the output might have a different versioning number.

### Errors and a note on macOSX Mojave

If the above command does not work, or you had trouble installing it may be due to Mac OSX Mojave, as we have experienced various issues with the tools nix and cachix not working correctly on this OS, specifically due to a multi-user bug, you are more than welcome to ask for help on [chat.makerdao.com](https://chat.makerdao.com/) in the #help channel.

### Errors and a note on macOSX Catalina

Nix wouln't be able to be installed on the Catalina OS due to it being stricted to be installed on the maid disk. [This](https://github.com/NixOS/nix/issues/2925) issue guides you trough the process of getting around this error. Also, you can run [this](https://gist.github.com/charles-dyfis-net/22c4337d2b59a2ac4b3d8debced70d5c) script to help you install.

## Set up and configuring variables

Configuring Seth can be done with environment variables or command line options. Environment variables can be generally used in two ways: you can save them in a configuration file named .sethrc in specific locations, like your home folder, or just set them only for the current terminal session. In this guide you will use environment variables with the latter approach for simplicity’s sake, however for ease-of-use in the future, it is strongly encouraged to save the variables in your project folder. Follow [this example](https://github.com/dapphub/dapptools/tree/master/src/seth#example-sethrc-file) to do so.

### Using a local private network

You can quickly set up a local private network with the Dapp tool, which will also create accounts and their keystore files with empty strings for passwords by default. Setting up a local network can be handy when developing dapps for a quick an easy and way to deploy and test functionality without the need of acquiring test-net Ether for contract deployment.

Open a new terminal and execute the following command, and keep it running in the background during the tutorial:

`$ dapp testnet`

Copy your account address from the output.

Then in a separate terminal let’s create an empty password file:

`$ touch pass`

And let’s create your environment variables:

    export ETH_PASSWORD=$PWD/pass   
    export ETH_KEYSTORE=~/.dapp/testnet/8545/keystore   
    export ETH_FROM=<your ethereum account address>

### Using Kovan

Seth can connect to the Kovan Ethereum testnet through a default remote node provided by Infura. This is the most convenient way to do so. You can either create a new account or use the existing one created by the testnet. If you decide to use the existing one, you only need to change the chain parameter:

`$ export SETH_CHAIN=kovan`

If you decide to create a new account, an easy method is using the "create new wallet" option in MEW: [https://www.myetherwallet.com/](https://www.myetherwallet.com/). It is also possible to use Parity or Geth to create a new account or you can use an existing keystore file for a Parity or Geth account. You are also going to need to save the password of your keystore file in a plain text file (Never use this keystore file for real ETH - saving the password for your keystore file in plain text would be very unsafe for a real account! This also goes for the testnet account!).

Then you have to set up the same variables:

    export ETH_KEYSTORE=<path to your keystore folder>
    export ETH_PASSWORD=<path and filename to the text file containing the password for your account e.g: /home/one1up/MakerDAO/415pass >
    export ETH_FROM=<your ethereum account address> 
    export SETH_CHAIN=kovan

You will need Kovan ETH for gas, you can get some by following the guide here: [https://github.com/kovan-testnet/faucet](https://github.com/kovan-testnet/faucet)

## Seth operations

For the first two operations you can use either your own testnet or the Kovan testnet - try both if you want to!

### seth balance - Checking ETH balance

Checking ETH balances is pretty straight forward. It can be done with the balance subcommand, then specifying the address as a parameter:

`$ seth balance $ETH_FROM`

### seth send - Sending ETH

Let’s send Kovan or private net ETH to an address. You can choose any valid address - in this example I am going to use [Ethereum Foundation's donation address](https://www.ethereum.org/donate):

`$ seth send --value 0.1 0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359`

Upon execution you should see something like the following:

    seth-send: warning: `ETH_GAS' not set; using default gas amount
    seth-send: Published transaction with 0 bytes of calldata.
    seth-send: 0x000000…
    seth-send: Waiting for transaction receipt.......
    seth-send: Transaction included in block xxxxxx.

This indicates that the transaction was successful.

### seth call - Reading contract storage

Since you don't have any contracts deployed to your private network, **let's use Kovan from now on**. Let’s use one of the simplest contracts possible: an ERC-20 token contract. In this example, you are going to use a test collateral token (BAT). You can save its address in a variable with the following command:

`$ export BAT=0x9f8cfb61d3b2af62864408dd703f9c3beb55dff7`

You can read the output of a public function of a contract using the call subcommand, the contract’s address, and the name of the function.

Let's check out the number of decimals of this token:

`seth call $BAT 'decimals()'`

The output is:

`0x0000000000000000000000000000000000000000000000000000000000000012`

Now don't let this fool you. Seth queries contract data in a low level manner, and returns the value in hexadecimal, as it is represented in the contract, but you can convert it using:

`$ seth --to-dec $(seth call $BAT 'decimals()')`

The output is:

`18`

### Sending contract transaction with seth send

You can send a transaction to a contract with the same send command, by adding a couple of extra parameters. Just like with call, you need to specify the contract address and the function we are calling. Let’s get some COL1 tokens from a previously set up faucet:

`$ export FAUCET=0x94598157fcf0715c3bc9b4a35450cce82ac57b20`

`$ seth send $FAUCET ‘gulp(address)’ $BAT`

### Using function parameters

Now you can check your COL1 balance. This time you will need to present a parameter for the ‘balanceOf’ method of the ERC-20 contract. You can do this by first defining the type, the function takes in its parentheses, and then putting the input parameter after the method:

`$ seth --to-dec $(seth call $BAT 'balanceOf(address)' $ETH_FROM)`

The output is:

`500000000000000000000`

Now, that's a rather large value you got. The reason for this is that the contract stores the balances in wei unit (10^-18), which is why you have to convert it to get the actual number of BAT you own:

`$ seth --from-wei $(seth --to-dec $(seth call $BAT 'balanceOf(address)' $ETH_FROM)) eth`

The output is:

`50.000000000000000000`

### seth block - Retrieving block information

With seth block, you are capable of querying any information about an Ethereum block. Here is the usage from the help option `$ seth block --help`:

    Usage: seth block [-j|--json] <block> [<field>] 
    Print a table of information about <block>.
    If <field> is given, print only the value of that field.

Like any other Seth command, this command depends on Ethereum JSON RPC calls, which are part of the interface of any Ethereum client. You can dive into the corresponding documentation ([https://github.com/ethereum/wiki/wiki/JSON-RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC)) to learn more about it.

What can come in handy is the fact that in place of a block number, you can also use earliest, latest or pending. So if you would like to query the current block gas limit (I have tried this with seth configured for the kovan testnet) you can do the following:

`$ seth block latest gasLimit`

Output:

`8000000`

### seth estimate - Estimating gas cost of a transaction

`seth estimate` can give an estimation for the gas usage of a transaction. The syntax is pretty much the same as for `seth send`, but `seth estimate` will not actually send the transaction.

When you want to send a transaction to a contract function with Seth, you have to provide the function signature and the parameters in order after the signature. The ERC-20 transfer function signature looks like the following in Solidity:

`transfer(address _to, uint256 _value) public returns (bool success)`

The signature part that Seth needs from this is 'transfer(address, uint)'  and the parameters are the recipient address and the amount. The contract needs to receive the amount in hexadecimal representation of the number in wei unit, which is why we need those conversions.

Now, to estimate the gas usage of an ERC-20 token transfer let’s execute the following:

`$ seth estimate $BAT 'transfer(address, uint)' 0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359 $(seth --to-uint256 $(seth --to-wei 0.1 ether))`

Output:

`37240`

### seth receipt and seth tx

With seth receipt and seth tx, you can query every single detail imaginable about a transaction. They both take a transaction (tx) hash as an input parameter. The main difference between the two, is that the receipt, which contains the results of the transaction, is only constructed after the transaction gets mined, while the output of seth tx only contains the basic parameters of the transaction before it takes effect.

You can try them for example by first executing a transaction to have a transaction hash:

`$ seth send $BAT 'transfer(address, uint)' 0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359 $(seth --to-uint256 $(seth --to-wei 0.1 ether))`

Output:

    seth-send: Published transaction with 68 bytes of calldata.
    seth-send: 0x58ba3980775741aecaf8435646a003bff3395d7d4e00c8f7a32ad1fa0ce64e01
    seth-send: Waiting for transaction receipt....
    seth-send: Transaction included in block 9704345.

Now you can try the discussed commands (use your own tx hash from the previous tx):

`$ seth receipt 0x58ba3980775741aecaf8435646a003bff3395d7d4e00c8f7a32ad1fa0ce64e01`

`$ seth tx 0x58ba3980775741aecaf8435646a003bff3395d7d4e00c8f7a32ad1fa0ce64e01`

These both generate a pretty long output, but we can filter each query with an optional extra parameter. For example let's see, how accurate was your previous estimation for the gas consumption (it was perfectly accurate):

`$ seth receipt 0x58ba3980775741aecaf8435646a003bff3395d7d4e00c8f7a32ad1fa0ce64e01 gasUsed`

Output:  
`37240`

## Additional Resources

This guide was written based on the official documentation in the Github repository of Seth. You can find additional information over there: [https://github.com/dapphub/dapptools/tree/master/src/seth](https://github.com/dapphub/dapptools/tree/master/src/seth)

## Known Issues

- Issues with MacOS Mojave & Catalina


Learn how to run a simple arbitrage keeper

Simple Abitrage Keeper Guide



# Simple Arbitrage Keeper Guide

Level: Intermediate  
Estimated Time: 60 minutes

- [Simple Arbitrage Keeper Guide](#simple-arbitrage-keeper-guide)
  - [Overview](#overview)
  - [Learning objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Guide](#guide)
    - [Introduction to Arbitrage](#introduction-to-arbitrage)
    - [System Process Structure](#system-process-structure)
    - [Documentation](#documentation)
    - [Startup on Kovan](#startup-on-kovan)
      - [Keeper Installation](#keeper-installation)
      - [Install the DappHub Toolkit](#install-the-dapphub-toolkit)
      - [Keeper Ethereum Address](#keeper-ethereum-address)
      - [Deploy TxManager](#deploy-txmanager)
      - [Deploy/Find a parity node](#deployfind-a-parity-node)
      - [Uniswap Exchange Addresses](#uniswap-exchange-addresses)
      - [Shell Script](#shell-script)
      - [Initial Startup](#initial-startup)
      - [Nominal Operation](#nominal-operation)
  - [Troubleshooting](#troubleshooting)
  - [Next steps](#next-steps)
    - [Improvements](#improvements)
  - [Resources](#resources)

## Overview

Typically in the form of an automated bot, Keepers are external actors that participate in [market making](https://github.com/makerdao/market-maker-keeper), [auctions](https://github.com/makerdao/auction-keeper), [market arbitrage](https://github.com/makerdao/arbitrage-keeper), and system upkeep within the Maker protocol and the greater Ethereum ecosystem. Under a pure economic assumption, they are solely incentivized by profits or a vested interest. However, their activity provides indirect services such as increased liquidity and price consistency across various financial markets. This guide presents a simple arbitrage keeper, and structure thereof, that can be used out of the box to participate in markets. The purpose of the guide is to motivate the user in improving its functionality to participate in less volatile markets, leading to a more efficient financial ecosystem.

## Learning objectives

By reading this guide, you’ll gain:

- Better understanding of arbitrage, how it is achieved and the role it plays in financial markets
- An overview of the simple arbitrage keeper and common structure across the Maker Keeper framework
- Insight into the operation of the simple arbitrage keeper and ways to improve its code

## Pre-requisites

- At least Python 3.6.2 and some python experience
- Linux, macOS, or Cygwin (on Windows)
- Some general experience with Ethereum Development (account management, contract interaction, node hosting)

## Guide

### Introduction to Arbitrage

Arbitrage is the process of simultaneously purchasing an asset on one exchange and selling a similar, if not identical, asset on another exchange at a higher price. Conceptually, this trading strategy can be broken down into two legs, the first buying leg and the second selling leg. As the timestamp of these legs converge, the risk of asset exposure approaches zero. For example, if both trades are not executed in perfect synchrony, there is a chance that the second trade is completed by another actor, forcing the arbitrageur to hold an asset until another opportunity arises.

With advancement in technology, this trading strategy is typically automated and can detect, as well as, profit from price deviations in a matter or seconds. Arbitrage opportunities exist because of [market inefficiencies](https://www.investopedia.com/terms/i/inefficientmarket.asp), such as a temporary shortage of liquidity. As a result, arbitrage provides a mechanism to ensure prices on one exchange/market do not deviate far from the [fair value](https://www.investopedia.com/terms/f/fairvalue.asp). [1](https://www.investopedia.com/terms/a/arbitrage.asp)

### System Process Structure

![Alternate text][ref]

[ref]: /images/guides/keeperLifecycle.jpeg "Operation of the Simple Arbitrage Keeper"
Operation of the Simple Arbitrage Keeper

The [simple-arbitrage-keeper](https://github.com/makerdao/simple-arbitrage-keeper) is an arbitrage keeper for OasisDEX and Uniswap. Given a minimum profit per trade and maximum trade size, as defined by the user and in units of `entry_token`, the Keeper will scan for arbitrage opportunities. When running, it monitors the `arb_token/entry_token` price on both exchanges, and when a discrepancy is detected, it executes an atomic multi-step trade in a single Ethereum transaction.
The multi-step trade is made up of two legs: the first leg is the purchasing of `arb_token` with the `entry_token` on the `start_exchange`, while the second leg is the selling of the `arb_token` with the `entry_token` on the `end_exchange`. The type of `entry_token` and `arb_token` is typically of a stable and volatile type, respectively; since arbitrage opportunities can be scarce, the Keeper sometimes rests in a default state, holding the `entry_token` for extended periods of time as it looks for new opportunities. Exposure only to a stable token is especially important in this default state. If any leg of the trade fails, the entire trade reverts, thereby upholding the "risk-free" attribute of true arbitrage.

It inherits a system structure that is consistent with other keepers in the Maker Keeper Framework. Apart from libraries typical to python projects, it relies on [pymaker](https://github.com/makerdao/pymaker) and [pyexchange](https://github.com/makerdao/pyexchange), both of which are highly applicable Python APIs for the Maker Protocol Contracts and cryptocurrency exchanges, respectively.
As can be seen in the flowchart, the ‘Lifecycle box’ is a [pymaker utility class](https://github.com/makerdao/pymaker/blob/master/pymaker/lifecycle.py#L38) that helps define the proper life cycle of a keeper; it consists of keeper startup, timers and/or subscriptions to Web3 events, and a keeper shutdown phase. The ‘Process block’ box is executed when the Keeper's node receives a new block. It generally contains the logic to query the blockchain state, evaluate any profit opportunities, and when applicable, publish a transaction.

The step for each process in simple-arbitrage-keeper is as follows:

1. Keeper Entry -> enter into SimpleArbitrageKeeper class
2. Startup -> make all necessary approvals between tokens, exchanges, and tx-manager
3. Evaluate Market -> pull price data from Oasis REST API and Uniswap exchange contracts
4. Profitable Opportunity Found? ->check if profit opportunity exists with a given max engagement and min profit
5. Execute multi-step trade -> with use of TxManager, buy asset on exchange A and sell on exchange B within one Ethereum transaction

### Documentation

General high level information and comments for each class/method are in the [simple-arbitrage-keeper github repository](https://github.com/makerdao/simple-arbitrage-keeper).

### Startup on Kovan

The usage of the bot can be found in the [Usage section](https://github.com/makerdao/simple-arbitrage-keeper#usage) of the README. Here are some preparation steps in running on Kovan:

To operate the keeper, call the `/bin/simple-arbitrage-keeper` script with the required arguments. This adds the pyexchange and pymaker modules to the python path and initializes the SimpleArbitrageKeeper class. It's convenient to write a shell script that can be easily rerun after argument changes, but before you begin, let's prepare your Keeper ethereum address, deploy the TxManager, find the Uniswap exchange addresses and MatchingMarket address.

#### Keeper Installation

This project uses Python 3.6.2.
In order to clone the project and install required third-party packages please execute:

```bash
git clone https://github.com/makerdao/simple-arbitrage-keeper.git
cd simple-arbitrage-keeper
git submodule update --init --recursive
pip3 install -r requirements.txt
```

For some known Ubuntu and macOS issues see the [pymaker README](https://github.com/makerdao/pymaker).

#### Install the DappHub Toolkit

If you are running Linux or macOS you can take advantage of the all in one installer.

```bash
curl https://dapp.tools/install | sh
```

If you're having issues with installation, head over to the ['Manual Installation' section](http://dapp.tools/)

#### Keeper Ethereum Address

Your Keeper will publish transactions through this address. Your ethereum address needs to be accessible by [seth](https://github.com/dapphub/dapptools/tree/master/src/seth), in order to deploy TxManager through [dapp.tools](http://dapp.tools). Furthermore, when the Keeper is deployed and in operation, this address must contain some ETH for transaction costs as well as an amount of entry-tokens equal to the max-engagement set by the User. Follow [these instructions](https://github.com/dapphub/dapptools/tree/master/src/seth#key-management-and-signing) to ensure seth can see your keystore and passphrase files.

If you'd like to start from scratch, [install geth](https://github.com/ethereum/go-ethereum/wiki/Installation-Instructions-for-Mac) and use `geth account new`, to create a new account, set a passphrase, and place the passphrase into a `<address>.txt` file in the ``~/Library/Ethereum/passphrase/`` directory; the corresponding keystore file can be found in the ``~/Library/Ethereum/keystore/`` directory. Both the keystore and passphrase files will later be passed into the Keeper as an argument. Make a note of your Keeper Ethereum Address, its keystore file location and passphrase file location.

#### Deploy TxManager

A [TxManager](https://github.com/makerdao/tx-manager) must be deployed and linked with the Keeper ethereum address in order to bundle multiple contract calls in a single ethereum transaction; this is what is called an atomic transaction, where the entire call set is successful, or the state remains unaffected. Once the DappHub Toolkit is installed, execute the following commands to deploy TxManager:

```bash
git clone https://github.com/makerdao/tx-manager.git
cd tx-manager
dapp update
dapp --use solc:0.4.25 build --extract

export SETH_CHAIN=kovan
export ETH_FROM=<your Keeper Ethereum Address e.g. 0xABC>
export ETH_GAS=2000000
dapp create TxManager --password /path/to/passphraseOfAddress.txt

```

The output of `dapp create` is the address to your TxManager

#### Deploy/Find a parity node

You need access to a JSON-RPC host that’s connected to a parity node. Unfortunately, Infura APIs are not connected to parity nodes, so you will need to find access to a remote endpoint (one example is <https://rivet.cloud/> or run a node on your local machine. An example of a remote node could be <https://kovan.sampleparitynode.com:8545>

#### Uniswap Exchange Addresses

You'll need to find the address to the Uniswap exchange corresponding to the entry-token as well as arb-token. To do that, call the `getExchange(TokenAddress)` at the Uniswap Factory contract to query the exchange addresses. [You can do that here](https://kovan.etherscan.io/address/0xD3E51Ef092B2845f10401a0159B2B96e8B6c3D30#readContract). For example, you can use the Kovan WETH token address and call `getExchange(0xd0A1E359811322d97991E03f863a0C30C2cF029C)`

#### Shell Script

As was mentioned before, let's make a shell script so that it's easy to run this Bot. For example, you're using _Kovan Sai_ for the entry-token since you won't be exposed to the arb token's price exposure in between trades. Moreover, for kovan testing, you will be using the WETH/DAI pair, since liquidity is thin across the Kovan versions of MatchingMarket and Uniswap exchanges. Any `NoneType` errors are likely due to a lack of liquidity on either exchange and can be resolved once liquidity is added. As mentioned earlier, the min-profit and max-engagement arguments define how the keeper will operate. Maximum engagement refers to the amount of entry-tokens you would like to sell within the first leg of the trade, whereas minimum profit refers to the amount of profit gained from executing the arbitrage; both arguments are denominated in entry-tokens and in _units of ether_ (in the below script, 1 SAI of min-profit would be 1 SAI). For example, the below script will trade with a max-engagement of 10 SAI, but only if the returned value from the trade results in at least 11 SAI.

Create a file called like below, insert the arguments relevant to your environment, make it executable, then run it!

```bash
vim run-simple-keeper-kovan.sh
```

In your run-simple-keeper-kovan.sh file:

```bash
#!/bin/bash
/full/path/to/githubClone/simple-arbitrage-keeper/bin/simple-arbitrage-keeper \
 --rpc-host 'kovan.sampleparitynode.com' \
 --eth-from '0xABC' \
 --eth-key 'key_file=/path/to/keystore.file,pass_file=/path/to/passphrase.txt' \
 --uniswap-entry-exchange '0x47D4Af3BBaEC0dE4dba5F44ae8Ed2761977D32d6' \
 --uniswap-arb-exchange '0x1D79BcC198281C5F9B52bf24F671437BaDd3a688' \
 --oasis-address '0x4A6bC4e803c62081ffEbCc8d227B5a87a58f1F8F' \
 --oasis-api-endpoint 'https://kovan-api.oasisdex.com' \
 --tx-manager '0xABC' \
 --entry-token '0xC4375B7De8af5a38a93548eb8453a498222C4fF2' \
 --arb-token '0xd0A1E359811322d97991E03f863a0C30C2cF029C' \
 --arb-token-name 'WETH' \
 --min-profit 1 \
 --max-engagement 10 \
```

Make your Keeper executable, and run it!

```bash
chmod +x run-simple-keeper-kovan.sh
./run-simple-keeper-kovan.sh
```

#### Initial Startup

During the initial startup, several approval transactions will be sent to the tx-manager, and relevant exchanges. When complete, you'll see a “Watching for new blocks” message that indicates that the bot is now looping through the `lifecycle.process_block()` method; following that message and with every new block is a "Best Trade regardless of profit" message that acts as a "heartbeat" to the Keeper.

```bash
Kentons-Macbook:scripts kentonprescott$ ./run-simple-arbitrage-keeper-mainnet-XYZ-XYZ.sh
2019-10-19 17:21:57,463 INFO     Keeper connected to RPC connection https://...
2019-10-19 17:21:57,463 INFO     Keeper operating as 0xABCD
2019-10-19 17:21:58,523 INFO     Executing keeper startup logic
2019-10-19 17:22:04,820 INFO     Watching for new blocks
2019-10-19 17:22:13,983 INFO     Best trade regardless of profit/min-profit: -1.243077085275947008 DAI from Uniswap to Oasis
```

#### Nominal Operation

After the initial approval phase the Keeper's startup will look something like the below output and will continue to print "Best Trade ... " messages with every new block witnessed. When the keeper publishes a transaction, all relevant info will be logged and printed to the console. Finally, when you’d like to shut down the keeper, simply click CTRL-C, and it will gracefully shutdown.

## Troubleshooting

During keeper operation, if the following error is shown, just CTRL-C and rerun:

```bash
ValueError: {'code': -32010, 'message': 'Transaction with the same hash was already imported.'}
```

## Next steps

### Improvements

Here are some suggestions to improve the usability, versatility, and profitability of this keeper. The hope is that everyone tinkers with the parameters, runs the keeper for their own benefit, and eventually upgrades the bot to meet their risk tolerance and profit appetite.

- Develop unit tests for each method
- Use the Uniswap Factory contract to query the _uniswap-entry-exchange_ and _uniswap-arb-exchange_ addresses rather than requiring it as an argument
- Rather than the default gas price implement a [dynamic gas price strategy](https://github.com/makerdao/market-maker-keeper/blob/master/market_maker_keeper/gas.py#L24)
- Increase scope
  - Monitor more than one pair
  - Monitor more than two decentralized exchanges
  - Implement support for centralized exchanges
  - Increase number of intermediary arb tokens
    - (e.x. DAI → WETH → BAT → DAI)
    - <https://math.stackexchange.com/a/94420>
    - <https://www.dailycodingproblem.com/blog/how-to-find-arbitrage-opportunities-in-python/>
- Improve efficiency of TxManager
  - Is it really necessary to send all of the token balance to the contract during every atomic transaction?
- Read the state of the MatchingMarket (OasisDex) contract rather than using the Oasis REST API
  - To save gas, [get all active orders](https://github.com/makerdao/pymaker/blob/master/pymaker/oasis.py#L613) and [take specific orders](https://github.com/makerdao/pymaker/blob/master/pymaker/oasis.py#L428) by ID rather than use `MatchingMarket.offer(...)` and the on-chain matching engine
- Send trade updates through a text/email Python API

## Resources

- <https://github.com/makerdao/market-maker-keeper>
- <https://github.com/makerdao/arbitrage-keeper>
- <https://github.com/makerdao/tx-manager>
- <https://github.com/makerdao/pymaker>
- <https://github.com/makerdao/pyexchange>


Learn how to run a testchain with Maker Protocol

Test Chain Guide


# Test Chain Guide

**Level**: Intermediate  
**Estimated-Time**: 30 - 50 minutes

- [Test Chain Guide](#test-chain-guide)
  - [Overview](#overview)
  - [Learning Objectives](#learning-objectives)
  - [Pre-requisites](#pre-requisites)
  - [Sections](#sections)
  - [Note on Windows Subsystem for Linux](#note-on-windows-subsystem-for-linux)
  - [Benefits of using the test chain](#benefits-of-using-the-test-chain)
  - [Getting Started](#getting-started)
  - [Options](#options)
  - [Interacting with Maker Protocol contracts](#interacting-with-maker-protocol-contracts)
    - [Open a Vault with dai.js](#open-a-vault-with-daijs)
    - [Interact with contracts directly with seth](#interact-with-contracts-directly-with-seth)
      - [Opening a Vault](#opening-a-vault)
      - [Pay back Dai debt](#pay-back-dai-debt)
      - [Using the testchain faucet](#using-the-testchain-faucet)
      - [Changing collateral prices](#changing-collateral-prices)
  - [Summary](#summary)
  - [Troubleshooting](#troubleshooting)
  - [Next Steps](#next-steps)
  - [Resources](#resources)

## Overview

This guide is intended to give an introduction on how to use test chain. The test chain has all of the Maker Protocol's smart contracts deployed on it, so you as a developer can start building your dApps on top of the Maker Protocol. In addition, you can also use [dai.js](/documentation/introduction-to-dai-js) library with this test chain.

## Learning Objectives

Learn how to deploy and interact with the test chain for your development purposes.

## Pre-requisites

You can run the testchain on MacOS/Linux systems and also on the [Windows Subsystem For Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
You need to have [dapp.tools](https://dapp.tools/), [NodeJs](https://nodejs.org/en/), [jq](https://stedolan.github.io/jq/download/) and bash installed on your machine.

## Sections

- Note on Windows Subsystem for Linux
- Benefits of using the test chain
- Getting Started
- Options
- Interacting with Maker Protocol contracts
- Open a Vault with dai.js
- Use Maker Protocol contracts to draw some Dai with seth

## Note on Windows Subsystem for Linux

If you want to run this test chain on the Windows Subsystem for Linux, you’ll run into some issues when installing the [nix](https://dapp.tools/) package manager.

This [thread](https://github.com/NixOS/nix/issues/1203#issuecomment-275089112) has some solutions to the installation process. In summary, their solution is to create a file in `/etc/nix/nix.conf` and add these flags in the file:

```text
use-sqlite-wal = false
sandbox = false
```

Have a go and see if it works for you.

## Benefits of using the test chain

This test chain has the Maker Protocol smart contracts deployed on it. This is very convenient for you as a developer to interact or build smart contracts that interact with the Maker Protocol.
In addition, you have the convenience of tweaking your chain configurations to suit your needs, such as changing the block time or deploying your own set of smart contracts when instantiating the chain.

## Getting Started

In a terminal, execute the following commands.

To [download](https://github.com/makerdao/testchain) the repo to your machine execute:

```bash
git clone https://github.com/makerdao/testchain.git
cd testchain
```

Install all the necessary dependencies

```bash
npm install
or
yarn install
```

To launch the chain

```bash
scripts/launch -s default --fast
```

In your terminal, after some time you'll see this text:

```bash
Starting Ganache...
Skipping git submodule update.
Launched testchain in --- seconds.
Press Ctrl-C to stop the test chain.
```

If you see this, then congratulations, you have your test chain running on `http://127.0.0.1:2000`

## Options

You have some configuration options to run your test chain.
In order to add these options you need to add some flags `-- optionName` as a suffix to the start command.

For example:
If you want to run the test chain with verbose option, you run the bellow script:

This will show you the chain logs in the terminal

```bash
scripts/launch -s default --fast --verbose
```

Here you change your port and add verbose option

```bash
scripts/launch -s default --fast --verbose -p 2001
```

For more options check out this [repo](https://github.com/makerdao/testchain#options).

## Interacting with Maker Protocol contracts

You’ll find all the necessary Maker Protocol contract addresses in the `out/addresses-mcd.json` file in the testchain folder. You can use these addresses to develop your own tools that interact with Maker Protocol contracts. Use [dai.js](/documentation/introduction-to-dai-js) library or interact through the command line with [seth](https://dapp.tools/seth/). You will go be introduced to both of these methods now.

### Open a Vault with [dai.js](/documentation/introduction-to-dai-js)

To start from scratch:

- Start the testchain in another terminal, as you’ll be connecting to it when running the js file.
- In a directory of your choice, in another terminal, initiate an empty project with `npm init -y`
- Add the `@makerdao/dai` and the `@makerdao/dai-plugin-mcd` packages: `npm i --save @makerdao/dai @makerdao/dai-plugin-mcd`
- Create a `vault.js` file where you’ll write your script.
- Copy the below example in your js file
- Run the file with `node vault.js`

Below is an example that shows the process of opening a Vault in the Multi Collateral Dai system, locking some Eth and drawing some Dai:

```javascript
const Maker = require('@makerdao/dai');
const McdPlugin = require('@makerdao/dai-plugin-mcd').default;
const ETH = require('@makerdao/dai-plugin-mcd').ETH;
const MDAI = require('@makerdao/dai-plugin-mcd').MDAI;

async function start() {
  try {
    const maker = await Maker.create('test', {
      plugins: [
        [McdPlugin, {}]
      ]
    });
    await maker.authenticate();

    const balance = await maker
      .service('token')
      .getToken('ETH')
      .balance();
    console.log('Account: ', maker.currentAddress());
    console.log('Balance', balance.toString());

    const cdp = await maker
      .service('mcd:cdpManager')
      .openLockAndDraw('ETH-A', ETH(1), MDAI(20));

    console.log('Opened CDP #'+cdp.id);
    console.log('Collateral amount:'+cdp.collateralAmount.toString());
    console.log('Debt Value:'+cdp.debtValue.toString());

  } catch (error) {
    console.log('error', error);
  }
}

start();
```

If everything went according to plan, you should see an output like the one below:

```bash
Web3 is initializing...
Web3 is connecting...
Web3 version:  1.2.1
Web3 is authenticating...
Account:  0x16fb96a5fa0427af0c8f7cf1eb4870231c8154b6
Balance 70.85 ETH
Opened CDP #6
Collateral amount:1.00 ETH
Debt Value:20.00 MDAI
```

### Interact with contracts directly with [seth](https://dapp.tools/seth/)

In this example, you will draw Dai by depositing ETH into the MCD contracts that are deployed on the testchain. You will interact with the smart contracts directly, so there’s more steps involved.

As a prerequisite, you need to have the test chain running in a terminal with the `scripts/launch -s default --fast` command, if you haven’t done so already.  Note: If you see a message saying the testchain is already running on port 2000, you can kill it with `kill -9 $(lsof -t -i:2000)`

Next, go to another terminal window or tab. To start, you will need to set up and export some environmental variables in your second terminal. These variables will help you connect to the test chain and interact with the MCD system through seth.

Let’s add the variables that will set your account and connection with the test chain. In your second terminal tab, in your home location, add these variables:

```bash
export ETH_FROM=0x16fb96a5fa0427af0c8f7cf1eb4870231c8154b6
```

- Taken from `testchain/out/addresses-mcd.json` under `ETH_FROM`.  
You need to add this address because it is already filled with some ether for you by the test chain.

```bash
export ETH_RPC_URL=http://localhost:2000
```

- This sets the connection to the test chain.

You are using an account handled by the ethereum client, and as such you need to instruct `seth` not to use local keystores and instead use to use the RPC account to sign the transactions:

```bash
export ETH_RPC_ACCOUNTS=1
```

You can try to test your connection by seeing your account balance:

```bash
seth balance $ETH_FROM
```

If connection is right, you’ll see this (your values might differ):

```bash
94829630380000000000
```

Next, you can start adding the MCD contract addresses. You’ll find these addresses in the file `testchain/out/addresses-mcd.json`. Make sure to be in the testchain directory. The following command will parse the json file and store the addresses as environment variables:

```bash
eval $(jq -r 'to_entries|map("\(.key)=\(.value|tostring)")|.[]' out/addresses-mcd.json)
```

#### Opening a Vault

You will begin by setting a few useful variables:

```bash
export ilk=$(seth --to-bytes32 "$(seth --from-ascii "ETH-A")")
```

- `ilk` - a collateral type
- Setting the `ilk` variable to the `ETH` type of collateral and converting it to hex and bytes32 format.

You also set the gas limit for your transactions (with the default, certain transactions are likely to fail):

```bash
export ETH_GAS=1000000
```

First you open the Vault using the CDP Manager:

```bash
seth send -F $ETH_FROM $CDP_MANAGER 'open(bytes32,address)' "$ilk" "$ETH_FROM"
```

This call does not return anything useful, so you use these commands to determine the Id and urn address of the vault you just opened:

```bash
export cdpId=$(seth --to-dec $(seth call $CDP_MANAGER 'last(address)' $ETH_FROM))
export urn=$(seth call $CDP_MANAGER 'urns(uint)(address)' $cdpId)
echo $cdpId
echo $urn
```

Then you deposit 5 eth into the `WETH` adapter:

```bash
seth send $ETH 'deposit()' --value $(seth --to-wei 5 ETH)
```

And you approve `MCD_JOIN_ETH_A` to withdraw some `WETH`:

```bash
seth send $ETH 'approve(address,uint256)' $MCD_JOIN_ETH_A $(seth --to-uint256 $(seth --to-wei 5 ETH))
```

To finally lock the 5 ether into the ether adapter, to the benefit of our vault (urn):

```bash
seth send $MCD_JOIN_ETH_A 'join(address,uint256)' $urn $(seth --to-uint256 $(seth --to-wei 5 ETH))
```

As a validation, you can confirm that the collateral is available to our vault:

```bash
seth --from-wei $(seth --to-dec $(seth call $MCD_VAT 'gem(bytes32,address)(uint256)' $ilk $urn)) eth
```

At this point, the collateral is in `MCD_JOIN_ETH_A` and available for use in the vault, but isn't yet locked.

To prepare the locking of collateral, you set two variables with the amount of collateral that you will put in the Vault and the amount of Dai you will be generating:

```bash
export dink=$(seth --to-uint256 $(seth --to-hex $(seth --to-wei 5 eth)))
export dart=$(seth --to-uint256 $(seth --to-hex $(seth --to-wei 100 eth)))
```

- `dink` is delta ink - a signed difference value to the current value. This value is used in the frob function call to determine how much ink to lock in the Vat.
- `dart`  is delta art - a signed difference value to the current value. This value is used in the frob function call to determine how much art(debt) to mint in the Vat.

Finally, you can lock up collateral in the Vat and generate Dai. The parameters `$dink` and `$dart` that you defined earlier represent how much ether you want to lock in our ether Vault and how much Dai you want to generate, respectively. This being 5 ether and 100 Dai. You can deposit the ether and generate Dai all in one transaction, as shown below:

```bash
seth send $CDP_MANAGER 'frob(uint256,int256,int256)' $cdpId $dink $dart
```

Now you can check if you successfully generated your Dai in the Dai Adapter (output is in rad):

```bash
 seth call $MCD_VAT 'dai(address)(uint256)' $urn
```

And then move the internal Dai balance from the urn account to your account:

```bash
export rad=$(seth call $MCD_VAT 'dai(address)(uint256)' $urn)
seth send $CDP_MANAGER 'move(uint256,address,uint256)' $cdpId $ETH_FROM $(seth --to-uint256 $rad)
```

You need to approve the Dai adapter to withdraw the created Dai from the `urn`.

```bash
seth send $MCD_VAT 'hope(address)' $MCD_JOIN_DAI
```

Finally, you withdraw the Dai to your account. You need the `$wad` parameter that will define the amount of Dai you want to withdraw.

```bash
export wad=$(seth --to-uint256 $(seth --to-wei 100 eth))
seth send $MCD_JOIN_DAI "exit(address,uint256)" $ETH_FROM $wad
```

- `wad`  - some quantity of tokens

Checking the balance in the account:

```bash
seth --from-wei $(seth --to-dec $(seth call $MCD_DAI 'balanceOf(address)' $ETH_FROM)) eth
```

Output:

```bash
100.000000000000000000
```

Congratulations, you’ve successfully created an ETH Vault in the MCD system and drawn some fresh Dai.

#### Pay back Dai debt

If you want to pay back your Dai, follow the steps below.

Note: These steps assume that the DAI is paid before fees are accrued using `drip()`. If `drip()` is called, an extra amount of DAI must be paid back.

Approve `$MCD_JOIN_DAI` to withdraw `$wad` DAI (the amount you just generated) from `$MCD_DAI`

```bash
seth send $MCD_DAI 'approve(address,uint256)' $MCD_JOIN_DAI $wad
```

Add Dai back to the MCD_JOIN_DAI adapter.

```bash
seth send $MCD_JOIN_DAI 'join(address,uint256)' $urn $wad
```

Pay back your Dai debt and unlock your collateral. You do this with the same `$dink` `$dart` values and with the `$frob` function. But you change them into negative numbers instead. You do it this way:

Using [mcd-cli](https://github.com/makerdao/mcd-cli#installation), you create your two negative numbers:

```bash
export minus20hex=$(mcd --to-hex $(seth --to-wei -20 eth))
export minus5hex=$(mcd --to-hex $(seth --to-wei -5 eth))
```

Then, you set these negative numbers to `$dink` and `$dart`.

 ```bash
 export dink=$(seth --to-uint256 $minus5hex)
 export dart=$(seth --to-uint256 $minus20hex)
 ```

 Now you can call the `frob` function via the CDPManager to pay back Dai and unlock your collateral.

```bash
seth send $CDP_MANAGER "frob(uint256,int256,int256)" $cdpId $dink $dart
```

The collateral withdrawn by from is still in possession of the urn, so you have to move to your own account:

```bash
seth send $CDP_MANAGER 'flux(uint256,address,uint256)' $cdpId $ETH_FROM $(seth --to-uint256 $(seth --to-wei 5 eth))
```

Your ETH is in the `MCD_JOIN_ETH_A` adapter now, you need to call the exit function to withdraw them.

```bash
seth send $MCD_JOIN_ETH_A 'exit(address,uint)' $ETH_FROM $(seth --to-uint256 $(seth --to-wei 5 eth))
```

Finally, you just need to unwrap your ETH from the `$WETH` contract.

```bash
seth send $ETH 'withdraw(uint)' $(seth --to-uint256 $(seth --to-wei 5 eth))
```

You can check your account balance again and see that your ETH is back.

```bash
seth balance $ETH_FROM
```

#### Using the testchain faucet

If you want to create a Vault with other tokens, like `BAT`, you need to request some from the `FAUCET` contract. You'll find the `FAUCET` contract address in the `out/addresses-mcd.json` file.

Add the `FAUCET` address to the env variable:

```bash
export FAUCET=0x9783d28387f5097d72397388d98c52ca9b18dec8
```

Add the `BAT` address to the variable:

```bash
export BAT=0x927f29f213c691ace67cbc9fdb6ebbfd04d07ec4
```

Now, you can call the gulp(address) function:

```bash
seth send $FAUCET 'gulp(address)' $BAT
```

Verify your balance:

```bash
seth --from-wei $(seth --to-dec $(seth call $BAT 'balanceOf(address)' $ETH_FROM)) eth
```

Then you need to follow the same steps as above but change the `$ilk` to `BAT`  and interact with `$BAT` and `$MCD_JOIN_BAT_A` contracts.

#### Changing collateral prices

By running your own MCD instance, you have the liberty of changing the collateral prices. This can be useful to test liquidations.

`PIP_ETH` is a price oracle feed for the ETH price. In this case, you are providing the price feed information to the contract.

To read the current price:

```bash
seth --from-wei $(seth --to-dec $(seth call $PIP_ETH 'read()(uint256)'))
```

Setting the price feed:

```bash
seth send $PIP_ETH 'poke(bytes32)' $(seth --to-uint256 "$(seth --to-wei 151 ETH)")
```

The `MCD_SPOT` contract allows external actors to update the price feed in the Vat contract.
Setting the value of spot, which defines how much unit dai you can draw from unit collateral.

```bash
seth send "$MCD_SPOT" 'poke(bytes32)' "$ilk"
```

## Summary

In this guide, you have been introduced to Maker’s test chain and its benefits. You’ve learned how to deploy your own test chain with your preferred configuration options. You have interacted with the Maker system through the dai.js and seth tools by creating a Vault and drawing some Dai.

## Troubleshooting

Feel free to create an [issue](https://github.com/makerdao/testchain/issues) if you run into trouble.

## Next Steps

After you have deployed your test chain, you could go and discover your [integration examples](https://github.com/makerdao/integration-examples). Some of them will need to use this test chain that you just deployed. Feel free to poke around and do PRs with your own examples.
In addition, you can use this [repo](https://github.com/makerdao/dss-deploy) to deploy the MCD contracts to your own local test chain of choice.

## Resources

- <https://makerdao.com/documentation/>
- <https://docs.microsoft.com/en-us/windows/wsl/install-win10>
- <https://dapp.tools/>
- <https://nodejs.org>
- <https://github.com/NixOS/nix/issues/1203#issuecomment-275089112>
- <https://github.com/makerdao/testchain.git>
- <https://www.mycrypto.com/>
- <https://medium.com/makerdao/guide-vote-proxy-setup-with-seth-f62397a10c59>
- <https://github.com/makerdao/integration-examples>
- <https://github.com/makerdao/dss-deploy>
- <https://github.com/makerdao/mcd-cli>


Describes how contributors can edit content and create a pull request to the Developer Portal using TinaCMS.

TinaCMS Pull Request Workflow

# TinaCMS Pull Request Workflow

_This document describes how contributors can edit content and create a pull request to the Developer Portal using TinaCMS._

## Pull Request Workflow Steps

1. Click the "Edit this Site" button at the bottom of the page.

   1. Click "Continue to Github" to move to authorization.

      ![/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.34.19_PM.png](/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.34.19_PM.png)

   2. Enter your username and password

      ![/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.34.30_PM.png](/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.34.30_PM.png)

   3. Click "Create Fork" (this may take a minute or two)

      ![/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.36.07_PM.png](/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.36.07_PM.png)

   4. Notice your Github profile page will now have a fork of the developer portal

      ![/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.37.29_PM.png](/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.37.29_PM.png)

2. Switch branches using the TinaCMS menu bar

   1. You will see the menu bar appear at the top of your screen.

      ![/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.41.16_PM.png](/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.41.16_PM.png)

      1. Note the menu items may change based on which page you're on.

   2. Notice the "Fork" section should display your new forked repo.
   3. Click the "Branch" dropdown and click "New Branch"

      ![/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.46.41_PM.png](/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.46.41_PM.png)

      1. Give your branch a name and click "Create"

         ![/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.46.52_PM.png](/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.46.52_PM.png)

3. Make your changes to the site then click "Save" in the upper left corner to commit them.

   1. Notice the status indicator in the upper right will indicate "Unsaved Changes" enabling the "Save" button.

      ![/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.59.20_PM.png](/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_5.59.20_PM.png)

4. Make a pull request to the original branch

   1. Click the Pull Request button
   2. You will see the option to create a pull request opened on the main repo. Fill it out and click "Create Pull Request"

      ![/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_6.01.00_PM.png](/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_6.01.00_PM.png)

   3. You can now view the pull request on the main repo

      ![/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_6.02.10_PM.png](/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_6.02.10_PM.png)

5. Exit the TinaCMS editor

   1. Click the menu button on the upper right and exit

      ![/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_6.03.15_PM.png](/images/guides/tina-pr-workflow/Screen_Shot_2021-03-23_at_6.03.15_PM.png)

## Github Authorizations

Members of the DX team are authorized to commit to `master`.

Members of Makerdao org are authorized to create branches and commit to the branch on the main repo.

All other users must create a fork and a pull request.


This guide will focus on the Dai and CDP migration with a high level overview of the upgrade process for different actors in the Maker ecosystem.

Upgrading to Multi-Collateral Dai Guide

Learn how to setup voteproxy through an air gapped machine

VoteProxy Setup Air-gapped Machine


# VoteProxy Setup: Air-gapped Machine

**Level:** Intermediate  
**Estimated Time:** 60 minutes

- [VoteProxy Setup: Air-gapped Machine](#voteproxy-setup-air-gapped-machine)
  - [Overview](#overview)
  - [Learning objectives](#learning-objectives)
  - [Pre-requisites and Disclaimers](#pre-requisites-and-disclaimers)
  - [Sections](#sections)
    - [Configure geth](#configure-geth)
      - [Signing Process - example](#signing-process---example)
    - [Configure seth](#configure-seth)
    - [Initiate link](#initiate-link)
    - [Approve link](#approve-link)
    - [Approve MKR transfer](#approve-mkr-transfer)
    - [Lock MKR](#lock-mkr)
    - [Using this guide on Mainnet](#using-this-guide-on-mainnet)
  - [Summary](#summary)
  - [Additional Resources](#additional-resources)

## Overview

This guide describes one way to link an offline cold wallet to an online hot wallet for participating in MakerDAO governance by voting using the [Voting-Proxy contract](https://github.com/makerdao/vote-proxy) as described in this [article](https://blog.makerdao.com/the-makerdao-voting-proxy-contract/)

More specifically, it will show how to set up the cold-hot wallet link on your personal voting contract (VoteProxy) while your cold wallet resides on an air-gapped machine. To initiate the link, you will use [seth](https://github.com/dapphub/dapptools/tree/master/src/seth), a simple ethereum client tool in the [dapp.tools](https://dapp.tools/) collection, and geth, the go ethereum client. Geth on an air-gapped machine will be used to create and sign the transaction, but Seth on a hot machine will be used to prepare and publish the transaction. To approve the proxy link, approve MKR transfers, and lock up MKR, you will use [Etherscan](https://etherscan.io/) and [MyCrypto](https://www.mycrypto.com/). The reader needs their air-gapped machine provisioned with geth and access to their MetaMask hot wallet on another machine; it is suggested to store the cold wallet in a keystore file, accessible by geth. The following instructions work for GNU/Linux, macOS, and in a [Windows 10 bash shell](https://www.laptopmag.com/articles/use-bash-shell-windows-10).

## Learning objectives

In this guide, you will learn how to

- Set up the VoteProxy contract with an air-gapped machine
- Use geth to sign offline transactions for broadcasting

## Pre-requisites and Disclaimers

- It is assumed that you have correctly set up an air-gapped computer. Do not use these instructions if you have any concerns regarding the security of your machine.
- It is assumed that you broadcast signed transaction immediately after transaction fabrication. Especially near/after hard forks, it is suggested to research methods of replay protection if signed transactions are not immediately broadcasted. [EIP-155](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md) is a great starting point.

## Sections

### Configure geth

Download a standalone bundle of geth and transfer it to your air-gapped machine:
<https://github.com/ethereum/go-ethereum/wiki/Installing-Geth#download-standalone-bundle>

Confirm that your cold wallet is in a local keystore file.\
Let’s list which accounts are visible to geth.

```bash
geth account list
```

If your account is not listed, be sure to store the keystore and password file in geth’s default location, which is:

- `~/Library/Ethereum/keystore/<UTC...time.info…>--<yourPublicAddress>`
- `~/Library/Ethereum/passwords/<yourPublicAddress>.txt`

#### Signing Process - example

The following process will be employed when submitting transactions with the cold wallet. Here is a quick example of how one would approve another address for ERC20 token transfers. Note that one must include their information in every < > pair.

If geth is the only program on the air-gapped computer, then the user would need to painstakingly retype the function call data (`calldata`) and transaction hash (`tx.raw`) onto the air-gapped machine and hot machine, respectively. However, if the air-gapped computer is/can be safely provisioned with qrencode, then a QR code can be generated with the transaction hash and displayed through the CLI. With a QR code scanner, one could conveniently transfer the transaction hash to a hot machine.

1. Seth - create the data to be attached to the transaction (e.g. the method and the appropriate arguments being called). For example:

   ```bash
   seth calldata "approve(address,uint256)" <ERC20 Address> <ALLOWANCE>
   ```

   Output: `0xdaea85c50000000000000000000000008e2a84d6ade1e7fffee039a35ef5f19f13057152`

2. Geth (air-gapped machine) - from the geth console and with your unlocked wallet, create and sign a transaction with the calldata, which is shown as bytecode from seth’s output.

   ```bash
   geth --verbosity 0 --unlock <0x123ABC cold address> --password <~/path/to/passwordFile console>
   ```

   Consult <https://ethgasstation.info/> for current gas price information

   ```bash
   > var tx = eth.signTransaction({from:"<cold wallet address>", to:"<ERC20 Token Address>", gas: <gas>, gasPrice:<Wei per unit of gas>, nonce:<transaction number>, data:"<calldata output 0x12345>"}, "<cold wallet address>")
   > tx.raw
   ```

   Output: `0xf88...f1a8`

   Optional - generate a QR code and print it to the CLI

   ```bash
   echo "<tx.raw output 0x12345>" | tr -d '[:space:]' | qrencode -t ANSIUTF8
   ```

3. Seth - publish the signed transaction, which is shown as bytecode from geth’s output

   ```bash
   seth publish "<tx.raw output 0x12345>"
   ```

4. Optional - publish the QR code of the signed transaction hash through a Broadcasting tool, such as <https://etherscan.io/pushTx> or <https://www.mycrypto.com/pushTx>

### Configure seth

On another hot machine, install dapp.tools, which includes seth:

```bash
curl https://dapp.tools/install | sh
```

If install correctly, you will see:

```text
Installing dapptools ...

Installation finihsed!

You now have access to dapp, seth, solc, hevm, and ethsign.

Please open a new terminal to start using dapptools!
```

Remember to open a new terminal, as dapptools needs a fresh CLI restart.
For this tutorial, you will work with the Kovan testnet:

```bash
export SETH_CHAIN=kovan
```

### Initiate link

To initiate the link, you need to call `initateLink(hotAddress)` with our wallet on the air-gapped machine.
Make sure you have enough kovan ethereum on your cold wallet to cover gas costs. [You can get kovan ETH here](https://github.com/kovan-testnet/faucet).

Following the Signing Process outlined over in the Configure geth section

1. Seth - hot machine

   ```bash
   HOTADDRESS=<address of one of your MetaMask wallets>
   seth calldata "initiateLink(address)" $HOTADDRESS
   ```

2. Geth console - airgapped machine

   ```bash
   $ geth --verbosity 0 --unlock <0x123ABC cold address> --password ~/Library/Ethereum/passwords/<yourColdPublicAddress>.txt console
   > KPROXYFACTORY="0x3E08741A68c2d964d172793cD0Ad14292F658cd8"
   > GAS=75000
   > GASPRICE=10000000000
   > YOURADDRESS="<your cold wallet address>"
   > CALLDATA="<output from seth calldata>"
   > var tx = eth.signTransaction({from:YOURADDRESS, to:KPROXYFACTORY, gas:GAS, gasPrice:GASPRICE, nonce:1, data:CALLDATA},YOURADDRESS)
   > tx.raw
   ```

   Optional QR code generation (in another tab)

   ```bash
   echo "<tx.raw output 0x12345>" | tr -d '[:space:]' | qrencode -t ANSIUTF8
   ```

3. Seth - hot machine

   ```bash
   seth publish "<tx.raw output 0x12345>"
   ```

4. Optional - publish the QR code of the signed transaction hash through a Broadcasting tool, such as <https://etherscan.io/pushTx> or <https://www.mycrypto.com/pushTx>

### Approve link

To approve the link, you need to call `approveLink(coldAddress)` with our MetaMask wallet. To mitigate the risks in moving multiple private keys at once, you will use etherscan.io to call this smart contract function.

Now, let’s head over to the `Write Contract` tab under the Kovan etherscan Address page for the [VoteProxyFactory](https://kovan.etherscan.io/address/0x3e08741a68c2d964d172793cd0ad14292f658cd8#writeContract)

Select `Connect with MetaMask`:

![Etherscan](/images/guides/vote-proxy-setup-airgapped/voteproxyfactory.png)

Below, you’ll be able to select the `approveLink()` method.

After selection, include your cold wallet address in the argument field and submit the transaction with the default transaction settings and your MetaMask hot wallet.

If the transaction went through without any reverts, great! Your link is now approved. Next, let’s lock up some MKR to be used in Executive/Governance voting.

Note: Every cold-hot wallet link is one to one, meaning for any approved link, there is one unique cold wallet for another unique hot wallet. If you’d like to break a link, you could use either address to call the public `breakLink()` function in the VoteProxyFactory contract.

### Approve MKR transfer

Before you can lock up MKR, you need to approve our VoteProxy to make ERC20 Token (MKR) transfers. That way MKR can be pulled from the cold wallet and pushed to the voting contract (DSChief). Feel free to change the allowance to a value more appropriate for your case.

- Allowance: 100000 MKR
- Gas price: 10 Gwei
- Gas: 75000

The approve(address, uint256) method requires us to provide the amount argument in hex, denominated in WEI. Fortunately, seth has a number of simple conversion commands that will allow you to easily convert the amount in ether to wei and then to uint256:

```bash
$ seth --to-uint256 $(seth --to-wei 100000 ether)

00000000000000000000000000000000000000000000152d02c7e14af6800000
```

You’ll also need the address of your VoteProxy. This can be found via [kovan.etherscan.io](kovan.etherscan.io) and under the internal transactions tab of your previous transaction (the one used to approve the cold-hot link).

![ProxyContract](/images/guides/vote-proxy-setup-airgapped/proxycontract.png)

Let’s set up and approve the Voting Proxy contract that you made in the previous step.
If your cold wallet is locked, refer to the Configure Geth section when unlocking your account.

Following the Signing Process outlined over in the Configure geth section

1. Seth - hot machine

   ```bash
   ALLOWANCE=$(seth --to-uint256 $(seth --to-wei 100000 ether))
   KVOTEPROXY=< your VoteProxy address >
   seth calldata "approve(address,uint256)" $KVOTEPROXY $ALLOWANCE
   ```

2. Geth console - airgapped machine

   ```bash
   $ geth --verbosity 0 --unlock <0x123ABC cold address> --password ~/Library/Ethereum/passwords/<yourColdPublicAddress>.txt console
   > KMKR="0xAaF64BFCC32d0F15873a02163e7E500671a4ffcD"
   > GAS=75000
   > GASPRICE=10000000000
   > YOURADDRESS="<your cold wallet address>"
   > CALLDATA="<output from seth calldata>"
   > var tx = eth.signTransaction({from:YOURADDRESS, to:KMKR, gas:GAS, gasPrice:GASPRICE, nonce:2, data:CALLDATA},YOURADDRESS)
   > tx.raw
   ```

   Optional QR code generation (in another tab)

   ```bash
   echo "<tx.raw output 0x12345>" | tr -d '[:space:]' | qrencode -t ANSIUTF8
   ```

3. Seth - hot machine

   ```bash
   seth publish "<tx.raw output 0x12345>"
   ```

4. Optional - publish the QR code of the signed transaction hash through a Broadcasting tool, such as <https://etherscan.io/pushTx> or <https://www.mycrypto.com/pushTx>

### Lock MKR

With both the proxy link and MKR transfer approved, the hot wallet can be used to move MKR to and from DSChief. To call the `lock()` method on your VoteProxy contract, you will use MyCrypto, though the method can be called with your cold wallet as well. You are using MyCrypto instead of Etherscan because the former allows us to pass in your own ABI Interface sections on the fly. The lock method will pull MKR from your cold wallet and push it to DSChief. In this example, you will lock 5 MKR. Note that the MKR amount has to be represented in units of WEI.

<https://www.mycrypto.com/contracts/interact>

![LockMKR](/images/guides/vote-proxy-setup-airgapped/lockmkr.png)

Input the kovan vote-proxy contract and `lock()` ABI as follows:

- Contract address:
  - `< your VoteProxy address >`
- ABI / JSON Interface:
  - `[{"constant":false,"inputs":[{"name":"wad","type":"uint256"}],"name":"lock","outputs":[],"payable":false,"stateMutability":"nonpayable","type":"function"}]`

Confirm you are on the kovan network (top right of screen), and click `Access` (bottom left).
Below, you’ll be able to select the `lock()` method.

![Lock](/images/guides/vote-proxy-setup-airgapped/lock.png)

After selection, include the number of MKR you wish to lock in the parameter field; remember that it needs to be expressed in WEI. Submit the transaction with the default settings and your MetaMask hot wallet.

If the transaction went through without any reverts, great!

When ready, head over to <https://vote.makerdao.com> with your MetaMask hotwallet. At the top of the screen, you should see your MKR locked up and cold wallet linked.

![vote](/images/guides/vote-proxy-setup-airgapped/voteFront.png)

For instructions on how to vote, and finding your way around the rest of the dashboard, please click [here](https://medium.com/makerdao/introducing-the-governance-voting-ui-for-the-maker-foundational-vote-3fa669551ce1).

### Using this guide on Mainnet

If you wish to work with mainnet, you would need to go through the guide again with a couple different arguments -- set the chain to mainnet, change the gas price to be consistent with the present average gas/txn, and use all mainnet addresses:

```bash
export SETH_CHAIN=ethlive

GAS=<insert competitive gas price>

PROXYFACTORY=0xa63E145309cadaa6A903a19993868Ef7E85058BE
```

## Summary

In this guide, you signed transactions on your air-gapped machine, initiated and approved a cold-hot wallet link, approved an MKR transfer, and locked MKR in DSChief. You can now participate in Polling and Executive Voting at the Governance dapp at <https://vote.makerdao.com>

If you have any questions, you can reach out in the #dev channel on chat.makerdao.com.

Happy voting!

## Additional Resources

- [DSChief](https://github.com/dapphub/ds-chief)
- [VoteProxy](https://github.com/makerdao/vote-proxy)


Learn how to setup your voting proxy with Gnosis Multisig

VoteProxy Setup through Gnosis Multisig


# VoteProxy Setup through Gnosis Multisig

**Level:** Intermediary  
**Estimated Time:** 60 minutes

- [VoteProxy Setup through Gnosis Multisig](#voteproxy-setup-through-gnosis-multisig)
  - [Overview](#overview)
  - [Pre-requisites](#pre-requisites)
  - [Learning objectives](#learning-objectives)
  - [Step 1: Initiate Link](#step-1-initiate-link)
  - [Step 2: Approve Link](#step-2-approve-link)
  - [Step 3: Approve MKR Transfer](#step-3-approve-mkr-transfer)
  - [Step 4: Lock MKR](#step-4-lock-mkr)
  - [Using this guide on Mainnet](#using-this-guide-on-mainnet)
  - [Summary](#summary)

## Overview

This guide describes a method of linking an old version of the Gnosis Multisig wallet (as the cold wallet holding MKR) to an online hot wallet for participating in MakerDAO governance by voting using the [Voting-Proxy contract](https://github.com/makerdao/vote-proxy) as described in this [article](https://blog.makerdao.com/the-makerdao-voting-proxy-contract/). This is the recommended method of voting and is utilized in the vote.makerdao.com governance dashboard.

This guide is meant to be used on the Kovan Testnet. After a test run, this guide can be used again on mainnet, along with the revisions (addresses, etc) located at the end.

## Pre-requisites

Basic knowledge of executing multisig transactions in the Gnosis Multisig UI.

## Learning objectives

In this guide, we will learn how to

- Set up the VoteProxy contract with a Gnosis Multisig wallet as the cold wallet

## Step 1: Initiate Link

To initiate the link, we need to call `initateLink(hotAddress)` with our multisig wallet. Make sure you have enough kovan MKR to conduct the test and enough kovan ETH on your multisig wallet to cover gas costs. [You can get kovan ETH here](https://github.com/kovan-testnet/faucet) and kovan MKR by reaching out to @kenton, @lollike, @petru.catana or asking around in the public channels of RocketChat!

- Go to <https://wallet.gnosis.pm/> and login with your wallet. This is the old version of Gnosis Multisig.

- Navigate to the “Wallets” page, and click on the specific multisig wallet name, to enter the user interface for the specific multisig wallet.

- Under “Multisig transactions” press “Add”

- In the “Destination” field input the address of the

  - `VoteProxyFactory: 0x3E08741A68c2d964d172793cD0Ad14292F658cd8`

- In the “ABI string” window copy and insert the entire VoteProxyFactory ABI text string from this [etherscan link](http://api-kovan.etherscan.io/api?module=contract&action=getabi&address=0x3e08741a68c2d964d172793cd0ad14292f658cd8&format=raw)

- In the “Method” dropdown select the “initiateLink” method that will generate one input field, “hotAddress”.

- In “hotAddress” you copy/paste the address of your chosen hot address.

- Press “Send multisig transaction.”

- The other key holders must now confirm this transaction, and once the quorum is reached, a keyholder can execute the transaction.

- Once the transaction has been mined you can continue to the next step

## Step 2: Approve Link

To approve the link, you need to call `approveLink(coldAddress)` with our Hot wallet. In this guide, it is assumed it is a MetaMask wallet.

- Now, let’s head over to the `Write Contract tab` under the Kovan etherscan Address page for the [VoteProxyFactory](https://kovan.etherscan.io/address/0x3e08741a68c2d964d172793cd0ad14292f658cd8#writeContract)

- Select `Connect to Web3`.

![Etherscan](/images/guides/vote-proxy-setup-gnosis/proxyFactory.png)

Below, you’ll be able to select the `approveLink(coldAddress)` method.

After selection, include your cold wallet address in the argument field and submit the transaction with the default transaction settings and your MetaMask hot wallet.

If the transaction went through without any reverts, great! Your link is now approved. Next, let’s lock up some MKR to be used in Executive/Governance voting.

Note: Every cold-hot wallet link is one to one, meaning for any approved link, there is one unique cold wallet for another unique hot wallet. If you’d like to break a link, you could use either address to call the public `breakLink()` function in the VoteProxyFactory contract.

## Step 3: Approve MKR Transfer

Before you can lock up MKR, you need to approve our VoteProxy to make ERC20 Token (MKR) transfers. That way MKR can be pulled from the cold wallet and pushed to the voting contract (DSChief). Feel free to change the allowance to a value more appropriate for your case.

You’ll also need the address of your VoteProxy. This can be found via <https://kovan.etherscan.io> and under the internal transactions tab of your previous transaction (the one used to approve the cold-hot link).

![Etherscan](/images/guides/vote-proxy-setup-gnosis/proxycontract.png)

Let’s set up and approve the Voting Proxy contract that you made in the previous step.

- Go to <https://wallet.gnosis.pm/> and login with your wallet. This is the old version of Gnosis Multisig.

- Navigate to the “Wallets” page, and click on the specific multisig wallet name, to enter the user interface for the specific multisig wallet.

- Under “Multisig transactions” press “Add”

- In the “Destination” field input the address of the

  - `MKR ERC20: 0xaaf64bfcc32d0f15873a02163e7e500671a4ffcd`

- In the “ABI string” window copy and insert the entire MKR ERC20 ABI text string from this [etherscan link](http://api-kovan.etherscan.io/api?module=contract&action=getabi&address=0xaaf64bfcc32d0f15873a02163e7e500671a4ffcd&format=raw)

- In the “Method” dropdown select the “approve” method that will generate two input fields, “guy” and “wad”. Note that there are two "approve" methods, one with a "guy" and adjustable "wad" parameter, and another with just a "guy" parameter. The latter binary approval automatically sets the "wad" to be a very large number. We recommend using the first method, which limits the Vote Proxy's authority to pull only that that is intentionally prescribed.

- In “guy” you copy/paste the address of VoteProxy (as found in the previous, internal transaction).

- In “wad” you add a test amount (< 1) of MKR to be locked up in the VoteProxy. Note this is in units of Wad, which is equivalent to Wei (10^18), so one would enter 1000000000000000000 (1 with 18 zeros) for 1 MKR.

- Press “Send multisig transaction.”

- The other key holders must now confirm this transaction, and once the quorum is reached, a keyholder can execute the transaction.

- Once the transaction has been mined you can continue to the next step.

## Step 4: Lock MKR

With both the proxy link and MKR transfer approved, the hot wallet can be used to move MKR to and from DSChief. To call the `lock(wad)` method on your VoteProxy contract, you will use the multisig, though the method can be called with your hot wallet as well. The lock method will pull MKR from your cold wallet and push it to DSChief.

- Go to <https://wallet.gnosis.pm/> and login with your wallet. This is the old version of Gnosis Multisig.

- Navigate to the “Wallets” page, and click on the specific multisig wallet name, to enter the user interface for the specific multisig wallet.

- Under “Multisig transactions” press “Add”

- In the “Destination” field input the following address:

  - `VoteProxy: <0xABC123>`

- In the “ABI string” window copy and insert the following ABI text string:

  - `[{"constant":false,"inputs":[{"name":"wad","type":"uint256"}],"name":"lock","outputs":[],"payable":false,"stateMutability":"nonpayable","type":"function"}]`

- In the “Method” dropdown select the “lock” method that will generate one input field, “wad”.

- In “wad” you add a test amount (< 1) of MKR to be locked up in the VoteProxy. Note this is in units of Wad, which is equivalent to Wei (10^18), so one would enter `1000000000000000000` (1 with 18 zeros) for 1 MKR.

- Press “Send multisig transaction.”

- The other key holders must now confirm this transaction, and once the quorum is reached, a keyholder can execute the transaction.

- Once the transaction has been mined you can continue to voting.

If the transaction went through without any reverts, great!
When ready, head over to <https://vote.makerdao.com> with your MetaMask hotwallet. At the top of the screen, you should see your MKR locked up and cold wallet linked.

![vote](/images/guides/vote-proxy-setup-gnosis/voteFront.png)

## Using this guide on Mainnet

If you wish to work with mainnet, you would need to go through the guide again with mainnet contracts, which include:

- `MKR ERC20: 0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2`
- `VoteProxyFactory: 0x868ba9aeacA5B73c7C27F3B01588bf4F1339F2bC`

## Summary

In this guide, you signed transactions on your Gnosis Multisig wallet, initiated and approved a cold-hot wallet link, approved an MKR transfer, and locked MKR in DSChief. You can now participate in Polling and Executive Voting at the Governance dapp at <https://vote.makerdao.com>

If you have any questions, you can reach out in the #dev channel on chat.makerdao.com.

Happy voting!

Learn how DSProxy is used in Maker and apply it in your applications

Working with DSProxy

Dedicated to providing transparency to our community with respect to the results of our MCD Audits, our Bug Bounty Program, and Formal Verification

Multi-Collateral DAI (MCD) Security

# Multi-Collateral DAI (MCD) Security

These resources are 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.

1. Updates On MCD Security Roadmap

    * [MCD Bug Bounty Announcement and Security Roadmap Update](https://blog.makerdao.com/mcd-bug-bounty-announcement-and-security-roadmap-update/) _July 24, 2019_
    * [MCD Security Roadmap Update](https://blog.makerdao.com/mcd-security-roadmap-update-october-2019/) _October 23, 2019_
    * [Publication of the Runtime Verification Audit](https://forum.makerdao.com/t/publication-of-the-runtime-verification-audit/976) _December 19, 2019_

2. [Audit Reports](mcd-security-audits)

3. [Bug Bounty Program](bug-bounty-program)

4. [Formal Verification](formal-verification)




To protect against logical errors and/or potential failure modes in the contract logic

MCD Security Audits


# MCD Security Audits

We determined that the best strategy to maximize security would be to combine our formal verification efforts with more traditional security audits paired with higher-level formal modeling. Therefore, we partnered with three leading independent security auditors to protect against logical errors and/or potential failure modes in the contract logic.

**The following industry experts focused on:**

- **[Trail of Bits](https://www.trailofbits.com/)** - security reviews of our smart contracts.
- **[PeckShield](https://peckshield.com/)** - traditional audit.
- **[Runtime Verification](https://runtimeverification.com/smartcontract/)** - high-level formal model that can be used to further verify the logic of the system.

# Updates and Results

### [Runtime Verification Specification](https://github.com/makerdao/mkr-mcd-spec)

Runtime Verification, an Illinois-based software analysis company, uses runtime verification-based techniques to improve the safety, reliability, and technical “correctness” of software systems. The modelling and review components of Runtime Verification’s engagement have been delivered. [The code repository can be found in the MakerDAO’s Github](https://github.com/makerdao/mkr-mcd-spec).

The project involved a review of the DSS source code, the development of a K specification that described the high-level behaviors of MCD core and the overall state-updates that each operation in the system should have. It also included reproducing the issues found through our other review and the bug bounty program and adding those tests to the specification. Lastly, it included a random tester and bounded model checker that run on both concrete and symbolic back-ends to ensure the properties hold.

While this engagement has been focused more on designing and building the specification than a traditional audit of the code, it did identify several improvements that could be made in the code and integrated known/previous bugs to give us reasonable confidence in the model's ability to identify similar bugs. Going forward this specification and the resulting model can be used to check that changes to the protocol do not violate the specified system behaviors. We are continuing this work by focusing on applying and directing the tester over random and real world events and continuing to add to the high-level properties of the specification.

The random tester can generate arbitrary sequences of transactions for testing and test them against the known properties of the system. These properties document the intended behavior of the system and act as checks against the traces that the random tester generates.
Future governance updates to system parameters and changes to the MCD system itself can be tested against the high-level model and random tester before deploying to mainnet to ensure they do not unintentionally violate the desired system properties. If it is desirable to change the properties, the model and testing can be used to show how the proposed change alters the overall behavior of the system.

### [Trail of Bits Final Audit Report](https://github.com/makerdao/developer-portal/blob/master/public/images/security/audit-reports/TOB_MakerDAO_Final_Report.pdf)

Trail of Bits (ToB), a world leader in security, has audited our MCD smart contracts. ToB reviews a broad variety of software, creates security tooling, and consults on the modifications necessary for secure system deployment. Its audit consisted of manual review, automated analysis, and bespoke tool development.

**Summary of Findings**

- The Trail of Bits team identified two medium-severity issues, four low-severity issues, and eight informational security issues.
- In its audit report, the ToB team noted that our use of formal verification eliminated much of the “low-hanging fruit” in terms of vulnerabilities, and recommended continued use.
- The ToB team also developed several security analysis tools specialized to the MCD codebase. These tools were used throughout the course of the audit to discover bugs, and then delivered to the MCD team once the audit was completed.
- ToB had one specific finding concerning the DSR that we want to address here ([source](https://github.com/makerdao/developer-portal/blob/master/public/images/security/audit-reports/TOB_MakerDAO_Final_Report.pdf), pp. 22). We understand the perceived issue and are exploring the possibilities of how we could apply the DSR to Dai throughout the system. In the meantime, we agree with the risks of users' non-standard ERC-20 proxies for the DSR and have begun R&D on a proof-of-concept implementation. As always, we recommend users practice caution when using third-party smart contracts to interact with the MCD system.
- [Final Audit Report](https://github.com/makerdao/developer-portal/blob/master/public/images/security/audit-reports/TOB_MakerDAO_Final_Report.pdf)

### [PeckShield Final Audit Report](https://github.com/makerdao/developer-portal/blob/master/public/images/security/audit-reports/PeckShield_Final_Audit_Report.pdf)

PeckShield, a security services organization based in China, had previously and independently verified the Maker DSChief vulnerability that was patched in May. Therefore, we contracted them to do a formal audit.

**Summary**

- The PeckShield team identified one high-severity issue (previously discovered through the bug bounty program), one medium-severity issue, four low-severity issues, and 10 informational security issues.
- In its audit report, the team recognized our independent security efforts: “We always recommend proceeding with several independent audits and a public bug bounty program to ensure the security of smart contract(s).”
- Zero bugs noted in PeckShield’s “17 Typical Smart Contract Coding Bugs” list were found.
- [Final Audit Report](https://github.com/makerdao/developer-portal/blob/master/public/images/security/audit-reports/PeckShield_Final_Audit_Report.pdf)

### Third-Party Audit Results

In addition to the audit results provided by the three contracted organizations noted above, we were contacted by a third-party security firm, Certora, who presented findings after reviewing the MCD code on their own and with their own tools. We want to thank Certora for independently verifying two important vulnerabilities.

## In Summary

**Overall, security audits have covered the following areas within MCD:**

- The core Maker Protocol
- Incentive reasoning
- DoS, Replay, Front-running, System/Blockchain-level attacks
- Governance Attacks
- Governance (general)
- Front-end contracts and collateral adapters
- Oracles
- Off-chain price-feed infrastructure
- On-chain oracle contracts
- System deployment and Permissions correctness
- Auctions
- K-dss

Our efforts from all four security tracks have resulted in the discovery of a number of bugs, including some high- and critical-severity issues. We’ve taken steps to evaluate and mitigate these issues, and we will continue to work with auditors to verify that we have completely addressed them pre-MCD launch.


A key component of our strategy to maximize security testing by approaching it from different angles and multiple layers to ensure the security of the MCD smart contracts

Bug Bounty Program


# Program Summary

The [Bug Bounty Program](https://hackerone.com/makerdao_bbp/hacktivity?order_direction=DESC&order_field=popular&filter=type%3Abounty-awarded) is a key component of our strategy to maximize security testing by approaching it from different angles and multiple layers to ensure the security of the MCD smart contracts.

### Timeline

- Initiated the Bug Bounty program privately for selected researchers (Private testnet on June 3rd).
- Launched our public bug bounty program on [Hackerone](https://hackerone.com/makerdao_bbp) (July 24th).
- Bug Bounty Program to continue indefinitely.

### Program Scope

The bug bounty program currently contains two separate scopes, which share the same rules with a few exceptions as noted below:

- Smart contracts for Multi-Collateral Dai.
- Infrastructure for select public facing domains (please see the "Ineligible Bugs" section in the **Policy** section on HackerOne, especially regarding third party software, before submitting a report).

**Note:** The program may be expanded in the future to include more asset types such as frontends and apps.

## Updates and Results

Since the launch of the program, three high-severity bugs and one critical-severity bug have been discovered, resulting in bounty reward payments totalling \$90,000. The vulnerabilities consisted of unwanted interactions between the Dai Savings Rate (DSR) module and the Maker Protocol in one case, and the emergency shutdown module and the auctions in another case. The discoveries were in line with our expectations, as these modules either required additional scrutiny or were the most recent ones to be integrated with the system. Given that the security of the system remains our highest priority, we will continue the bug bounty program indefinitely.


Formal Verification


# Formal Verification

Overall, the MCD system's core contracts have been fully formally verified, and the verification of peripheral and helper contracts is ongoing. We are now currently working on the formal verification of the tokens that may be voted in as new collateral types, focusing on formally verifying the secondary contracts as well as the governance contracts in the system, and have incorporated formal verification into our continuous testing and release processes. In terms of our in-house efforts, we are leveraging klab, KEVM, and the K Framework for our Formal verification processes.

**Small-step semantics:**

- DSS Core - executable specification
- Exhaustive reachability claims
- EVM bytecode performs as we expect
- Function-level correctness
- Transaction-level correctness

**Big-step semantics:**

- Maker DSL / State Machine
- High-level system model (K)
- System-level invariants
- Exhaustive behaviour checking
- Executable system documentation

**Update - Formal Verification that has been completed thus far:**

- Core system
- Dai token contract
- Auction contracts
- Dai Savings Rate (DSR)
- Emergency shutdown module (ESM)
- The Oracle security module (OSM) has been largely completed.

Overall, the plan is to continue our formal verification efforts on the road to launching MCD, which includes updating past proofs based on the findings of our audits and bug findings.


The auction mechanisms within the system explained

The Auctions of the Maker Protocol


# The Auctions of the Maker Protocol

## Introduction

The Multi-Collateral Dai MCD system within the MakerDAO Protocol is a smart contract platform on Ethereum that backs and stabilizes the value of our stablecoin, Dai. It does this through a dynamic system of Vaults, autonomous feedback mechanisms, and appropriately incentivized external actors.

In this document, we explain the auction mechanisms within the system, as well as particular types of external actors, called Keepers, that bid on the Auctions.

## Auctions

When everything in the system is going well, Dai accrues through [stability fees](https://github.com/makerdao/community/blob/master/faqs/stability-fee.md) collected from Vaults. Whenever the net surplus from stability fees reaches a certain limit, that surplus in Dai is auctioned off to external actors for MKR which subsequently is burnt, thereby reducing the amount of MKR in circulation. This is done through a **Surplus Auction**.

The system protects against debt creation by overcollateralization. Under ideal circumstances and with the right risk parameters, the debt for an individual Vault can be covered by the collateral deposited in that Vault. If the price of that collateral drops to the point where a Vault no longer sustains the required collateralization ratio, then the system automatically liquidates the Vault and sells off the collateral until the outstanding debt in the Vault and a liquidation penalty, is covered. This is done through a **Collateral Auction**.

Further, if, for example, the collateral price drops sharply or no one wants to buy the collateral, there may be debt in the liquidated Vault that cannot be repaid through a collateral auction and must be addressed by the system. The first course of action is to cover this debt using surplus from stability fees, if there is any surplus to cover it. If there is not, then the system initiates a **Debt Auction**, whereby the winning bidder pays Dai to cover the outstanding debt and in return receives an amount of newly minted MKR, increasing the amount of MKR in circulation.

### To summarize, we have three types of Auctions:

- **Surplus Auction**: The winning bidder pays MKR for surplus Dai from stability fees. The MKR received is burnt, thereby reducing the amount of MKR in circulation.
- **Collateral Auction**: The winning bidder pays Dai for collateral from a liquidated Vault. The Dai received is used to cover the outstanding debt in the liquidated Vault
- **Debt Auction**: The winning bidder pays Dai for MKR to cover outstanding debt that Collateral Auctions haven’t been able to cover. MKR is minted by the system, thereby increasing the amount of MKR in circulation.

The actors that bid on these Auctions are called **Keepers**.

## Keepers

With all information published on the Ethereum blockchain, anyone can access or monitor price feeds and data on individual Vaults, thereby determining whether certain Vaults are in breach of the Liquidation Ratio. The system incentivizes these market participants which can be human or automated bot, known as “keepers,” to monitor the MCD System and trigger liquidation when the Liquidation Ratio is breached.

In the context of Multi-Collateral Dai, Keepers may participate in auctions as a result of liquidation events and thereby acquire collateral at attractive prices. Keepers can also perform other functions, including trading Dai motivated by the expected long-term convergence toward the Target Price.

We will now go into more detail about how the **Auctions** work.

### The Auction Parameters and Mechanisms

Various considerations were taken into account when designing the auction mechanisms. For example, from a systems point of view, it’s best to complete the auction as soon as possible to keep the system in a steady state, so the auction mechanism incentivizes early bidders. Another consideration is that the Auctions are executed on-chain, minimizing the number of required transactions and reducing associated fees.

#### Auctions Glossary

**Risk parameters**. In general, the following parameters are used across all of the auction types:

- `beg`: Minimum bid increase for example, 3%.
- `ttl`: Bid duration for example, 6 hours. The auction ends if no new bid is placed during this time.
- `tau`: Auction duration for example, 24 hours. The auction ends after this period under all circumstances.

The values of the risk parameters are determined by Maker Governance voters MKR holders per auction type. Note that there are different Collateral Auction risk parameters for each type of collateral used in the system.

**Auction and bid information**. The following information is always available during an active auction:

- `lot` : Amount of asset that is up for auction/sale.
- `bid`: Current highest bid.
- `guy`: Highest bidder.
- `tic`: Bid expiry date/time empty if zero bids.
- `end`: Auction expiry date/time.

#### Bid Increments During an Auction

During an auction, bid amounts will increase by a percentage with each new bid. This is the `beg` at work. For example, the `beg` could be set to 3%, meaning if the current bidder has placed a bid of 100 Dai, then the next bid must be at least 103 Dai. Overall, the purpose of the bid increment system is to incentivize early bidding and make the auction process move quickly.

#### How Bids are Placed During an Auction

Bidders send DAI or 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.

**Now, let’s review the mechanisms of the three different auction types.**

### Surplus Auction

**Summary**: A Surplus Auction is used to auction off a fixed amount of surplus Dai in the system in exchange for MKR. This surplus Dai will generally come from accumulated stability fees. In this auction, bidders compete with increasing bids of MKR. Once the auction has ended, the auctioned Dai is sent to the winning bidder, and the system burns the MKR received from the winning bidder.

**High-level Mechanism Process**:

- Maker Governance voters determine the amount of surplus allowed in the system at any one time. A Surplus auction is triggered when the system has a Dai surplus over the pre-determined amount as set by MKR governance.
  - To determine whether the system has a net surplus, accrued stability fees and debt in the system must be added together. Any user can do this by sending the `heal` transaction to the system contract called Vow.
  - Provided there is a net surplus, the Surplus Auction is triggered when any user sends the `flap` transaction to the Vow contract.
- When the auction begins, a fixed amount `lot` of Dai is put up for sale. Bidders then bid with MKR in increments greater than the minimum bid increase amount. The auction officially ends when the bid duration ends `ttl` without another bid OR when the auction duration `tau` has been reached. Once the auction ends, the MKR received for the surplus Dai is then sent to be burnt, thereby contracting the system’s MKR supply.

### Collateral Auction (Collateral Sale)

**Summary**: Collateral Auctions serve as a means to recover debt in liquidated Vaults. Those Vaults are being liquidated because the value of the Vault collateral has fallen below a certain limit determined by the Maker Governance voters.

**High-level Mechanism Process**:

For each type of collateral, MKR holders approve a specific risk parameter called the liquidation ratio. This ratio determines the amount of overcollaterization a Vault requires to avoid liquidation. For example, if the liquidation ratio is 150%, then the value of the collateral must always be one and a half times the value of the Dai generated. If the value of the collateral falls below the liquidation ratio, then the Vault becomes unsafe and is liquidated by the system. The system then takes over the collateral and auctions it off to cover both the debt in the Vault and an applied liquidation penalty.

- The Collateral Auction is triggered when a Vault is liquidated.
  - Any user can liquidate a Vault that is unsafe by sending the bite transaction identifying the Vault. This will launch a collateral auction.
  - If the amount of collateral in the Vault being “bitten” is less than the lot size for the auction, then there will be one auction for all collateral in the Vault.
  - If the amount of collateral in the Vault being “bitten” is larger than the lot size for the auction, then an auction will launch with the full lot size of collateral, and the Vault can be “bitten” again to launch another auction until all collateral in the Vault is up for bidding in Collateral Auctions.

An important aspect of a Collateral Auction is that the auction expiration and bid expiration parameters are dependent on the specific type of collateral, where more liquid collateral types have shorter expiration times and vice-versa.

Once the auction begins, the first bidder can bid any amount of Dai to aquire the collateral amount `lot`. Other bidders can raise that bid offering more Dai for the same collateral amount `lot` until there is a bid that covers the outstanding debt. If and when there is a bid that covers the outstanding debt, the auction will turn into a reverse auction, where a bidder bids on accepting smaller parts of the collateral for the fixed amount of Dai that covers the outstanding debt. The auction ends when the bid duration `ttl` has passed OR when the auction duration `tau` has been reached. Again, this process is designed to encourage early bidding. Once the auction is over, the system sends the collateral to the winning bidder’s address.

### Debt Auction

**Summary**: Debt Auctions are used to recapitalize the system by auctioning off MKR for a fixed amount of Dai. In this process, bidders compete with their willingness to accept decreasing amounts of MKR for the fixed Dai they will have to pay.

**High-level Mechanism Process**:

Debt Auctions are triggered when the system has Dai debt that has passed the specified debt limit.

- Maker Governance voters determine the debt limit. The Debt auction is triggered when the system has a debt in Dai below that limit.
  - In order to determine whether the system has a net debt, the accrued stability fees and debt in the system must be added together. Any user can do this by sending the `heal` transaction to the system contract named Vow.
  - Provided there is a sufficiently sized net debt, the debt auction is triggered when any user sends the `flop` transaction to the Vow contract

This is a reverse auction, where Keepers bid on how little MKR they are willing to accept for the fixed Dai amount `lot` they have to pay at auction settlement. The auction ends when the bid duration `ttl` has passed OR when the auction duration `tau` has been reached. Once the auction is over, the Dai, paid into the system by bidders in exchange for newly minted MKR, reduces the original debt balance in the system.

**To participate as a Keeper in MCD, please visit thee Auction Keeper Bot Setup Guide [here](/documentation/auction-keeper-bot-setup-guide).**


Multi Collateral Dai (MCD) CLI


# Multi Collateral Dai (MCD) CLI

## Installation

First install [dapp tools](https://dapp.tools/):

```bash
curl https://dapp.tools/install | sh
```

Then install the `mcd` package:

```bash
dapp pkg install mcd
```

#### The following list details all of the commands available when interacting with the command-line interface:

```bash
MCD - Multi-collateral Dai

Usage: mcd [<options>] <command> [<args>]
   or: mcd help [<command>]

Commands:

   bite            Trigger liquidation of an unsafe Urn
   bites           Recent bites
   cdp             CDP managerment
   dai             Dai management
   debt            Total dai issuance
   drip            Trigger stability fee accumulation
   flap            Trigger a flap auction
   flips           View flips and kick-off auctions
   flog            Release queued bad-debt for auction
   flop            Trigger a flop auction
   frob            Urn management
   frobs           Recent frobs
   gem             Collateral management
   help            Print help about mcd or one of its subcommands
   ilk             Ilk (collateral type) parameters
   line            Total debt ceiling
   live            Liveness flag
   poke            Update the spot price for a given Ilk
   unwrap          Unwrap WETH to ETH
   urn             CDP state
   vice            Total bad debt
   vow             Liquidator balances
   wrap            Wrap ETH to WETH
```

### Configuration

Mcd is built on [Seth](https://github.com/dapphub/dapptools/tree/master/src/seth) and uses the same network configuration options, which just like Seth, can be defined in the `~/sethrc` initialisation file.

Similar to Seth, `mcd` also supports transaction signing with Ledger hardware wallets and can run against both local and remote nodes.

Since `mcd` will always be used against a known deployment of the system, defaults can be loaded wherever possible. In most cases the only required configuration parameter is the `-C, --chain=<chain>` (`MCD_CHAIN`) option and `-F, --from=<address>` (`ETH_FROM`) sender account when not using a testnet.

Example `~/.sethrc`:

```bash
#!/usr/bin/env bash
export ETH_FROM=0x4Ffa8667Fe2db498DCb95A322b448eA688Ce430c
export MCD_CHAIN=kovan
```

**Kovan**

Run against the latest Kovan deployment by setting the `-C, --chain` option to `kovan`. Specify a sender account when sending transactions using the `-F, --from` option, or via the `ETH_FROM` env variable.

```bash
export ETH_FROM=0x4Ffa8667Fe2db498DCb95A322b448eA688Ce430c
mcd --chain=kovan dai join 100
```

**Remote testchain**

Run agaist remote testchain deployments by setting the `-C, --chain` option to the remote testchain Id. Mcd will auto-configure account settings via the testchain api so that no further configuration is required. To view a list of available testchains run:

```bash
mcd testnet chains`
```

Then set the chain option, or the chain env variable to the appropriate testchain Id.

```bash
export MCD_CHAIN=12899149080555595289
mcd dai join 100
```

**Local testnet**

Run against a locally running instance of [Dapp testnet](https://github.com/dapphub/dapptools/tree/master/src/dapp) where the system has been deployed by setting the `C, --chain` option to `testnet`. Mcd will auto-configure account testings for `dapp testnet` so that no further configuration is required.

By default, Mcd assumes that the output of the testchain deployment script is available at `~/.dapp/testnet/8545/config/addresses.json`. Configuration addresses can be loaded from a different location by setting the `--config` (`MCD_CONFIG`) option.

```bash
export MCD_CONFIG=~/testchain-deployment-scripts/out/addresses.json
mcd -C testnet dai join 100
```

### Ilk

Ilks are collateral types with corresponding risk parameters which have been approved by system governance. Use the `ilks` command to view the list off available Ilks.

```bash
mcd ilks
ILK      GEM    DESC

ETH-A    WETH   Ethereum
ETH-B    WETH   Ethereum
REP-A    REP    Augur
```

Each Ilk has its own set of configuration parameters which can be viewed via the `ilk` command. The `I, --ilk=<id>` option is used to scope commands to a particular Ilk:

```bash
mcd --ilk=ETH-A ilk
Art  40.000000000000000000                      Total debt (DAI)
rate 1.000080370887129123082627939              WETH DAI exchange rate
spot 99.333333333333333333333333333             WETH price with safety mat (USD)
line 1000.0000000000000000000000000000000000000 Debt ceiling (DAI)
dust 0.0000000000000000000000000000000000000000 Debt floor (DAI)
flip 0x9d905effff127a01da3b38124f8da88e766eb8dd Flip auction contract
chop 1.000000000000000000000000000              Liquidation penalty
lump 10000.000000000000000000                   Flip auction lot size
tax  1.000000000782997609082909351              Stability fee
rho  1552802862                                 Last drip timestamp
pip  0x98312e16f5b2c0def872a1f7484a8456e5a67a3b Price feed contract
mat  1.500000000000000000000000000              Liquidation ratio
```

Individial ilk values can be retrieved by adding the parameter name as an argument to the `ilk` command:

```bash
mcd --ilk=ETH-A ilk spot
99.333333333333333333333333333
```

### Gem

Gems are collateral tokens. Collateral is added and removed from the via adapters, which abstract away the differences between various token behaviours. Use `gem [<subcommand>]` to manage collateral balances for any given Ilk.

```bash
gem --ilk=<id> symbol             Gem symbol e.g. WETH
gem --ilk=<id> balance            Print balances for a given urn (default: ETH_FROM)
gem --ilk=<id> join <wad>         Add collateral to a given Urn (default: ETH_FROM)
gem --ilk=<id> exit <wad> [<guy>] Remove collateral from an Urn (default: ETH_FROM)
```

The `join` command can add collateral from the sender account to any specified Urn. The `exit` command can remove collateral from a specified Urn, provided that the sender controls the private key associated with that Urn.

By default, `ETH_FROM` is used to determine which Urn should be credited with collateral. Use `U, --urn=<address>` to optionally credit an Urn other than the default.

```bash
mcd --ilk=ETH-A --urn=0x123456789abcdef0123456789abcdef012345678 join 100
```

The `exit` command can remove collateral from a specified Urn, provided that the sender controls the private key associated with that Urn. The `exit` command can also withdraw collateral to an account other than `ETH_FROM` buy passing the destination address as an additional argument:

```bash
mcd --ilk=ETH-A exit 100 0xDecaf00000000000000000000000000000000000
```

### Urn

Urns represent Cdp state for any given Urn address.

Use the `urn` command to view Urn state for any given Ilk:

```bash
ilk  ETH-A                                      Collateral type
urn  0xC93C178EC17B06bddBa0CC798546161aF9D25e8A Urn handler
ink  45.000000000000000000                      Locked collateral (WETH)
art  120.000000000000000000                     Issued debt (Dai)
tab  120.000244107582797248312544980            Outstanding debt (Dai)
rap  0.000244107582797248312544980              Accumulated stability fee (Dai)
-->  37.24                                      Collateralization ratio

spot 99.333333333333333333333333333             WETH price with safety mat (USD)
rate 1.000002034229856643749638820              WETH DAI exchange rate
```

By default, `ETH_FROM` is used to determine which Urn to query. Use the `U, --urn=<address>` option to query Urns at other indexes.

**Urn management**

Urn state `urn.ink` and `urn.art` is managed via the `frob <dink> <dart>` command, where `dink` and `dart` are delta amounts by which `ink` Locked collateral and `art` Outstanding debt should be changed. For example, to lock 100 WETH and draw 400 Dai on the ETH-A Ilk:

```bash
mcd --ilk=ETH-A frob 100 400
```

To reduce outstanding debt by 200 Dai whilst keeping the amount of locked collateral constant:

```bash
mcd --ilk=ETH-A frob -- 0 -200
```

### Dai

Similar to Gem adapters, a Dai adapter is used to exchange Vat Dai for ERC20 token Dai which can then be used outside the system. Use `dai [<subcommand>]` to manage dai balances.

```bash
dai balance    Print balances for a given urn (default: ETH_FROM)
dai join <wad> Exchange DSToken Dai for Vat Dai
dai exit <wad> Exchange Vat Dai for DSToken Dai
```

Once Dai has been drawn on an Urn, it can be withdrawn for use outside the system using `dai exit`. Dai can be returned to repay Urn debt via `dai join`.

The `dai balance` command displays the internal system vat balance and the external ext token balance:

```bash
mcd dai balance
vat 1030.003120998308631176024235912000000000000000000 Vat balance
ext 0.000000000000000000 ERC20 balance
```

Individial balance values can be retrieved by adding `vat` or `ext` as an argument to the `balance` command:

```bash
mcd dai balance vat
1030.003120998308631176024235912000000000000000000
```

### Cdp

The `cdp` command provides compatability with CDPs managed via the CDP Portal and uses the same proxy contract and [Cdp Manager](https://github.com/makerdao/dss-cdp-manager) font-end. This allows CDPs to be managed via a unique integer identifier rather than the `I, --ilk` and `U, --urn` options.

```bash
Usage: mcd cdp [<id>] [<command>]

Commands: ls [<owner>]     List Cdps
          count [<owner>]  Cdp count
          open             Open a new Cdp
          <id> urn         Cdp state
          <id> lock <wad>  Join & lock collateral
          <id> free <wad>  Free & exit collateral
          <id> draw <wad>  Draw & exit dai
          <id> wipe <wad>  Join & wipe dai
```

### Examples

Note: examples assume that `ETH_FROM` is set to an address controlled by the user, and that the `MCD_CHAIN` env variable has been set to a vaild chain identifier.

#### 1. Native Urn - lock 100 ETH & draw 500 Dai

Note: The system doesn't handle ETH directly but instead uses WETH to represent ETH collateral. For convenience, the `wrap` and `unwrap` commands are provided for exchanging ETH to WETH and visa versa.

```bash
# i) Wrap
$ mcd wrap 100
eth  900.000000000000000000
weth 100.000000000000000000

# ii) Gem join
$ mcd --ilk=ETH-A gem join 100
$ Grant approval to move WETH to the Vat? [Y/n]: Y
vat 100.000000000000000000 Free collateral (WETH)
ink   0.000000000000000000 Locked collateral (WETH)
ext   0.000000000000000000 External account balance (WETH)
ext 900.000000000000000000 External account balance (ETH)

# iii) Lock & Draw
$ mcd --ilk=ETH-A frob 100 500
ilk  ETH-A                                      Collateral type
urn  0xC93C178EC17B06bddBa0CC798546161aF9D25e8A Urn handler
ink  100.000000000000000000                     Locked collateral (WETH)
art  500.000000000000000000                     Issued debt (Dai)
tab  500.000244107582797248312544980            Outstanding debt (Dai)
rap  0.000244107582797248312544980              Accumulated stability fee (Dai)
-->  19.86                                      Collateralization ratio

# iv) Withdraw Dai
$ mcd dai exit 500
vat 0.000060682318362511884962000000000000000000000 Vat balance
ext 500.000000000000000000 ERC20 balance
```

#### 2. Managed Cdp - lock 100 REP & draw 50 Dai

```bash
# i) Open
$ mcd --ilk=REP-A cdp open
mcd-cdp-open: Waiting for transaction receipt...
0x800e5578d3ac4b77b7ada1aba48cf80d0d238d4392d2676d79159eac2c2cdd73
Opened: cdp 19

# ii) Lock
$ mcd --ilk=REP-A cdp 19 lock 100
seth-send: Published transaction with 260 bytes of calldata.
seth-send: 0x4d30cb4863ca997d24ff2346c9a92e86648369ce7b4a86ed004c73b8d4ef299a
seth-send: Waiting for transaction receipt...
seth-send: Transaction included in block 333.
ilk  REP-A                                      Collateral type
urn  0x4518c4709a50C915b7996A0e6Dfb38c67248BBcF Urn handler
ink  100.000000000000000000                     Locked collateral (REP)
art  0.000000000000000000                       Issued debt (Dai)
tab  0                                          Outstanding debt (Dai)
rap  0                                          Accumulated stability fee (Dai)
-->  0                                          Collateralization ratio

# iii) Draw
$ mcd --ilk=REP-A cdp 19 draw 500
seth-send: Published transaction with 260 bytes of calldata.
seth-send: 0xd5fb7ddf94bb910fbba2af118ecde88a03a13129b2e1979238236afe672781c3
seth-send: Waiting for transaction receipt...
seth-send: Transaction included in block 335.
ilk  REP-A                                      Collateral type
urn  0x4518c4709a50C915b7996A0e6Dfb38c67248BBcF Urn handler
ink  100.000000000000000000                     Locked collateral (REP)
art  49.999505439113270178                      Issued debt (Dai)
tab  50.000000000000000000000000000             Outstanding debt (Dai)
rap  0.000494560886729822000020743              Accumulated stability fee (Dai)
-->  16.66                                      Collateralization ratio
```


A powerful command line tool created to interface with the Ethereum blockchain

Seth


# Seth

## Introduction to Seth

Seth is a simple, but powerful command line tool created to interface with the Ethereum blockchain. It is part of the [Dapp.Tools](https://dapp.tools/) toolset along with other tools for Ethereum. Its two main functionalities among others are performing calls queries of the Ethereum blockchain - a “read” operation and sending transactions writing into the blockchain, changing its state. It also provides conversion between data of Ethereum’s own specific formats and the more widespread, usual data formats.

### Getting started

In the following section we will go through the installation and setup of Seth. These steps only work on Unix-based systems i.e. Linux and macOS, however on Windows, you can try with an emulator, like [cmder](http://cmder.net/) or [cygwin](https://www.cygwin.com/), the [linux subsystem](https://docs.microsoft.com/en-us/windows/wsl/install-win10) in Windows 10, a virtual machine or a container.

### Installation

Seth can be installed as a part of the Dapp Tools suite, which is a collection of blockchain tools created with the Unix philosophy in mind. The most convenient way to do this, is to install Dapp Tools with the one line script provided on the [webpage](https://dapp.tools/). Here is how to do it:

From the Dapp Tools page:

> If you are running GNU/Linux or macOS you can take advantage of our all in one installer.

`$ curl https://dapp.tools/install | sh`

This script downloads the Nix package manager, setups binary cache with Cachix and installs our most used tools.

### Manual install

If you have issues using the script above, you can try the manual installation on the aforementioned website. A this point in time you can do a manual installation by running the following scripts:

```bash
$ curl https://nixos.org/nix/install | sh
$ . "$HOME/.nix-profile/etc/profile.d/nix.sh"
$ nix-env -if https://github.com/cachix/cachix/tarball/master --substituters https://cachix.cachix.org --trusted-public-keys cachix.cachix.org-1:eWNHQldwUO7G2VkjpnjDbWwy4KQ/HNxht7H4SSoMckM=
$ cachix use dapp
$ git clone --recursive [https://github.com/dapphub/dapptools](https://github.com/dapphub/dapptools) $HOME/.dapp/dapptools
$ nix-env -f $HOME/.dapp/dapptools -iA dapp seth solc hevm ethsign
```

In order to test if the tools have been installed correctly, check the current version of Seth with the following command:

`$ seth --version`

If Seth has been installed correctly, the command should produce the following output:

`seth 0.7.0`

At the time of writing, seth 0.7.0 is thus the latest version, however in the future the output might have a different versioning number.

#### Errors and a note on macOSX Mojave

If the above command does not work, or you had trouble installing it may be due to Mac OSX Mojave, as we have experienced various issues with the tools nix and cachix not working correctly on this OS, specifically due to a multi-user bug. If you happen to have more user accounts on your Mac, and experience errors running this guide, [this document](https://github.com/makerdao/developerguides/blob/master/devtools/seth/seth-guide-01/seth-guide-01.md#) might help you resolve the issue. If this does not resolve the issue, you are more than welcome to ask for help on [chat.makerdao.com](https://chat.makerdao.com/) in the help channel.

### Set up and configuring variables

Configuring Seth can be done with environment variables or command line options. Environment variables can be generally used in two ways: you can save them in a configuration file named .sethrc in specific locations, like your home folder, or just set them only for the current terminal session. In this guide we will use environment variables with the latter approach for simplicity’s sake, however for ease-of-use in the future, we strongly encourage to save the variables in your project folder. Follow [this example](https://github.com/dapphub/dapptools/tree/master/src/seth#example-sethrc-file) to do so.

#### Using a local private network

You can quickly set up a local private network with the Dapp tool, which will also create accounts and their keystore files with empty strings for passwords by default. Setting up a local network can be handy when developing dapps for a quick an easy and way to deploy and test functionality without the need of acquiring test-net Ether for contract deployment.

Open a new terminal and execute the following command, and keep it running in the background during the tutorial:

`$ dapp testnet`

Copy your account address from the output.

Then in a separate terminal let’s create an empty password file:

`$ touch pass`

And let’s create our environment variables:

```bash
$ export ETH_PASSWORD=$PWD/pass
$ export ETH_KEYSTORE=~/.dapp/testnet/8545/keystore
$ export ETH_FROM=<your ethereum account address>
```

#### Using Kovan

Seth can connect to the Kovan Ethereum testnet through a default remote node provided by Infura. This is the most convenient way to do so. You can either create a new account or use the existing one created by the testnet. If you decide to use the existing one, you only need to change the chain parameter:

`$ export SETH_CHAIN=kovan`

If you decide to create a new account, an easy method is using the "create new wallet" option in MEW: [https://www.myetherwallet.com/](https://www.myetherwallet.com/). It is also possible to use Parity or Geth to create a new account or you can use an existing keystore file for a Parity or Geth account. You are also going to need to save the password of your keystore file in a plain text file Never use this keystore file for real ETH - saving the password for your keystore file in plain text would be very unsafe for a real account! This also goes for the testnet account!.

Then you have to set up the same variables:

```text
$ export ETH_KEYSTORE=<path to your keystore folder>
$ export ETH_PASSWORD=<path and filename to the text file containing the password for your account e.g: /home/one1up/MakerDAO/415pass >
$ export ETH_FROM=<your ethereum account address>
$ export SETH_CHAIN=kovan
```

You will need Kovan ETH for gas, you can get some by following the guide here: [https://github.com/kovan-testnet/faucet](https://github.com/kovan-testnet/faucet)

### Seth operations

For the first two operations you can use either your own testnet or the Kovan testnet - try both if you want to!

#### seth balance - Checking ETH balance

Checking ETH balances is pretty straight forward. It can be done with the balance subcommand, then specifying the address as a parameter:

`$ seth balance $ETH_FROM`

#### seth send - Sending ETH

Let’s send Kovan or private net ETH to an address. You can choose any valid address - in this example I am going to use [Ethereum Foundation's donation address](https://www.ethereum.org/donate):

`$ seth send --value 0.1` 
[`0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359`](https://etherscan.io/address/0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359)

Upon execution you should see something like the following:

```bash
seth-send: warning: `ETH_GAS' not set; using default gas amount
seth-send: Published transaction with 0 bytes of calldata.
seth-send: 0x000000…
seth-send: Waiting for transaction receipt.......
seth-send: Transaction included in block xxxxxx.
```

This indicates that the transaction was successful.

#### seth call - Reading contract storage

Since we don't have any contracts deployed to our private network, **let's use Kovan from now on**. Let’s use one of the simplest contracts possible: an ERC-20 token contract. In this example, we are going to use a test collateral token COL1. You can save its address in a variable with the following command:

`$ export COL1=0x911eb92e02477a4e0698790f4d858e09dc39468a`

You can read the output of a public function of a contract using the call subcommand, the contract’s address, and the name of the function.

Let's check out the number of decimals of this token:

`seth call $COL1 'decimals()'`

The output is:

`0x0000000000000000000000000000000000000000000000000000000000000012`

Now don't let this fool you. Seth queries contract data in a low level manner, and returns the value in hexadecimal, as it is represented in the contract, but you can convert it using:

`$ seth --to-dec $(seth call $COL1 'decimals()')`

The output is:

`18`

#### Sending contract transaction with seth send

You can send a transaction to a contract with the same send command, by adding a couple of extra parameters. Just like with call, you need to specify the contract address and the function we are calling. Let’s get some COL1 tokens from a previously set up faucet:

`$ export FAUCET=0xe8121d250973229e7988ffa1e9330b420666113a`

`$ seth send $FAUCET ‘gulp(address)’ $COL1`

#### Using function parameters

Now you can check your COL1 balance. This time you will need to present a parameter for the ‘balanceOf’ method of the ERC-20 contract. You can do this by first defining the type, the function takes in its parentheses, and then putting the input parameter after the method:

`$ seth --to-dec $(seth call $COL1 'balanceOf(address)' $ETH_FROM)`

The output is:

`500000000000000000000`

Now, that's a rather large value we got. The reason for this is that the contract stores the balances in wei unit 10^-18, which is why we have to convert it to get the actual number of COL1 we own:

`$ seth --from-wei $(seth --to-dec $(seth call $COL1 'balanceOf(address)' $ETH_FROM)) eth`

The output is:

`50.000000000000000000`

#### seth block - Retrieving block information

With seth block, we are capable of querying any information about an Ethereum block. Here is the usage from the help option `$ seth block --help`:

```bash
Usage: seth block [-j|--json] <block> [<field>]
Print a table of information about <block>.
If <field> is given, print only the value of that field.
```

Like any other Seth command, this command depends on Ethereum JSON RPC calls, which are part of the interface of any Ethereum client. You can dive into the corresponding documentation [https://github.com/ethereum/wiki/wiki/JSON-RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC) to learn more about it.

What can come in handy is the fact that in place of a block number, we can also use earliest, latest or pending. So if we would like to query the current block gas limit I have tried this with seth configured for the kovan testnet we can do the following:

`$ seth block latest gasLimit`

Output:

`8000000`

#### seth estimate - Estimating gas cost of a transaction

`seth estimate` can give an estimation for the gas usage of a transaction. The syntax is pretty much the same as for `seth send`, but `seth estimate` will not actually send the transaction.

When you want to send a transaction to a contract function with Seth, you have to provide the function signature and the parameters in order after the signature. The ERC-20 transfer function signature looks like the following in Solidity:

`transfer(address _to, uint256 _value) public returns (bool success)`

The signature part that Seth needs from this is 'transfer(address, uint)' and the parameters are the recipient address and the amount. The contract needs to receive the amount in hexadecimal representation of the number in wei unit, which is why we need those conversions.

Now, to estimate the gas usage of an ERC-20 token transfer let’s execute the following:

`$ seth estimate $COL1 'transfer(address, uint)'` [ `0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359`](https://etherscan.io/address/0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359) `$(seth --to-uint256 $(seth --to-wei 0.1 ether))`

Output:

`37240`

#### seth receipt and seth tx

With seth receipt and seth tx, we can query every single detail imaginable about a transaction. They both take a transaction tx hash as an input parameter. The main difference between the two, is that the receipt, which contains the results of the transaction, is only constructed after the transaction gets mined, while the output of seth tx only contains the basic parameters of the transaction before it takes effect.

You can try them for example by first executing a transaction to have a transaction hash:

`$ seth send $COL1 'transfer(address, uint)'` [ `0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359`](https://etherscan.io/address/0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359) `$(seth --to-uint256 $(seth --to-wei 0.1 ether))`

Output:

```bash
seth-send: Published transaction with 68 bytes of calldata.
seth-send: 0x58ba3980775741aecaf8435646a003bff3395d7d4e00c8f7a32ad1fa0ce64e01
seth-send: Waiting for transaction receipt....
seth-send: Transaction included in block 9704345.
```

Now you can try the discussed commands use your own tx hash from the previous tx:

`$ seth receipt 0x58ba3980775741aecaf8435646a003bff3395d7d4e00c8f7a32ad1fa0ce64e01`

`$ seth tx 0x58ba3980775741aecaf8435646a003bff3395d7d4e00c8f7a32ad1fa0ce64e01`

These both generate a pretty long output, but we can filter each query with an optional extra parameter. For example let's see, how accurate was our previous estimation for the gas consumption it was perfectly accurate:

`$ seth receipt 0x58ba3980775741aecaf8435646a003bff3395d7d4e00c8f7a32ad1fa0ce64e01 gasUsed`

Output:  
`37240`

### Additional Resources

This guide was written based on the official documentation in the Github repository of Seth. You can find additional information over there: [https://github.com/dapphub/dapptools/tree/master/src/seth](https://github.com/dapphub/dapptools/tree/master/src/seth)

### Known Issues

- Issues with MacOS Mojave


Look up parameters for different collateral types in the system

Collateral Types


# Collateral types

Use the `'mcd:cdpType'` service to look up parameters for different collateral types in the system. In the code, this is called [CdpTypeService](https://github.com/makerdao/dai.js/tree/dev/packages/dai-plugin-mcd/src/CdpTypeService.js).

```javascript
const service = maker.service('mcd:cdpType');
```

## Properties

### cdpTypes

This is a list of [collateral type instances](cdptypeservice.md#collateral-type-instances), initialized during `Maker.create`.

```javascript
service.cdpTypes.forEach((type) => console.log(type.ilk));
// ETH-A
// BAT-A
// USDC-A
```

## Instance methods

### getCdpType()

Return the [collateral type instance](cdptypeservice.md#collateral-type-instances) for the specified currency and/or [ilk](cdptypeservice.md#ilk).

```javascript
// this will error if more than one type is defined for ETH
const type = service.getCdpType(ETH);

// disambiguate using the ilk name string:
const ethA = service.getCdpType(null, 'ETH-A');
```

## 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 [currency ratio](currency-units.md). See "A note on caching" above.

```javascript
console.log(type.price.toString()); // "9000.01 ETH/USD"
```

#### 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 [base rate](systemdataservice.md#getannualbaserate), 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:

```javascript
vault.reset();
await vault.prefetch();
```

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

```javascript
service.resetAllCdpTypes();
await service.prefetchAllCdpTypes();
```


These are useful for managing precision, keeping track of units, and passing in wei values

Currency Units


# Currency units

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:

- **toNumber**: return the raw JavaScript value. This may fail for very large numbers.
- **toBigNumber**: return the raw value as a [BigNumber](https://github.com/MikeMcl/bignumber.js).
- **isEqual**: compare the values and symbols of two different instances.
- **toString**: show the value in human-readable form, e.g. "500 USD/ETH".

```javascript
import Maker from '@makerdao/dai';

// Multi-Collateral Dai

import { ETH, BAT, DAI } from '@makerdao/dai-plugin-mcd';

const maker = await Maker.create(...);
const mgr = maker.service('mcd:cdpManager');

// lock BAT into a new vault and draw Dai
const vault = await mgr.openLockAndDraw(
  'BAT-A',
  BAT(100),
  DAI(100)
);

// Single-Collateral Sai

const {
  MKR,
  SAI,
  ETH,
  WETH,
  PETH,
  USD_ETH,
  USD_MKR,
  USD_SAI
} = Maker;

// These are all identical:

// each method has a default type
cdp.lockEth(0.25);
cdp.lockEth('0.25');

// you can pass in a currency unit instance
cdp.lockEth(ETH(0.25));

// currency units have convenient converter methods
cdp.lockEth(ETH.wei(250000000000000000));

const eth = ETH(5);
eth.toString() == '5.00 ETH';

const price = USD_ETH(500);
price.toString() == '500.00 USD/ETH';

// multiplication handles units
const usd = eth.times(price);
usd.toString() == '2500.00 USD';

// division does too
const eth2 = usd.div(eth);
eth2.isEqual(eth);
```

If you would like to use these helper classes outside of Dai.js, check out [@makerdao/currency](https://github.com/makerdao/currency).


Getting Started


# Getting started

## **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.

```javascript
import Maker from '@makerdao/dai';
// or
const Maker = require('@makerdao/dai');
```

Multi-Collateral Dai support in Dai.js is implemented as a [plugin](maker/plugins.md). This may change in the future. The MCD Plugin is also available as an [npm](https://www.npmjs.com/package/@makerdao/dai-plugin-mcd) package and its source code can be found on [Github](https://github.com/makerdao/dai.js/tree/dev/packages/dai-plugin-mcd).

`npm install @makerdao/dai-plugin-mcd`

```javascript
import { McdPlugin } from '@makerdao/dai-plugin-mcd';
// or
const { McdPlugin } = require('@makerdao/dai-plugin-mcd');
```

Note the `.default` at the end of the line when using `require`.

**UMD**

This library is also usable as a [UMD module](https://github.com/umdjs/umd), which you can build with `npm run build:frontend`.

```javascript
<script src="./dai.js" />

<script>
// once the script loads, window.Maker is available
</script>
```

## **Quick Examples**

### Look up information about a vault

This code uses [`getCdpIds`](the-mcd-plugin.md#getcdpids) to look up a vault that was created in the [Oasis Borrow](https://oasis.app/borrow) 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.

```javascript
// you provide these values
const infuraKey = 'your-infura-api-key';
const ownerAddress = '0xf00...';

const maker = await Maker.create('http', {
  plugins: [McdPlugin],
  url: `https://mainnet.infura.io/v3/${infuraKey}`
});

const manager = maker.service('mcd:cdpManager');
const proxyAddress = maker.service('proxy').getProxyAddress(ownerAddress);
const data = await manager.getCdpIds(proxyAddress); // returns list of { id, ilk } objects
const vault = await manager.getCdp(data[0].id);

console.log([
  vault.collateralAmount, // amount of collateral tokens
  vault.collateralValue,  // value in USD, using current price feed values
  vault.debtValue,        // amount of Dai debt
  vault.collateralizationRatio, // collateralValue / debt
  vault.liquidationPrice  // vault becomes unsafe at this price
].map(x => x.toString());
```

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

```javascript
import Maker from '@makerdao/dai';
import { McdPlugin, ETH, DAI } from '@makerdao/dai-plugin-mcd';

// you provide these values
const infuraKey = 'your-infura-api-key';
const myPrivateKey = 'your-private-key';

const maker = await Maker.create('http', {
  plugins: [McdPlugin],
  url: `https://mainnet.infura.io/v3/${infuraKey}`,
  privateKey: myPrivateKey,
});

// verify that the private key was read correctly
console.log(maker.currentAddress());

// make sure the current account owns a proxy contract;
// create it if needed. the proxy contract is used to
// perform multiple operations in a single transaction
await maker.service('proxy').ensureProxy();

// use the "vault manager" service to work with vaults
const manager = maker.service('mcd:cdpManager');

// ETH-A is the name of the collateral type; in the future,
// there could be multiple collateral types for a token with
// different risk parameters
const vault = await manager.openLockAndDraw('ETH-A', ETH(50), DAI(1000));

console.log(vault.id);
console.log(vault.debtValue); // '1000.00 DAI'
```

In the next section, learn more about how to configure the Maker instance with `Maker.create`. Or jump to learning more about [accounts](advanced-configuration/using-multiple-accounts.md), [vaults](the-mcd-plugin.md), [proxies](advanced-configuration/using-ds-proxy.md), and [currency units](currency-units.md).

## Integration Examples

For larger examples of integrating this library, check out this [repo](https://github.com/makerdao/integration-examples) and the [Dai react template](https://github.com/ethanbennett/dai-react-template).


Dai.js service to work with the Dai Savings Rate system

Dai Savings Rate


# Dai Savings Rate

Use the `'mcd:savings'` service to work with the Dai Savings Rate system. In the code, this is called [SavingsService](https://github.com/makerdao/dai.js/blob/dev/packages/dai-plugin-mcd/src/SavingsService.js).

```javascript
const service = maker.service('mcd:savings');
```

## Instance methods

All the methods below are asynchronous. `join`, `exit`, and `exitAll` use a [proxy contract](advanced-configuration/using-ds-proxy.md).

### join(amount)

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

```javascript
await service.join(DAI(1000));
```

### 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 [current address](advanced-configuration/using-multiple-accounts.md). 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.


Dai.js service to look up system-wide parameters

System data


# System data

Use the `mcd:systemData` service to look up system-wide parameters. In the code, this is called [SystemDataService](https://github.com/makerdao/dai.js/blob/dev/packages/dai-plugin-mcd/src/SystemDataService.js).

```javascript
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.

```javascript
const base = await service.getAnnualBaseRate();
```

### getSystemWideDebtCeiling()

Returns the debt ceiling for the entire system.

```javascript
const line = await service.getSystemWideDebtCeiling();
```

### isGlobalSettlementInvoked()

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

```javascript
const dead = await service.isGlobalSettlementInvoked();
```


This intermediary contract allows the use of incrementing integer IDs for vaults, familiar to users of Single-Collateral Sai, as well as other conveniences

Vault Manager


# Vault manager

The vault manager works with vaults that are owned by the [CdpManager](https://github.com/makerdao/dss-cdp-manager/) contract, which is also used by Oasis Borrow. This intermediary contract allows the use of incrementing integer IDs for vaults, familiar to users of Single-Collateral Sai, as well as other conveniences.

In the code, this is called [CdpManager](https://github.com/makerdao/dai.js/blob/dev/packages/dai-plugin-mcd/src/CdpManager.js).

```javascript
const mgr = maker.service('mcd:cdpManager');
```

## Instance methods

The methods below are all asynchronous.

### getCdpIds()

Return an array describing the vaults owned by the specified address. Note that if the vaults were created in Oasis Borrow, the address of the proxy contract should be used.

```javascript
const proxyAddress = await maker.service('proxy').currentProxy();
const data = await mgr.getCdpIds(proxyAddress);
const { id, ilk } = data[0];
// e.g. id = 5, ilk = 'ETH-A'
```

### getCdp()

Get an existing vault by its numerical ID. Returns a [Vault instance](the-mcd-plugin.md#vault-instances).

```javascript
const vault = await mgr.getCdp(111);
```

### open()

Open a new vault with the specified [collateral type](cdptypeservice.md). Will create a [proxy](advanced-configuration/using-ds-proxy.md) if one does not already exist. Returns a [Vault instance](the-mcd-plugin.md#vault-instances). Works with the [transaction manager](advanced-configuration/transactions.md).

```javascript
const txMgr = maker.service('transactionManager');
const open = await mgr.open('ETH-A');
txMgr.listen(open, {
  pending: (tx) => console.log('tx pending: ' + tx.hash),
});
const vault = await open;
```

### openLockAndDraw()

Open a new vault, then lock and/or draw in a single transaction. Will create a [proxy](advanced-configuration/using-ds-proxy.md) if one does not already exist. Returns a [Vault instance](the-mcd-plugin.md#vault-instances).

```javascript
const vault = await mgr.openLockAndDraw('BAT-A', BAT(1000), DAI(100));
```

## Vault instances

In the code, these are called [ManagedCdp](https://github.com/makerdao/dai.js/blob/dev/packages/dai-plugin-mcd/src/ManagedCdp.js).

### Properties

**A note on 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:

```javascript
vault.reset();
await vault.prefetch();
```

#### collateralAmount

The amount of collateral tokens locked, as a [currency unit](currency-units.md).

#### collateralValue

The USD value of collateral locked, given the current price according to the price feed, as a [currency unit](currency-units.md).

#### debtValue

The amount of Dai drawn, as a [currency unit](currency-units.md).

#### liquidationPrice

The USD price of collateral at which the Vault becomes unsafe.

#### isSafe

Whether the Vault is currently safe or not.

### Instance methods

All of the methods below are asynchronous and work with the [transaction manager](advanced-configuration/transactions.md). Amount arguments should be [currency units](currency-units.md), e.g.:

```javascript
import { ETH, DAI } from '@makerdao/dai-plugin-mcd';

await vault.lockAndDraw(ETH(2), DAI(20));
```

#### lockCollateral(amount)

Deposit the specified amount of collateral.

#### drawDai(amount)

Generate the specified amount of Dai.

#### lockAndDraw(lockAmount, drawAmount)

Deposit some collateral and generate some Dai in a single transaction.

#### wipeDai(amount)

Pay back the specified amount of Dai.

#### wipeAll()

Pay back all debt. This method ensures that dust amounts do not remain.

#### freeCollateral(amount)

Withdraw the specified amount of collateral.

#### wipeAndFree(wipeAmount, freeAmount)

Pay back some debt and withdraw some collateral in a single transaction.

#### wipeAllAndFree(freeAmount)

Pay back all debt, ensuring dust amounts do not remain, and withdraw a specified amount of collateral in a single transaction.

#### give(address)

Transfer ownership of this vault to `address`. Note that if the new owner plans to use this vault with Oasis Borrow, it should be transferred to their proxy with [giveToProxy](the-mcd-plugin.md#givetoproxy-address) instead.

#### giveToProxy(address)

Look up the proxy contract owned by `address` and transfer ownership of this vault to that proxy.


A Keeper to facilitate Emergency Shutdown

Cage Keeper


# Cage Keeper

## Introduction

The `cage-keeper` is used to help facilitate [Emergency Shutdown](https://blog.makerdao.com/introduction-to-emergency-shutdown-in-multi-collateral-dai/) of the [Maker Protocol](https://github.com/makerdao/dss). 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 [(ESM)](https://github.com/makerdao/esm) 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 [Maker Protocol 101](/documentation/maker-protocol-101) as well as a more thorough, [technical description](/documentation/introduction-to-es-module). Functions mentioned are from the implementation contained by the `End` contract, which is [located here](https://github.com/makerdao/dss/blob/master/src/end.sol).

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

- `urn` = Vault
- `ilk` = Collateral Type

## Architecture

![](/images/documentation/cage2.png)

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:

```bash
git clone https://github.com/makerdao/cage-keeper.git
cd cage-keeper
git submodule update --init --recursive
./install.sh
```

For some known Ubuntu and macOS issues see the [pymaker](https://github.com/makerdao/pymaker) README.

### Sample Startup Script

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

```bash
#!/bin/bash
/full/path/to/cage-keeper/bin/cage-keeper \
    --rpc-host 'sample.ParityNode.com' \
    --network 'kovan' \
    --eth-from '0xABCAddress' \
    --eth-key 'key_file=/full/path/to/keystoreFile.json,pass_file=/full/path/to/passphrase/file.txt' \
    --vat-deployment-block 14374534
```

## Testing

**Prerequisites:**

- Download [docker and docker-compose](https://www.docker.com/get-started)

This project uses [pytest](https://docs.pytest.org/en/latest/) 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:**

```bash
pip3 install -r requirements-dev.txt
```

**You can then run all tests with**:

```bash
./test.sh
```

## License

See [COPYING](https://github.com/makerdao/auction-keeper/blob/master/COPYING) file

## Support

If you have questions regarding Cage Keepers, please reach out to us on the [\#keeper](https://chat.makerdao.com/channel/keeper) channel on [**chat.makerdao.com**](http://chat.makerdao.com/).


Keeper that lifts the hat and streamlines executive actions

Chief Keeper


# Chief Keeper

## Introduction

The `chief-keeper` monitors and interacts with [DSChief](https://github.com/dapphub/ds-chief) and DSSSpells, which is the executive voting contract and a type of proposal object of the [Maker Protocol](https://github.com/makerdao/dss).

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
- `lift`s the hat for the spell `yay` most favored `approvals[yay]`
- Schedules spells in the GSM by calling `DSSSpell.schedule()`
- Executes spells after their `eta` has elapsed in the GSM by calling `DSSSpell.cast()`

#### Review

The following section assumes familiarity with the [DSChief](https://github.com/dapphub/ds-chief), DSSSpells, and [DSPause](https://github.com/dapphub/ds-pause) Governance Security Module, as well as the processes within [MakerDAO Governance](https://community-development.makerdao.com/governance).

## Architecture

![alt text](https://github.com/makerdao/chief-keeper/raw/master/operation.jpeg)

`chief-keeper` interacts directly with the `DS-Chief` and `DSSSpell`s.

## 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:

- [Python v3.6.6](https://www.python.org/downloads/release/python-366/)
- [virtualenv](https://virtualenv.pypa.io/en/latest/)
  - 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:

```bash
git clone https://github.com/makerdao/chief-keeper.git
cd chief-keeper
git submodule update --init --recursive
./install.sh
```

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 [pymaker](https://github.com/makerdao/pymaker) README.

#### Sample Startup Script

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

```bash
#!/bin/bash
/full/path/to/chief-keeper/bin/chief-keeper \
    --rpc-host 'sample.ParityNode.com' \
    --network 'kovan' \
    --eth-from '0xABCAddress' \
    --eth-key 'key_file=/full/path/to/keystoreFile.json,pass_file=/full/path/to/passphrase/file.txt' \
    --chief-deployment-block 14374534
```

## Testing

- Download [docker and docker-compose](https://www.docker.com/get-started)

This project uses [pytest](https://docs.pytest.org/en/latest/) 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:

```bash
pip3 install -r requirements-dev.txt
```

You can then run all tests with:

```bash
./test.sh
```

## Roadmap

- [ ] [Dynamic gas pricing strategy](https://github.com/makerdao/market-maker-keeper/blob/master/market_maker_keeper/gas.py)

### License

See [COPYING](https://github.com/makerdao/chief-keeper/blob/master/COPYING) file.

## Support

If you have questions regarding Cage Keepers, please reach out to us on the [\#keeper](https://chat.makerdao.com/channel/keeper) channel on [**chat.makerdao.com**](http://chat.makerdao.com/).


Keeper that can be used out of the box to participate in wildly volatile markets

Simple Arbitrage Keeper


# Simple Arbitrage Keeper

## Overview

Typically in the form of an automated bot, Keepers are external actors that participate in [market making](https://github.com/makerdao/market-maker-keeper), [auctions](https://github.com/makerdao/auction-keeper), [market arbitrage](https://github.com/makerdao/arbitrage-keeper), and system upkeep within the Maker protocol and the greater Ethereum ecosystem. Under a pure economic assumption, they are solely incentivized by profits or a vested interest. However, their activity provides indirect services such as increased liquidity and price consistency across various financial markets. This guide presents a simple arbitrage keeper, and structure thereof, that can be used out of the box to participate in wildly volatile markets. The purpose of the guide is to motivate the user in improving its functionality to participate in less volatile markets, leading to a more efficient financial ecosystem.

### Learning objectives

By reading this guide, you’ll gain:

- Better understanding of Arbitrage, how it is achieved and the role it plays in financial markets
- An overview of the simple arbitrage keeper and common structure across the Maker Keeper framework
- Insight into the operation of the simple arbitrage keeper and ways to improve its code

### Pre-requisites

- At least Python 3.6.2 and some python experience
- Linux, macOS, or Cygwin on Windows
- Some general experience with Ethereum Development account management, contract interaction, node hosting

### Guide

#### Introduction to Arbitrage

Arbitrage is the process of simultaneously purchasing an asset on one exchange and selling a similar, if not identical, asset on another exchange at a higher price. Conceptually, this trading strategy can be broken down into two legs, the first buying leg and the second selling leg. As the timestamp of these legs converge, the risk of asset exposure approaches zero. For example, if both trades are not executed in perfect synchrony, there is a chance that the second trade is completed by another actor, forcing the arbitrageur to hold an asset until another opportunity arises.

With advancement in technology, this trading strategy is typically automated and can detect, as well as, profit from price deviations in a matter or seconds. Arbitrage opportunities exist because of [market inefficiencies](https://www.investopedia.com/terms/i/inefficientmarket.asp), such as a temporary shortage of liquidity. As a result, arbitrage provides a mechanism to ensure prices on one exchange/market do not deviate far from the [fair value](https://www.investopedia.com/terms/f/fairvalue.asp). [1](https://www.investopedia.com/terms/a/arbitrage.asp)

#### System Process Structure

![](/images/documentation/arb.jpeg)

**Operation of the Simple Arbitrage Keeper**

The [simple-arbitrage-keeper](https://github.com/makerdao/simple-arbitrage-keeper) is an arbitrage keeper for OasisDex and Uniswap. Given a minimum profit per trade and maximum trade size, as defined by the user and in units of `entry_token`, the Keeper will scan for arbitrage opportunities. When running, it monitors the `arb_token/entry_token` price on both exchanges, and when a discrepancy is detected, it executes an atomic multi-step trade in a single Ethereum transaction. The multi-step trade is made up of two legs: the first leg is the purchasing of `arb_token` with the `entry_token` on the `start_exchange`, while the second leg is the selling of the `arb_token` with the `entry_token` on the `end_exchange`. The type of `entry_token` and `arb_token` is typically of a stable and volatile type, respectively; since arbitrage opportunities can be scarce, the Keeper sometimes rests in a default state, holding the `entry_token` for extended periods of time as it looks for new opportunities. Exposure only to a stable token is especially important in this default state. If any leg of the trade fails, the entire trade reverts, thereby upholding the "risk-free" attribute of true arbitrage.

It inherits a system structure that is consistent with other keepers in the Maker Keeper Framework. Apart from libraries typical to python projects, it relies on [pymaker](https://github.com/makerdao/pymaker) and [pyexchange](https://github.com/makerdao/pyexchange), both of which are highly applicable Python APIs for the Maker Protocol Contracts and cryptocurrency exchanges, respectively. As can be seen in the flowchart, the ‘Lifecycle box’ is a [pymaker utility class](https://github.com/makerdao/pymaker/blob/master/pymaker/lifecycle.py#L38) that helps define the proper life cycle of a keeper; it consists of keeper startup, timers and/or subscriptions to Web3 events, and a keeper shutdown phase. The ‘Process block’ box is executed when the Keeper's node receives a new block. It generally contains the logic to query the blockchain state, evaluate any profit opportunities, and when applicable, publish a transaction.

**The step for each process in simple-arbitrage-keeper is as follows:**

1. Keeper Entry -&gt; enter into SimpleArbitrageKeeper class
2. Startup -&gt; make all necessary approvals between tokens, exchanges, and tx-manager
3. Evaluate Market -&gt; pull price data from Oasis REST API and Uniswap exchange contracts
4. Profitable Opportunity Found? -&gt;check if profit opportunity exists with a given max engagement and min profit
5. Execute multi-step trade -&gt; with use of TxManager, buy asset on exchange A and sell on exchange B within one Ethereum transaction

#### Documentation

General high level information and comments for each class/method are in the [simple-arbitrage-keeper github repository](https://github.com/makerdao/simple-arbitrage-keeper).

#### Startup on Kovan

The usage of the bot can be found in the [Usage section](https://github.com/makerdao/simple-arbitrage-keeper#usage) of the README. Here are some preparation steps in running on Kovan:

To operate the keeper, call the `/bin/simple-arbitrage-keeper` script with the required arguments. This adds the pyexchange and pymaker modules to the python path and initializes the SimpleArbitrageKeeper class. It's convenient to write a shell script that can be easily rerun after argument changes, but before we begin, let's prepare our Keeper ethereum address, deploy our TxManager, find the Uniswap exchange addresses and MatchingMarket address.

**Keeper Installation**

This project uses Python 3.6.2. In order to clone the project and install required third-party packages please execute:

```bash
$ git clone https://github.com/makerdao/simple-arbitrage-keeper.git
$ cd simple-arbitrage-keeper
$ git submodule update --init --recursive
$ pip3 install -r requirements.txt
```

For some known Ubuntu and macOS issues see the [pymaker README](https://github.com/makerdao/pymaker).

**Install the DappHub Toolkit**

If you are running Linux or macOS you can take advantage of our all in one installer.

```bash
$ curl https://dapp.tools/install | sh
```

If you're having issues with installation, head over to the ['Manual Installation' section](http://dapp.tools/)

**Keeper Ethereum Address**

Your Keeper will publish transactions through this address. Your ethereum address needs to be accessible by [seth](https://github.com/dapphub/dapptools/tree/master/src/seth), in order to deploy TxManager through [dapp.tools](http://dapp.tools/). Furthermore, when the Keeper is deployed and in operation, this address must contain some ETH for transaction costs as well as an amount of entry-tokens equal to the max-engagement set by the User. Follow [these instructions](https://github.com/dapphub/dapptools/tree/master/src/seth#key-management-and-signing) to ensure seth can see your keystore and passphrase files.

If you'd like to start from scratch, [install geth](https://github.com/ethereum/go-ethereum/wiki/Installation-Instructions-for-Mac) and use `geth account new`, to create a new account, set a passphrase, and place the passphrase into a `<address>.txt` file in the `~/Library/Ethereum/passphrase/` directory; the corresponding keystore file can be found in the `~/Library/Ethereum/keystore/` directory. Both the keystore and passphrase files will later be passed into the Keeper as an argument. Make a note of your Keeper Ethereum Address, its keystore file location and passphrase file location.

**Deploy TxManager**

A [TxManager](https://github.com/makerdao/tx-manager) must be deployed and linked with the Keeper ethereum address in order to bundle multiple contract calls in a single ethereum transaction; this is what we call an atomic transaction, where the entire call set is successful, or the state remains unaffected. Once the DappHub Toolkit is installed, execute the following commands to deploy TxManager:

```bash
$ git clone https://github.com/makerdao/tx-manager.git
$ cd tx-manager
$ dapp update
$ dapp --use solc:0.4.25 build --extract

$ export SETH_CHAIN=kovan
$ export ETH_FROM=<your Keeper Ethereum Address e.g. 0xABC>
$ export ETH_GAS=2000000
$ dapp create TxManager --password /path/to/passphraseOfAddress.txt

```

The output of `dapp create` is the address to your TxManager

**Deploy/Find a parity node**

You need access to a JSON-RPC host that’s connected to a parity node. Unfortunately, Infura APIs are not connected to parity nodes, so you will need to find access to a remote endpoint one example is [https://rivet.cloud/](https://rivet.cloud/) or run a node on your local machine. An example of a remote node could be [https://kovan.sampleparitynode.com:8545](https://kovan.sampleparitynode.com:8545/)

**Uniswap Exchange Addresses**

You'll need to find the address to the Uniswap exchange corresponding to the entry-token as well as arb-token. To do that, call the `getExchange(TokenAddress)` at the Uniswap Factory contract to query the exchange addresses. [You can do that here](https://kovan.etherscan.io/address/0xD3E51Ef092B2845f10401a0159B2B96e8B6c3D30#readContract). For example, you can use the Kovan WETH token address and call `getExchange(0xd0A1E359811322d97991E03f863a0C30C2cF029C)`

**Shell Script**

As was mentioned before, let's make a shell script so that it's easy to run this Bot. For example, we're using _Kovan Sai_ for the entry-token since we won't be exposed to the arb token's price exposure in between trades. Moreover, for kovan testing, we will be using the WETH/DAI pair, since liquidity is thin across the Kovan versions of MatchingMarket and Uniswap exchanges. Any `NoneType` errors are likely due to a lack of liquidity on either exchange and can be resolved once liquidity is added. As mentioned earlier, the min-profit and max-engagement arguments define how the keeper will operate. Maximum engagement refers to the amount of entry-tokens you would like to sell within the first leg of the trade, whereas minimum profit refers to the amount of profit gained from executing the arbitrage; both arguments are denominated in entry-tokens and in _units of ether_ in the below script, 1 SAI of min-profit would be 1 SAI. For example, the below script will trade with a max-engagement of 10 SAI, but only if the returned value from the trade results in at least 11 SAI.

Create a file called like below, insert the arguments relevant to your environment, make it executable, then run it!

```bash
$ vim run-simple-keeper-kovan.sh
```

In your run-simple-keeper-kovan.sh file:

```bash
#!/bin/bash
/full/path/to/githubClone/simple-arbitrage-keeper/bin/simple-arbitrage-keeper \
    --rpc-host 'kovan.sampleparitynode.com' \
    --eth-from '0xABC' \
    --eth-key 'key_file=/path/to/keystore.file,pass_file=/path/to/passphrase.txt' \
    --uniswap-entry-exchange '0x47D4Af3BBaEC0dE4dba5F44ae8Ed2761977D32d6' \
    --uniswap-arb-exchange '0x1D79BcC198281C5F9B52bf24F671437BaDd3a688' \
    --oasis-address '0x4A6bC4e803c62081ffEbCc8d227B5a87a58f1F8F' \
    --oasis-api-endpoint 'https://kovan-api.oasisdex.com' \
    --tx-manager '0xABC' \
    --entry-token '0xC4375B7De8af5a38a93548eb8453a498222C4fF2' \
    --arb-token '0xd0A1E359811322d97991E03f863a0C30C2cF029C' \
    --arb-token-name 'WETH' \
    --min-profit 1 \
    --max-engagement 10 \
```

Make your Keeper executable, and run it!

```bash
$ chmod +x run-simple-keeper-kovan.sh
$ ./run-simple-keeper-kovan.sh

```

**Initial Startup**

During the initial startup, several approval transactions will be sent to the tx-manager, and relevant exchanges. When complete, you'll see a “Watching for new blocks” message that indicates that the bot is now looping through the `lifecycle.process_block()` method; following that message and with every new block is a "Best Trade regardless of profit" message that acts as a "heartbeat" to the Keeper.

```bash
Kentons-Macbook:scripts kentonprescott$ ./run-simple-arbitrage-keeper-mainnet-XYZ-XYZ.sh
2019-10-19 17:21:57,463 INFO     Keeper connected to RPC connection https://...
2019-10-19 17:21:57,463 INFO     Keeper operating as 0xABCD
2019-10-19 17:21:58,523 INFO     Executing keeper startup logic
2019-10-19 17:22:04,820 INFO     Watching for new blocks
2019-10-19 17:22:13,983 INFO     Best trade regardless of profit/min-profit: -1.243077085275947008 DAI from Uniswap to Oasis
```

**Nominal Operation**

After the initial approval phase the Keeper's startup will look something like the below output and will continue to print "Best Trade ... " messages with every new block witnessed. When the keeper publishes a transaction, all relevant info will be logged and printed to the console. Finally, when you’d like to shut down the keeper, simply click CTRL-C, and it will gracefully shutdown.

### Troubleshooting

During keeper operation, if the following error is shown, just CTRL-C and rerun:

```bash
ValueError: {'code': -32010, 'message': 'Transaction with the same hash was already imported.'}
```

### Next steps

#### Improvements

Here are some suggestions to improve the usability, versatility, and profitability of this keeper. We hope that everyone tinkers with the parameters, runs the keeper for their own benefit, and eventually upgrades the bot to meet their risk tolerance and profit appetite.

- Develop unit tests for each method
- Use the Uniswap Factory contract to query the _uniswap-entry-exchange_ and _uniswap-arb-exchange_ addresses rather than requiring it as an argument
- Rather than the default gas price implement a [dynamic gas price strategy](https://github.com/makerdao/market-maker-keeper/blob/master/market_maker_keeper/gas.py#L24)
- Increase scope
  - Monitor more than one pair
  - Monitor more than two decentralized exchanges
  - Implement support for centralized exchanges
  - Increase number of intermediary arb tokens
    - e.x. DAI → WETH → BAT → DAI
    - [https://math.stackexchange.com/a/94420](https://math.stackexchange.com/a/94420)
    - [https://www.dailycodingproblem.com/blog/how-to-find-arbitrage-opportunities-in-python/](https://www.dailycodingproblem.com/blog/how-to-find-arbitrage-opportunities-in-python/)
- Improve efficiency of TxManager
  - Do we really need to send all of our token balance to the contract during every atomic transaction?
- Read the state of the MatchingMarket OasisDex contract rather than using the Oasis REST API
  - To save gas, [get all active orders](https://github.com/makerdao/pymaker/blob/master/pymaker/oasis.py#L613) and [take specific orders](https://github.com/makerdao/pymaker/blob/master/pymaker/oasis.py#L428) by ID rather than use `MatchingMarket.offer(...)` and the on-chain matching engine
- Send trade updates through a text/email Python API

### Resources

- [https://github.com/makerdao/market-maker-keeper](https://github.com/makerdao/market-maker-keeper)
- [https://github.com/makerdao/arbitrage-keeper](https://github.com/makerdao/arbitrage-keeper)
- [https://github.com/makerdao/tx-manager](https://github.com/makerdao/tx-manager)
- [https://github.com/makerdao/pymaker](https://github.com/makerdao/pymaker)
- [https://github.com/makerdao/pyexchange](https://github.com/makerdao/pyexchange)


The MCD Changelog provides valuable information for developers interacting with MCD deployments

Multi-Collateral DAI Public Releases


# Multi-Collateral DAI Public Releases

## [Changelog.makerdao.com ](https://changelog.makerdao.com/)

### The MCD Changelog provides valuable information for developers interacting with MCD deployments. This includes deployments on the following networks:

- Main Ethereum network
- Kovan test network
- Rinkeby test network
- Ropsten test network

### **Additionally, each release includes the following information:**

- Link to corresponding main network or test network release
- Contract addresses
- ABIs
- Links to GitHub repositories with changelogs
  - MCD CDP Portal
  - Dai.js
  - Governance Dashboard
  - DSS deploy scripts
  - MCD CLI

### Latest Kovan release <a id="latest-kovan-release"></a>

- [Permanent link to the latest Kovan release](https://changelog.makerdao.com/releases/latest)


SCD to MCD Migration


# SCD to MCD Migration

- **Contract Name:** scd-mcd-migration.sol
- **Type/Category:** Migration
- \*\*\*\*[**Associated MCD System Diagram**](https://github.com/makerdao/dss/wiki#system-architecture)
- \*\*\*\*[**Contract Source**](https://github.com/makerdao/scd-mcd-migration/blob/master/src/ScdMcdMigration.sol)
- \*\*\*\*[**Etherscan**](https://etherscan.io/address/0xc73e0383f3aff3215e6f04b0331d58cecf0ab849)

## 1. Introduction (Summary)

The Migration contract's purpose is to allow moving SAI and CDPs from the SCD system to the MCD system, thus becoming DAI and Vaults. It also allows users to move SAI/DAI in both directions should they want to exit MCD and go back to SCD.

![](/images/documentation/scd-mcd.png)

![](/images/documentation/scd-mcd2%20%281%29.png)

## 2. Contract Details

#### Key Functionalities

`swapSaiToDai` - Takes Sai ERC-20 DAI from Single Collateral System returns DAI ERC-20 DAI from MultiCollateral System.

`swapDaiToSai` - Takes DAI ERC-20 DAI from MultiCollateral System returns Sai ERC-20 DAI from Single Collateral System

`migrate` - Moves a Vault from SCD to MCD by closing the SCD one and opening a corresponding MCD one.

#### Storage

`tub`: SCD Tub contract address

`vat`: MCD Vat Contract address

`cdpManager`: MCD CDP manager

`saiJoin`: SAI collateral adapter for MCD

`wethJoin`: WETH collateral adapter for MCD

`daiJoin`: DAI join adapter for MCD

## 3. Key Mechanisms & Concepts

**Overall this contract has two primary purposes:**

1. Two-way exchange for SAI and DAI
2. One-way transfer of Vaults

#### 1. `constructor` (setup)

#### 2. `swapSaiToDai`

Users of the current DAI system will want to move to the new MCD system. This function allows DAI holders to seamlessly convert their DAI. They will need to `approve` the migration contract on the SAI ERC-20 contract so that it can perform the `transferFrom`. The migration contract holds a Vault in MCD that takes SAI as collateral and allows it to exit MCD-DAI, which it does and returns to the `msg.sender`.

#### 3. `swapDaiToSai`

In case a user wants to go back to SAI, this function allows them to turn in their DAI in exchange for SAI. This requires the user `approve`s the migration contract on the DAI ERC-20 contract so that it can `transferFrom` then `join` the DAI back into MCD. This pays back the "debt" in its SAI-MCD Vault and allows it to retrieve the SAI "collateral" and return it to the `msg.sender`.

#### 4. `migrate`

This function is meant to be used in combination with the `MigrationProxyActions` as it requires the migration contract owns the SCD-Vault `cup` already and that the migration contract has enough MKR to pay the stability fees. The `MigrationProxyActions` `migrate` function `transferFrom`s the `msg.sender` to the migration contract so that the migration contract has enough MKR to pay the stability fee and close the `cup`.

The migration contract first draws its own SAI out of its MCD contract and uses that to pay back the debt for the `cup` along with the MKR it has from the proxy action to pay the fee. Then it withdraws the PETH as WETH.

Next the migration contract opens a Vault using the MCD CDP manager and `join`s its WETH into its new Vault and withdraws enough DAI from the new Vault and pays back its Vault to compensate for the SAI it drew earlier in this step.

Lastly, the migration contract gives the MCD-Vault to the `msg.sender`.

## 4. Gotchas (Potential source of user error)

- Any special/unique information about the specific contract
- Anything that it may rely on, especially if it is not obvious
- Sources of user error if not explicitly defined

#### `swapSaiToDai`

The `wad` amount has to be below the debt ceiling for both the overall MCD system and the SAI collateral type, otherwise the `frob` will fail. This means that these governance parameters can impact the speed of the transition from SAI to DAI.

#### `swapDaiToSai`

The `wad` amount has to be below the amount of SAI collateral in the migration contract's Vault. If a user with DAI wants to move to SAI but no SAI users have already moved to DAI, then this will fail.

#### `migrate`

Because the migration contract will have to first draw SAI from its MCD collateral, the system will have to be seeded with SAI in the migration contract's Vault in an amount that exceeds the SAI debt for the `cup` being migrated.

If a user holds both a `cup` and SAI, they should decide whether it makes sense to:

1. Pay back the `cup` in SCD, then `migrate` their `cup` to MCD essentially just transfer the collateral to a new MCD Vault.
2. `migrate` their `cup` with the debt in place, then use `swapSaiToDai` to get DAI which they can then use as an ERC-20 or payback their MCD debt.

One additional consideration, to close or migrate a `cup`, a user will have to purchase MKR in order to pay the stability fee and be able to `exit` the SCD system. However, once in MCD, new fees will be accrued and have to be paid in DAI. If a user's converted SAI does not cover their MCD debt + stability fee, they may have to purchase DAI on the open market.

Before SCD shutdown: Users who took out a Vault in SCD and then used the DAI to purchase something will either have to buy SAI on the open market to pay back their SCD debt or they will have to migrate their collateral to MCD.

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

- **Potential for error:** Governance parameters around SAI collateral
  - Collateralization ratio has to be set to a very low number
  - Both `ilks["sai"].duty` and `Jug.base` have to be set to `0` during the migration period
- **Auth errors on Sai Join**
- Excess Sai in MCD i.e. more `cup`s are lost/not migrated than lost/not migrated Sai: results in an auction and possibly MKR auction to cover bad debt.

**Migration**

- Sai debt ceiling to 0
- MCD.ilks sai debt ceiling to SCD.totalDai
- DSR value competitive with Compound to encourage migration


In-line comments on the Maker Protocol's Core Smart Contracts

Smart Contract Annotations


# Smart Contract Annotations

## 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 the developer portal, 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:**

- Highlight terms to display their definitions
  - **Ex:** `ink`, `art`
- Explain various input parameters in-depth
  - **Ex:** Explain the precise role of users defined as `gal` or `guy` within input parameters.
- Link to sections of other smart contracts from where function calls typically originate from
  - **Ex:** `heal` in `Vat` is called from `Vow`
- Additional context to Maker specific design practices that other smart contract developers might not be accustomed to
  - **Ex:** Show the event log signature produced by the `note` modifier on a function.
- Help developers navigate through scenarios that result in calls across multiple smart contracts
  - **Ex:** Keepers participating in collateral auctions kick the process with `bite` on `Cat`, bad debt is settled in `Vat`, accounted for in `Vow`, and a series of transactions on `flip` until they receive collateral they purchased for a discount.
- Superimposing the operational view of the system on all functions will help developers build richer mental models of the Maker Protocol.
  - **Ex:** Annotating a function's `auth` modifier and mentioning the smart contracts authorized to call it.

Annotations will also serve as an open and collaborative discussion layer that helps developers discuss and evolve their understanding of the smart contracts over time.

## Using Hypothesis

[Hypothesis](https://web.hypothes.is/) is a web-based tool that we use to annotate the codebase hosted on our Github org.

### **Example**

Check out the annotations of the **Vat** smart contract [here. ](https://via.hypothes.is/https://github.com/makerdao/dss/blob/master/src/vat.sol)

### Usage

Hypothesis annotations can be viewed by expanding a sidebar on the top right corner of your browser window.

**There are three options to view annotations on a webpage:**

- Install the [chrome extension](https://chrome.google.com/webstore/detail/hypothesis-web-pdf-annota/bjfhmglciegochdpefhhlphglcehbmek) from the web store.
- Follow instructions to setup a [bookmarklet](https://web.hypothes.is/start/)
- Append [https://via.hypothes.is](https://via.hypothes.is/) to a URL.

### **Our Hypothesis Groups:**

- `MakerDAO` restricted group- everyone is allowed to read annotations but only approved members can contribute [here](https://hypothes.is/groups/zy1LApRW/makerdao).
- Public MakerDAO group that is open for everyone to both read and contribute.

### Create a Hypothesis account [here](https://hypothes.is/signup) to get started!


A list of words, terms, variables, functions and more relating to the Maker Protocol

MCD Glossaries


# MCD Glossaries

## 1. [MCD General Glossary of Terms](https://community-development.makerdao.com/makerdao-mcd-faqs/faqs/glossary)

## ​2. MCD Core Smart Contracts Glossary:

### **General**

- `guy`, `usr`: some address
- `wad`: some quantity of tokens, usually as a fixed point integer with 18 decimal places.
- `ray`: a fixed point integer, with 27 decimal places.
- `rad`: a fixed point integer, with 45 decimal places.
- `file`: administer some configuration value

### **Auth**

- `auth`: check whether an address can call this method
- `ward`: an address that is allowed to call auth'ed methods
- `rely`: allow an address to call auth'ed methods
- `deny`: disallow an address from calling auth'ed methods
- `Authority` - checks whether an address can call this method
- `Kiss` - cancels out surplus and on-auction debt

### **Vat (Vault Engine)**

- `gem`: collateral tokens.
- `dai`: stablecoin tokens.
- `sin`: unbacked stablecoin (system debt, not belonging to any `urn`).
- `ilk`: a collateral type.
  - `rate`: stablecoin debt multiplier (accumulated stability fees).
  - `take`: collateral balance multiplier.
  - `Ink`: total collateral balance.
  - `Art`: total normalized stablecoin debt.
- `init`: create a new collateral type.
- `urn`: a specific Vault.
  - `ink`: collateral balance.
  - `art`: normalized outstanding stablecoin debt.
- `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.
- `toll`: modify the collateral multiplier, creating / destroying corresponding collateral.
- `suck`: mint unbacked stablecoin (accounted for with `vice`).
- `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.
- `Line`: the total debt ceiling for all collateral types.
- `dust`: the minimum possible debt of a Vault.
- `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.
  - `calm`: true when the Vault remains under both collateral and total debt ceilings.
  - `cool`: true when the stablecoin debt does not increase.
  - `firm`: true when the collateral balance does not decrease.
  - `safe`: true when the Vault's ratio of collateral to debt is above the collateral's liquidation ratio.
- `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`: the sum of all `dai` (the total quantity of dai issued).
- `vice`: the sum of all `sin` (the total quantity of system debt).
- `ilk.Art`: the sum of all `art` in the `urn`s for that `ilk`.
- `debt`: is `vice` plus the sum of `ilk.Art * ilk.rate` across all `ilk`'s.

#### **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 / can always be transferred to any address by it's owner.

**Other**

- `LogNote`: a general purpose log that can be added to any function from a contract.

### **Jug (Stability Fees)**

#### Structs

`Ilk`: contains two `uint256` values—`duty`, the collateral-specific risk premium, and `rho`, the timestamp of the last fee update

`VatLike`: mock contract to make Vat interfaces callable from code without an explicit dependency on the Vat contract itself

#### Storage

`wards`: `mapping(address => uint)` that indicates which addresses may call administrative functions

`ilks`: `mapping (bytes32 => Ilk)` that stores an `Ilk` struct for each collateral type

`vat`: a `VatLike` that points the the system's [Vat](https://www.notion.so/makerdao/Vat-Core-Accounting-5314995c98e544c4aaa0ebedb01988ad) contract

`vow`: the `address` of the Vow contract

`base`: a `uint256` that specifies a fee applying to all collateral types

#### Administrative

These methods require `wards[msg.sender] == 1` (i.e. only authorized users may call them).

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

`init(bytes32)`: start stability fee collection for a particular collateral type

`file(bytes32, bytes32, uint)`: set `duty` for a particular collateral type

`file(bytes32, data)`: set the `base` value

`file(bytes32, address)`: set the `vow` value

#### Fee Collection Methods

`drip(bytes32)`: collect stability fees for a given collateral type

### **Cat (Liquidations)**

- `mat`: the liquidation ratio
- `chop`: the liquidation penalty
- `lump`: the liquidation quantity, i.e. the fixed debt quantity to be covered by any one liquidation event
- `bite`: initiate liquidation of a Vault
- `flip`: liquidate collateral from a Vault to cover a fixed quantity of debt

### **Vow (Settlement)**

- `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 Vow documentation:**

- `move`: transfers stablecoin between users.
- `kick`: starts an auction.
- `woe`: indicates specifically bad debt, or be used as a variable name for any amount of debt.

### Flipper (Collateral Auctions)

- `wards [usr: address]`, `rely`/`deny`/`auth`: Auth mechanisms
- `Bid`: State of a specific Auction {`bid`, `lot`, `guy`, `tic`, `end`, `usr`, `gal`, `tab`}
  - `bid`: Bid amount (DAI)/ DAI paid
  - `lot`: quantity up for auction / collateral gems for sale
  - `guy`: high bidder (address)
  - `tic`: Bid expiry
  - `end`: when the auction will finish / max auction duration
  - `usr`: address of the Vault being auctioned. Receives gems during the `dent` phase
  - `gal`: recipient of auction income / receives dai income (this is the Vow contract)
  - `tab`: total dai wanted from the auction / total dai to be raised (in flip auction)
- `bids[id: uint]`: storage of all bids
- `vat`: storage of the Vat's address
- `ilk`: id of the Ilk for which the Flipper is responsible
- `beg`: minimum bid increase (default: 5%)
- `ttl`: bid duration (default: 3 hours)
- `tau`: auction length (default: 2 days)
- `kicks`: Total auction count, used to track auction `id`s
- `kick`: function used by `Cat` to start an auction / Put collateral up for auction
- `tick`: restart an auction if there have been 0 bids and the `end` has passed
- `tend`: first phase of an auction. Increasing Dai `bid`s for a set `lot` of Gems
- `dent`: second phase of an auction. Set Dai `bid` for a decreasing `lot` of Gems
- `file`: function used by governance to set `beg`, `ttl`, and `tau`
- `deal`: claim a winning bid / settles a completed auction
- `yank`: used during Global Settlement to move `tend` phase auctions to the `End` by retrieving the collateral and repaying dai to the highest bidder.

### Flapper (Surplus Auctions)

- `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 `Bid`s 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.

### Flopper (Debt Auctions)

- `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 `id`s
- `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

### **End (Global Settlement / Shutdown)**

`cage`: Locks the system and initiates shutdown. This is done by freezing the user-facing actions, canceling `flap` and `flop` auctions, locking the rest of the system's contracts, disabling certain governance actions that could interfere with the settlement process, and starting the cool-down period.

`cage(ilk)`: Tags the Ilk prices / Sets the final price for an ilk (`tag`).

`skim`: Settles a Vault at the tagged price / Cancels owed Dai from the Vault

`free`: Remove (remaining) collateral from a settled Vault. This occurs only after there is no debt in the Vault.

`thaw`: Fixes the Dai supply after all Skims / Fixes the total outstanding supply of stablecoin.

`flow`: Calculates the fixed price for an ilk, possibly adjusting the `cage` price with surplus/deficit.

`pack`: Locks Dai ahead of Cash / Puts some stablecoin into a `bag` in preparation for `cash`.

`cash`: Exchange `pack`ed Dai for collateral / Exchange some Dai from `bag` for a given `gem`, share proportional to `bag` size.

`file`: The Governance configuration—sets various parameter values.

`skip`: optionally cancel live auctions.

#### **Other**

`wards(usr: address)`: Auth Mechanism

`vat`: Vat contract

`cat`: Cat contract

`vow`: Vow contract

`spot`: Spotter contract

`live`: Cage flag

- "Live" contracts have `live` = 1, indicating the system is running normally. Thus, when `cage()` is invoked, it sets the flag to 0. This includes the `End` contract, which means that `cage()` can only be invoked once and the subsequent functions cannot be invoked until we are "dead" and in the End process

`ilk`: A collateral type

`when`: Time of cage / the time of settlement.

`wait`: Processing cooldown duration / the length of processing cooldown.

`debt`: Outstanding Dai after processing / outstanding stablecoin supply, after system surplus/deficit has been absorbed.

`tag`: Cage price / price per collateral type at time of settlement.

`gap`: Collateral shortfall / shortfall per collateral considering undercollateralised Vaults.

`Art`: Total debt per Ilk/outstanding stablecoin debt.

`fix`: Final cash price / the cash price for an ilk (amount per stablecoin).

`bag(usr: address)`: Dai packed for `cash` / nontransferable stablecoins ready to exchange for collateral.

`out`: Cash out / the amount of already exchanged stablecoin for a given address.

`skip`: Optionally cancel live auctions.

`wad`: Some quantity of tokens, usually as a fixed point integer with 10^18 decimal places.

`urn`: A specific Vault.

`tend`: To make a bid, increasing the bid size.

`bid`: The quantity being offered for the `lot`.

`lot`: The quantity up for auction.

`dent`: To make a bid, decreasing the lot size.

### Join (Token Adapters)

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

### Cat (Liquidations)

- `mul(uint, uint)`/`rmul(uint, uint)`: will revert on overflow or underflow
- `bite(bytes32, address)`: will revert if `lot` or `art` are larger than or equal to 2^255.
- `bite`: will not leave a Vault with debt and no collateral.
- `wards`: are allowed to call protected functions (Administration and `cage()`)
- `ilks`: stores `Ilk` structs
  - `Ilk` is the struct with the address of the collateral auction contract (`flip`), the penalty for that collateral to be liquidated (`chop`) and the maximum size of collateral that can be auctioned at once (`lump`).
- `live`: must be `1` for the `Cat` to `bite` (see `cage` in mechanisms)
- `vat`: address that conforms to a `VatLike` interface (see `vat` documentation [TODO - Link] for more info). It is set during the constructor and **cannot be changed**.
- `vow`: address that conforms to a `VowLike` interface (see `vow` documentation [TODO - Link] for more info).

**Events**

- `Bite`: emitted when a `bite(bytes32, address)` is successfully executed. Contains:
  - `ilk`: Collateral
  - `urn`: Vault address
  - `ink`: see `lot` in `bite`
  - `art`: see `art` in `bite`
  - `tab`: see `tab` in `bite`
  - `flip`: address of the auction contract
  - `id`: ID of the auction in the `Flipper`

### Spot (Oracles and Contracts Liaison)

- `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`: the relationship between DAI and 1 unit of value in the price. (Similar to TRFM)

**Collateral**

- Only authorized users can update any variables in contract

### Pot (Savings Dai)

**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`.

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

### Dai (Stablecoin)

`name`: Dai Stablecoin

`symbol`: DAI

`version`: 1

`decimals`: 18

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

`totalSupply`: Total DAI Supply

`balanceOf(usr: address)`: User balance

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

`nonces(usr: address)`: Permit nonce


MKR Module


# MKR Module

- **Contract Name:** token.sol
- **Type/Category:** MKR Module
- [**Associated MCD System Diagram**](https://github.com/makerdao/dss/wiki#system-architecture)
- [**Contract Source**](https://github.com/dapphub/ds-token/blob/master/src/token.sol)
- [**Etherscan**](https://etherscan.io/address/0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2)

## 1. Introduction (Summary)

The MKR Module contains the MKR token, which is a deployed [Ds-Token](https://github.com/dapphub/ds-token) contract. It is an ERC20 token that provides a standard ERC20 token interface. It also contains logic for burning and authorized minting of MKR.

![MKR Interactions with the Maker Protocol](/images/documentation/screen-shot-2019-11-17-at-2.10.06-pm.png)

## 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 [here](https://eips.ethereum.org/EIPS/eip-20).

**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** [**Maker Protocol 101 Presentation**](/documentation/maker-protocol-101)**):**

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


Learm about DSR amd integrate it into your platform

DSR Integration Guide

Learn how to integrate Maker Vaults into your own application

Maker Vault Integration Guide

Take advantage of the pluggable architecture of this library by choosing different implementations for services

Adding a new service


# Adding a new service

## 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 methods.

It can depend on other services through our built-in [dependency injection framework](https://github.com/makerdao/dai.js/tree/dev/packages/services-core), and can also be configured through the Maker config file / config options.

## Steps to add a new service

{% hint style="info" %}
The information below is written for developers who want to add to dai.js, but you can also add services through the use of [plugins](../maker/plugins.md).
{% endhint %}

Here are the steps to add a new service called ExampleService:

1 In the src directory, create an ExampleService.js file in one of the subdirectories.

2 In src/config/DefaultServiceProvider.js, import ExampleService.js and add it to the services array

3 Create a class called ExampleService in ExampleService.js

4 The service must extend one of:

- PrivateService - requires both a network connection and authentication
- PublicService - requires just a network connection
- LocalService - requires neither

See the Service Lifecycle section below for more info

5 In the constructor, call the parent class's constructor with the following arguments:

- The name of the service. This is how the service can be referenced by other services
- An array of the names of services to depend on

6 Add the necessary public methods

```javascript
//example code in ExampleService.js for steps 3-6
import PublicService from '../core/PublicService';

export default class ExampleService extends PublicService {
    constructor (name='example') {
        super(name, ['log']);
    }

    test(){
        this.get('log').info('test');
    }
```

7 If your service will be used to replace a default service the full list of default service roles can be found in src/config/ConfigFactory, then skip this step. Otherwise, you'll need to add your new service role e.g. "example" to the ServiceRoles array in src/config/ConfigFactory.

8 Create a corresponding ExampleService.spec.js file in the test directory. Write a test in the test file that creates a Maker object using your service.

```javascript
//example code in ExampleService.spec.js for step 8
import Maker from '../../src/index';

//step 8: a new service role ('example') is used
test('test 1', async () => {
  const maker = await Maker.create('http', { example: 'ExampleService' });
  const exampleService = customMaker.service('example');
  exampleService.test(); //logs "test"
});

//step 8: a custom service replaces a default service (Web3)
test('test 2', async () => {
  const maker = await Maker.create('http', { web3: 'MyCustomWeb3Service' });
  const mycustomWeb3Service = maker.service('web3');
});
```

9 Optional Implement the relevant service lifecycle functions initialize(), connect(), and authenticate(). See the Service Lifecycle section below for more info

10 Optional Allow for configuration. Service-specific settings can be passed into a service by the Maker config file or config options. These service-specific settings can then be accessed from inside a service as the parameter passed into the initialize function see the Service Lifecycle section below

```javascript
//step 10: in ExampleService.spec.js
const maker = await Maker.create('http', {
    example: ["ExampleService", {
    exampleSetting: "this is a configuration setting"
  }]
});

//step 10: accessing configuration settings in ExampleService.js
initialize(settings) {
  if(settings.exampleSetting){
    this.get('log').info(settings.exampleSetting);
  }
}
```

## Service Lifecycle

The three kinds of services mentioned in step 4 above follow the following state machine diagrams in the picture below.

To specify what initializing, connecting and authenticating entails, implement the initialize(), connect(), and authenticate() functions in the service itself. This will be called while the service's manager brings the service to the corresponding state.

```javascript
//example initialize() function in ExampleService.js
  initialize(settings) {
    this.get('log').info('ExampleService is initializing...');
    this._setSettings(settings);
  }
```

A service will not finish initializing/connecting/authenticating until all of its dependent services have completed the same state if applicable - for example a LocalService is considered authenticated/connected in addition to initialized, if it has finished initializing. The example code here shows how to wait for the service to be in a certain state.

```javascript
const maker = await Maker.create('http', { example: 'ExampleService' });
const exampleService = customMaker.service('example');

//wait for example service and its dependencies to initialize
await exampleService.manager().initialize();

//wait for example service and its dependencies to connect
await exampleService.manager().connect();

//wait for example service and its dependencies to authenticate
await exampleService.manager().authenticate();

//can also use callback syntax
exampleService.manager().onConnected(() => {
  /*executed after connected*/
});

//wait for all services used by the maker object to authenticate
maker.authenticate();
```

## Adding Custom Events

One way to add an event is to “register” a function that gets called on each new block, using the event service's registerPollEvents function. For example, here is some code from the price service. this.getEthPrice will be called on each new block, and if the state has changed from the last call, a price/ETH_USD event will be emitted with the payload { price: new_price }.

Another way to an add an event is to manually emit an event using the event service's emit function. For example, when the Web3Service initializes, it emits an event that contains info about the provider.

Note that calling registerPollEvents and emit() directly on the event service like in the previous two examples will register events on the "default" event emitter instance. However, you can create a new event emitter instance for your new service. For example, the CDP object defines it's own event emitter, as can be seen here, by calling the event service's buildEmitter() function.

```javascript
//in PriceService.js
this.get('event').registerPollEvents({
  'price/ETH_USD': {
    price: () => this.getEthPrice(),
  },
});

//in Web3Service.js
this.get('event').emit('web3/INITIALIZED', {
  provider: { ...settings.provider },
});

//in the constructor in the Cdp.js
this._emitterInstance = this._cdpService.get('event').buildEmitter();
this.on = this._emitterInstance.on;
this._emitterInstance.registerPollEvents({
  COLLATERAL: {
    USD: () => this.getCollateralValueInUSD(),
    ETH: () => this.getCollateralValueInEth(),
  },
  DEBT: {
    dai: () => this.getDebtValueInDai(),
  },
});
```


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

Events


# Events

## Summary

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

## Wildcards

- An event name passed to any event emitter method can contain a wildcard the `*`character. A wildcard may appear as `foo/*`, `foo/bar/*`, or simply `*`.
- `*` matches one sub-level.

e.g. `price/*` will trigger on both `price/USD_ETH` and `price/MKR_USD` but not `price/MKR_USD/foo`.

- `**` matches all sub-levels.

e.g. `price/**` will trigger on `price/USD_ETH`, `price/MKR_USD`, and `price/MKR_USD/foo`.

**Event Object**

Triggered events will receive the object shown on the right.

- `<event_type>` - the name of the event
- `<event_payload>` - the new state data sent with the event
- `<event_sequence_number>` - a sequentially increasing index
- `<latest_block_when_emitted>` - the current block at the time of the emit

```javascript
{
    type: <event_type>,
    payload: <event_payload>, /* if applicable */
    index: <event_sequence_number>,
    block: <latest_block_when_emitted>
}
```

## Maker Object

### Price

| Event Name        | Payload   |
| :---------------- | :-------- |
| `price/ETH_USD`   | { price } |
| `price/MKR_USD`   | { price } |
| `price/WETH_PETH` | { ratio } |

```javascript
maker.on('price/ETH_USD', (eventObj) => {
  const { price } = eventObj.payload;
  console.log('ETH price changed to', price);
});
```

### Web3

| Event Name             | Payload                     |
| :--------------------- | :-------------------------- |
| `web3/INITIALIZED`     | { provider: { type, url } } |
| `web3/CONNECTED`       | { api, network, node }      |
| `web3/AUTHENTICATED`   | { account }                 |
| `web3/DEAUTHENTICATED` | { }                         |
| `web3/DISCONNECTED`    | { }                         |

```javascript
maker.on('web3/AUTHENTICATED', (eventObj) => {
  const { account } = eventObj.payload;
  console.log('web3 authenticated with account', account);
});
```

### CDP Object

| Event Name   | Payload      |
| :----------- | :----------- |
| `COLLATERAL` | { USD, ETH } |
| `DEBT`       | { dai }      |

```javascript
cdp.on('DEBT', (eventObj) => {
  const { dai } = eventObj.payload;
  console.log('Your cdp now has a dai debt of', dai);
});
```


Transactions


# Transaction manager

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

```javascript
const txMgr = maker.service('transactionManager');
// instance of transactionManager
const open = maker.service('cdp').openCdp();
// open is a promise--note the absence of `await`
```

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

```javascript
txMgr.listen(open, {
  pending: (tx) => {
    // do something when tx is pending
  },
  mined: (tx) => {
    // do something when tx is mined
  },
  confirmed: (tx) => {
    // do something when tx is confirmed
  },
  error: (tx) => {
    // do someting when tx fails
  },
});

await txMgr.confirm(open);
// 'confirmed' callback will fire after 5 blocks
```

Note that the `confirmed` event will not fire unless `transactionManager.confirm` is called. This async function waits a number of blocks default 5 after the transaction has been mined to resolve. To change this globally, set the `confirmedBlockCount` attribute in Maker [options](../maker/#options). To change it for just one call, pass the number of blocks to wait as the second argument:

```javascript
await txMgr.confirm(open, 3);
```

## Transaction Metadata

There are functions such as `lockEth()` which are composed of several internal transactions. These can be more accurately tracked by accessing `tx.metadata`in the callback which contains both the `contract` and the `method` the internal transactions were created from.

## Transaction Object Methods

A `TransactionObject` also has a few methods to provide further details on the transaction:

- `hash` : transaction hash
- `fees()` : amount of ether spent on gas
- `timeStamp()` : timestamp of when transaction was mined
- `timeStampSubmitted()` : timestamp of when transaction was submitted to the network

```javascript
const lock = cdp.lockEth(1);
txMgr.listen(lock, {
  pending: (tx) => {
    const { contract, method } = tx.metadata;
    if (contract === 'WETH' && method === 'deposit') {
      console.log(tx.hash); // print hash for WETH.deposit
    }
  },
});
```


Learn the functionality for interacting with both profile proxies and forwarding proxies

DS Proxy


# DSProxy

```javascript
const service = maker.service('proxy');
```

## Summary

The `DSProxyService` includes all the functionality necessary for interacting with both types of proxy contracts used in Maker products: **profile proxies** and **forwarding proxies**.

Forwarding proxies are simple contracts that aggregate function calls in the body of a single method. These are used in the [CDP Portal](https://github.com/makerdao/sai-proxy) and [Oasis Direct](https://github.com/makerdao/oasis-direct-proxy) in order to allow users to execute multiple transactions atomically, which is both safer and more user-friendly than implementing several steps as discrete transactions.

```solidity
// Forwarding proxy

function lockAndDraw(address tub_, bytes32 cup, uint wad) public payable {
  lock(tub_, cup);
  draw(tub_, cup, wad);
}
```

Forwarding proxies are meant to be as simple as possible, so they lack some features that could be important if they are to be used as interfaces for more complex smart contract logic. This problem can be solved by using profile proxies i.e. copies of [DSProxy](https://github.com/dapphub/ds-proxy) to execute the functionality defined in the forwarding proxies.

The first time an account is used to interact with any Maker application, the user will be prompted to deploy a profile proxy. This copy of DSProxy can be used in any product, including dai.js, by way of a universal [proxy registry](https://github.com/makerdao/proxy-registry/tree/master). Then, the calldata from any function in the forwarding proxy can be passed to DSProxy's `execute()`method, which runs the provided code in the context of the profile proxy.

```javascript
// Calling the forwarding proxy with dai.js

function lockAndDraw(tubContractAddress, cdpId, daiAmount, ethAmount) {
  const saiProxy = maker.service('smartContract').getContractByName('SAI_PROXY');

  return saiProxy.lockAndDraw(tubContractAddress, cdpId, daiAmount, {
    value: ethAmount,
    dsProxy: true,
  });
}
```

This makes it possible for users' token allowances to persist from one Maker application to another, and it allows users to [recover any funds](https://proxy-recover-funds.surge.sh/) mistakenly sent to the proxy's address. Many of the functions in `DSProxyService` will only be relevant to `power users`. All that is strictly required to automatically generate a function's calldata and find the correct profile proxy is the inclusion of `{ dsProxy: true }` in the options object for any transaction — provided the user has already deployed a profile proxy. If that's not certain, it may also be necessary to query the registry to determine if a user already owns a proxy, and to `build` one if they do not.

## currentProxy()

- **Params:** None
- **Returns:** promise resolves to address **or** `null`

If the `currentAccount` according the `Web3Service` has already deployed a DSProxy, `currentProxy()` returns its address. If not, it returns `null`. It will update automatically in the event that the active account is changed. This function should be used to check whether a user has a proxy before attempting to build one.

```javascript
async function getProxy() {
  return maker.service('proxy').currentProxy();
}
```

## build()

- **Params:** None
- **Returns:** `TransactionObject`

`build` will deploy a copy of DSProxy owned by the current account. **This transaction will revert if the current account already owns a profile proxy.** By default, `build()` returns after the transaction is mined.

```javascript
async function buildProxy() {
  const proxyService = maker.service('proxy');
  if (!proxyService.currentProxy()) {
    return proxyService.build();
  }
}
```

## ensureProxy()

This convenience function will either return an existing proxy or create one.

```javascript
const proxyAddress = await maker.service('proxy').ensureProxy();
```

## getProxyAddress()

- **Params:** Address optional
- **Returns:** promise resolves to contract address

`getProxyAddress` will query the proxy registry for the profile proxy address associated with a given account. If no address is provided as a parameter, the function will return the address of the proxy owned by the `currentAccount`.

```javascript
const proxy = await maker.service('proxy').getProxyAddress('0x...');
```

## getOwner()

- **Params:** Address
- **Returns:** promise resolves to address

`getOwner` will query the proxy registry for the owner of a provided instance of DSProxy.

```javascript
const owner = await maker.service('proxy').getOwner('0x...');
```

## setOwner()

- **Params:** Address of new owner, DSProxy address optional
- **Returns:** `TransactionObject`

`setOwner` can be used to give a profile proxy to a new owner. The address of the recipient account must be specified, but the DSProxy address will default to `currentProxy` if the second parameter is excluded.

```javascript
await maker.service('proxy').setOwner(newOwner, proxyAddress);
```


Dai.js supports the use of multiple accounts with a single Maker instance

Using multiple accounts


# Using multiple accounts

## 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 `default` if it exists, or the first account in the list otherwise.

```javascript
const maker = await Maker.create({
  url: 'http://localhost:2000',
  accounts: {
    other: { type: privateKey, key: someOtherKey },
    default: { type: privateKey, key: myKey },
  },
});

await maker.addAccount('yetAnother', { type: privateKey, key: thirdKey });

const cdp1 = await maker.openCdp(); // owned by "default"

maker.useAccount('other');
const cdp2 = await maker.openCdp(); // owned by "other"

maker.useAccount('yetAnother');
const cdp3 = await maker.openCdp(); // owned by "yetAnother"

await maker.addAccount({ type: privateKey, key: fourthAccount.key }); // the name argument is optional
maker.useAccountWithAddress(fourthAccount.address);
const cdp4 = await maker.openCdp(); //owned by the fourth account
```

You can check the current account with `currentAccount` and `currentAddress`:

```javascript
> maker.currentAccount()
{ name: 'other', type: 'privateKey', address: '0xfff...' }
> maker.currentAddress()
'0xfff...'
```

## Account types

In addition to the `privateKey` account type, there are two other built-in types:

- `provider`: Get the first account from the provider e.g. the value from `getAccounts`.
- `browser`: Get the first account from the provider in the browser e.g. MetaMask, even if the Maker instance is configured to use a different provider.

```javascript
const maker = await Maker.create({
  url: 'http://localhost:2000',
  accounts: {
    // this will be the first account from the provider at
    // localhost:2000
    first: { type: 'provider' },

    // this will be the current account in MetaMask, and it
    // will send its transactions through MetaMask
    second: { type: 'browser' },

    // this account will send its transactions through the
    // provider at localhost:2000
    third: { type: 'privateKey', key: myPrivateKey },
  },
});
```

## Hardware wallets

Plugins can add additional account types. There are currently two such plugins for hardware wallet support:

- [dai-plugin-trezor-web](https://github.com/makerdao/dai-plugin-trezor-web)
- [dai-plugin-ledger-web](https://github.com/makerdao/dai-plugin-ledger-web)

```javascript
import TrezorPlugin from '@makerdao/dai-plugin-trezor-web';
import LedgerPlugin from '@makerdao/dai-plugin-ledger-web';

const maker = await Maker.create({
  plugins: [TrezorPlugin, LedgerPlugin],
  accounts: {
    // default derivation path is "44'/60'/0'/0/0"
    myTrezor: { type: 'trezor', path: derivationPath1 },
    myLedger: { type: 'ledger', path: derivationPath2 },
  },
});
```

## **Demo**

Install the [multiple accounts demo app](https://github.com/makerdao/integration-examples/tree/master/accounts) to see this functionality in action.


Advanced Features


# Advanced

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](https://github.com/makerdao/dai.js/blob/dev/packages/dai/contracts/addresses/mainnet.json)

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





Plugins allow a developer to add functionality for specific needs without increasing the size of the core library.

Plugins


# Plugins

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](https://github.com/makerdao/dai-plugin-trezor-web) for using Trezor with dai.js in a browser environment.
2. [Ledger Plugin](https://github.com/makerdao/dai-plugin-ledger-web) for using Ledger in a browser environment.
3. [Governance Plugin](https://github.com/makerdao/dai-plugin-governance) for working with the governance contracts.
4. [eth2dai Instant Plugin](dai-plugin-eth2dai-instant) for atomic trading on maker OTC Oasis.
5. [Maker OTC Plugin](https://github.com/makerdao/dai-plugin-maker-otc) for interacting with the maker OTC contract Oasis.
6. [MCD Plugin](../the-mcd-plugin.md) for interacting with the multi-collateral dai contracts.
7. [SCD Plugin](../single-collateral-dai/) for interacting with the single-collateral dai contracts.

### Building your own plugin

Check out the [Dai Plugin Template](https://github.com/makerdao/dai-plugin-template).


Maker Object Introduction


# Configuration

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

### Presets

* `'browser'`
  * Use this preset when using the library in a browser environment. It will attempt to connect using `window.ethereum` or `window.web3`.
* `'http'`
  * Connect to a JSON-RPC node. Requires `url` to be set in the options.
* `'test'`
  * Use a local node e.g. Ganache running at `http://127.0.0.1:2000`, and sign transactions using node-managed keys.

```javascript
const makerBrowser = await Maker.create('browser');

const makerHttp = await Maker.create('http', {
  url: 'https://kovan.infura.io/v3/YOUR_INFURA_PROJECT_ID'
});

const makerTest = await Maker.create('test');
```

### Options

* `privateKey`
  * Optional. The private key used to sign transactions. If this is omitted, the first account available from the Ethereum provider will be used. Only used with the `'http'` preset.
  * If this is omitted and the provider does not have an unlocked account, the `maker` object will start in [read-only mode](./#read-only-mode).
* `url`
  * The URL of the node to connect to. Only used with the `'http'` preset.
* `web3.transactionSettings`
  * Object containing transaction options to be applied to all transactions sent through the library.
  * Default value: `{ gasLimit: 4000000 }`
* `web3.confirmedBlockCount`
  * Number of blocks to wait after a transaction has been mined when calling `confirm`. See [Transactions](../advanced-configuration/transactions.md) for further explanation. 
  * Default value: 5
* `web3.inject`
  * For advanced users. You can inject your own custom instance of a Web3 provider with this, instead of using the default HttpProvider.
* `log`
  * Set this to `false` to reduce the verbosity of logging.
* `autoAuthenticate`
  * Set this to `false` to create the Maker instance without connecting yet. If so, you must run `await maker.authenticate()` before using any other methods.

```javascript
// It doesn't necessarily make sense to set all these
// options at the same time (e.g. `url` and `inject`),
// this is just meant to illustrate the shape of the
// options object.
const maker = await Maker.create('http', {
  privateKey: YOUR_PRIVATE_KEY, // '0xabc...'
  url: 'http://some-ethereum-rpc-node.net',
  web3: {
    statusTimerDelay: 2000,
    confirmedBlockCount: 8
    transactionSettings: {
      gasPrice: 12000000000
    },
    inject: someProviderInstance
  },
  log: false,
  autoAuthenticate: false
});
```

## Instance methods

### service()

* **Returns:** service object

Return a service instance that was included in this instance of `maker`.

```javascript
const accountsService = maker.service('accounts');
```

## Services

The MCD plugin defines several services for working with Multi-Collateral Dai. Review [Getting started](../getting-started.md) to see how to add the plugin.

* [`'mcd:cdpManager'`](../the-mcd-plugin.md): for working with Vaults.
* [`'mcd:cdpType'`](../cdptypeservice.md): for reading parameters and live data totals and prices for collateral types.
* [`'mcd:savings'`](../savingsservice.md): for working with the Dai Savings Rate.
* [`'mcd:systemData'`](../systemdataservice.md): for reading system-wide parameters.

## Read-only mode

As mentioned above, the `Maker` instance can be used in read-only mode, if you just want to read data from the blockchain without signing any transactions. Simply omit the `privateKey` option.

You can start in read-only mode and still [add an account](../advanced-configuration/using-multiple-accounts.md) with the ability to sign transactions later on.



Collateralized Debt Position


# Collateralized Debt Position

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

After [opening a new CDP](./#opencdp) or [getting an existing one](./#getcdp-int-id), you can use the returned `cdp` object to call functions on it.

## Properties

### **`id`**

This is the ID of the CDP object. You can pass this ID to [Maker.getCdp](Maker#getcdp).

## Methods

### getDebtValue

- **Params:** [currency unit](Currency-units) optional
- **Returns:** promise resolves to the amount of outstanding debt

`cdp.getDebtValue()` returns the amount of debt that has been borrowed against the collateral in the CDP. By default it returns the amount of Dai as a [currency unit](https://makerdao.com/documentation/#units), but can return the equivalent in USD if the first argument is `Maker.USD`.

```javascript
const daiDebt = await cdp.getDebtValue();
const usdDebt = await cdp.getDebtValue(Maker.USD);
```

### getGovernanceFee

- **Params:** [currency unit](Currency-units) optional
- **Returns:** promise resolves to the value of the accrued governance fee in USD

`cdp.getGovernanceFee()` returns the value of the accrued governance fee. By default it returns the amount of MKR as a [currency unit](https://makerdao.com/documentation/#units), but can return the equivalent in USD if the first argument is `Maker.USD`.

**Note:** this is often referred to as the `Stability Fee`, even though technically the `Stability Fee` is the fee that is paid in Dai, and the `Governance Fee` is the fee that is paid in MKR. But since fees are only paid in MKR in Single-Collateral Dai, and only paid in Dai in Multi-Collateral Dai, the fee in Single-Collateral Dai is often referred to as the `Stability Fee` to be consistent with the term that will be used in Multi-Collateral Dai and to avoid unduly confusing regular users.

```javascript
const mkrFee = await cdp.getGovernanceFee();
const usdFee = await cdp.getGovernanceFee(Maker.USD);
```

### getCollateralizationRatio

- **Params:** none
- **Returns:** promise resolves to the collateralization ratio

`cdp.getCollateralizationRatio()` returns the USD value of the collateral in the CDP divided by the USD value of the Dai debt for the CDP, e.g. `2.5`.

```javascript
const ratio = await cdp.getCollateralizationRatio();
```

### **getLiquidationPrice**

- **Params:** none
- **Returns:** promise resolves to the liquidation price

`cdp.getLiquidationPrice()` returns the price of Ether in USD that causes the CDP to become unsafe able to be liquidated, all other factors constant. It returns a `USD_ETH` [price unit](https://makerdao.com/documentation/#units).

```javascript
const ratio = await cdp.getLiquidationPrice();
```

### getCollateralValue

- **Params:** [currency unit](Currency-units) optional
- **Returns:** promise resolves to collateral amount

`cdp.getCollateralValue()` returns the value of the collateral in the CDP. By default it returns the amount of ETH as a [currency unit](https://makerdao.com/documentation/#units), but can return the equivalent in PETH or USD depending on the first argument.

```javascript
const ethCollateral = await cdp.getCollateralValue();
const pethCollateral = await cdp.getCollateralValue(Maker.PETH);
const usdCollateral = await cdp.getCollateralValue(Maker.USD);
```

### isSafe

- **Params:** none
- **Returns:** promise resolves to boolean

`cdp.isSafe()` returns true if the cdp is safe, that is, if the USD value of its collateral is greater than or equal to USD value of the its debt multiplied by the liquidation ratio.

```javascript
const ratio = await cdp.isSafe();
```

### enoughMkrToWipe

- **Params:** amount of Sai to wipe
- **Returns:** promise resolves to boolean

`cdp.enoughMkrToWipe(dai)` returns true if the current account owns enough MKR to wipe the specified amount of Sai from the CDP.

```javascript
const enoughMkrToWipe = await cdp.enoughMkrToWipe(10000000000000000000, SAI.wei);
```

### lockEth

- **Params:** amount to lock in the CDP, in units defined by the price service.
- **Returns:** promise resolves to [transactionObject](https://makerdao.com/documentation/#transactions) once mined

`cdp.lockEth(eth)` abstracts the token conversions needed to lock collateral in a CDP. It first converts the ETH to WETH, then converts the WETH to PETH, then locks the PETH in the CDP.

**Note:** this process is not atomic, so it's possible for some of the transactions to succeed but not all three. See [Using DsProxy](https://makerdao.com/documentation/#proxy-service) for executing multiple transactions atomically.

```javascript
return await cdp.lockEth(10000000000000000000, ETH.wei);
// or equivalently
return await cdp.lockEth(100, ETH);
```

### drawSai

- **Params:** amount to draw in Sai, as string
- **Returns:** promise resolves to [transactionObject](https://makerdao.com/documentation/#transactions) once mined

`cdp.drawSai(sai)` withdraws the specified amount of Sai as a loan against the collateral in the CDP. As such, it will fail if the CDP doesn't have enough PETH locked in it to remain at least 150% collateralized.

```javascript
return await cdp.drawSai(10000000000000000000, SAI.wei);
// or equivalently
return await cdp.drawSai(100, SAI);
```

### wipeSai

- **Params:** amount to repay in Sai, as string
- **Returns:** promise resolves to [transactionObject](https://makerdao.com/documentation/#transactions) once mined

`cdp.wipeSai(sai)` sends Sai back to the CDP in order to repay some or all of its outstanding debt.

**Note:** CDPs accumulate MKR governance debt over their lifetime. This must be paid when wiping sai debt, and thus MKR must be acquired before calling this method.

```javascript
return await cdp.wipeSai(10000000000000000000, SAI.wei);
// or equivalently
return await cdp.wipeSai(100, SAI);
```

### freePeth

- **Params:** amount of Peth collateral to free from the CDP, in units defined by the price service.
- **Returns:** promise resolves to [transactionObject](https://makerdao.com/documentation/#transactions) once mined

`cdp.freePeth(peth)` withdraws the specified amount of PETH and returns it to the owner's address. As such, the contract will only allow you to free PETH that's locked in excess of 150% of the CDP's outstanding debt.

```javascript
return await cdp.freePeth(100, PETH);
// or equivalently
return await cdp.freePeth(10000000000000000000, PETH.wei);
```

### give

- **Params:** Ethereum address string
- **Returns:** promise resolves to [transactionObject](https://makerdao.com/documentation/#transactions) once mined

`cdp.give(address)` transfers ownership of the CDP from the current owner to the address you provide as an argument.

```javascript
return await cdp.give('0x046ce6b8ecb159645d3a605051ee37ba93b6efcc');
```

### shut

- **Params:** none
- **Returns:** promise resolves to [transactionObject](https://makerdao.com/documentation/#transactions) once mined

`cdp.shut()` wipes all remaining sai, frees all remaining collateral, and deletes the CDP. This will fail if the caller does not have enough DAI to wipe all the sai debt and enough MKR to pay for all the accrued stability fee

```javascript
return await cdp.shut();
```

### **bite**

- **Params:** none
- **Returns:** promise resolves to [transactionObject](https://makerdao.com/documentation/#transactions) once mined

`cdp.bite()` will initiate the liquidation process of an undercollateralized CDP

```javascript
return await cdp.bite();
```


CDP Service


# CDP Service

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

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

## getLiquidationRatio

- **Params:** none
- **Returns:** promise resolves to liquidation ratio

`getLiquidationRatio()` returns a decimal representation of the liquidation ratio, e.g. 1.5

```javascript
const ratio = await service.getLiquidationRatio();
```

## getLiquidationPenalty

- **Params:** none
- **Returns:** promise resolves to liquidation penalty

`getLiquidationPenalty()` returns a decimal representation of the liquidation penalty, e.g. 0.13

```javascript
const penalty = await service.getLiquidationPenalty();
```

## getAnnualGovernanceFee

- **Params:** none
- **Returns:** promise resolves to yearly governance fee

`getAnnualGovernanceFee()` returns a decimal representation of the annual governance fee, e.g. 0.005.

```javascript
const fee = await service.getAnnualGovernanceFee();
```

**Note:** This is often referred to as the `Stability Fee`, even though technically the `Stability Fee` is the fee that is paid in Sai, and the `Governance Fee` is the fee that is paid in MKR. But since fees are only paid in MKR in Single-Collateral Dai, and only paid in Dai in Multi-Collateral Dai, the fee in Single-Collateral Sai is often referred to as the `Stability Fee` to be consistent with the term that will be used in Multi-Collateral Dai and to avoid unduly confusing regular users.


The exchange service allows to buy and sell DAI, MKR, and other tokens

Exchange Service


# Exchange Service

## 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 [plugins](../maker/plugins.md#available-plugins) to be in use.

```javascript
const exchange = maker.service('exchange');
```

## sellDai

Sell a set amount of DAI and receive another token in return.

- **Parameters**
  - `daiAmount` - Amount of DAI to sell.
  - `tokenSymbol` - Token to receive in return.
  - `minFillAmount` - Minimum amount to receive in return.
- **Returns:** promise resolves to [OasisOrder](https://makerdao.com/documentation/#oasisorder) once mined

```javascript
// Sell 100.00 DAI for 0.30 WETH or more.
const sellOrder = await exchange.sellDai('100.0', 'WETH', '0.30');
```

## **buyDai**

Buy a set amount of DAI and give another token in return.

- **Parameters**
  - `daiAmount` - Amount of DAI to buy.
  - `tokenSymbol` - Token to give in return.
  - `minFillAmount` - Maximum amount to give in return.
- **Returns:** promise resolves to [OasisOrder](https://makerdao.com/documentation/#oasisorder) once mined

```javascript
// Buy 100.00 DAI for 0.30 WETH or less.
const buyOrder = await exchange.buyDai('100.0', 'WETH', '0.35');
```

## **OasisOrder**

`OasisOrders` have a few methods: `fillAmount`: amount of token received in exchange `fees()`: amount of ether spent on gas `created()`: timestamp of when transaction was mined

```javascript
const buyOrder = await exchange.buyDai('100.0', 'WETH', '0.35');
const fillAmount = buyOrder.fillAmount();
const gasPaid = buyOrder.fees();
const created = buyOrder.created();
```


PriceService exposes the collateral and governance tokens' price information

Price Service


# Price Service

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

```javascript
const price = maker.service('price');
```

## getEthPrice

Get the current USD price of ETH, as a `USD_ETH` [price unit](https://makerdao.com/documentation/#units).

```javascript
const ethPrice = await price.getEthPrice();
```

## getMkrPrice

Get the current USD price of the governance token MKR, as a `USD_MKR` [price unit](https://makerdao.com/documentation/#units).

```javascript
const mkrPrice = await price.getMkrPrice();
```

## getPethPrice

Get the current USD price of PETH (pooled ethereum), as a `USD_PETH` [price unit](https://makerdao.com/documentation/#units).

```javascript
await pethPrice = price.getPethPrice();
```

## setEthPrice

Set the current USD price of ETH. This requires the necessary permissions and will only be useful in a testing environment.

```javascript
await price.setEthPrice(475);
```

## setMkrPrice

Set the current USD price of the governance token MKR. This requires the necessary permissions and will only be useful in a testing environment.

```javascript
await price.setMkrPrice(950.0);
```

## getWethToPethRatio

Returns the current WETH to PETH ratio.

```javascript
await price.getWethToPethRatio();
```


Access system status information with the ETH CDP Service

System Status


# System Status

## Summary

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

```javascript
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

```javascript
const systemRatio = await service.getSystemCollateralization();
```

## 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` [price unit](system-status.md#units).

```javascript
const targetPrice = await service.getTargetPrice();
```


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

Token Conversion


# Token Conversion

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

```javascript
const conversionService = maker.service('conversion');
```

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

## convertEthToWeth

```javascript
return await conversionService.convertEthToWeth(ETH(10));
```

- Params: amount of Eth to convert
- Returns: promise resolves to transactionObject once mined

**Note:** this is the same as weth.deposit

`convertEthToWeth` deposits ETH into the WETH contract

## convertWethToPeth

```javascript
return await conversionService.convertWethToPeth(WETH(10));
```

- Params: amount of Weth to convert
- Returns: promise resolves to transactionObject once mined

`convertWethToPeth` joins WETH into PETH, first giving token allowance if necessary.

**Note:** this process is not atomic if a token allowance needs to be set, so it's possible for one of the transactions to succeed but not both. See [DsProxy](../advanced-configuration/using-ds-proxy.md) for executing multiple transactions atomically. Also, [peth.join](tokens.md#join-peth-only) can be called instead if you do not want the allowance to be set first automatically.

## convertEthToPeth

```javascript
return await conversionService.convertEthToPeth(ETH(10));
```

- Params: amount of Eth to convert
- Returns: promise resolves to transactionObject once mined

`convertEthToPeth` awaits convertEthToWeth, then calls convertWethToPeth

**Note:** this process is not atomic, so it's possible for some of the transactions to succeed but not all. See Using DsProxy for executing multiple transactions atomically.

## convertWethToEth

```javascript
return await conversionService.convertconvertWethToEth(WETH(10));
```

- Params: amount of Weth to convert
- Returns: promise resolves to transactionObject once mined

`convertWethToEth` withdraws Eth from Weth contract

**Note:** this is the same as weth.withdraw

## convertPethToWeth

```javascript
return await conversionService.convertPethToWeth(PETH(10));
```

- Params: amount of Peth to convert
- Returns: promise resolves to transactionObject once mined

`convertPethToWeth` exits PETH into WETH, first giving token allowance if necessary

**Note:** this process is not atomic if a token allowance needs to be set, so it's possible for one of the transactions to succeed but not both. See Using DsProxy for executing multiple transactions atomically. Also, peth.exit can be called instead if you do not want the allowance to be set first automatically.

## convertPethToEth

```javascript
return await conversionService.convertPethToEth(PETH(10));
```

- Params: amount of Peth to convert
- Returns: promise resolves to transactionObject once mined

`convertPethToEth` awaits convertPethToWeth, then calls convertWethToEth

**Note:** this process is not atomic, so it's possible for some of the transactions to succeed but not all. See Using DsProxy for executing multiple transactions atomically.


Dai.js

Introduction

Related guides

Was this document helpful?

Edit this page

Make the community proud with your contributions