Auction Contract

1. Introduction

The Auction contract is the contract responsible for distributing the BLU governance token across a long period. It allows a gradual injection of the governance token in circulation while dynamically adjusting its price to market prices.
​Contract Source​

2. Module Details

Key Parameters

startBlock - Defines the block number where users are first able to purchase BLU from the contract.
blocksPerPeriod - Defines how long is a single period. Using the value of 43200 to represent one day on Polygon chain with ~2 seconds block time.
tokenPerPeriod - Defines how many tokens are up for sale during each period. Using the value of 600E18 to sell 600 tokens a day.
targetTokenPeriod - Defines what's the target number of tokens to be sold. It's initiated to exactly half of tokenPerPeriod. If the target number is sold for the period, the price remains the same for the next period. If the actual token sold is higher or lower than the target, the price is adjusted to be higher or lower respectively for the next period.
sensitivity - Defines the maximum level of change to price between two periods. It's initialized to 2E27 to allow the price to double or half between two periods depending if the token sold for the given period is above or under the target.

Stored Variables

lastPrice - Stores the price of the token during the current or last period. A number 100E27 means that one BLU requires 100 MATIC.
lastTokenSoldInPeriod - Stores the number of tokens sold during the current or last period.
lastTransactionPeriod - Stores the period number where the lastPrice and lastTokenSoldInPeriod is valid for.
totalTokenSold - Stores the total number of tokens sold by the contract.

Key Functionalities

buyToken - Payable method to allow anyone to buy BLU from the contract. Excess funds will be refunded to the buyer if there is not enough BLU to be purchased. This method is protected by re-entrancy guard.
updatePrice - Method to update the price between periods. It is called by buyToken to attempt to update the price whenever purchases are made.
updateSensitivity - Allow admin to update the price sensitivity. It must be greater than 1E27. This should be adjusted to be a lower level once the market has reached a consensus on the initial price. The parameter is set to 2E27 initially.
updatePriceManually - Emergency method to allow admin to update price should the automatic mechanism does not work (ie unbounded loop in currentPrice may require more gas than allowed in a block).
emergencyShutdown - Emergency method to allow admin to shut down the sale until a new patch is rolled out.
withdraw - Method to allow admin to withdraw funds from the contract.
upgradeTo - Upgrades the UUPS contract to a new implementation. Requires upgrader role only granted to timelock/governance contract for upgrading functionalities of the token.

3. Key Mechanism & Concepts

The auction module aims to distribute a fixed number of tokens every day (or period), with a maximum limit. This mechanism allows for price discovery to happen and for work done to be priced in during the entire length of the sale.
The contract targets to sell 300 tokens each day, with a maximum number of 600 tokens available. The price of tokens on the next day depends on how many tokens are sold in the previous period. The maximum price fluctuation is determined by the sensitivity parameter.
For example with a 2E27 sensitivity:
    If the auction sells 0 tokens for the current period, the price will be halved in the next period.
    If the auction sells 150 tokens for the current period, the price will be 0.75x in the next period.
    If the auction sells 300 tokens for the current period, the price will remain the same in the next period.
    If the auction sells 450 tokens for the current period, the price will be 1.5x in the next period
    If the auction sells 600 tokens for the current period, the price will be doubled in the next period.

4. Gotchas (Potential sources of user error)

The contract allows users to send any amount MATIC to the contract and refunds excessive MATIC to the users. In the case where there are no more BLU for sale, users can still continue to send funds to the contract and will be simply be returned the MATIC. This can be prevented by encouraging users to use the front-end application to buy MATIC.
Users might send funds to contracts on the wrong network. This is prevented by encouraging users to use the front-end application to buy MATIC where it ascertains that the user to connected to the right network first.
Users might send other tokens to the contract. This is prevented by encouraging users to use the front-end application to buy MATIC.

5. Known Risk

    1.
    Contract Upgrade Error - There are caveats to writing upgradable smart contracts, as well as tools to ensure safe upgrades, that the developers should be aware of. Failure to follow the safety protocol may result in corruption of stored states in the smart contract as well as rendering the contract impossible to upgrade.
    2.
    Excessively High Price Sensitivity - Once there is sufficient liquidity in the market and the prices stabilized, the price sensitivity should be reduced to prevent the auction from selling 100% of the token on one day when the asset is hugely underpriced, and then selling 0% of the tokens the next day when the asset is hugely overpriced in a continuous loop.
Last modified 1mo ago