Add aggregate_price_status which takes care of becoming stale

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,