# Architecture

{% hint style="info" %}
Frontend demonstration: <https://app.increment.fi/oracle>
{% endhint %}

## Overall architecture

### Mainnet:

**Basic architecture**: *Multiple whitelisted-nodes* independently fetching price data from *multiple data* *sources* to guard against potential node failure. Then the medianizer contract aggregates and picks the median data reported from whitelisted nodes.&#x20;

<figure><img src="https://3251356001-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOYVGTCPlwadp5cBBtffl%2Fuploads%2FpRl3rElyicOou62fzriC%2Fimage.png?alt=media&#x26;token=760d344b-13b8-4ac5-97fb-71014ea90265" alt=""><figcaption></figcaption></figure>

There are two ways for nodes to perform price aggregation: median method and weighted-average method.

* **Median**: When there are enough price origins, taking the median value can improve security more effectively.
* **Weighted-average**: Based-on trading volume, liquidity depth, exchange reputation, etc., price will be fetch from different exchanges for different fungible tokens, applied with different weights.

#### **Flow/USD** price feed&#x20;

It has 8 origins currently and is applied with the ***median*** method based on <https://www.coingecko.com/en/coins/flow#markets>:

* Kraken [Flow/USD](https://pro.kraken.com/app/trade/FLOW-USD) &#x20;
* Coinbase [Flow/USD](https://pro.coinbase.com/trade/FLOW-USD)
* Binance [Flow/USDT](https://www.binance.com/en/trade/FLOW_USDT) x (Latest USDT/USD On-Chain PriceOracle data)
* OKX [Flow/USDT](https://www.okx.com/trade-spot/flow-usdt) x (Latest USDT/USD On-Chain PriceOracle data)
* Gateio [Flow/USDT](https://www.gate.io/zh/trade/FLOW_USDT) x (Latest USDT/USD On-Chain PriceOracle data)
* Huobi [Flow/USDT](https://www.huobi.com/en-us/exchange/flow_usdt) x (Latest USDT/USD On-Chain PriceOracle data)
* KuCoin [Flow/USDT](https://www.kucoin.com/trade/FLOW-USDT) x (Latest USDT/USD On-Chain PriceOracle data)
* Bybit [Flow/USDT](https://www.bybit.com/en-US/trade/spot/FLOW/USDT) x (Latest USDT/USD On-Chain PriceOracle data)

#### **USDT/USD** price feed

It has 3 origins and is applied with the ***weighted-average*** method base on <https://www.coingecko.com/en/coins/tether#markets>:

* Kraken [USDT/USD](https://pro.kraken.com/app/trade/usdt-usd) - 50%
* Coinbase [USDT/USD](https://pro.coinbase.com/trade/USDT-USD) - 35%
* Bitfinex [USDT/USD](https://trading.bitfinex.com/t/UST:USD?type=exchange) - 15%\*

*\* There're concerns and rumors about Bitfinex & Tether manipulation / non-transparency. So although Bitfinex's USDT/USD volume is on par with Coinbase's, it only has a weight of 15%.*

#### **Stablecoins'** price feed

* **USDC/USD** price feed has 5 price origins and is applied with the ***median*** method based on <https://www.coingecko.com/en/coins/usd-coin#markets>:

  *(\* According to the recent SBV's collapse and Circle is* [*holding*](https://twitter.com/circle/status/1634391505988206592) *a % of cash reserve in SBV, so USDC is not fixed to 1.0 face value any more since 03/11/2023.)*

  * The "fair-value" 1.0
  * Kraken [USDC/USD](https://pro.kraken.com/app/trade/USDC-USD)
  * (Bybit [USDC/USDT](https://www.bybit.com/en-US/trade/spot/USDC/USDT)) x (Latest USDT/USD On-Chain PriceOracle data)
  * (Binance [USDC/USDT](https://www.binance.com/en/trade/USDC_USDT)) x (Latest USDT/USD On-Chain PriceOracle data)
  * (OKX [USDC/USDT](https://www.okx.com/trade-spot/usdc-usdt)) x (Latest USDT/USD On-Chain PriceOracle data)
* **FUSD/USD** price feed is applied with a *constant* 1.0. (FUSD is under-deprecation on Flow, and there's very little exposure to FUSD.)

#### **Other fungible tokens' price feed**:

* **BLT/USD** price feed is applied with the ***weighted-average*** method based on <https://www.coingecko.com/en/coins/blocto-token#markets>:
  * Gateio [BLT/USDT](https://www.gate.io/zh/trade/BLT_USDT) x (Latest USDT/USD On-Chain PriceOracle data) - 67%
  * Mexc [BLT/USDT](https://www.mexc.com/exchange/BLT_USDT) x (Latest USDT/USD On-Chain PriceOracle data) - 33%
  * \*To on-board BLT token's price from Bloctoswap, it needs to integrate with care.
* **stFlow/USD** price feed is computed with on-chain data by:
  * &#x20;(stFlow/Flow taken from LiquidStaking Contract) x (Flow/USD On-Chain PriceOracle data)

### Testnet:

**Basic architecture**: A *single node* fetching from *multiple* data sources. (Very much close to the mainnet's arch, but to save our resources and costs.)

### Emulator:

**Basic architecture**: A *single node* SimpleOracle fetching from a *single data* source (Coingecko api) is used on emulator for local bootstrapping and testing.&#x20;

Price data is periodically fetched, and it gets updated whichever below conditions happen first:

* `windowSize`: e.g. 1200 - every 1,200 seconds
* `deviation`: e.g. 0.01 - once Δ { fetchedData, lastData } > 0.01 \* lastData

## Contract architecture

<figure><img src="https://3251356001-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOYVGTCPlwadp5cBBtffl%2Fuploads%2FI68lDSyGQlCVnCYFglgE%2Fimage.png?alt=media&#x26;token=b6ab74fa-b2fe-42a9-993d-46f92d1ba251" alt=""><figcaption></figcaption></figure>

For each different type of price feed, a separate `PriceOracle` contract is deployed to support it.&#x20;

The PriceOracle contract defines two whitelists and two resources: `PriceReader` and `PriceFeeder`. PriceReader resource holder has the ability to access reported data as long as it's also in the reader whitelist. PriceFeeder resource holder has the ability to post price data and influence the medianized onchain price data as long as it's also in the feeder whitelist.

<figure><img src="https://3251356001-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOYVGTCPlwadp5cBBtffl%2Fuploads%2F5APdXKegE8LaG0eLbeN2%2Fimage.png?alt=media&#x26;token=c87cfbdd-8d8f-4ff8-b8de-44fa7cabcf82" alt=""><figcaption></figcaption></figure>

* For developers to use the on-chain price data in your Cadence contracts there's no barrier to apply for the reader whitelist - we've made it **free and public** through the PublicPriceOracle contract with some Chainlink-like APIs. Please read [using-price-feeds](https://docs.increment.fi/protocols/decentralized-price-feed-oracle/using-price-feeds "mention") for more details.&#x20;
* For institutions and partners interest in joining node runners & feeder whitelist to provide more decentralized price feeds on flow, welcome to contact us.