GEB Docs
Surplus Auction House
Surplus auctioneer that sells extra stability fees in exchange for protocol tokens

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

    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
      auctionDeadline - when the auction will finish
    isAuthorized - checks whether an address is part of authorizedAddresses (and thus can call authed 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.
    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.
Last modified 9mo ago