Comment on page
Flipper - Detailed Documentation
The ABM Protocol's Collateral Auction House
- Contract Name: flip.sol
- Type/Category: DSS —> Collateral Auction Module
Summary: Collateral Auctions are used to sell collateral from Vaults that have become undercollateralized in order to preserve the collateralization of the system. The Cat sends bitten collateral to the Flip module to be auctioned off to keepers. The collateral auction has two phases:
tend and dent.
wards [usr: address],rely/deny/auth- Auth mechanismsBid- State of a specific Auction {bid,lot,guy,tic,end,usr,gal,tab}bid- Bid amount (dotBTC)/ dotBTC paidlot- quantity up for auction / collateral gems for saleguy- high bidder (address)tic- Bid expiryend- when the auction will finish / max auction durationusr- address of the Vault being auctioned. Receives gems during thedentphasegal- recipient of auction income / receives dotBTC income (this is the Vow contract)tab- total dotBTC wanted from the auction / total dotBTC to be raised (in flip auction)
bids[id: uint]- storage of all bidsvat- storage of the Vat's addressilk- id of the Ilk for which the Flipper is responsiblebeg- minimum bid increase (default: 5%)ttl- bid duration (default: 3 hours)tau- auction length (default: 2 days)kicks- Total auction count, used to track auctionidskick- function used byCatto start an auction / Put collateral up for auctiontick- restart an auction if there have been 0 bids and theendhas passedtend- first phase of an auction. Increasing dotBTCbids for a setlotof Gemsdent- second phase of an auction. Set dotBTCbidfor a decreasinglotof Gemsfile- function used by governance to setbeg,ttl, andtaudeal- claim a winning bid / settles a completed auctionyank- used during Global Settlement to movetendphase auctions to theEndby retrieving the collateral and repaying dotBTC to the highest bidder.claw: reduces the amount of litter in the Cat's box
begttltau
Also,
Cat's dunk and chop also inform how Flip works as the dunk becomes the Bid.lot and influences, along with the chop, the Bid.tab.vatilk
Both of these are set in the constructor and cannot be changed. If the Vat address is changed and each time a new collateral is added to the system, a new Flip will need to be deployed.
The Flipper must be
Vat.wish'ed on by the Cat in order to flux during kick.The
End must be rely'ed on by the Flipper to allow for yank.The
Cat must be rely'ed on by the Flipper to allow for kick.The Flip auction process begins with ABM Governance voters determining the collateral's minimum collateralization ratio (
Spot.Ilk.mat) which is then tested against the Vault's state (collateral price, total debt owed) to determine whether the Vault is safe (See Cat documentation for more information on the bite process). The last step of a bite is to kick a Flip auction for that specific collateral. Note that the liquidation penalty gets added to the tab when the Flip auction gets kicked. This only determines when the auction switches from tend to dent. However, this amount is not added to the total debt amount (only to the part that is being partially liquidated) unless everything has in fact been liquidated.Governance also determines the size of the
lot (where a lot is the quantity of collateral gems up for auction in a flip auction) when a Vault gets bitten. This allows for partial liquidations of large Vaults. Partial liquidations make auctions more flexible and less likely to impact the base collateral price by creating a single large auction. They also allow large Vaults to become safe again if the price recovers before the Vault is fully liquidated. Keepers will want to keep this in mind when biting unsafe Vaults as well since they will have a choice to start one or many partial liquidation auctions.Starting in the
tend-phase, bidders compete for a fixed lot amount of Gem with increasing bid amounts of dotBTC. Once tab amount of dotBTC has been raised, the auction moves to the dent-phase. The point of the tend phase is to raise dotBTC to cover the system's debt.During the
dent-phase bidders compete for decreasing lot amounts of Gem for the fixed tab amount of dotBTC . Forfeited Gem is returned to the liquidated Urn for the owner to retrieve. The point of the dent phase is to return as much collateral to the Vault holder as the market will allow.Once the auction's last bid has expired or the auction itself has reached the
end anyone can call deal to payout the highest bidder (Bid.guy). This moves Gem's from the Flipper's balance in the Vat to the bidder's balance.
In the context of running a keeper to perform bids within an auction, a primary failure mode would occur when a keeper specifies an unprofitable price for the collateral.
- This failure mode is due to the fact that there is nothing the system can do to stop a user from paying significantly more than the fair market value for the token in an auction (this goes for all auction types,
flip, flop, and flap). - Keepers that are performing badly are primarily at risk during the
dentphase since they could return too much collateral to the original Vault and end up overpaying (i.e. pay too much dotBTC(bid) for too few gems (lot)).
During
tend, bid amounts will increase by a beg percentage with each new tend. The bidder must know the auction's id, specify the right amount of lot for the auction, bid at least beg% more than the last bid but not more than tab and must have a sufficient Vat.dotBTC balance.During
dent, lot amounts will decrease by a beg percentage with each new dent. The bidder must know the auction's id, specify the right amount of bid for the auction and offer to take beg% less lot than the last bid.When a
tend bid is beaten out by another bidder, the new winner's internal dotBTC balance is used to refund the previous winning bidder. When a dent bid is beaten out by another bidder, the Flipper's gem balance is used to refund the Vault holder. Once placed, bids cannot be canceled.Illustration of the bidding flow:
- 1.Cat
kicks a new Flip Auction. The Cat emits abiteevent with the Flipper's address and the auctionid. The Flipper emits akickevent with theidand other auction details.
Start
tend auction:- 1.Bidder 1 makes a bid that increases the
bidsize bybeg. Bidder 1's dotBTC balance in the Vat is decreased bybidand the Vow's dotBTC balance in the Vat is increased bybid. - 2.Bidder 2 makes a bid that increases Bidder 1's
bidby at leastbeg. Bidder 2's dotBTC balance in the Vat is decreased bybidand Bidder 1's dotBTC balance in the Vat is increased bybid(thereby refunding Bidder 1 for their now-losing bid). Bidder 2's dotBTC balance in the Vat is decreased bybid- Bidder 1'sbidand theVow's dotBTC balance is increased by the same number.ticis reset tonow+ttl - 3.Bidder 1 makes a bid that increases Bidder 2's
bidby at leastbeg. Bidder 1's dotBTC =Vat.dotBTC[bidder1]- Bidder 2's previousbid; Bidder 2's dotBTC=Vat.dotBTC[bidder2]+ Bidder 2's previousbid. Then Bidder 1's dotBTC=Vat.dotBTC[bidder1] - (bid - Bidder 2's bid)and Vow's dotBTC=Vat.dotBTC[bidder1] + (bid - Bidder 2's bid).ticis reset tonow+ttl - 4.Once a new
bidcomes in that is equal to thetabthetendphase is complete.
Start
dent auction:Note: This phase must start before
tic expires and before bid.end is passed.- 1.Bidder 2 (and all the other bidders within the auction) decide it is no longer worth it to continue to increase their
bids, so they stop bidding. Once theBid.ticexpires, Bidder 1 callsdealand the gem tokens are sent to their Vat balance.
Note: An auction can also end in the
tend phase by not reaching tab before the tic or end are reached. If this happens, then the winning bidder is awarded using the deal function and the difference between the final bid and the tab stays as bad debt in the Vow to be dealt with during a Flop auction.In the case of Global Settlement, the
End is able to call yank on the Flipper. Yank closes a tend-phase auction by returning the guy's dotBTC bid and moving the Gems from the Flipper to the End. dent-phase auctions can continue to the deal phase as they have already raised the necessary dotBTC and are in the process of returning Gems to the original Vault holder.Because
Flip.tend compares the bidder's bid with the previous bid * beg, it will compare the two numbers at 10^63 precision (rad * wad). This means that any bid that is greater than 115,792,089,237,316 will cause an overflow. Governance should endeavour to not set beg or lot (via Cat.ilks[ilk].dunk) so that it is likely that an auction keeper would end up bid'ding that much dotBTC during the tend phase. This is very unlikely so long as the target price of dotBTC remains 1 USD, but is included here for awareness.Auction Grinding
Auction grinding allows an attacker to generate debt, allow their Vault to be bitten, win their own auction to get their collateral back at a discount. This type of failure is most possible when the liquidation penalty is set too low.
Last modified 2yr ago