English Collateral Auction House

1. Summary
English collateral auctions are used to sell collateral from SAFEs that have become undercollateralized in order to preserve the overall system health. The LiquidationEngine sends collateral to the EnglishCollateralAuctionHouse where it is auctioned in two phases: increaseBidSize and decreaseSoldAmount.
2. Contract Variables & Functions
Variables
contractEnabled - settlement flag (1 or 0).
AUCTION_HOUSE_TYPE - flag set to bytes32("COLLATERAL")
AUCTION_TYPE - flag set to bytes32("ENGLISH").
authorizedAccounts[usr: address] - addresses allowed to call modifyParameters() and disableContract().
safeEngine - storage of the SAFEEngine's address.
bids[id: uint] - storage of all bids.
collateralType - id of the collateral type for which the CollateralAuctionHouse is responsible.
bidIncrease - minimum bid increase (default: 5%).
bidDuration - bid duration (default: 3 hours).
totalAuctionLength - auction length (default: 2 days).
auctionsStarted - total auction count, used to track auction ids.
bidToMarketPriceRatio - the minimum size of the first bid compared to the latest recorded collateral price (for collateralType) in the system.
oracleRelayer - address of the OracleRelayer.
osm - collateral type OSM address
liquidationEngine - the address of the LiquidationEngine
Data Structures
Bid - state of a specific auction
bidAmount - paid system coins
amountToSell - quantity up for auction / collateral for sale
highBidder
bidExpiry - when a bid expires (and the auction ends)
auctionDeadline - max auction duration
forgoneCollateralReceiver - address of the SAFE being auctioned. Receives collateral during the decreaseSoldAmount phase
auctionIncomeRecipient - recipient of auction income / receives system coin income (this is the AccountingEngine contract)
amountToRaise - total system coins wanted from the auction
Modifiers
isAuthorized - checks whether an address is part of authorizedAddresses (and thus can call authed functions).
Functions
modifyParameters(bytes32 parameter, uint256 data) - update a uint256 parameter.
modifyParameters(bytes32 parameter, address data) - update an address parameter.
addAuthorization(usr: address) - add an address to authorizedAddresses.
removeAuthorization(usr: address) - remove an address from authorizedAddresses.
startAuction(forgoneCollateralReceiver: address, auctionIncomeRecipient: address, amountToRaise: uint256, amountToSell: uint256, initialBid: uint256 ) - function used by LiquidationEngine to start an auction / put collateral up for auction
restartAuction(id: uint256) - restart an auction if there have been 0 bids and the auctionDeadline has passed
increaseBidSize(id: uint256, amountToBuy: uint256, rad: uint256) - first phase of an auction. Increasing system coin bids for a set amountToSell of collateral
decreaseSoldAmount(id: uint256, amountToBuy: uint256, rad: uint256) - second phase of an auction. Set system coin bid for a decreasingamountToSellof collateral.
settleAuction(id: uint256) - claim a winning bid / settles a completed auction
terminateAuctionPrematurely(id: uint256) - used during GlobalSettlement to terminate increaseBidSize phase auctions and transfer the collateral to the settlement contract while repaying system coins (the winning bid) to the highest bidder.
bidAmount(id: uint256) public view returns (uint256) - return the latest bidAmount from a specific auction
remainingAmountToSell(id: uint256) public view returns (uint256) - return the remaining collateral amount to sell from a specific auction
forgoneCollateralReceiver(uint id) public view returns (address) - return theforgoneCollateralReceiver for a specific auction
raisedAmount(id: uint256) - always returns zero
amountToRaise(uint id) public view returns (uint256) - return the amount of system coins to raise for a specific auction
Events
AddAuthorization - emitted when a new address becomes authorized. Contains:
account - the new authorized account
RemoveAuthorization - emitted when an address is de-authorized. Contains:
account - the address that was de-authorized
StartAuction- emitted when startAuction(address, address, uint256, uint256, uint256) is successfully executed. Contains:
id - auction id
auctionsStarted - total amount of auctions started up until now
amountToSell - amount of collateral sold in the auction
initialBid - starting bid for the auction (usually zero).
amountToRaise - amount of system coins that should be raised by the auction.
forgoneCollateralReceiver - receiver of leftover collateral (usually the SAFE whose collateral was confiscated by the LiquidationEngine).
auctionIncomeRecipient - receiver of system coins (usually the AccountingEngine)
auctionDeadline - the auction's deadline
ModifyParameters - emitted when a parameter is updated
RestartAuction - emitted when an auction restarts due to a lack of bids. Contains:
id - the ID of the auction to restart
auctionDeadline - the new deadline for the auction with the ID id
IncreaseBidSize - emitted when a bidder offers more system coins for the same amount of collateral. Contains:
id - the id of the auction being bid on
highBidder - the new high bidder (new auction winner which is set to msg.sender)
amountToBuy - total amount of collateral being bought from the auction
rad - the new system coin bid
bidExpiry - the timestamp after which the new bid will be considered final and highBidder can receive the collateral (even if bidExpiry < auctionDeadline)
DecreaseSoldAmount - emitted when someone accepts a smaller amount of collateral for the same amount of rad system coins bid in the increaseBidSize phase. Contains:
id - the id of the auction being bid on
highBidder - the new high bidder (new auction winner which is set to msg.sender)
amountToBuy - new (and lower) amount of collateral being bought from the auction
rad - same system coin bid as the winning bid from the 
bidExpiry - the timestamp after which the new bid will be considered final and highBidder can receive the collateral (even if bidExpiry < auctionDeadline)
SettleAuction - emitted after an auction is settled. Contains:
id - the ID of the auction that has just been settled
TerminateAuctionPrematurely - emitted after an auction is terminated prematurely by an authed address. Contains:
id - the ID of the auction being terminated
sender - msg.sender
bidAmount - the amount of system coins that should have been raised by the auction
collateralAmount - the total amount of collateral that should have been sold by the auction
3. Walkthrough
Starting in the increaseBidSize-phase, bidders compete for an amountToSell of collateral with increasing bid amounts of system coins. The very first bidAmount will need to be higher than or equal to latest collateral price in collateral OSM * bidToMarketPriceRatio / RAY. This ensures that no bidder can submit an extremely small bidAmount and thus pay a negligible price for the entire amountToSell collateral. 
Once amountToRaise amount of system coins has been raised, the auction moves to the decreaseSoldAmount-phase. This phase is meant to incentivize bidders to returns as much collateral as possible back to the SAFE while still paying amountToRaise system coins.
Once the auction's last bid has expired or the auction itself has reached the auctionDeadline anyone can call settleAuction to payout the highest bidder (Bid.highBidder). This moves collateral from the CollateralAuctionHouse's balance in the SAFEEngine to the winning bidder's balance.
When the auction is settled (or terminated prematurely), the contract will call the LiquidationEngine in order to removeCoinsFromAuction (subtract bids[auctionId].amountToRaise from LiquidationEngine.currentOnAuctionSystemCoins).

System Contracts - Previous

Auction Module

Fixed Discount Collateral Auction House

Last modified 1yr ago

Copy link

Contents

1. Summary

2. Contract Variables & Functions

3. Walkthrough