diff --git a/docs/index.md b/docs/index.md index 1ae956d0d..4a654788a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -40,7 +40,7 @@ Descriptions of Flare’s products Quick links: -* [FTSO](./tech/ftso/index.md) +* [FTSO](https://dev.flare.network/ftso/overview) * [State Connector](./tech/state-connector.md) * [FAssets](./tech/fassets/index.md) @@ -64,11 +64,6 @@ Quick links: - - - - - These pages are a **Work In Progress**. Use the contact buttons at the bottom of the page if there is anything you cannot find here! diff --git a/docs/infra/data/index.md b/docs/infra/data/index.md index 6fdcc46ad..d8346b784 100644 --- a/docs/infra/data/index.md +++ b/docs/infra/data/index.md @@ -1,9 +1,8 @@ # FTSO Data Providers -These guides explain how to manage the infrastructure required for the [FTSO system](../../tech/ftso/index.md). +These guides explain how to manage the infrastructure required for the FTSO system. Select one of the guides below: -* [Operating a Data Provider](./operating.md) * [Working with Whitelists](./whitelisting.md) * [Managing the Ecosystem](./managing-ecosystem/index.md) diff --git a/docs/infra/data/operating.md b/docs/infra/data/operating.md deleted file mode 100644 index 53a25765e..000000000 --- a/docs/infra/data/operating.md +++ /dev/null @@ -1,240 +0,0 @@ -# Operating a Data Provider - -## Introduction - -!!! info inline end "Quick links" - - * [NPM Kickoff package](https://www.npmjs.com/package/@flarenetwork/ftso_price_provider_kick_off_package) - * [Reference implementation](https://github.com/flare-foundation/FTSO-price-provider) - -[Data providers](glossary.md#data_provider) play an essential role in the decentralized oracle system by submitting data to on-chain contracts deployed on the Flare and Songbird networks. -Operating a data provider generates rewards in `$FLR`, `$SGB`, or both for you and the people who delegate tokens to you. -To maximize your rewards, your data provider needs to be constantly available and operating. -If your data provider is unavailable and doesn't send data during a specific epoch, you and your delegators won't earn rewards during that epoch. - -If all the submission and reveal transactions are successful, the cost is approximately 3 - 4 `$FLR` or `$SGB` per day. - -Data providers consist of the following code components, and you can write them in any language: - -* **FTSO interface**: The code that submits data to the FTSO. - This code is all the necessary logic to determine which data epoch you want to submit data in and to assess when and what to submit throughout all reward epochs. -* **Data algorithm**: The code that runs the algorithm that collects and processes data. - The more efficient this code is the better advantage over competing data providers you will have. - Consider [these tips for maximizing your advantage](#maximizing-your-data-algorithms-performance). - -The rest of this guide explains how to deploy and operate a data provider. - -## Prerequisites - -While none of the listed prerequisites are required, you will be more successful if you have them before you try to deploy an FTSO data provider: - -* Familiarity with smart contracts, signal processing, game theory, and prompt data submission on blockchains -* Experience with a coding language that has a web3 library, for example: - - | Language | Web3 Library | - | ---------- | -------------------------------------------------------------------------------- | - | Go | [go-web3](https://github.com/chenzhijie/go-web3) | - | Java | [web3.j](https://docs.web3j.io/) | - | JavaScript | [ethers.js](https://docs.ethers.org/), [web3.js](https://web3js.readthedocs.io/) | - | Node.js | [ethers.js](https://docs.ethers.org/), [web3.js](https://web3js.readthedocs.io/) | - | Python | [web3.py](https://web3py.readthedocs.io/) | - | Rust | [rust-web3](https://docs.rs/web3/latest/web3/) | - -## Getting Started - -To start building your data provider, use the [npm kick-off package](https://www.npmjs.com/package/@flarenetwork/ftso_price_provider_kick_off_package). -It showcases the main contracts related to whitelisting a data provider and submitting data, and it enables you to deploy FTSO mock contracts in a local setup and submit data to those contracts. - -Providing data by using this package is like providing data on-chain. -The following aspects work identically in the package and on-chain: - -* Smart-contract APIs -* Events - -Timing aspects in the package work similarly but not identically to timing aspects on-chain. -The package does not run the weighted-median algorithm or do calculations to distribute rewards like the FTSO smart contract deployed on-chain does. - -The [Flare Network price provider](https://github.com/flare-foundation/FTSO-price-provider) repository shows an example of a data-provider implementation. -This implementation shows the FTSO interface and a sample data algorithm. -To earn rewards, you must write your own data algorithm. - -## Interacting with Smart Contracts - -Data providers interact primarily with the `PriceSubmitter` contract and the different `FTSO` contracts. -Other useful contracts are: - -* `FtsoRegistry`: Holds information about specific FTSOs, their symbols, indices, and addresses. - To see supported tickers, query the `getSupportedSymbols` method. - New tickers can be added by a governance vote. -* `FtsoManager`: Holds epoch and voting-related configuration data, oversees all FTSOs, and gives access to additional useful contracts, such as the `Inflation` and `Supply` contracts. -* `VoterWhitelister`: Accepts the names of data providers that list themselves to submit data. - -Find these contract addresses in the [Developer Hub](https://dev.flare.network/). - -## Generating Random Numbers - -The data-providing process is structured as a commit-and-reveal scheme to prevent users from copying another user's submitted data. -The commit-and-reveal phases are restricted to only a few minutes in duration. -With each reveal the data provider also provides a random number. -The random number is used first as a salt in the commit-and-reveal scheme and later during the reward calculation process. - -Strong random numbers are important for network security because they are the only true source of randomness on the network, and they make the commit-and-reveal scheme resilient to attacks. Random numbers below 2^128^ are considered weak and unsafe, and they are rejected when they are revealed. - -To provide strong, cryptographically secure, random numbers with high entropy and sufficient range, consider implementing the following strategies: - -* Use available random-number generators, such as the [`csprng library`](https://www.npmjs.com/package/csprng) for Node.js applications or the `web3.utils.toBN(web3.utils.randomHex(32))` function in the [`web3.utils` package](https://web3js.readthedocs.io/en/v1.2.11/web3-utils.html) for JavaScript. -* Submit 256-bit random numbers. - -## Calculating Hash for the Commit-and-Reveal Scheme - -The [FTSO price provider](https://gitlab.com/flarenetwork/flare-smart-contracts/-/blob/master/docs/specs/PriceProvider.md) shows the complete specification for the commit-and-reveal scheme. - -The following code snippets show how to generate hashes in Typescript and Python using publicly available web3 libraries: - -=== "Typescript" - - ```typescript - import BN from "bn.js"; - import { - BigNumber - } from "ethers"; - import { - ethers - } from "hardhat"; - const MIN_RANDOM = web3.utils.toBN(2).pow(web3.utils.toBN(128)); - - function submitHash(ftsoIndices: (number | BN | BigNumber)[], - prices: (number | BN | BigNumber)[], - random: number | BN | BigNumber, - address: string): string { - - return ethers.utils.keccak256(web3.eth.abi.encodeParameters( - ["uint256[]", "uint256[]", "uint256", "address"], - [ftsoIndices, prices, random, address])); - } - const ftsoIndices = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - const randoms = [MIN_RANDOM, MIN_RANDOM.addn(5), MIN_RANDOM.addn(1059), - MIN_RANDOM.addn(10682), MIN_RANDOM.addn(159726) - ]; - const prices = [0, 1, 2, 3, 5, 10, 50, 100, 101, 10 ** 5 + 1, 10 ** 8]; - const addrs = [accounts[10], accounts[11], accounts[12], accounts[13]]; - - console.log(`Prices: ${prices}`); - for(let addr of addrs) { - console.log(`Address: ${addr}`); - for(let random of randoms) { - console.log(`\tRandom: ${random}`) - const hash = submitHash(ftsoIndices, prices, random, addr); - console.log(`\t\t${hash}`); - } - } - ``` - -=== "Python" - - ```python - from typing import List - from web3 import Web3 - import eth_abi - - minimal_random = 2 ** 128 - - def submit_price_hash( - ftsoIndices: List[int], prices: List[int], random: int, address: str - ) -> str: - assert len(ftsoIndices) == len(prices) - assert list(sorted(ftsoIndices)) == ftsoIndices and len( - set(ftsoIndices) - ) == len(ftsoIndices), "Indices are non increasing" - return Web3.keccak( - eth_abi.encode_abi( - ["uint256[]", "uint256[]", "uint256", "address"], - [ftsoIndices, prices, random, address], - ) - ).hex() - - - def test_fun( - prices: List[int], - random: int, - address="0xD7de703D9BBC4602242D0f3149E5fFCD30Eb3ADF", - ) -> List[str]: - return submit_price_hash(list(range(len(prices))), prices, random, address) - - - addrs = [ - "0xD7de703D9BBC4602242D0f3149E5fFCD30Eb3ADF", - "0xEa960515F8b4C237730F028cBAcF0a28E7F45dE0", - "0x3d91185a02774C70287F6c74Dd26d13DFB58ff16", - ] - prices = [0, 1, 2, 3, 5, 10, 50, 100, 101, 10 ** 5 + 1, 10 ** 8] - randoms = [ - min_random + r for r in - [0, 1, 100, 101, 100000000000000000000] - ] - for addr in addrs: - print(f"Address: {addr}") - for rand in randoms: - print(f" Random: {rand}") - print(" hash:", test_fun(prices, rand, addr)) - print() - ``` - -!!! info - To see sample code for calculating submit hashes using the `web3.py` library, see the [`hasher.py` gist](https://gist.github.com/jO-Osko/a9e8904cb3e8f9af5f154302117b4444). - -## Retrieving Information About Rewarded Data - -Listen for `PriceFinalized` events, which contain information about calculated median data and rewarding bounds. -Each FTSO emits these events. - -## Managing Vote Power - -* To check your [vote power](../../tech/ftso/index.md#vote-power) in a specific vote power block, use the `votePowerOfAt` method in the `WNat` contract. - -* To find the vote-power block of the current reward epoch, use the `getCurrentRewardEpoch` method in the `FtsoManager` contract. - Then, use the `getRewardEpochVotePowerBlock` method in the same contract. - -* Vote power [delegated](../../tech/ftso/index.md#delegation) to you belongs to only you; you cannot redelegate it. - To retrieve information about delegations you receive, listen to `Delegate` events because this information is not contained in any on-chain structure. - -## Retrieving Price Epoch Information - -Use the `getPriceEpochConfiguration` method in the `FtsoManager` contract to retrieve: - -* When the first price epoch started, as a UNIX timestamp. -* The duration of every price epoch, in seconds. -* The duration of every reveal phase, in seconds. - -These numbers allow you to calculate the price epoch number from any timestamp. - -The duration of price epochs is fixed and can only change through a governance decision. - -## Submitting Data On-Chain - -After you feel comfortable running the local npm package, you can start submitting your data on the real network. - -To run on the real network, you need to: - -* **Gain vote power**: You can [whitelist yourself](whitelisting.md) as a data provider only if you have enough vote power. -* **Optimize your timing**: - * Align with the on-chain time data. - Because the network is decentralized, the on-chain timestamp might skew up to 30 - 40 seconds from the real-world time. - To avoid missing commit-and-reveal periods, synchronize local time with global time through the [Network Time Protocol (NTP)](https://en.wikipedia.org/wiki/Network_Time_Protocol). - * The later you submit, the more time you have to gather data. - However, if you submit too late, you might miss the epoch window. - Find the balance that works best for you. -* **Claim rewards**: Ensure you regularly [claim your rewards](../../user/delegation/managing-rewards.md) and wrap them to earn more vote power. Each FTSO emits a `PriceFinalized` event that contains information about calculated median data and rewarding bounds. -* **Set the gas limit** of your commit-and-reveal transactions to around 2'500'000 gwei so that you provide enough gas. - -## Maximizing Your Data Algorithm's Performance - -Use the following tips: - -* Run your own [observer node](https://dev.flare.network/run-node/rpc-node) and submit all your data through it. - This will allow you to more efficiently and securely operate your data provider. -* Gather your data directly from each source instead of using APIs provided by data aggregators. -* Write your own code instead of relying entirely on third-party code. -* Keep an open mind, and try new strategies to find your advantage over other data providers and keep it. - -If your submissions are reverted, ensure the node you submit them through is healthy and has enough peers, and review the above tips. \ No newline at end of file diff --git a/docs/tech/archive/ftso-v1.md b/docs/tech/archive/ftso-v1.md index 2b4ee8b21..7458a5d2a 100644 --- a/docs/tech/archive/ftso-v1.md +++ b/docs/tech/archive/ftso-v1.md @@ -247,6 +247,5 @@ It is also worth noting that: ## Related Infrastructure Guides -* [Operating a Data Provider](../../infra/data/operating.md) * [Working with Whitelists](../../infra/data/whitelisting.md) * [Managing the Ecosystem](../../infra/data/managing-ecosystem/index.md) diff --git a/docs/tech/flare.md b/docs/tech/flare.md index 109a41561..8bf6037bf 100644 --- a/docs/tech/flare.md +++ b/docs/tech/flare.md @@ -12,7 +12,7 @@ Flare is the blockchain for data. It is a [layer 1](glossary.md#layer1), [EVM](glossary.md#evm) [smart contract](glossary.md#smart_contract) platform designed to expand the utility of blockchain. Flare's aim is to provide data as a public good, meaning that data is not controlled by a centralized entity and is available to all. -The infrastructure providers, which perform doubly as [validators](../tech/validators.md) and [data providers](../infra/data/operating.md), enable two native [oracles](glossary.md#oracle), the [FTSO](./ftso/index.md) and the [State Connector](./state-connector.md). +The infrastructure providers, which perform doubly as [validators](../tech/validators.md) and data providers, enable two native [oracles](glossary.md#oracle), the [FTSO](./ftso/index.md) and the [State Connector](./state-connector.md). This [native](glossary.md#native) processing provides developers on Flare with efficient access to large amounts of data and [data proofs](glossary.md#data_proof) at minimal cost, with which to build software on the platform. By giving developers [trustless](glossary.md#trustless) access to the broadest range of data needed by the software they build, Flare can advance the development of more blockchain use cases where data is important, such as in [DeFi](glossary.md#defi), gaming, [NFT](glossary.md#nft), music, social networks, Real World Assets [(RWAs)](glossary.md#rwa), Machine Learning (ML), and Artificial Intelligence (AI). diff --git a/docs/tech/ftso/ftso-fast-updates.md b/docs/tech/ftso/ftso-fast-updates.md deleted file mode 100644 index 7fd1e6c0f..000000000 --- a/docs/tech/ftso/ftso-fast-updates.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -search: - boost: 2 ---- - -# FTSO Fast Updates - -FTSO Fast Updates is one of the two [FTSO sub-protocols](./index.md). -In every block, data providers are randomly selected from an open set to provide small, cumulative updates to each data feed's value. - -This operation differs from the other FTSO sub-protocol, [FTSO Scaling](./ftso-scaling.md), in which all data providers contribute to the data feed's value but updates only every 90 seconds. - -!!! note - - FTSO Fast Updates is part of the second iteration of the FTSO protocol. - For information about previous implementations, please visit [the archive](../archive/ftso-v1.md). - -## Process - -The FTSO Fast Updates protocol is integrated with the [Flare Systems Protocol](../flare-systems-protocol.md) but does not make use of all its features. -In particular, data providers do not vote on the correctness of data feed values, so the protocol does not require voting rounds as the FTSO Scaling protocol does. -Voting epochs are only used for rewarding. - -Conversely, data providers submit their values in each block, directly to a smart contract, as described next. - -### Sortition Process - -Using a [verifiable random function](https://en.wikipedia.org/wiki/Verifiable_random_function), data providers independently decide whether they should submit a new update in each block. - -
- ![FTSO Fast Updates workflow](ftso-fu-workflow.png){ loading=lazy .allow-zoom } -
FTSO Fast Updates workflow.
-
- -The chance of being selected is proportional to a data provider's weight, which is the sum of its own stake and the [delegations](./ftso-scaling.md#delegation) made to it. -Since selection is random, some blocks might receive more or less than one update, but on average, each block receives only one. - -Furthermore, to allow for more processing time, data providers are allowed to submit their updates up to 10 blocks later than the block in which they were selected. -This allowance for more processing time might introduce some inaccuracy in the instantaneous values of the data feeds, which are then corrected by subsequent updates. - -Since there is no consensus on the submitted updates, a malicious data provider can try to steer the feeds away from the actual values. -However, the magnitude of each update is limited, and such Byzantine submissions are corrected by subsequent updates from well-behaved data providers. - -### Update Packing - -The amount of space available on a block is limited. -Therefore, in order to support a large number of data feeds, the size of each feed's updates must be necessarily small. - -FTSO Fast Updates uses 2 bits for each update, resulting in 3 possible values (plus an unused one): - -* `+`: The current value of the data feed is increased by a small amount "delta" (δ). -* `-`: The current value of the data feed is decreased by a small amount "delta" (δ). -* `0`: The current value of the data feed remains unaffected. - -After extensive tests, the value of delta has been set to 0.0122% of each feed's current value, or ${1}/{2^{13}}$ %. - -Using this scheme, the updates for 1000 data feeds only require 250 bytes. -After adding the rest of the required signaling this amounts to less than 0.6% of Flare's gas limit per block. - -The following figure shows how the two FTSO sub-protocols compare when following a data feed: - -
- ![FTSO Fast Updates value tracking comparison](ftso-fu-values.png){ loading=lazy .allow-zoom } -
FTSO Fast Updates value tracking comparison.
-
- -FTSO Scaling (in blue) follows exactly the actual value (in green), but only updates every voting epoch (90s). -On the other hand, FTSO Fast Updates (in pink) is able to follow closer to the actual value thanks to the much higher update rate. - -However, since values can only be changed by a fixed amount (delta) every block, FTSO Fast Updates cannot follow quick changes of the tracked value, as shown at the right of the above plot. -The next section shows a solution to this issue. - -The plot also includes the data provider that submitted each update, showing that they are random and proportional to their weights. -In this case, provider A's weight is double that of providers B and C, so its updates appear twice as frequently. - -### Volatility Incentives - -During times of high volatility, which result in rapid price fluctuations, the limited range of the updates cannot follow the tracked value, as shown above. -To deal with this issue, FTSO Fast Updates defines the volatility incentives, which can be provided by any user of the system. - -These incentives allow more data providers to submit their updates, resulting in more updates per block. -In turn, this causes the data feed to react more quickly and be able to better adapt to fluctuations: - -
- ![FTSO Fast Updates incentivization](ftso-fu-values-incentivized.png){ loading=lazy .allow-zoom } -
FTSO Fast Updates incentivization.
-
- -Additionally, incentivized updates use an increased value for delta, not shown in the above diagram. - -Volatility incentives are shared among all data providers that submitted updates, proportionally to the amount of submissions they made during the reward epoch. - -### Rewarding - -Data providers that participated in a 90-second voting epoch are only rewarded if the value of the FTSO Fast Updates at the end of the voting epoch is close enough to the value of the FTSO Scaling, currently meaning within 0.5% of its value. - -This mechanism indirectly ensures that the Fast Updates data feeds do not deviate from the tracked values. diff --git a/docs/tech/ftso/ftso-scaling.md b/docs/tech/ftso/ftso-scaling.md deleted file mode 100644 index 62fa851c1..000000000 --- a/docs/tech/ftso/ftso-scaling.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -mathjax: true -search: - boost: 2 ---- - -# FTSO Scaling - -FTSO Scaling is one of the two [FTSO sub-protocols](./index.md). -It supplies reliable data estimates by calculating the median of all values submitted by an open set of independent data providers, weighted by each data provider's [vote power](#vote-power), every 90 seconds. - -This operation differs from the other FTSO sub-protocol, [FTSO Fast Updates](./ftso-fast-updates.md), which updates values in every block but only one data provider participates the update. - -!!! note - - FTSO Scaling is part of the second iteration of the FTSO protocol. - For information about previous implementations, please visit [the archive](../archive/ftso-v1.md). - -## Data Gathering Overview - -FTSO Scaling is integrated in the [Flare Systems Protocol](../flare-systems-protocol.md) and uses the same concepts. -In particular: - -* **Voting epoch**: A 90-second period, also known as voting round, during which data providers submit data. - Data estimates are produced at the end of each voting epoch. -* **Reward epoch**: A 3.5-day period (3360 voting epochs). - Data providers accrue rewards that are paid at the end of each reward period. - -The procedure to gather data from external sources and produce filtered estimates in a decentralized fashion is summarized below: - -
- ![FTSO workflow](ftso-workflow.png){ loading=lazy .allow-zoom } -
FTSO workflow.
-
- -1. Any user can act as an FTSO data provider, submit data, and collect rewards. - - During each voting epoch, only submissions from the 100 data providers with the most vote power are considered. - An account's vote power is based on its wrapped `$FLR` or `$SGB` balance and the delegations made to it (see [Vote Power](#vote-power) below). - - Submitted data must be one or more of the supported data feeds. - See governance proposals [STP.08](https://proposals.flare.network/STP/STP_8.html) and [FIP.08](https://proposals.flare.network/FIP/FIP_8.html) for the current list. - -2. FTSO data providers submit data in rounds in a commit-and-reveal process, so they cannot see each other's submissions until a round is over. - - This process is like submitting data in a closed envelope, and when the round is over, all envelopes are opened. - - * **Commit**: During the 90-second voting epoch, providers fetch the information, run their algorithms, and submit a hash of the data. - - * **Reveal**: During the first 45 seconds of the following voting epoch, providers submit the actual data. - - See technical details about the [data-submission process](../../dev/reference/ftso.md#data-submission-process) in the developer reference section. - -3. For each data feed, the FTSO system calculates the resulting median, taking into account each provider's vote power (see [How Results are Calculated](#how-results-are-calculated) below). - - All results are aggregated into a [Merkle tree](glossary.md#merkle_tree), and the resulting hash (the Merkle root) is stored on-chain. - Dapps can then retrieve individual data feeds from any of the involved data providers and verify the values against the on-chain hash. - -4. For each voting epoch in which the submitted data is close enough to the median value, data providers and their [delegators](#delegation) are rewarded. - - Rewards are accumulated in reward epochs and can be claimed after the epoch finishes. -{ #reward-epoch } - - See [Rewards](#rewards) below. - -## How Results are Calculated - -This graphic shows the filtering process that turns all submitted data into a single estimate. -See all details [in the Flare whitepaper](https://flare.network/whitepapers/). - -
- ![FTSO value calculation](ftso-price.png){ loading=lazy .allow-zoom } -
FTSO value calculation.
-
- -* During each 90-second voting epoch, submissions from all data providers are stored in a smart contract. - -* Each submission has a value and a weight. - Weight is based on the data provider's [vote power](#vote-power), as explained below. - -* The resulting filtered value is then the [weighted median](https://en.wikipedia.org/wiki/Weighted_median) of all received values. - -* Submissions in the top and bottom 25% range are not [rewarded](#rewards). - -## Vote Power - -* As explained above, an FTSO data provider's submissions are weighted by its vote power. - A data provider's vote power is proportional to the amount of wrapped Flare (`$WFLR`) or Songbird (`$WSGB`) tokens it holds, plus any amount [delegated to it](#delegation). - - !!! note "A data provider's influence is limited" - - A **vote-power cap** limits the influence of individual data providers to **2.5% of the total vote power** on both Flare and Songbird. - - Any vote power above this cap is ignored. - If vote power exceeds the limit, consider delegating those `$WFLR` or `$WSGB` to a different data provider. - -* A snapshot of each data provider's vote power is taken once per reward epoch, and the resulting weight is then used throughout the next reward epoch. -* The actual snapshot block is called the vote-power block, and it is randomly chosen from all the blocks in the previous epoch, moving the epoch starting times 2 hours down: - -
- ![FTSO vote-power calculation](ftso-v2-weight.png){ loading=lazy .allow-zoom } -
FTSO vote-power calculation.
-
- -!!! note "Reward epochs" - - The first reward epoch on **Songbird** started on Thursday Jul 21 2022 18:59:15 (GMT), 1658429955 in Unix time, and repeats every 3.5 days. - Therefore, all Songbird reward epochs start on Thursday evening (GMT) and Monday morning (GMT). - - The first reward epoch on **Flare** started on Thursday, 21 July 2022 19:00:00 (GMT), 1658430000 in Unix time and repeats every 3.5 days. - Therefore, all Flare reward epochs start on Thursday evening (GMT) and Monday morning (GMT). - -## Delegation - -If you hold `$FLR` or `$SGB` tokens, you can delegate them to an FTSO data provider to increase its [vote power](#vote-power) and earn a share of its [rewards](#rewards), resulting in a mutually beneficial arrangement. -When you delegate your vote power, you not only earn rewards but also support reliable data providers, which strengthens the stability of the FTSO and the whole ecosystem. - -Before you can delegate your native `$FLR` and `$SGB` tokens, you must [wrap these tokens](../../user/wrapping-tokens.md) into ERC-20 `$WFLR` and `$WSGB` tokens, an operation you can reverse at any time. - -After you wrap your tokens, you will have the vote power that is equivalent to the wrapped token balance, and you can delegate 100% of this vote power to 1 or 2 data providers. -Delegating 100% of your vote power to reliable data providers committed to providing accurate data maximizes your rewards and enhances the stability of the ecosystem. - -!!! example "The reward rate (for advanced users)" - - As you explore data providers, consider the expected reward rate each one offers. - The reward rate describes how many tokens were earned by a data provider during a reward epoch for every 100 tokens delegated. - - The reward rate is calculated as $total\_reward / vote\_power * (100 - fee)$, where: - - * $total\_reward$: All accumulated rewards for the data provider and its delegators in the reward epoch. - * $vote\_power$: All the data provider's `$WFLR` and all the `$WFLR` delegated to it in the vote-power block selected for the reward epoch. - * $fee$: The amount kept by the data provider as compensation for the service it provides. - The value is specified as a percentage. - For example, if the data provider's fee is 21.3%, specify 21.3 to calculate the reward rate. - - Because rewards are distributed in units of `$FLR`, the reward rate is calculated in units of `$FLR`. - -For the duration of the delegation, you will earn rewards that are commensurate with vote power and the performance of the chosen data providers. -Rewards accumulate, and they become claimable for each reward epoch that is finalized. - -[Inflation](glossary.md#inflation) is distributed to everyone who participates in the FTSO system, which includes data providers and entities that delegate their vote power to the data providers. -Delegated tokens are not locked, meaning that they remain in the user's control and the delegation can be removed at any time. - -Any `$WFLR` or `$WSGB` that is newly wrapped, sent, or received will automatically update your actual delegated vote power. -However, if you receive native tokens, you must [wrap them](../../user/wrapping-tokens.md) before you contribute to existing delegations. - -### Immediate Delegation Revocation - -Sometimes, a data provider might maliciously attack the FTSO system to skew the reported data. -If this type of attack occurs, the vote power of a data provider can be revoked immediately instead of in the next reward epoch. - -In this situation, an off-chain process, such as a Twitter storm, calls for users to revoke vote power from the data provider that has attacked the system. -When vote power is revoked, the revocation occurs immediately. - -### Effects of the Vote-Power Block Snapshot on Delegations - -The following table shows when new, changed, and revoked delegations take effect in relation to the vote-power block snapshot. - -| Delegation Type | Before or After Vote-Power Block Snapshot | When Delegation Takes Effect | -| --------------- | ----------------------------------------- | -------------------------------- | -| New or changed | Before | In the next reward epoch | -| | After | After the next reward epoch ends | -| Revoked | N/A | Immediately | - -### Delegation Procedure - -You can [delegate your tokens using the Flare Portal](../../user/delegation/managing-delegations.md), a supported wallet like [Bifrost](../../user/wallets/bifrost-wallet.md), or a [dapp](glossary.md#dapp). -Some FTSO data providers offer these dapps as a convenience. -Take a look at [flaremetrics.io](https://flaremetrics.io/) and pick the one you prefer. - -## Rewards - -A percentage of the annual network **[inflation](glossary.md#inflation)** is reserved to reward FTSO data providers and distributed uniformly among the year's reward epochs. -The mechanism that distributes rewards to data providers consists of several bands: - -* **Primary reward band**: This band rewards [50% of submitted data, weighted by vote power and centered around the median price](#how-results-are-calculated). -That is, the primary reward band fixes the rewarded vote power at 50%, which makes the width of the primary reward band in each epoch variable. -* **Secondary reward band**: This band rewards [submitted data that falls within a fixed percentage around the calculated median](https://proposals.flare.network/STP/STP_2.html#annex-a). -That is, the width of the secondary reward band is fixed, which makes the rewarded vote power in each epoch variable. - -Submitted data in each reward epoch belongs to one of the following: - -* Primary reward band -* Primary and secondary reward band -* Neither reward band - -In each reward epoch, rewards are distributed to providers whose submission falls within the primary or secondary reward bands. - -Because the secondary reward band is wider, it rewards more data providers than the primary band. -However, submissions still must be close enough to the median to be included. -If a submission falls within both bands, it receives both rewards because each reward band is independent. - -The secondary reward band receives 30% of all FTSO rewards, and the primary reward band receives the remaining 70%. -As the FTSO system evolves, these reward percentages might be revised later, in accordance with an accepted proposal that requests changes to the secondary reward band. - -After the band rewards are distributed, each provider can take an optional, configurable fee, which is set to 20% by default, and distributes the rest of the reward among all contributors to its vote power, i.e., itself and all its delegators, according to the delegated amounts. - -If you delegated to a data provider, the amount of your rewards depends on multiple factors: - -* The percentage of vote power you delegated -* The data providers to which you delegated your vote power -* The performance of those data providers -* The fee charged by those data providers -* Whether the total vote power of one or both of those data providers exceeded the vote power cap - -You can claim your rewards at the end of each reward epoch. - -You must claim your rewards within 90 days of their availability. -After 90 days, unclaimed rewards are [burned](glossary.md#burn). - -### Reward-Claiming Procedure - -FTSO rewards are not automatically transferred to their recipients. -Instead, the amounts are accumulated in a smart contract and must be claimed once the reward epoch is finished. - -You can [claim your rewards using the Flare Portal](../../user/delegation/managing-rewards.md), a supported wallet like [Bifrost](../../user/wallets/bifrost-wallet.md), or a [dapp](glossary.md#dapp). -Take a look at [flaremetrics.io](https://flaremetrics.io/) and pick the one you prefer. - -To save on gas costs, rewards from multiple reward epochs are claimed simultaneously when you use the Portal. -However, be aware that rewards expire after 90 days. -Moreover, you probably want to claim soon, to redelegate the received amount and obtain compounded rewards. - -It is also worth noting that: - -* Rewards are paid in the network's native currency. - On Flare, the native token is `$FLR`, and on Songbird, the native token is `$SGB`. -* Data providers and their delegators must claim independently. - -## Related User Guides - -* [Managing delegations](../../user/delegation/managing-delegations.md) -* [Managing rewards](../../user/delegation/managing-rewards.md) -* [Wrapping tokens](../../user/wrapping-tokens.md) - -## Related Infrastructure Guides - -* [Operating a Data Provider](../../infra/data/operating.md) -* [Working with Whitelists](../../infra/data/whitelisting.md) -* [Managing the Ecosystem](../../infra/data/managing-ecosystem/index.md) diff --git a/docs/tech/ftso/index.md b/docs/tech/ftso/index.md index f468c7346..6def566a7 100644 --- a/docs/tech/ftso/index.md +++ b/docs/tech/ftso/index.md @@ -5,34 +5,4 @@ search: # FTSO -The Flare Time Series Oracle (FTSO) is a protocol running on the Flare network that provides continuous estimations for different types of data. -It does so in a decentralized manner (no single party is in control of the process) and securely (it takes a lot of effort to disrupt the process). - -To achieve a secure, decentralized system, a set of independent data providers retrieves data from external sources, like centralized and decentralized exchanges, and supplies it to the FTSO smart contracts. -This information is then filtered to produce an agreed-upon final estimate and published on-chain. - -The following diagram shows how data feeds are submitted to and filtered by the FTSO system. - -
- ![FTSO summary](ftso-summary.png){ loading=lazy .allow-zoom } -
FTSO summary.
-
- -Data providers that supply useful information, such as price pairs that are not removed as outliers, are rewarded from inflation. - -The FTSO system comprises two sub-protocols, both making use of the [Flare Systems Protocol](../flare-systems-protocol.md), offering different tradeoffs between decentralization and speed: - -* [FTSO Scaling](./ftso-scaling.md) - - Every published data feed is agreed upon by a majority of data providers, making the feeds highly reliable but necessarily slow to update. - -* [FTSO Fast Updates](./ftso-fast-updates.md) - - Randomly-selected data providers submit small, incremental updates to the data feeds in every block, resulting in a much faster refresh rate at a slight cost in decentralization. - -Applications are free to use either protocol, or both, depending on their needs. - -!!! note - - This is the second iteration of the FTSO protocol. - For information about previous implementations, please visit [the archive](../archive/ftso-v1.md). +For details about the Flare Time Series Oracle (FTSO), see [FTSOv2 in the Flare Developer Hub](https://dev.flare.network/ftso/overview). diff --git a/mkdocs.yml b/mkdocs.yml index f3764c9d2..7ce25280d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -95,12 +95,12 @@ plugins: 'tutorials/reward-faq/block-explorer-+-metamask.md': 'user/delegation/managing-rewards.md' 'tutorials/price-provider/setting-up-an-observation-node/README.md': 'developer-hub.md' 'tutorials/price-provider/setting-up-an-observation-node/observation-node-faq.md': 'developer-hub.md' - 'tutorials/price-provider/ftso-price-provider/README.md': 'infra/data/operating.md' - 'tutorials/price-provider/ftso-price-provider/price-provider-faq.md': 'infra/data/operating.md' + 'tutorials/price-provider/ftso-price-provider/README.md': 'developer-hub.md' + 'tutorials/price-provider/ftso-price-provider/price-provider-faq.md': 'developer-hub.md' 'tutorials/price-provider/ftso-price-provider/whitelisting-a-price-provider.md': 'infra/data/whitelisting.md' 'tutorials/price-provider/ftso-price-provider/whitelisting-price-provider-faq.md': 'infra/data/whitelisting.md' - 'tutorials/price-provider/troubleshooting/price-provider.md': 'infra/data/operating.md' - 'infra/data/deploying.md': 'infra/data/operating.md' + 'tutorials/price-provider/troubleshooting/price-provider.md': 'developer-hub.md' + 'infra/data/deploying.md': 'developer-hub.md' 'tutorials/price-provider/troubleshooting/observation-node.md': 'developer-hub.md' 'tutorials/price-provider/whitelisting.md': 'infra/data/whitelisting.md' 'dev/getting-started/index.md': 'developer-hub.md' @@ -247,6 +247,7 @@ plugins: 'user/delegation/reward-claiming-faq.md': 'tech/ftso/index.md' 'user/delegation/reward-claiming-in-detail.md': 'tech/ftso/index.md' 'user/fassets/minting-redeeming.md': 'user/fassets/index.md' + 'infra/data/operating.md': 'developer-hub.md' 'infra/validation/staking-cli.md': 'user/staking/staking-cli.md' 'infra/observation/faq.md': 'developer-hub.md' 'infra/observation/index.md': 'developer-hub.md' @@ -254,6 +255,8 @@ plugins: 'infra/observation/deploying-docker.md': 'developer-hub.md' 'infra/validation/index.md': 'developer-hub.md' 'infra/validation/deploying.md': 'developer-hub.md' + 'tech/ftso/ftso-scaling.md': 'https://dev.flare.network/ftso/overview/' + 'tech/ftso/ftso-fast-updates.md': 'https://dev.flare.network/ftso/overview/' extra_css: - assets/stylesheets/extra.css @@ -336,8 +339,6 @@ nav: - products/index.md - FTSO: - tech/ftso/index.md - - tech/ftso/ftso-scaling.md - - tech/ftso/ftso-fast-updates.md - tech/state-connector.md - FAssets: - tech/fassets/index.md @@ -367,7 +368,6 @@ nav: - infra/index.md - FTSO Data Providers: - infra/data/index.md - - infra/data/operating.md - infra/data/whitelisting.md - Managing the Ecosystem: - infra/data/managing-ecosystem/index.md