Oracle Sequential Dutch Auctioneer (OSDA)
The Oracle Sequential Dutch Auctioneer implements a simplified sequential dutch auction pricing methodology which seeks to sell out the capacity of the market linearly over the duration. We do so by implementing a linear decay of price based on the percent difference in expected capacity vs. actual capacity (relative to the initial capacity) at any given point in time. The OSDA allows specifying a base discount from the oracle price and calculates a decay speed based on a target deposit interval and target discount over that interval. More specifically, we define the price as:
We calculate the capacity ratio as:
Market creators can also set a minimum total discount from the starting price, which creates a hard floor for the market price.
The below chart shows a notional example of how price might evolve over an OSDA market.
If you're familiar with other dutch auction mechanism designs, this version of the SDA is similar to Paradigm's Continuous Gradual Dutch Auction (GDA) model with linear decay, but there is no price slippage based on the purchase amount. Note the version described in the link above uses exponential decay vs. linear decay, but it's possible to derive a linear decay version as well.
Configuring appropriate base discount and target interval discounts is a function of the market demand for the token and the vesting period of the payouts. Typically, longer vesting periods require a larger base discount. Target interval discounts may need to be higher for smaller cap tokens or where demand is soft. However, various combinations can be used depending on desired market characteristics. For example, a high base discount and low target interval discount will give a consistently good deal with low volatility in the market price. The opposite configuration, low base discount and high target interval discount, will be more volatile, but may result in lower overall discounts depending on demand.
Data Structures (Structs)
MarketParams
Parameters to create a new OSDA market. Encoded as bytes and provided as input to createMarket
.
BondMarket
BondMarket contains the token, callback, capacity, owner, and purchased/sold amount data for a Oracle Fixed Discount Market.
BondTerms
BondTerms contains the oracle, pricing, and time parameters of an Oracle Fixed Discount Market.
Public Variables and View Methods
allowNewMarkets
Whether or not the auctioneer allows new markets to be created
Changing to false will sunset the auctioneer after all active markets end
authority
Roles authority contract for the bond system which managed access-control to permissioned functions.
callbackAuthorized
Whether or not the market creator is authorized to use a callback address
Parameters
currentCapacity
Returns current capacity of a market
Parameters
getAggregator
Returns the Aggregator that services the Auctioneer
getMarketInfoForPurchase
Provides information for the Teller to execute purchases on a Market
Parameters
Returns
getTeller
Returns the Teller that services the Auctioneer
isInstantSwap
Does market send payout immediately
Parameters
isLive
Is a given market accepting deposits
Parameters
marketPrice
Calculate current market price. Value returned is the number of quote tokens per payout token. The value is the oracle price scaled by the BondTerms.oracleConversion factor. marketPrice
and marketScale
can be used to convert between amounts of quote tokens and payout tokens at the current price.
Parameters
marketScale
Scale value to use when converting between quote token and payout token amounts with marketPrice()
Parameters
markets
Returns the token, callback, capacity, owner, and purchased/sold amount data for a market. See BondMarket.
Parameters
maxAmountAccepted
Returns maximum amount of quote token accepted by the market
Parameters
maxPayout
Calculate max payout of the market in payout tokens
Returns a dynamically calculated payout or the maximum set by the creator, whichever is less. If the remaining capacity is less than the max payout, then that amount will be returned.
Parameters
minDepositInterval
Minimum deposit interval for a market
minMarketDuration
Minimum market duration in seconds
newOwners
New address to designate as market owner. They must accept ownership to transfer permissions.
Parameters
ownerOf
Returns the address of the market owner
Parameters
payoutFor
Payout due for amount of quote tokens at current market price
Parameters
terms
Information pertaining to oracle, pricing, and time parameters. See BondTerms.
Parameters
State-Mutating Methods
closeMarket
Disable existing bond market. Must be market owner
Parameters
createMarket
Creates a new bond market
See MarketParams for the required formatting for the abi-encoded input params.
Parameters
Returns
pullOwnership
Accept ownership of a marketMust be market newOwner
The existing owner must call pushOwnership prior to the newOwner calling this function
Parameters
purchaseBond
Exchange quote tokens for a bond in a specified market. Must be teller. End users interact with the Teller contract to purchase.
Parameters
Returns
pushOwnership
Designate a new owner of a marketMust be market owner
Doesn't change permissions until newOwner calls pullOwnership
Parameters
setAllowNewMarkets
Change the status of the auctioneer to allow creation of new markets
Setting to false and allowing active markets to end will sunset the auctioneer
Parameters
setCallbackAuthStatus
Change whether a market creator is allowed to use a callback address in their markets or not. Must be guardian
Callback is believed to be safe, but a whitelist is implemented to prevent abuse
Parameters
setMinDepositInterval
Set the minimum deposit interval. Access controlled
Parameters
setMinMarketDuration
Set the minimum market duration. Access controlled
Parameters
Events
MarketClosed
Parameters
MarketCreated
Parameters
Errors
The following custom errors are used in the OSDA contract to denote specific revert conditions. The errors are prefixed with "Auctioneer" to denote that it is within this contract when multi-contract actions are performed (such as buying a bond).