nado-protocol 0.1.6__py3-none-any.whl → 0.2.0__py3-none-any.whl

nado_protocol/indexer_client/query.py

@@ -49,6 +49,8 @@ from nado_protocol.indexer_client.types.query import (
     IndexerMerkleProofsData,
     IndexerInterestAndFundingParams,
     IndexerInterestAndFundingData,
+    IndexerAccountSnapshotsParams,
+    IndexerAccountSnapshotsData,
     IndexerTickersData,
     IndexerPerpContractsData,
     IndexerHistoricalTradesData,
@@ -459,3 +461,24 @@ class IndexerQueryClient:
         if max_trade_id is not None:
             url += f"&max_trade_id={max_trade_id}"
         return ensure_data_type(self._query_v2(url), list)
+
+    def get_multi_subaccount_snapshots(
+        self, params: IndexerAccountSnapshotsParams
+    ) -> IndexerAccountSnapshotsData:
+        """
+        Retrieves subaccount snapshots at specified timestamps.
+        Each snapshot is a view of the subaccount's balances at that point in time,
+        with tracked variables for interest, funding, etc.
+
+        Args:
+            params (IndexerAccountSnapshotsParams): Parameters specifying subaccounts,
+                timestamps, and whether to include isolated positions.
+
+        Returns:
+            IndexerAccountSnapshotsData: Dict mapping subaccount hex -> timestamp -> snapshot data.
+                Each snapshot contains balances with trackedVars including netEntryUnrealized.
+        """
+        return ensure_data_type(
+            self.query(IndexerAccountSnapshotsParams.parse_obj(params)).data,
+            IndexerAccountSnapshotsData,
+        )

nado_protocol/indexer_client/types/models.py

@@ -182,7 +182,7 @@ class IndexerEventTrackedData(NadoBaseModel):
     net_funding_cumulative: str
     net_entry_unrealized: str
     net_entry_cumulative: str
-    cumulative_volume: str
+    quote_volume_cumulative: str
 
 
 class IndexerEvent(IndexerBaseModel, IndexerEventTrackedData):

nado_protocol/indexer_client/types/query.py

@@ -49,6 +49,7 @@ class IndexerQueryType(StrEnum):
     REFERRAL_CODE = "referral_code"
     SUBACCOUNTS = "subaccounts"
     USDC_PRICE = "usdc_price"
+    ACCOUNT_SNAPSHOTS = "account_snapshots"
     # TODO: revise once this endpoint is live
     TOKEN_MERKLE_PROOFS = "token_merkle_proofs"
     FOUNDATION_REWARDS_MERKLE_PROOFS = "foundation_rewards_merkle_proofs"
@@ -292,6 +293,17 @@ class IndexerInterestAndFundingParams(NadoBaseModel):
     limit: int
 
 
+class IndexerAccountSnapshotsParams(NadoBaseModel):
+    """
+    Parameters for querying account snapshots.
+    """
+
+    subaccounts: list[str]
+    timestamps: list[int]
+    isolated: Optional[bool] = None
+    active: Optional[bool] = None
+
+
 IndexerParams = Union[
     IndexerSubaccountHistoricalOrdersParams,
     IndexerHistoricalOrdersByDigestParams,
@@ -314,6 +326,7 @@ IndexerParams = Union[
     IndexerTokenMerkleProofsParams,
     IndexerFoundationRewardsMerkleProofsParams,
     IndexerInterestAndFundingParams,
+    IndexerAccountSnapshotsParams,
 ]
 
 
@@ -487,6 +500,14 @@ class IndexerInterestAndFundingRequest(NadoBaseModel):
     interest_and_funding: IndexerInterestAndFundingParams
 
 
+class IndexerAccountSnapshotsRequest(NadoBaseModel):
+    """
+    Request object for querying account snapshots.
+    """
+
+    account_snapshots: IndexerAccountSnapshotsParams
+
+
 IndexerRequest = Union[
     IndexerHistoricalOrdersRequest,
     IndexerMatchesRequest,
@@ -508,6 +529,7 @@ IndexerRequest = Union[
     IndexerTokenMerkleProofsRequest,
     IndexerFoundationRewardsMerkleProofsRequest,
     IndexerInterestAndFundingRequest,
+    IndexerAccountSnapshotsRequest,
 ]
 
 
@@ -681,6 +703,14 @@ class IndexerInterestAndFundingData(NadoBaseModel):
 IndexerLiquidationFeedData = list[IndexerLiquidatableAccount]
 
 
+class IndexerAccountSnapshotsData(NadoBaseModel):
+    """
+    Data object for subaccount snapshots grouped by subaccount and timestamp.
+    """
+
+    snapshots: Dict[str, Dict[str, list[IndexerEvent]]]
+
+
 IndexerResponseData = Union[
     IndexerHistoricalOrdersData,
     IndexerMatchesData,
@@ -702,6 +732,7 @@ IndexerResponseData = Union[
     IndexerInterestAndFundingData,
     IndexerLiquidationFeedData,
     IndexerFundingRatesData,
+    IndexerAccountSnapshotsData,
 ]
 
 
@@ -809,6 +840,10 @@ def to_indexer_request(params: IndexerParams) -> IndexerRequest:
             IndexerInterestAndFundingRequest,
             IndexerQueryType.INTEREST_AND_FUNDING.value,
         ),
+        IndexerAccountSnapshotsParams: (
+            IndexerAccountSnapshotsRequest,
+            IndexerQueryType.ACCOUNT_SNAPSHOTS.value,
+        ),
     }
 
     RequestClass, field_name = indexer_request_mapping[type(params)]

nado_protocol/utils/__init__.py

@@ -26,8 +26,10 @@ __all__ = [
     "get_expiration_timestamp",
     "gen_order_nonce",
     "to_pow_10",
+    "to_x6",
     "to_x18",
     "from_pow_10",
+    "from_x6",
     "from_x18",
     "ExecuteFailedException",
     "QueryFailedException",

nado_protocol/utils/balance.py

@@ -0,0 +1,249 @@
+"""
+Balance Value Calculation Utilities
+"""
+
+from decimal import Decimal
+from typing import Union
+from nado_protocol.engine_client.types.models import (
+    SpotProduct,
+    PerpProduct,
+    SpotProductBalance,
+    PerpProductBalance,
+)
+from nado_protocol.utils.math import from_x18
+
+
+def calculate_spot_balance_value(
+    amount: Union[Decimal, float, str], oracle_price: Union[Decimal, float, str]
+) -> Decimal:
+    """
+    Calculate the quote value of a spot balance.
+
+    Formula: amount * oracle_price
+
+    This is used for:
+    - Calculating health contributions
+    - Determining deposits vs borrows
+    - Portfolio value calculations
+
+    Args:
+        amount: Token amount (can be negative for borrows)
+        oracle_price: Oracle price in quote currency
+
+    Returns:
+        Value in quote currency (positive for deposits, negative for borrows)
+
+    Example:
+        >>> calculate_spot_balance_value(100, 2000)  # 100 ETH at $2000
+        Decimal('200000')
+        >>> calculate_spot_balance_value(-50, 2000)  # 50 ETH borrowed
+        Decimal('-100000')
+    """
+    amount_dec = Decimal(str(amount))
+    price_dec = Decimal(str(oracle_price))
+    return amount_dec * price_dec
+
+
+def calculate_perp_balance_notional_value(
+    amount: Union[Decimal, float, str], oracle_price: Union[Decimal, float, str]
+) -> Decimal:
+    """
+    Calculate the notional value of a perp position.
+
+    Formula: abs(amount * oracle_price)
+
+    This represents the total size of the position in quote currency terms,
+    regardless of direction (long or short).
+
+    Args:
+        amount: Position size (positive for long, negative for short)
+        oracle_price: Oracle price in quote currency
+
+    Returns:
+        Absolute notional value in quote currency
+
+    Example:
+        >>> calculate_perp_balance_notional_value(10, 50000)  # 10 BTC long
+        Decimal('500000')
+        >>> calculate_perp_balance_notional_value(-10, 50000)  # 10 BTC short
+        Decimal('500000')
+    """
+    amount_dec = Decimal(str(amount))
+    price_dec = Decimal(str(oracle_price))
+    return abs(amount_dec * price_dec)
+
+
+def calculate_perp_balance_value(
+    amount: Union[Decimal, float, str],
+    oracle_price: Union[Decimal, float, str],
+    v_quote_balance: Union[Decimal, float, str],
+) -> Decimal:
+    """
+    Calculate the true quote value of a perp balance (unrealized PnL).
+
+    Formula: (amount * oracle_price) + v_quote_balance
+
+    The v_quote_balance represents:
+    - Unrealized PnL from price changes
+    - Accumulated funding payments
+    - Entry cost adjustments
+
+    This value is what would be added to your balance if the position were closed.
+
+    Args:
+        amount: Position size
+        oracle_price: Oracle price in quote currency
+        v_quote_balance: Virtual quote balance (unsettled PnL)
+
+    Returns:
+        Total value in quote currency (can be positive or negative)
+
+    Example:
+        >>> # Long 10 BTC at $50k, now at $51k, with funding
+        >>> calculate_perp_balance_value(10, 51000, -500000)
+        Decimal('10000')  # $10k profit
+    """
+    amount_dec = Decimal(str(amount))
+    price_dec = Decimal(str(oracle_price))
+    v_quote_dec = Decimal(str(v_quote_balance))
+    return (amount_dec * price_dec) + v_quote_dec
+
+
+def parse_spot_balance_value(
+    balance: SpotProductBalance, product: SpotProduct
+) -> Decimal:
+    """
+    Parse spot balance value from raw SDK types.
+
+    This is a convenience function that extracts values from the SDK types
+    and calls calculate_spot_balance_value.
+
+    Args:
+        balance: Spot balance from subaccount info
+        product: Spot product information
+
+    Returns:
+        Balance value in quote currency
+    """
+    amount = Decimal(from_x18(int(balance.balance.amount)))
+    oracle_price = Decimal(from_x18(int(product.oracle_price_x18)))
+    return calculate_spot_balance_value(amount, oracle_price)
+
+
+def parse_perp_balance_notional_value(
+    balance: PerpProductBalance, product: PerpProduct
+) -> Decimal:
+    """
+    Parse perp notional value from raw SDK types.
+
+    Args:
+        balance: Perp balance from subaccount info
+        product: Perp product information
+
+    Returns:
+        Notional value in quote currency
+    """
+    amount = Decimal(from_x18(int(balance.balance.amount)))
+    oracle_price = Decimal(from_x18(int(product.oracle_price_x18)))
+    return calculate_perp_balance_notional_value(amount, oracle_price)
+
+
+def parse_perp_balance_value(
+    balance: PerpProductBalance, product: PerpProduct
+) -> Decimal:
+    """
+    Parse perp balance value (unrealized PnL) from raw SDK types.
+
+    Args:
+        balance: Perp balance from subaccount info
+        product: Perp product information
+
+    Returns:
+        Balance value in quote currency
+    """
+    amount = Decimal(from_x18(int(balance.balance.amount)))
+    oracle_price = Decimal(from_x18(int(product.oracle_price_x18)))
+    v_quote = Decimal(from_x18(int(balance.balance.v_quote_balance)))
+    return calculate_perp_balance_value(amount, oracle_price, v_quote)
+
+
+def calculate_total_spot_deposits_and_borrows(
+    balances: list[tuple[SpotProductBalance, SpotProduct]]
+) -> tuple[Decimal, Decimal]:
+    """
+    Calculate total spot deposits and borrows across all balances.
+
+    Args:
+        balances: List of (balance, product) tuples
+
+    Returns:
+        Tuple of (total_deposits, total_borrows) in quote currency
+        Both values are positive (borrows is absolute value)
+
+    Example:
+        >>> balances = [(usdt_balance, usdt_product), (eth_balance, eth_product)]
+        >>> deposits, borrows = calculate_total_spot_deposits_and_borrows(balances)
+        >>> deposits  # Total deposits
+        Decimal('10000')
+        >>> borrows   # Total borrows (absolute value)
+        Decimal('5000')
+    """
+    total_deposits = Decimal(0)
+    total_borrows = Decimal(0)
+
+    for balance, product in balances:
+        value = parse_spot_balance_value(balance, product)
+        if value > 0:
+            total_deposits += value
+        else:
+            total_borrows += abs(value)
+
+    return total_deposits, total_borrows
+
+
+def calculate_total_perp_notional(
+    balances: list[tuple[PerpProductBalance, PerpProduct]]
+) -> Decimal:
+    """
+    Calculate total notional value across all perp positions.
+
+    Args:
+        balances: List of (balance, product) tuples
+
+    Returns:
+        Total notional value in quote currency
+
+    Example:
+        >>> balances = [(btc_perp_balance, btc_perp_product)]
+        >>> total = calculate_total_perp_notional(balances)
+        >>> total
+        Decimal('500000')  # Total position size
+    """
+    total = Decimal(0)
+    for balance, product in balances:
+        total += parse_perp_balance_notional_value(balance, product)
+    return total
+
+
+def calculate_total_perp_value(
+    balances: list[tuple[PerpProductBalance, PerpProduct]]
+) -> Decimal:
+    """
+    Calculate total unrealized PnL across all perp positions.
+
+    Args:
+        balances: List of (balance, product) tuples
+
+    Returns:
+        Total unrealized PnL in quote currency (can be positive or negative)
+
+    Example:
+        >>> balances = [(btc_perp_balance, btc_perp_product)]
+        >>> total_pnl = calculate_total_perp_value(balances)
+        >>> total_pnl
+        Decimal('10000')  # $10k unrealized profit
+    """
+    total = Decimal(0)
+    for balance, product in balances:
+        total += parse_perp_balance_value(balance, product)
+    return total