tonutils 2.0.1b2__py3-none-any.whl → 2.0.1b3__py3-none-any.whl

tonutils/clients/adnl/{provider/builder.py → utils.py}

@@ -11,10 +11,12 @@ from pytoniq_core import (
     SimpleAccount,
     begin_cell,
     check_account_proof,
+    Slice,
+    VmTuple,
 )
 
-from tonutils.types import ContractState, ContractStateInfo
-from tonutils.utils import cell_to_hex
+from tonutils.types import ContractState, ContractStateInfo, StackItems, StackItem
+from tonutils.utils import cell_to_hex, norm_stack_num, norm_stack_cell
 
 
 def build_config_all(config_proof: Cell) -> t.Dict[int, t.Any]:
@@ -109,3 +111,61 @@ def build_contract_state_info(
         info.state = ContractState.NONEXIST
 
     return info
+
+
+def decode_stack(items: t.List[t.Any]) -> StackItems:
+    """
+    Decode VM stack items into internal Python structures.
+
+    Supports:
+    - int → int
+    - Cell/Slice → normalized cell
+    - Address → address cell
+    - VmTuple/list → recursive decode
+    - None → None
+
+    :param items: Raw VM stack items
+    :return: Normalized Python stack values
+    """
+
+    out: StackItems = []
+    for item in items:
+        if item is None:
+            out.append(None)
+        elif isinstance(item, int):
+            out.append(norm_stack_num(item))
+        elif isinstance(item, Address):
+            out.append(item.to_cell())
+        elif isinstance(item, (Cell, Slice)):
+            out.append(norm_stack_cell(item))
+        elif isinstance(item, VmTuple):
+            out.append(decode_stack(item.list))
+        elif isinstance(item, list):
+            out.append(decode_stack(item))
+    return out
+
+
+def encode_stack(items: t.List[StackItem]) -> t.List[t.Any]:
+    """
+    Encode Python stack values into VM-compatible format.
+
+    Supports:
+    - int → int
+    - Cell/Slice → cell/slice
+    - Address → cell slice
+    - list/tuple → recursive encode
+
+    :param items: Normalized Python stack items
+    :return: VM-encoded stack values
+    """
+    out: t.List[t.Any] = []
+    for item in items:
+        if isinstance(item, int):
+            out.append(item)
+        elif isinstance(item, Address):
+            out.append(item.to_cell().to_slice())
+        elif isinstance(item, (Cell, Slice)):
+            out.append(item)
+        elif isinstance(item, (list, tuple)):
+            out.append(encode_stack(list(item)))
+    return out

tonutils/clients/http/__init__.py

@@ -1,18 +1,21 @@
 from .balancer import HttpBalancer
-from .chainstack import ChainstackHttpClient, ChainstackHttpProvider
-from .quicknode import QuicknodeHttpClient, QuicknodeHttpProvider
-from .tatum import TatumHttpClient, TatumHttpProvider
-from .tonapi import TonapiHttpClient, TonapiHttpProvider
-from .toncenter import ToncenterHttpClient, ToncenterHttpProvider
+from .clients import (
+    ChainstackHttpClient,
+    QuicknodeHttpClient,
+    TatumHttpClient,
+    TonapiHttpClient,
+    ToncenterHttpClient,
+)
+from .providers import (
+    TonapiHttpProvider,
+    ToncenterHttpProvider,
+)
 
 __all__ = [
     "HttpBalancer",
     "ChainstackHttpClient",
-    "ChainstackHttpProvider",
     "QuicknodeHttpClient",
-    "QuicknodeHttpProvider",
     "TatumHttpClient",
-    "TatumHttpProvider",
     "TonapiHttpClient",
     "TonapiHttpProvider",
     "ToncenterHttpClient",

tonutils/clients/http/balancer.py

@@ -7,18 +7,19 @@ from contextlib import suppress
 from dataclasses import dataclass
 from itertools import cycle
 
-from pyapiq.exceptions import (
-    APIQException,
-    APIClientResponseError,
-    APIClientServerError,
-    APIClientTooManyRequestsError,
-    RateLimitExceeded,
-)
 from pytoniq_core import Transaction
 
 from tonutils.clients.base import BaseClient
-from tonutils.clients.http.quicknode import QuicknodeHttpClient
-from tonutils.exceptions import ClientError, ClientNotConnectedError
+from tonutils.clients.http.clients.quicknode import QuicknodeHttpClient
+from tonutils.exceptions import (
+    BalancerError,
+    ClientError,
+    TransportError,
+    ProviderError,
+    ProviderResponseError,
+    RunGetMethodError,
+    ProviderTimeoutError,
+)
 from tonutils.types import ClientType, ContractStateInfo, NetworkGlobalID
 
 _T = t.TypeVar("_T")
@@ -52,6 +53,7 @@ class HttpBalancer(BaseClient):
         *,
         network: NetworkGlobalID = NetworkGlobalID.MAINNET,
         clients: t.List[BaseClient],
+        request_timeout: float = 12.0,
     ) -> None:
         """
         Initialize HTTP balancer.
@@ -71,6 +73,8 @@ class HttpBalancer(BaseClient):
 
         :param network: Target TON network (mainnet or testnet)
         :param clients: List of HTTP BaseClient instances to balance between
+        :param request_timeout: Maximum total time in seconds for a balancer operation,
+            including all failover attempts across providers
         """
         self.network = network
 
@@ -83,6 +87,8 @@ class HttpBalancer(BaseClient):
         self._retry_after_base = 1.0
         self._retry_after_max = 10.0
 
+        self._request_timeout = request_timeout
+
     def __init_clients(
         self,
         clients: t.List[BaseClient],
@@ -109,6 +115,25 @@ class HttpBalancer(BaseClient):
             self._clients.append(client)
             self._states.append(state)
 
+    @property
+    def provider(self) -> t.Any:
+        """
+        Provider of the currently selected client.
+
+        :return: Provider instance of chosen HTTP client
+        """
+        c = self._pick_client()
+        return c.provider
+
+    @property
+    def is_connected(self) -> bool:
+        """
+        Check whether at least one underlying client is connected.
+
+        :return: True if any client is connected, otherwise False
+        """
+        return any(c.is_connected for c in self._clients)
+
     @property
     def clients(self) -> t.Tuple[BaseClient, ...]:
         """
@@ -146,27 +171,6 @@ class HttpBalancer(BaseClient):
             if state.retry_after is not None and state.retry_after > now
         )
 
-    @property
-    def provider(self) -> t.Any:
-        """
-        Provider of the currently selected client.
-
-        :return: Provider instance of chosen HTTP client
-        """
-        if not self.is_connected:
-            raise ClientNotConnectedError(self)
-        client = self._pick_client()
-        return client.provider
-
-    @property
-    def is_connected(self) -> bool:
-        """
-        Check whether at least one underlying client is connected.
-
-        :return: True if any client is connected, otherwise False
-        """
-        return any(c.is_connected for c in self._clients)
-
     async def __aenter__(self) -> HttpBalancer:
         """
         Enter async context manager and connect all underlying clients.
@@ -219,7 +223,7 @@ class HttpBalancer(BaseClient):
             height_candidates.append((wait, state.error_count, state))
 
         if not height_candidates:
-            raise ClientError("No available HTTP clients in HttpBalancer.")
+            raise BalancerError("no available HTTP clients")
 
         height_candidates.sort(key=lambda x: (x[0], x[1]))
         best_wait, best_err, _ = height_candidates[0]
@@ -292,39 +296,47 @@ class HttpBalancer(BaseClient):
         :param func: Callable performing an operation using a client
         :return: Result of the successful invocation
         """
-        last_exc: t.Optional[BaseException] = None
-
-        for _ in range(len(self._clients)):
-            if not self.alive_clients:
-                break
-
-            client = self._pick_client()
-
-            try:
-                result = await func(client)
-            except (APIClientTooManyRequestsError, RateLimitExceeded) as e:
-                self._mark_error(client, is_rate_limit=True)
-                last_exc = e
-                continue
-            except APIClientResponseError as e:
-                last_exc = e
-                break
-            except (APIClientServerError, APIQException) as e:
-                self._mark_error(client, is_rate_limit=False)
-                last_exc = e
-                continue
-            except Exception as e:
-                self._mark_error(client, is_rate_limit=False)
-                last_exc = e
-                continue
-
-            self._mark_success(client)
-            return result
-
-        if last_exc is not None:
-            raise last_exc
 
-        raise ClientError("All HTTP clients failed to process request.")
+        async def _run() -> _T:
+            last_exc: t.Optional[BaseException] = None
+
+            for _ in range(len(self._clients)):
+                if not self.alive_clients:
+                    break
+
+                client = self._pick_client()
+
+                try:
+                    result = await func(client)
+
+                except RunGetMethodError:
+                    raise
+                except ProviderResponseError as e:
+                    is_rate_limit = e.code == 429
+                    self._mark_error(client, is_rate_limit=is_rate_limit)
+                    last_exc = e
+                    continue
+                except (TransportError, ProviderError) as e:
+                    self._mark_error(client, is_rate_limit=False)
+                    last_exc = e
+                    continue
+
+                self._mark_success(client)
+                return result
+
+            if last_exc is not None:
+                raise last_exc
+
+            raise ClientError("all HTTP clients failed to process request.")
+
+        try:
+            return await asyncio.wait_for(_run(), timeout=self._request_timeout)
+        except asyncio.TimeoutError as exc:
+            raise ProviderTimeoutError(
+                timeout=self._request_timeout,
+                endpoint="http balancer",
+                operation="failover request",
+            ) from exc
 
     async def _send_boc(self, boc: str) -> None:
         async def _call(client: BaseClient) -> None:

tonutils/clients/http/clients/__init__.py

@@ -0,0 +1,13 @@
+from .chainstack import ChainstackHttpClient
+from .quicknode import QuicknodeHttpClient
+from .tatum import TatumHttpClient
+from .tonapi import TonapiHttpClient
+from .toncenter import ToncenterHttpClient
+
+__all__ = [
+    "ChainstackHttpClient",
+    "QuicknodeHttpClient",
+    "TatumHttpClient",
+    "TonapiHttpClient",
+    "ToncenterHttpClient",
+]

tonutils/clients/http/clients/chainstack.py

@@ -0,0 +1,48 @@
+import typing as t
+
+from aiohttp import ClientSession
+
+from tonutils.clients.http.clients.toncenter import ToncenterHttpClient
+from tonutils.types import NetworkGlobalID, RetryPolicy
+
+
+class ChainstackHttpClient(ToncenterHttpClient):
+
+    def __init__(
+        self,
+        *,
+        network: NetworkGlobalID,
+        http_provider_url: str,
+        timeout: float = 10.0,
+        session: t.Optional[ClientSession] = None,
+        headers: t.Optional[t.Dict[str, str]] = None,
+        cookies: t.Optional[t.Dict[str, str]] = None,
+        rps_limit: t.Optional[int] = None,
+        rps_period: float = 1.0,
+        retry_policy: t.Optional[RetryPolicy] = None,
+    ) -> None:
+        """
+        Initialize Chainstack HTTP client.
+
+        :param network: Target TON network (mainnet or testnet)
+        :param http_provider_url: Chainstack TON HTTP endpoint URL
+            You can obtain a personal endpoint on the Chainstack website: https://chainstack.com/
+        :param timeout: Total request timeout in seconds.
+        :param session: Optional external aiohttp session.
+        :param headers: Default headers for owned session.
+        :param cookies: Default cookies for owned session.
+        :param rps_limit: Optional requests-per-period limit.
+        :param rps_period: Rate limit period in seconds.
+        :param retry_policy: Optional retry policy that defines per-error-code retry rules
+        """
+        super().__init__(
+            network=network,
+            base_url=http_provider_url,
+            timeout=timeout,
+            session=session,
+            headers=headers,
+            cookies=cookies,
+            rps_limit=rps_limit,
+            rps_period=rps_period,
+            retry_policy=retry_policy,
+        )

tonutils/clients/http/clients/quicknode.py

@@ -0,0 +1,47 @@
+import typing as t
+
+from aiohttp import ClientSession
+
+from tonutils.clients.http.clients.toncenter import ToncenterHttpClient
+from tonutils.types import NetworkGlobalID, RetryPolicy
+
+
+class QuicknodeHttpClient(ToncenterHttpClient):
+
+    def __init__(
+        self,
+        *,
+        http_provider_url: str,
+        timeout: float = 10.0,
+        session: t.Optional[ClientSession] = None,
+        headers: t.Optional[t.Dict[str, str]] = None,
+        cookies: t.Optional[t.Dict[str, str]] = None,
+        rps_limit: t.Optional[int] = None,
+        rps_period: float = 1.0,
+        retry_policy: t.Optional[RetryPolicy] = None,
+    ) -> None:
+        """
+        Initialize QuickNode HTTP client.
+
+        :param http_provider_url: QuickNode TON HTTP endpoint URL.
+            You can obtain a personal endpoint on the QuickNode website: https://www.quicknode.com/
+        :param timeout: Total request timeout in seconds.
+        :param session: Optional external aiohttp session.
+        :param headers: Default headers for owned session.
+        :param cookies: Default cookies for owned session.
+        :param rps_limit: Optional requests-per-period limit.
+        :param rps_period: Rate limit period in seconds.
+        :param retry_policy: Optional retry policy that defines per-error-code retry rules
+        """
+
+        super().__init__(
+            network=NetworkGlobalID.MAINNET,
+            base_url=http_provider_url,
+            timeout=timeout,
+            session=session,
+            headers=headers,
+            cookies=cookies,
+            rps_limit=rps_limit,
+            rps_period=rps_period,
+            retry_policy=retry_policy,
+        )

tonutils/clients/http/clients/tatum.py

@@ -0,0 +1,56 @@
+import typing as t
+
+from aiohttp import ClientSession
+
+from tonutils.clients.http.clients.toncenter import ToncenterHttpClient
+from tonutils.types import NetworkGlobalID, RetryPolicy
+
+
+class TatumHttpClient(ToncenterHttpClient):
+
+    def __init__(
+        self,
+        *,
+        network: NetworkGlobalID,
+        api_key: str,
+        base_url: t.Optional[str] = None,
+        timeout: float = 10.0,
+        session: t.Optional[ClientSession] = None,
+        headers: t.Optional[t.Dict[str, str]] = None,
+        cookies: t.Optional[t.Dict[str, str]] = None,
+        rps_limit: t.Optional[int] = None,
+        rps_period: float = 1.0,
+        retry_policy: t.Optional[RetryPolicy] = None,
+    ) -> None:
+        """
+        Initialize Tatum HTTP client.
+
+        :param network: Target TON network (mainnet or testnet)
+        :param api_key: Tatum API key
+            You can get an API key on the Tatum website: https://tatum.io/
+        :param base_url: Optional custom Tatum base URL
+        :param timeout: Total request timeout in seconds.
+        :param session: Optional external aiohttp session.
+        :param headers: Default headers for owned session.
+        :param cookies: Default cookies for owned session.
+        :param rps_limit: Optional requests-per-period limit.
+        :param rps_period: Rate limit period in seconds.
+        :param retry_policy: Optional retry policy that defines per-error-code retry rules
+        """
+        urls = {
+            NetworkGlobalID.MAINNET: "https://ton-mainnet.gateway.tatum.io",
+            NetworkGlobalID.TESTNET: "https://ton-testnet.gateway.tatum.io",
+        }
+        base_url = base_url or urls.get(network)
+        super().__init__(
+            network=network,
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            session=session,
+            headers=headers,
+            cookies=cookies,
+            rps_limit=rps_limit,
+            rps_period=rps_period,
+            retry_policy=retry_policy,
+        )

tonutils/clients/http/{tonapi/client.py → clients/tonapi.py}

@@ -6,15 +6,16 @@ from aiohttp import ClientSession
 from pytoniq_core import Cell, Slice, Transaction
 
 from tonutils.clients.base import BaseClient
-from tonutils.clients.http.tonapi.models import BlockchainMessagePayload
-from tonutils.clients.http.tonapi.provider import TonapiHttpProvider
-from tonutils.clients.http.tonapi.stack import decode_stack, encode_stack
-from tonutils.exceptions import ClientError, ClientNotConnectedError
+from tonutils.clients.http.providers.tonapi.models import BlockchainMessagePayload
+from tonutils.clients.http.providers.tonapi.provider import TonapiHttpProvider
+from tonutils.clients.http.utils import encode_tonapi_stack, decode_tonapi_stack
+from tonutils.exceptions import ClientError, RunGetMethodError
 from tonutils.types import (
     ClientType,
     ContractState,
     ContractStateInfo,
     NetworkGlobalID,
+    RetryPolicy,
 )
 from tonutils.utils import (
     cell_to_hex,
@@ -33,11 +34,13 @@ class TonapiHttpClient(BaseClient):
         network: NetworkGlobalID = NetworkGlobalID.MAINNET,
         api_key: str,
         base_url: t.Optional[str] = None,
-        timeout: int = 10,
+        timeout: float = 10.0,
         session: t.Optional[ClientSession] = None,
+        headers: t.Optional[t.Dict[str, str]] = None,
+        cookies: t.Optional[t.Dict[str, str]] = None,
         rps_limit: t.Optional[int] = None,
         rps_period: float = 1.0,
-        rps_retries: int = 2,
+        retry_policy: t.Optional[RetryPolicy] = None,
     ) -> None:
         """
         Initialize Tonapi HTTP client.
@@ -46,11 +49,13 @@ class TonapiHttpClient(BaseClient):
         :param api_key: Tonapi API key
             You can get an API key on the Tonconsole website: https://tonconsole.com/
         :param base_url: Optional custom Tonapi base URL
-        :param timeout: HTTP request timeout in seconds
-        :param session: Optional externally managed aiohttp.ClientSession
-        :param rps_limit: Optional requests-per-second limit
-        :param rps_period: Time window in seconds for rate limiting
-        :param rps_retries: Number of retries on rate limiting
+        :param timeout: Total request timeout in seconds.
+        :param session: Optional external aiohttp session.
+        :param headers: Default headers for owned session.
+        :param cookies: Default cookies for owned session.
+        :param rps_limit: Optional requests-per-period limit.
+        :param rps_period: Rate limit period in seconds.
+        :param retry_policy: Optional retry policy that defines per-error-code retry rules
         """
         self.network: NetworkGlobalID = network
         self._provider: TonapiHttpProvider = TonapiHttpProvider(
@@ -59,34 +64,24 @@ class TonapiHttpClient(BaseClient):
             base_url=base_url,
             timeout=timeout,
             session=session,
+            headers=headers,
+            cookies=cookies,
             rps_limit=rps_limit,
             rps_period=rps_period,
-            rps_retries=rps_retries,
+            retry_policy=retry_policy,
         )
 
     @property
     def provider(self) -> TonapiHttpProvider:
-        """
-        Underlying Tonapi HTTP provider.
-
-        :return: TonapiHttpProvider instance used for HTTP requests
-        """
-        if not self.is_connected:
-            raise ClientNotConnectedError(self)
         return self._provider
 
     @property
     def is_connected(self) -> bool:
-        """
-        Check whether HTTP session is initialized and open.
-
-        :return: True if session exists and is not closed, False otherwise
-        """
         session = self._provider.session
         return session is not None and not session.closed
 
     async def __aenter__(self) -> TonapiHttpClient:
-        await self._provider.__aenter__()
+        await self._provider.connect()
         return self
 
     async def __aexit__(
@@ -95,7 +90,7 @@ class TonapiHttpClient(BaseClient):
         exc_value: t.Optional[BaseException],
         traceback: t.Optional[t.Any],
     ) -> None:
-        await self._provider.__aexit__(exc_type, exc_value, traceback)
+        await self._provider.close()
 
     async def _send_boc(self, boc: str) -> None:
         payload = BlockchainMessagePayload(boc=boc)
@@ -161,14 +156,19 @@ class TonapiHttpClient(BaseClient):
         result = await self.provider.blockchain_account_method(
             address=address,
             method_name=method_name,
-            args=encode_stack(stack or []),
+            args=encode_tonapi_stack(stack or []),
         )
-        return decode_stack(result.stack or [])
+        if result.exit_code != 0:
+            raise RunGetMethodError(
+                address=address,
+                method_name=method_name,
+                exit_code=result.exit_code,
+            )
+
+        return decode_tonapi_stack(result.stack or [])
 
     async def connect(self) -> None:
-        """Ensure that HTTP session is initialized."""
-        await self._provider.ensure_session()
+        await self._provider.connect()
 
     async def close(self) -> None:
-        """Close HTTP session if it is owned by the provider."""
         await self._provider.close()