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

tonutils/clients/limiter.py

@@ -4,11 +4,10 @@ import time
 
 class RateLimiter:
     """
-    Asynchronous token-bucket rate limiter with optional priority acquisition.
+    Asynchronous token-bucket rate limiter with priority support.
 
-    Limits the number of acquire operations per time period and supports
-    priority waiters that can bypass non-priority requests when tokens
-    become available.
+    Priority requests are served before non-priority requests when
+    tokens become available.
     """
 
     __slots__ = (
@@ -26,7 +25,7 @@ class RateLimiter:
 
         :param max_rate: Maximum number of acquisitions allowed per period.
         :param period: Period length in seconds.
-        :raises ValueError: If ``max_rate`` or ``period`` is not positive.
+        :raises ValueError: If max_rate or period is not positive.
         """
         if max_rate <= 0:
             raise ValueError("max_rate must be > 0")
@@ -40,76 +39,79 @@ class RateLimiter:
         self._cond = asyncio.Condition()
         self._priority_waiters = 0
 
-    def when_ready(self) -> float:
-        """
-        Calculate delay until the next token becomes available.
-
-        :return: Number of seconds to wait before a token can be acquired,
-            or ``0`` if a token is available immediately.
-        """
+    def _refill(self) -> None:
+        """Refill tokens based on elapsed time."""
         now = time.monotonic()
-        tokens = self._peek_tokens(now)
-        if tokens >= 1.0:
+        elapsed = now - self._updated_at
+        if elapsed > 0:
+            rate = self._max_rate / self._period
+            self._tokens = min(float(self._max_rate), self._tokens + elapsed * rate)
+            self._updated_at = now
+
+    def _seconds_to_token(self) -> float:
+        """Calculate seconds until next token is available."""
+        if self._tokens >= 1.0:
             return 0.0
-        return self._seconds_to_one_token(tokens)
+        missing = 1.0 - self._tokens
+        rate = self._max_rate / self._period
+        return missing / rate
 
     async def acquire(self, priority: bool = False) -> None:
         """
-        Acquire a single token, waiting asynchronously if necessary.
+        Acquire a single token, waiting if necessary.
 
-        Priority acquisitions are allowed to bypass non-priority waiters
-        when tokens become available.
+        Priority requests bypass non-priority waiters when tokens
+        become available.
 
-        :param priority: Whether to acquire the token with priority.
+        :param priority: Whether to acquire with priority.
         """
-        if priority:
-            async with self._cond:
-                self._priority_waiters += 1
+        async with self._cond:
+            is_waiting = False
 
             try:
-                await self._acquire(priority=True)
+                while True:
+                    self._refill()
+
+                    # Check if token available
+                    if self._tokens >= 1.0:
+                        # Priority always takes; non-priority only if no priority waiting
+                        if priority or self._priority_waiters == 0:
+                            self._tokens -= 1.0
+                            self._cond.notify_all()
+                            return
+
+                    # Register as priority waiter only when actually waiting
+                    if priority and not is_waiting:
+                        self._priority_waiters += 1
+                        is_waiting = True
+
+                    # Wait for token
+                    wait_time = self._seconds_to_token()
+                    if wait_time > 0:
+                        try:
+                            await asyncio.wait_for(self._cond.wait(), timeout=wait_time)
+                        except asyncio.TimeoutError:
+                            pass  # Expected — token should be ready now
+                    else:
+                        # Token available but blocked by priority — wait for notify
+                        await self._cond.wait()
+
             finally:
-                async with self._cond:
+                if is_waiting:
                     self._priority_waiters -= 1
                     self._cond.notify_all()
-            return
 
-        await self._acquire(priority=False)
-
-    async def _acquire(self, priority: bool) -> None:
-        while True:
-            async with self._cond:
-                now = time.monotonic()
-                self._refill(now)
-
-                if self._tokens >= 1.0 and (priority or self._priority_waiters == 0):
-                    self._tokens -= 1.0
-                    self._cond.notify_all()
-                    return
-
-                if self._tokens < 1.0:
-                    timeout = self._seconds_to_one_token(self._tokens)
-                    await asyncio.wait_for(self._cond.wait(), timeout=timeout)
-                else:
-                    await self._cond.wait()
+    def when_ready(self) -> float:
+        """
+        Calculate delay until the next token becomes available.
 
-    def _peek_tokens(self, now: float) -> float:
+        :return: Seconds to wait, or 0 if ready immediately.
+        """
+        now = time.monotonic()
         elapsed = now - self._updated_at
-        if elapsed <= 0.0:
-            return self._tokens
-
         rate = self._max_rate / self._period
-        tokens = self._tokens + elapsed * rate
-        return min(float(self._max_rate), tokens)
-
-    def _refill(self, now: float) -> None:
-        self._tokens = self._peek_tokens(now)
-        self._updated_at = now
+        tokens = min(float(self._max_rate), self._tokens + elapsed * rate)
 
-    def _seconds_to_one_token(self, tokens: float) -> float:
-        missing = 1.0 - tokens
-        if missing <= 0.0:
+        if tokens >= 1.0:
             return 0.0
-
-        rate = self._max_rate / self._period
-        return missing / rate
+        return (1.0 - tokens) / rate

tonutils/clients/protocol.py

@@ -6,7 +6,7 @@ from pytoniq_core import Cell, Transaction
 
 from tonutils.types import (
     AddressLike,
-    ContractStateInfo,
+    ContractInfo,
     DNSCategory,
     NetworkGlobalID,
     ClientType,
@@ -40,27 +40,27 @@ class ClientProtocol(t.Protocol):
         """Underlying provider or transport backend."""
 
     @property
-    def is_connected(self) -> bool:
+    def connected(self) -> bool:
         """Whether the client is connected and ready for requests."""
 
-    async def send_boc(self, boc: str) -> None:
+    async def send_message(self, boc: str) -> None:
         """Send an external message to the blockchain."""
 
-    async def get_blockchain_config(self) -> t.Dict[int, t.Any]:
+    async def get_config(self) -> t.Dict[int, t.Any]:
         """Fetch global blockchain configuration."""
 
-    async def get_contract_info(
+    async def get_info(
         self,
         address: AddressLike,
-    ) -> ContractStateInfo:
+    ) -> ContractInfo:
         """Fetch basic contract state information."""
 
-    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 contract transactions."""
 

tonutils/contracts/base.py

@@ -13,7 +13,7 @@ from tonutils.exceptions import (
     StateNotLoadedError,
     ProviderResponseError,
 )
-from tonutils.types import AddressLike, ContractState, ContractStateInfo, WorkchainID
+from tonutils.types import AddressLike, ContractInfo, ContractState, WorkchainID
 from tonutils.utils import to_cell
 
 _R = t.TypeVar("_R")
@@ -61,7 +61,7 @@ class BaseContract(ContractProtocol[_D]):
         client: ClientProtocol,
         address: Address,
         state_init: t.Optional[StateInit] = None,
-        state_info: t.Optional[ContractStateInfo] = None,
+        info: t.Optional[ContractInfo] = None,
     ) -> None:
         """
         Initialize base contract wrapper.
@@ -69,12 +69,12 @@ class BaseContract(ContractProtocol[_D]):
         :param client: TON client for blockchain interactions
         :param address: Contract address on the blockchain
         :param state_init: Optional known StateInit (code and data)
-        :param state_info: Optional preloaded on-chain contract state
+        :param info: Optional preloaded on-chain contract state
         """
         self._client = client
         self._address = address
         self._state_init = state_init
-        self._state_info = state_info
+        self._info = info
 
     @property
     def client(self) -> ClientProtocol:
@@ -91,17 +91,6 @@ class BaseContract(ContractProtocol[_D]):
         """Locally known StateInit for this contract, if any."""
         return self._state_init
 
-    @property
-    def state_info(self) -> ContractStateInfo:
-        """
-        Cached snapshot of the contract state.
-
-        :return: Contract state information
-        """
-        if self._state_info is None:
-            raise StateNotLoadedError(self, missing="state_info")
-        return t.cast(ContractStateInfo, self._state_info)
-
     @property
     def state_data(self) -> _D:
         """
@@ -113,11 +102,22 @@ class BaseContract(ContractProtocol[_D]):
         """
         if not hasattr(self, "_data_model") or self._data_model is None:
             raise ContractError(self, "No `_data_model` defined for contract class.")
-        if not (self._state_info and self._state_info.data):
+        if not (self._info and self._info.data):
             raise StateNotLoadedError(self, missing="state_data")
-        cs = self._state_info.data.begin_parse()
+        cs = self._info.data.begin_parse()
         return self._data_model.deserialize(cs)
 
+    @property
+    def info(self) -> ContractInfo:
+        """
+        Cached snapshot of the contract state info.
+
+        :return: Contract state information
+        """
+        if self._info is None:
+            raise StateNotLoadedError(self, missing="info")
+        return t.cast(ContractInfo, self._info)
+
     @property
     def balance(self) -> int:
         """
@@ -125,7 +125,7 @@ class BaseContract(ContractProtocol[_D]):
 
         :return: Balance from the latest known state
         """
-        return self.state_info.balance
+        return self.info.balance
 
     @property
     def state(self) -> ContractState:
@@ -134,7 +134,7 @@ class BaseContract(ContractProtocol[_D]):
 
         :return: One of ContractState enum values (ACTIVE, FROZEN, UNINIT, NONEXIST)
         """
-        return self.state_info.state
+        return self.info.state
 
     @property
     def is_active(self) -> bool:
@@ -179,7 +179,7 @@ class BaseContract(ContractProtocol[_D]):
 
         :return: Transaction LT or None if unknown
         """
-        return self.state_info.last_transaction_lt
+        return self.info.last_transaction_lt
 
     @property
     def last_transaction_hash(self) -> t.Optional[str]:
@@ -188,7 +188,7 @@ class BaseContract(ContractProtocol[_D]):
 
         :return: Transaction hash as hex string or None if unknown
         """
-        return self.state_info.last_transaction_hash
+        return self.info.last_transaction_hash
 
     @property
     def code(self) -> t.Optional[Cell]:
@@ -197,7 +197,7 @@ class BaseContract(ContractProtocol[_D]):
 
         :return: Code cell or None if not available
         """
-        return self.state_info.code
+        return self.info.code
 
     @property
     def data(self) -> t.Optional[Cell]:
@@ -206,36 +206,36 @@ class BaseContract(ContractProtocol[_D]):
 
         :return: Data cell or None if not available
         """
-        return self.state_info.data
+        return self.info.data
 
     @classmethod
-    async def _load_state_info(
+    async def _load_info(
         cls,
         client: ClientProtocol,
         address: Address,
-    ) -> ContractStateInfo:
+    ) -> ContractInfo:
         """
         Fetch contract state from the blockchain.
 
         If the request fails (except rate limits), sets state to default empty state.
         """
         try:
-            return await client.get_contract_info(address)
+            return await client.get_info(address)
         except ProviderResponseError as e:
             if e.code in {429, 228, 5556}:  # rate limit exceed
                 raise
-            return ContractStateInfo()
+            return ContractInfo()
         except (Exception,):
-            return ContractStateInfo()
+            return ContractInfo()
 
     async def refresh(self) -> None:
         """
         Refresh contract state from the blockchain.
 
-        Fetches current contract information and updates the cached state_info.
+        Fetches current contract information and updates the cached info.
         If the request fails (except rate limits), sets state to default empty state.
         """
-        self._state_info = await self._load_state_info(self.client, self.address)
+        self._info = await self._load_info(self.client, self.address)
 
     @classmethod
     def from_state_init(
@@ -323,8 +323,8 @@ class BaseContract(ContractProtocol[_D]):
         if not load_state:
             return cls(client, address)
 
-        state_info = await cls._load_state_info(client, address)
-        return cls(client, address, state_info=state_info)
+        info = await cls._load_info(client, address)
+        return cls(client, address, info=info)
 
     def __repr__(self) -> str:
         return f"< Contract {self.__class__.__name__} address: {self.address} >"

tonutils/contracts/protocol.py

@@ -5,7 +5,7 @@ import typing as t
 from pytoniq_core import Address, Cell, StateInit
 
 from tonutils.clients.protocol import ClientProtocol
-from tonutils.types import AddressLike, ContractState, ContractStateInfo, WorkchainID
+from tonutils.types import AddressLike, ContractInfo, ContractState, WorkchainID
 
 if t.TYPE_CHECKING:
     from tonutils.contracts.versions import ContractVersion
@@ -48,21 +48,21 @@ class ContractProtocol(t.Protocol[_D]):
         """Locally known StateInit for this contract, if any."""
 
     @property
-    def state_info(self) -> ContractStateInfo:
+    def state_data(self) -> _D:
         """
-        Cached snapshot of the contract state.
+        Decoded on-chain data in typed form.
 
-        Implementations usually update this via refresh() or in constructors
-        that read on-chain data.
+        Implementations must decode the current data cell from info
+        using the associated _data_model.
         """
 
     @property
-    def state_data(self) -> _D:
+    def info(self) -> ContractInfo:
         """
-        Decoded on-chain data in typed form.
+        Cached snapshot of the contract state info.
 
-        Implementations must decode the current data cell from state_info
-        using the associated _data_model.
+        Implementations usually update this via refresh() or in constructors
+        that read on-chain data.
         """
 
     @property

tonutils/contracts/wallet/base.py

@@ -22,14 +22,14 @@ from tonutils.contracts.wallet.tlb import BaseWalletData
 from tonutils.exceptions import ContractError
 from tonutils.types import (
     AddressLike,
-    ContractStateInfo,
+    ContractInfo,
     SendMode,
     PublicKey,
     PrivateKey,
     WorkchainID,
     DEFAULT_SENDMODE,
 )
-from tonutils.utils import resolve_wallet_address, to_cell
+from tonutils.utils import to_cell
 
 _D = t.TypeVar("_D", bound=BaseWalletData)
 _C = t.TypeVar("_C", bound=BaseWalletConfig)
@@ -61,7 +61,7 @@ class BaseWallet(BaseContract, WalletProtocol[_D, _C, _P], abc.ABC):
         client: ClientProtocol,
         address: Address,
         state_init: t.Optional[StateInit] = None,
-        state_info: t.Optional[ContractStateInfo] = None,
+        info: t.Optional[ContractInfo] = None,
         config: t.Optional[_C] = None,
         private_key: t.Optional[PrivateKey] = None,
     ) -> None:
@@ -71,7 +71,7 @@ class BaseWallet(BaseContract, WalletProtocol[_D, _C, _P], abc.ABC):
         :param client: TON client for blockchain interactions
         :param address: Wallet address on the blockchain
         :param state_init: Optional StateInit (code and data)
-        :param state_info: Optional preloaded contract state
+        :param info: Optional preloaded contract state
         :param config: Optional wallet configuration
         :param private_key: Optional private key for signing transactions
         """
@@ -82,7 +82,7 @@ class BaseWallet(BaseContract, WalletProtocol[_D, _C, _P], abc.ABC):
         if private_key is not None:
             self._private_key = private_key
             self._public_key = private_key.public_key
-        super().__init__(client, address, state_init, state_info)
+        super().__init__(client, address, state_init, info)
 
     @property
     def state_data(self) -> _D:
@@ -295,7 +295,7 @@ class BaseWallet(BaseContract, WalletProtocol[_D, _C, _P], abc.ABC):
         :return: Signed external message that was sent
         """
         external_msg = await self.build_external_message(messages, params)
-        await self.client.send_boc(external_msg.as_hex)
+        await self.client.send_message(external_msg.as_hex)
         return external_msg
 
     async def transfer_message(
@@ -325,7 +325,7 @@ class BaseWallet(BaseContract, WalletProtocol[_D, _C, _P], abc.ABC):
         """
         Build and send a transfer to a single destination.
 
-        :param destination: Recipient address (Address, string, or domain)
+        :param destination: Recipient address
         :param amount: Amount to send in nanotons
         :param body: Optional message body (Cell or text comment)
         :param state_init: Optional StateInit for contract deployment
@@ -334,7 +334,6 @@ class BaseWallet(BaseContract, WalletProtocol[_D, _C, _P], abc.ABC):
         :param params: Optional transaction parameters
         :return: Signed external message that was sent
         """
-        destination = await resolve_wallet_address(self.client, destination)
         message = TONTransferBuilder(
             destination=destination,
             amount=amount,

tonutils/contracts/wallet/messages.py

@@ -23,7 +23,6 @@ from tonutils.utils import (
     cell_to_b64,
     normalize_hash,
     to_nano,
-    resolve_wallet_address,
 )
 
 
@@ -191,7 +190,7 @@ class TONTransferBuilder(BaseMessageBuilder):
         """
         Initialize TON transfer builder.
 
-        :param destination: Recipient address (Address, string, or domain)
+        :param destination: Recipient address
         :param amount: Amount to send in nanotons
         :param body: Optional message body (Cell or text comment string)
         :param state_init: Optional StateInit for contract deployment
@@ -214,11 +213,10 @@ class TONTransferBuilder(BaseMessageBuilder):
         :param wallet: Wallet instance to build message for
         :return: WalletMessage with TON transfer
         """
-        destination = await resolve_wallet_address(wallet.client, self.destination)
         return WalletMessage(
             send_mode=self.send_mode,
             message=InternalMessage(
-                dest=destination,
+                dest=self.destination,
                 value=self.amount,
                 body=self.body,
                 state_init=self.state_init,
@@ -277,9 +275,8 @@ class NFTTransferBuilder(BaseMessageBuilder):
         :param wallet: Wallet instance to build message for
         :return: WalletMessage with NFT transfer
         """
-        destination = await resolve_wallet_address(wallet.client, self.destination)
         body = NFTTransferBody(
-            destination=destination,
+            destination=self.destination,
             response_address=self.response_address or wallet.address,
             custom_payload=self.custom_payload,
             forward_payload=self.forward_payload,
@@ -358,7 +355,6 @@ class JettonTransferBuilder(BaseMessageBuilder):
         :param wallet: Wallet instance to build message for
         :return: WalletMessage with jetton transfer
         """
-        destination = await resolve_wallet_address(wallet.client, self.destination)
         jetton_wallet_address = self.jetton_wallet_address
         if self.jetton_wallet_address is None:
             jetton_wallet_address = await get_wallet_address_get_method(
@@ -367,7 +363,7 @@ class JettonTransferBuilder(BaseMessageBuilder):
                 owner_address=wallet.address,
             )
         body = JettonTransferBody(
-            destination=destination,
+            destination=self.destination,
             jetton_amount=self.jetton_amount,
             response_address=self.response_address or wallet.address,
             custom_payload=self.custom_payload,

tonutils/contracts/wallet/versions/v5.py

@@ -219,13 +219,13 @@ class WalletV5R1(
 
         :return: Typed wallet data
         """
-        if not (self._state_info and self._state_info.data):
+        if not (self._info and self._info.data):
             raise StateNotLoadedError(self, missing="state_data")
 
         network_global_id = (
             NetworkGlobalID.TESTNET if self.client.network else NetworkGlobalID.MAINNET
         )
-        cs = self._state_info.data.begin_parse()
+        cs = self._info.data.begin_parse()
         return self._data_model.deserialize(cs, network_global_id)
 
     async def _build_msg_cell(

tonutils/exceptions.py

@@ -27,7 +27,7 @@ class TransportError(TonutilsError):
 
     Covers: TCP connect, ADNL handshake, send/recv, crypto failures.
 
-    :param endpoint: Server address as "host:port"
+    :param endpoint: Endpoint identifier (URL or "host:port").
     :param operation: What was attempted ("connect", "handshake", "send", "recv")
     :param reason: Why it failed ("timeout 2.0s", "connection refused", etc.)
     """
@@ -46,7 +46,7 @@ class TransportError(TonutilsError):
         self.endpoint = endpoint
         self.operation = operation
         self.reason = reason
-        super().__init__(f"{operation} failed at {endpoint}: {reason}")
+        super().__init__(f"{operation} failed: {reason} ({endpoint})")
 
 
 class ProviderError(TonutilsError):
@@ -64,14 +64,28 @@ class BalancerError(TonutilsError):
 class NotConnectedError(TonutilsError, RuntimeError):
     """Raise when an operation requires an active connection."""
 
+    component: str
     endpoint: t.Optional[str]
+    operation: t.Optional[str]
 
-    def __init__(self, endpoint: t.Optional[str] = None) -> None:
+    def __init__(
+        self,
+        *,
+        component: str = "client",
+        endpoint: t.Optional[str] = None,
+        operation: t.Optional[str] = None,
+        hint: t.Optional[str] = None,
+    ) -> None:
+        self.component = component
         self.endpoint = endpoint
-        if endpoint:
-            super().__init__(f"not connected to {endpoint}")
-        else:
-            super().__init__("not connected")
+        self.operation = operation
+
+        if hint is None:
+            hint = "Call connect() first or use an async context manager (`async with ...`)."
+
+        where = f" ({endpoint})" if endpoint else ""
+        prefix = f"cannot `{operation}`: " if operation else ""
+        super().__init__(f"{prefix}{component} is not connected{where}. {hint}")
 
 
 class ProviderTimeoutError(ProviderError, asyncio.TimeoutError):
@@ -90,7 +104,7 @@ class ProviderTimeoutError(ProviderError, asyncio.TimeoutError):
         self.timeout = timeout
         self.endpoint = endpoint
         self.operation = operation
-        super().__init__(f"{operation} timed out after {timeout}s at {endpoint}")
+        super().__init__(f"{operation} timed out after {timeout}s ({endpoint})")
 
 
 class ProviderResponseError(ProviderError):
@@ -109,7 +123,7 @@ class ProviderResponseError(ProviderError):
         self.code = code
         self.message = message
         self.endpoint = endpoint
-        super().__init__(f"request failed with code {code} at {endpoint}: {message}")
+        super().__init__(f"request failed: {code} {message} ({endpoint})")
 
 
 class RetryLimitError(ProviderError):
@@ -134,7 +148,9 @@ class RetryLimitError(ProviderError):
         self.attempts = attempts
         self.max_attempts = max_attempts
         self.last_error = last_error
-        super().__init__(f"retry exhausted ({attempts}/{max_attempts}): {last_error}")
+        super().__init__(
+            f"retry limit reached ({attempts}/{max_attempts}): {last_error}"
+        )
 
 
 class ContractError(ClientError):
@@ -153,14 +169,14 @@ class ContractError(ClientError):
         name = (
             target.__name__ if isinstance(target, type) else target.__class__.__name__
         )
-        super().__init__(f"{name}: {message}")
+        super().__init__(f"{name} failed: {message}")
 
 
 class StateNotLoadedError(ContractError):
     """Raise when a contract wrapper requires state that is not loaded.
 
     :param contract: Contract instance related to the failure.
-    :param missing: Missing field name (e.g. "state_info", "state_data").
+    :param missing: Missing field name (e.g. "info", "state_data").
     """
 
     missing: str
@@ -188,7 +204,7 @@ class RunGetMethodError(ClientError):
         self.method_name = method_name
         self.exit_code = exit_code
         super().__init__(
-            f"get-method '{method_name}' failed for {address} with exit code {exit_code}"
+            f"get-method `{method_name}` failed: exit code {exit_code} ({address})"
         )