Checker Liquidation Auction Flow
If a checker vault becomes undercollateralized (overburrowed in Checker terminology), meaning it's collateral does not cover the amount of outstanding cCHF, a part of it's collateral will be put up for a liquidation auction. Bidders can then bid in cCHF and get the liquidated vault's collateral if they win the liquidation auction.
This is how a liquidation auction takes place from the perspective of a bidder:
#Before a liquidation auction starts
- The price of the collateral declines in comparison with the price of cCHF. The vault of tz1user becomes untercollateralized. The view
truefor this vault. To check a vault in this view provide it's owners address, in this case tz1user with the id 0.
- The price of the collateral declines further and/or the Checker contract's
protected_indexcatches up to the
index. The view
is_burrow_liquidatablenow also returns
truefor this vault. The vault can now be partially (or fully) liquidated.
- A user observes that the vault of tz1user is now liquidateable and marks this vault for liquidation by calling the entrypoint
mark_for_liquidation. This user, let's call him the marker, immediately receives 10% of the collateral that will be auctioned off as a reward for marking the vault. The
mark_for_liquidationentrypoint needs the parameters
addresswhich is the owners address tz1user and the id 0.
- The vault of tz1user is now marked for liquidation. A part of his collateral is queued for the next upcoming liquidation auction.
#The liquidation auction starts
- A touch is done on the Checker contract by calling the entrypoint
touchwhich starts the
current_auction. This is usually done by bots, but anybody can call the
touchentrypoint at any time.
- The liquidation auction starts at a calculated price which declines over time, the auction is in
descendingstate. Bidders can now start to bid. The view
current_liquidation_auction_detailsshows the minimum amount of cCHF that needs to be bid.
- A first bidder steps forward and offers the
liquidation_auction_place_bidwith the current
auction_idand his bid amount as parameters. The auction now changes to
ascendingmode and the
minimum_bidstarts to increase. A countdown starts and counts down 20 blocks and 20 minutes (1200 seconds).
- A second bidder takes part and offers a higher bid than the current
minimum_bid(which is always higher than the first bid) by calling
liquidation_auction_place_bidwith the current
auction_idand his bid amount as parameters. The countdown of 20 blocks and 20 minutes is reset and starts over.
- Once the countdown has run down, on blocks and seconds (whichever comes last), the auction can be closed by touching the contract again using the
touchentrypoint. This ends the current auction and immediately triggers the start of the next auction if there is any collateral queued for being auctioned off.
#After the liquidation auction ended
- The winning bidder can now claim the collateral he was bidding on by calling the
claim_winning_bidentrypoint with the auction id as parameter. Attention: If too many collateral parts (slices in Checker terminology) were in the auction that just completed, the following
touchcannot process all of them and some excess collateral parts of completed auctions remain and are tracked in a
completed_auctiontree in the
avl_storage. These collateral parts need to be processed before
claim_winning_bidcan be called. To process these collateral parts (slices), the entrypoint
touch_liquidation_slicesneeds to be called with the ids of the slices as parameters. The ids of the slices of a
completed_auctioncan be found by searching for all leaves in the AVL tree in
liquidation_auctions>avl_storage>mem, which have the
completed_auctionid as a root. By calling
touch_liquidation_slices, these completed auction slices will be processed. Note, that depending on the number of completed auction slices, this might be needed to be done several times, due to gas restrictions and needed computing resources. Once all slices have been processed, the liquidation auction winner can claim his bid, by calling the
#Cancelling a queued slice
When a user is marked for liquidation, he has the possibility to cancel the liquidation, by adding more collateral or payback (burn in Checker terminology) cCHF to cover. If the user adds enough collateral or pays back enough cCHF and has a Collateralization Ratio of less than 100%, he can cancel the liquidation of his collateral part (slice). This can be done via the frontend, but can also be done by calling the entrypoint
cancel_liquidation_slice, providing the slice ID of the auction slice to be cancelled. Cancelling liquidation slices can only be done if the user is not undercollateralized/overburrowed and the auction slice is not part of a current or completed auction.
When marking vaults or querying the views we need to provide the
id of the burrow (vault). In our implementation this always is
id 0 which stands for the first borrow (vault) created. The contract would allow for a user to create more than one burrow, but the youves frontend does not support this. We advise to not create more than one burrow even if the contract would allow to do so. The frontend will not provide any detail information about vaults with ids other than 0.
In some cases, when the bid raises more cCHF than a vault has outstanding, all of the outstanding cCHF will be burned (paid back) and the excess cCHF will be paid to the vault owner who's vault got liquidated.
More information about the liquidation auctions can be found here.