nado-protocol 0.1.0__py3-none-any.whl

nado_protocol/client/apis/spot/execute.py

@@ -0,0 +1,117 @@
+from typing import Optional
+from nado_protocol.contracts.types import DepositCollateralParams
+from eth_account.signers.local import LocalAccount
+from nado_protocol.client.apis.spot.base import BaseSpotAPI
+from nado_protocol.engine_client.types.execute import (
+    ExecuteResponse,
+    WithdrawCollateralParams,
+)
+from nado_protocol.utils.exceptions import MissingSignerException
+
+
+class SpotExecuteAPI(BaseSpotAPI):
+    """
+    Class providing execution operations for the spot market in the Nado Protocol.
+
+    This class provides functionality for executing transactions related to spot products,
+    such as depositing a specified amount into a spot product.
+
+    Inheritance:
+        BaseSpotAPI: Base class for Spot operations. Inherits connectivity context and base functionalities.
+    """
+
+    def deposit(
+        self, params: DepositCollateralParams, signer: Optional[LocalAccount] = None
+    ) -> str:
+        """
+        Executes the operation of depositing a specified amount into a spot product.
+
+        Args:
+            params (DepositCollateralParams): Parameters required for depositing collateral.
+
+            signer (LocalAccount, optional):  The account that will sign the deposit transaction. If no signer is provided, the signer set in the client context will be used.
+
+        Raises:
+            MissingSignerException: Raised when there is no signer provided and no signer set in the client context.
+
+        Returns:
+            str: The deposit collateral transaction hash.
+        """
+        signer = signer if signer else self.context.signer
+        if not signer:
+            raise MissingSignerException(
+                "A signer must be provided or set via the context."
+            )
+        return self.context.contracts.deposit_collateral(params, signer)
+
+    def withdraw(self, params: WithdrawCollateralParams) -> ExecuteResponse:
+        """
+        Executes a withdrawal for the specified spot product via the off-chain engine.
+
+        Args:
+            params (WithdrawCollateralParams): Parameters needed to execute the withdrawal.
+
+        Returns:
+            ExecuteResponse: The response from the engine execution.
+
+        Raises:
+            Exception: If there is an error during the execution or the response status is not "success".
+        """
+        return self.context.engine_client.withdraw_collateral(params)
+
+    def approve_allowance(
+        self, product_id: int, amount: int, signer: Optional[LocalAccount] = None
+    ) -> str:
+        """
+        Approves an allowance for a certain amount of tokens for a spot product.
+
+        Args:
+            product_id (int): The identifier of the spot product for which to approve an allowance.
+
+            amount (int): The amount of the tokens to be approved.
+
+            signer (LocalAccount, optional):  The account that will sign the approval transaction. If no signer is provided, the signer set in the client context will be used.
+
+        Returns:
+            str: The approve allowance transaction hash.
+
+        Raises:
+            MissingSignerException: Raised when there is no signer provided and no signer set in the client context.
+            InvalidProductId: If the provided product ID is not valid.
+        """
+        signer = signer if signer else self.context.signer
+        if not signer:
+            raise MissingSignerException(
+                "A signer must be provided or set via the context."
+            )
+        token = self.get_token_contract_for_product(product_id)
+        return self.context.contracts.approve_allowance(token, amount, signer)
+
+    def _mint_mock_erc20(
+        self, product_id: int, amount: int, signer: Optional[LocalAccount] = None
+    ):
+        """
+        Mints a specified amount of mock ERC20 tokens for testing purposes.
+
+        Args:
+            product_id (int): The identifier for the spot product.
+
+            amount (int): The amount of mock ERC20 tokens to mint.
+
+            signer (LocalAccount, optional):  The account that will sign the mint transaction.
+                If no signer is provided, the signer set in the client context will be used.
+
+        Returns:
+            str: The mock ERC20 mint transaction hash.
+
+        Raises:
+            MissingSignerException: Raised when there is no signer provided and no signer set in the client context.
+            InvalidProductId: If the provided product ID is not valid.
+        """
+        signer = signer if signer else self.context.signer
+        if not signer:
+            raise MissingSignerException(
+                "A signer must be provided or set via the context."
+            )
+        token = self.get_token_contract_for_product(product_id)
+        return self.context.contracts._mint_mock_erc20(token, amount, signer)

nado_protocol/client/apis/spot/query.py

@@ -0,0 +1,79 @@
+from typing import Optional
+from nado_protocol.client.apis.spot.base import BaseSpotAPI
+from nado_protocol.engine_client.types.query import MaxWithdrawableData
+from nado_protocol.utils.math import from_pow_10
+
+
+class SpotQueryAPI(BaseSpotAPI):
+    """
+    Class providing querying operations for the spot market in the Nado Protocol.
+
+    This class allows for retrieval of various kinds of information related to spot products,
+    such as getting wallet token balance of a given spot product.
+
+    Inheritance:
+        BaseSpotAPI: Base class for Spot operations. Inherits connectivity context and base functionalities.
+    """
+
+    def get_max_withdrawable(
+        self, product_id: int, sender: str, spot_leverage: Optional[bool] = None
+    ) -> MaxWithdrawableData:
+        """
+        Retrieves the estimated maximum withdrawable amount for a provided spot product.
+
+        Args:
+            product_id (int): The identifier for the spot 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:
+            MaxWithdrawableData: The maximum withdrawable amount for the spot product.
+        """
+        return self.context.engine_client.get_max_withdrawable(
+            product_id, sender, spot_leverage
+        )
+
+    def get_token_wallet_balance(self, product_id: int, address: str) -> float:
+        """
+        Retrieves the balance of a specific token in the user's wallet (i.e. not in a Nado subaccount)
+
+        Args:
+            product_id (int): Identifier for the spot product.
+
+            address (str): User's wallet address.
+
+        Returns:
+            float: The balance of the token in the user's wallet in decimal form.
+
+        Raises:
+            InvalidProductId: If the provided product ID is not valid.
+        """
+        token = self.get_token_contract_for_product(product_id)
+        decimals = token.functions.decimals().call()
+        return from_pow_10(token.functions.balanceOf(address).call(), decimals)
+
+    def get_token_allowance(self, product_id: int, address: str) -> float:
+        """
+        Retrieves the current token allowance of a specified spot product.
+
+        Args:
+            product_id (int): Identifier for the spot product.
+
+            address (str): The user's wallet address.
+
+        Returns:
+            float: The current token allowance of the user's wallet address to the associated spot product.
+
+        Raises:
+            InvalidProductId: If the provided product ID is not valid.
+        """
+        token = self.get_token_contract_for_product(product_id)
+        decimals = token.functions.decimals().call()
+        return from_pow_10(
+            token.functions.allowance(
+                address, self.context.contracts.endpoint.address
+            ).call(),
+            decimals,
+        )

nado_protocol/client/apis/subaccount/__init__.py

@@ -0,0 +1,24 @@
+from nado_protocol.client.apis.subaccount.execute import SubaccountExecuteAPI
+from nado_protocol.client.apis.subaccount.query import SubaccountQueryAPI
+
+
+class SubaccountAPI(SubaccountExecuteAPI, SubaccountQueryAPI):
+    """
+    A unified interface for subaccount operations in the Nado Protocol.
+
+    This class combines functionalities from both SubaccountExecuteAPI and SubaccountQueryAPI
+    into a single interface, providing a simpler and more consistent way to perform subaccount operations.
+    It allows for both query (data retrieval) and execution (transaction) operations for subaccounts.
+
+    Inheritance:
+        SubaccountExecuteAPI: This provides functionalities to execute various operations related to subaccounts.
+        These include actions like liquidating a subaccount or linking a signer to a subaccount.
+
+        SubaccountQueryAPI: This provides functionalities to retrieve various kinds of information related to subaccounts.
+        These include operations like retrieving a summary of a subaccount's state, retrieving the fee rates associated with a
+        subaccount, querying token rewards for a wallet, and getting linked signer rate limits for a subaccount.
+
+    Attributes and Methods: Inherited from SubaccountExecuteAPI and SubaccountQueryAPI.
+    """
+
+    pass

nado_protocol/client/apis/subaccount/execute.py

@@ -0,0 +1,54 @@
+from nado_protocol.client.apis.base import NadoBaseAPI
+from nado_protocol.engine_client.types.execute import (
+    ExecuteResponse,
+    LinkSignerParams,
+    LiquidateSubaccountParams,
+)
+
+
+class SubaccountExecuteAPI(NadoBaseAPI):
+    """
+    Provides functionalities for executing operations related to subaccounts 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 executing actions related to subaccounts.
+
+    The provided methods include:
+    - `liquidate_subaccount`: Performs the liquidation of a subaccount.
+    - `link_signer`: Links a signer to a subaccount, granting them transaction signing permissions.
+
+    Attributes:
+        context (NadoClientContext): Provides connectivity details for accessing Nado APIs.
+    """
+
+    def liquidate_subaccount(
+        self, params: LiquidateSubaccountParams
+    ) -> ExecuteResponse:
+        """
+        Liquidates a subaccount through the engine.
+
+        Args:
+            params (LiquidateSubaccountParams): Parameters for liquidating the subaccount.
+
+        Returns:
+            ExecuteResponse: Execution response from the engine.
+
+        Raises:
+            Exception: If there is an error during the execution or the response status is not "success".
+        """
+        return self.context.engine_client.liquidate_subaccount(params)
+
+    def link_signer(self, params: LinkSignerParams) -> ExecuteResponse:
+        """
+        Links a signer to a subaccount to allow them to sign transactions on behalf of the subaccount.
+
+        Args:
+            params (LinkSignerParams): Parameters for linking a signer to a subaccount.
+
+        Returns:
+            ExecuteResponse: Execution response from the engine.
+
+        Raises:
+            Exception: If there is an error during the execution or the response status is not "success".
+        """
+        return self.context.engine_client.link_signer(params)

nado_protocol/client/apis/subaccount/query.py

@@ -0,0 +1,145 @@
+from typing import Optional
+from nado_protocol.client.apis.base import NadoBaseAPI
+from nado_protocol.engine_client.types.query import (
+    FeeRatesData,
+    QuerySubaccountInfoTx,
+    SubaccountInfoData,
+)
+from nado_protocol.indexer_client.types.query import (
+    IndexerLinkedSignerRateLimitData,
+    IndexerReferralCodeData,
+    IndexerSubaccountsData,
+    IndexerSubaccountsParams,
+    IndexerTokenRewardsData,
+    IndexerInterestAndFundingParams,
+    IndexerInterestAndFundingData,
+)
+
+
+class SubaccountQueryAPI(NadoBaseAPI):
+    """
+    Provides functionalities for querying data related to subaccounts in the Nado Protocol.
+
+    Inherits from NadoBaseAPI, which provides a basic context setup for accessing Nado Clearinghouse.
+    This class extends the base class to provide specific functionalities for querying data related to subaccounts.
+
+    Attributes:
+        context (NadoClientContext): Provides connectivity details for accessing Nado APIs.
+    """
+
+    def get_engine_subaccount_summary(
+        self, subaccount: str, txs: Optional[list[QuerySubaccountInfoTx]] = None
+    ) -> SubaccountInfoData:
+        """
+        Retrieve a comprehensive summary of the specified subaccount's state as per the off-chain engine.
+
+        You can optionally provide a list of txs to get an estimated view of your subaccount.
+
+        Args:
+            subaccount (str): Unique identifier for the subaccount.
+
+            txs (list[QuerySubaccountInfoTx], optional): Optional list of transactions for the subaccount.
+
+        Returns:
+            SubaccountInfoData: A data class object containing detailed state information about the queried subaccount.
+        """
+        return self.context.engine_client.get_subaccount_info(subaccount, txs)
+
+    def get_subaccount_fee_rates(self, subaccount: str) -> FeeRatesData:
+        """
+        Retrieve the fee rates associated with a specific subaccount from the off-chain engine.
+
+        Args:
+            subaccount (str): Unique identifier for the subaccount.
+
+        Returns:
+            FeeRatesData: A data class object containing detailed fee rates data for the specified subaccount.
+        """
+        return self.context.engine_client.get_fee_rates(subaccount)
+
+    def get_subaccount_token_rewards(self, address: str) -> IndexerTokenRewardsData:
+        """
+        Query the $VRTX token rewards accumulated per epoch for a specified wallet from the indexer.
+
+        Args:
+            address (str): Wallet address to be queried.
+
+        Returns:
+            IndexerTokenRewardsData: A data class object containing detailed information about the accrued token rewards.
+        """
+        return self.context.indexer_client.get_token_rewards(address)
+
+    def get_subaccount_linked_signer_rate_limits(
+        self, subaccount: str
+    ) -> IndexerLinkedSignerRateLimitData:
+        """
+        Retrieve the current linked signer and their rate limit for a specified subaccount from the indexer.
+
+        Args:
+            subaccount (str): Unique identifier for the subaccount.
+
+        Returns:
+            IndexerLinkedSignerRateLimitData: A data class object containing information about the current linked signer and their rate limits for the queried subaccount.
+        """
+        return self.context.indexer_client.get_linked_signer_rate_limits(subaccount)
+
+    def get_referral_code(self, subaccount: str) -> IndexerReferralCodeData:
+        """
+        Query the referral code for the specified wallet from the indexer.
+
+        Args:
+            subaccount (str): Unique identifier for the subaccount.
+
+        Returns:
+            IndexerReferralCodeData: A data class object containing the wallet's referral code.
+        """
+        return self.context.indexer_client.get_referral_code(subaccount)
+
+    def get_subaccounts(
+        self,
+        address: Optional[str] = None,
+        start_idx: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> IndexerSubaccountsData:
+        """
+        List nado subaccounts via the indexer.
+
+        Args:
+            address (Optional[str]): An optional wallet address to find all subaccounts associated to it.
+            start_idx (Optional[int]): Optional subaccount id to start from. Used for pagination. Defaults to 0.
+            limit (Optional[int]): Maximum number of subaccounts to return. Defaults to 100. Max of 500.
+
+        Returns:
+            IndexerSubaccountsData: A data class object containing the list of subaccounts found.
+        """
+        return self.context.indexer_client.get_subaccounts(
+            IndexerSubaccountsParams(address=address, start=start_idx, limit=limit)
+        )
+
+    def get_interest_and_funding_payments(
+        self,
+        subaccount: str,
+        product_ids: list[int],
+        limit: int,
+        max_idx: Optional[int] = None,
+    ) -> IndexerInterestAndFundingData:
+        """
+        List interests and funding payments for a subaccount and provided products from the indexer.
+
+        Args:
+            subaccount (str): Subaccount to fetch interest / funding payments for.
+            product_ids (list[int]): List of product IDs to fetch interest / funding payments for.
+            limit (int): Max number of records to return. Max possible of 100.
+            max_idx (Optional[int]): When provided, only return records with idx <= max_idx. Used for pagination.
+
+        Returns:
+            IndexerInterestAndFundingData: A data class object containing the list of interest / funding payments found.
+        """
+        return self.context.indexer_client.get_interest_and_funding_payments(
+            IndexerInterestAndFundingParams(
+                subaccount=subaccount,
+                product_ids=product_ids,
+                limit=limit,
+                max_idx=max_idx,
+            )
+        )

nado_protocol/client/context.py

@@ -0,0 +1,90 @@
+import logging
+from dataclasses import dataclass
+from typing import Optional
+from eth_account import Account
+
+from pydantic import AnyUrl, BaseModel
+from nado_protocol.contracts import NadoContracts, NadoContractsContext
+from eth_account.signers.local import LocalAccount
+from nado_protocol.engine_client import EngineClient
+from nado_protocol.engine_client.types import EngineClientOpts
+from nado_protocol.utils.backend import Signer
+from nado_protocol.indexer_client import IndexerClient
+from nado_protocol.trigger_client import TriggerClient
+from nado_protocol.indexer_client.types import IndexerClientOpts
+from nado_protocol.trigger_client.types import TriggerClientOpts
+
+
+@dataclass
+class NadoClientContext:
+    """
+    Context required to use the Nado client.
+    """
+
+    signer: Optional[LocalAccount]
+    engine_client: EngineClient
+    indexer_client: IndexerClient
+    trigger_client: Optional[TriggerClient]
+    contracts: NadoContracts
+
+
+class NadoClientContextOpts(BaseModel):
+    contracts_context: Optional[NadoContractsContext]
+    rpc_node_url: Optional[AnyUrl]
+    engine_endpoint_url: Optional[AnyUrl]
+    indexer_endpoint_url: Optional[AnyUrl]
+    trigger_endpoint_url: Optional[AnyUrl]
+
+
+def create_nado_client_context(
+    opts: NadoClientContextOpts, signer: Optional[Signer] = None
+) -> NadoClientContext:
+    """
+    Initializes a NadoClientContext instance with the provided signer and options.
+
+    Args:
+        opts (NadoClientContextOpts): Options including endpoints for the engine and indexer clients.
+
+        signer (Signer, optional): An instance of LocalAccount or a private key string for signing transactions.
+
+    Returns:
+        NadoClientContext: The initialized Nado client context.
+
+    Note:
+        This helper attempts to fully set up the engine, indexer and trigger clients, including the necessary verifying contracts
+        to correctly sign executes. If this step fails, it is skipped and can be set up later, while logging the error.
+    """
+    assert opts.contracts_context is not None, "Missing contracts context"
+    assert opts.rpc_node_url is not None, "Missing RPC node URL"
+    assert opts.engine_endpoint_url is not None, "Missing engine endpoint URL"
+    assert opts.indexer_endpoint_url is not None, "Missing indexer endpoint URL"
+
+    signer = Account.from_key(signer) if isinstance(signer, str) else signer
+    engine_client = EngineClient(
+        EngineClientOpts(url=opts.engine_endpoint_url, signer=signer)
+    )
+    trigger_client = None
+    try:
+        contracts = engine_client.get_contracts()
+        engine_client.endpoint_addr = contracts.endpoint_addr
+        engine_client.book_addrs = contracts.book_addrs
+        engine_client.chain_id = int(contracts.chain_id)
+
+        if opts.trigger_endpoint_url is not None:
+            trigger_client = TriggerClient(
+                TriggerClientOpts(url=opts.trigger_endpoint_url, signer=signer)
+            )
+            trigger_client.endpoint_addr = contracts.endpoint_addr
+            trigger_client.book_addrs = contracts.book_addrs
+            trigger_client.chain_id = int(contracts.chain_id)
+    except Exception as e:
+        logging.warning(
+            f"Failed to setup engine client verifying contracts with error: {e}"
+        )
+    return NadoClientContext(
+        signer=signer,
+        engine_client=engine_client,
+        trigger_client=trigger_client,
+        indexer_client=IndexerClient(IndexerClientOpts(url=opts.indexer_endpoint_url)),
+        contracts=NadoContracts(opts.rpc_node_url, opts.contracts_context),
+    )