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

tonutils/clients/adnl/provider/provider.py

@@ -18,12 +18,6 @@ from pytoniq_core import (
 from pytoniq_core.crypto.ciphers import get_random
 from pytoniq_core.crypto.crc import crc16
 
-from tonutils.clients.adnl.provider.builder import (
-    build_contract_state_info,
-    build_shard_account,
-    build_config_all,
-)
-from tonutils.clients.adnl.provider.limiter import PriorityLimiter
 from tonutils.clients.adnl.provider.models import LiteServer, MasterchainInfo
 from tonutils.clients.adnl.provider.transport import AdnlTcpTransport
 from tonutils.clients.adnl.provider.workers import (
@@ -31,35 +25,38 @@ from tonutils.clients.adnl.provider.workers import (
     ReaderWorker,
     UpdaterWorker,
 )
+from tonutils.clients.adnl.utils import (
+    build_contract_state_info,
+    build_shard_account,
+    build_config_all,
+)
+from tonutils.clients.limiter import RateLimiter
 from tonutils.exceptions import (
-    AdnlHandshakeError,
-    AdnlProviderConnectError,
-    AdnlServerError,
-    AdnlProviderMissingBlockError,
-    AdnlProviderResponseError,
-    AdnlProviderClosedError,
     ClientError,
-    ClientNotConnectedError,
-    RateLimitExceededError,
+    NotConnectedError,
+    ProviderError,
     RunGetMethodError,
+    ProviderTimeoutError,
+    RetryLimitError,
+    ProviderResponseError,
+)
+from tonutils.types import (
+    ContractStateInfo,
+    RetryPolicy,
+    WorkchainID,
 )
-from tonutils.types import ContractStateInfo, WorkchainID
 
 
 class AdnlProvider:
-    """
-    ADNL-based provider for TON lite-servers.
-
-    Handles encrypted TCP transport, ping and masterchain updates, and exposes
-    a high-level API for lite-server queries.
-    """
+    """ADNL-based provider for TON lite-servers."""
 
     def __init__(
         self,
         node: LiteServer,
-        timeout: int = 10,
-        rps_retries: t.Optional[int] = None,
-        limiter: t.Optional[PriorityLimiter] = None,
+        connect_timeout: float = 2.0,
+        request_timeout: float = 10.0,
+        limiter: t.Optional[RateLimiter] = None,
+        retry_policy: t.Optional[RetryPolicy] = None,
     ) -> None:
         """
         Initialize ADNL provider for a specific lite-server.
@@ -71,14 +68,15 @@ class AdnlProvider:
             - dTON telegram bot: https://t.me/dtontech_bot (https://dton.io/)
 
         :param node: LiteServer configuration (host, port, public key)
-        :param timeout: Timeout in seconds for queries
-        :param rps_retries: Number of retries on rate limiting
+        :param connect_timeout: Timeout in seconds for connect/reconnect
+        :param request_timeout: Timeout in seconds for queries
         :param limiter: Optional priority-aware rate limiter
+        :param retry_policy: Optional retry policy that defines per-error-code retry rules
         """
         self.node = node
-        self.timeout = timeout
-        self.rps_retries = rps_retries
-        self.transport = AdnlTcpTransport(self.node, self.timeout)
+        self.connect_timeout = connect_timeout
+        self.request_timeout = request_timeout
+        self.transport = AdnlTcpTransport(self.node, self.connect_timeout)
         self.loop: t.Optional[asyncio.AbstractEventLoop] = None
 
         self.tl_schemas = TlGenerator.with_default_schemas().generate()
@@ -92,16 +90,13 @@ class AdnlProvider:
 
         self.pending: t.Dict[str, asyncio.Future] = {}
 
+        self._limiter: t.Optional[RateLimiter] = limiter
+        self._retry_policy: t.Optional[RetryPolicy] = retry_policy
         self._connect_lock: asyncio.Lock = asyncio.Lock()
-        self._limiter: t.Optional[PriorityLimiter] = limiter
 
     @property
     def is_connected(self) -> bool:
-        """
-        Check whether the underlying transport is connected.
-
-        :return: True if ADNL transport is connected, False otherwise
-        """
+        """Check whether the underlying transport is connected."""
         return self.transport.is_connected
 
     @property
@@ -172,18 +167,8 @@ class AdnlProvider:
         self.loop = asyncio.get_running_loop()
         try:
             await self.transport.connect()
-        except AdnlHandshakeError as exc:
-            raise AdnlProviderConnectError(
-                host=self.node.host,
-                port=self.node.port,
-                message=str(exc),
-            ) from exc
-        except OSError as exc:
-            raise AdnlProviderConnectError(
-                host=self.node.host,
-                port=self.node.port,
-                message=str(exc),
-            ) from exc
+        except Exception as exc:
+            raise ProviderError(f"adnl connect failed ({self.node.endpoint})") from exc
 
         tasks = [self.reader.start(), self.pinger.start(), self.updater.start()]
         await asyncio.gather(*tasks, return_exceptions=True)
@@ -221,124 +206,99 @@ class AdnlProvider:
         async with self._connect_lock:
             await self._do_close()
 
-    async def send_adnl_query(
-        self,
-        query: bytes,
-        priority: bool = False,
-    ) -> dict:
+    async def _send_once_adnl_query(self, query: bytes, *, priority: bool) -> dict:
         """
-        Send a raw ADNL query with retry support for rate-limit and missing-block conditions.
-
-        Retries temporary overload errors (228, 5556) and missing-block errors (651)
-        before returning a response or raising an exception.
+        Send a single ADNL query.
 
         :param query: Encoded ADNL TL-query bytes
         :param priority: Whether to use priority slot in the limiter
         :return: Lite-server response payload as a decoded dictionary
         """
-        return await self._send_with_missing_block_retries(query, priority)
+        if not self.is_connected or self.loop is None:
+            raise NotConnectedError()
 
-    async def _send_with_missing_block_retries(
-        self,
-        query: bytes,
-        priority: bool = False,
-    ) -> dict:
-        """
-        Internal wrapper adding retry handling for missing-block errors (code 651).
+        if self._limiter is not None:
+            await self._limiter.acquire(priority=priority)
 
-        Performs a fixed number of attempts with exponential backoff on 651 and
-        delegates transport-level and rate-limit handling to `_send_with_rps_retries`.
+        query_id = get_random(32)
+        packet = self.tl_schemas.serialize(
+            self.adnl_query_tl_schema,
+            {"query_id": query_id, "query": query},
+        )
 
-        :param query: Encoded ADNL TL-query bytes
-        :param priority: Whether to use priority slot in the limiter
-        :return: Lite-server response payload as a dictionary
-        """
-        max_651_retries = 5
-        error_message = "unknown lite-server error"
+        query_id_key = query_id[::-1].hex()
+        fut: asyncio.Future[t.Any] = self.loop.create_future()
+        self.pending[query_id_key] = fut
+
+        try:
+            await self.transport.send_adnl_packet(packet)
 
-        for attempt in range(max_651_retries):
             try:
-                return await self._send_with_rps_retries(query, priority=priority)
-            except AdnlServerError as e:
-                if e.code != 651:
-                    raise
-                error_message = e.message
-                if attempt < max_651_retries - 1:
-                    await asyncio.sleep(0.3 * (2**attempt))
-                    continue
-                break
-
-        raise AdnlProviderMissingBlockError(
-            attempts=max_651_retries,
-            host=self.node.host,
-            port=self.node.port,
-            message=error_message,
-        )
+                resp = await asyncio.wait_for(fut, timeout=self.request_timeout)
+            except asyncio.TimeoutError as exc:
+                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})"
+                ) from exc
+
+            if not isinstance(resp, dict):
+                raise ProviderError(
+                    f"adnl invalid response type ({self.node.endpoint})"
+                )
+
+            return resp
+        finally:
+            if query_id_key in self.pending:
+                del self.pending[query_id_key]
 
-    async def _send_with_rps_retries(
+    async def send_adnl_query(
         self,
         query: bytes,
         priority: bool = False,
     ) -> dict:
         """
-        Internal ADNL request executor with retry handling for rate-limit errors.
+        Send a raw ADNL query with retry handling based on retry policy.
 
-        Performs a bounded number of attempts on lite-server overload conditions
-        (error codes 228 and 5556) using exponential backoff before failing.
+        On server error, retries the request according to the rule associated
+        with the received error code. If no rule matches, or retry attempts are
+        exhausted, the error is raised.
 
         :param query: Encoded ADNL TL-query bytes
         :param priority: Whether to use priority slot in the limiter
-        :return: Lite-server response payload as a dictionary
+        :return: Lite-server response payload as a decoded dictionary
         """
-        if not self.is_connected or self.loop is None:
-            raise ClientNotConnectedError(self)
-
-        attempts = max(self.rps_retries or 0, 1)
-        for attempt in range(attempts):
-            if self._limiter is not None:
-                await self._limiter.acquire(priority=priority)
-
-            query_id = get_random(32)
-            packet = self.tl_schemas.serialize(
-                self.adnl_query_tl_schema,
-                {
-                    "query_id": query_id,
-                    "query": query,
-                },
-            )
-            query_id_key = query_id[::-1].hex()
-            fut: asyncio.Future = self.loop.create_future()
-            self.pending[query_id_key] = fut
+        attempts: t.Dict[int, int] = {}
 
+        while True:
             try:
-                await self.transport.send_adnl_packet(packet)
-                try:
-                    resp = await asyncio.wait_for(fut, timeout=self.timeout)
-                except asyncio.TimeoutError:
+                return await self._send_once_adnl_query(query, priority=priority)
+
+            except ProviderResponseError as e:
+                policy = self._retry_policy
+                if policy is None:
                     raise
-                except asyncio.CancelledError as exc:
-                    raise AdnlProviderClosedError(
-                        host=self.node.host,
-                        port=self.node.port,
-                    ) from exc
-                except AdnlServerError as e:
-                    if e.code in (228, 5556):
-                        if attempt < attempts - 1:
-                            await asyncio.sleep(0.3 * (2**attempt))
-                            continue
-                        break
+
+                rule = policy.rule_for(e.code, e.message)
+                if rule is None:
                     raise
-                if not isinstance(resp, dict):
-                    raise AdnlProviderResponseError(
-                        host=self.node.host,
-                        port=self.node.port,
-                    )
-                return resp
-            finally:
-                if query_id_key in self.pending:
-                    del self.pending[query_id_key]
-
-        raise RateLimitExceededError(attempts)
+
+                key = id(rule)
+                n = attempts.get(key, 0) + 1
+                attempts[key] = n
+
+                if n >= rule.attempts:
+                    raise RetryLimitError(
+                        attempts=n,
+                        max_attempts=rule.attempts,
+                        last_error=e,
+                    ) from e
+
+                await asyncio.sleep(rule.delay(n - 1))
 
     async def send_liteserver_query(
         self,
@@ -507,6 +467,92 @@ class AdnlProvider:
             Block.deserialize(cell[0].begin_parse()),
         )
 
+    async def get_block_header(
+        self,
+        block: BlockIdExt,
+        *,
+        priority: bool = False,
+    ) -> t.Tuple[BlockIdExt, Block]:
+        """
+        Fetch and deserialize block header by BlockIdExt.
+
+        :param block: BlockIdExt to query
+        :param priority: Whether to use priority slot in the limiter
+        :return: Tuple of BlockIdExt and deserialized Block
+        """
+        result = await self.send_liteserver_query(
+            method="getBlockHeader",
+            data={"id": block.to_dict(), "mode": 0},
+            priority=priority,
+        )
+
+        cell = Cell.one_from_boc(result["header_proof"])
+        return (
+            BlockIdExt.from_dict(result["id"]),
+            Block.deserialize(cell[0].begin_parse()),
+        )
+
+    async def get_block_transactions_ext(
+        self,
+        block: BlockIdExt,
+        *,
+        count: int = 1024,
+        priority: bool = False,
+    ) -> t.List[Transaction]:
+        """
+        Fetch extended block transactions list.
+
+        :param block: Target block identifier
+        :param count: Maximum number of transactions per request
+        :param priority: Whether to use priority slot in the limiter
+        :return: List of deserialized Transaction objects
+        """
+        mode = 39
+
+        result = await self.send_liteserver_query(
+            method="listBlockTransactionsExt",
+            data={
+                "id": block.to_dict(),
+                "mode": mode,
+                "count": count,
+                "want_proof": b"",
+            },
+            priority=priority,
+        )
+
+        transactions: t.List[Transaction] = []
+
+        def _append(result_data: dict) -> None:
+            if not result_data.get("transactions"):
+                return
+            for cell in Cell.from_boc(result_data["transactions"]):
+                transactions.append(Transaction.deserialize(cell.begin_parse()))
+
+        _append(result)
+
+        while result.get("incomplete"):
+            mode = 167
+            after = {
+                "account": transactions[-1].account_addr_hex,
+                "lt": transactions[-1].lt,
+            }
+
+            result = await self.send_liteserver_query(
+                method="listBlockTransactionsExt",
+                data={
+                    "id": block.to_dict(),
+                    "mode": mode,
+                    "count": count,
+                    "want_proof": b"",
+                    "after": after,
+                },
+                priority=priority,
+            )
+
+            _append(result)
+
+        return transactions
+
     async def get_all_shards_info(
         self,
         block: t.Optional[BlockIdExt] = None,
@@ -586,13 +632,13 @@ class AdnlProvider:
 
         exit_code = result.get("exit_code")
         if exit_code is None:
-            raise AdnlServerError(
-                code=-1,
-                message="RunGetMethod: missing `exit_code` in response",
+            raise ProviderError(
+                f"runSmcMethod: missing `exit_code` in response ({self.node.endpoint})"
             )
+
         if exit_code != 0:
             raise RunGetMethodError(
-                address=address,
+                address=address.to_str(),
                 method_name=method_name,
                 exit_code=exit_code,
             )
@@ -676,7 +722,7 @@ class AdnlProvider:
         from_hash: str,
         *,
         priority: bool = False,
-    ) -> list[Transaction]:
+    ) -> t.List[Transaction]:
         """
         Fetch a chain of transactions for an account.
 
@@ -707,7 +753,7 @@ class AdnlProvider:
         cells = Cell.from_boc(result["transactions"])
 
         prev_tr_hash = from_hash
-        transactions: list[Transaction] = []
+        transactions: t.List[Transaction] = []
 
         for i, cell in enumerate(cells):
             curr_hash = cell.get_hash(0).hex()

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
 
 
 class AdnlTcpTransport:
@@ -40,12 +34,12 @@ 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.server = Server(
             host=node.host,
@@ -54,7 +48,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
 
@@ -131,12 +125,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 TransportError("transport state: writer is not initialized")
         try:
             await self.writer.drain()
-        except ConnectionError:
+        except ConnectionError as exc:
             await self.close()
-            raise
+            raise TransportError(f"transport io: drain failed") from exc
 
     def encrypt_frame(self, data: bytes) -> bytes:
         """
@@ -145,7 +139,9 @@ class AdnlTcpTransport:
         :param data: Plaintext frame bytes
         """
         if self.enc_cipher is None:
-            raise AdnlTransportCipherError("`encryption`")
+            raise TransportError(
+                "transport cipher: encryption cipher is not initialized"
+            )
         return aes_ctr_encrypt(self.enc_cipher, data)
 
     def decrypt_frame(self, data: bytes) -> bytes:
@@ -155,22 +151,32 @@ class AdnlTcpTransport:
         :param data: Encrypted frame bytes
         """
         if self.dec_cipher is None:
-            raise AdnlTransportCipherError("`decryption`")
+            raise TransportError(
+                "transport cipher: decryption cipher is 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 TransportError("transport state: 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 TransportError(
+                f"transport connect: timeout {self.connect_timeout}s"
+            ) from exc
+        except OSError as exc:
+            raise TransportError(f"transport connect: failed") from exc
+
         if self.writer is None or self.reader is None:
-            raise AdnlTransportError("failed to initialize TCP streams")
+            raise TransportError(f"transport connect: failed to initialize streams")
 
         try:
             handshake = self._build_handshake()
@@ -180,15 +186,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"
+                raise TransportError(
+                    f"transport handshake: remote closed connection"
                 ) from exc
             except asyncio.TimeoutError as exc:
-                raise AdnlHandshakeError(
-                    f"Timed out waiting for initial ADNL handshake ({self.timeout}s)"
+                raise TransportError(
+                    f"transport handshake: timeout {self.connect_timeout}s"
                 ) from exc
             self._connected = True
             self._reader_task = asyncio.create_task(
@@ -208,7 +214,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 TransportError("transport state: not connected")
 
         packet = self._build_frame(payload)
         encrypted = self.encrypt_frame(packet)
@@ -223,7 +229,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 TransportError("transport state: not connected")
         return await self._incoming.get()
 
     async def read_frame(self, discard: bool = False) -> t.Optional[bytes]:
@@ -238,24 +244,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 TransportError("transport state: reader is 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 TransportError(f"transport frame: non-positive 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 TransportError("transport frame: frame is too short")
 
         payload, checksum = data[:-32], data[-32:]
         if hashlib.sha256(payload).digest() != checksum:
-            raise AdnlTransportFrameError("checksum mismatch")
+            raise TransportError("transport frame: checksum mismatch")
 
         if discard:
             return None

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: