Skip to main content

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#

  1. The price of the collateral declines in comparison with the price of cCHF. The vault of tz1user becomes untercollateralized. The view is_burrow_overburrowed then returns true for this vault. To check a vault in this view provide it's owners address, in this case tz1user with the id 0.
  2. The price of the collateral declines further and/or the Checker contract's protected_index catches up to the index. The view is_burrow_liquidatable now also returns true for this vault. The vault can now be partially (or fully) liquidated.
  3. 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 1 tez (the vault creation fee) + 0.1% of the marked vault's total collateral. The mark_for_liquidationentrypoint needs the parameters address which is the owners address tz1user and the id 0.
  4. 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#

  1. A touch is done on the Checker contract by calling the entrypoint touch which starts the current_auction. This is usually done by bots, but anybody can call the touchentrypoint at any time.
  2. The liquidation auction starts at a calculated price which declines over time, the auction is in descending state. Bidders can now start to bid. The view current_liquidation_auction_details shows the minimum amount of cCHF that needs to be bid.
  3. A first bidder steps forward and offers the minimum_bid by calling liquidation_auction_place_bid with the current auction_id and his bid amount as parameters. The auction now changes to ascending mode and the minimum_bid starts to increase. A countdown starts and counts down 20 blocks and 20 minutes (1200 seconds).
  4. 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_bid with the current auction_id and his bid amount as parameters. The countdown of 20 blocks and 20 minutes is reset and starts over.
  5. 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 touch entrypoint. 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#

  1. The winning bidder can now claim the collateral he was bidding on by calling the claim_winning_bid entrypoint 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 touch cannot process all of them and some excess collateral parts of completed auctions remain and are tracked in a completed_auction tree in the avl_storage. These collateral parts need to be processed before claim_winning_bid can be called. To process these collateral parts (slices), the entrypoint touch_liquidation_slices needs to be called with the ids of the slices as parameters. The ids of the slices of a completed_auction can be found by searching for all leaves in the AVL tree in liquidation_auctions>avl_storage>mem, which have the completed_auction id 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 claim_winning_bid entrypoint.

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.

Additional information#

Burrow ids#

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.

Excess cCHF#

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.