Fixed Price Auctioneer (FPA)
Fixed Price Auctioneer is the simplest auction variant. It allows creators to buy/sell a set capacity of token at the quoted price for a certain amount of time. Because of this, it is similar to a limit order in an order book exchange. The goal of this auction variant is to sell as many tokens as possible at the set price. Unlike the SDA auction variants, it will not adjust price to sell out the capacity over the duration.
The Base FPA contract has the following data structures, variables, and methods.
Data Structures (Structs)
MarketParams
Parameters to create a new FPA market. Encoded as bytes and provided as input to createMarket
.
Field | Type | Description |
---|---|---|
payoutToken | ERC20 (address) | Payout Token (token paid out by market and provided by creator) |
quoteToken | ERC20 (address) | Quote Token (token to be received by the market and provided by purchaser) |
callbackAddr | address | Callback contract address, should conform to |
capacityInQuote | bool | Is Capacity in Quote Token? |
capacity | uint256 | Capacity (amount in quote token decimals or amount in payout token decimals). Set |
formattedPrice | uint256 | Initial price of the market as a ratio of quote tokens per payout token, see note below on formatting |
depositInterval | uint48 | Target deposit interval for purchases (in seconds). Determines the |
vesting | uint48 | Is fixed term ? Vesting length (seconds) : Vesting expiry (timestamp). A 'vesting' param longer than 50 years is considered a timestamp for fixed expiry |
start | uint48 | Start time of the market as a timestamp. Allows starting a market in the future. If provided, the transaction must be sent prior to the start time. If not provided, the market will start immediately. |
duration | uint48 | Duration of the market in seconds. |
scaleAdjustment | int8 | Market scaling adjustment factor, ranges from -24 to +24. See note below on how to calculate |
Calculating Formatted Price and Scale Adjustment
In order to support a broad range of tokens, with different decimal configurations and prices, we calculate an optimal scaling factor for each market. Specifically, the scale adjustment allows the FPA to support tokens with 6 to 18 configured decimals and with prices that differ by up to 24 decimal places (if the tokens have the configured decimals, less if not). To implement this, the market creator must provide a scale adjustment factor and format the price correctly.
First, you need the price of each token in a common unit, e.g. dollars or ether.
Then, if is the price of the payout token and is the price of quote token in the common unit, it can expressed in base 10 (or scientific) notation as:
where:
is the coefficient of the payout token price and is the number of price decimals for the payout token (aka the significand of the price).
is the coefficient of the quote token price and is the number of price decimals for the quote token.
Example: If the price of WETH is $1,500, then we would deconstruct it as . Therefore and .
Now, using the price values and the configured number of decimals for each token, we can calculate the scale adjustment.
where:
is the configured payout token decimals (e.g. WETH has 18 configured decimals)
is the configured quote token decimals.
and are as defined above.
Example:
Let WETH be the quote token and OHM be the payout token. WETH has 18 configured decimals and OHM has 9 configured decimals. Assume the market price of WETH is $1,500 -> and the market price of OHM is $10 -> .
Then, the scale adjustment is
Once we have the scale adjustment, we can format the price using the variables defined above. Here we assume the auction will use the current market price. If selling vesting tokens, a discount to the current market price may be appropriate.
Example: Continuing with the WETH and OHM example from above, we format the price as:
The above price example can be interpreted as 0.0666.. WETH per OHM.
BondMarket
BondMarket contains the core data, such as tokens, capacity, owner, price, etc., for a Fixed Price Market.
BondTerms
BondTerms contains the time parameters of a Fixed Price 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
callbackAuthorized
Whether or not the market creator is authorized to use a callback address
currentCapacity
Returns current capacity of a market
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of market |
getAggregator
Returns the Aggregator that services the Auctioneer
getMarketInfoForPurchase
Provides information for the Teller to execute purchases on a Market
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of market |
Returns
Name | Type | Description |
---|---|---|
owner | address | Address of the market owner (tokens transferred from this address if no callback) |
callbackAddr | address | Address of the callback contract to get tokens for payouts |
payoutToken | contract ERC20 | Payout Token (token paid out) for the Market |
quoteToken | contract ERC20 | Quote Token (token received) for the Market |
vesting | uint48 | Timestamp or duration for vesting, implementation-dependent |
maxPayout_ | uint256 | Maximum amount of payout tokens you can purchase in one transaction |
getTeller
Returns the Teller that services the Auctioneer
isInstantSwap
Returns whether the market sends payout immediately (true = no vesting) or not (false = vesting)
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of market |
isLive
Returns whether the market is currently accepting deposits (true) or not (false)
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of market |
marketPrice
Calculates current market price, value returned is the number of quote tokens per payout token, scaled according to the logic described in Calculating Formatted Price and Scale Adjustment
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of market |
marketScale
Scale value to use when converting between quote token and payout token amounts with marketPrice()
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of market |
markets
Returns the core information pertaining to a bond market, see BondMarket
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of market |
maxAmountAccepted
Returns maximum amount of quote token accepted by the market
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of market |
referrer_ | address | Address of referrer, used to get fees to calculate accurate payout amount. Inputting the zero address will take into account just the protocol fee. |
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
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of market |
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
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of market |
ownerOf
Returns the address of the market owner
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of market |
payoutFor
Payout due for amount of quote tokens
Parameters
Name | Type | Description |
---|---|---|
amount_ | uint256 | Amount of quote tokens to spend |
id_ | uint256 | ID of market |
referrer_ | address | Address of referrer, used to get fees to calculate accurate payout amount. Inputting the zero address will take into account just the protocol fee. |
terms
Information pertaining to market time parameters, see BondTerms
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of the market |
State-Mutating Methods
closeMarket
Disable existing bond marketMust be market owner
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of market to close |
createMarket
Creates a new bond market
See MarketParams for the required formatting for the abi-encoded input params.
Parameters
Name | Type | Description |
---|---|---|
params_ | bytes | Configuration data needed for market creation, encoded in a bytes array |
Returns
id | uint256 | ID of the new bond market |
pullOwnership
Accept ownership of a marketMust be market newOwner
The existing owner must call pushOwnership prior to the newOwner calling this function
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | Market ID |
purchaseBond
Execute a purchase on the auctioneer. Only callable by the configured Teller. Users must interact with the Teller to make purchases.
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | ID of the Market the bond is being purchased from |
amount_ | uint256 | Amount to deposit in exchange for bond (after fee has been deducted) |
minAmountOut_ | uint256 | Minimum acceptable amount of bond to receive. Prevents front-running |
Returns
Name | Type | Description |
---|---|---|
payout | uint256 | Amount of payout token to be received from the bond |
pushOwnership
Designate a new owner of a marketMust be market owner
Doesn't change permissions until newOwner calls pullOwnership
Parameters
Name | Type | Description |
---|---|---|
id_ | uint256 | Market ID |
newOwner_ | address | New address to give ownership to |
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
Name | Type | Description |
---|---|---|
status_ | bool | Allow market creation (true) : Disallow market creation (false) |
setCallbackAuthStatus
Change whether a market creator is allowed to use a callback address in their markets or notMust be guardian
Callback is believed to be safe, but a whitelist is implemented to prevent abuse
Parameters
Name | Type | Description |
---|---|---|
creator_ | address | Address of market creator |
status_ | bool | Allow callback (true) : Disallow callback (false) |
setMinDepositInterval
Set the minimum deposit intervalAccess controlled
Parameters
Name | Type | Description |
---|---|---|
depositInterval_ | uint48 | Minimum deposit interval in seconds |
setMinMarketDuration
Set the minimum market durationAccess controlled
Parameters
Name | Type | Description |
---|---|---|
duration_ | uint48 | Minimum market duration in seconds |
Events
MarketClosed
Parameters
Name | Type | Description |
---|---|---|
id | uint256 | ID of the market |
MarketCreated
Parameters
Name | Type | Description |
---|---|---|
id | uint256 | ID of the market |
payoutToken | address | Address of the payout token |
quoteToken | address | Address of the quote token |
vesting | uint48 | Vesting duration or timestamp |
fixedPrice | uint256 | Fixed price of the market |
Errors
Auctioneer_AmountLessThanMinimum
Auctioneer_BadExpiry
Auctioneer_InvalidCallback
Auctioneer_InvalidParams
Auctioneer_MarketNotActive
Auctioneer_MaxPayoutExceeded
Auctioneer_NewMarketsNotAllowed
Auctioneer_NotAuthorized
Auctioneer_NotEnoughCapacity
Auctioneer_OnlyMarketOwner
Last updated