Merge pull request #3044 from pyth-network/ois

chore(developer-hub): Oracle Integrity Staking(OIS) section

Author: nidhi-singh02

apps/developer-hub/content/docs/meta.json

@@ -2,6 +2,7 @@
   "pages": [
     "pyth-core",
     "pyth-token",
+    "oracle-integrity-staking",
     "express-relay",
     "entropy",
     "metrics",

apps/developer-hub/content/docs/oracle-integrity-staking/index.mdx

@@ -0,0 +1,43 @@
+---
+title: "Oracle Integrity Staking (OIS)"
+description: >-
+  Oracle Integrity Staking enhances Pyth Price Feeds with decentralized staking 
+  rewards and slashing mechanisms to improve data source accountability.
+full: false
+index: true
+---
+
+This document outlines the design principles and implementation details of the [Oracle Integrity Staking (OIS)](https://staking.pyth.network/) protocol.
+
+## Design Principles
+
+OIS's economic design focuses on awarding and penalizing stakers over the primary dimension of data accuracy.
+
+Stakers are incentivized to help maintain data quality by receiving rewards from an open-ended pool. However, they also face the risk of having their stake slashed as a penalty for failing to maintain data accuracy.
+
+The core design principles behind OIS include the following:
+
+- Oracle Integrity Staking secures all current and future price feeds produced by the Pyth Network.
+- Data Publishers are individually responsible for data accuracy.
+- Rewards and penalties are proportionate to the stake assigned to each publisher. Delegators share the risks and rewards of the publisher(s) to whom they assign their stake.
+- A higher number of publishers for each price feed contributes positively to the security of such feed.
+- Staking for **OIS** is complementary to staking for **governance**, and eligible $PYTH tokens can be used for both purposes.
+- The ability to slash stake in OIS requires **unlocked** \$PYTH tokens, whereas staking for governance can use both locked and unlocked $PYTH tokens.
+- All parameter related to the OIS protocol are subject to the governance of the Pyth DAO.
+
+## Implementation
+
+OIS implements the design principles above through the following structure:
+
+1. OIS is subject to the same 7-day epoch as governance voting. All parameters used in the OIS protocol are captured at each start of the epoch on Thursdays at 0:00 UTC and remain constant until the end of the epoch. Staking into OIS is also subject to warmup and cooldown period prior and post epoch respectively.
+
+2. Each publisher is programmatically assigned a staking pool where they can self-stake and to which other stakers can delegate.
+   - The staking pool assigned to each publisher covers all price feeds/symbols they publish.
+   - Each staking pool has a soft cap. This soft cap dynamically expands and shrinks given the number of symbols published by the assigned publisher.
+   - Price feeds with a low number of publishers contribute more to the cap's expansion.
+   - Staking into the pool can exceed the soft cap. However no rewards are paid for the excess amount. On the contrary, the excess amount is subject to the penalty if the assigned publisher's data is inaccurate.
+   - The OIS protocol prioritizes self-stake attributed to the **publisher's stake** when distributing rewards to the publisher's pool.
+   - All staking pools charge the same delegation fee for stakers who are delegating stake to one or many pools.
+3. Each pool has a maximum reward rate per epoch, which applies only to the staked amount within the soft cap.
+4. The total amount of rewards paid to all pools is bound by the same cap relative to the amount of rewards available to the OIS protocol.
+5. Slashing of stake has a hard percentage cap and only impacts pools that assigned to publishers responsible for the poor data quality. Both self-stakers and delegators are also slashed proportionally to their staked amount in the impacted pools.

apps/developer-hub/content/docs/oracle-integrity-staking/mathematical-representation.mdx

@@ -0,0 +1,96 @@
+---
+title: "Mathematical Representation"
+description: >-
+  This section outlines the mathematical representation of the Oracle Integrity Staking (OIS) protocol.
+---
+
+As explained in the [implementation](../oracle-integrity-staking#implementation) section, every publisher is assigned a staking pool where they can self-stake and to which other stakers can delegate.
+
+## Pool Cap
+
+The **pool cap** is calculated as follows:
+
+$$
+\large{\text{Pool Cap}: {\bold{C_p}} = M \cdot \sum_{s \in \text{Symbols}_p} \frac{1}{\max(n_s, Z)}}
+$$
+
+Where:
+
+- $M$ is a constant parameter representing the target stake per symbol.
+- $\text{Symbols}_p$ is the set of symbols published by the publisher $p$.
+- $n_s$ be the number of publishers for symbol $s$.
+- $Z$ is a constant parameter to control cap contribution from symbols with a low number of publishers.
+
+This formula ensures that symbols with a lower number of publishers contribute more to the overall cap, while symbols with a higher number of publishers contribute less. This is because the contribution of each symbol is inversely proportional to the number of publishers (or Z, whichever is larger).
+
+## Reward
+
+The reward $R_p$ distributed to each pool is calculated as follows:
+
+$$
+\large{\bold{R_p} = y \cdot \min(S_p, C_p)}
+$$
+
+Where:
+
+- $y$ is the cap to the rate of rewards for any pool
+- $S_p$ be the stake assigned to the publisher p pool , made of self-staked amount $S^{p}_{p}$ and delegated stake $S^{d}_{p}$ , or $S_{p} = S^{p}_{p} + S^{d}_{p}$.
+- $C_p$ be the stake cap for the pool assigned to publisher p.
+
+The total amount of rewards distributed to all pools is bound by the same cap relative to the amount of rewards available to the OIS protocol.
+
+$$
+\large{\sum_{p \in \text{Publishers}} R_p \leq y \cdot \min(N \cdot M, \sum_{p=1}^{P} S_p)}
+$$
+
+Where:
+
+- $N$ is the total number of symbols in the system.
+- $P$ is the total number of publishers in the system.
+
+Whereas the reward component relative to the amount self-staked by the publisher $p$ is defined as:
+
+$$
+\large{\bold{R^{p}_{p}} = y \cdot \min(S^p_p, C_p) = R_p - R^d_p}
+$$
+
+Where:
+
+- $R^d_p$ is the reward component relative to the amount delegated to the publisher $p$.
+
+## Slashing
+
+Slashing is an important aspect of the OIS protocol to ensure the integrity of the system.
+
+The slashed amount for each pool is calculated as follows:
+
+$$
+\large{\bold{SL_p} = w \cdot S_p = w \cdot (S^{p}_{p} + S^{d}_{p})}
+$$
+
+Where:
+
+- $SL_p$ is the slashed amount for the publisher $p$ pool.
+- $w$ is the slashing rate.
+- $S_p$ is the stake assigned to the publisher $p$ pool , made of self-staked amount $S^{p}_{p}$ and delegated stake $S^{d}_{p}$ , or $S_{p} = S^{p}_{p} + S^{d}_{p}$.
+
+Here $SL_p$ is uniformly allocated to both the self-staking publisher and delegators in the pool, pro-rata to their respective stake.
+
+Subsequently, the rewards received by a publisher and delegators into a pool, net of any slashed amounts can be expressed as below:
+
+$$
+\large{\bold{\Pi^p_p} = ( R^p_p + f \cdot R^d_p ) - w \cdot S^p_p}
+$$
+
+$$
+\large{\bold{\Pi^d_p} = R^d_p - ( f \cdot R^d_p + w \cdot S^d_p )}
+$$
+
+Where:
+
+- $\Pi^p_p$ is the net reward received by the publisher $p$ after slashing.
+- $\Pi^d_p$ is the net reward received by the delegators after slashing.
+- $f$ is the delegation fee charged by the pool.
+- $w$ is the slashing rate.
+- $S^p_p$ is the amount self-staked by the publisher $p$.
+- $S^d_p$ is the amount delegated to the publisher $p$.

apps/developer-hub/content/docs/oracle-integrity-staking/meta.json

@@ -0,0 +1,13 @@
+{
+  "root": true,
+  "title": "Oracle Integrity Staking",
+  "description": "Decentralized staking rewards and slashing mechanisms for data accuracy",
+  "icon": "Shield",
+  "pages": [
+    "index",
+    "mathematical-representation",
+    "reward-examples",
+    "slashing-rulebook",
+    "publisher-quality-ranking"
+  ]
+}

apps/developer-hub/content/docs/oracle-integrity-staking/publisher-quality-ranking.mdx

@@ -0,0 +1,116 @@
+---
+title: "Publisher Quality Ranking"
+description: >-
+  This document introduces a quality ranking system to ensure high-quality pricing data on Pythnet.
+---
+
+The ranking system will use **three** metrics to evaluate each publisher's performance:
+
+- Uptime (40% weight),
+- Price Deviation (40% weight),
+- Lack of Stalled Prices (20% weight).
+
+The ranking will be calculated **monthly** to ensure that only the top-performing publishers remain permissioned for each price feed on Pythnet.
+
+**Important: Publishers with an uptime of at least 50% will be included in the ranking. If a publisher's uptime is less than 50%, then the deviation and the stalled score of the publisher will be 0 to reflect their ineligibility.**
+
+Publishers in Pythtest conformance who are not publishing on Pythnet and pass this uptime condition will also be ranked together with the Pythnet publishers for each symbol.
+
+Checkout [Publisher Rankings](https://www.pyth.network/publishers/ranking) on the main website to see the updated rank of the publishers.
+
+## Metrics Used for Ranking
+
+The three metrics used for ranking are:
+
+### Uptime
+
+This metric measures the percentage of time a publisher is available and actively publishing data. A higher numerical score indicates a higher uptime maintained for the price feed. Score range: **0-1**.
+
+### Price Deviation
+
+This metric measures deviations that occur between a publishers' price and the aggregate price, normalized by the aggregate confidence interval. A higher numerical score indicates a lower degree of price deviation. Score range: **0-1**.
+
+### Lack of Stalled Prices
+
+This metric penalizes publishers reporting the same value for the price of an asset for at least 100 consecutive slots because such instances indicate potential data staleness. Publishers with fewer stalled prices will get a higher score. Score range: **0-1**.
+
+## Ranking Algorithm
+
+Each metric is assigned a weight as mentioned above, and the score for each metric is calculated based on the publisher's performance.
+The scores from each metrics are aggregated with respect to their weights to get the final score for each publisher.
+The weight distribution is as follows:
+
+- Uptime: 40%
+- Price Deviation: 40%
+- Lack of Stalled Prices: 20%
+
+Publishers are then sorted based on their final scores with the highest score indicating the best performance.
+As mentioned earlier, the score for each metric range from 0 to 1, where 1 represents the best performance.
+Each publisher will also be assigned a rank based on their final scores, where lower ranks are assigned to publishers with higher scores indicating better performance.
+
+## Metric Calculations
+
+This section provides a detailed breakdown of how each metric is calculated.
+
+### Uptime
+
+Uptime measures a publisher's reliability and availability. If a publisher consistently provides data without interruptions, it indicates a high level of reliability. This is aligned with the current conformance testing, which checks the publisher's availability based on price publication within the number of slots as defined on each feed's "Max Slot Latency" which is available on each feed's web page and within each feed's metadata.
+
+$$
+\text{Score}_{\text{Uptime}} = \frac{\text{Publisher Slot Count}}{\text{Aggregate Slot Count}}
+$$
+
+Uptime is given **40% weight** in the final ranking.
+
+**Reason for Weight:** Uptime is the most critical metric because consistent data availability is fundamental for ensuring a data feed's overall quality and reliability. A publisher that is frequently unable to publish for every set number of slots or unavailable would significantly disrupt the service, hence the high weight of 40%.
+
+### Price Deviation
+
+This metric evaluates the deviations between the publisher's price and the aggregate price, normalized by the aggregate's confidence interval.
+
+$$
+\text{Penalty}_{\text{Deviation}} =
+\frac{1}{N} \sum_{i=1}^{N} \left( \frac{|P_i - A_i|}{{CI}_i} \right)^2
+$$
+
+$$
+\text{Score}_{\text{Deviation}} = \frac{{\text{NumPublishers}}-{\text{Rank}}(\text{Penalty}_\text{Deviation}) + 1}{\text{NumPublishers}}
+$$
+
+Where:
+
+- $N$ is the total number of prices
+- $P_i$ is the publisher's price at instance $i$
+- $A_i$ is the aggregate price at instance $i$
+- ${CI}_i$ is the aggregate confidence interval at instance $i$
+
+It is calculated similarly to a z-score, where the aggregate price $A_i$ is the mean, and the aggregate confidence interval $CI_i$ is the Standard Deviation. A higher deviation score indicates that the publisher's prices are significantly inconsistent with the aggregate prices, especially when these deviations exceed the confidence interval. The $\text{Score}_{\text{Deviation}}$ is calculated by ranking the $\text{Penalty}_{\text{Deviation}}$ among all publishers and expressing this rank as a percentage of the total number of publishers.
+
+Price deviation is given **40% weight** in the final ranking.
+
+**Reason for Weight:** To maintain trust in the data published on a feed, it is crucial to ensure that reported prices are within a reasonable range of the aggregate price when adjusted for confidence intervals. Significant inconsistencies can undermine confidence in the published data, hence the weight of 40%.
+
+### Lack of Stalled Prices
+
+This metric checks if the publisher is reporting the same price continuously for a specified duration. Repeated prices over an extended period can indicate data staleness or a problem with the data feed.
+
+$$
+\text{Penalty}_{\text{Stalled}} =  \frac{1}{N} \sum_{i=T+1}^{N} \mathbf{1} \left( P_i = P_{i-1} = \cdots = P_{i-T} \right)
+$$
+
+$$
+\text{Score}_{\text{Stalled}} = \max \left((1 -  \text{Penalty}_{\text{Stalled}} \times 10) , 0\right)
+$$
+
+Where:
+
+- $N$ is the total number of slots for the aggregate price.
+- $T$ is the duration threshold for staleness in slot. The threshold is $100$ slots (or about $40$ seconds) for all the symbols but can change in the future on a per-symbol basis.
+- $P_i$ is the price reported by the publisher at time $i$.
+- $\mathbf{1}(\cdot)$ is an indicator function that returns 1 if the condition inside it is true and 0 otherwise.
+- $\text{Penalty}_{\text{Stalled}}$ calculates the fraction of time periods where the price remains unchanged for T consecutive intervals.
+- $\text{Score}_{\text{Stalled}} $ adjusts the raw stalled penalty multiplied by $10$ to a score out of 1, which penalizes higher staleness rates. It means that if a publisher publishes stalled prices more than 10% of the times, it will get the score of 0.
+
+This metric is given **20% weight** in the final ranking.
+
+**Reason for Weight:** Staleness in data can mislead users into thinking the market conditions are unchanged, which can be detrimental in volatile market conditions. While important, measuring data staleness is deemed relatively less critical than evaluating uptime and price accuracy, hence a weight of 20%.