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

tonutils/clients/adnl/provider/provider.py

@@ -96,7 +96,11 @@ class AdnlProvider:
 
     @property
     def is_connected(self) -> bool:
-        """Check whether the underlying transport is connected."""
+        """
+        Whether the underlying transport is currently connected.
+
+        :return: True if connected, False otherwise
+        """
         return self.transport.is_connected
 
     @property
@@ -129,9 +133,9 @@ class AdnlProvider:
     @property
     def last_ping_ms(self) -> t.Optional[int]:
         """
-        Round-trip time of the last ping in milliseconds.
+        Round-trip time of the last successful ping.
 
-        :return: Ping RTT in milliseconds or None if unknown
+        :return: Ping RTT in milliseconds, or None if unknown
         """
         if self.last_ping_rtt is None:
             return None
@@ -165,10 +169,7 @@ class AdnlProvider:
             return
 
         self.loop = asyncio.get_running_loop()
-        try:
-            await self.transport.connect()
-        except Exception as exc:
-            raise ProviderError(f"adnl connect failed ({self.node.endpoint})") from exc
+        await self.transport.connect()
 
         tasks = [self.reader.start(), self.pinger.start(), self.updater.start()]
         await asyncio.gather(*tasks, return_exceptions=True)
@@ -239,19 +240,13 @@ class AdnlProvider:
                 raise ProviderTimeoutError(
                     timeout=self.request_timeout,
                     endpoint=self.node.endpoint,
-                    operation="adnl query",
-                ) from exc
-            except asyncio.CancelledError as exc:
-                raise ProviderError(
-                    f"adnl provider closed ({self.node.endpoint})"
+                    operation="request",
                 ) from exc
 
             if not isinstance(resp, dict):
-                raise ProviderError(
-                    f"adnl invalid response type ({self.node.endpoint})"
-                )
-
+                raise ProviderError(f"invalid response type: {type(resp).__name__}")
             return resp
+
         finally:
             if query_id_key in self.pending:
                 del self.pending[query_id_key]
@@ -419,7 +414,7 @@ class AdnlProvider:
         self,
         workchain: WorkchainID,
         shard: int,
-        seqno: int = -1,
+        seqno: t.Optional[int] = None,
         lt: t.Optional[int] = None,
         utime: t.Optional[int] = None,
         *,
@@ -430,42 +425,45 @@ class AdnlProvider:
 
         :param workchain: Workchain identifier
         :param shard: Shard identifier
-        :param seqno: Block seqno or -1 to ignore
+        :param seqno: Block sequence number
         :param lt: Logical time filter
         :param utime: UNIX time filter
         :param priority: Whether to use priority slot in the limiter
         :return: Tuple of BlockIdExt and deserialized Block
         """
         mode = 0
-        if seqno != -1:
+        block_seqno = 0
+
+        if seqno is not None:
             mode = 1
+            block_seqno = seqno
         if lt is not None:
             mode = 2
         if utime is not None:
             mode = 4
 
         data = {
+            "mode": mode,
             "id": {
-                "workchain": workchain.value,
+                "workchain": workchain,
                 "shard": shard,
-                "seqno": seqno,
+                "seqno": block_seqno,
             },
             "lt": lt,
-            "mode": mode,
             "utime": utime,
         }
+
         result = await self.send_liteserver_query(
-            method="lookupBlock",
+            "lookupBlock",
             data=data,
             priority=priority,
         )
 
-        cell = Cell.one_from_boc(result["header_proof"])
+        block_id = BlockIdExt.from_dict(result["id"])
+        header_proof = Cell.one_from_boc(result["header_proof"])
+        block = Block.deserialize(header_proof[0].begin_parse())
 
-        return (
-            BlockIdExt.from_dict(result["id"]),
-            Block.deserialize(cell[0].begin_parse()),
-        )
+        return block_id, block
 
     async def get_block_header(
         self,
@@ -480,23 +478,25 @@ class AdnlProvider:
         :param priority: Whether to use priority slot in the limiter
         :return: Tuple of BlockIdExt and deserialized Block
         """
+        data = {"id": block.to_dict(), "mode": 0}
+
         result = await self.send_liteserver_query(
-            method="getBlockHeader",
-            data={"id": block.to_dict(), "mode": 0},
+            "getBlockHeader",
+            data=data,
             priority=priority,
         )
 
-        cell = Cell.one_from_boc(result["header_proof"])
-        return (
-            BlockIdExt.from_dict(result["id"]),
-            Block.deserialize(cell[0].begin_parse()),
-        )
+        block_id = BlockIdExt.from_dict(result["id"])
+        header_proof = Cell.one_from_boc(result["header_proof"])
+        block_obj = Block.deserialize(header_proof[0].begin_parse())
+
+        return block_id, block_obj
 
     async def get_block_transactions_ext(
         self,
         block: BlockIdExt,
-        *,
         count: int = 1024,
+        *,
         priority: bool = False,
     ) -> t.List[Transaction]:
         """
@@ -508,7 +508,6 @@ class AdnlProvider:
         :return: List of deserialized Transaction objects
         """
         mode = 39
-
         result = await self.send_liteserver_query(
             method="listBlockTransactionsExt",
             data={
@@ -632,9 +631,7 @@ class AdnlProvider:
 
         exit_code = result.get("exit_code")
         if exit_code is None:
-            raise ProviderError(
-                f"runSmcMethod: missing `exit_code` in response ({self.node.endpoint})"
-            )
+            raise ProviderError("runSmcMethod: missing exit_code in response")
 
         if exit_code != 0:
             raise RunGetMethodError(
@@ -735,7 +732,7 @@ class AdnlProvider:
         """
         if count > 16:
             raise ClientError(
-                "`get_raw_transactions` supports up to 16 transactions per request"
+                "get_transactions supports up to 16 transactions per request"
             )
 
         data = {
@@ -759,7 +756,7 @@ class AdnlProvider:
             curr_hash = cell.get_hash(0).hex()
             if curr_hash != prev_tr_hash:
                 raise ClientError(
-                    "Transaction hash mismatch in `raw_get_transactions`: "
+                    f"transaction hash mismatch: "
                     f"expected {prev_tr_hash}, got {curr_hash}"
                 )
 

tonutils/clients/adnl/provider/transport.py

@@ -16,7 +16,7 @@ from pytoniq_core.crypto.ciphers import (
 )
 
 from tonutils.clients.adnl.provider.models import LiteServer
-from tonutils.exceptions import TransportError
+from tonutils.exceptions import TransportError, NotConnectedError
 
 
 class AdnlTcpTransport:
@@ -41,6 +41,7 @@ class AdnlTcpTransport:
         :param node: Liteserver configuration with host, port, and public key
         :param connect_timeout: Timeout in seconds for connection
         """
+        self.node = node
         self.server = Server(
             host=node.host,
             port=node.port,
@@ -67,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:
         """
@@ -125,12 +134,12 @@ class AdnlTcpTransport:
     async def _flush(self) -> None:
         """Flush the TCP write buffer."""
         if self.writer is None:
-            raise TransportError("transport state: writer is not initialized")
+            raise self._error("send", "writer not initialized")
         try:
             await self.writer.drain()
         except ConnectionError as exc:
             await self.close()
-            raise TransportError(f"transport io: drain failed") from exc
+            raise self._error("send", "connection lost") from exc
 
     def encrypt_frame(self, data: bytes) -> bytes:
         """
@@ -139,9 +148,7 @@ class AdnlTcpTransport:
         :param data: Plaintext frame bytes
         """
         if self.enc_cipher is None:
-            raise TransportError(
-                "transport cipher: encryption cipher is not initialized"
-            )
+            raise self._error("encrypt", "cipher not initialized")
         return aes_ctr_encrypt(self.enc_cipher, data)
 
     def decrypt_frame(self, data: bytes) -> bytes:
@@ -151,15 +158,13 @@ class AdnlTcpTransport:
         :param data: Encrypted frame bytes
         """
         if self.dec_cipher is None:
-            raise TransportError(
-                "transport cipher: decryption cipher is not initialized"
-            )
+            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 TransportError("transport state: already connected")
+            raise self._error("connect", "already connected")
 
         self.loop = asyncio.get_running_loop()
 
@@ -169,14 +174,14 @@ class AdnlTcpTransport:
                 timeout=self.connect_timeout,
             )
         except asyncio.TimeoutError as exc:
-            raise TransportError(
-                f"transport connect: timeout {self.connect_timeout}s"
+            raise self._error(
+                "connect", f"timeout after {self.connect_timeout}s"
             ) from exc
         except OSError as exc:
-            raise TransportError(f"transport connect: failed") from exc
+            raise self._error("connect", "connection refused") from exc
 
         if self.writer is None or self.reader is None:
-            raise TransportError(f"transport connect: failed to initialize streams")
+            raise self._error("connect", "stream init failed")
 
         try:
             handshake = self._build_handshake()
@@ -189,13 +194,12 @@ class AdnlTcpTransport:
                     timeout=self.connect_timeout,
                 )
             except asyncio.IncompleteReadError as exc:
-                raise TransportError(
-                    f"transport handshake: remote closed connection"
-                ) from exc
+                raise self._error("handshake", "remote closed") from exc
             except asyncio.TimeoutError as exc:
-                raise TransportError(
-                    f"transport handshake: timeout {self.connect_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(),
@@ -214,7 +218,7 @@ class AdnlTcpTransport:
         :param payload: Raw ADNL packet bytes
         """
         if not self._connected or self.writer is None:
-            raise TransportError("transport state: not connected")
+            raise NotConnectedError()
 
         packet = self._build_frame(payload)
         encrypted = self.encrypt_frame(packet)
@@ -229,7 +233,7 @@ class AdnlTcpTransport:
         Blocks until a complete packet is available from the background reader.
         """
         if not self._connected:
-            raise TransportError("transport state: not connected")
+            raise NotConnectedError()
         return await self._incoming.get()
 
     async def read_frame(self, discard: bool = False) -> t.Optional[bytes]:
@@ -244,24 +248,24 @@ class AdnlTcpTransport:
         :param discard: If True, validates but returns None (used for handshake ack)
         """
         if self.reader is None:
-            raise TransportError("transport state: 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 TransportError(f"transport frame: 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 TransportError("transport frame: 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 TransportError("transport frame: checksum mismatch")
+            raise self._error("recv", "checksum mismatch")
 
         if discard:
             return None
@@ -278,6 +282,7 @@ class AdnlTcpTransport:
         except asyncio.CancelledError:
             pass
         except (
+            TransportError,
             asyncio.IncompleteReadError,
             ConnectionAbortedError,
             ConnectionError,

tonutils/clients/base.py

@@ -272,7 +272,11 @@ class BaseClient(abc.ABC):
 
         blen = len(domain) * 8
         rlen = t.cast(int, res[0])
-        cell = t.cast(Cell, res[1])
+
+        cell = res[1]
+
+        if cell is None:
+            return None
 
         if rlen % 8 != 0 or rlen > blen:
             raise ValueError(f"Invalid resolved length: result {rlen}, bytes {blen}.")

tonutils/exceptions.py

@@ -23,7 +23,30 @@ class TonutilsError(Exception):
 
 
 class TransportError(TonutilsError):
-    """Raise on transport-level failures (I/O, handshake, crypto, socket)."""
+    """Transport-level failure with structured context.
+
+    Covers: TCP connect, ADNL handshake, send/recv, crypto failures.
+
+    :param endpoint: Server address as "host:port"
+    :param operation: What was attempted ("connect", "handshake", "send", "recv")
+    :param reason: Why it failed ("timeout 2.0s", "connection refused", etc.)
+    """
+
+    endpoint: str
+    operation: str
+    reason: str
+
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        operation: str,
+        reason: str,
+    ) -> None:
+        self.endpoint = endpoint
+        self.operation = operation
+        self.reason = reason
+        super().__init__(f"{operation} failed at {endpoint}: {reason}")
 
 
 class ProviderError(TonutilsError):
@@ -39,23 +62,24 @@ class BalancerError(TonutilsError):
 
 
 class NotConnectedError(TonutilsError, RuntimeError):
-    """Raise when an operation requires an active connection.
+    """Raise when an operation requires an active connection."""
 
-    Typically means the underlying client/provider is not connected yet or was closed.
-    """
+    endpoint: t.Optional[str]
 
-    def __init__(self) -> None:
-        super().__init__("not connected. Use `await connect()` or `async with ...`.")
+    def __init__(self, endpoint: t.Optional[str] = None) -> None:
+        self.endpoint = endpoint
+        if endpoint:
+            super().__init__(f"not connected to {endpoint}")
+        else:
+            super().__init__("not connected")
 
 
 class ProviderTimeoutError(ProviderError, asyncio.TimeoutError):
     """Raise when a provider operation exceeds its timeout.
 
-    Used for both ADNL and HTTP providers.
-
     :param timeout: Timeout in seconds.
     :param endpoint: Endpoint identifier (URL or host:port).
-    :param operation: Operation label (e.g. "adnl query", "http request").
+    :param operation: Operation label (e.g. "request", "connect").
     """
 
     timeout: float
@@ -63,19 +87,15 @@ class ProviderTimeoutError(ProviderError, asyncio.TimeoutError):
     operation: str
 
     def __init__(self, *, timeout: float, endpoint: str, operation: str) -> None:
-        self.timeout = float(timeout)
+        self.timeout = timeout
         self.endpoint = endpoint
         self.operation = operation
-        super().__init__(f"{operation} timed out after {timeout}s: {endpoint}")
+        super().__init__(f"{operation} timed out after {timeout}s at {endpoint}")
 
 
 class ProviderResponseError(ProviderError):
     """Raise when a backend returns an error response.
 
-    This is a normalized provider error for:
-    - HTTP status codes (e.g. 429/5xx)
-    - lite-server numeric error codes
-
     :param code: Backend code (HTTP status or lite-server code).
     :param message: Backend error description.
     :param endpoint: Endpoint identifier (URL or host:port).
@@ -86,7 +106,7 @@ class ProviderResponseError(ProviderError):
     endpoint: str
 
     def __init__(self, *, code: int, message: str, endpoint: str) -> None:
-        self.code = int(code)
+        self.code = code
         self.message = message
         self.endpoint = endpoint
         super().__init__(f"request failed with code {code} at {endpoint}: {message}")
@@ -111,13 +131,10 @@ class RetryLimitError(ProviderError):
         max_attempts: int,
         last_error: ProviderError,
     ) -> None:
-        self.attempts = int(attempts)
-        self.max_attempts = int(max_attempts)
+        self.attempts = attempts
+        self.max_attempts = max_attempts
         self.last_error = last_error
-        super().__init__(
-            f"retry exhausted ({self.attempts}/{self.max_attempts}). "
-            f"Last error: {last_error}"
-        )
+        super().__init__(f"retry exhausted ({attempts}/{max_attempts}): {last_error}")
 
 
 class ContractError(ClientError):
@@ -133,7 +150,6 @@ class ContractError(ClientError):
     def __init__(self, target: t.Any, message: str) -> None:
         self.target = target
         self.message = message
-
         name = (
             target.__name__ if isinstance(target, type) else target.__class__.__name__
         )
@@ -143,10 +159,6 @@ class ContractError(ClientError):
 class StateNotLoadedError(ContractError):
     """Raise when a contract wrapper requires state that is not loaded.
 
-    Typical cases:
-    - state_info not fetched
-    - state_data not decoded/available
-
     :param contract: Contract instance related to the failure.
     :param missing: Missing field name (e.g. "state_info", "state_data").
     """
@@ -174,9 +186,9 @@ class RunGetMethodError(ClientError):
     def __init__(self, *, address: str, method_name: str, exit_code: int) -> None:
         self.address = address
         self.method_name = method_name
-        self.exit_code = int(exit_code)
+        self.exit_code = exit_code
         super().__init__(
-            f"get-method `{method_name}` failed for {address} (exit code {self.exit_code})."
+            f"get-method '{method_name}' failed for {address} with exit code {exit_code}"
         )
 
 
@@ -198,5 +210,3 @@ CDN_CHALLENGE_MARKERS: t.Dict[str, str] = {
     "503 service unavailable": "Service temporarily unavailable (proxy or CDN).",
     "ddos": "Possible DDoS protection or mitigation page.",
 }
-"""Markers for detecting CDN / proxy challenge and anti-DDoS responses, 
-used for error normalization and default retry policies."""

tonutils/tools/__init__.py

@@ -0,0 +1,6 @@
+from . import block_scanner, status_monitor
+
+__all__ = [
+    "block_scanner",
+    "status_monitor",
+]

tonutils/tools/block_scanner/__init__.py

@@ -0,0 +1,16 @@
+from .events import (
+    BlockEvent,
+    TransactionEvent,
+    TransactionsEvent,
+)
+from .scanner import BlockScanner
+from .where import Where
+
+
+__all__ = [
+    "BlockScanner",
+    "BlockEvent",
+    "TransactionEvent",
+    "TransactionsEvent",
+    "Where",
+]

tonutils/tools/block_scanner/annotations.py

@@ -0,0 +1,23 @@
+import typing as t
+
+from tonutils.tools.block_scanner.events import (
+    BlockEvent,
+    EventBase,
+    TransactionEvent,
+    TransactionsEvent,
+)
+
+TEvent = t.TypeVar("TEvent", bound=EventBase)
+
+Handler = t.Callable[[TEvent], t.Awaitable[None]]
+Where = t.Callable[[TEvent], t.Union[bool, t.Awaitable[bool]]]
+
+BlockWhere = t.Callable[[BlockEvent], t.Union[bool, t.Awaitable[bool]]]
+TransactionWhere = t.Callable[[TransactionEvent], t.Union[bool, t.Awaitable[bool]]]
+TransactionsWhere = t.Callable[[TransactionsEvent], t.Union[bool, t.Awaitable[bool]]]
+
+AnyHandler = t.Callable[[EventBase], t.Awaitable[None]]
+AnyWhere = t.Callable[[EventBase], t.Union[bool, t.Awaitable[bool]]]
+
+HandlerEntry = t.Tuple[AnyHandler, t.Optional[AnyWhere]]
+Decorator = t.Callable[[Handler[TEvent]], Handler[TEvent]]