Skip to content

Commit f453a08

Browse files
magurhmagurh
committed
Merge branch 'custom-feeds' into 'main'
Custom feeds See merge request flarenetwork/docs-team/governance-proposals!24
2 parents e1d26cc + ac70bf2 commit f453a08

File tree

3 files changed

+266
-1
lines changed

3 files changed

+266
-1
lines changed

‎FIP/FIP_13.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
nav_order: 10013
3+
title: FIP.13
4+
---
5+
6+
# FIP.13: Add Custom Feeds to FTSO
7+
8+
| Type | Flare Improvement Proposal |
9+
| :----------------- | :------------------------------------------ |
10+
| Author | Flare Foundation |
11+
| Created | 04-Feb-2025 |
12+
| Document Status | Draft |
13+
| Majority Condition | 50% (required) |
14+
15+
## 1. Brief Description
16+
17+
The Flare Time Series Oracle (FTSO) provides decentralized price feeds for the Flare network through a system of data providers who submit price data for various crypto assets.
18+
Currently, the FTSO only supports direct price feeds for assets that maintain significant trading volume on centralized exchanges.
19+
These feeds are supplied by Flare’s network of data providers.
20+
21+
However, the system has limited support for custom types of data feeds such as Liquid Staked Tokens (LSTs), Liquid Restaked Tokens (LRTs), and more generally, feeds of an arbitrary time-series nature.
22+
This proposal seeks to extend the FTSO by implementing *Custom Feeds* - a new category of feeds that derive their values through custom logic encoded in on-chain smart contracts.
23+
24+
Custom Feeds will be made available through the same interface as FTSO’s block-latency feeds i.e. through the long-term support (LTS) `FtsoV2Interface` contract.
25+
Their implementation does not require any modification to the FTSO data provider client logic, nor to dApps integrating the FTSO.
26+
Furthermore, there is no token inflation allocated to Custom Feeds.
27+
28+
The implementation of Custom Feeds will significantly enhance DeFi capabilities across the Flare network.
29+
Lending and borrowing protocols will gain the ability to accurately value custom assets as collateral, while risk management systems will benefit from reliable price data for liquidation mechanisms, all of which will be served by the familiar FTSO on-chain interface.
30+
This represents a significant expansion to the FTSO's core functionality, with substantial expansion in the amount and type of data the FTSO can support.
31+
As such, a governance vote is required due to the proposal’s far-reaching implications for the Flare network.
32+
33+
## 2. Technical Description
34+
35+
### 2.1 Overview
36+
37+
The implementation of Custom Feeds requires several technical modifications to the FTSO smart-contract system.
38+
These changes are designed to maintain backward compatibility while introducing new functionality.
39+
All modifications are visible on the public [Flare Smart Contracts GitHub](https://github.com/flare-foundation/flare-smart-contracts-v2).
40+
41+
Feed categories have been updated to use a composite classification system that combines a super-category with the existing feed type.
42+
The super-category differentiates between normal and custom feeds - normal feeds are assigned values in the range 0-31 (i.e. 0x00-0x1F), while custom feeds use values in the range 32-63 (i.e. 0x20-0x3F).
43+
Meanwhile, the existing type codes remain unchanged: 0 - none, 1 - crypto, 2 - FX, 3 - commodity, and 4 - stock.
44+
45+
Under this updated system, a normal crypto feed is classified as 1 (i.e. 0x01), whereas a custom crypto feed is classified as 33 (i.e. 0x21).
46+
To ensure a consistent user and developer experience, the legacy mechanism of querying feeds using their index will be deprecated.
47+
48+
### 2.2 Associated Risks
49+
50+
Custom Feeds will have a completely distinct risk profile compared to standard FTSO feeds.
51+
Unlike standard FTSO feeds, where every feed is backed by the entire network of data providers, the security of a Custom Feed is conditional on the logic defined in its smart contract.
52+
An example of how a smart contract can define the value of a Custom Feed is given in [Section 2.4](#24-example-implementation).
53+
54+
This change in risk profile requires users and developers integrating a Custom Feed in their application to carefully evaluate each Custom Feed on a per-feed basis, and assess how the security of the feed, in particular the smart-contract implementation of that feed, impacts their application’s security model.
55+
56+
### 2.3 Smart Contract Changes
57+
58+
#### 2.3.1 `FtsoV2Interface.sol`
59+
60+
The interface contract has been updated to support the new Custom Feeds functionality while removing legacy index-based methods that could create inconsistencies.
61+
62+
The following methods have been added:
63+
64+
* `getFtsoProtocolId`: Returns anchor feeds protocol ID.
65+
* `getSupportedFeedIds`: Returns a list of supported Feed IDs.
66+
* `getFeedIdChanges`: Returns a list of Feed ID changes.
67+
* `calculateFeeById`: Returns the fee for fetching a feed.
68+
* `calculateFeeByIds`: Returns the fee for fetching multiple feeds.
69+
70+
Several legacy methods have been deprecated to prevent potential inconsistencies with the new category of feeds:
71+
72+
* `getFeedByIndex`.
73+
* `getFeedsByIndex`.
74+
* `getFeedByIndexInWei`.
75+
* `getFeedsByIndexInWei`.
76+
* `getFeedIndex`.
77+
* `getFeedId`.
78+
79+
Moving forward the only way to query FTSO feeds will be using their Feed ID.
80+
For a list of all FTSO Feed IDs refer to the [Flare Developer Hub](https://dev.flare.network/ftso/feeds).
81+
82+
#### 2.3.2 `FtsoV2.sol`
83+
84+
The core FTSO contract has been enhanced to support Custom Feeds, alongside the following Governance methods being added:
85+
86+
* `addCustomFeeds`: Method to add new custom feed contracts.
87+
* `replaceCustomFeeds`: Method to replace custom feed contracts.
88+
* `removeCustomFeeds`: Method to remove custom feed contracts.
89+
90+
#### 2.3.3 `IICustomFeed.sol`
91+
92+
A new internal interface has been introduced to standardize the implementation of new Custom Feeds.
93+
An example of an implementation using this internal interface is given in the next section using Sceptre Staked Flare.
94+
95+
### 2.4 Example Implementation
96+
97+
The first Custom Feed added to FTSO is the price feed for [Sceptre Staked Flare](https://www.sceptre.fi/) (sFLR), implemented through the `SFlrCustomFeed.sol` contract.
98+
This feed was chosen due to its central importance to the Flare ecosystem, alongside serving as a base for developers looking to implement new Custom Feeds.
99+
100+
At a high-level the price of sFLR is calculated as:
101+
102+
```Price_sFLR = Price_FLR x getPooledFlrByShares
103+
```
104+
105+
where:
106+
107+
* `Price_sFLR`: Price of sFLR in USD.
108+
* `Price_FLR`: Current FLR price in USD sourced from FTSO.
109+
* `getPooledFlrByShares`: Sceptre's contract method calculating the ratio of sFLR to FLR, i.e. Total FLR locked in Sceptre / Total supply of sFLR.
110+
111+
The Sceptre smart contract can be inspected on the [Flare Explorer](https://flare-explorer.flare.network/token/0x12e605bc104e93B45e1aD99F9e555f659051c2BB), with additional analytics regarding sFLR available on the [Dune Dashboard](https://dune.com/insights4vc/sceptre).
112+
113+
### 2.5 Process to add new Custom Feeds
114+
115+
A request to add a new Custom Feeds can be made by raising a [New Feed Request Issue](https://github.com/flare-foundation/developer-hub/issues/new?template=feed_request.yml) on the [Flare Developer Hub GitHub](https://github.com/flare-foundation/developer-hub), explaining the business justification for the request alongside a link to the verified contract code of the Custom Feed on the Flare explorer.
116+
Once a request is raised, the Flare Foundation will determine eligibility after reviewing input from the data providers' [Management Group](./FIP_2.md) (MG).
117+
If significant concerns are raised, the request will be submitted for a vote within the MG group.
118+
119+
## 3. Links to Code Repositories and Contracts
120+
121+
* [Flare Smart Contracts](https://github.com/flare-foundation/flare-smart-contracts-v2)
122+
* [`FtsoV2.sol`](https://github.com/flare-foundation/flare-smart-contracts-v2/blob/v1.1.0-rc.0/contracts/protocol/implementation/FtsoV2.sol)
123+
* [`FtsoV2Interface.sol`](https://github.com/flare-foundation/flare-smart-contracts-v2/blob/v1.1.0-rc.0/contracts/userInterfaces/LTS/FtsoV2Interface.sol)
124+
* [`IICustomFeed.sol`](https://github.com/flare-foundation/flare-smart-contracts-v2/blob/v1.1.0-rc.0/contracts/customFeeds/interface/IICustomFeed.sol)
125+
* [`SFlrCustomFeed.sol`](https://github.com/flare-foundation/flare-smart-contracts-v2/blob/v1.1.0-rc.0/contracts/customFeeds/implementation/SFlrCustomFeed.sol)
126+
127+
## 4. Proposed Implementation Date Range
128+
129+
Implementation is expected to start shortly after the voting finishes.
130+
131+
## 5. Voting Details
132+
133+
To pass, the proposal requires a simple majority of votes in favor of it.
134+
135+
## 6. Deadline for Voting
136+
137+
* **Notice period**: 11-February-2025 to 16-February-2025
138+
* **Voting period**: 17-February-2025 to 23-February-2025

‎STP/STP_10.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
nav_order: 30010
3+
title: STP.10
4+
---
5+
6+
# STP.10: Add Custom Feeds to FTSO
7+
8+
| Type | Songbird Test Proposal |
9+
| :------------------ | :------------------------------------------ |
10+
| Author | Flare Foundation |
11+
| Created | 04-February-2025 |
12+
| Document Status | Draft |
13+
| Threshold Condition | 75% (required to reject) |
14+
| Majority Condition | 50% (required to reject) |
15+
16+
## 1. Brief Description
17+
18+
The Flare Time Series Oracle (FTSO) provides decentralized price feeds for the Flare network through a system of data providers who submit price data for various crypto assets.
19+
Currently, the FTSO only supports direct price feeds for assets that maintain significant trading volume on centralized exchanges.
20+
These feeds are supplied by Flare’s network of data providers.
21+
22+
However, the system has limited support for custom types of data feeds such as Liquid Staked Tokens (LSTs), Liquid Restaked Tokens (LRTs), and more generally, feeds of an arbitrary time-series nature.
23+
This proposal and its counterpart [FIP.13](../FIP/FIP_13.md) seek to extend the FTSO by implementing *Custom Feeds* - a new category of feeds that derive their values through custom logic encoded in on-chain smart contracts.
24+
25+
Custom Feeds will be made available through the same interface as FTSO’s block-latency feeds i.e. through the long-term support (LTS) `FtsoV2Interface` contract.
26+
Their implementation does not require any modification to the FTSO data provider client logic, nor to dApps integrating the FTSO.
27+
Furthermore, there is no token inflation allocated to Custom Feeds.
28+
29+
The implementation of Custom Feeds will significantly enhance DeFi capabilities across the Flare network.
30+
Lending and borrowing protocols will gain the ability to accurately value custom assets as collateral, while risk management systems will benefit from reliable price data for liquidation mechanisms, all of which will be served by the familiar FTSO on-chain interface.
31+
This represents a significant expansion to the FTSO's core functionality, with substantial expansion in the amount and type of data the FTSO can support.
32+
As such, a governance vote is required due to the proposal’s far-reaching implications for the Flare network.
33+
34+
## 2. Technical Description
35+
36+
### 2.1 Overview
37+
38+
The implementation of Custom Feeds requires several technical modifications to the FTSO smart-contract system.
39+
These changes are designed to maintain backward compatibility while introducing new functionality.
40+
All modifications are visible on the public [Flare Smart Contracts GitHub](https://github.com/flare-foundation/flare-smart-contracts-v2).
41+
42+
Feed categories have been updated to use a composite classification system that combines a super-category with the existing feed type.
43+
The super-category differentiates between normal and custom feeds - normal feeds are assigned values in the range 0-31 (i.e. 0x00-0x1F), while custom feeds use values in the range 32-63 (i.e. 0x20-0x3F).
44+
Meanwhile, the existing type codes remain unchanged: 0 - none, 1 - crypto, 2 - FX, 3 - commodity, and 4 - stock.
45+
46+
Under this updated system, a normal crypto feed is classified as 1 (i.e. 0x01), whereas a custom crypto feed is classified as 33 (i.e. 0x21).
47+
To ensure a consistent user and developer experience, the legacy mechanism of querying feeds using their index will be deprecated.
48+
49+
### 2.2 Associated Risks
50+
51+
Custom Feeds will have a completely distinct risk profile compared to standard FTSO feeds.
52+
Unlike standard FTSO feeds, where every feed is backed by the entire network of data providers, the security of a Custom Feed is conditional on the logic defined in its smart contract.
53+
54+
This change in risk profile requires users and developers integrating a Custom Feed in their application to carefully evaluate each Custom Feed on a per-feed basis, and assess how the security of the feed, in particular the smart-contract implementation of that feed, impacts their application’s security model.
55+
56+
### 2.3 Smart Contract Changes
57+
58+
#### 2.3.1 `FtsoV2Interface.sol`
59+
60+
The interface contract has been updated to support the new Custom Feeds functionality while removing legacy index-based methods that could create inconsistencies.
61+
62+
The following methods have been added:
63+
64+
* `getFtsoProtocolId`: Returns anchor feeds protocol ID.
65+
* `getSupportedFeedIds`: Returns a list of supported Feed IDs.
66+
* `getFeedIdChanges`: Returns a list of Feed ID changes.
67+
* `calculateFeeById`: Returns the fee for fetching a feed.
68+
* `calculateFeeByIds`: Returns the fee for fetching multiple feeds.
69+
70+
Several legacy methods have been deprecated to prevent potential inconsistencies with the new category of feeds:
71+
72+
* `getFeedByIndex`.
73+
* `getFeedsByIndex`.
74+
* `getFeedByIndexInWei`.
75+
* `getFeedsByIndexInWei`.
76+
* `getFeedIndex`.
77+
* `getFeedId`.
78+
79+
Moving forward the only way to query FTSO feeds will be using their Feed ID.
80+
For a list of all FTSO Feed IDs refer to the [Flare Developer Hub](https://dev.flare.network/ftso/feeds).
81+
82+
#### 2.3.2 `FtsoV2.sol`
83+
84+
The core FTSO contract has been enhanced to support Custom Feeds, alongside the following Governance methods being added:
85+
86+
* `addCustomFeeds`: Method to add new custom feed contracts.
87+
* `replaceCustomFeeds`: Method to replace custom feed contracts.
88+
* `removeCustomFeeds`: Method to remove custom feed contracts.
89+
90+
#### 2.3.3 `IICustomFeed.sol`
91+
92+
A new internal interface has been introduced to standardize the implementation of new Custom Feeds.
93+
An example of an implementation using this internal interface is given in the next section using Sceptre Staked Flare.
94+
95+
### 2.4 Example Implementation
96+
97+
An example implementation of a custom feed is available in the `SFlrCustomFeed.sol` contract for [Sceptre Staked Flare](https://www.sceptre.fi/) (sFLR).
98+
99+
### 2.5 Process to add new Custom Feeds
100+
101+
A request to add a new Custom Feeds can be made by raising a [New Feed Request Issue](https://github.com/flare-foundation/developer-hub/issues/new?template=feed_request.yml) on the [Flare Developer Hub GitHub](https://github.com/flare-foundation/developer-hub), explaining the business justification for the request alongside a link to the verified contract code of the Custom Feed on the Flare explorer.
102+
Once a request is raised, the Flare Foundation will determine eligibility after reviewing input from the data providers' [Management Group](./STP_3.html) (MG).
103+
If significant concerns are raised, the request will be submitted for a vote within the MG group.
104+
105+
## 3. Links to Code Repositories and Contracts
106+
107+
* [Flare Smart Contracts](https://github.com/flare-foundation/flare-smart-contracts-v2)
108+
* [`FtsoV2.sol`](https://github.com/flare-foundation/flare-smart-contracts-v2/blob/v1.1.0-rc.0/contracts/protocol/implementation/FtsoV2.sol)
109+
* [`FtsoV2Interface.sol`](https://github.com/flare-foundation/flare-smart-contracts-v2/blob/v1.1.0-rc.0/contracts/userInterfaces/LTS/FtsoV2Interface.sol)
110+
* [`IICustomFeed.sol`](https://github.com/flare-foundation/flare-smart-contracts-v2/blob/v1.1.0-rc.0/contracts/customFeeds/interface/IICustomFeed.sol)
111+
* [`SFlrCustomFeed.sol`](https://github.com/flare-foundation/flare-smart-contracts-v2/blob/v1.1.0-rc.0/contracts/customFeeds/implementation/SFlrCustomFeed.sol)
112+
113+
## 4. Proposed Implementation Date Range
114+
115+
Implementation is expected to start shortly after the voting finishes.
116+
117+
## 5. Voting Details
118+
119+
An STP is rejection-based, meaning that it is accepted unless certain conditions are met, namely, that the quorum threshold (75%) is reached and at least half of the votes are against it.
120+
(See [Governance](https://docs.flare.network/tech/governance/#stps).)
121+
122+
## 6. Deadline for Voting
123+
124+
* **Notice period**: 11-February-2025 to 16-February-2025
125+
* **Voting period**: 17-February-2025 to 23-February-2025

‎index.markdown‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Proposals aimed at improving the Flare network.
3030
| 10 | [Add an Incentive Structure for Participating in All Protocols](FIP/FIP_10.md) |
3131
| 11 | [Optimize Rewarding Structure and Adjust Protocol Parameters](FIP/FIP_11.md) |
3232
| 12 | [Add Support for the Flare Data Connector](FIP/FIP_12.md) |
33+
| 13 | [Add Custom Feeds to FTSO](FIP/FIP_13.md) |
3334

3435
## Songbird Improvement Proposals (SIP)
3536

@@ -58,7 +59,8 @@ Proposals aimed at improving the Flare network by being tested first on the Song
5859
| 6 | [Add Support for the Flare Systems Protocol and FTSO Scaling](STP/STP_6.md) |
5960
| 7 | [Add Support for FTSO Fast Updates](STP/STP_7.md) |
6061
| 8 | [Update FTSO Data Feeds and Define Process to Add New Ones](STP/STP_8.md) |
61-
| 9 | [Add Support for the Flare Data Connector](STP/STP_9.md) |
62+
| 9 | [Add Support for the Flare Data Connector](STP/STP_9.md) |
63+
| 10 | [Add Custom Feeds to FTSO](STP/STP_10.md) |
6264

6365
<style>
6466
table thead tr th:first-child {

0 commit comments

Comments
 (0)