Comment CollateralOpts & update README.md

README.md

@@ -202,7 +202,7 @@ import "src/CollateralOpts.sol";
 
 // Initialize the pricing function with the appropriate initializer
 address xmpl_calc = 0x1f206d7916Fd3B1b5B0Ce53d5Cab11FCebc124DA;
-DssExecLib.initStairstepExponentialDecrease(xmpl_calc, 60, 9900);
+DssExecLib.setStairstepExponentialDecrease(xmpl_calc, 60, 9900);
 
 CollateralOpts memory XMPL_A = CollateralOpts({
     ilk:                   "XMPL-A",
@@ -220,12 +220,17 @@ CollateralOpts memory XMPL_A = CollateralOpts({
     liquidationPenalty:    1300,        // 13% penalty
     ilkStabilityFee:       1000000000705562181084137268,
     startingPriceFactor:   13000,       // 1.3x multiplier
+    breakerTolerance:      5000,        // 50% drop before liquidations are paused
     auctionDuration:       6 hours,
     permittedDrop:         4000,        // 40% drop before reset
-    liquidationRatio:      15000        // 150% collateralization ratio
+    liquidationRatio:      15000,       // 150% collateralization ratio
+    kprFlatReward:         300,         // keepers receive 300 DAI
+    kprPctReward:          10,          // keepers receive 0.1%        
 });
 
 DssExecLib.addNewCollateral(XMPL_A);
+// set the parameters for an ilk in the "MCD_IAM_AUTO_LINE" auto-line
+DssExecLib.setIlkAutoLineParameter("XMPL-A", 3 * MILLION, 100 * MILLION, 8 hours);
 
 DssExecLib.setChangelogAddress("XMPL",          0xCE4F3774620764Ea881a8F8840Cbe0F701372283);
 DssExecLib.setChangelogAddress("PIP_XMPL",      0x9eb923339c24c40Bef2f4AF4961742AA7C23EF3a);
@@ -234,25 +239,27 @@ DssExecLib.setChangelogAddress("MCD_CLIP_XMPL-A", 0x9daCc11dcD0aa13386D295eAeeBB
 DssExecLib.setChangelogAddress("MCD_CLIP_CALC_XMPL-A", xmpl_calc);
 ```
 
-- `ilk`:                  Collateral type
-- `gem`:                  Address of collateral token
-- `join`:                 Address of GemJoin contract
-- `clip`:                 Address of Clip contract
+- `ilk`:                  Bytes32 result of the hyphenated, all caps collateral type name (e.g. "WBTC-C")
+- `gem`:                  Address of the particular underlying token (e.g. WBTC), found in the latest MCD deployment
+- `join`:                 Address of deployed GemJoin contract
+- `clip`:                 Address of auction Clip contract
 - `calc`:                 Address of Abacus pricing contract
-- `pip`:                  Address of Pip contract
+- `pip`:                  Address of Pip price feed contract
 - `isLiquidatable`:       Boolean indicating whether liquidations are enabled for collateral
 - `isOsm`:                Boolean indicating whether pip address used is an OSM contract
-- `whitelistOsm`:         Boolean indicating whether median is src in OSM.
-- `ilkDebtCeiling`:       Debt ceiling for new collateral
-- `minVaultAmount`:       Minimum DAI vault amount required for new collateral
+- `whitelistOsm`:         Boolean indicating whether median is src in OSM
+- `ilkDebtCeiling`:       Debt ceiling (maximum amount of DAI able to be minted from a given ilk collectively) for new collateral
+- `minVaultAmount`:       Minimum DAI vault amount a particular user can generate
 - `maxLiquidationAmount`: Max DAI amount per vault for liquidation for new collateral
-- `liquidationPenalty`:   Percent liquidation penalty for new collateral [ex. 13.5% == 1350]
-- `ilkStabilityFee`:      Percent stability fee for new collateral       [ex. 4% == 1000000001243680656318820312]
-- `startingPriceFactor`:  Percentage to multiply for initial auction price. [ex. 1.3x == 130% == 13000 bps]
-- `auctionDuration`:      Total auction duration before reset for new collateral
-- `permittedDrop`:        Percent an auction can drop before it can be reset.
-- `liquidationRatio`:     Percent liquidation ratio for new collateral   [ex. 150% == 15000]
-
+- `liquidationPenalty`:   Basis point percent liquidation penalty for new collateral [ex. 13.5% == 1350]
+- `ilkStabilityFee`:      Percent stability fee for new collateral, per-second-rate obtained from the "Stability Fee" gov proposal parameter [ex. 4% == 1000000001243680656318820312]
+- `startingPriceFactor`:  Basis point percentage to multiply for initial auction price [ex. 1.3x == 130% == 13000 bps]
+- `breakerTolerance`:     Percentage of how large of a price drop is tolerated before liquidations are paused [ex. 0.5x == 50% == 5000 bps]
+- `auctionDuration`:      Total auction duration before reset for new collateral in Solidity time unit
+- `permittedDrop`:        Basis point percent an auction can drop before it can be reset
+- `liquidationRatio`:     Basis point percent liquidation ratio for new collateral, sets the maximum amount of DAI debt that a vault user can draw from their vault given the value of their collateral locked in that vault [ex. 150% == 15000]
+- `kprFlatReward`:        Flat DAI reward a keeper receives for triggering liquidations (to compensate for gas costs)
+- `kprPctReward`:         Basis point percent reward keeper receive from liquidations
 ### Payments
 - `sendPaymentFromSurplusBuffer(address _target, uint256 _amount)`: Send a payment in ERC20 DAI from the surplus buffer.
 

src/CollateralOpts.sol

@@ -1,15 +1,39 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// CollateralOpts.sol -- DSS Executive Spell Collateral Options
+//
+// Copyright (C) 2021 Maker Ecosystem Growth Holdings, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
 pragma solidity ^0.6.12;
 
+/**
+    @title Collateral Onboarding Options
+    @notice This contract defines the CollateralOpts struct, used as parameter for addNewCollateral function
+    @dev For a more in depth description of the struct components visit https://github.com/makerdao/dss-exec-lib#collateral-onboarding
+*/
 struct CollateralOpts {
     bytes32 ilk;
     address gem;
     address join;
     address clip;
     address calc;
     address pip;
-    bool    isLiquidatable;
-    bool    isOSM;
-    bool    whitelistOSM;
+    bool isLiquidatable;
+    bool isOSM;
+    bool whitelistOSM;
     uint256 ilkDebtCeiling;
     uint256 minVaultAmount;
     uint256 maxLiquidationAmount;