English
counterpart in that they are used to preserve the overall system health by liquidating under-collateralized SAFEs and selling off collateral in exchange for system coins. This auction type automatically calculates an amount of collateral to send back to a bidder, taking into account the amount of system coins the bidder submits as well as the current system coin redemptionPrice
(and optionally its market price) and collateral market price.contractEnabled
- settlement flag (1
or 0
).AUCTION_HOUSE_TYPE
- flag set to bytes32("COLLATERAL")
AUCTION_TYPE
- flag set to bytes32("FIXED_DISCOUNT")
.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.minimumBid
- minimum amount of system coins that must be submitted by each bidder.totalAuctionLength
- auction length (default: uint48(-1)
).auctionsStarted
- total auction count, used to track auction id
s.lastReadRedemptionPrice
- the last read redemption price. Can (and most probably is) be different than the latest OracleRelayer._redemptionPrice
discount
- discount compared to the collateral market price; used when calculating the amount of collateral to send to a bidder.lowerCollateralMedianDeviation
- max collateralMedian
collateral price deviation (compared to the FSM
price) used when the median price is lower than the collateralFSM
price and the contract needs to pick which one to useupperCollateralMedianDeviation
- max collateralMedian
collateral price deviation (compared to the FSM
price) used when the median price is higher than the collateralFSM
price and the contract needs to pick which one to uselowerSystemCoinMedianDeviation
- max systemCoinOracle
price deviation (compared to the redemptionPrice
) used when the system coin's redemptionPrice
price is higher than its market price and the contract needs to pick which one to useupperSystemCoinMedianDeviation
- max systemCoinOracle
price deviation (compared to the redemptionPrice
) used when the system coin's redemptionPrice
price is lower than its market price and the contract needs to pick which one to useminSystemCoinMedianDeviation
- minimum deviation between the system coin's market and redemption prices that must be passed in order for the contract to use the deviated price instead of the redemption oneoracleRelayer
- address of the OracleRelayer
collateralFSM
- the collateral type's FSM
addresscollateralMedian
- collateral type medianizer addresssystemCoinOracle
- market price oracle for the system coinliquidationEngine
- the address of the LiquidationEngine
RAD
- number with 45 decimals (e.g a safeEngine.coinBalance
)WAD
- number with 18 decimals (e.g a bid submitted when someone wants to buy collateral from an auction)RAY
- number with 27 decimalsBid
- state of a specific auctionraisedAmount
- amount of system coins raised up until this pointsoldAmount
- amount of collateral sold up until this pointamountToSell
- quantity up for auction / collateral for saleamountToRaise
- total system coins wanted from the auctionauctionDeadline
- max auction durationforgoneCollateralReceiver
- address of the SAFE being auctionedauctionIncomeRecipient
- recipient of auction income / receives system coin income (this is the AccountingEngine
contract)isAuthorized
- checks whether an address is part of authorizedAddresses
(and thus can call authed functions).modifyParameters(bytes32 parameter
, uint256 data)
- update an 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
.getCollateralMedianPrice() public view returns (priceFeed: uint256)
- get the collateral's median price from collateralMedian
getSystemCoinMarketPrice() public view returns (priceFeed: uint256)
- get the system coin's market price from systemCoinOracle
getFinalTokenPrices(systemCoinRedemptionPrice: uint256) public view returns (uint256
, uint256)
- get the collateral and system coin prices that can be currently used to determine the amount of collateral bought by biddersgetFinalBaseCollateralPrice(collateralFsmPriceFeedValue: uint256
, collateralMedianPriceFeedValue: uint256) public view returns (uint256)
- get the final collateral price (without the discount applied) that will be used to determine the amount of collateral bought by a bidgetDiscountedCollateralPrice(collateralFsmPriceFeedValue: bytes32
, collateralMedianPriceFeedValue: bytes32
, systemCoinPriceFeedValue: uint256
, customDiscount: uint256) public view returns (uint256)
- get the (discounted) collateral price using either the FSM
or median price for the collateral and the redemption/market price for the system coinstartAuction(forgoneCollateralReceiver: address
, auctionIncomeRecipient: address
, amountToRaise: uint256
, amountToSell: uint256
, initialBid: uint256 )
- function used by LiquidationEngine
to start an auction / put collateral up for auctiongetApproximateCollateralBought(id: uint256
, wad: uint256)
- get the amount of collateral that can be bought from a specific auction by bidding wad
and assuming that the latest system coin redemptionPrice
is equal to lastReadRedemptionPrice
getCollateralBought(id: uint256
, wad: uint256) returns (uint256
, uint256)
- get the amount of collateral that can be bought from a specific auction by bidding wad
amount of system coins (where wad
will be scaled by RAY
to transfer the correct amount of RAD
system coins from safeEngine.coinBalance
)buyCollateral(id: uint256
, wad: uint256)
- buy collateral from an auction and offer wad
amount of system coins in return (where wad
is scaled by RAY
in order to transfer RAD
amount of coins from the bidder's safeEngine.coinBalance
)settleAuction(id: uint256)
- settle an auction that has passed its auctionDeadline
and return any unsold collateral to the forgoneCollateralReceiver
terminateAuctionPrematurely(id: uint256)
- normally used during GlobalSettlement
to terminate an auction early and send unsold collateral to the msg.sender
as well as call LiquidationEngine
in order to subtract bids[auctionId].amountToRaise
from LiquidationEngine.currentOnAuctionSystemCoins
bidAmount(id: uint256) public view returns (uint256)
- always returns zeroremainingAmountToSell(id: uint256) public view returns (uint256)
- return the remaining collateral amount to sell from a specific auctionforgoneCollateralReceiver(uint id) public view returns (address)
- returns theforgoneCollateralReceiver
for a specific auctionraisedAmount(id: uint256)
- returns the currently raised amount of system coins for a specific auction.amountToRaise(uint id) public view returns (uint256)
- returns the amount of system coins to raise for a specific auctionAddAuthorization
- emitted when a new address becomes authorized. Contains:account
- the new authorized accountRemoveAuthorization
- emitted when an address is de-authorized. Contains:account
- the address that was de-authorizedStartAuction
- emitted when startAuction(address
, address
, uint256
, uint256
, uint256)
is successfully executed. Contains:id
- auction idauctionsStarted
- amount of auctions started up until nowamountToSell
- amount of collateral sold in the auctioninitialBid
- 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 deadlineModifyParameters
- emitted when a parameter is modifiedBuyCollateral
- emitted when someone buys collateral from an auction. Contains:id
- the ID of the auction from which collateral was boughtwad
- the bid sizeboughtCollateral
- the amount of collateral that was boughtSettleAuction
- emitted when someone settles an auction. Contains:id
- the ID of the auction settledleftoverCollateral
- the amount of collateral that hasn't been sold by the now settled auctionTerminateAuctionPrematurely
- emitted when an auction is terminated before its deadline. Contains:id
- the ID of the auction that was terminatedsender
- the address that terminated the auctioncollateralAmount
- the amount of collateral still unauctionedEnglish
auctions) to put SAFE collateral up for sale in exchange for system coins used to settle bad debt. Bidders are only required to allow the auction house to transfer their safeEngine.coinBalance
and can then callbuyCollateral(id: uint256
, wad: uint256)
in order to exchange their system coins for collateral which is sold at a discount
compared to its latest recorded market price. Bidders can also review the amount of collateral they can get from a specific auction by calling getCollateralBought(id: uint256
, wad: uint256)
or getApproximateCollateralBought(id: uint256
, wad: uint256)
. Note that getCollateralBought
is not marked as view
because it reads (and also updates) the redemptionPrice
from the OracleRelayer
whereas getApproximateCollateralBought
uses thelastReadRedemptionPrice
.English
auctions where bidders submit bids with RAD
amounts of system coins (using increaseBidSize
and decreaseSoldAmount
), buyCollateral
requires a WAD
amount of coins that are then multiplied by RAY
in order to correctly scale the amount to RAD
and transfer coins from the bidder's safeEngine.coinBalance.
wad
used when calling buyCollateral
. wad
must be bigger than zero and bigger than or equal to minimumBid
. In case wad
is bigger than minimumBid
, the contract will only request what it needs in order to fill remainingToRaise
. Note that in order to avoid dusty auctions resulting from computing an adjustedBid
(because of precision loss from division) the contract will automatically request 10**-18
extra system coinsFSM
price (the delayed price) and the latest market price stored in the medianizer (which the FSM
is connected to). The auction house uses the FSM
price by default so that, in case of an oracle attack, governance can react and temporarily disable the FSM
(in case they have power over that system component).FSM
's delay, the market price (and thus the medianizer value) might change significantly and thus bidders might have to wait until a new median price feed is pushed into the FSM
so that they can profit from auctions. In order to avoid scenarios where bidders have to wait for an FSM
update and at the same time protect collateral auctions from an oracle attack, we added two variables: lowerCollateralMedianDeviation
and upperCollateralMedianDeviation
which allow the auction house to pick the medianizer price (when calculating the amount of collateral bought by a bidder) in case it deviated within certain bounds compared to the FSM
price.redemptionPrice
and its market price (provided only if systemCoinOracle
is not null and it returns a valid price). The auction house uses the redemptionPrice
by default, although, during market shocks, there may be a significant difference between the system coin's redemption and market prices which will discourage bidding (if the market price is above redemption). This is why governance can set lowerSystemCoinMedianDeviation
and upperSystemCoinMedianDeviation
in order to allow the contract to use the system coin market price if it deviated within certain bounds from the redemptionPrice
. Governance can also set minSystemCoinMedianDeviation
so that the contract only chooses the market price in case it deviated above a certain threshold.English
auctions, 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
).10**-18
extra system coins (meant to prevent dusty auctions)minimum(minimumBid
, subtract(bids[id].amountToRaise
, bids[id].raisedAmount))
. The contract will take care of charging only for the amount needed to cover the total remainingamountToRaise
redemptionPrice
by default (not its market price)