Pythnet: Account Structure

The Pyth oracle program manages a number of on-chain accounts. There are 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 of the 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 available on Pyth.
3. Mapping accounts serve as a listing of other accounts. The mapping accounts are organized into a linked list whose values are set of product accounts. These accounts allow applications to enumerate the full list of products whose prices are available on Pyth.
The Pyth Rust SDK contains a sample application that prints the current content of all Pyth accounts. The following sectioons use the output of this application to bettter undestand the content of these accounts.

Product Accounts

Product accounts store metadata about a product.
This product 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.
For example, the product account for AAPL contains the following fields

product_account.... G89jkM5wFLpmnbvRbeePUumxsJyzoXaRfgBVjyx2CPzQ
    symbol......... Equity.US.AAPL/USD
    asset_type..... Equity
    quote_currency. USD
    description.... APPLE INC
    base........... AAPL
    country........ US
    cms_symbol..... AAPL
    cqs_symbol..... AAPL
    nasdaq_symbol.. AAPL
    price_account.. CqFJLrT4rSpA46RQkVYWn8tdBDuQ7p7RXcp6Um76oaph

This snippet shows the reference attributes for AAPL.
The set of available attributes depends on the asset_type.
Every product account has symbol. asset_type, quote_currency, and price_account.
US equity products additionally include reference symbology that is useful for mapping Pyth products to other industry-standard identifiers.
The product account also contains a pointer to a price account that contains the product's current pricing information.
As another example, here is the product account for BTC/USD

product_account.... 3m1y5h2uv7EQL3KaJZehvAJa4yDNvgc5yAdL9KPMKwvk    
    symbol......... Crypto.BTC/USD
    asset_type..... Crypto
    quote_currency. USD
    description.... BTC/USD
    generic_symbol. BTCUSD
    base........... BTC
    price_account.. HovQMDrbAgAYPCmHVSrezcSmkMtXSSUsLDFANExrZh2J

Price Accounts

Price accounts store the current price of the product along with additional useful information.
For example, consider the following content of AAPL's price account.

price_accoount...... 
    price...........
    conf............
    price_type......
    exponent........
    status..........
    corp_act........
    num_qt..........
    valid_slot......
    publish_slot....
    ema_price.......
    ema_confidence..

This account stores the current price in a fixed point format.
The price is computed by taking the price field and multiplying by 10^exponent.
The account also includes a confidence interval that represents Pyth's uncertainty about the current price.
This confidence interval can be interpreted as the standard deviation of a Laplace distribution centered around the price.
conf is also stored in the same fixed point format.
In the example above, the price is 12276250, and the conf is 1500 and the exponent is -5.
These values translate into the price of $122.76250 \pm 0.015$

Price accounts also include several other useful fields.
First, each account has a status that indicates whether or not the price is valid.
Pricing information for a product can be unavailable for various reasons, for example, US equity markets only trade during certain hours.
The status field indicates whether or not Pyth currently has the price of the product.
Only prices with a value of status=trading should be used
If the statuss is not trading but is Unknown, Halted or Auction, the Pyth price can be an arbitrary value.

Mapping Accounts

Mapping accounts serve as an index of the pricing information currently available on Pyth.
These accounts are organized into a linked list whose values are product accounts.
Applications can traverse this linked list to enumerate all products currently available on Pyth.


  -------------        -------------       -------------
  |           |1      m|           |       |           |
  |  mapping  |------->|  product  |------>|   price   |
  |           |        |           |       |           |
  -------------        -------------       -------------
        |
        V
  -------------
  |           |
  |  mapping  |
  |           |
  -------------
        |
        V
       ...

Each mapping account contains a list of product account ids, plus an optional pointer to the subsequent mapping account.
Each product account in turn points to the price account that stores the current price information about the product.