search

makerdao / dss-exec-lib

DSS Executive Spellcrafting Library Contracts
GNU Affero General Public License v3.0
36 stars 21 forks source link

readme

DSS Exec Library

Build Status

A library for crafting spells in DSS more efficiently, predictably, and easily.

Public Library Addresses

Requirements

About

Provides a list of functions to call to perform commonly used actions in spells in DSS.

Here is an example of a SpellAction.sol file that uses the deployed library (from spells-mainnet repo):

import {DssAction} from "lib/dss-exec-lib/src/DssAction.sol";

contract SpellAction is DssAction {

    constructor(address lib, bool officeHours) DssAction(lib, officeHours) {}

    uint256 constant MILLION  = 10 ** 6;

    function actions() public override {
        setGlobalDebtCeiling(1500 * MILLION);
        setIlkDebtCeiling("ETH-A", 10 * MILLION);
    }
}

The SpellAction.sol file must always inherit DssAction from lib/dss-exec-lib.

The developer must override the actions() function and place all spell actions within. This is called by the execute() function in the pause, which is subject to an optional limiter for office hours.

Note: All variables within the SpellAction MUST be defined as constants, or assigned at runtime inside of the actions() function. Variable memory storage is not available within a Spell Action due to the underlying delegatecall mechanisms.

The spell itself is deployed as follows:

new DssExec(
    "A test dss exec spell",      // Description
    block.timestamp + 30 days,    // Expiration
    address(new SpellAction())
);

Variables and Precision

Below is an outline of how all variables are accounted for for precision based on name.

NOTE: DSSExecLib.sol has NatSpec comments above every function definition that provides a comprehensive definition of the function, its parameters, and any precision calculations that are made.

Actions

Below is an outline of all functions used in the library.

Core Address Helpers

Changelog Management

Authorizations

Time Management

Accumulating Rates

Price Updates

System Configuration

System Risk Parameters

Collateral Management

Abacus Management

Oracle Management

Direct Deposit Module

Collateral Onboarding

In order to onboard new collateral to the Maker protocol, the following must be done before the spell is prepared:

Once these actions are done, add the following code (below is an example) to the execute() function in the spell. The setChangelogAddress function calls are required to add the collateral to the on-chain changelog. They must follow the following convention:

import "src/CollateralOpts.sol";

// Initialize the pricing function with the appropriate initializer
address xmpl_calc = 0x1f206d7916Fd3B1b5B0Ce53d5Cab11FCebc124DA;
DssExecLib.initStairstepExponentialDecrease(xmpl_calc, 60, 9900);

CollateralOpts memory XMPL_A = CollateralOpts({
    ilk:                   "XMPL-A",
    gem:                   0xCE4F3774620764Ea881a8F8840Cbe0F701372283,
    join:                  0xa30925910067a2d9eB2a7358c017E6075F660842,
    clip:                  0x9daCc11dcD0aa13386D295eAeeBBd38130897E6f,
    calc:                  xmpl_calc,
    pip:                   0x9eb923339c24c40Bef2f4AF4961742AA7C23EF3a,
    isLiquidatable:        true,
    isOSM:                 true,
    whitelistOSM:          true,
    ilkDebtCeiling:        3 * MILLION,
    minVaultAmount:        100,         // 100 Dust
    maxLiquidationAmount:  50000,       // 50,000 Dai
    liquidationPenalty:    1300,        // 13% penalty
    ilkStabilityFee:       1000000000705562181084137268,
    startingPriceFactor:   13000,       // 1.3x multiplier
    auctionDuration:       6 hours,
    permittedDrop:         4000,        // 40% drop before reset
    liquidationRatio:      15000        // 150% collateralization ratio
});

DssExecLib.addNewCollateral(XMPL_A);

DssExecLib.setChangelogAddress("XMPL",          0xCE4F3774620764Ea881a8F8840Cbe0F701372283);
DssExecLib.setChangelogAddress("PIP_XMPL",      0x9eb923339c24c40Bef2f4AF4961742AA7C23EF3a);
DssExecLib.setChangelogAddress("MCD_JOIN_XMPL-A", 0xa30925910067a2d9eB2a7358c017E6075F660842);
DssExecLib.setChangelogAddress("MCD_CLIP_XMPL-A", 0x9daCc11dcD0aa13386D295eAeeBBd38130897E6f);
DssExecLib.setChangelogAddress("MCD_CLIP_CALC_XMPL-A", xmpl_calc);

Payments

Misc

Testing

$ dapp update
$ make test