Add aggregate_price_status which takes care of becoming stale (#21)

Adds `aggregate_price_status` property in Price Account which returns the aggregate price status considering the latest fetch slot to make sure price is not stale. `get_aggregate_price_status_with_slot` is also added so users can give latest solana slot for checking that price is not stale.

Additional Changes:
- Price Info `slot` field is renamed to `pub_slot`: `slot` is used in other objects within the pyth client with a different meaning (fetch slot). `pub_slot` is also consistent with other clients.
- `aggregate_price` and `aggregate_price_confidence_interval` will use status and return None if price is not available (status != trading). Comments have been added to guide how to get these values if needed regardless of availability. This is more consistent with our Rust client api and will prevent incautious users to rely on price if it's not available. 
- In solana module `get_commitment_slot` is renamed to `get_slot` to be more consistent with the rest of its interface. Also the return type is updated.
- Also fixes a small bug in dump example by indenting back the `break` on ws update handling logic.

Author: ali-behjati

README.md

@@ -16,7 +16,7 @@ Install the library:
 
 You can then read the current Pyth price using the following:
 
-```
+```python
 from pythclient.pythclient import PythClient
 from pythclient.pythaccounts import PythPriceAccount
 from pythclient.utils import get_key
@@ -34,6 +34,7 @@ async with PythClient(
         for _, pr in prices.items():
             print(
                 pr.price_type,
+                pr.aggregate_price_status,
                 pr.aggregate_price,
                 "p/m",
                 pr.aggregate_price_confidence_interval,
@@ -44,11 +45,11 @@ This code snippet lists the products on pyth and the price for each product. Sam
 
 ```
 {'symbol': 'Crypto.ETH/USD', 'asset_type': 'Crypto', 'quote_currency': 'USD', 'description': 'ETH/USD', 'generic_symbol': 'ETHUSD', 'base': 'ETH'}
-PythPriceType.PRICE 4390.286 p/m 2.4331
+PythPriceType.PRICE PythPriceStatus.TRADING 4390.286 p/m 2.4331
 {'symbol': 'Crypto.SOL/USD', 'asset_type': 'Crypto', 'quote_currency': 'USD', 'description': 'SOL/USD', 'generic_symbol': 'SOLUSD', 'base': 'SOL'}
-PythPriceType.PRICE 192.27550000000002 p/m 0.0485
+PythPriceType.PRICE PythPriceStatus.TRADING 192.27550000000002 p/m 0.0485
 {'symbol': 'Crypto.SRM/USD', 'asset_type': 'Crypto', 'quote_currency': 'USD', 'description': 'SRM/USD', 'generic_symbol': 'SRMUSD', 'base': 'SRM'}
-PythPriceType.PRICE 4.23125 p/m 0.0019500000000000001
+PythPriceType.PRICE PythPriceStatus.UNKNOWN None p/m None
 ...
 ```
 

examples/dump.py

@@ -54,6 +54,7 @@ async def main():
                     pr.key,
                     pr.product_account_key,
                     pr.price_type,
+                    pr.aggregate_price_status,
                     pr.aggregate_price,
                     "p/m",
                     pr.aggregate_price_confidence_interval,
@@ -86,11 +87,12 @@ async def main():
                         print(
                             pr.product.symbol,
                             pr.price_type,
+                            pr.aggregate_price_status,
                             pr.aggregate_price,
                             "p/m",
                             pr.aggregate_price_confidence_interval,
                         )
-                        break
+                    break
 
         print("Unsubscribing...")
         if use_program:

examples/read_one_price_feed.py

@@ -2,7 +2,7 @@
 
 import asyncio
 
-from pythclient.pythaccounts import PythPriceAccount
+from pythclient.pythaccounts import PythPriceAccount, PythPriceStatus
 from pythclient.solana import SolanaClient, SolanaPublicKey, SOLANA_DEVNET_HTTP_ENDPOINT, SOLANA_DEVNET_WS_ENDPOINT
 
 async def get_price():
@@ -12,7 +12,14 @@ async def get_price():
     price: PythPriceAccount = PythPriceAccount(account_key, solana_client)
 
     await price.update()
-    # Sample output: "DOGE/USD is 0.141455 ± 7.4e-05"
-    print("DOGE/USD is", price.aggregate_price, "±", price.aggregate_price_confidence_interval)
+
+    price_status = price.aggregate_price_status
+    if price_status == PythPriceStatus.TRADING:
+        # Sample output: "DOGE/USD is 0.141455 ± 7.4e-05"
+        print("DOGE/USD is", price.aggregate_price, "±", price.aggregate_price_confidence_interval)
+    else:
+        print("Price is not valid now. Status is", price_status)
+
+    await solana_client.close()
 
 asyncio.run(get_price())

pythclient/pythaccounts.py

@@ -17,6 +17,7 @@
 _SUPPORTED_VERSIONS = set((_VERSION_1, _VERSION_2))
 _ACCOUNT_HEADER_BYTES = 16  # magic + version + type + size, u32 * 4
 _NULL_KEY_BYTES = b'\x00' * SolanaPublicKey.LENGTH
+MAX_SLOT_DIFFERENCE = 25
 
 
 class PythAccountType(Enum):
@@ -364,7 +365,7 @@ class PythPriceInfo:
         price (int): the price
         confidence_interval (int): the price confidence interval
         price_status (PythPriceStatus): the price status
-        slot (int): the slot time this price information was published
+        pub_slot (int): the slot time this price information was published
         exponent (int): the power-of-10 order of the price
     """
 
@@ -373,7 +374,7 @@ class PythPriceInfo:
     raw_price: int
     raw_confidence_interval: int
     price_status: PythPriceStatus
-    slot: int
+    pub_slot: int
     exponent: int
 
     price: float = field(init=False)
@@ -397,9 +398,9 @@ def deserialise(buffer: bytes, offset: int = 0, *, exponent: int) -> PythPriceIn
             slot (u64)
         """
         # _ is corporate_action
-        price, confidence_interval, price_status, _, slot = struct.unpack_from(
+        price, confidence_interval, price_status, _, pub_slot = struct.unpack_from(
             "<qQIIQ", buffer, offset)
-        return PythPriceInfo(price, confidence_interval, PythPriceStatus(price_status), slot, exponent)
+        return PythPriceInfo(price, confidence_interval, PythPriceStatus(price_status), pub_slot, exponent)
 
     def __str__(self) -> str:
         return f"PythPriceInfo status {self.price_status} price {self.price}"
@@ -472,7 +473,7 @@ class PythPriceAccount(PythAccount):
         aggregate_price_info (PythPriceInfo): the aggregate price information
         price_components (List[PythPriceComponent]): the price components that the
             aggregate price is composed of
-        slot (int): the slot time when this account was last updated
+        slot (int): the slot time when this account was last fetched
         product (Optional[PythProductAccount]): the product this price is for, if loaded
     """
 
@@ -493,13 +494,41 @@ def __init__(self, key: SolanaPublicKey, solana: SolanaClient, *, product: Optio
 
     @property
     def aggregate_price(self) -> Optional[float]:
-        """the aggregate price"""
-        return self.aggregate_price_info and self.aggregate_price_info.price
+        """
+        The aggregate price. Returns None if price is not currently available.
+        If you need the price value regardless of availability use `aggregate_price_info.price`
+        """
+        if self.aggregate_price_status == PythPriceStatus.TRADING:
+            return self.aggregate_price_info.price
+        else:
+            return None
 
     @property
     def aggregate_price_confidence_interval(self) -> Optional[float]:
-        """the aggregate price confidence interval"""
-        return self.aggregate_price_info and self.aggregate_price_info.confidence_interval
+        """
+        The aggregate price confidence interval. Returns None if price is not currently available.
+        If you need the confidence value regardless of availability use `aggregate_price_info.confidence_interval`
+        """
+        if self.aggregate_price_status == PythPriceStatus.TRADING:
+            return self.aggregate_price_info.confidence_interval
+        else:
+            return None
+    
+    @property
+    def aggregate_price_status(self) -> Optional[PythPriceStatus]:
+        """The aggregate price status."""
+        return self.get_aggregate_price_status_with_slot(self.slot)
+
+    def get_aggregate_price_status_with_slot(self, slot: int) -> Optional[PythPriceStatus]:
+        """
+        Gets the aggregate price status given a solana slot.
+        You might consider using this function with the latest solana slot to make sure the price has not gone stale.
+        """
+        if self.aggregate_price_info.price_status == PythPriceStatus.TRADING and \
+            slot - self.aggregate_price_info.pub_slot > MAX_SLOT_DIFFERENCE:
+            return PythPriceStatus.UNKNOWN
+
+        return self.aggregate_price_info.price_status
 
     def update_from(self, buffer: bytes, *, version: int, offset: int = 0) -> None:
         """

pythclient/solana.py

@@ -286,10 +286,10 @@ async def get_health(self) -> Union[Literal['ok'], Dict[str, Any]]:
     async def get_cluster_nodes(self) -> List[Dict[str, Any]]:
         return await self.http_send("getClusterNodes")
 
-    async def get_commitment_slot(
+    async def get_slot(
         self,
-        commitment: str
-        ) -> Dict[str, Any]:
+        commitment: str = SolanaCommitment.CONFIRMED,
+        ) -> Union[int, Dict[str, Any]]:
         return await self.http_send(
             "getSlot",
             [{"commitment": commitment}]

tests/test_price_account.py

@@ -3,6 +3,7 @@
 from dataclasses import asdict
 
 from pythclient.pythaccounts import (
+    MAX_SLOT_DIFFERENCE,
     PythPriceAccount,
     PythPriceType,
     PythPriceStatus,
@@ -55,15 +56,13 @@ def price_account_bytes():
         b'AAABAAAAAAAAANipUgYAAAAAn4M0eBAAAABh7UgCAAAAAAEAAAAAAAAA2alSBgAAAAA='
     ))
 
-
 @pytest.fixture
 def price_account(solana_client: SolanaClient) -> PythPriceAccount:
     return PythPriceAccount(
         key=SolanaPublicKey("5ALDzwcRJfSyGdGyhP3kP628aqBNHZzLuVww7o9kdspe"),
         solana=solana_client,
     )
 
-
 def test_price_account_update_from(price_account_bytes: bytes, price_account: PythPriceAccount):
     price_account.update_from(buffer=price_account_bytes, version=2, offset=0)
 
@@ -81,7 +80,7 @@ def test_price_account_update_from(price_account_bytes: bytes, price_account: Py
         "raw_price": 70712500000,
         "raw_confidence_interval": 36630500,
         "price_status": PythPriceStatus.TRADING,
-        "slot": 106080731,
+        "pub_slot": 106080731,
         "exponent": -8,
         "price": 707.125,
         "confidence_interval": 0.366305,
@@ -95,7 +94,7 @@ def test_price_account_update_from(price_account_bytes: bytes, price_account: Py
             "raw_price": 70709500000,
             "raw_confidence_interval": 21500000,
             "price_status": PythPriceStatus.TRADING,
-            "slot": 106080728,
+            "pub_slot": 106080728,
             "exponent": -8,
             "price": 707.095,
             "confidence_interval": 0.215,
@@ -104,7 +103,7 @@ def test_price_account_update_from(price_account_bytes: bytes, price_account: Py
             "raw_price": 70709500000,
             "raw_confidence_interval": 21500000,
             "price_status": PythPriceStatus.TRADING,
-            "slot": 106080729,
+            "pub_slot": 106080729,
             "exponent": -8,
             "price": 707.095,
             "confidence_interval": 0.215,
@@ -141,11 +140,41 @@ def test_price_account_agregate_conf_interval(
     price_account_bytes: bytes, price_account: PythPriceAccount,
 ):
     price_account.update_from(buffer=price_account_bytes, version=2, offset=0)
+    price_account.slot = price_account.aggregate_price_info.pub_slot
     assert price_account.aggregate_price_confidence_interval == 0.366305
 
 
 def test_price_account_agregate_price(
     price_account_bytes: bytes, price_account: PythPriceAccount,
 ):
     price_account.update_from(buffer=price_account_bytes, version=2, offset=0)
+    price_account.slot = price_account.aggregate_price_info.pub_slot
     assert price_account.aggregate_price == 707.125
+
+def test_price_account_unknown_status(
+    price_account_bytes: bytes, price_account: PythPriceAccount,
+):
+    price_account.update_from(buffer=price_account_bytes, version=2, offset=0)
+    price_account.slot = price_account.aggregate_price_info.pub_slot
+    price_account.aggregate_price_info.price_status = PythPriceStatus.UNKNOWN
+
+    assert price_account.aggregate_price is None
+    assert price_account.aggregate_price_confidence_interval is None
+
+def test_price_account_get_aggregate_price_status_still_trading(
+    price_account_bytes: bytes, price_account: PythPriceAccount
+):
+    price_account.update_from(buffer=price_account_bytes, version=2, offset=0)
+    price_account.slot = price_account.aggregate_price_info.pub_slot + MAX_SLOT_DIFFERENCE
+
+    price_status = price_account.aggregate_price_status
+    assert price_status == PythPriceStatus.TRADING
+
+def test_price_account_get_aggregate_price_status_got_stale(
+    price_account_bytes: bytes, price_account: PythPriceAccount
+):
+    price_account.update_from(buffer=price_account_bytes, version=2, offset=0)
+    price_account.slot = price_account.aggregate_price_info.pub_slot + MAX_SLOT_DIFFERENCE + 1
+
+    price_status = price_account.aggregate_price_status
+    assert price_status == PythPriceStatus.UNKNOWN

tests/test_price_component.py

@@ -21,14 +21,14 @@ def price_component() -> PythPriceComponent:
         'raw_price': 62931500000,
         'raw_confidence_interval': 16500000,
         'price_status': PythPriceStatus.TRADING,
-        'slot': 105886163,
+        'pub_slot': 105886163,
         'exponent': exponent,
     })
     latest_price = PythPriceInfo(**{
         'raw_price': 62931500000,
         'raw_confidence_interval': 16500000,
         'price_status': PythPriceStatus.TRADING,
-        'slot': 105886164,
+        'pub_slot': 105886164,
         'exponent': exponent,
     })
     return PythPriceComponent(

tests/test_price_info.py

@@ -10,7 +10,7 @@ def price_info_trading():
         raw_price=59609162000,
         raw_confidence_interval=43078500,
         price_status=PythPriceStatus.TRADING,
-        slot=105367617,
+        pub_slot=105367617,
         exponent=-8,
     )
 
@@ -21,7 +21,7 @@ def price_info_trading_bytes():
 
 
 @pytest.mark.parametrize(
-    "raw_price,raw_confidence_interval,price_status,slot,exponent,price,confidence_interval",
+    "raw_price,raw_confidence_interval,price_status,pub_slot,exponent,price,confidence_interval",
     [
         (
             1234567890,
@@ -42,7 +42,7 @@ def test_price_info(
         raw_price,
         raw_confidence_interval,
         price_status,
-        slot,
+        pub_slot,
         exponent,
         price,
         confidence_interval,
@@ -51,7 +51,7 @@ def test_price_info(
             raw_price=raw_price,
             raw_confidence_interval=raw_confidence_interval,
             price_status=price_status,
-            slot=slot,
+            pub_slot=pub_slot,
             exponent=exponent,
         )
         for key, actual_value in asdict(actual).items():
@@ -62,7 +62,7 @@ def test_price_info_iter(
         raw_price,
         raw_confidence_interval,
         price_status,
-        slot,
+        pub_slot,
         exponent,
         price,
         confidence_interval,
@@ -72,15 +72,15 @@ def test_price_info_iter(
                 raw_price=raw_price,
                 raw_confidence_interval=raw_confidence_interval,
                 price_status=price_status,
-                slot=slot,
+                pub_slot=pub_slot,
                 exponent=exponent,
             )
         )
         expected = {
             "raw_price": raw_price,
             "raw_confidence_interval": raw_confidence_interval,
             "price_status": price_status,
-            "slot": slot,
+            "pub_slot": pub_slot,
             "exponent": exponent,
             "price": price,
             "confidence_interval": confidence_interval,