Cat - Detailed Documentation
The Maker Protocol's Liquidation Agent
Contract Name: cat.sol
Type/Category: DSS
1. Introduction (Summary)
The Cat
is the system's liquidation agent, it enables keepers to mark positions as unsafe and sends them to auction.
2. Contract Details
Glossary (Cat)
Math
mul(uint, uint)
/rmul(uint, uint)
- will revert on overflow or underflowbite(bytes32, address)
will revert iflot
orart
are larger than or equal to 2^255.bite
will not leave a Vault with debt and no collateral.
Auth
wards
are allowed to call protected functions (Administration andcage()
)
Storage
ilks
storesIlk
structsIlk
is the struct with the address of the collateral auction contract (flip
), the penalty for that collateral to be liquidated (chop
) and the maximum size of collateral that can be auctioned at once (dunk
).
live
must be1
for theCat
tobite
. (seecage
in mechanisms)box
the limit on the debt and penalty fees available for auction. [RAD]dunk
("debt chunk") amount of debt plus penalty fee per auction, in Dai. [RAD]vat
address that conforms to aVatLike
interface (seevat
documentation for more info). It is set during the constructor and cannot be changed.vow
address that conforms to aVowLike
interface (seevow
documentation for more info).
The values of all parameters here (except vat
) are changeable by an address that is rely
ed on. For instance, the End
module should be auth
ed to allow for it to call cage()
and update live
from 1 to 0. Governance (through an auth
ed address) should be able to add collateral types to Cat
, update their parameters, and change the vow
.
Unsafe
bite
can be called at anytime but will only succeed if the Vault is unsafe. A Vault is unsafe when its locked collateral (ink
) times its collateral's liquidation price (spot
) is less than its debt (art
times the fee for the collateral rate
). Liquidation price is the oracle-reported price scaled by the collateral's liquidation ratio.
Events
Bite
: emitted when abite(bytes32, address)
is successfully executed. Contains:ilk
: Collateralurn
: Vault addressink
: seelot
inbite
art
: seeart
inbite
tab
: seetab
inbite
flip
: address of the auction contractid
: ID of the auction in theFlipper
3. Key Mechanisms & Concepts
cage()
auth
sets
live
to 0 (preventsbite
). SeeEnd
documentation for further description.Once
live=0
it cannot be set back to 1.
bite(bytes32 ilk, address urn)
bytes32 ilk
parameter represents the collateral type that is being bitten.address urn
the address that identifies the Vault being bitten.returns
uint id
which is the ID of the new auction in theFlipper
.bite
checks if the Vault is in an unsafe position and if it is, it starts a Flip auction for a piece of the collateral to cover a share of the debt.
The following is a line-by-line explanation of what bite
does.
Administration
Various file function signatures for administering Cat
:
Setting new vow (
file(bytes32, address)
)Setting new collateral (
file(bytes32, bytes32, address)
)Setting penalty or dunk size for collateral (
file(bytes32, bytes32, uint)
)
Usage
The primary usage will be for keepers to call bite
on a Vault they believe to be unsafe in order to start the auction process.
4. Gotchas (Potential source of user error)
When the
Cat
is upgraded, there are multiple references to it that must be updated at the same time (End
,Vat.rely
,Vow.rely
). It must also rely on theEnd
, the system'spause.proxy()
A
Vat
upgrade will require a newCat
The Cat stores each
Ilk
's liquidation penalty and maximum auction size.Each ilk will be initiated with the
file
for theirFlipper
; however, auctions cannot start untilfile
is also called to set thechop
and thedunk
. Without these auctions for either 0 gems or 0 dai would be created by callingbite
on an unsafe Vault.bite
needs to be calledn
times wheren = urn.ink / ilks[ilk].dunk
ifn > 1
. This allows for the possibility that the Vault becomes safe betweenbite
calls either through increased collateral (in value or quantity), or decreased debt.Calling
bite
returns the auctionid
and emits and event with theid
. This is required to bid in theFlipper
on the auction.
5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)
Coding Error
A bug in the Cat
could lead to loss (or locking) of Dai and Collateral by assigning it to an address that cannot recover it (i.e. a bad Vow address or an incorrectly programmed Flipper). The main coding failure mode of Cat
is if it has a bug that causes auctions to cease to function. This would require upgrading the system to a corrected Cat
contract. If there is a bug in Cat
that reverts on cage
then it would cause Shutdown could fail (until a correct Cat
is launched).
Feeds
The Cat
relies indirectly on the price Feeds as it looks to the Vat
's tracking of the collateral prices (spot
) to determine Vault safety. If this system breaks down, it could lead to theft of collateral (too low spot
) or unbacked Dai (incorrectly high spot
).
Governance
Governance can authorize and configure new collaterals for Cat
. This could lead to misconfiguration or inefficiencies in the system. Misconfiguration could cause Cat
not to operate properly or at all. For instance, if an Ilk.dunk
is set to be greater than 2**255 could allow for very, very large Vaults to be un-bite
-able.
Inefficiencies in the dunk
or chop
could affect auctions. For instance, a dunk
that is too large or too small could lead to disincentives for keepers to participate in auctions. A chop
that is too small would not sufficiently dis-incentivize risky Vaults and too large could lead to it being converted to bad debt. Further discussion of how the parameters could lead to system attacks is described in this Auction Grinding paper.
Flipper
The Cat
relies on an external Flipper contract to run the auction and moves the collateral from the Cat
to the Flipper
contracts in the Vat
. A faulty collateral auction contract could result in the loss of collateral or dai or non-functioning auctions.
Last updated