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

tonutils/clients/adnl/provider/transport.py

@@ -16,13 +16,7 @@ from pytoniq_core.crypto.ciphers import (
 )
 
 from tonutils.clients.adnl.provider.models import LiteServer
-from tonutils.exceptions import (
-    AdnlHandshakeError,
-    AdnlTransportCipherError,
-    AdnlTransportFrameError,
-    AdnlTransportStateError,
-    AdnlTransportError,
-)
+from tonutils.exceptions import TransportError, NotConnectedError
 
 
 class AdnlTcpTransport:
@@ -40,13 +34,14 @@ class AdnlTcpTransport:
     for incoming frames.
     """
 
-    def __init__(self, node: LiteServer, timeout: int) -> None:
+    def __init__(self, node: LiteServer, connect_timeout: float) -> None:
         """
         Initialize ADNL TCP transport for a liteserver connection.
 
         :param node: Liteserver configuration with host, port, and public key
-        :param timeout: Timeout in seconds for connection and I/O operations
+        :param connect_timeout: Timeout in seconds for connection
         """
+        self.node = node
         self.server = Server(
             host=node.host,
             port=node.port,
@@ -54,7 +49,7 @@ class AdnlTcpTransport:
         )
         self.client = Client(Client.generate_ed25519_private_key())
 
-        self.timeout = timeout
+        self.connect_timeout = connect_timeout
         self.enc_cipher = None
         self.dec_cipher = None
 
@@ -73,6 +68,14 @@ class AdnlTcpTransport:
         """Check if the transport is currently connected."""
         return self._connected
 
+    def _error(self, operation: str, reason: str) -> TransportError:
+        """Create TransportError with endpoint context."""
+        return TransportError(
+            endpoint=self.node.endpoint,
+            operation=operation,
+            reason=reason,
+        )
+
     @staticmethod
     def _build_frame(data: bytes) -> bytes:
         """
@@ -131,12 +134,12 @@ class AdnlTcpTransport:
     async def _flush(self) -> None:
         """Flush the TCP write buffer."""
         if self.writer is None:
-            raise AdnlTransportStateError("`writer` is not initialized")
+            raise self._error("send", "writer not initialized")
         try:
             await self.writer.drain()
-        except ConnectionError:
+        except ConnectionError as exc:
             await self.close()
-            raise
+            raise self._error("send", "connection lost") from exc
 
     def encrypt_frame(self, data: bytes) -> bytes:
         """
@@ -145,7 +148,7 @@ class AdnlTcpTransport:
         :param data: Plaintext frame bytes
         """
         if self.enc_cipher is None:
-            raise AdnlTransportCipherError("`encryption`")
+            raise self._error("encrypt", "cipher not initialized")
         return aes_ctr_encrypt(self.enc_cipher, data)
 
     def decrypt_frame(self, data: bytes) -> bytes:
@@ -155,22 +158,30 @@ class AdnlTcpTransport:
         :param data: Encrypted frame bytes
         """
         if self.dec_cipher is None:
-            raise AdnlTransportCipherError("`decryption`")
+            raise self._error("decrypt", "cipher not initialized")
         return aes_ctr_decrypt(self.dec_cipher, data)
 
     async def connect(self) -> None:
         """Establish encrypted connection to the liteserver."""
         if self._connected:
-            raise AdnlTransportStateError("already connected")
+            raise self._error("connect", "already connected")
 
         self.loop = asyncio.get_running_loop()
 
-        self.reader, self.writer = await asyncio.wait_for(
-            asyncio.open_connection(self.server.host, self.server.port),
-            timeout=self.timeout,
-        )
+        try:
+            self.reader, self.writer = await asyncio.wait_for(
+                asyncio.open_connection(self.server.host, self.server.port),
+                timeout=self.connect_timeout,
+            )
+        except asyncio.TimeoutError as exc:
+            raise self._error(
+                "connect", f"timeout after {self.connect_timeout}s"
+            ) from exc
+        except OSError as exc:
+            raise self._error("connect", "connection refused") from exc
+
         if self.writer is None or self.reader is None:
-            raise AdnlTransportError("failed to initialize TCP streams")
+            raise self._error("connect", "stream init failed")
 
         try:
             handshake = self._build_handshake()
@@ -180,16 +191,15 @@ class AdnlTcpTransport:
             try:
                 await asyncio.wait_for(
                     self.read_frame(discard=True),
-                    timeout=self.timeout,
+                    timeout=self.connect_timeout,
                 )
             except asyncio.IncompleteReadError as exc:
-                raise AdnlHandshakeError(
-                    "ADNL handshake failed: remote closed connection"
-                ) from exc
+                raise self._error("handshake", "remote closed") from exc
             except asyncio.TimeoutError as exc:
-                raise AdnlHandshakeError(
-                    f"Timed out waiting for initial ADNL handshake ({self.timeout}s)"
+                raise self._error(
+                    "handshake", f"timeout after {self.connect_timeout}s"
                 ) from exc
+
             self._connected = True
             self._reader_task = asyncio.create_task(
                 self.frame_reader_loop(),
@@ -208,7 +218,7 @@ class AdnlTcpTransport:
         :param payload: Raw ADNL packet bytes
         """
         if not self._connected or self.writer is None:
-            raise AdnlTransportStateError("transport is not connected")
+            raise NotConnectedError()
 
         packet = self._build_frame(payload)
         encrypted = self.encrypt_frame(packet)
@@ -223,7 +233,7 @@ class AdnlTcpTransport:
         Blocks until a complete packet is available from the background reader.
         """
         if not self._connected:
-            raise AdnlTransportStateError("transport is not connected")
+            raise NotConnectedError()
         return await self._incoming.get()
 
     async def read_frame(self, discard: bool = False) -> t.Optional[bytes]:
@@ -238,24 +248,24 @@ class AdnlTcpTransport:
         :param discard: If True, validates but returns None (used for handshake ack)
         """
         if self.reader is None:
-            raise AdnlTransportStateError("`reader` is not initialized")
+            raise self._error("recv", "reader not initialized")
 
         length_enc = await self.reader.readexactly(4)
         length_dec = self.decrypt_frame(length_enc)
         data_len = int.from_bytes(length_dec, "little")
 
         if data_len <= 0:
-            raise AdnlTransportFrameError(f"non-positive length `{data_len}`")
+            raise self._error("recv", f"invalid frame length: {data_len}")
 
         data_enc = await self.reader.readexactly(data_len)
         data = self.decrypt_frame(data_enc)
 
         if len(data) < 32:
-            raise AdnlTransportFrameError("frame is too short")
+            raise self._error("recv", f"frame too short: {len(data)} bytes")
 
         payload, checksum = data[:-32], data[-32:]
         if hashlib.sha256(payload).digest() != checksum:
-            raise AdnlTransportFrameError("checksum mismatch")
+            raise self._error("recv", "checksum mismatch")
 
         if discard:
             return None
@@ -272,6 +282,7 @@ class AdnlTcpTransport:
         except asyncio.CancelledError:
             pass
         except (
+            TransportError,
             asyncio.IncompleteReadError,
             ConnectionAbortedError,
             ConnectionError,

tonutils/clients/adnl/provider/workers/base.py

@@ -63,8 +63,6 @@ class BaseWorker(ABC):
             await self._run()
         except asyncio.CancelledError:
             pass
-        except (Exception,):
-            pass
         finally:
             self._running = False
 

tonutils/clients/adnl/provider/workers/pinger.py

@@ -66,7 +66,7 @@ class PingerWorker(BaseWorker):
         await self.provider.transport.send_adnl_packet(payload)
 
         start = self.provider.loop.time()
-        await asyncio.wait_for(fut, timeout=self.provider.timeout)
+        await asyncio.wait_for(fut, timeout=self.provider.request_timeout)
         end = self.provider.loop.time()
 
         self._last_time = end

tonutils/clients/adnl/provider/workers/reader.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from tonutils.clients.adnl.provider.workers.base import BaseWorker
-from tonutils.exceptions import AdnlServerError
+from tonutils.exceptions import ProviderResponseError
 
 
 class ReaderWorker(BaseWorker):
@@ -35,9 +35,10 @@ class ReaderWorker(BaseWorker):
         payload = root.get("answer", root)
 
         if "code" in payload and "message" in payload:
-            exception = AdnlServerError(
+            exception = ProviderResponseError(
                 code=payload["code"],
                 message=payload["message"],
+                endpoint=self.provider.node.endpoint,
             )
             fut.set_exception(exception)
         else:

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,
+        )