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

tonutils/clients/adnl/client.py

@@ -2,19 +2,33 @@ from __future__ import annotations
 
 import typing as t
 
-from pytoniq_core import Address, Transaction
+from pytoniq_core import Address, BlockIdExt, Block, Transaction
 
 from tonutils.clients.adnl.provider import AdnlProvider
-from tonutils.clients.adnl.provider.config import TONClient
-from tonutils.clients.adnl.provider.limiter import PriorityLimiter
-from tonutils.clients.adnl.provider.models import LiteServer, GlobalConfig
-from tonutils.clients.adnl.stack import decode_stack, encode_stack
+from tonutils.clients.adnl.provider.config import (
+    get_mainnet_global_config,
+    get_testnet_global_config,
+)
+from tonutils.clients.adnl.provider.models import (
+    LiteServer,
+    GlobalConfig,
+    MasterchainInfo,
+)
+from tonutils.clients.adnl.utils import decode_stack, encode_stack
 from tonutils.clients.base import BaseClient
-from tonutils.types import BinaryLike, ClientType, ContractStateInfo, NetworkGlobalID
+from tonutils.clients.limiter import RateLimiter
+from tonutils.types import (
+    BinaryLike,
+    ClientType,
+    ContractStateInfo,
+    NetworkGlobalID,
+    RetryPolicy,
+    WorkchainID,
+)
 
 
-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
 
@@ -25,39 +39,40 @@ class AdnlClient(BaseClient):
         ip: t.Union[str, int],
         port: int,
         public_key: BinaryLike,
-        timeout: int = 10,
+        connect_timeout: float = 2.0,
+        request_timeout: float = 10.0,
         rps_limit: t.Optional[int] = None,
         rps_period: float = 1.0,
-        rps_retries: int = 2,
-        limiter: t.Optional[PriorityLimiter] = None,
+        retry_policy: t.Optional[RetryPolicy] = None,
+        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
         and performance. You can obtain private lite-server configs from:
             - Tonconsole website: https://tonconsole.com/
             - dTON telegram bot: https://t.me/dtontech_bot (https://dton.io/)
+        Public free lite-server data may also be used, but may be unstable under load.
 
-        Public free lite-server data may also be used via `from_network_config()`.
-
-        :param network: Target TON network (mainnet or testnet)
+        :param network: Target TON network
         :param ip: Lite-server IP address or integer representation
         :param port: Lite-server port
         :param public_key: Lite-server ADNL public key
-        :param timeout: Request timeout in seconds
-        :param rps_limit: Optional requests-per-second limit
+        :param connect_timeout: Timeout in seconds for connect/handshake performed
+            by this client.
+        :param request_timeout: Timeout in seconds for a single request executed
+            by this client (one provider attempt).
+        :param rps_limit: Optional requests-per-second limit for this client
         :param rps_period: Time window in seconds for RPS limit
-        :param rps_retries: Number of retries on rate limiting
-        :param limiter: Optional pre-configured PriorityLimiter
+        :param retry_policy: Optional retry policy that defines per-error-code retry rules
+        :param limiter: Optional pre-configured RateLimiter (overrides rps_limit)
         """
         self.network: NetworkGlobalID = network
 
-        if limiter is not None:
-            limiter = limiter
-        elif rps_limit is not None:
-            limiter = PriorityLimiter(rps_limit, rps_period)
+        if limiter is None and rps_limit is not None:
+            limiter = RateLimiter(rps_limit, rps_period)
 
         self._provider: AdnlProvider = AdnlProvider(
             node=LiteServer(
@@ -65,9 +80,10 @@ class AdnlClient(BaseClient):
                 port=port,
                 id=public_key,
             ),
-            timeout=timeout,
-            rps_retries=rps_retries,
+            connect_timeout=connect_timeout,
+            request_timeout=request_timeout,
             limiter=limiter,
+            retry_policy=retry_policy,
         )
 
     @property
@@ -75,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
 
@@ -107,57 +123,64 @@ class AdnlClient(BaseClient):
         network: NetworkGlobalID = NetworkGlobalID.MAINNET,
         config: t.Union[GlobalConfig, t.Dict[str, t.Any]],
         index: int,
-        timeout: int = 10,
+        connect_timeout: float = 2.0,
+        request_timeout: float = 10.0,
         rps_limit: t.Optional[int] = None,
         rps_period: float = 1.0,
-        rps_retries: int = 2,
-    ) -> AdnlClient:
+        retry_policy: t.Optional[RetryPolicy] = None,
+    ) -> LiteClient:
         """
-        Create ADNL client from a lite-server config.
+        Create lite-server client from a configuration.
 
-        For best performance, it is recommended to use a private lite-server
-        configuration. You can obtain private configs from:
+        To obtain lite-server connection parameters, it is recommended to use
+        a private lite-server configuration for better stability and performance.
+        You can obtain private lite-server configs from:
             - Tonconsole website: https://tonconsole.com/
             - dTON telegram bot: https://t.me/dtontech_bot (https://dton.io/)
 
-        Public free configs may also be used via `from_network_config()`.
+        Public free configs may also be used, but may be unstable under load.
 
         :param network: Target TON network
         :param config: GlobalConfig instance or raw dict
-        :param index: Index of lite-server
-        :param timeout: Request timeout in seconds
-        :param rps_limit: Optional requests-per-second limit
+        :param index: Index of lite-server entry in the configuration
+        :param connect_timeout: Timeout in seconds for connect/handshake performed
+            by this client.
+        :param request_timeout: Timeout in seconds for a single request executed
+            by this client (one provider attempt).
+        :param rps_limit: Optional requests-per-second limit for this client
         :param rps_period: Time window in seconds for RPS limit
-        :param rps_retries: Number of retries on rate limiting
-        :return: Configured AdnlClient instance
+        :param retry_policy: Optional retry policy that defines per-error-code retry rules
+        :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,
-            timeout=timeout,
+            ip=ls.host,
+            port=ls.port,
+            public_key=ls.id,
+            connect_timeout=connect_timeout,
+            request_timeout=request_timeout,
             rps_limit=rps_limit,
             rps_period=rps_period,
-            rps_retries=rps_retries,
+            retry_policy=retry_policy,
         )
 
     @classmethod
-    async def from_network_config(
+    def from_network_config(
         cls,
         *,
         network: NetworkGlobalID = NetworkGlobalID.MAINNET,
         index: int,
-        timeout: int = 10,
+        connect_timeout: float = 2.0,
+        request_timeout: float = 10.0,
         rps_limit: t.Optional[int] = None,
         rps_period: float = 1.0,
-        rps_retries: int = 2,
-    ) -> AdnlClient:
+        retry_policy: t.Optional[RetryPolicy] = None,
+    ) -> LiteClient:
         """
-        Create ADNL client using global network config 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
@@ -167,28 +190,30 @@ class AdnlClient(BaseClient):
             - dTON telegram bot: https://t.me/dtontech_bot (https://dton.io/)
 
         :param network: Target TON network
-        :param index: Index of lite-server
-        :param timeout: Request timeout in seconds
-        :param rps_limit: Optional requests-per-second limit
+        :param index: Index of lite-server entry in the global configuration
+        :param connect_timeout: Timeout in seconds for connect/handshake performed
+            by this client.
+        :param request_timeout: Timeout in seconds for a single request executed
+            by this client (one provider attempt).
+        :param rps_limit: Optional requests-per-second limit for this client
         :param rps_period: Time window in seconds for RPS limit
-        :param rps_retries: Number of retries on rate limiting
-        :return: Configured AdnlClient instance
+        :param retry_policy: Optional retry policy that defines per-error-code retry rules
+        :return: Configured LiteClient instance
         """
-        ton_client = TONClient()
         config_getters = {
-            NetworkGlobalID.MAINNET: ton_client.mainnet_global_config,
-            NetworkGlobalID.TESTNET: ton_client.testnet_global_config,
+            NetworkGlobalID.MAINNET: get_mainnet_global_config,
+            NetworkGlobalID.TESTNET: get_testnet_global_config,
         }
-        async with ton_client:
-            config = await config_getters[network]()
+        config = config_getters[network]()
         return cls.from_config(
             network=network,
             config=config,
             index=index,
-            timeout=timeout,
+            connect_timeout=connect_timeout,
+            request_timeout=request_timeout,
             rps_limit=rps_limit,
             rps_period=rps_period,
-            rps_retries=rps_retries,
+            retry_policy=retry_policy,
         )
 
     async def _send_boc(self, boc: str) -> None:
@@ -215,7 +240,7 @@ class AdnlClient(BaseClient):
 
         curr_lt = state.last_transaction_lt
         curr_hash = state.last_transaction_hash
-        transactions: list[Transaction] = []
+        transactions: t.List[Transaction] = []
 
         while len(transactions) < limit and curr_lt != 0:
             batch_size = min(16, limit - len(transactions))
@@ -230,7 +255,7 @@ class AdnlClient(BaseClient):
                 break
 
             if to_lt > 0 and txs[-1].lt <= to_lt:
-                trimmed: list[Transaction] = []
+                trimmed: t.List[Transaction] = []
                 for tx in txs:
                     if tx.lt <= to_lt:
                         break
@@ -264,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:
@@ -272,5 +297,116 @@ 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:
+        """
+        Fetch current network time from lite-server.
+
+        :return: Current UNIX timestamp
+        """
+        return await self.provider.get_time()
+
+    async def get_version(self) -> int:
+        """
+        Fetch lite-server protocol version.
+
+        :return: Version number
+        """
+        return await self.provider.get_version()
+
+    async def wait_masterchain_seqno(
+        self,
+        seqno: int,
+        timeout_ms: int,
+        schema_name: str,
+        data: t.Optional[dict] = None,
+    ) -> dict:
+        """
+        Combine waitMasterchainSeqno with another lite-server query.
+
+        :param seqno: Masterchain seqno to wait for
+        :param timeout_ms: Wait timeout in milliseconds
+        :param schema_name: Lite-server TL method name without prefix
+        :param data: Additional method arguments
+        :return: Lite-server response as dictionary
+        """
+        return await self.provider.wait_masterchain_seqno(
+            seqno=seqno,
+            timeout_ms=timeout_ms,
+            schema_name=schema_name,
+            data=data,
+        )
+
+    async def get_masterchain_info(self) -> MasterchainInfo:
+        """
+        Fetch basic masterchain information.
+
+        :return: MasterchainInfo instance
+        """
+        return await self.provider.get_masterchain_info()
+
+    async def lookup_block(
+        self,
+        workchain: WorkchainID,
+        shard: int,
+        seqno: t.Optional[int] = None,
+        lt: t.Optional[int] = None,
+        utime: t.Optional[int] = None,
+    ) -> t.Tuple[BlockIdExt, Block]:
+        """
+        Locate a block by workchain/shard and one of seqno/lt/utime.
+
+        :param workchain: Workchain identifier
+        :param shard: Shard identifier
+        :param seqno: Block sequence number
+        :param lt: Logical time filter
+        :param utime: UNIX time filter
+        :return: Tuple of BlockIdExt and deserialized Block
+        """
+        return await self.provider.lookup_block(
+            workchain=workchain,
+            shard=shard,
+            seqno=seqno,
+            lt=lt,
+            utime=utime,
+        )
+
+    async def get_block_header(
+        self,
+        block: BlockIdExt,
+    ) -> t.Tuple[BlockIdExt, Block]:
+        """
+        Fetch and deserialize block header by BlockIdExt.
+
+        :param block: BlockIdExt to query
+        :return: Tuple of BlockIdExt and deserialized Block
+        """
+        return await self.provider.get_block_header(block)
+
+    async def get_block_transactions_ext(
+        self,
+        block: BlockIdExt,
+        count: int = 1024,
+    ) -> t.List[Transaction]:
+        """
+        Fetch extended block transactions list.
+
+        :param block: Target block identifier
+        :param count: Maximum number of transactions per request
+        :return: List of deserialized Transaction objects
+        """
+        return await self.provider.get_block_transactions_ext(block, count=count)
+
+    async def get_all_shards_info(
+        self,
+        block: t.Optional[BlockIdExt] = None,
+    ) -> t.List[BlockIdExt]:
+        """
+        Fetch shard info for all workchains at a given masterchain block.
+
+        :param block: Masterchain block ID or None to use latest
+        :return: List of shard BlockIdExt objects
+        """
+        return await self.provider.get_all_shards_info(block)

tonutils/clients/adnl/provider/config.py

@@ -1,34 +1,33 @@
-from pyapiq import AsyncClientAPI, async_endpoint
-from pyapiq.types import HTTPMethod
+import json
+import urllib.request
+from pathlib import Path
 
 from tonutils.clients.adnl.provider.models import GlobalConfig
 
 
-class TONClient(AsyncClientAPI):
-    """Minimal HTTP client for fetching TON global configuration files."""
+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())
 
-    base_url = "https://ton.org/"
+    return GlobalConfig.model_validate(data)
 
-    @async_endpoint(
-        HTTPMethod.GET,
-        path="global-config.json",
-        return_as=GlobalConfig,
-    )
-    async def mainnet_global_config(self) -> GlobalConfig:  # type: ignore[empty-body]
-        """
-        Fetch mainnet global configuration.
 
-        :return: Parsed GlobalConfig instance
-        """
+def get_mainnet_global_config() -> GlobalConfig:
+    """
+    Fetch mainnet global configuration.
 
-    @async_endpoint(
-        HTTPMethod.GET,
-        path="testnet-global-config.json",
-        return_as=GlobalConfig,
-    )
-    async def testnet_global_config(self) -> GlobalConfig:  # type: ignore[empty-body]
-        """
-        Fetch testnet global configuration.
+    :return: Parsed GlobalConfig instance
+    """
+    return load_global_config("https://ton.org/global-config.json")
 
-        :return: Parsed GlobalConfig instance
-        """
+
+def get_testnet_global_config() -> GlobalConfig:
+    """
+    Fetch testnet global configuration.
+
+    :return: Parsed GlobalConfig instance
+    """
+    return load_global_config("https://ton.org/testnet-global-config.json")

tonutils/clients/adnl/provider/models.py

@@ -66,6 +66,10 @@ class LiteServer(BaseModel):
             return socket.inet_ntoa(packed_id)
         return str(self.ip)
 
+    @property
+    def endpoint(self) -> str:
+        return f"{self.host}:{self.port}"
+
 
 class Block(BaseModel):
     """