Skip to content

Latest commit

 

History

History
332 lines (207 loc) · 27.3 KB

emergency-shutdown-design-patterns.md

File metadata and controls

332 lines (207 loc) · 27.3 KB
Raw
title description parent tags slug contentType root
Emergency Shutdown Design Patterns for Integrations
Learn about design processes for the emergency shutdown process
mcd
emergency shutdown
mcd
shutdown process
design processes
emergency-shutdown-design-patterns-for-integrations
guides
false

Emergency Shutdown Design Patterns for Integrations

Level: Advanced

Estimated Time: 45 min

Overview

Dai is a stablecoin softly pegged to the U.S. Dollar and backed by Vault owners' debt. The Vault owners’ incentive to pay back the debt in order to retrieve locked collateral allows Dai to trade in a tight band around its 1 USD peg. Even in the permissionless environment created by the Maker Protocol, Dai trades around its internal reference price because of well-crafted incentives for both Dai and Vault owners. These constituencies can only achieve their goals if they are able to consistently buy and sell Dai at or near its peg. If one constituency consistently pays a premium over a long term, it affects the entire ecosystem, which depends on the market price being reasonable.

Maker governance can impact various incentives through adjustments to mechanisms like the Dai Savings Rate, Stability fees, and Debt ceilings of collateral types. These adjustments may correct short term drifts of the market price away from the peg, but they cannot force Dai holders or Vault owners to behave a certain way since the assets themselves are permissionless. The only meaningful (dis)incentive available to protect the ecosystem from long term irrationality is the threat to trigger an emergency shutdown and settle all Dai holders and Vault owners by giving back their future fair value of 1 USD/DAI.

While this is an action of last resort, all products that integrate with both Dai and Vaults must appropriately prepare to address the changes Maker Protocol will undergo when Emergency Shutdown is triggered:

  • Dai will no longer be softly pegged to 1 USD and the market price of Dai will transition to the value of the basket of collateral locked in the system and backing Dai.

  • Existing Vaults will be frozen and owners can only retrieve excess collateral if their debt is settled.

  • New Dai will no longer be generated by the Maker Protocol.

Learning Objectives

In this guide, we will help you understand the impact Emergency Shutdown will have on your system's integration with components in the Maker Protocol and highlight design patterns you can implement to ensure your users are protected and know the path forward after emergency shutdown is triggered.

Pre-requisites

Effects

Emergency shutdown will generally have the below functionality changes on various components of the Maker Protocol.

Dai

  • Dai token operations will not be restricted and Dai can be transferred.
  • Dai balances held in Vat may also be transferred between addresses.
  • There could be a Dai supply crunch because,
    • Existing Dai token balances will gradually migrate internally to redeem underlying collateral.
    • DaiJoin adapter will completely stop new Dai token issuance.
    • No new Dai can be generated from vaults.
  • Dai Savings Rate(DSR) in Pot is set permanently to 0%.

Vaults

  • Vaults will be frozen immediately and cannot generate new Dai anymore. All debt will be removed when skim is executed on each Vault by keepers.
  • Excess collateral from Vaults that have been skimmed can be withdrawn using free in End.
  • Locked collateral and debt can still be transferred between Vaults as long as they continue to remain safe.
  • Collateral adapters will stop users from depositing collateral into the system.
  • Transfer functions will not be frozen and internal collateral balances can be transferred between addresses.
  • Vaults cannot be liquidated anymore and the bite function in Cat is frozen.

Price feeds

  • Price feeds have two main components and are not linked to Emergency Shutdown and will remain operational after it is triggered.
    • Medianizer contract which aggregates price feed data is not frozen.
    • Oracle Security Module that introduces a security delay is also not frozen.
  • Internal price values of collateral types adjusted for their collateralization ratios stored in spot within Vat will be frozen and can no longer be updated even when price feeds report new values.
  • Shortly after shutdown, collateral prices will be pulled from each OSM and fixed in End, and will later be used for Vault settlement and Dai redemption.

Auctions

  • Existing debt and surplus auctions will be frozen, and new ones cannot be started.
  • Bidders(or anyone) can execute yank to retrieve their MKR or Dai bid amounts from debt and surplus auctions that have not been finalized.
  • Collateral auctions that are still in their first tend phase can be stopped by anyone with skip in End to return the Dai submitted back to the bidder.

Features

In this section, we briefly discuss how emergency shutdown is handled by the Maker Protocol and the user expectations it sets.

If there are undercollateralized Vaults, or there is net system deficit at the time of emergency shutdown (including debt from canceled debt auctions), Dai holders receive a haircut which means they will only be able to redeem collateral that is valued at less than 1 USD.

Any system Dai surplus existing at the time of emergency shutdown is also passed along to Dai holders, which will allow them to retrieve collateral valued at greater than 1 USD based on the prices fixed in the End shortly after shutdown.

The system is designed to ensure that Vault owners do not receive a haircut in the amount of excess collateral they can withdraw (over the amount required to satisfy their debt) when other Vaults are left under-collateralized. This gives Vault owners the confidence to maintain safe collateralization levels during normal operations.

The cooldown period is used to conduct certain calculations that allow the system to determine the amounts of collateral it can allow each Dai holder to redeem. This ensures there is no race condition amongst Dai holders to redeem their collateral early before others.

All calculations necessary for emergency shutdown are performed on-chain. While off-chain actors still have responsibilities to monitor and call certain functions in order to fully process debt and settle the system, no one, including governance, is trusted to calculate and submit external values into the system during emergency shutdown.

The Maker Protocol completely halts its operations after emergency shutdown is triggered and operates only in a settlement mode that ensures various stakeholders can safely retrieve assets. Please note that you are free to use different criteria and features in your protocol and communicate those expectations to your users.

We suggest reading the following documents for an overview of the Emergency Shutdown Mechanism and how various users will interact with the Maker Protocol- ES Documentation, ES Guide, and Cage Keeper Documentation.

Monitoring

Vault owners are allowed to withdraw their excess collateral immediately while Dai holders have to wait for a cooldown period before they can start withdrawing their portion of the collateral.

Parties may either manually or through Keeper bots take multiple actions to process any outstanding system debt or system surplus.

While governance has control over some of these parameters, relevant parameters are stored locally in End where they cannot be modified after emergency shutdown is triggered.

Status of the system

The live flag is stored within the End, Vat, Cat, Vow, Spot, Pot, Flap, and Flop contracts and is initialized to 1 during initial deployment. Executing the cage function in End to trigger emergency shutdown changes the value of live to 0 in all these contracts.

You can rely on the emergency shutdown flag live on the Maker protocol or store it locally and use an off-chain script to monitor the maker protocol and synchronize it.

Timestamp

The timestamp at which emergency shutdown is triggered is stored in the when variable within End.

Cooldown period

Dai redemption can occur only after the cooldown period is over, which runs from emergency shutdown being triggered. The length of this time period is stored in the wait variable.

Dai haircut

Dai holders could receive a haircut to their collateral redemption when there is existing system debt or undercollateralized vaults in the system.

The Maker Protocol will first attempt to cancel system debt with surplus, but any remaining system debt is passed on to Dai holders as a haircut to the 1 USD/Dai value they receive back from the system. You can monitor the system debt with the Vice value in Vat.

Debt not backed by collateral in undercollateralized vaults is also passed on as a haircut to Dai holders. You can monitor this by checking the gap value of each collateral type in End after the cooldown period ends.

Dai surplus

System surplus is also passed on to Dai holders. You can monitor the system surplus with the internal Dai balance of the Vow contract address within Vat.

Collateral type processing

The amount of collateral each Dai can redeem after the cooldown period is set for each collateral type individually in fix after the processing is complete.

Emergency Shutdown processing

live is set to 0 when emergency shutdown is triggered.

tag is set when the value of a collateral type is locked.

fix value finalizes the amount of collateral each Dai will redeem.

gap is used for intermediate calculations and its value should not be relied upon directly.

out value tracks the Dai amount each address has successfully redeemed for each type of collateral.

Vault

Vaults are liquidated (without a liquidation penalty) and their debt, along with a portion of collateral, locked (sufficient to cover the Vault’s debt based on tag) by a call to the skim method of End (per Vault) after emergency shutdown is triggered. All systems should read the amount of collateral locked (ink) and the amount of debt held by the vault (art) directly from Vat.

Emergency shutdown trigger

Emergency shutdown is triggered by an executive vote and will be processed only after it has gone through the governance delay set in Pause. Please note that any scheduled executive action can also be withdrawn by governance within this window.

Decentralized Emergency Shutdown

There is a decentralized mechanism available to MKR holders to trigger emergency shutdown if the Sum amount of MKR locked in the Emergency Shutdown Module (ESM) contract exceeds the min threshold set by governance. Emergency shutdown is effective immediately and can be instantaneous when triggered via this route.

Dai Reference Price

If Emergency Shutdown is triggered, the Maker Protocol calculates how much of each collateral type can be redeemed per Dai. This calculation is done per collateral type when the cage() function is called. See below:

function cage(bytes32 ilk) external note {
        require(live == 0, "End/still-live");
        require(tag[ilk] == 0, "End/tag-ilk-already-defined");
        (Art[ilk],,,,) = vat.ilks(ilk);
        (PipLike pip,) = spot.ilks(ilk);
        // par is a ray, pip returns a wad
        tag[ilk] = wdiv(spot.par(), uint(pip.read()));
    }

The tag mapping in the last line of the function sets the price for each collateral. The price of the collateral types is influenced by the par parameter in the system, par being the reference price of Dai in the Maker Protocol. Depending on the value of par set by Maker governance, the system will calculate the final amount of collateral the user is entitled to redeem per Dai.

Therefore, if you are integrating Dai redemption functionality, it is important to take par into consideration.

Design Patterns

We believe each system that integrates with the Maker Protocol is unique and must design and implement a tailored Emergency Shutdown plan. Our goal with this guide is to highlight a few design patterns we have observed so far that permit components to modify their behavior after Emergency Shutdown is triggered. As you analyze the impact Emergency Shutdown could have on various aspects of your system, you can use these design patterns as a starting point to mitigate adverse affects Emergency Shutdown could cause for your users.

For each pattern, we go over at least one example function scenario where the pattern could be applied and why it is most suitable. We also discuss how each pattern applies to Dai held or debt carried by users within your system, common pitfalls you can avoid during implementation, ideal values you need to monitor both before and after Emergency Shutdown is triggered, and any infrastructure you may need to set up.

These patterns are usually not applied at the system level. Instead, you will need to analyze the impact of emergency shutdown on each part of your system and determine if one of these patterns can be applied to mitigate issues. Some patterns may immediately halt a portion of your system while others will continue to permit its operation. In some instances, you may not need to implement anything special to handle Emergency Shutdown because there may be no impact on the functionality of your system.

We cover the following patterns in the remainder of this guide,

  • Freeze actions
  • Oracle price feeds
  • Undo
  • Withdrawal
  • Debt substitution
  • Settlement
  • Recursive redemption

Freeze actions

Freezing the part of your system that interacts with Dai when Emergency Shutdown is triggered will help you avoid complications that could arise from Dai, which would no longer be stable. You can use this approach if you need Dai to be stable at all times within your system.

Implementing this will completely halt usage of Dai in your system, and this action cannot be reversed. Monitoring for Emergency Shutdown triggering is required to activate freeze in your system. You can either read the live flag directly from the Maker Protocol for all calls from your system, or synchronize that value first to an internal flag within your system and then allow your functions to read from this flag internally.

Dai

Entry points that let users bring Dai into your system will need to be blocked. You can choose to let users immediately withdraw Dai to their own addresses, and they can wait for the cooldown period to be done before withdrawing collateral themselves. Or, you can choose to use the cooldown period for any internal processing and activate Dai withdrawals only after this period is over.

Debt

Implementing freeze on the parts of your system that interact with Vault debt is the right choice most of the time because all debt and the leverage it enables disappear shortly after Emergency Shutdown. A portion of collateral is removed and debt is zeroed in each vault when keepers execute the public skim function right after Emergency Shutdown gets triggered. Unlike Dai, which still has value and can be transferred between addresses, Vault debt is fully settled, and the existing system will no longer be able to generate new debt. Since the debt is already settled and paid for with a portion of locked collateral, it cannot be repaid manually.

Oracle price feeds

Dai is an ideal choice for collateral in systems like lending protocols because it is decentralized. Its value is not lost but becomes pegged to a basket of collateral, instead of 1 USD. Sometimes, there is no need to freeze the usage of Dai completely. Dai will continue to hold value, and you can operate normally if your system is already set up to deal with unstable assets along with Dai. Taking this approach to manage Emergency Shutdown could minimize disruption to both your protocol and your users.

Although common, you should not rely on a hardcoded 1 USD value as a proxy for Dai due to complications it could create when Emergency Shutdown is triggered. A real-time, actual DAI-USD price feed oracle is needed to ensure that Dai is accurately valued both before and after Emergency Shutdown. Please note that the Maker price feed oracles currently do not provide a Dai price feed, and other price feeds, like ETH-USD, do not take the market value of Dai into account.

As long as you do not need to tweak any other parameters to handle an unstable Dai, there is no need to monitor Emergency Shutdown if the price feeds are already able to address its impact and report an accurate Dai value.

Undo

The cooldown period set in the Maker Protocol presents an opportunity for everyone to perform certain actions that require time to complete and return Dai. We see this in the yank implementation present in various auctions the Maker Protocol runs, which could take longer than the cooldown period.

There could always be in-progress items in your system, like auctions, that take some time to be finalized, and not all actions in a system can be completed within a single block. It is important for your system to ensure these long running actions can be reversed or prematurely finalized if Emergency Shutdown is triggered users do not incur any loss of assets.

You can make use of the cooldown period or create your own internal version with a time period that suits your system needs. A yank-like function, internal to your protocol, could be implemented that can undo a long running action to facilitate returning Dai back to the user. Restrictions can be placed on who can execute yank during the cooldown period. Such restrictions can either be called solely by an administrator or be open for anyone to call.

In the Maker Protocol, debt auctions do not allow a current active bidder to withdraw its bid in the normal course of operations, but a yank function can be activated after Emergency Shutdown is triggered to send the Dai back to the active bidder whose bid is in progress and hasn't been finalized yet.

You can monitor the when variable, which stores the timestamp when Emergency Shutdown is triggered, and optionally monitor the wait variable to synchronize with Maker Protocol's cooldown period. We also advise you to build and set up off-chain bots, which can perform yanks automatically, to quickly revert to a safe state right after Emergency Shutdown is triggered.

Withdrawal of Dai

Digital asset custodians and similar services that hold Dai balances on behalf of users may need to prepare for large amounts of Dai withdrawals from users simultaneously after Emergency Shutdown. This is particularly prescient if users are forced to use external Emergency Shutdown interfaces to withdraw collateral. Building functionality to either allow users to access the collateral or exchange Dai with other assets could be helpful as users will not be forced to interact with new services.

You can monitor the live flag in End to be notified when the Emergency Shutdown gets triggered and prepare for upcoming user withdrawals after the cooldown period is finished.

Debt Substitution

Collateral operators who oversee the management of digital tokens representing real world assets might find Emergency Shutdown particularly disruptive to their operations because Emergency Shutdown will instantly disperse ownership of the asset from a small group of people to a large group of Dai holders, each now owning a very small portion. While we do envision the majority of Dai holders trading Dai back to keepers for other assets instead of participating in collateral redemption themselves, this may still be a significant impediment for integration of your collateral type in the Maker Protocol.

Using a debt substitution mechanism, you could create an intermediate layer of debt tokens, which are used to back the Vault's debt while the digital tokens representing the ownership claims on your collateral stay locked in a smart contract. Instead of directly transferring collateral ownership, the Vault owners or the collateral operator is allowed within a predefined time period after Emergency Shutdown to substitute the value of the collateral locked with a stablecoin and redeem their entire collateral locked in one piece. If debt is not substituted within a time window, collateral will continue to be settled and Dai owners can access it in redemption.

While it can mitigate some effects, collateral owners accessing leverage from the Maker Protocol will still need to be prepared for leverage to instantly disappear along with a portion of the collateral or have a backup plan to replace this with leverage from another source at a short notice.

This pattern was originally proposed (not implemented) in the Tinlake framework developed by Centrifuge, and currently no smart contract infrastructure or risk models exist to onboard collateral with this pattern. Many details still need to be figured out, but you could use this as a starting point to think of ways to mitigate distribution of your collateral type to a wide group of users after Emergency Shutdown.

You will need to monitor the emergency shutdown flag live. Please note that the cooldown period has no effect on debt held by Vault owners. The debt gets settled when skim, which is open for anyone to call, is executed after live is set to 0.

Settlement

Derivative contracts which have Dai locked as collateral and are sensitive to Dai becoming unstable will have to settle the contracts right after Emergency Shutdown is triggered. It is important that any such settlement takes into account the time left in the contract after Emergency Shutdown to calculate and distribute portions of locked Dai back to parties to the contract.

Contracts that have already matured need not be processed through this settlement logic and the Emergency Shutdown timestamp can be used to make this decision.

Additionally, a best practice would be to explicitly include the effects of Emergency Shutdown on the distribution mechanisms of the contract in the terms so that parties have appropriate notice of that potential eventuality before entering into the contract..

You can monitor the when timestamp to get the timestamp when Emergency Shutdown is triggered and synchronize it for your internal components.

You might have to set up valuation oracles if a fair value for settlement cannot be calculated using on-chain logic.

Recursive Redemption

Dai itself does not disappear and will continue to remain fungible and transferable. It is very likely that there is no need for you to handle collateral redemption on behalf of your users aside from their convenience.

The number of function calls needed to redeem collateral from the system will at minimum be equal to the number of collateral types active in the system.

Collateral redemption will have to be processed in multiple rounds when Dai or assets backed with Dai are present as collateral within the system when emergency shutdown is triggered. After each round of redemption, you could receive assets that need to be redeemed for Dai in their respective systems, which needs to be processed again with another round of collateral redemption in order to acquire more collateral. Please ensure that you are set up to handle this when implementing collateral redemption for your users.

Communication Plan

The MakerDAO has not outlined any specific scenarios under which governance will trigger an emergency shutdown yet, and we will update this guide once there is more information available.

As a part of your integration, you should establish a communication plan to educate your users and help them understand what Emergency Shutdown is and the impact it could have throughout your system.

You should also implement a plan to guide your users on the actions they must take after Emergency Shutdown is triggered.

You should also establish a communication plan to send messages to your users while your integration with the Maker Protocol is live. Many times your system could be the only gateway to Dai for your users, and it is important for them to understand what could happen to Dai once the Emergency Shutdown is triggered.

Summary

While we have discussed many patterns, you can use the following rule of thumb to determine whether you should apply one. Most functionality in your system that deals with Dai need not apply a design pattern if the unit of account is 1 Dai disconnected from its market price. If the functionality is using the value of Dai either as an asset pegged to 1 USD or as a stable and valuable collateral, you might have to implement one or more of the above patterns to permit that functionality to effectively manage the abrupt transition of the Maker Protocol and resulting immediate effect on the value of Dai. Only you as the system's designer can assess how the Maker Protocol Emergency Shutdown can be addressed to protect your users.

Troubleshooting

Next Steps

  • Checkout the cage-keeper repo for details on how to setup an Emergency Shutdown processing bot.

Resources