owned this note   changed 2 years ago  
Published Linked with GitHub

GMX Price Feed Explainer

The following notes explain the GMX Protocol's price fetching mechanism. The primary aim to convey a sense of the price fetching mechanism and execution flow as it is used by the GMX protocol.

Introduction

The Vault is one of the central contracts of the GMX protocol. It allows users to deposit funds into the vault and mints them GLP tokens. In addition to withdrawing their assets from the vault, users can also swap tokens, short and long (bet on asset prices, whether they will fall or rise) using leverage. Users get liquidated if losses of the position reduce the collateral's value to the point where position size / deposited collateral is more than the max allowed leverage. This makes asset price fetching very important. Price fetching done through two contracts: VaultPriceFeed and FastPriceFeed.

Price Calculation Overview

keeper bots calculate asset prices by averaging the prices of said asset on Binance, Bitfinex and Coinbase. There are two types of keeper bots:

  1. PriceFeedKeeper: Submits prices for swaps routinely (every 2 hours)
  2. PositionKeeper: Submits prices when a position is being executed.

Prices submitted from keepers are not used in two cases (i.e., chainlink prices are used instead):

  1. It has been more than 5 minutes since the last keeper price submission.
  2. The keeper prices deviate by more than the maxDeviationBasisPoints (currently 1000 so 10%) in which case a spread will be used. See further below.

There is also a element called maxDeviationBasisPoints (currently 1000 so 10%). This is the historical max deviation of the prices supplied by the keepers from the chainlink price. If the prices supplied by the keeprs deviate by more than 10% from the chainlink price e.g., CL is 100 and keeper price is 111, then a pricing spread would be created: 100 and 111.

This pricing spread will then be used as follows:

  1. Long Position: High price used when opening, low price used when closing.
  2. Short Position: Low price used when opening, high price when closing.

There are also Watcher bots which monitor Keeper bots for irregular conduct. If it is noticed, then Watcher bots can enforece a spread even if the keeper bots are submitting prices that are within max deviation and are not stale.

All prices are multiplied by 1e30 or 10**30 to increase precision. 1 USD is thus equal to 1e30.

Basis points are also used to account for finer movements in prices and values. 10000 is the BPSDivisor, the max spread bps is 50, max adjustment interval is 2 hours and max adjustment bps are 20.

There is another contract called FastPriceFeed which is used as a secondary price feed. The prices returned from this contract's getPrice function are ones that are submitted by the keeprs and are to be used if there are none of the issues mentioned above which either force use of the chainlink price or the spread.

The maximise bool is used to return the higher or lower of the spread price.

This above is explained below in detail along with the execution steps.

Price Fetching Flow:

Contracts in consideration::

  1. VaultPriceFeed: 0x2d68011bcA022ed0E474264145F46CC4de96a002
  2. FastPriceFeed: 0x11D62807dAE812a0F1571243460Bf94325F43BB7

VaultPriceFeed Relevant State: (31Dec2022)
useV2Pricing: false
isAmmEnabled: false
isSecondaryPriceEnabled: true
secondaryPriceFeed aka FastPriceFeed
MAX_ADJUSTMENT_INTERVAL: 2 hours (7200s)
MAX_ADJUSTMENT_BASIS_POINTS: 20 BPS (0.2%)
MAX_SPREAD_BASIS_POINTS: 50 BPS (0.5%)
BPS_DIVISOR: 10000 (100%)
maxStrictPriceDeviation: 10000000000000000000000000000 OR 1e28

FastPriceFeed Relevant State: (31Dec2022)
MAX_PRICE_DURATION: 30 minutes (1800s)
priceDuration: 5 minutes (300s)
maxPriceUpdateDelay: 1 hr (3600s)
isSpreadEnabled: false
spreadBasisPointsIfChainError: 500 (5%)
spreadBasisPointsIfInactive: 2 (0.2%)
maxDeviationBasisPoints: 1000 (10%)

Functions in consideration:

1.VaultPriceFeed.getPrice(address _token, bool _maximise, bool _includeAmmPrice)
2.FastPriceFeed.getPrice(address _token, uint256 _refPrice, bool _maximise)

Looking into getPrice

The following happens when a call to VaultPriceFeed.getPrice(_token, _maximise, _includeAmmPrice) is made:

  1. Fetch the token price from Chainlink (via getPrimaryPrice(_token, _maximise)), use the highest/ lowest out of 3 rounds depending on the maximise bool passed.
  2. If isSecondaryPriceEnabled is true (it is), use the other contractFastPriceFeed.getPrice(_token,price,maximise) to calculate and use a price.

We now look at FastPriceFeed.getPrice where the process goes after step 2. This function is supplied 3 arguments:

a. The token address

b. The reference price for the given token as fetched from Chainlink in VaultPriceFeed.getPrice().

c. The maximise bool, whether to return the higher or lower price in case a spread is used.

  1. If it has been more than 1 hr since the price was last updated, convert price to BPS (multiply by BPS_DIVISOR - 10_000BPS) add spreadBasisPointsIfChainError (500BPS so 5%) to it and divide by BPS_DIVISOR and this is the price.

    3.1. If it has not been more than 1 hr since last price update, then if it has been more than priceDuration (5 minutes) since the last price update, add / subtract spreadBasisPointsIfInactive (2 BPS - 0.2%) from the price depending on the maximise bool, and this is the price.

  2. If It has NEITHER been 1 hr NOR 5 mins since last price update, calculate the BPS diff b/w refPrice and fastPrice (the stale price from prices[_token] for the given token, ).

  3. If favorFastPrice(_token) returns false for this token (i.e., bool to use the fast price or not. Watcher bots can disable fast price for this token due to any suspicion) OR the diff as calculated in prev step exceeds the maxDeviationBasisPoints 1000 so 10%, then a spread-based (i.e., higher or lower) price will be returned depending on _maximise. If maximise is true, then the greater of refPrice and fastPrice will be returned. If maxmimise is false, then the lesser of the two is the price.

  4. If favorFastPrice returns true for the token and the diff in BPS is within the maxDeviationBasisPoints threshold, then the price is simply the fastPrice which is prices[token].

Control now shifts back to VaultPriceFeed.getPrice() as the price calculated thus far by FastPriceFeed.getPrice() is returned to it. VaultPriceFeed.getPrice() takes this price and performs further checks and calculations as shown below:

  1. If the token is a stablecoin, check how much its price deviates from 1 USD (10**30). If it the difference b/w 1 USD and its price is within the maxStrictPriceDeviation (1e28), continue with this price.

    7.1. If the price is more than 1 USD and maximise is true, return that price. Similarly, if the price is less than 1 USD and maximise is false, continue with this price.

    7.2 If the price is neither more than 1 USD nor less than it, continue with 1 USD (1e30) as the price.

  2. If the token is not a stable coin, add/ subtract (depending on maximise bool) the spreadBasisPoints for that token(if any have been set) and continue with this price.

  3. If the token has any adjustmentBps set, then add/ subtract those from the price calculated thus far, depending on if the isAdjustmentAdditive[token] for this token is additive or subtractive.

  4. Return the price to the caller.

Select a repo