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

tonutils/clients/http/providers/toncenter/provider.py

@@ -0,0 +1,119 @@
+import typing as t
+
+import aiohttp
+from pydantic import BaseModel
+
+from tonutils.clients.http.providers.base import HttpProvider
+from tonutils.clients.http.providers.toncenter.models import (
+    GetAddressInformationResult,
+    GetConfigAllResult,
+    GetTransactionResult,
+    RunGetMethodResul,
+    SendBocPayload,
+    RunGetMethodPayload,
+)
+from tonutils.types import NetworkGlobalID, RetryPolicy
+
+
+class ToncenterHttpProvider(HttpProvider):
+
+    def __init__(
+        self,
+        network: NetworkGlobalID,
+        api_key: t.Optional[str] = None,
+        base_url: t.Optional[str] = None,
+        timeout: float = 10.0,
+        session: t.Optional[aiohttp.ClientSession] = None,
+        headers: t.Optional[t.Dict[str, str]] = None,
+        cookies: t.Optional[t.Dict[str, str]] = None,
+        rps_limit: t.Optional[int] = None,
+        rps_period: float = 1.0,
+        retry_policy: t.Optional[RetryPolicy] = None,
+    ) -> None:
+        urls = {
+            NetworkGlobalID.MAINNET: "https://toncenter.com/api/v2",
+            NetworkGlobalID.TESTNET: "https://testnet.toncenter.com/api/v2",
+        }
+        base_url = base_url or urls[network]
+        headers = {**(headers or {}), **({"X-Api-Key": api_key} if api_key else {})}
+        super().__init__(
+            base_url=base_url,
+            session=session,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            rps_limit=rps_limit,
+            rps_period=rps_period,
+            retry_policy=retry_policy,
+        )
+
+    @staticmethod
+    def _model(model: t.Type[BaseModel], data: t.Any) -> t.Any:
+        return model.model_validate(data)
+
+    async def send_boc(
+        self,
+        payload: SendBocPayload,
+    ) -> None:
+        await self.send_http_request(
+            "POST",
+            "/sendBoc",
+            json_data=payload.model_dump(),
+        )
+
+    async def get_config_all(
+        self,
+    ) -> GetConfigAllResult:
+        return self._model(
+            GetConfigAllResult,
+            await self.send_http_request(
+                "GET",
+                "/getConfigAll",
+            ),
+        )
+
+    async def get_address_information(
+        self,
+        address: str,
+    ) -> GetAddressInformationResult:
+        return self._model(
+            GetAddressInformationResult,
+            await self.send_http_request(
+                "GET",
+                "/getAddressInformation",
+                params={"address": address},
+            ),
+        )
+
+    async def get_transaction(
+        self,
+        address: str,
+        limit: int = 100,
+        from_lt: t.Optional[int] = None,
+        to_lt: int = 0,
+    ) -> GetTransactionResult:
+        params = {"address": address, "limit": limit, "to_lt": to_lt}
+        if from_lt is not None:
+            params["from_lt"] = from_lt
+
+        return self._model(
+            GetTransactionResult,
+            await self.send_http_request(
+                "GET",
+                "/getTransactions",
+                params=params,
+            ),
+        )
+
+    async def run_get_method(
+        self,
+        payload: RunGetMethodPayload,
+    ) -> RunGetMethodResul:
+        return self._model(
+            RunGetMethodResul,
+            await self.send_http_request(
+                "POST",
+                "/runGetMethod",
+                json_data=payload.model_dump(),
+            ),
+        )

tonutils/clients/http/utils.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import typing as t
+
+from pytoniq_core import Address, Cell, Slice
+
+from tonutils.types import StackTag, StackItem, StackItems
+from tonutils.utils import cell_to_b64, cell_to_hex, norm_stack_num, norm_stack_cell
+
+
+def decode_toncenter_stack(items: t.List[t.Any]) -> StackItems:
+    """
+    Decode Toncenter TVM stack format into internal python structures.
+
+    Converts Toncenter stack elements into native Python values:
+    - NUM → int
+    - CELL/SLICE → Cell or Address (auto-detected)
+    - LIST/TUPLE → recursively decoded lists
+    - NULL → None
+
+    :param items: Raw stack items as returned by Toncenter
+    :return: Normalized list of decoded stack values
+    """
+    out: StackItems = []
+    for item in items:
+        if not (isinstance(item, list) and len(item) == 2):
+            continue
+        tag, payload = item
+        if tag == StackTag.NULL:
+            out.append(None)
+        elif tag == StackTag.NUM.value:
+            out.append(norm_stack_num(payload))
+        elif tag in (
+            StackTag.CELL.value,
+            StackTag.TVM_CELL.value,
+            StackTag.SLICE.value,
+            StackTag.TVM_SLICE.value,
+        ):
+            out.append(norm_stack_cell((payload or {}).get("bytes")))
+        elif tag in (StackTag.LIST.value, StackTag.TUPLE.value):
+            elements = (payload or {}).get("elements") or []
+            out.append(decode_toncenter_stack(elements) if len(elements) > 0 else None)
+    return out
+
+
+def encode_toncenter_stack(items: t.List[StackItem]) -> t.List[list]:
+    """
+    Encode Python stack values into Toncenter-compatible TVM stack format.
+
+    Supports:
+    - int → NUM
+    - Cell → TVM_CELL
+    - Slice → TVM_SLICE
+    - list/tuple → LIST/TUPLE (recursive)
+    - Address → encoded as TVM_CELL
+
+    :param items: List of python TVM stack values
+    :return: Encoded stack items suitable for Toncenter API
+    """
+    out: t.List[t.Any] = []
+    for item in items:
+        tpe = StackTag.of(item)
+        if tpe is StackTag.NUM:
+            out.append([StackTag.NUM.value, str(t.cast(str, item))])
+        elif tpe is StackTag.CELL:
+            cell = item.to_cell() if isinstance(item, Address) else t.cast(Cell, item)
+            out.append([StackTag.TVM_CELL.value, cell_to_b64(cell)])
+        elif tpe is StackTag.SLICE:
+            cell = t.cast(Slice, item).to_cell()
+            out.append([StackTag.TVM_SLICE.value, cell_to_b64(cell)])
+        elif tpe in (StackTag.LIST, StackTag.TUPLE):
+            out.append(
+                [tpe.value, {"elements": encode_toncenter_stack(t.cast(list, item))}]
+            )
+    return out
+
+
+def decode_tonapi_stack(items: t.List[t.Any]) -> StackItems:
+    """
+    Decode Tonapi TVM stack format into internal Python structures.
+
+    Tonapi represents stack items as dictionaries with a "type" key and
+    a value under the same key. This function converts them into:
+    - NUM → int
+    - CELL/SLICE → Cell or Address (auto-detected)
+    - LIST/TUPLE → nested Python lists
+    - NULL → None
+
+    :param items: Raw stack items as returned by Tonapi
+    :return: Normalized list of decoded stack values
+    """
+    out: StackItems = []
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        tpe = item.get("type")
+        val = item.get(tpe)
+        if tpe == StackTag.NULL.value:
+            out.append(None)
+        elif tpe == StackTag.NUM.value and val is not None:
+            out.append(norm_stack_num(t.cast(str | int, val)))
+        elif tpe in (StackTag.CELL.value, StackTag.SLICE.value):
+            out.append(norm_stack_cell(val))
+        elif tpe in (StackTag.LIST.value, StackTag.TUPLE.value):
+            inner: t.List[t.Any] = []
+            for el in val or []:
+                inner.append(
+                    decode_tonapi_stack([el])[0] if isinstance(el, dict) else el
+                )
+            out.append(inner)
+    return out
+
+
+def encode_tonapi_stack(items: t.List[StackItem]) -> t.List[t.Any]:
+    """
+    Encode Python TVM stack values into Tonapi-compatible format.
+
+    Produces values expected by Tonapi query parameters:
+    - int → hex string
+    - Cell/Address → hex BoC string
+    - Slice → hex BoC string
+    - list/tuple → recursively encoded list
+
+    :param items: List of python TVM stack values
+    :return: Encoded stack items suitable for Tonapi API
+    """
+    out: t.List[t.Any] = []
+    for item in items:
+        tpe = StackTag.of(item)
+        if tpe == StackTag.NUM:
+            out.append(hex(t.cast(int, item)))
+        elif tpe == StackTag.CELL:
+            cell = item.to_cell() if isinstance(item, Address) else item
+            out.append(cell_to_hex(cell))
+        elif tpe == StackTag.SLICE:
+            cell = t.cast(Slice, item).to_cell()
+            out.append(cell_to_hex(cell))
+        elif tpe in (StackTag.LIST, StackTag.TUPLE):
+            out.append(encode_tonapi_stack(t.cast(list, item)))
+    return out

tonutils/clients/limiter.py

@@ -0,0 +1,115 @@
+import asyncio
+import time
+
+
+class RateLimiter:
+    """
+    Asynchronous token-bucket rate limiter with optional priority acquisition.
+
+    Limits the number of acquire operations per time period and supports
+    priority waiters that can bypass non-priority requests when tokens
+    become available.
+    """
+
+    __slots__ = (
+        "_max_rate",
+        "_period",
+        "_tokens",
+        "_updated_at",
+        "_cond",
+        "_priority_waiters",
+    )
+
+    def __init__(self, max_rate: int, period: float = 1.0) -> None:
+        """
+        Initialize the rate limiter.
+
+        :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.
+        """
+        if max_rate <= 0:
+            raise ValueError("max_rate must be > 0")
+        if period <= 0:
+            raise ValueError("period must be > 0")
+
+        self._max_rate = max_rate
+        self._period = period
+        self._tokens = float(max_rate)
+        self._updated_at = time.monotonic()
+        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.
+        """
+        now = time.monotonic()
+        tokens = self._peek_tokens(now)
+        if tokens >= 1.0:
+            return 0.0
+        return self._seconds_to_one_token(tokens)
+
+    async def acquire(self, priority: bool = False) -> None:
+        """
+        Acquire a single token, waiting asynchronously if necessary.
+
+        Priority acquisitions are allowed to bypass non-priority waiters
+        when tokens become available.
+
+        :param priority: Whether to acquire the token with priority.
+        """
+        if priority:
+            async with self._cond:
+                self._priority_waiters += 1
+
+            try:
+                await self._acquire(priority=True)
+            finally:
+                async with self._cond:
+                    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 _peek_tokens(self, now: float) -> float:
+        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
+
+    def _seconds_to_one_token(self, tokens: float) -> float:
+        missing = 1.0 - tokens
+        if missing <= 0.0:
+            return 0.0
+
+        rate = self._max_rate / self._period
+        return missing / rate

tonutils/contracts/__init__.py

@@ -91,6 +91,7 @@ from .nft import (
     royalty_params_get_method,
 )
 from .opcodes import OpCode
+from .protocol import ContractProtocol
 from .telegram import (
     TeleCollectionData,
     TeleItemAuction,
@@ -142,6 +143,7 @@ from .wallet import (
     WalletHighloadV3Data,
     WalletHighloadV3Params,
     WalletHighloadV3R1,
+    WalletProtocol,
     WalletPreprocessedV2,
     WalletPreprocessedV2Config,
     WalletPreprocessedV2Data,
@@ -194,6 +196,7 @@ __all__ = [
     "BaseMessageBuilder",
     "ChangeDNSRecordBody",
     "CONTRACT_CODES",
+    "ContractProtocol",
     "ContractVersion",
     "DNSBalanceReleaseBody",
     "DNSRecordDNSNextResolver",
@@ -297,6 +300,7 @@ __all__ = [
     "WalletHighloadV3Data",
     "WalletHighloadV3Params",
     "WalletHighloadV3R1",
+    "WalletProtocol",
     "WalletPreprocessedV2",
     "WalletPreprocessedV2Config",
     "WalletPreprocessedV2Data",

tonutils/contracts/base.py

@@ -2,14 +2,17 @@ from __future__ import annotations
 
 import typing as t
 
-from pyapiq.exceptions import APIQException, RateLimitExceeded
 from pytoniq_core import Address, Cell, StateInit, TlbScheme
 
+from tonutils.clients.protocol import ClientProtocol
 from tonutils.contracts.codes import CONTRACT_CODES
+from tonutils.contracts.protocol import ContractProtocol
 from tonutils.contracts.versions import ContractVersion
-from tonutils.exceptions import ContractError, NotRefreshedError
-from tonutils.protocols.client import ClientProtocol
-from tonutils.protocols.contract import ContractProtocol
+from tonutils.exceptions import (
+    ContractError,
+    StateNotLoadedError,
+    ProviderResponseError,
+)
 from tonutils.types import AddressLike, ContractState, ContractStateInfo, WorkchainID
 from tonutils.utils import to_cell
 
@@ -49,7 +52,7 @@ class BaseContract(ContractProtocol[_D]):
             default_code = to_cell(CONTRACT_CODES[cls.VERSION])
         except KeyError:
             raise ContractError(
-                cls, f"No contract code defined for `VERSION` {cls.VERSION!r}."
+                cls, f"No contract code defined for `version` {cls.VERSION!r}."
             )
         return default_code
 
@@ -96,7 +99,7 @@ class BaseContract(ContractProtocol[_D]):
         :return: Contract state information
         """
         if self._state_info is None:
-            raise NotRefreshedError(self, "state_info")
+            raise StateNotLoadedError(self, missing="state_info")
         return t.cast(ContractStateInfo, self._state_info)
 
     @property
@@ -111,7 +114,7 @@ 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):
-            raise NotRefreshedError(self, "state_data")
+            raise StateNotLoadedError(self, missing="state_data")
         cs = self._state_info.data.begin_parse()
         return self._data_model.deserialize(cs)
 
@@ -205,6 +208,26 @@ class BaseContract(ContractProtocol[_D]):
         """
         return self.state_info.data
 
+    @classmethod
+    async def _load_state_info(
+        cls,
+        client: ClientProtocol,
+        address: Address,
+    ) -> ContractStateInfo:
+        """
+        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)
+        except ProviderResponseError as e:
+            if e.code in {429, 228, 5556}:  # rate limit exceed
+                raise
+            return ContractStateInfo()
+        except (Exception,):
+            return ContractStateInfo()
+
     async def refresh(self) -> None:
         """
         Refresh contract state from the blockchain.
@@ -212,13 +235,7 @@ class BaseContract(ContractProtocol[_D]):
         Fetches current contract information and updates the cached state_info.
         If the request fails (except rate limits), sets state to default empty state.
         """
-        try:
-            state_info = await self.client.get_contract_info(self.address)
-        except RateLimitExceeded:
-            raise
-        except APIQException:
-            state_info = ContractStateInfo()
-        self._state_info = state_info
+        self._state_info = await self._load_state_info(self.client, self.address)
 
     @classmethod
     def from_state_init(
@@ -305,12 +322,8 @@ class BaseContract(ContractProtocol[_D]):
             address = Address(address)
         if not load_state:
             return cls(client, address)
-        try:
-            state_info = await client.get_contract_info(address)
-        except RateLimitExceeded:
-            raise
-        except APIQException:
-            state_info = ContractStateInfo()
+
+        state_info = await cls._load_state_info(client, address)
         return cls(client, address, state_info=state_info)
 
     def __repr__(self) -> str:

tonutils/contracts/dns/methods.py

@@ -2,8 +2,8 @@ import typing as t
 
 from pytoniq_core import Cell, begin_cell
 
-from tonutils.protocols.client import ClientProtocol
-from tonutils.protocols.contract import ContractProtocol
+from tonutils.clients.protocol import ClientProtocol
+from tonutils.contracts.protocol import ContractProtocol
 from tonutils.types import AddressLike, DNSCategory
 
 

tonutils/contracts/jetton/methods.py

@@ -2,8 +2,8 @@ import typing as t
 
 from pytoniq_core import Address
 
-from tonutils.protocols.client import ClientProtocol
-from tonutils.protocols.contract import ContractProtocol
+from tonutils.clients.protocol import ClientProtocol
+from tonutils.contracts.protocol import ContractProtocol
 from tonutils.types import AddressLike
 
 

tonutils/contracts/nft/methods.py

@@ -2,8 +2,8 @@ import typing as t
 
 from pytoniq_core import Address, Cell
 
-from tonutils.protocols.client import ClientProtocol
-from tonutils.protocols.contract import ContractProtocol
+from tonutils.clients.protocol import ClientProtocol
+from tonutils.contracts.protocol import ContractProtocol
 from tonutils.types import AddressLike
 
 

tonutils/contracts/nft/tlb.py

@@ -822,7 +822,7 @@ class NFTCollectionBatchMintItemBody(TlbScheme):
         :return: Sorted list of (index, amount, item_ref) tuples
         """
         hashmap = cs.load_dict(key_length=64)
-        out: list[tuple[int, int, Cell]] = []
+        out: t.List[tuple[int, int, Cell]] = []
         for key, val in hashmap.items():
             amount = val.load_coins()
             item_ref = val.load_ref()