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

tonutils/tools/status_monitor/console.py

@@ -0,0 +1,157 @@
+import sys
+import typing as t
+from collections import deque
+from datetime import datetime
+
+from tonutils.tools.status_monitor.models import BlockInfo, LiteServerStatus
+
+_ENTER_ALT_SCREEN = "\033[?1049h"
+_EXIT_ALT_SCREEN = "\033[?1049l"
+_HIDE_CURSOR = "\033[?25l"
+_SHOW_CURSOR = "\033[?25h"
+_MOVE_HOME = "\033[H"
+_CLEAR_SCREEN = "\033[2J"
+_CLEAR_LINE = "\033[K"
+
+
+class Console:
+    HEADERS = [
+        "LS",
+        "HOST",
+        "PORT",
+        "Version",
+        "Time",
+        "Ping",
+        "Connect RTT",
+        "Request RTT",
+        "Last MC Block",
+        "Last BC Block",
+        "Archive From",
+    ]
+    WIDTHS = [2, 15, 5, 7, 19, 7, 11, 11, 16, 16, 12]
+
+    TABLE_TITLE = "Lite Server Status"
+    ERROR_TITLE = "Error Log"
+    MAX_ERROR_LOGS = 10
+
+    def __init__(self) -> None:
+        self._index_width = 2
+        self._is_tty = sys.stdout.isatty()
+        self._error_log: deque[str] = deque(maxlen=self.MAX_ERROR_LOGS)
+        self._prev_errors: t.Dict[int, t.Optional[str]] = {}
+
+    def enter(self) -> None:
+        if self._is_tty:
+            sys.stdout.write(_ENTER_ALT_SCREEN + _HIDE_CURSOR + _CLEAR_SCREEN)
+            sys.stdout.flush()
+
+    def exit(self) -> None:
+        if self._is_tty:
+            sys.stdout.write(_SHOW_CURSOR + _EXIT_ALT_SCREEN)
+            sys.stdout.flush()
+
+    def render(self, statuses: t.List[LiteServerStatus]) -> None:
+        self._update_state(statuses)
+        self._home()
+        self._draw(statuses)
+
+    def _home(self) -> None:
+        if self._is_tty:
+            sys.stdout.write(_MOVE_HOME)
+            sys.stdout.flush()
+
+    def _update_state(self, statuses: t.List[LiteServerStatus]) -> None:
+        self._update_index_width(statuses)
+        self._update_error_log(statuses)
+
+    def _update_index_width(self, statuses: t.List[LiteServerStatus]) -> None:
+        if statuses:
+            self._index_width = max(2, len(str(len(statuses) - 1)))
+
+    def _update_error_log(self, statuses: t.List[LiteServerStatus]) -> None:
+        now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        for status in statuses:
+            prev = self._prev_errors.get(status.server.index)
+            if status.last_error and status.last_error != prev:
+                idx = str(status.server.index).rjust(self._index_width)
+                self._error_log.appendleft(f"  {now} [LS {idx}]: {status.last_error}")
+            self._prev_errors[status.server.index] = status.last_error
+
+    def _get_table_width(self) -> int:
+        return sum(self.WIDTHS) + (len(self.WIDTHS) - 1) * 3
+
+    def _draw(self, statuses: t.List[LiteServerStatus]) -> None:
+        table_width = self._get_table_width()
+        padding = (table_width - len(self.TABLE_TITLE)) // 2
+
+        lines = [
+            "═" * table_width,
+            " " * padding + self.TABLE_TITLE,
+            "═" * table_width,
+            self._format_header(),
+            self._format_separator(),
+        ]
+
+        for status in statuses:
+            lines.append(self._format_row(status))
+
+        lines.append("")
+
+        if self._error_log:
+            lines.append("─" * table_width)
+            lines.append(f"  {self.ERROR_TITLE}:")
+            lines.extend(self._error_log)
+
+        output = (_CLEAR_LINE + "\n").join(lines) + _CLEAR_LINE
+
+        output += "\n" + _CLEAR_LINE
+        sys.stdout.write(output)
+        sys.stdout.flush()
+
+    def _format_header(self) -> str:
+        return " │ ".join(h.ljust(w) for h, w in zip(self.HEADERS, self.WIDTHS))
+
+    def _format_separator(self) -> str:
+        return "─┼─".join("─" * w for w in self.WIDTHS)
+
+    def _format_row(self, status: LiteServerStatus) -> str:
+        cells = [
+            str(status.server.index),
+            status.server.host,
+            str(status.server.port),
+            self._fmt_int(status.version),
+            self._fmt_datetime(status.time),
+            self._fmt_ms(status.ping_ms),
+            self._fmt_ms(status.connect_ms),
+            self._fmt_ms(status.request_ms),
+            self._fmt_block(status.last_mc_block),
+            self._fmt_block(status.last_bc_block),
+            self._fmt_date(status.archive_from),
+        ]
+        return " │ ".join(c.ljust(w) for c, w in zip(cells, self.WIDTHS))
+
+    @staticmethod
+    def _fmt_int(value: t.Optional[int]) -> str:
+        return str(value) if value is not None else "-"
+
+    @staticmethod
+    def _fmt_ms(value: t.Optional[int]) -> str:
+        return f"{value}ms" if value is not None else "-"
+
+    @staticmethod
+    def _fmt_block(block: t.Optional[BlockInfo]) -> str:
+        if block is None:
+            return "-"
+        return f"{block.seqno} / {block.txs_count}"
+
+    @staticmethod
+    def _fmt_date(ts: t.Optional[int]) -> str:
+        if ts is None:
+            return "-"
+        return datetime.fromtimestamp(ts).strftime("%Y-%m-%d")
+
+    @staticmethod
+    def _fmt_datetime(ts: t.Optional[int]) -> str:
+        if ts is None:
+            return "-"
+        return datetime.fromtimestamp(ts).strftime("%Y-%m-%d %H:%M:%S")

tonutils/tools/status_monitor/models.py

@@ -0,0 +1,27 @@
+import typing as t
+
+from pydantic import BaseModel
+
+
+class LiteServer(BaseModel):
+    index: int
+    host: str
+    port: int
+
+
+class BlockInfo(BaseModel):
+    seqno: int
+    txs_count: int
+
+
+class LiteServerStatus(BaseModel):
+    server: LiteServer
+    version: t.Optional[int] = None
+    time: t.Optional[int] = None
+    ping_ms: t.Optional[int] = None
+    connect_ms: t.Optional[int] = None
+    request_ms: t.Optional[int] = None
+    last_mc_block: t.Optional[BlockInfo] = None
+    last_bc_block: t.Optional[BlockInfo] = None
+    archive_from: t.Optional[int] = None
+    last_error: t.Optional[str] = None

tonutils/tools/status_monitor/monitor.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+import asyncio
+import time
+import typing as t
+
+from tonutils.clients import LiteClient
+from tonutils.clients.adnl.provider.models import GlobalConfig
+from tonutils.tools.status_monitor.console import Console
+from tonutils.tools.status_monitor.models import (
+    BlockInfo,
+    LiteServerStatus,
+    LiteServer,
+)
+from tonutils.types import (
+    NetworkGlobalID,
+    WorkchainID,
+    MAINNET_GENESIS_UTIME,
+    MASTERCHAIN_SHARD,
+)
+
+
+class LiteServerMonitor:
+    RENDER_INTERVAL = 0.1
+    RECONNECT_INTERVAL = 30.0
+
+    FAST_UPDATE_INTERVAL = 0.3
+    MEDIUM_UPDATE_INTERVAL = 3.0
+    SLOW_UPDATE_INTERVAL = 10.0
+
+    def __init__(self, clients: t.List[LiteClient]) -> None:
+        self._clients = clients
+        self._console = Console()
+
+        self._archive_cache: t.Dict[int, int] = {}
+        self._statuses: t.Dict[int, LiteServerStatus] = {}
+        self._last_connect: t.Dict[int, float] = {}
+
+        self._tasks: t.List[asyncio.Task[None]] = []
+        self._stop = asyncio.Event()
+
+        self._locks: t.Dict[int, asyncio.Lock] = {}
+
+    @classmethod
+    def from_config(
+        cls,
+        config: GlobalConfig,
+        network: NetworkGlobalID,
+        rps_limit: t.Optional[int] = 100,
+    ) -> LiteServerMonitor:
+        return cls(
+            [
+                LiteClient(
+                    network=network,
+                    ip=server.host,
+                    port=server.port,
+                    public_key=server.id,
+                    rps_limit=rps_limit,
+                )
+                for server in config.liteservers
+            ]
+        )
+
+    @property
+    def statuses(self) -> t.List[LiteServerStatus]:
+        return list(self._statuses.values())
+
+    async def run(self) -> None:
+        self._console.enter()
+        self._init_statuses()
+        self._start_update_loops()
+
+        try:
+            while not self._stop.is_set():
+                self._console.render(self.statuses)
+                await self._sleep(self.RENDER_INTERVAL)
+        finally:
+            self._console.exit()
+
+    async def stop(self) -> None:
+        if self._stop.is_set():
+            return
+        self._stop.set()
+
+        for task in self._tasks:
+            task.cancel()
+        await asyncio.gather(*self._tasks, return_exceptions=True)
+
+        close_tasks = [client.close() for client in self._clients]
+        await asyncio.gather(*close_tasks, return_exceptions=True)
+
+    def _init_statuses(self) -> None:
+        for index, client in enumerate(self._clients):
+            server = LiteServer(
+                index=index,
+                host=client.provider.node.host,
+                port=client.provider.node.port,
+            )
+            self._statuses[index] = LiteServerStatus(server=server)
+            self._locks[index] = asyncio.Lock()
+
+    def _start_update_loops(self) -> None:
+        if self._tasks:
+            return
+
+        for index, client in enumerate(self._clients):
+            fast = self._fast_update_loop(index, client)
+            self._tasks.append(asyncio.create_task(fast))
+
+            medium = self._medium_update_loop(index, client)
+            self._tasks.append(asyncio.create_task(medium))
+
+            slow = self._slow_update_loop(index, client)
+            self._tasks.append(asyncio.create_task(slow))
+
+    async def _ensure_connected(self, index: int, client: LiteClient) -> bool:
+        if client.provider.is_connected:
+            return True
+
+        now = time.monotonic()
+        last_attempt = self._last_connect.get(index, 0.0)
+        if now - last_attempt < self.RECONNECT_INTERVAL:
+            return False
+
+        self._last_connect[index] = now
+        await self._connect(index, client)
+        return client.provider.is_connected
+
+    async def _fast_update_loop(self, index: int, client: LiteClient) -> None:
+        while not self._stop.is_set():
+            if not await self._ensure_connected(index, client):
+                await self._sleep(1.0)
+                continue
+
+            await asyncio.gather(
+                self._update_time(index, client),
+                self._update_last_blocks(index, client),
+                return_exceptions=True,
+            )
+            await self._sleep(self.FAST_UPDATE_INTERVAL)
+
+    async def _medium_update_loop(self, index: int, client: LiteClient) -> None:
+        while not self._stop.is_set():
+            if not client.is_connected:
+                await self._sleep(1.0)
+                continue
+
+            await asyncio.gather(
+                self._update_ping_ms(index, client),
+                self._update_request_ms(index, client),
+                return_exceptions=True,
+            )
+            await self._sleep(self.MEDIUM_UPDATE_INTERVAL)
+
+    async def _slow_update_loop(self, index: int, client: LiteClient) -> None:
+        while not self._stop.is_set():
+            if not client.is_connected:
+                await self._sleep(1.0)
+                continue
+
+            await asyncio.gather(
+                self._update_version(index, client),
+                self._update_archive_from(index, client),
+                return_exceptions=True,
+            )
+            await self._sleep(self.SLOW_UPDATE_INTERVAL)
+
+    async def _sleep(self, seconds: float) -> None:
+        try:
+            await asyncio.wait_for(self._stop.wait(), timeout=seconds)
+        except asyncio.TimeoutError:
+            pass
+
+    async def _set_status(self, index: int, **kwargs: t.Any) -> None:
+        async with self._locks[index]:
+            current = self._statuses[index]
+            self._statuses[index] = current.model_copy(update=kwargs)
+
+    async def _connect(self, index: int, client: LiteClient) -> None:
+        try:
+            start = time.perf_counter()
+            await client.connect()
+            connect_ms = int((time.perf_counter() - start) * 1000)
+            await self._set_status(index, connect_ms=connect_ms, last_error=None)
+        except Exception as e:
+            await self._set_status(index, last_error=str(e))
+
+    async def _update_version(self, index: int, client: LiteClient) -> None:
+        try:
+            version = await client.get_version()
+            await self._set_status(index, version=version)
+        except Exception as e:
+            await self._set_status(index, last_error=str(e))
+
+    async def _update_time(self, index: int, client: LiteClient) -> None:
+        try:
+            server_time = await client.get_time()
+            await self._set_status(index, time=server_time)
+        except Exception as e:
+            await self._set_status(index, last_error=str(e))
+
+    async def _update_ping_ms(self, index: int, client: LiteClient) -> None:
+        try:
+            ping_ms = client.provider.last_ping_ms
+            if ping_ms is not None:
+                await self._set_status(index, ping_ms=ping_ms)
+        except Exception as e:
+            await self._set_status(index, last_error=str(e))
+
+    async def _update_request_ms(self, index: int, client: LiteClient) -> None:
+        try:
+            start = time.perf_counter()
+            await client.get_masterchain_info()
+            request_ms = int((time.perf_counter() - start) * 1000)
+            await self._set_status(index, request_ms=request_ms)
+        except Exception as e:
+            await self._set_status(index, last_error=str(e))
+
+    async def _update_last_blocks(self, index: int, client: LiteClient) -> None:
+        try:
+            mc_block = client.provider.last_mc_block
+            if mc_block is None:
+                return
+
+            mc_txs, shards = await asyncio.gather(
+                client.get_block_transactions_ext(mc_block),
+                client.get_all_shards_info(mc_block),
+            )
+            last_mc_block = BlockInfo(seqno=mc_block.seqno, txs_count=len(mc_txs))
+
+            if shards:
+                bc_block = max(shards, key=lambda b: b.seqno)
+                bc_txs = await client.get_block_transactions_ext(bc_block)
+                last_bc_block = BlockInfo(seqno=bc_block.seqno, txs_count=len(bc_txs))
+                await self._set_status(
+                    index,
+                    last_mc_block=last_mc_block,
+                    last_bc_block=last_bc_block,
+                )
+            else:
+                await self._set_status(index, last_mc_block=last_mc_block)
+
+        except Exception as e:
+            await self._set_status(index, last_error=str(e))
+
+    async def _update_archive_from(self, index: int, client: LiteClient) -> None:
+        try:
+            now = int(time.time())
+            result = await self._find_archive_depth(
+                client, now, self._archive_cache.get(index)
+            )
+            self._archive_cache[index] = result
+            await self._set_status(index, archive_from=result)
+        except Exception as e:
+            await self._set_status(index, last_error=str(e))
+
+    @staticmethod
+    async def _find_archive_depth(
+        client: LiteClient,
+        now: int,
+        cached: t.Optional[int] = None,
+    ) -> int:
+        seconds_per_day = 86400
+        seconds_diff = now - MAINNET_GENESIS_UTIME
+        right = seconds_diff // seconds_per_day
+
+        if cached is not None:
+            cached_days = (now - cached) // seconds_per_day
+            left = cached_days
+            best_days = cached_days
+        else:
+            left = 0
+            best_days = 0
+
+        async def probe(days: int) -> bool:
+            utime = now - days * seconds_per_day
+            try:
+                await client.provider.lookup_block(
+                    workchain=WorkchainID.MASTERCHAIN,
+                    shard=MASTERCHAIN_SHARD,
+                    utime=utime,
+                )
+                return True
+            except (Exception,):
+                return False
+
+        while left <= right:
+            mid = (left + right) // 2
+            if await probe(mid):
+                best_days = mid
+                left = mid + 1
+            else:
+                right = mid - 1
+
+        return now - best_days * seconds_per_day

tonutils/types.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import base64
 import typing as t
+from dataclasses import dataclass
 from enum import Enum
 
 from nacl.signing import SigningKey
@@ -16,21 +17,29 @@ __all__ = [
     "ClientType",
     "ContractState",
     "ContractStateInfo",
-    "DEFAULT_SENDMODE",
-    "DEFAULT_SUBWALLET_ID",
     "DNSCategory",
     "DNSPrefix",
     "MetadataPrefix",
     "NetworkGlobalID",
     "PrivateKey",
     "PublicKey",
+    "RetryPolicy",
+    "RetryRule",
     "SendMode",
     "StackItem",
     "StackItems",
     "StackTag",
     "WorkchainID",
+    "DEFAULT_ADNL_RETRY_POLICY",
+    "DEFAULT_HTTP_RETRY_POLICY",
+    "DEFAULT_SENDMODE",
+    "DEFAULT_SUBWALLET_ID",
+    "MAINNET_GENESIS_UTIME",
+    "MASTERCHAIN_SHARD",
 ]
 
+from tonutils.exceptions import CDN_CHALLENGE_MARKERS
+
 AddressLike = t.Union[Address, str]
 """Type alias for TON address inputs. Accepts either an Address object or string representation."""
 
@@ -375,8 +384,122 @@ class BagID(ADNL):
     """TON Storage bag identifier (32 bytes)."""
 
 
+@dataclass(slots=True, frozen=True)
+class RetryRule:
+    """
+    Retry rule matched by numeric code and/or message substrings.
+
+    Matching:
+    - if codes is set: code must be in codes
+    - if markers is set: any marker must be present in message (case-insensitive)
+    - if both are set: both conditions must match
+
+    Attributes:
+        attempts: Maximum number of retry attempts
+        base_delay: Initial delay before first retry (seconds)
+        cap_delay: Maximum delay between retries (seconds)
+        codes: Error or status codes this rule applies to
+        markers: Case-insensitive substrings matched against error message
+    """
+
+    attempts: int = 3
+    base_delay: float = 0.3
+    cap_delay: float = 3.0
+
+    codes: t.Optional[t.Tuple[int, ...]] = None
+    markers: t.Optional[t.Tuple[str, ...]] = None
+
+    def __post_init__(self) -> None:
+        if self.attempts < 1:
+            raise ValueError("attempts must be >= 1")
+        if self.base_delay < 0:
+            raise ValueError("base_delay must be >= 0")
+        if self.cap_delay < 0:
+            raise ValueError("cap_delay must be >= 0")
+        if self.cap_delay < self.base_delay:
+            raise ValueError("cap_delay must be >= base_delay")
+        if self.markers:
+            norm = tuple(m.strip().lower() for m in self.markers if m and m.strip())
+            object.__setattr__(self, "markers", norm or None)
+
+    def matches(self, code: int, message: t.Any) -> bool:
+        if self.codes is not None and code not in self.codes:
+            return False
+
+        if self.markers:
+            msg = str(message or "").lower()
+            if not any(m in msg for m in self.markers):
+                return False
+
+        return True
+
+    def delay(self, attempt_index: int) -> float:
+        if attempt_index < 0:
+            raise ValueError("attempt_index must be >= 0")
+        d = self.base_delay * (2**attempt_index)
+        return d if d < self.cap_delay else self.cap_delay
+
+
+@dataclass(slots=True, frozen=True)
+class RetryPolicy:
+    """Ordered collection of retry rules (first match wins)."""
+
+    rules: t.Tuple[RetryRule, ...]
+
+    def rule_for(self, code: int, message: t.Any) -> t.Optional[RetryRule]:
+        for r in self.rules:
+            if r.matches(code, message):
+                return r
+        return None
+
+
+DEFAULT_HTTP_RETRY_POLICY = RetryPolicy(
+    rules=(
+        # rate limit exceed
+        RetryRule(
+            codes=(429,),
+            attempts=3,
+            base_delay=0.3,
+            cap_delay=3.0,
+        ),
+        # transient gateway/service failures
+        RetryRule(
+            codes=(502, 503, 504),
+            attempts=3,
+            base_delay=0.5,
+            cap_delay=5.0,
+        ),
+        # CDN/protection/challenge pages (сloudflare, etc.)
+        RetryRule(
+            attempts=3,
+            base_delay=1.0,
+            cap_delay=8.0,
+            markers=tuple(CDN_CHALLENGE_MARKERS.keys()),
+        ),
+    )
+)
+"""Default retry policy for HTTP queries."""
+
+DEFAULT_ADNL_RETRY_POLICY = RetryPolicy(
+    rules=(
+        # rate limit exceed
+        RetryRule(codes=(228, 5556), attempts=3),
+        # block (...) is not in db
+        RetryRule(codes=(651,), attempts=4),
+        # backend node timeout
+        RetryRule(codes=(502,), attempts=5),
+    )
+)
+"""Default retry policy for ADNL queries."""
+
 DEFAULT_SUBWALLET_ID = 698983191
 """Default subwallet ID for wallet contracts."""
 
 DEFAULT_SENDMODE = SendMode.PAY_GAS_SEPARATELY | SendMode.IGNORE_ERRORS
 """Default send mode: pay fees separately and ignore errors."""
+
+MASTERCHAIN_SHARD = -9223372036854775808
+"""Shard identifier for the masterchain (-2^63)."""
+
+MAINNET_GENESIS_UTIME = 1573822385
+"""Unix timestamp of the TON mainnet genesis block (November 15, 2019)."""

tonutils/utils.py

@@ -34,7 +34,7 @@ from tonutils.types import (
 )
 
 if t.TYPE_CHECKING:
-    from tonutils.protocols import ClientProtocol
+    from tonutils.clients.protocol import ClientProtocol
 
 
 __all__ = [
@@ -229,7 +229,7 @@ def norm_stack_cell(
     return maybe_stack_addr(cell)
 
 
-def parse_stack_config(config_slice: Slice) -> dict[int, t.Any]:
+def parse_stack_config(config_slice: Slice) -> t.Dict[int, t.Any]:
     """
     Parse blockchain configuration parameters from a config cell.
 
@@ -514,7 +514,7 @@ class TextCipher:
         """
         Decrypt an encrypted text message.
 
-        Decrypts a message that was encrypted with the encrypt() method.
+        Decrypts a message that was encrypted with the encrypt() method
         Verifies message integrity using HMAC authentication.
 
         :param payload: Encrypted message as Cell, hex string, base64 string, or bytes

{tonutils-2.0.1b2.dist-info → tonutils-2.0.1b4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tonutils
-Version: 2.0.1b2
+Version: 2.0.1b4
 Summary: Tonutils is a high-level, object-oriented Python library designed to facilitate seamless interactions with the TON blockchain.
 Author: nessshon
 Maintainer: nessshon
@@ -26,11 +26,8 @@ Requires-Python: <3.15,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp>=3.7.0
-Requires-Dist: pyapiq>=0.2.1
-Requires-Dist: pycryptodomex~=3.23.0
 Requires-Dist: pydantic<3.0,>=2.0
-Requires-Dist: pynacl~=1.6.0
-Requires-Dist: pytoniq-core~=0.1.45
+Requires-Dist: pytoniq-core~=0.1.46
 Dynamic: license-file
 
 # 📦 Tonutils 2.0 [BETA]