Cleaning up "How Pyth Works" docs (#92)

* cleaning up docs

* writing

* gr

* cleanup

Co-authored-by: Jayant Krishnamurthy <[email protected]>

Author: jayantk

Diff for: SUMMARY.md

@@ -9,30 +9,31 @@
 * [Pythnet Price Feeds](pythnet-price-feeds/pythnet-price-feeds.md)
   * [On-Demand Updates](pythnet-price-feeds/on-demand.md)
   * [Using Price Feeds](pythnet-price-feeds/best-practices.md)
-  * [Price Service](pythnet-price-feeds/price-service.md)
-  * [Pyth Cross-chain Batches](pythnet-price-feeds/cross-chain-batches.md)
   * [Pyth on EVM](pythnet-price-feeds/evm.md)
   * [Pyth on Aptos](pythnet-price-feeds/aptos.md)  
   * [Pyth on BAS Chains](pythnet-price-feeds/bas.md) 
   * [Pyth for Off-chain Apps](pythnet-price-feeds/off-chain.md)
+  * [Price Service](pythnet-price-feeds/price-service.md)
+  * [Price Feed Batches](pythnet-price-feeds/cross-chain-batches.md)  
 
 * [Publish Data](publishers/publish-data.md)
   * [Understanding Publishing Slots](publishers/understanding-publishing-slots.md)
   * [pyth-client Websocket API](publishers/pyth-client-websocket-api.md)
   * [Confidence Interval and Crypto Exchange Fees](publishers/confidence-interval-and-crypto-exchange-fees.md)
 
-* [How Pyth Works](how-pyth-works/how-pyth-works.md)
-  * [Design Overview](how-pyth-works/design-overview.md)
+* [How Pyth Works](how-pyth-works/design-overview.md)
   * [Pythnet](how-pyth-works/pythnet.md)
   * [Cross-chain](how-pyth-works/cross-chain.md)
-  * [Solana Account Structure](how-pyth-works/account-structure.md)
-  * [Product Metadata](how-pyth-works/product-metadata.md)
+  * [Oracle Program](how-pyth-works/oracle-program.md)
+  * [Account Structure](how-pyth-works/account-structure.md)
+  * [Product Metadata](how-pyth-works/product-metadata.md)  
   * [Price Aggregation](how-pyth-works/price-aggregation.md)
   * [EMA Price Aggregation](how-pyth-works/ema-price-aggregation.md)
-  * [Accounts](https://pyth.network/developers/accounts/)
-  * [Network Participants](how-pyth-works/network-participants.md)
-  * [Network Interactions](how-pyth-works/network-interactions.md)
-  * [Participant Incentives](how-pyth-works/participant-incentives.md)
+
+* [Whitepaper](whitepaper/whitepaper.md)
+  * [Network Participants](whitepaper/network-participants.md)
+  * [Network Interactions](whitepaper/network-interactions.md)
+  * [Participant Incentives](whitepaper/participant-incentives.md)
 
 * [Pyth Metrics](metrics/metrics.md)
   * [Pyth Dune Dashboard](metrics/dune-dashboard.md)

Diff for: how-pyth-works/account-structure.md

@@ -1,6 +1,6 @@
 # Solana Account Structure
 
-The Pyth price oracle manages a number of on-chain accounts. There are three different types of accounts:
+The Pyth oracle program manages a number of on-chain accounts. There are three different types of accounts:
 
 1. _Product accounts_ store metadata about a product, such as its symbol (e.g., "BTC/USD") and asset type.
 2. _Price accounts_ store the current price information for a particular product. This account has fields such as the current price, a confidence interval, an exponential moving average price, an exponential moving average confidence interval and whether or not a price is currently available.
@@ -10,7 +10,7 @@ The [Pyth Rust Client Library](https://github.com/pyth-network/pyth-client-rs) c
 
 **Product Accounts**
 
-Product accounts store metadata about a product. This metadata is represented as a set of reference attributes, stored as a list of text key/value pairs. Not all product accounts follow the same structure, for a comprehensive overview, visit the [Product Metadata page](product-metadata.md). For example, the product account for AAPL contains the following fields:
+Product accounts store metadata about a product. This metadata is represented as a set of reference attributes, stored as a list of text key/value pairs. Not all product accounts follow the same structure; for a comprehensive overview, visit the [Product Metadata page](product-metadata.md). For example, the product account for AAPL contains the following fields:
 
 ```
 product_account .. G89jkM5wFLpmnbvRbeePUumxsJyzoXaRfgBVjyx2CPzQ

Diff for: how-pyth-works/cross-chain.md

@@ -1,18 +1,12 @@
 # Cross-chain
 
-Pyth needs a cross-chain component to ferry prices on [Pythnet](pythnet.md) to target chains. Pyth Network uses a “pull” update model for target chain prices: instead of continually pushing updates to each target chain, users pull the prices on-chain when they are needed. This pull model is highly scalable and allows Pyth Network to deliver high-frequency price updates for a large number of products without overwhelming the transaction capacity of target chains (or incurring excessive gas fees).
-
-The diagram below shows how prices are delivered from Pythnet to target chains.
+Pyth uses a cross-chain mechanism to transfer prices from [Pythnet](pythnet.md) to target chains.
+The diagram below shows how prices are delivered from Pythnet to target chains:
 
 ![](<../.gitbook/assets/pythnet_schema.png>)
 
-Data providers publish their prices on Pythnet. The on-chain [aggregation program](price-aggregation.md) then aggregates prices for a feed to obtain the aggregate price and confidence. Next, the attester program regularly attests to the most recently observed Pyth prices and creates a Wormhole message to be sent to the Wormhole contract on Pythnet. The Wormhole guardians then observe the attestation message and create a signed VAA for the message.
+Data providers publish their prices on Pythnet. The on-chain [oracle program](oracle-program.md) then aggregates prices for a feed to obtain the aggregate price and confidence. Next, the attester program regularly attests to the most recently observed Pyth prices and creates a Wormhole message to be sent to the Wormhole contract on Pythnet. The Wormhole guardians then observe the attestation message and create a signed VAA for the message.
 
-The price service API continually listens to Wormhole for Pyth price update messages. It stores the latest update message in memory and exposes HTTP and websocket APIs for retrieving the latest update. (Anyone can run an instance of this webservice, but the Pyth Data Association runs a public instance for convenience.) When a user wants to use a Pyth price in a transaction, they retrieve the latest update message (a signed VAA) from the price service and submit it in their transaction. The target chain Pyth contract will verify the validity of the price update message and, if it is valid, store the new price in its on-chain storage.   
+The price service API continually listens to Wormhole for Pyth price update messages. It stores the latest update message in memory and exposes HTTP and websocket APIs for retrieving the latest update. (Anyone can run an instance of this webservice, but the Pyth Data Association runs a public instance for convenience.) When a user wants to use a Pyth price in a transaction, they retrieve the latest update message (a signed VAA) from the price service and submit it in their transaction. The target chain Pyth contract will verify the validity of the price update message and, if it is valid, store the new price in its on-chain storage. See [on-demand updates](pythnet-price-feeds/on-demand) for more details about this process.
 
 Finally, on-chain protocols integrate with the Pyth contract via a simple API that retrieves the current Pyth price from its on-chain storage. This API will return the current price as long as it has been updated sufficiently recently; this approach works because users will have updated the Pyth price earlier in the same transaction. Protocols can configure the recency threshold to suit their needs — e.g., latency sensitive applications can set a lower threshold than the default.
-
-
-
-
-

Diff for: how-pyth-works/design-overview.md

@@ -2,13 +2,20 @@
 
 Pyth is a protocol that allows market participants to publish pricing information on-chain for others to use. The protocol is an interaction between three parties:
 
-1. _Publishers_ submit pricing information to Pyth's on-chain program. Pyth has multiple data publishers for every product to improve the accuracy and robustness of the system. 
-2. Pyth's _on-chain program_ combines publishers' data to produce a single aggregate price and confidence interval.
-3. _Consumers_ read the price information produced by the on-chain program.
-
-Pyth's on-chain program runs simultaneously on both Solana mainnet and [Pythnet](pythnet.md).
-Pythnet is an appchain used to aggregate the prices delivered to all other blockchains.
-In both cases, the Pyth program maintains a number of different [Solana accounts](account-structure.md) that list the products on Pyth and their current price data.
-Publishers publish their price and confidence by interacting with the on-chain program on every slot. The program stores this information in its accounts.
+1. _Publishers_ submit pricing information to Pyth's oracle program. Pyth has multiple data publishers for every product to improve the accuracy and robustness of the system.
+2. Pyth's _oracle program_ combines publishers' data to produce a single aggregate price and confidence interval.
+3. _Consumers_ read the price information produced by the oracle program.
+
+Pyth's oracle program runs simultaneously on both Solana mainnet and [Pythnet](pythnet.md).
+Each instance of the program is responsible for its own set of price feeds.
+[Solana Price Feeds](../solana-price-feeds/solana-price-feeds.md) are available for use by Solana protocols.
+In this case, since the oracle program itself runs on Solana, the resulting prices are immediately available to consumers without requiring any additional work.
+[Pythnet Price Feeds](../pythnet-price-feeds/pythnet-price-feeds.md) are available on 12+ blockchains.
+The prices constructed on Pythnet are transferred [cross-chain](cross-chain.md) to reach consumers on these blockchains.
+
+In both cases, the critical component of the system is the [oracle program](oracle-program.md) that combines the data from each individual publisher.
+This program maintains a number of different [Solana accounts](account-structure.md) that list the products on Pyth and their current price data.
+Publishers publish their price and confidence by interacting with the oracle program on every slot.
+The program stores this information in its accounts.
 The first price update in a slot additionally triggers [price aggregation](price-aggregation.md), which combines the price data from the previous slot into a single aggregate price and confidence interval.
-This aggregate price is written to the Solana account where it is readable by other on- and off-chain programs (see [Solana Price Feeds](../solana-price-feeds/solana-price-feeds.md) or [Pythnet Price Feeds](../pythnet-price-feeds/pythnet-price-feeds.md) for how to use this data). 
+This aggregate price is written to the Solana account where it is readable by other on-chain programs and available for transmission to other blockchains.

Diff for: how-pyth-works/how-pyth-works.md

@@ -1,17 +0,0 @@
----
-description: >-
-  For more information, visit the Pyth whitepaper
-  https://pyth.network/whitepaper
----
-
-# How Pyth Works
-
-Growth in DeFi requires high-fidelity, time-sensitive, real-world data, direct from the source and made available on any L1 blockchain. Financial market data, however, is often accessible to only a limited set of institutions and users. Traditional markets typically maintain strict control over and access to both live and historical price feeds. Consequently, only a selected group of users has access to the most timely, accurate, and valuable information.
-
-The Pyth network is a next-generation oracle solution that aims to bring this valuable financial market data to the general public. The network does so by incentivizing market participants — trading firms, market makers, and exchanges — to share directly on-chain the price data collected as part of their existing operations. Pyth's data providers include some of the largest **traders**, **exchanges**, and **financial services** players who create unique high quality market data. This includes real world market data in **equities**, **fx, crypto, and metals with ambitions to scale across asset classes**. Data publishers include Jump Trading Group, [GTS](https://pythnetwork.medium.com/new-pyth-data-provider-gts-555c4d0e362b), Jane Street, Hudson River Trading, [LMAX](https://pythnetwork.medium.com/new-pyth-data-provider-lmax-dd05264d1a16), [Virtu](https://pythnetwork.medium.com/new-pyth-data-provider-virtu-financial-ed09143f44d5), [BSX](https://pythnetwork.medium.com/new-pyth-data-provider-the-bermuda-stock-exchange-ccf3c04bd430), [CTC](https://pythnetwork.medium.com/new-pyth-data-provider-chicago-trading-company-64a457340443), and [many more](https://pyth.network/publishers/).
-
-The network then aggregates this first-party price data (still on-chain) and makes it available for use by either on- or off-chain applications.
-
-End-users of Pyth data can elect to pay data fees to gain protection against a potential oracle failure. As data publishers must stake tokens in order to publish data for a product, the stake of at-fault publishers (if they make the aggregate price erroneous) will be used as a payout to those end-users voluntarily paying fees. Delegators choose which product (price feed) and a publisher to stake on top of in order to earn data fees (or lose their stake if the oracle is inaccurate due to publisher faults). Initially, 80% of the data fees will go to delegators while the remaining 20% will be shared among publishers — this, among other parameters, will be subject to change through a PYTH governance.
-
-The goal of the design and mechanics around the PYTH token aim to make the Pyth network self-sustaining and decentralized.

Diff for: how-pyth-works/oracle-program.md

@@ -0,0 +1,16 @@
+# Oracle Program
+
+The oracle program is responsible for several tasks:
+
+1. Maintaining the set of price feeds.
+2. Storing the contributions of data providers to each price feed.
+3. Combining the individual data providers' prices into a single aggregate price and confidence interval.
+4. Performing any additional stateful computations on the resulting price series, such as computing moving averages.
+
+The oracle solves these problems by maintaining a collection of [Solana accounts](account-structure.md) to represent the set of price feeds.
+Each feed has two accounts: a product account to store [metadata](product-metadata.md) and a price account.
+The price account stores a list of authorized data providers for this specific price feed, and allocates storage space for each data provider's price.
+The oracle program exposes an instruction called `upd_price` that enables an authorized data provider to update the price account with their current estimate of the price and confidence interval.
+Additionally, the first time that `upd_price` is called in a slot, it will [aggregate](price-aggregation.md) the individual data provider's prices into an aggregate price and confidence interval.
+Only the aggregate price and confidence are made available for use in downstream applications; the individual data providers prices are internal state of the oracle program.
+Finally, the oracle program computes an [exponentially-weighted moving average](ema-price-aggregation.md) of the oracle price.