Maker Protocol Technical Docs
  • MakerDAO Technical Docs
  • Getting Started
    • Maker Protocol 101
  • Smart Contract Modules
    • Dai Module
      • Dai - Detailed Documentation
    • Core Module
      • Vat - Detailed Documentation
      • Spot - Detailed Documentation
    • Collateral Module
      • Join - Detailed Documentation
    • Liquidation 2.0 Module
    • System Stabilizer Module
      • Flapper - Detailed Documentation
      • Flopper - Detailed Documentation
      • Vow - Detailed Documentation
    • Oracle Module
      • Oracle Security Module (OSM) - Detailed Documentation
      • Median - Detailed Documentation
    • MKR Module
    • Governance Module
      • Spell - Detailed Documentation
      • Pause - Detailed Documentation
      • Chief - Detailed Documentation
    • Rates Module
      • Pot - Detailed Documentation
      • Jug - Detailed Documentation
    • Proxy Module
      • Proxy Actions - Detailed Documentation
      • Vote Proxy - Detailed Documentation
      • CDP Manager - Detailed Documentation
      • DSR Manager - Detailed Documentation
    • Flash Mint Module
    • Maker Protocol Emergency Shutdown
      • Emergency Shutdown for Partners
      • The Emergency Shutdown Process for Multi-Collateral Dai (MCD)
      • End - Detailed Documentation
      • ESM - Detailed Documentation
  • Glossary
    • MCD Glossaries
    • Smart Contract Annotations
  • Deployment Addresses
    • Maker Protocol Deployments
  • Security
    • Security for the Maker Protocol
  • Building on top of the Maker Protocol
    • Developer Guides and Tutorials
    • The Dai Javascript Library of the Maker Protocol
      • Getting started
      • Configuration
        • Plugins
      • Vault manager
      • Collateral types
      • Dai Savings Rate
      • Currency units
      • System data
      • Advanced
        • Transaction manager
        • DSProxy
        • Events
        • Using multiple accounts
        • Adding a new service
      • Single-Collateral Sai
        • Collateralized Debt Position
        • CDP Service
        • Price Service
        • System Status
        • Tokens
        • Token Conversion
        • Exchange Service
    • Pymaker
  • Keepers
    • The Auctions of the Maker Protocol
    • Auction Keepers
      • Auction Keeper Bot Setup Guide
    • Market Maker Keepers
      • Market Maker Keeper Bot Setup Guide
    • Cage Keeper
    • Simple Arbitrage Keeper
    • Chief Keeper
  • Command-line Interfaces
    • Seth
    • Multi Collateral Dai (MCD) CLI
    • Dai and Collateral Redemption during Emergency Shutdown
    • Emergency Shutdown (ES) CLI
  • Miscellaneous
    • Liquidations 1.2 System (Deprecated)
      • Cat - Detailed Documentation
      • Flipper - Detailed Documentation
    • SCD <> MCD Migration
    • Upgrading to Multi-Collateral Dai Guide
Powered by GitBook
On this page
  • Introduction
  • Prerequisites
  • Architecture
  • Operation
  • Installation
  • Sample Startup Script
  • Testing
  • License
  • Support
Export as PDF
  1. Keepers

Cage Keeper

A Keeper to facilitate Emergency Shutdown

PreviousMarket Maker Keeper Bot Setup GuideNextSimple Arbitrage Keeper

Last updated 3 years ago

Introduction

The cage-keeper is used to help facilitate of the . Emergency shutdown is an involved, deterministic process, requiring interaction from all user types: Vault owners, Dai holders, Redemption keepers, MKR governors, and other Maker Protocol Stakeholders. A high level overview is as follows:

  1. System Caged - The Emergency Security Module calls End.cage() function, which freezes the USD price for each collateral type as well as many parts of the system.

  2. Processing Period - Next, Vault owners interact with End to settle their Vault and withdraw excess collateral. Auctions are left to conclude or are yanked before Dai redemption.

  3. Dai Redemption - After the processing period duration End.wait has elapsed, Vault settlement and all Dai generating processes (auctions) are assumed to have concluded. At this point, Dai holders can begin to claim a proportional amount of each collateral type at a fixed rate.

To prevent a race-condition for Dai holders during Step 3, it's imperative that any Vaults having a collateralization ratio of less than 100% at Step 1 must be processed during Step 2. The owner of an underwater Vault would not receive excess collateral, so they lack an incentive to skim their position in the End contract. Thus, it is the responsibility of a MakerDAO Stakeholder (MKR holders, large Dai holders, etc) to ensure the system facilitates a Dai redemption phase without a time variable. The cage-keeper is a tool to help stakeholders carry out this responsibility.

Prerequisites

The following section assumes familiarity with Emergency Shutdown. Good places to start is the Emergency Shutdown Module in Section 3 and Section 4 of the as well as a more thorough, . Functions mentioned are from the implementation contained by the End contract, which is .

To be consistent with the Protocol's technical terminology for the rest of this description:

  • urn = Vault

  • ilk = Collateral Type

Architecture

The cage-keeper directly interacts with the End, Flopper and Flapper contracts.

The central goal of the cage-keeper is to process all under-collateralized urns. This accounting step is performed within End.skim(), and since it is surrounded by other required/important steps in the Emergency Shutdown, a first iteration of this keeper will help to call most of the other public function calls within the End contract.

As can be seen in the above flowchart, the keeper checks if the system has been caged before attempting to skim all underwater urns and skip all flip auctions. After the processing period has been facilitated and the End.wait wait time has been reached, it will transition the system into the Dai redemption phase of Emergency Shutdown by calling End.thaw() and End.flow(). This first iteration of this keeper is naive, as it assumes it's the only keeper and attempts to account for all urns, ilks, and auctions. Because of this, it's important that the keeper's address has enough ETH to cover the gas costs involved with sending numerous transactions. Any transaction that attempts to call a function that's already been invoked by another Keeper/user would simply fail.

Operation

This keeper can either run continuously on a local/virtual machine or be run when the operator becomes aware of Emergency Shutdown. A sample startup script is shown below. The keeper's Ethereum address should have enough ETH to cover gas costs and is a function of the protocol's state at the time of shutdown (i.e. more urns to skim means more required ETH to cover gas costs). When new collateral types are added to the protocol, the operator should pull the latest version of the keeper, which would include contracts associated with the aforementioned collateral types.

After the cage-keeper facilitates the processing period, it can be turned off until End.wait is nearly reached. Then, at that point, the operator would pass in the --previous-cage argument during keeper start in order to bypass the feature that supports the processing period.

Installation

This project uses Python 3.6.2.

In order to clone the project and install required third-party packages please execute:

git clone https://github.com/makerdao/cage-keeper.git
cd cage-keeper
git submodule update --init --recursive
./install.sh

Sample Startup Script

Make a run-cage-keeper.sh to easily spin up the cage-keeper.

#!/bin/bash
/full/path/to/cage-keeper/bin/cage-keeper \
	--rpc-host 'sample.ParityNode.com' \
	--network 'kovan' \
	--eth-from '0xABCAddress' \
	--eth-key 'key_file=/full/path/to/keystoreFile.json,pass_file=/full/path/to/passphrase/file.txt' \
	--vat-deployment-block 14374534

Testing

Prerequisites:

In order to be able to run tests, please install development dependencies first by executing:

pip3 install -r requirements-dev.txt

You can then run all tests with:

./test.sh

License

Support

For some known Ubuntu and macOS issues see the README.

Download

This project uses for unit testing. Testing of Multi-collateral Dai is performed on a Dockerized local testchain included in tests\config.

See file

If you have questions regarding Cage Keepers, please reach out to us on the channel on .

pymaker
docker and docker-compose
pytest
COPYING
#keeper
chat.makerdao.com
Emergency Shutdown
Maker Protocol
(ESM)
Maker Protocol 101
technical description
located here