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

tonutils/__meta__.py

@@ -1 +1 @@
-__version__ = "2.0.1b3"
+__version__ = "2.0.1b5"

tonutils/cli.py

@@ -0,0 +1,111 @@
+import argparse
+import asyncio
+import typing as t
+
+from tonutils.__meta__ import __version__
+from tonutils.clients.adnl.provider.config import (
+    get_mainnet_global_config,
+    get_testnet_global_config,
+    load_global_config,
+)
+from tonutils.tools.status_monitor import LiteServerMonitor
+from tonutils.types import NetworkGlobalID
+
+NETWORK_MAP: t.Dict[str, NetworkGlobalID] = {
+    "mainnet": NetworkGlobalID.MAINNET,
+    "testnet": NetworkGlobalID.TESTNET,
+}
+
+
+def parse_network(value: str) -> NetworkGlobalID:
+    value = value.lower().strip()
+    if value not in NETWORK_MAP:
+        raise argparse.ArgumentTypeError(f"Unknown network: {value}")
+    return NETWORK_MAP[value]
+
+
+def cmd_status(args: argparse.Namespace) -> None:
+    if args.config:
+        config = load_global_config(args.config)
+    else:
+        config_getter = {
+            NetworkGlobalID.MAINNET: get_mainnet_global_config,
+            NetworkGlobalID.TESTNET: get_testnet_global_config,
+        }
+        config = config_getter[args.network]()
+
+    async def _run() -> None:
+        monitor = LiteServerMonitor.from_config(
+            config=config,
+            network=args.network,
+            rps_limit=args.rps,
+        )
+        try:
+            await monitor.run()
+        finally:
+            await monitor.stop()
+
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        pass
+
+
+def _create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tonutils",
+        description="Tonutils CLI.",
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"tonutils {__version__}",
+    )
+
+    subs = parser.add_subparsers(dest="command", metavar="command")
+
+    status = subs.add_parser(
+        "status",
+        help="Monitor lite-servers status.",
+    )
+    status.add_argument(
+        "-n",
+        "--network",
+        type=parse_network,
+        metavar="NET",
+        default=NetworkGlobalID.MAINNET,
+        help="mainnet (default) or testnet",
+    )
+    status.add_argument(
+        "-c",
+        "--config",
+        type=str,
+        metavar="PATH",
+        help="Config file path or URL",
+    )
+    status.add_argument(
+        "-r",
+        "--rps",
+        type=int,
+        metavar="N",
+        default=100,
+        help="Requests per second (default: 100)",
+    )
+    status.set_defaults(func=cmd_status)
+
+    return parser
+
+
+def main() -> None:
+    parser = _create_parser()
+    args = parser.parse_args()
+
+    if hasattr(args, "func"):
+        args.func(args)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

tonutils/clients/__init__.py

@@ -1,6 +1,6 @@
 from .adnl import (
-    AdnlBalancer,
-    AdnlClient,
+    LiteBalancer,
+    LiteClient,
     AdnlProvider,
 )
 from .http import (
@@ -15,8 +15,8 @@ from .http import (
 )
 
 __all__ = [
-    "AdnlBalancer",
-    "AdnlClient",
+    "LiteBalancer",
+    "LiteClient",
     "AdnlProvider",
     "HttpBalancer",
     "ChainstackHttpClient",

tonutils/clients/adnl/__init__.py

@@ -1,9 +1,9 @@
-from .balancer import AdnlBalancer
-from .client import AdnlClient
+from .balancer import LiteBalancer
+from .client import LiteClient
 from .provider import AdnlProvider
 
 __all__ = [
-    "AdnlBalancer",
-    "AdnlClient",
+    "LiteBalancer",
+    "LiteClient",
     "AdnlProvider",
 ]

tonutils/clients/adnl/balancer.py

@@ -9,7 +9,7 @@ from itertools import cycle
 
 from pytoniq_core import Address, BlockIdExt, Block, Transaction
 
-from tonutils.clients.adnl.client import AdnlClient
+from tonutils.clients.adnl.client import LiteClient
 from tonutils.clients.adnl.provider import AdnlProvider
 from tonutils.clients.adnl.provider.config import (
     get_mainnet_global_config,
@@ -40,21 +40,21 @@ _T = t.TypeVar("_T")
 
 
 @dataclass
-class AdnlClientState:
+class LiteClientState:
     """
-    Internal state container for an ADNL client.
+    Internal state container for a lite-server client.
 
     Tracks error count and cooldown timeout for retry scheduling.
     """
 
-    client: AdnlClient
+    client: LiteClient
     retry_after: t.Optional[float] = None
     error_count: int = 0
 
 
-class AdnlBalancer(BaseClient):
+class LiteBalancer(BaseClient):
     """
-    Multi-provider ADNL client with automatic failover and load balancing.
+    Multi-client lite-server balancer with automatic failover and load balancing.
 
     Selects the best available lite-server using height, ping metrics and
     round-robin tie-breaking.
@@ -66,14 +66,14 @@ class AdnlBalancer(BaseClient):
         self,
         *,
         network: NetworkGlobalID = NetworkGlobalID.MAINNET,
-        clients: t.List[AdnlClient],
+        clients: t.List[LiteClient],
         connect_timeout: float = 2.0,
         request_timeout: float = 12.0,
     ) -> None:
         """
-        Initialize ADNL balancer.
+        Initialize lite-server balancer.
 
-        It is recommended to build underlying AdnlClient instances from
+        It is recommended to build underlying LiteClient instances from
         private lite-server configurations for better stability and performance.
         You can obtain private lite-server configs from:
             - Tonconsole website: https://tonconsole.com/
@@ -82,15 +82,15 @@ class AdnlBalancer(BaseClient):
         Public free lite-server data may also be used via `from_network_config()`.
 
         :param network: Target TON network (mainnet or testnet)
-        :param clients: List of AdnlClient instances to balance between
+        :param clients: List of LiteClient instances to balance between
         :param connect_timeout: Timeout in seconds for connect/reconnect attempts
         :param request_timeout: Maximum total time in seconds for a balancer operation,
-            including all failover attempts across providers
+            including all failover attempts across lite-servers
         """
         self.network: NetworkGlobalID = network
 
-        self._clients: t.List[AdnlClient] = []
-        self._states: t.List[AdnlClientState] = []
+        self._clients: t.List[LiteClient] = []
+        self._states: t.List[LiteClientState] = []
         self.__init_clients(clients)
 
         self._rr = cycle(self._clients)
@@ -106,30 +106,30 @@ class AdnlBalancer(BaseClient):
 
     def __init_clients(
         self,
-        clients: t.List[AdnlClient],
+        clients: t.List[LiteClient],
     ) -> None:
         """
-        Validate and register input ADNL clients.
+        Validate and register input lite-server clients.
 
         Ensures correct client type and network assignment.
         """
         for client in clients:
             if client.TYPE != ClientType.ADNL:
                 raise ClientError(
-                    "AdnlBalancer can work only with ADNL clients, "
+                    "LiteBalancer can work only with LiteClient instances, "
                     f"got {client.__class__.__name__}."
                 )
 
             client.network = self.network
 
-            state = AdnlClientState(client=client)
+            state = LiteClientState(client=client)
             self._clients.append(client)
             self._states.append(state)
 
     @property
     def provider(self) -> AdnlProvider:
         """
-        Provider of the currently selected ADNL client.
+        Provider of the currently selected lite-server client.
 
         :return: AdnlProvider instance of chosen client
         """
@@ -139,27 +139,27 @@ class AdnlBalancer(BaseClient):
     @property
     def is_connected(self) -> bool:
         """
-        Check whether at least one underlying ADNL client is connected.
+        Check whether at least one underlying lite-server 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[AdnlClient, ...]:
+    def clients(self) -> t.Tuple[LiteClient, ...]:
         """
-        List of all registered ADNL clients.
+        List of all registered lite-server clients.
 
-        :return: Tuple of AdnlClient objects
+        :return: Tuple of LiteClient objects
         """
         return tuple(self._clients)
 
     @property
-    def alive_clients(self) -> t.Tuple[AdnlClient, ...]:
+    def alive_clients(self) -> t.Tuple[LiteClient, ...]:
         """
-        ADNL clients that are allowed to send requests now.
+        Lite-server clients that are allowed to send requests now.
 
-        :return: Tuple of available AdnlClient instances
+        :return: Tuple of available LiteClient instances
         """
         now = time.monotonic()
         return tuple(
@@ -170,11 +170,11 @@ class AdnlBalancer(BaseClient):
         )
 
     @property
-    def dead_clients(self) -> t.Tuple[AdnlClient, ...]:
+    def dead_clients(self) -> t.Tuple[LiteClient, ...]:
         """
-        ADNL clients currently in cooldown or disconnected.
+        Lite-server clients currently in cooldown or disconnected.
 
-        :return: Tuple of unavailable AdnlClient instances
+        :return: Tuple of unavailable LiteClient instances
         """
         now = time.monotonic()
         return tuple(
@@ -184,7 +184,7 @@ class AdnlBalancer(BaseClient):
             or (state.retry_after is not None and state.retry_after > now)
         )
 
-    async def __aenter__(self) -> AdnlBalancer:
+    async def __aenter__(self) -> LiteBalancer:
         """
         Enter async context manager and connect underlying clients.
 
@@ -217,9 +217,9 @@ class AdnlBalancer(BaseClient):
         rps_period: float = 1.0,
         rps_per_client: bool = False,
         retry_policy: t.Optional[RetryPolicy] = None,
-    ) -> AdnlBalancer:
+    ) -> LiteBalancer:
         """
-        Build ADNL balancer from a lite-server config.
+        Build lite-server balancer from a configuration.
 
         For best performance, it is recommended to use a private lite-server
         configuration. You can obtain private configs from:
@@ -235,14 +235,14 @@ class AdnlBalancer(BaseClient):
         :param request_timeout: Maximum total time in seconds for a single balancer operation,
             including all failover attempts across clients.
         :param client_connect_timeout: Timeout in seconds for connect/handshake performed by an
-            individual ADNL client.
+            individual lite-server client.
         :param client_request_timeout: Timeout in seconds for a single request executed by an
-            individual ADNL client.
+            individual lite-server client.
         :param rps_limit: Optional requests-per-second limit
         :param rps_period: Time window in seconds for RPS limit
         :param rps_per_client: Whether to create per-client limiters
         :param retry_policy: Optional retry policy that defines per-error-code retry rules
-        :return: Configured AdnlBalancer instance
+        :return: Configured LiteBalancer instance
         """
         if isinstance(config, dict):
             config = GlobalConfig(**config)
@@ -251,8 +251,8 @@ class AdnlBalancer(BaseClient):
         if rps_limit is not None and not rps_per_client:
             shared_limiter = RateLimiter(rps_limit, rps_period)
 
-        clients: t.List[AdnlClient] = []
-        for node in config.liteservers:
+        clients: t.List[LiteClient] = []
+        for ls in config.liteservers:
             limiter = (
                 RateLimiter(rps_limit, rps_period)
                 if rps_per_client and rps_limit is not None
@@ -261,11 +261,11 @@ class AdnlBalancer(BaseClient):
             client_rps_limit = rps_limit if rps_per_client else None
 
             clients.append(
-                AdnlClient(
+                LiteClient(
                     network=network,
-                    ip=node.host,
-                    port=node.port,
-                    public_key=node.id,
+                    ip=ls.host,
+                    port=ls.port,
+                    public_key=ls.id,
                     connect_timeout=client_connect_timeout,
                     request_timeout=client_request_timeout,
                     rps_limit=client_rps_limit,
@@ -295,9 +295,9 @@ class AdnlBalancer(BaseClient):
         rps_period: float = 1.0,
         rps_per_client: bool = False,
         retry_policy: t.Optional[RetryPolicy] = None,
-    ) -> AdnlBalancer:
+    ) -> LiteBalancer:
         """
-        Build ADNL balancer using global config fetched from ton.org.
+        Build lite-server balancer using global config fetched from ton.org.
 
         Public lite-servers available in the global network configuration are
         free to use but may be unstable under load. For higher reliability and
@@ -312,14 +312,14 @@ class AdnlBalancer(BaseClient):
         :param request_timeout: Maximum total time in seconds for a single balancer operation,
             including all failover attempts across clients.
         :param client_connect_timeout: Timeout in seconds for connect/handshake performed by an
-            individual ADNL client.
+            individual lite-server client.
         :param client_request_timeout: Timeout in seconds for a single request executed by an
-            individual ADNL client.
+            individual lite-server client.
         :param rps_limit: Optional requests-per-second limit
         :param rps_period: Time window in seconds for RPS limit
         :param rps_per_client: Whether to create per-client limiters
         :param retry_policy: Optional retry policy that defines per-error-code retry rules
-        :return: Configured AdnlBalancer instance
+        :return: Configured LiteBalancer instance
         """
         config_getters = {
             NetworkGlobalID.MAINNET: get_mainnet_global_config,
@@ -339,9 +339,9 @@ class AdnlBalancer(BaseClient):
             retry_policy=retry_policy,
         )
 
-    def _pick_client(self) -> AdnlClient:
+    def _pick_client(self) -> LiteClient:
         """
-        Select the best available ADNL client.
+        Select the best available lite-server client.
 
         Selection criteria:
         - highest known masterchain seqno
@@ -358,7 +358,7 @@ class AdnlBalancer(BaseClient):
                 int,
                 t.Optional[float],
                 t.Optional[float],
-                AdnlClient,
+                LiteClient,
             ]
         ] = []
 
@@ -391,7 +391,7 @@ class AdnlBalancer(BaseClient):
 
         return alive[0]
 
-    def _mark_success(self, client: AdnlClient) -> None:
+    def _mark_success(self, client: LiteClient) -> None:
         """
         Reset error state for a successful client.
 
@@ -403,7 +403,7 @@ class AdnlBalancer(BaseClient):
                 state.retry_after = None
                 break
 
-    def _mark_error(self, client: AdnlClient, is_rate_limit: bool) -> None:
+    def _mark_error(self, client: LiteClient, is_rate_limit: bool) -> None:
         """
         Update error state and schedule retry cooldown.
 
@@ -437,7 +437,7 @@ class AdnlBalancer(BaseClient):
         Execute a provider operation with automatic failover.
 
         Iterates through available lite-servers until one succeeds
-        or all providers fail.
+        or all fail.
 
         :param func: Callable performing an operation using an AdnlProvider
         :return: Result of the successful invocation
@@ -484,14 +484,14 @@ class AdnlBalancer(BaseClient):
             if last_exc is not None:
                 raise last_exc
 
-            raise BalancerError("all lite-server providers failed to process request")
+            raise BalancerError("all lite-servers 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="adnl balancer",
+                endpoint="lite balancer",
                 operation="failover request",
             ) from exc
 
@@ -600,12 +600,12 @@ class AdnlBalancer(BaseClient):
 
     async def _health_loop(self) -> None:
         """
-        Periodically attempt to reconnect dead ADNL clients.
+        Periodically attempt to reconnect dead lite-server clients.
 
         Runs until cancelled.
         """
 
-        async def _recon(c: AdnlClient) -> None:
+        async def _recon(c: LiteClient) -> None:
             with suppress(Exception):
                 await asyncio.wait_for(
                     c.reconnect(),
@@ -629,7 +629,7 @@ class AdnlBalancer(BaseClient):
             self._ensure_health_task()
             return
 
-        async def _con(client: AdnlClient) -> None:
+        async def _con(client: LiteClient) -> None:
             with suppress(asyncio.TimeoutError):
                 await asyncio.wait_for(
                     client.connect(),
@@ -723,7 +723,7 @@ class AdnlBalancer(BaseClient):
         self,
         workchain: WorkchainID,
         shard: int,
-        seqno: int = -1,
+        seqno: t.Optional[int] = None,
         lt: t.Optional[int] = None,
         utime: t.Optional[int] = None,
     ) -> t.Tuple[BlockIdExt, Block]:
@@ -732,7 +732,7 @@ class AdnlBalancer(BaseClient):
 
         :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
         :return: Tuple of BlockIdExt and deserialized Block

tonutils/clients/adnl/client.py

@@ -27,8 +27,8 @@ from tonutils.types import (
 )
 
 
-class AdnlClient(BaseClient):
-    """TON blockchain client using ADNL lite-server as transport."""
+class LiteClient(BaseClient):
+    """TON blockchain client for lite-server communication over ADNL provider."""
 
     TYPE = ClientType.ADNL
 
@@ -47,7 +47,7 @@ class AdnlClient(BaseClient):
         limiter: t.Optional[RateLimiter] = None,
     ) -> None:
         """
-        Initialize ADNL client.
+        Initialize lite-server client.
 
         To obtain lite-server connection parameters (ip, port, public_key),
         it is recommended to use a private configuration for better stability
@@ -91,20 +91,20 @@ class AdnlClient(BaseClient):
         """
         Underlying ADNL provider.
 
-        :return: AdnlProvider instance used for all ADNL requests
+        :return: AdnlProvider instance used for all lite-server requests
         """
         return self._provider
 
     @property
     def is_connected(self) -> bool:
         """
-        Check whether ADNL transport is connected.
+        Check whether the lite-server connection is established.
 
         :return: True if connected, False otherwise
         """
         return self._provider.is_connected
 
-    async def __aenter__(self) -> AdnlClient:
+    async def __aenter__(self) -> LiteClient:
         await self.connect()
         return self
 
@@ -128,9 +128,9 @@ class AdnlClient(BaseClient):
         rps_limit: t.Optional[int] = None,
         rps_period: float = 1.0,
         retry_policy: t.Optional[RetryPolicy] = None,
-    ) -> AdnlClient:
+    ) -> LiteClient:
         """
-        Create ADNL client from a lite-server configuration.
+        Create lite-server client from a configuration.
 
         To obtain lite-server connection parameters, it is recommended to use
         a private lite-server configuration for better stability and performance.
@@ -150,16 +150,16 @@ class AdnlClient(BaseClient):
         :param rps_limit: Optional requests-per-second limit for this client
         :param rps_period: Time window in seconds for RPS limit
         :param retry_policy: Optional retry policy that defines per-error-code retry rules
-        :return: Configured AdnlClient instance
+        :return: Configured LiteClient instance
         """
         if isinstance(config, dict):
             config = GlobalConfig(**config)
-        node = config.liteservers[index]
+        ls = config.liteservers[index]
         return cls(
             network=network,
-            ip=node.host,
-            port=node.port,
-            public_key=node.id,
+            ip=ls.host,
+            port=ls.port,
+            public_key=ls.id,
             connect_timeout=connect_timeout,
             request_timeout=request_timeout,
             rps_limit=rps_limit,
@@ -178,9 +178,9 @@ class AdnlClient(BaseClient):
         rps_limit: t.Optional[int] = None,
         rps_period: float = 1.0,
         retry_policy: t.Optional[RetryPolicy] = None,
-    ) -> AdnlClient:
+    ) -> LiteClient:
         """
-        Create ADNL client using global network configuration fetched from ton.org.
+        Create lite-server client using global network configuration fetched from ton.org.
 
         Public lite-servers available in the global network configuration are
         free to use but may be unstable under load. For higher reliability and
@@ -198,7 +198,7 @@ class AdnlClient(BaseClient):
         :param rps_limit: Optional requests-per-second limit for this client
         :param rps_period: Time window in seconds for RPS limit
         :param retry_policy: Optional retry policy that defines per-error-code retry rules
-        :return: Configured AdnlClient instance
+        :return: Configured LiteClient instance
         """
         config_getters = {
             NetworkGlobalID.MAINNET: get_mainnet_global_config,
@@ -289,7 +289,7 @@ class AdnlClient(BaseClient):
         return decode_stack(result or [])
 
     async def connect(self) -> None:
-        """Ensure that ADNL connection is established."""
+        """Establish connection to the lite-server."""
         await self.provider.connect()
 
     async def reconnect(self) -> None:
@@ -297,7 +297,7 @@ class AdnlClient(BaseClient):
         await self.provider.reconnect()
 
     async def close(self) -> None:
-        """Close ADNL connection."""
+        """Close the lite-server connection."""
         await self.provider.close()
 
     async def get_time(self) -> int:
@@ -351,7 +351,7 @@ class AdnlClient(BaseClient):
         self,
         workchain: WorkchainID,
         shard: int,
-        seqno: int = -1,
+        seqno: t.Optional[int] = None,
         lt: t.Optional[int] = None,
         utime: t.Optional[int] = None,
     ) -> t.Tuple[BlockIdExt, Block]:
@@ -360,7 +360,7 @@ class AdnlClient(BaseClient):
 
         :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
         :return: Tuple of BlockIdExt and deserialized Block

tonutils/clients/adnl/provider/config.py

@@ -1,13 +1,18 @@
-import requests
+import json
+import urllib.request
+from pathlib import Path
 
 from tonutils.clients.adnl.provider.models import GlobalConfig
 
 
-def _get_global_config(path: str) -> GlobalConfig:
-    url = f"https://ton.org/{path}"
-    resp = requests.get(url)
-    resp.raise_for_status()
-    return GlobalConfig.model_validate(resp.json())
+def load_global_config(source: str) -> GlobalConfig:
+    if source.startswith(("http://", "https://")):
+        with urllib.request.urlopen(source) as response:
+            data = json.loads(response.read().decode())
+    else:
+        data = json.loads(Path(source).read_text())
+
+    return GlobalConfig.model_validate(data)
 
 
 def get_mainnet_global_config() -> GlobalConfig:
@@ -16,7 +21,7 @@ def get_mainnet_global_config() -> GlobalConfig:
 
     :return: Parsed GlobalConfig instance
     """
-    return _get_global_config("global-config.json")
+    return load_global_config("https://ton.org/global-config.json")
 
 
 def get_testnet_global_config() -> GlobalConfig:
@@ -25,4 +30,4 @@ def get_testnet_global_config() -> GlobalConfig:
 
     :return: Parsed GlobalConfig instance
     """
-    return _get_global_config("testnet-global-config.json")
+    return load_global_config("https://ton.org/testnet-global-config.json")