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

tonutils/clients/adnl/provider/provider.py

@@ -14,6 +14,7 @@ from pytoniq_core import (
     Transaction,
     VmStack,
     deserialize_shard_hashes,
+    ShardAccount,
 )
 from pytoniq_core.crypto.ciphers import get_random
 from pytoniq_core.crypto.crc import crc16
@@ -41,7 +42,7 @@ from tonutils.exceptions import (
     ProviderResponseError,
 )
 from tonutils.types import (
-    ContractStateInfo,
+    ContractInfo,
     RetryPolicy,
     WorkchainID,
 )
@@ -95,13 +96,13 @@ class AdnlProvider:
         self._connect_lock: asyncio.Lock = asyncio.Lock()
 
     @property
-    def is_connected(self) -> bool:
+    def connected(self) -> bool:
         """
         Whether the underlying transport is currently connected.
 
         :return: True if connected, False otherwise
         """
-        return self.transport.is_connected
+        return self.transport.connected
 
     @property
     def last_mc_block(self) -> BlockIdExt:
@@ -165,7 +166,7 @@ class AdnlProvider:
 
         Establishes transport, performs handshake and starts background workers.
         """
-        if self.is_connected:
+        if self.connected:
             return
 
         self.loop = asyncio.get_running_loop()
@@ -215,8 +216,12 @@ class AdnlProvider:
         :param priority: Whether to use priority slot in the limiter
         :return: Lite-server response payload as a decoded dictionary
         """
-        if not self.is_connected or self.loop is None:
-            raise NotConnectedError()
+        if not self.connected or self.loop is None:
+            raise NotConnectedError(
+                component="AdnlProvider",
+                endpoint=self.node.endpoint,
+                operation="request",
+            )
 
         if self._limiter is not None:
             await self._limiter.acquire(priority=priority)
@@ -492,7 +497,7 @@ class AdnlProvider:
 
         return block_id, block_obj
 
-    async def get_block_transactions_ext(
+    async def get_block_transactions(
         self,
         block: BlockIdExt,
         count: int = 1024,
@@ -591,7 +596,7 @@ class AdnlProvider:
             for sh in v.list
         ]
 
-    async def run_smc_method(
+    async def run_get_method(
         self,
         address: Address,
         method_name: str,
@@ -643,7 +648,7 @@ class AdnlProvider:
         cs = Slice.one_from_boc(result["result"])
         return VmStack.deserialize(cs)
 
-    async def get_config_all(
+    async def get_config(
         self,
         *,
         priority: bool = False,
@@ -667,18 +672,18 @@ class AdnlProvider:
         config_proof = Cell.one_from_boc(result.get("config_proof"))
         return build_config_all(config_proof)
 
-    async def get_account_state(
+    async def get_info(
         self,
         address: Address,
         *,
         priority: bool = False,
-    ) -> ContractStateInfo:
+    ) -> ContractInfo:
         """
         Fetch contract state at the latest masterchain block.
 
         :param address: Contract address
         :param priority: Whether to use priority slot in the limiter
-        :return: ContractStateInfo with balance, code, data and last tx
+        :return: ContractInfo with balance, code, data and last tx
         """
         if self.last_mc_block is None:
             await self.updater.refresh()
@@ -693,7 +698,7 @@ class AdnlProvider:
             priority=priority,
         )
         if not result["state"]:
-            return ContractStateInfo(balance=0)
+            return ContractInfo(balance=0)
 
         account_state_root = Cell.one_from_boc(result["state"])
         account = Account.deserialize(account_state_root.begin_parse())
@@ -755,9 +760,9 @@ class AdnlProvider:
         for i, cell in enumerate(cells):
             curr_hash = cell.get_hash(0).hex()
             if curr_hash != prev_tr_hash:
-                raise ClientError(
-                    f"transaction hash mismatch: "
-                    f"expected {prev_tr_hash}, got {curr_hash}"
+                raise ProviderError(
+                    "getTransactions failed: transaction hash mismatch "
+                    f"(expected {prev_tr_hash}, got {curr_hash})"
                 )
 
             tx = Transaction.deserialize(cell.begin_parse())
@@ -765,3 +770,43 @@ class AdnlProvider:
             transactions.append(tx)
 
         return transactions
+
+    async def get_account_state(
+        self,
+        address: Address,
+        *,
+        priority: bool = False,
+    ) -> t.Tuple[t.Optional[Account], t.Optional[ShardAccount]]:
+        """
+        Fetch account state and shard account from lite-server.
+
+        :param address: Account address
+        :param priority: Whether to use priority slot in the limiter
+        :return: Tuple of (Account | None, ShardAccount | None)
+        """
+        if self.last_mc_block is None:
+            await self.updater.refresh()
+
+        data = {
+            "id": self.last_mc_block.to_dict(),
+            "account": address.to_tl_account_id(),
+        }
+        result = await self.send_liteserver_query(
+            method="getAccountState",
+            data=data,
+            priority=priority,
+        )
+        if not result.get("state"):
+            return None, None
+
+        account_state_root = Cell.one_from_boc(result["state"])
+        account = Account.deserialize(account_state_root.begin_parse())
+
+        shrd_blk = BlockIdExt.from_dict(result["shardblk"])
+        shard_account = build_shard_account(
+            account_state_root=account_state_root,
+            shard_account_descr=result["proof"],
+            shrd_blk=shrd_blk,
+            address=address,
+        )
+        return account, shard_account

tonutils/clients/adnl/provider/transport.py

@@ -64,7 +64,7 @@ class AdnlTcpTransport:
         self._closing = False
 
     @property
-    def is_connected(self) -> bool:
+    def connected(self) -> bool:
         """Check if the transport is currently connected."""
         return self._connected
 
@@ -178,7 +178,7 @@ class AdnlTcpTransport:
                 "connect", f"timeout after {self.connect_timeout}s"
             ) from exc
         except OSError as exc:
-            raise self._error("connect", "connection refused") from exc
+            raise self._error("connect", str(exc)) from exc
 
         if self.writer is None or self.reader is None:
             raise self._error("connect", "stream init failed")
@@ -218,7 +218,11 @@ class AdnlTcpTransport:
         :param payload: Raw ADNL packet bytes
         """
         if not self._connected or self.writer is None:
-            raise NotConnectedError()
+            raise NotConnectedError(
+                component="ADNL transport",
+                endpoint=self.node.endpoint,
+                operation="send",
+            )
 
         packet = self._build_frame(payload)
         encrypted = self.encrypt_frame(packet)
@@ -233,7 +237,12 @@ class AdnlTcpTransport:
         Blocks until a complete packet is available from the background reader.
         """
         if not self._connected:
-            raise NotConnectedError()
+            raise NotConnectedError(
+                component="ADNL transport",
+                endpoint=self.node.endpoint,
+                operation="recv",
+            )
+
         return await self._incoming.get()
 
     async def read_frame(self, discard: bool = False) -> t.Optional[bytes]:

tonutils/clients/adnl/provider/workers/pinger.py

@@ -79,5 +79,5 @@ class PingerWorker(BaseWorker):
         while self.running:
             await asyncio.sleep(self._interval)
 
-            if self.provider.is_connected:
+            if self.provider.connected:
                 await self.ping_once()

tonutils/clients/adnl/utils.py

@@ -15,7 +15,7 @@ from pytoniq_core import (
     VmTuple,
 )
 
-from tonutils.types import ContractState, ContractStateInfo, StackItems, StackItem
+from tonutils.types import ContractState, ContractInfo, StackItems, StackItem
 from tonutils.utils import cell_to_hex, norm_stack_num, norm_stack_cell
 
 
@@ -72,17 +72,17 @@ def build_contract_state_info(
     address: Address,
     account: Account,
     shard_account: ShardAccount,
-) -> ContractStateInfo:
+) -> ContractInfo:
     """
-    Build a high-level ContractStateInfo object from raw account data.
+    Build a high-level ContractInfo object from raw account data.
 
     :param address: Contract address
     :param account: Raw Account data structure
     :param shard_account: Parsed ShardAccount entry
-    :return: Filled ContractStateInfo instance
+    :return: Filled ContractInfo instance
     """
     simple_account = SimpleAccount.from_raw(account, address)
-    info = ContractStateInfo(balance=simple_account.balance)
+    info = ContractInfo(balance=simple_account.balance)
 
     if simple_account.state is not None:
         state_init = simple_account.state.state_init

tonutils/clients/base.py

@@ -1,13 +1,16 @@
 from __future__ import annotations
 
 import abc
+import asyncio
 import typing as t
+from contextlib import suppress
 
 from pytoniq_core import Address, Cell, Transaction, begin_cell
 
+from tonutils.exceptions import ProviderError
 from tonutils.types import (
     AddressLike,
-    ContractStateInfo,
+    ContractInfo,
     ClientType,
     DNSCategory,
     NetworkGlobalID,
@@ -36,85 +39,48 @@ class BaseClient(abc.ABC):
 
     @property
     @abc.abstractmethod
-    def provider(self) -> t.Any:
+    def connected(self) -> bool:
         """
-        Underlying transport/provider backend used for all requests.
+        Check whether provider resources are initialized and usable.
 
-        Expected to expose network I/O primitives appropriate for the client
-        type (HTTP session, ADNL transport, etc.).
+        :return: True if client has an active session/connection, False otherwise
         """
-        raise NotImplementedError
 
+    @property
     @abc.abstractmethod
-    async def __aenter__(self) -> BaseClient:
+    def provider(self) -> t.Any:
         """
-        Prepare client resources for use.
+        Underlying transport/provider backend used for all requests.
 
-        Should initialize network connections or sessions as required.
+        Expected to expose network I/O primitives appropriate for the client
+        type (HTTP session, ADNL transport, etc.).
         """
-        raise NotImplementedError
 
     @abc.abstractmethod
-    async def __aexit__(
-        self,
-        exc_type: t.Optional[t.Type[BaseException]],
-        exc_value: t.Optional[BaseException],
-        traceback: t.Optional[t.Any],
-    ) -> None:
-        """
-        Release allocated client resources.
-
-        Called automatically when the async context ends.
-        """
-        raise NotImplementedError
+    async def connect(self) -> None:
+        """Initialize any required provider resources (sessions, transports, etc.)."""
 
     @abc.abstractmethod
-    async def _send_boc(self, boc: str) -> None:
-        """
-        Send an external message to the network using the underlying provider.
-
-        :param boc: Message body serialized as BoC string,
-            in a format accepted by the underlying provider
-        """
-        raise NotImplementedError
+    async def close(self) -> None:
+        """Close provider resources. Should be safe to call multiple times."""
 
     @abc.abstractmethod
-    async def _get_blockchain_config(self) -> t.Dict[int, t.Any]:
-        """
-        Fetch full blockchain configuration from the underlying provider.
-
-        :return: Mapping of configuration parameter ID to parsed value
-        """
-        raise NotImplementedError
+    async def _send_message(self, boc: str) -> None: ...
 
     @abc.abstractmethod
-    async def _get_contract_info(self, address: str) -> ContractStateInfo:
-        """
-        Retrieve basic contract state information from the provider.
+    async def _get_config(self) -> t.Dict[int, t.Any]: ...
 
-        :param address: Contract address in raw
-        :return: ContractStateInfo with basic state, balance and last tx data
-        """
-        raise NotImplementedError
+    @abc.abstractmethod
+    async def _get_info(self, address: str) -> ContractInfo: ...
 
     @abc.abstractmethod
-    async def _get_contract_transactions(
+    async def _get_transactions(
         self,
         address: str,
         limit: int = 100,
         from_lt: t.Optional[int] = None,
-        to_lt: int = 0,
-    ) -> t.List[Transaction]:
-        """
-        Fetch a list of recent contract transactions from the provider.
-
-        :param address: Contract address in raw
-        :param limit: Maximum number of transactions to return
-        :param from_lt: Optional lower bound (exclusive) logical time
-        :param to_lt: Upper bound (inclusive) logical time, 0 means latest
-        :return: List of Transaction objects ordered from newest to oldest
-        """
-        raise NotImplementedError
+        to_lt: t.Optional[int] = None,
+    ) -> t.List[Transaction]: ...
 
     @abc.abstractmethod
     async def _run_get_method(
@@ -122,83 +88,79 @@ class BaseClient(abc.ABC):
         address: str,
         method_name: str,
         stack: t.Optional[t.List[t.Any]] = None,
-    ) -> t.List[t.Any]:
-        """
-        Execute a contract get-method via the provider.
+    ) -> t.List[t.Any]: ...
 
-        :param address: Contract address in raw
-        :param method_name: Name of the get-method to execute
-        :param stack: Optional initial TVM stack items for the call
-        :return: Decoded TVM stack items returned by the method
+    async def __aenter__(self) -> BaseClient:
         """
-        raise NotImplementedError
+        Prepare client resources for use.
 
-    @property
-    @abc.abstractmethod
-    def is_connected(self) -> bool:
+        Should initialize network connections or sessions as required.
         """
-        Check whether provider resources are initialized and usable.
+        await self.connect()
+        return self
 
-        :return: True if client has an active session/connection, False otherwise
+    async def __aexit__(
+        self,
+        exc_type: t.Optional[t.Type[BaseException]],
+        exc_value: t.Optional[BaseException],
+        traceback: t.Optional[t.Any],
+    ) -> None:
         """
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    async def connect(self) -> None:
-        """Initialize any required provider resources (sessions, transports, etc.)."""
-        raise NotImplementedError
+        Release allocated client resources.
 
-    @abc.abstractmethod
-    async def close(self) -> None:
-        """Close provider resources. Should be safe to call multiple times."""
-        raise NotImplementedError
+        Called automatically when the async context ends.
+        """
+        with suppress(asyncio.CancelledError):
+            await self.close()
 
-    async def send_boc(self, boc: str) -> None:
+    async def send_message(self, boc: str) -> None:
         """
         Send an external message to the blockchain.
 
         :param boc: Message body serialized as BoC string, in a format accepted by the underlying provider
         """
-        await self._send_boc(boc)
+        await self._send_message(boc)
 
-    async def get_blockchain_config(self) -> t.Dict[int, t.Any]:
+    async def get_config(self) -> t.Dict[int, t.Any]:
         """
         Fetch and decode global blockchain configuration.
 
         :return: Mapping of configuration parameter ID to parsed value
         """
-        return await self._get_blockchain_config()
+        return await self._get_config()
 
-    async def get_contract_info(self, address: AddressLike) -> ContractStateInfo:
+    async def get_info(self, address: AddressLike) -> ContractInfo:
         """
         Fetch basic state information for a smart contract.
 
         :param address: Contract address as Address object or string
-        :return: ContractStateInfo with code, data, balance and last tx data
+        :return: ContractInfo with code, data, balance and last tx data
         """
         if isinstance(address, Address):
             address = Address(address).to_str(is_user_friendly=False)
-        return await self._get_contract_info(address=address)
+        return await self._get_info(address=address)
 
-    async def get_contract_transactions(
+    async def get_transactions(
         self,
         address: AddressLike,
         limit: int = 100,
         from_lt: t.Optional[int] = None,
-        to_lt: int = 0,
+        to_lt: t.Optional[int] = None,
     ) -> t.List[Transaction]:
         """
         Fetch transaction history for a contract.
 
         :param address: Contract address as Address object or string
         :param limit: Maximum number of transactions to return
-        :param from_lt: Optional lower bound (exclusive) logical time
-        :param to_lt: Upper bound (inclusive) logical time, 0 means latest
+        :param from_lt: Upper bound logical time (inclusive).
+            If None, starts from the most recent transaction.
+        :param to_lt: Lower bound logical time (exclusive).
+            If None or 0, no lower bound is applied.
         :return: List of Transaction objects ordered from newest to oldest
         """
         if isinstance(address, Address):
             address = Address(address).to_str(is_user_friendly=False)
-        return await self._get_contract_transactions(
+        return await self._get_transactions(
             address=address,
             limit=limit,
             from_lt=from_lt,
@@ -256,7 +218,7 @@ class BaseClient(abc.ABC):
         if isinstance(domain, str):
             domain = encode_dns_name(domain)
         if dns_root_address is None:
-            blockchain_config = await self.get_blockchain_config()
+            blockchain_config = await self.get_config()
             hash_part = blockchain_config[4].dns_root_addr
             dns_root_address = Address((WorkchainID.MASTERCHAIN.value, hash_part))
 
@@ -268,7 +230,9 @@ class BaseClient(abc.ABC):
             stack=[domain_cell.to_slice(), category.value],
         )
         if len(res) < 2:
-            raise ValueError(f"`dnsresolve` returned {len(res)} items, but 2 expected.")
+            raise ProviderError(
+                f"dnsresolve failed: invalid response (expected 2 stack items, got {len(res)})"
+            )
 
         blen = len(domain) * 8
         rlen = t.cast(int, res[0])
@@ -279,7 +243,9 @@ class BaseClient(abc.ABC):
             return None
 
         if rlen % 8 != 0 or rlen > blen:
-            raise ValueError(f"Invalid resolved length: result {rlen}, bytes {blen}.")
+            raise ProviderError(
+                f"dnsresolve failed: invalid resolved length {rlen} bits (domain {blen} bits)"
+            )
         if rlen == blen:
             # noinspection PyProtectedMember
             tcls = DNSRecords._DNS_RECORDS_CLASSES.get(category.name.lower())

tonutils/clients/http/__init__.py

@@ -1,23 +1,23 @@
 from .balancer import HttpBalancer
 from .clients import (
-    ChainstackHttpClient,
-    QuicknodeHttpClient,
-    TatumHttpClient,
-    TonapiHttpClient,
-    ToncenterHttpClient,
+    ChainstackClient,
+    QuicknodeClient,
+    TatumClient,
+    TonapiClient,
+    ToncenterClient,
 )
-from .providers import (
+from .provider import (
     TonapiHttpProvider,
     ToncenterHttpProvider,
 )
 
 __all__ = [
     "HttpBalancer",
-    "ChainstackHttpClient",
-    "QuicknodeHttpClient",
-    "TatumHttpClient",
-    "TonapiHttpClient",
+    "ChainstackClient",
+    "QuicknodeClient",
+    "TatumClient",
+    "TonapiClient",
     "TonapiHttpProvider",
-    "ToncenterHttpClient",
+    "ToncenterClient",
     "ToncenterHttpProvider",
 ]