tonutils 2.0.1b2__py3-none-any.whl → 2.0.1b4__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,15 +90,16 @@ 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.
+        Whether the underlying transport is currently connected.
 
-        :return: True if ADNL transport is connected, False otherwise
+        :return: True if connected, False otherwise
         """
         return self.transport.is_connected
 
@@ -134,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
@@ -170,20 +169,7 @@ class AdnlProvider:
             return
 
         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
+        await self.transport.connect()
 
         tasks = [self.reader.start(), self.pinger.start(), self.updater.start()]
         await asyncio.gather(*tasks, return_exceptions=True)
@@ -221,124 +207,93 @@ 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="request",
+                ) from exc
+
+            if not isinstance(resp, dict):
+                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]
 
-    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,
@@ -459,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,
         *,
@@ -470,43 +425,133 @@ 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(
+            "lookupBlock",
+            data=data,
+            priority=priority,
+        )
+
+        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 block_id, block
+
+    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
+        """
+        data = {"id": block.to_dict(), "mode": 0}
+
         result = await self.send_liteserver_query(
-            method="lookupBlock",
+            "getBlockHeader",
             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_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]:
+        """
+        Fetch extended block transactions list.
 
-        return (
-            BlockIdExt.from_dict(result["id"]),
-            Block.deserialize(cell[0].begin_parse()),
+        :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 +631,11 @@ 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("runSmcMethod: missing exit_code in response")
+
         if exit_code != 0:
             raise RunGetMethodError(
-                address=address,
+                address=address.to_str(),
                 method_name=method_name,
                 exit_code=exit_code,
             )
@@ -676,7 +719,7 @@ class AdnlProvider:
         from_hash: str,
         *,
         priority: bool = False,
-    ) -> list[Transaction]:
+    ) -> t.List[Transaction]:
         """
         Fetch a chain of transactions for an account.
 
@@ -689,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 = {
@@ -707,13 +750,13 @@ 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()
             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}"
                 )