Surplus Auction House

1. Summary
The surplus auction is used to sell off a fixed amount of the surplus in exchange for protocol tokens. The surplus comes from the stability fees charged to SAFEs (and stored in the AccountingEngine). Bidders submit increasing amounts of protocol tokens and the winner receives all auctioned surplus in exchange for their coins which are burned or transferred to another address.
2. Contract Variables & Functions
Variables
contractEnabled - settlement flag (available only in the pre-settlement surplus auction house)
AUCTION_HOUSE_TYPE - flag set to bytes32("SURPLUS")
authorizedAccounts[usr: address] - addresses allowed to call modifyParameters() and disableContract().
bids[id: uint] - storage of all Bids by id
safeEngine - storage of the SAFEEngine's address
protocolToken - address of the protocol token
auctionsStarted - total auction count
bidDuration - bid lifetime / max bid duration (default: 3 hours)
bidIncrease - minimum bid increase (default: 5%)
totalAuctionLength - maximum auction duration (default: 2 days)
protocolTokenBidReceiver - receiver of protocol tokens after an auction is settled. Only present in the RecyclingSurplusAuctionHouse.
Data Structures
Bid - state of a specific auction
bidAmount - quantity being offered for the amountToSell
amountToSell- amount of surplus sold
highBidder
bidExpiry
auctionDeadline - when the auction will finish
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 addr) - update an address parameter. Only present in the RecyclingSurplusAuctionHouse.
startAuction(amountToSell: uint256, initialBid: uint256) - start a new surplus auction.
restartAuction(id: uint256) - restart an auction if there have been 0 bids and the auctionDeadline has passed.
increaseBidSize(id: uint256, amountToBuy: uint256, bid: uint256) - submit a bid with an increasing amount of protocol tokens for a fixed amount of system coins.
disableContract() - disable the contract.
settleAuction(id: uint256) - claim a winning bid / settles a completed auction.
terminateAuctionPrematurely(id: uint256) - is used in case Governance wishes to upgrade (only) the PreSettlementSurplusAuctionHouse or in case GlobalSettlement is triggered. It settles increaseBidSize phase auctions, sending back the protocol tokens submitted by the highBidder. 
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
ModifyParameters - emitted after a parameter is modified
RestartAuction - emitted after an auction is restarted. Contains:
id - the ID of the auction being restarted
auctionDeadline - the new auction deadline
IncreaseBidSize - emitted when someone bids a higher amount of protocol tokens for the same amount of system coins. Contains:
id - the ID of the auction that's being bid on
highBidder - the new high bidder
amountToBuy - the amount of system coins to buy
bid - the amount of protocol tokens bid
bidExpiry - the new deadline when the auction will end which can be before the original auctionDeadline
StartAuction- emitted when startAuction(uint256, uint256) is successfully executed. Contains:
id - auction id
auctionsStarted - total amount of auctions that have started up until now
amountToSell - amount of system coins sold  in the auction.
initialBid - starting bid for the auction
auctionDeadline - the auction's deadline
SettleAuction - emitted after an auction is settled. Contains:
id - the ID of the auction that was settled
DisableContract - emitted after the contract is disabled
TerminateAuctionPrematurely - emitted after an auction is terminated before its deadline. Contains:
id - the ID of the auction that was terminated
sender - the address that terminated the auction
highBidder - the auction's high bidder
bidAmount - the latest bid amount
3. Walkthrough
In a surplus auction, bidders compete for a fixed amountToSell of system coins with increasing bidAmounts of protocol tokens.
The surplus auction ends when the last bid's duration is passed (bidDuration) without another bid getting placed or when the auction duration (totalAuctionLength) has been surpassed. When the auction settles, the protocol tokens received are burnt in the case of a BurningSurplusAuctionHouse or transferred to a separate address in the case of RecyclingSurplusAuctionHouse.
In case governance disables the surplus auction house by calling disableContract, anyone can call terminateAuctionPrematurely in order to quickly settle an auction and return the protocol token bid to the highBidder. 

Debt Auction House

Next - System Contracts

Oracle Module

Last modified 9mo ago

Copy link

Contents

1. Summary

2. Contract Variables & Functions

3. Walkthrough