DSS deployment scripts

A set of scripts that deploy dss to an Ethereum chain of your choosing.

Description

This repo is composed of two steps:

Bash scripts to modify the state of the base system

At the end of the first step, the addresses of deployed contracts are written to an out/addresses.json file. The scripts read those addresses and use seth and dapp to modify the deployment, using the values in out/config.json.

Installing

The only way to install everything necessary to deploy is Nix. Run

$ nix-shell --pure

to drop into a Bash shell with all dependency installed.

Ethereum node

You'll also need an Ethereum RPC node to connect to. Depending on your usecase, this could be a local node (e.g. dapp testnet) or a remote one.

Configuration

There are 2 main pieces of configuration necessary for a deployment:

Ethereum account configuration
Chain configuration

Account configuration

seth relies on the presence of environment variables to know which Ethereum account to use, which RPC server to talk to, etc.

If you're using nix-shell, these variables are set automatically for you in shell.nix.

But you can also configure the below variables manually:

ETH_FROM: address of deployment account
ETH_PASSWORD: path of account password file
ETH_KEYSTORE: keystore path
ETH_RPC_URL: URL of the RPC node

Chain configuration

Some networks have a default config file at config/<NETWORK>.json, which will be used if non custom config values are set. A config file can be passed via param with flag -f allowing to execute the script in any network (e.g. dss-deploy testchain -f <CONFIG_FILE_PATH>). As other option, custom config values can be loaded as an environment variable called DDS_CONFIG_VALUES. File passed by parameter overwrites the environment variable.

Below is the expected structure of such a config file:

{
  "description": "",
  "omniaFromAddr": "<Address being used by Omnia Service (only for testchain)>",
  "omniaAmount": "<Amount in ETH to be sent to Omnia Address (only for testchain)>",
  "pauseDelay": "<Delay of Pause contract in seconds>",
  "vat_line": "<General debt ceiling in DAI unit>",
  "vow_wait": "<Flop delay in seconds>",
  "vow_sump": "<Flop fixed bid size in DAI unit>",
  "vow_dump": "<Flop initial lot size in MKR unit>",
  "vow_bump": "<Flap fixed lot size in DAI unit>",
  "vow_hump": "<Flap Surplus buffer in DAI unit>",
  "cat_box": "<Max total DAI needed to cover all debt plus penalty fees on active Flip auctions in DAI unit>",
  "dog_hole": "<Max total DAI needed to cover all debt plus penalty fees on active Clip auctions in DAI unit>",
  "jug_base": "<Base component of stability fee in percentage per year (e.g. 2.5)>",
  "pot_dsr": "<Dai Savings Rate in percentage per year (e.g. 2.5)>",
  "end_wait": "<Global Settlement cooldown period in seconds>",
  "esm_pit": "<Pit address to send MKR to be burnt when ESM is fired>",
  "esm_min": "<Minimum amount to trigger ESM in MKR unit>",
  "flap_beg": "<Minimum bid increase in percentage (e.g. 5.5)>",
  "flap_ttl": "<Max time between bids in seconds>",
  "flap_tau": "<Max auction duration in seconds>",
  "flop_beg": "<Minimum bid increase in percentage (e.g. 5.5)>",
  "flop_pad": "<Increase of lot size after `tick` in percentage (e.g. 50)>",
  "flop_ttl": "<Max time between bids in seconds>",
  "flop_tau": "<Max auction duration in seconds>",
  "flash_max": "<Max DAI can be borrowed from flash loan module in DAI unit (e.g. 1000000)>",
  "flash_toll": "<Fee being charged from amount being borrow via flash loan module in percentage (e.g 0.1%)>",
  import: {
    "gov": "<GOV token address (if there is an existing one to import)>",
    "authority": "<Authority address (if there is an existing one to import)>",
    "proxyRegistry": "<Proxy Registry address (if there is an existing one to import)>",
    "faucet": "<Faucet address (if there is an existing one to import)>"
  },
  "tokens": {
    "<ETH|COL>": {
      "import": {
        "gem": "<Gem token address (if there is an existing one to import)>",
        "pip": "<Price feed address (if there is an existing one to import)>"
      },
      "gemDeploy": { // Only used if there is not a gem imported
        "src": "<REPO/CONTRACT (e.g. dss-gem-joins/GemJoin2)>",
        "params": [<Any params to be passed to the constructor of the token in its native form (e.g. amounts in wei or strings in hex encoding)>],
        "faucetSupply": "<Amount of token to be transferred to the faucet>",
        "faucetAmount": "<Amount of token to be obtained in each faucet gulp (only if a new faucet is deployed)>"
      },
      "joinDeploy": { // Mandatory always
        "src": "<GemJoin/GemJoin2/GemJoinX>",
        "extraParams": [<Any extra params to be passed to the constructor of the join in its native form (e.g. amounts in wei or strings in hex encoding)>]
      },
      "pipDeploy": { // Only used if there is not a pip imported
        "osmDelay": "<Time in seconds for the OSM delay>",
        "type": "<median|value>",
        "price": "<Initial oracle price (only if type == "value")>",
        "signers": [
            <Set of signer addreeses (only if type == "median")>
        ]
      },
      "ilks": {
        "A": {
          "mat": "<Liquidation ratio value in percentage (e.g. 150)>",
          "line": "<Debt ceiling value in DAI unit (won't be used if autoLine is > 0)>",
          "autoLine": "<Max debt ceiling value in DAI unit (for DssAutoLine IAM)>",
          "autoLineGap": "<Value to set the ceiling over the current ilk debt in DAI unit (for DssAutoLine IAM)>",
          "autoLineTtl": "<Time between debt ceiling increments (for DssAutoLine IAM)>",
          "dust": "<Min amount of debt a CDP can hold in DAI unit>"
          "duty": "<Collateral component of stability fee in percentage per year (e.g. 2.5)>",
          "flipDeploy": {
            "chop": "<Liquidation penalty value in percentage (e.g. 12.5)>",
            "dunk": "<Liquidation Quantity in DAI Unit>",
            "beg": "<Minimum bid increase in percentage (e.g. 5.5)>",
            "ttl": "<Max time between bids in seconds>",
            "tau": "<Max auction duration in seconds>"
          },
          "clipDeploy": { // Will be used only if there isn't a flipDeploy
            "chop": "<Liquidation penalty value in percentage (e.g. 12.5)>",
            "hole": "<Max DAI needed to cover debt+fees of active auctions per ilk (e.g. 100,000 DAI)>",
            "chip": "<Percentage of due to suck from vow to incentivize keepers (e.g. 2%)>",
            "tip": "<Flat fee to suck from vow to incentivize keepers (e.g. 100 DAI)>",
            "buf": "<Multiplicative factor to increase starting price (e.g. 125%)>",
            "tail": "<Time elapsed before auction reset in seconds>",
            "cusp": "<Percentage taken for the new price before auction reset (e.g. 30%)>",
            "calc": {
              "type": "LinearDecrease/StairstepExponentialDecrease/ExponentialDecrease",
              "tau":  "<Time after auction start when the price reaches zero in seconds (LinearDecrease)>",
              "step": "<Length of time between price drops in seconds (StairstepExponentialDecrease)>",
              "cut":  "<Percentage to be taken as new price per step (e.g. 99%, which is 1% drop) (StairstepExponentialDecrease/ExponentialDecrease)>"
            },
            "cm_tolerance": "<Percentage of previous price which a drop would enable anyone to be able to circuit break the liquidator via ClipperMom (e.g. 50%)>"
          }
        }
      }
    }
  }
}

Default config files

Currently, there are default config files for 3 networks:

a local testchain (e.g. dapp testnet)
Kovan
Mainnet

Deploy on local testchain with default config file

dss-deploy testchain

It is possible to pass a value to define a testing scenario via -c flag (e.g. dss-deploy testchain -c crash-bite)

The only case currently available is:

crash-bite

Deploy on Kovan with default config file

dss-deploy kovan

Deploy on Mainnet with default config file

dss-deploy main

Deploy on any network passing a custom config file

dss-deploy <NETWORK> -f <CONFIG_FILE_PATH>

Output

Successful deployments save their output to the following files:

out/addresses.json: addresses of all deployed contracts
out/config.json: copy of the configuration file used for the deployment
out/abi/: JSON representation of the ABIs of all deployed contracts
out/bin/: .bin and .bin-runtime files of all deployed contracts
out/meta/: meta.json files of all deployed contracts
out/dss-<NETWORK>.log: output log of deployment

Helper scripts

The auth-checker script loads the addresses from out/addresses.json and the config file from out/config.json and verifies that the deployed authorizations match what is expected.

Nix

To enable full reproducibility of our deployments, we use Nix.

This command will drop you in a shell with all dependencies and environment variables definend:

nix-shell --pure

You can even run deploy scripts without having to clone this repo:

nix run -f https://github.com/makerdao/dss-deploy-scripts/tarball/master -c dss-deploy testchain

Dependencies are managed through a central repository referenced in nix/pkgs.nix and the main Nix expression to build this repo is in default.nix.

Smart Contract Dependencies

To update smart contract dependencies use dapp2nix:

nix-shell --pure
dapp2nix help
dapp2nix list
dapp2nix up vote-proxy <COMMIT_HASH>

To clone smart contract dependencies into working directory run:

dapp2nix clone-recursive contracts

Additional Documentation

dss-deploy source code
dss is documented in the wiki and in DEVELOPING.md

TODO

More cases to test scenarios for testchain script

bridgecrew-perf6 / dss-deploy-scripts-1 Goto Github PK

dss-deploy-scripts-1's Introduction