nado-protocol 0.1.0__py3-none-any.whl

nado_protocol/client/apis/market/query.py

@@ -0,0 +1,310 @@
+from typing import Optional
+from nado_protocol.client.apis.base import NadoBaseAPI
+from nado_protocol.engine_client.types.query import (
+    AllProductsData,
+    MarketLiquidityData,
+    MarketPriceData,
+    MaxLpMintableData,
+    MaxOrderSizeData,
+    ProductSymbolsData,
+    SubaccountOpenOrdersData,
+    SubaccountMultiProductsOpenOrdersData,
+    QueryMaxOrderSizeParams,
+    IsolatedPositionsData,
+)
+from nado_protocol.indexer_client.types.query import (
+    IndexerCandlesticksData,
+    IndexerCandlesticksParams,
+    IndexerFundingRateData,
+    IndexerFundingRatesData,
+    IndexerHistoricalOrdersData,
+    IndexerSubaccountHistoricalOrdersParams,
+    IndexerProductSnapshotsData,
+    IndexerProductSnapshotsParams,
+    IndexerMarketSnapshotsParams,
+    IndexerMarketSnapshotsData,
+)
+from nado_protocol.trigger_client.types.query import (
+    ListTriggerOrdersParams,
+    TriggerQueryResponse,
+)
+from nado_protocol.utils.exceptions import MissingTriggerClient
+
+
+class MarketQueryAPI(NadoBaseAPI):
+    """
+    The MarketQueryAPI class provides methods to interact with the Nado's market querying APIs.
+
+    This class provides functionality for querying various details about the market including fetching
+    information about order books, fetching historical orders, and retrieving market matches, among others.
+
+    Attributes:
+        context (NadoClientContext): The context that provides connectivity configuration for NadoClient.
+
+    Note:
+        This class should not be instantiated directly, it is designed to be used through a NadoClient instance.
+    """
+
+    def get_all_engine_markets(self) -> AllProductsData:
+        """
+        Retrieves all market states from the off-chain engine.
+
+        Returns:
+            AllProductsData: A data class object containing information about all products in the engine.
+        """
+        return self.context.engine_client.get_all_products()
+
+    def get_all_product_symbols(self) -> ProductSymbolsData:
+        """
+        Retrieves all product symbols from the off-chain engine
+
+        Returns:
+            ProductSymbolsData: A list of all products with corresponding symbol.
+        """
+        return self.context.engine_client.get_product_symbols()
+
+    def get_market_liquidity(self, product_id: int, depth: int) -> MarketLiquidityData:
+        """
+        Retrieves liquidity per price tick from the engine.
+
+        The engine will skip price levels that have no liquidity,
+        so it is not guaranteed that the bids/asks are evenly spaced
+
+        Parameters:
+            product_id (int): The product ID for which liquidity is to be fetched.
+            depth (int): The depth of the order book to retrieve liquidity from.
+
+        Returns:
+            MarketLiquidityData: A data class object containing liquidity information for the specified product.
+        """
+        return self.context.engine_client.get_market_liquidity(product_id, depth)
+
+    def get_latest_market_price(self, product_id: int) -> MarketPriceData:
+        """
+        Retrieves the latest off-chain orderbook price from the engine for a specific product.
+
+        Args:
+            product_id (int): The identifier for the product to retrieve the latest market price.
+
+        Returns:
+            MarketPriceData: A data class object containing information about the latest market price for the given product.
+        """
+        return self.context.engine_client.get_market_price(product_id)
+
+    def get_subaccount_open_orders(
+        self, product_id: int, sender: str
+    ) -> SubaccountOpenOrdersData:
+        """
+        Queries the off-chain engine to retrieve the status of any open orders for a given subaccount.
+
+        This function fetches any open orders that a specific subaccount might have
+        for a specific product from the off-chain engine. The orders are returned as
+        an SubaccountOpenOrdersData object.
+
+        Args:
+            product_id (int): The identifier for the product to fetch open orders.
+
+            sender (str): The address and subaccount identifier as a bytes32 hex string.
+
+        Returns:
+            SubaccountOpenOrdersData: A data class object containing information about the open orders of a subaccount.
+        """
+        return self.context.engine_client.get_subaccount_open_orders(product_id, sender)
+
+    def get_subaccount_multi_products_open_orders(
+        self, product_ids: list[int], sender: str
+    ) -> SubaccountMultiProductsOpenOrdersData:
+        """
+        Queries the off-chain engine to retrieve the status of any open orders for a given subaccount across multiple products.
+
+        This function fetches any open orders that a specific subaccount might have
+        for products product from the off-chain engine. The orders are returned as
+        an SubaccountMultiProductsOpenOrdersData object.
+
+        Args:
+            product_ids (list[int]): List of product ids to fetch open orders for.
+
+            sender (str): The address and subaccount identifier as a bytes32 hex string.
+
+        Returns:
+            SubaccountMultiProductsOpenOrdersData: A data class object containing information about the open orders of a subaccount.
+        """
+        return self.context.engine_client.get_subaccount_multi_products_open_orders(
+            product_ids, sender
+        )
+
+    def get_subaccount_historical_orders(
+        self, params: IndexerSubaccountHistoricalOrdersParams
+    ) -> IndexerHistoricalOrdersData:
+        """
+        Queries the indexer to fetch historical orders of a specific subaccount.
+
+        This function retrieves a list of historical orders that a specific subaccount has placed.
+        The order data can be filtered using various parameters provided in the
+        IndexerSubaccountHistoricalOrdersParams object. The fetched historical orders data
+        is returned as an IndexerHistoricalOrdersData object.
+
+        Args:
+            params (IndexerSubaccountHistoricalOrdersParams): Parameters to filter the historical orders data:
+                - subaccount (str): The address and subaccount identifier as a bytes32 hex string.
+                - product_ids (list[int], optional): A list of identifiers for the products to fetch orders for. If provided, the function will return orders related to these products.
+                - idx (int, optional): Submission index. If provided, the function will return orders submitted before this index.
+                - max_time (int, optional): Maximum timestamp for the orders. The function will return orders submitted before this time.
+                - limit (int, optional): Maximum number of orders to return. If provided, the function will return at most 'limit' number of orders.
+
+        Returns:
+            IndexerHistoricalOrdersData: A data class object containing information about the historical orders of a subaccount.
+        """
+        return self.context.indexer_client.get_subaccount_historical_orders(params)
+
+    def get_historical_orders_by_digest(
+        self, digests: list[str]
+    ) -> IndexerHistoricalOrdersData:
+        """
+        Queries the indexer to fetch historical orders based on a list of provided digests.
+
+        This function retrieves historical order data for a given list of order digests.
+        Each digest represents a unique order. The returned object includes the historical
+        order data for each digest in the provided list.
+
+        Args:
+            digests (list[str]): List of order digests. An order digest is a unique identifier for each order.
+
+        Returns:
+            IndexerHistoricalOrdersData: A data class object containing information about the historical orders associated with the provided digests.
+        """
+        return self.context.indexer_client.get_historical_orders_by_digest(digests)
+
+    def get_max_order_size(self, params: QueryMaxOrderSizeParams) -> MaxOrderSizeData:
+        """
+        Queries the engine to determine the maximum order size that can be submitted within
+        health requirements.
+
+        Args:
+            params (QueryMaxOrderSizeParams):
+                - sender (str): The address and subaccount identifier in a bytes32 hex string.
+                - product_id (int): The identifier for the spot/perp product.
+                - price_x18 (str): The price of the order in x18 format as a string.
+                - direction (MaxOrderSizeDirection): 'long' for max bid or 'short' for max ask.
+                - spot_leverage (Optional[bool]): If False, calculates max size without borrowing. Defaults to True.
+
+        Returns:
+            MaxOrderSizeData: The maximum size of the order that can be placed.
+        """
+        return self.context.engine_client.get_max_order_size(params)
+
+    def get_max_lp_mintable(
+        self, product_id: int, sender: str, spot_leverage: Optional[bool] = None
+    ) -> MaxLpMintableData:
+        """
+        Queries the engine to determine the maximum base amount that can be contributed for minting LPs.
+
+        Args:
+            product_id (int): The identifier for the spot/perp product.
+
+            sender (str): The address and subaccount identifier in a bytes32 hex string.
+
+            spot_leverage (Optional[bool]): If False, calculates max amount without considering leverage. Defaults to True.
+
+        Returns:
+            MaxLpMintableData: Maximum base amount that can be contributed for minting LPs, in string format.
+        """
+        return self.context.engine_client.get_max_lp_mintable(
+            product_id, sender, spot_leverage
+        )
+
+    def get_candlesticks(
+        self, params: IndexerCandlesticksParams
+    ) -> IndexerCandlesticksData:
+        """
+        Fetches historical candlestick data for a specific product using the indexer.
+
+        Args:
+            params (IndexerCandlesticksParams): Parameters for the query, which include:
+                - product_id (int): The identifier for the product.
+                - granularity (IndexerCandlesticksGranularity): Duration for each candlestick in seconds.
+
+        Returns:
+            IndexerCandlesticksData: Contains a list of historical candlestick data (IndexerCandlestick)
+            for the specified product at the specified granularity.
+
+        Note:
+            For obtaining the latest orderbook prices, consider using the 'get_latest_market_price()' method.
+        """
+
+        return self.context.indexer_client.get_candlesticks(params)
+
+    def get_perp_funding_rate(self, product_id: int) -> IndexerFundingRateData:
+        """
+        Fetches the latest funding rate for a specific perp product.
+
+        Args:
+            product_id (int): Identifier for the perp product.
+
+        Returns:
+            IndexerFundingRateData: Contains the latest funding rate and related details for the given perp product.
+        """
+        return self.context.indexer_client.get_perp_funding_rate(product_id)
+
+    def get_perp_funding_rates(self, product_ids: list) -> IndexerFundingRatesData:
+        """
+        Fetches the latest funding rates for a list of perp products.
+
+        Args:
+            product_ids (list): List of identifiers for the perp products.
+
+        Returns:
+            dict: A dictionary mapping each product_id to its latest funding rate and related details.
+        """
+        return self.context.indexer_client.get_perp_funding_rates(product_ids)
+
+    def get_product_snapshots(
+        self, params: IndexerProductSnapshotsParams
+    ) -> IndexerProductSnapshotsData:
+        """
+        Fetches the historical snapshots for a specific product from the indexer.
+
+        Args:
+            params (IndexerProductSnapshotsParams): Query parameters consisting of:
+                - product_id (int): Identifier for the product.
+                - idx (int, optional): Submission index to filter the returned snapshots.
+                - max_time (int, optional): Maximum timestamp to filter the returned snapshots.
+                - limit (int, optional): Maximum number of snapshots to return.
+
+        Returns:
+            IndexerProductSnapshotsData: Object containing lists of product snapshots and related transaction data.
+        """
+        return self.context.indexer_client.get_product_snapshots(params)
+
+    def get_market_snapshots(
+        self, params: IndexerMarketSnapshotsParams
+    ) -> IndexerMarketSnapshotsData:
+        """
+        Fetches the historical market snapshots from the indexer.
+
+        Args:
+            params (IndexerMarketSnapshotsParams): Parameters specifying the historical market snapshot request.
+
+        Returns:
+            IndexerMarketSnapshotsData: The market snapshot data corresponding to the provided parameters.
+        """
+        return self.context.indexer_client.get_market_snapshots(params)
+
+    def get_trigger_orders(
+        self, params: ListTriggerOrdersParams
+    ) -> TriggerQueryResponse:
+        if self.context.trigger_client is None:
+            raise MissingTriggerClient()
+        return self.context.trigger_client.list_trigger_orders(params)
+
+    def get_isolated_positions(self, subaccount: str) -> IsolatedPositionsData:
+        """
+        Retrieve isolated positions for a specific subaccount.
+
+        Args:
+            subaccount (str): Unique identifier for the subaccount.
+
+        Returns:
+            IsolatedPositionsData: A data class object containing information about the isolated positions for the specified subaccount.
+        """
+        return self.context.engine_client.get_isolated_positions(subaccount)

nado_protocol/client/apis/perp/__init__.py

@@ -0,0 +1,18 @@
+from nado_protocol.client.apis.perp.query import PerpQueryAPI
+
+
+class PerpAPI(PerpQueryAPI):
+    """
+    A unified interface for Perpetual (Perp) operations in the Nado Protocol.
+
+    This class extends functionalities from PerpQueryAPI into a single interface, providing a simpler and more consistent way to perform Perp operations.
+    Currently, it allows for querying (data retrieval) operations for Perp products.
+
+    Inheritance:
+        PerpQueryAPI: This provides functionalities to retrieve various kinds of information related to Perp products.
+        These include operations like retrieving the latest index and mark price for a specific Perp product.
+
+    Attributes and Methods: Inherited from PerpQueryAPI.
+    """
+
+    pass

nado_protocol/client/apis/perp/query.py

@@ -0,0 +1,30 @@
+from nado_protocol.client.apis.base import NadoBaseAPI
+from nado_protocol.indexer_client.types.query import IndexerPerpPricesData
+
+
+class PerpQueryAPI(NadoBaseAPI):
+    """
+    Provides functionalities for querying data related to Perpetual (Perp) products in the Nado Protocol.
+
+    Inherits from NadoBaseAPI, which provides a basic context setup for accessing Nado.
+    This class extends the base class to provide specific functionalities for querying data related to Perp products.
+
+    Attributes:
+        context (NadoClientContext): Provides connectivity details for accessing Nado APIs.
+    """
+
+    def get_prices(self, product_id: int) -> IndexerPerpPricesData:
+        """
+        Retrieves the latest index and mark price for a specific perp product from the indexer.
+
+        Args:
+            product_id (int): The identifier for the perp product.
+
+        Returns:
+            IndexerPerpPricesData: An object containing the latest index and mark price for the specified product.
+                - product_id (int): The identifier for the perp product.
+                - index_price_x18 (str): The latest index price for the product, scaled by 1e18.
+                - mark_price_x18 (str): The latest mark price for the product, scaled by 1e18.
+                - update_time (str): The timestamp of the last price update.
+        """
+        return self.context.indexer_client.get_perp_prices(product_id)

nado_protocol/client/apis/rewards/__init__.py

@@ -0,0 +1,6 @@
+from nado_protocol.client.apis.rewards.execute import RewardsExecuteAPI
+from nado_protocol.client.apis.rewards.query import RewardsQueryAPI
+
+
+class RewardsAPI(RewardsExecuteAPI, RewardsQueryAPI):
+    pass

nado_protocol/client/apis/rewards/execute.py

@@ -0,0 +1,131 @@
+from typing import Optional
+from nado_protocol.contracts.types import (
+    ClaimFoundationRewardsContractParams,
+    ClaimFoundationRewardsProofStruct,
+    ClaimVrtxContractParams,
+    ClaimVrtxParams,
+)
+from nado_protocol.client.apis.base import NadoBaseAPI
+from eth_account.signers.local import LocalAccount
+
+from nado_protocol.utils.exceptions import InvalidVrtxClaimParams
+
+
+class RewardsExecuteAPI(NadoBaseAPI):
+    def _validate_claim_params(self, params: ClaimVrtxParams):
+        p = ClaimVrtxParams.parse_obj(params)
+        if p.amount is None and p.claim_all is None:
+            raise InvalidVrtxClaimParams()
+
+    def claim_vrtx(
+        self, params: ClaimVrtxParams, signer: Optional[LocalAccount] = None
+    ) -> str:
+        self._validate_claim_params(params)
+        signer = self._get_signer(signer)
+        claim_params = self._get_claim_vrtx_contract_params(params, signer)
+        return self.context.contracts.claim_vrtx(
+            claim_params.epoch,
+            claim_params.amount_to_claim,
+            claim_params.total_claimable_amount,
+            claim_params.merkle_proof,
+            signer,
+        )
+
+    def claim_and_stake_vrtx(
+        self, params: ClaimVrtxParams, signer: Optional[LocalAccount] = None
+    ) -> str:
+        self._validate_claim_params(params)
+        signer = self._get_signer(signer)
+        claim_params = self._get_claim_vrtx_contract_params(params, signer)
+        return self.context.contracts.claim_and_stake_vrtx(
+            claim_params.epoch,
+            claim_params.amount_to_claim,
+            claim_params.total_claimable_amount,
+            claim_params.merkle_proof,
+            signer,
+        )
+
+    def stake_vrtx(self, amount: int, signer: Optional[LocalAccount] = None) -> str:
+        signer = self._get_signer(signer)
+        return self.context.contracts.stake_vrtx(amount, signer)
+
+    def unstake_vrtx(self, amount: int, signer: Optional[LocalAccount] = None) -> str:
+        signer = self._get_signer(signer)
+        return self.context.contracts.unstake_vrtx(amount, signer)
+
+    def withdraw_unstaked_vrtx(self, signer: Optional[LocalAccount] = None):
+        signer = self._get_signer(signer)
+        return self.context.contracts.withdraw_unstaked_vrtx(signer)
+
+    def claim_usdc_rewards(self, signer: Optional[LocalAccount] = None):
+        signer = self._get_signer(signer)
+        return self.context.contracts.claim_usdc_rewards(signer)
+
+    def claim_and_stake_usdc_rewards(self, signer: Optional[LocalAccount] = None):
+        signer = self._get_signer(signer)
+        return self.context.contracts.claim_and_stake_usdc_rewards(signer)
+
+    def claim_foundation_rewards(self, signer: Optional[LocalAccount] = None):
+        """
+        Claims all available foundation rewards. Foundation rewards are tokens associated with the chain. For example, ARB on Arbitrum.
+        """
+        signer = self._get_signer(signer)
+        claim_params = self._get_claim_foundation_rewards_contract_params(signer)
+        return self.context.contracts.claim_foundation_rewards(
+            claim_params.claim_proofs, signer
+        )
+
+    def _get_claim_vrtx_contract_params(
+        self, params: ClaimVrtxParams, signer: LocalAccount
+    ) -> ClaimVrtxContractParams:
+        epoch_merkle_proofs = self.context.indexer_client.get_vrtx_merkle_proofs(
+            signer.address
+        ).merkle_proofs[params.epoch]
+        total_claimable_amount = int(epoch_merkle_proofs.total_amount)
+        if params.amount is not None:
+            amount_to_claim = params.amount
+        else:
+            assert self.context.contracts.vrtx_airdrop is not None
+            amount_claimed = self.context.contracts.vrtx_airdrop.functions.getClaimed(
+                signer.address
+            ).call()
+            amount_to_claim = total_claimable_amount - amount_claimed[params.epoch]
+        return ClaimVrtxContractParams(
+            epoch=params.epoch,
+            amount_to_claim=amount_to_claim,
+            total_claimable_amount=total_claimable_amount,
+            merkle_proof=epoch_merkle_proofs.proof,
+        )
+
+    def _get_claim_foundation_rewards_contract_params(
+        self, signer: LocalAccount
+    ) -> ClaimFoundationRewardsContractParams:
+        assert self.context.contracts.foundation_rewards_airdrop is not None
+        claimed = (
+            self.context.contracts.foundation_rewards_airdrop.functions.getClaimed(
+                signer.address
+            ).call()
+        )
+        merkle_proofs = (
+            self.context.indexer_client.get_foundation_rewards_merkle_proofs(
+                signer.address
+            )
+        )
+        claim_proofs = []
+
+        for idx, proof in enumerate(merkle_proofs.merkle_proofs):
+            if idx == 0:
+                # week 0 is invalid
+                continue
+
+            total_amount = int(proof.total_amount)
+
+            # There's no partial claim, so find weeks where there's a claimable amount and amt claimed is zero
+            if total_amount > 0 and int(claimed[idx]) == 0:
+                claim_proofs.append(
+                    ClaimFoundationRewardsProofStruct(
+                        totalAmount=total_amount, week=idx, proof=proof.proof
+                    )
+                )
+
+        return ClaimFoundationRewardsContractParams(claim_proofs=claim_proofs)

nado_protocol/client/apis/rewards/query.py

@@ -0,0 +1,12 @@
+from nado_protocol.client.apis.base import NadoBaseAPI
+
+
+class RewardsQueryAPI(NadoBaseAPI):
+    def get_claim_and_stake_estimated_vrtx(self, wallet: str) -> int:
+        """
+        Estimates the amount of USDC -> VRTX swap when claiming + staking USDC rewards
+        """
+        assert self.context.contracts.vrtx_staking is not None
+        return self.context.contracts.vrtx_staking.functions.getEstimatedVrtxToStake(
+            wallet
+        ).call()

nado_protocol/client/apis/spot/__init__.py

@@ -0,0 +1,23 @@
+from nado_protocol.client.apis.spot.execute import SpotExecuteAPI
+from nado_protocol.client.apis.spot.query import SpotQueryAPI
+
+
+class SpotAPI(SpotExecuteAPI, SpotQueryAPI):
+    """
+    A unified interface for spot operations in the Nado Protocol.
+
+    This class combines functionalities from both SpotExecuteAPI and SpotQueryAPI
+    into a single interface, providing a simpler and more consistent way to perform spot operations.
+    It allows for both query (data retrieval) and execution (transaction) operations for spot products.
+
+    Inheritance:
+        SpotExecuteAPI: This provides functionalities to execute various operations related to spot products,
+        such as depositing a specified amount into a spot product.
+
+        SpotQueryAPI: This provides functionalities to retrieve various kinds of information related to spot products,
+        such as getting the wallet token balance of a given spot product.
+
+    Attributes and Methods: Inherited from SpotExecuteAPI and SpotQueryAPI.
+    """
+
+    pass

nado_protocol/client/apis/spot/base.py

@@ -0,0 +1,32 @@
+from web3.contract import Contract
+from nado_protocol.client.apis.base import NadoBaseAPI
+
+
+class BaseSpotAPI(NadoBaseAPI):
+    """
+    Base class for Spot operations in the Nado Protocol.
+
+    This class provides basic functionality for retrieving product-specific information
+    from the spot market of the Nado Protocol, such as the associated ERC20 token contract for a given spot product.
+
+    Attributes:
+        context (NadoClientContext): Provides connectivity details for accessing Nado APIs.
+
+    Methods:
+        get_token_contract_for_product: Retrieves the associated ERC20 token contract for a given spot product.
+    """
+
+    def get_token_contract_for_product(self, product_id: int) -> Contract:
+        """
+        Retrieves the associated ERC20 token contract for a given spot product.
+
+        Args:
+            product_id (int): The identifier for the spot product.
+
+        Returns:
+            Contract: The associated ERC20 token contract for the specified spot product.
+
+        Raises:
+            InvalidProductId: If the provided product ID is not valid.
+        """
+        return self.context.contracts.get_token_contract_for_product(product_id)