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.

struct MarketParams {
    ERC20 payoutToken;
    ERC20 quoteToken;
    address callbackAddr;
    bool capacityInQuote;
    uint256 capacity;
    uint256 formattedPrice;
    uint48 depositInterval;
    uint48 vesting;
    uint48 start;
    uint48 duration;
    int8 scaleAdjustment;
}
FieldTypeDescription

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 IBondCallback. If 0x00, tokens will be transferred from market owner. Using a callback requires whitelisting by the protocol

capacityInQuote

bool

Is Capacity in Quote Token?

capacity

uint256

Capacity (amount in quote token decimals or amount in payout token decimals). Set capacityInQuote flag appropriately

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 maxPayout of the market. Minimum is 1 hour (3600 seconds)

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 Φp\Phi_p is the price of the payout token and Φq\Phi_q is the price of quote token in the common unit, it can expressed in base 10 (or scientific) notation as:

Φp=ϕp×10dϕp\Phi_p = \phi_p \times 10^{d_{\phi p}}
Φq=ϕq×10dϕq\Phi_q = \phi_q \times 10^{d_{\phi q}}

where:

  • ϕp\phi_p is the coefficient of the payout token price and ​dϕpd_{\phi p}​ is the number of price decimals for the payout token (aka the significand of the price).

  • ϕq\phi_q​ is the coefficient of the quote token price and dϕqd_{\phi q}​ 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 1.5×1031.5 \times 10^3​. Therefore ϕ=1.5\phi = 1.5 and dϕ=3d_{\phi} = 3.

Now, using the price values and the configured number of decimals for each token, we can calculate the scale adjustment.

s=dpdqdϕpdϕq2s = d_p - d_q - \left\lfloor\frac{d_{\phi p} - d_{\phi q}}{2}\right\rfloor

where:

  • dpd_p is the configured payout token decimals (e.g. WETH has 18 configured decimals)

  • dqd_q is the configured quote token decimals.

  • dϕpd_{\phi p} and dϕqd_{\phi q} 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 -> 1.5×1031.5 \times 10^3and the market price of OHM is $10 -> 1×1011 \times 10^1.​

  • Then, the scale adjustment is s=918132=9+1=8s = 9 - 18 - \left\lfloor\frac{1-3}{2}\right\rfloor = -9 + 1 = -8

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.

Φ0=ϕpϕq×1036+s+dqdp+dϕpdϕq\Phi_0 = \frac{\phi_p}{\phi_q} \times 10^{36 + s + d_q - d_p +d_{\phi p} - d_{\phi q}}

Example: Continuing with the WETH and OHM example from above, we format the price as:

Φ0=11.5×1036+(8)+189+13=0.666..×1035=0.0666..×1036\Phi_0 = \frac{1}{1.5} \times 10^{36+(-8)+18-9+1-3} = 0.666.. \times 10^{35} = 0.0666.. \times 10^{36}

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.

struct BondMarket {
    address owner; // market owner. sends payout tokens, receives quote tokens (defaults to creator)
    ERC20 payoutToken; // token to pay depositors with
    ERC20 quoteToken; // token to accept as payment
    address callbackAddr; // address to call for any operations on bond purchase. Must inherit to IBondCallback.
    bool capacityInQuote; // capacity limit is in payment token (true) or in payout (false, default)
    uint256 capacity; // capacity remaining
    uint256 maxPayout; // max payout tokens out in one order
    uint256 price; // fixed price of the market (see MarketParams struct)
    uint256 scale; // scaling factor for the market (see MarketParams struct)
    uint256 sold; // payout tokens out
    uint256 purchased; // quote tokens in
}

BondTerms

BondTerms contains the time parameters of a Fixed Price Market.

struct BondTerms {
    uint48 start; // timestamp when market starts
    uint48 conclusion; // timestamp when market no longer offered
    uint48 vesting; // length of time from deposit to expiry if fixed-term, vesting timestamp if fixed-expiry
}

Public Variables and View Methods

allowNewMarkets

function allowNewMarkets() external view returns (bool)

Whether or not the auctioneer allows new markets to be created

Changing to false will sunset the auctioneer after all active markets end

authority

function authority() external view returns (contract Authority)

callbackAuthorized

function callbackAuthorized(address) external view returns (bool)

Whether or not the market creator is authorized to use a callback address

currentCapacity

function currentCapacity(uint256 id_) external view returns (uint256)

Returns current capacity of a market

Parameters

NameTypeDescription

id_

uint256

ID of market

getAggregator

function getAggregator() external view returns (contract IBondAggregator)

Returns the Aggregator that services the Auctioneer

getMarketInfoForPurchase

function getMarketInfoForPurchase(uint256 id_) external view returns (address owner, address callbackAddr, contract ERC20 payoutToken, contract ERC20 quoteToken, uint48 vesting, uint256 maxPayout_)

Provides information for the Teller to execute purchases on a Market

Parameters

NameTypeDescription

id_

uint256

ID of market

Returns

NameTypeDescription

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

function getTeller() external view returns (contract IBondTeller)

Returns the Teller that services the Auctioneer

isInstantSwap

function isInstantSwap(uint256 id_) external view returns (bool)

Returns whether the market sends payout immediately (true = no vesting) or not (false = vesting)

Parameters

NameTypeDescription

id_

uint256

ID of market

isLive

function isLive(uint256 id_) external view returns (bool)

Returns whether the market is currently accepting deposits (true) or not (false)

Parameters

NameTypeDescription

id_

uint256

ID of market

marketPrice

function marketPrice(uint256 id_) external view returns (uint256)

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

NameTypeDescription

id_

uint256

ID of market

marketScale

function marketScale(uint256 id_) external view returns (uint256)

Scale value to use when converting between quote token and payout token amounts with marketPrice()

Parameters

NameTypeDescription

id_

uint256

ID of market

markets

function markets(uint256) external view returns (address owner, contract ERC20 payoutToken, contract ERC20 quoteToken, address callbackAddr, bool capacityInQuote, uint256 capacity, uint256 maxPayout, uint256 price, uint256 scale, uint256 sold, uint256 purchased)

Returns the core information pertaining to a bond market, see BondMarket

Parameters

NameTypeDescription

id_

uint256

ID of market

maxAmountAccepted

function maxAmountAccepted(uint256 id_, address referrer_) external view returns (uint256)

Returns maximum amount of quote token accepted by the market

Parameters

NameTypeDescription

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

function maxPayout(uint256 id_) external view returns (uint256)

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

NameTypeDescription

id_

uint256

ID of market

minDepositInterval

function minDepositInterval() external view returns (uint48)

Minimum deposit interval for a market

minMarketDuration

function minMarketDuration() external view returns (uint48)

Minimum market duration in seconds

newOwners

function newOwners(uint256) external view returns (address)

New address to designate as market owner. They must accept ownership to transfer permissions.

Parameters

NameTypeDescription

id_

uint256

ID of market

ownerOf

function ownerOf(uint256 id_) external view returns (address)

Returns the address of the market owner

Parameters

NameTypeDescription

id_

uint256

ID of market

payoutFor

function payoutFor(uint256 amount_, uint256 id_, address referrer_) external view returns (uint256)

Payout due for amount of quote tokens

Parameters

NameTypeDescription

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

function terms(uint256) external view returns (uint48 start, uint48 conclusion, uint48 vesting)

Information pertaining to market time parameters, see BondTerms

Parameters

NameTypeDescription

id_

uint256

ID of the market

State-Mutating Methods

closeMarket

function closeMarket(uint256 id_) external nonpayable

Disable existing bond marketMust be market owner

Parameters

NameTypeDescription

id_

uint256

ID of market to close

createMarket

function createMarket(bytes params_) external nonpayable returns (uint256)

Creates a new bond market

See MarketParams for the required formatting for the abi-encoded input params.

Parameters

NameTypeDescription

params_

bytes

Configuration data needed for market creation, encoded in a bytes array

Returns

id

uint256

ID of the new bond market

pullOwnership

function pullOwnership(uint256 id_) external nonpayable

Accept ownership of a marketMust be market newOwner

The existing owner must call pushOwnership prior to the newOwner calling this function

Parameters

NameTypeDescription

id_

uint256

Market ID

purchaseBond

function purchaseBond(uint256 id_, uint256 amount_, uint256 minAmountOut_) external nonpayable returns (uint256 payout)

Execute a purchase on the auctioneer. Only callable by the configured Teller. Users must interact with the Teller to make purchases.

Parameters

NameTypeDescription

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

NameTypeDescription

payout

uint256

Amount of payout token to be received from the bond

pushOwnership

function pushOwnership(uint256 id_, address newOwner_) external nonpayable

Designate a new owner of a marketMust be market owner

Doesn't change permissions until newOwner calls pullOwnership

Parameters

NameTypeDescription

id_

uint256

Market ID

newOwner_

address

New address to give ownership to

setAllowNewMarkets

function setAllowNewMarkets(bool status_) external nonpayable

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

NameTypeDescription

status_

bool

Allow market creation (true) : Disallow market creation (false)

setCallbackAuthStatus

function setCallbackAuthStatus(address creator_, bool status_) external nonpayable

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

NameTypeDescription

creator_

address

Address of market creator

status_

bool

Allow callback (true) : Disallow callback (false)

setMinDepositInterval

function setMinDepositInterval(uint48 depositInterval_) external nonpayable

Set the minimum deposit intervalAccess controlled

Parameters

NameTypeDescription

depositInterval_

uint48

Minimum deposit interval in seconds

setMinMarketDuration

function setMinMarketDuration(uint48 duration_) external nonpayable

Set the minimum market durationAccess controlled

Parameters

NameTypeDescription

duration_

uint48

Minimum market duration in seconds

Events

MarketClosed

event MarketClosed(uint256 indexed id)

Parameters

NameTypeDescription

id indexed

uint256

ID of the market

MarketCreated

event MarketCreated(uint256 indexed id, address indexed payoutToken, address indexed quoteToken, uint48 vesting, uint256 fixedPrice)

Parameters

NameTypeDescription

id indexed

uint256

ID of the market

payoutToken indexed

address

Address of the payout token

quoteToken indexed

address

Address of the quote token

vesting

uint48

Vesting duration or timestamp

fixedPrice

uint256

Fixed price of the market

Errors

Auctioneer_AmountLessThanMinimum

error Auctioneer_AmountLessThanMinimum()

Auctioneer_BadExpiry

error Auctioneer_BadExpiry()

Auctioneer_InvalidCallback

error Auctioneer_InvalidCallback()

Auctioneer_InvalidParams

error Auctioneer_InvalidParams()

Auctioneer_MarketNotActive

error Auctioneer_MarketNotActive()

Auctioneer_MaxPayoutExceeded

error Auctioneer_MaxPayoutExceeded()

Auctioneer_NewMarketsNotAllowed

error Auctioneer_NewMarketsNotAllowed()

Auctioneer_NotAuthorized

error Auctioneer_NotAuthorized()

Auctioneer_NotEnoughCapacity

error Auctioneer_NotEnoughCapacity()

Auctioneer_OnlyMarketOwner

error Auctioneer_OnlyMarketOwner()

Last updated