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
Installation
Contract Address Setup
Dai Holders to Redeem Collateral
Check user Dai holdings
Approve a Proxy
Create Calldata
Execute Calldata using the MYPROXY Contract
Call cashETH or cashGEM functions
Using cashETH
Define calldata for our function
Execute cashETHcalldata
Alternative from step (6), Using cashGEM
Define calldata for our function
Call execute in MYPROXY
Vault Owners to Redeem Excess Collateral
Vault Holder State
Redeeming ETH using the freeETH function
2.1. Set Call Data
2.2 Execute this calldata
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 toolset. We also provide further installation information here. 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 which can be verified on Etherscan. Similarly, additional information on the commands described below can be found in the End contract and the Proxy_Actions_End contract. These should be setup in the following manner and pasted into the terminal line by line:
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.
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.
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.
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.
export calldata=$(seth calldata 'pack(address,address,uint)' $MCD_JOIN_DAI $MCD_END $wad)
.
.
.
# 0x33ef33d6000000000000000000000000fc0b3b61407cdf5f583b5b1e08514e68ecee4a73000000000000000000000000d9026db5ca822d64a6ba18623d0ff2bb07ad162c0000000000000000000000000000000000000000000002d66a5b4bc1da600000
4. Execute calldata using the MYPROXY
contract
MYPROXY
contractThe 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.
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
cashETH
or cashGEM
functionsUsers 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
cashETH
The following function cashETH
is referenced as part of the calldata
function and should be referenced here.
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.
export cashETHcalldata=$(seth calldata 'cashETH(address,address,bytes32,uint)' $MCD_JOIN_ETH $MCD_END $ilk $wad)
8. Execute cashETHcalldata
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.
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
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.
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
export cashBATcalldata=$(seth calldata 'cashETH(address,address,bytes32,uint)' $MCD_JOIN_BAT $MCD_END $ilkBAT $wad)
11. Call execute in MYPROXY
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.
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
freeETH
functionfunction 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.
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.
seth send $MYPROXY 'execute(address,bytes memory)' $PROXY_ACTIONS_END $freeETHcalldata
3. Redeeming ETH using the freeGEM
function
freeGEM
functionfunction 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.
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.
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.
Last updated