tonutils 0.5.1__py3-none-any.whl → 0.6.0a1__py3-none-any.whl

tonutils/{client → clients}/__init__.py

@@ -1,21 +1,13 @@
-from ._base import Client
-
-from .lite import LiteserverClient
+from .liteserver import LiteserverClient
 from .quicknode import QuicknodeClient
 from .tatum import TatumClient
 from .tonapi import TonapiClient
-from .toncenter import (
-    ToncenterV2Client,
-    ToncenterV3Client,
-)
+from .toncenter import ToncenterClient
 
 __all__ = [
-    "Client",
-
     "LiteserverClient",
     "QuicknodeClient",
     "TatumClient",
     "TonapiClient",
-    "ToncenterV2Client",
-    "ToncenterV3Client",
+    "ToncenterClient",
 ]

tonutils/clients/base.py

@@ -0,0 +1,95 @@
+import abc
+import typing as t
+
+from pyapiq import AsyncClientAPI
+from pytoniq_core import Address, Transaction
+
+from .liteserver.stub import LiteBalancer
+from ..types import AddressLike, ContractStateInfo
+
+A = t.TypeVar("A", bound=t.Union[AsyncClientAPI, LiteBalancer])
+
+
+class BaseClient(abc.ABC, t.Generic[A]):
+    is_testnet: bool
+    api: A
+
+    @abc.abstractmethod
+    async def _send_boc(self, boc: str) -> None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def _get_blockchain_config(self) -> t.Dict[int, t.Any]:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def _get_contract_info(self, address: str) -> ContractStateInfo:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def _get_contract_transactions(
+        self,
+        address: str,
+        limit: int = 100,
+        from_lt: t.Optional[int] = None,
+        to_lt: t.Optional[int] = 0,
+    ) -> t.List[Transaction]:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def _run_get_method(
+        self,
+        address: str,
+        method_name: str,
+        stack: t.Optional[t.List[t.Any]] = None,
+    ) -> t.List[t.Any]:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def startup(self) -> None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def close(self) -> None:
+        raise NotImplementedError
+
+    async def send_boc(self, boc: str) -> None:
+        await self._send_boc(boc)
+
+    async def get_blockchain_config(self) -> t.Dict[int, t.Any]:
+        return await self._get_blockchain_config()
+
+    async def get_contract_info(self, address: AddressLike) -> ContractStateInfo:
+        if isinstance(address, Address):
+            address = Address(address).to_str(is_user_friendly=False)
+        return await self._get_contract_info(address=address)
+
+    async def get_contract_transactions(
+        self,
+        address: AddressLike,
+        limit: int = 100,
+        from_lt: t.Optional[int] = None,
+        to_lt: t.Optional[int] = 0,
+    ) -> t.List[Transaction]:
+        if isinstance(address, Address):
+            address = Address(address).to_str(is_user_friendly=False)
+        return await self._get_contract_transactions(
+            address=address,
+            limit=limit,
+            from_lt=from_lt,
+            to_lt=to_lt,
+        )
+
+    async def run_get_method(
+        self,
+        address: AddressLike,
+        method_name: str,
+        stack: t.Optional[t.List[t.Any]] = None,
+    ) -> t.List[t.Any]:
+        if isinstance(address, Address):
+            address = Address(address).to_str(is_user_friendly=False)
+        return await self._run_get_method(
+            address=address,
+            method_name=method_name,
+            stack=stack,
+        )

tonutils/clients/liteserver/__init__.py

@@ -0,0 +1,3 @@
+from .client import LiteserverClient
+
+__all__ = ["LiteserverClient"]

tonutils/clients/liteserver/client.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import typing as t
+from functools import wraps
+
+from pytoniq_core import Address, SimpleAccount, Transaction
+
+from ..base import BaseClient
+from ...exceptions import PytoniqDependencyError
+from ...types import (
+    ContractStateInfo,
+    ContractState,
+    ClientType,
+)
+from ...utils import (
+    StackCodec,
+    cell_to_hex,
+)
+
+try:
+    # noinspection PyPackageRequirements
+    from pytoniq import LiteBalancer
+
+    pytoniq_available = True
+except ImportError:
+    pytoniq_available = False
+    from .stub import LiteBalancer
+
+F = t.TypeVar("F", bound=t.Callable[..., t.Any])
+
+
+def _ensure_api_ready(func: F) -> F:
+
+    @wraps(func)
+    async def wrapper(self: LiteserverClient, *args: t.Any, **kwargs: t.Any) -> t.Any:
+        if not pytoniq_available:
+            raise PytoniqDependencyError()
+        if not self.api.inited:
+            await self.api.start_up()
+        return await func(self, *args, **kwargs)
+
+    return t.cast(F, wrapper)
+
+
+class LiteserverClient(BaseClient[LiteBalancer]):
+
+    def __init__(
+        self,
+        config: t.Optional[t.Dict[str, t.Any]] = None,
+        is_testnet: bool = False,
+        trust_level: int = 2,
+    ) -> None:
+        if not pytoniq_available:
+            raise PytoniqDependencyError()
+
+        if config is not None:
+            self.api = LiteBalancer.from_config(config, trust_level)
+        elif is_testnet:
+            self.api = LiteBalancer.from_testnet_config(trust_level)
+        else:
+            self.api = LiteBalancer.from_mainnet_config(trust_level)
+
+        self.is_testnet = is_testnet
+
+    async def __aenter__(self) -> LiteBalancer:
+        return await self.api.__aenter__()
+
+    async def __aexit__(
+        self,
+        exc_type: t.Optional[t.Type[BaseException]],
+        exc_value: t.Optional[BaseException],
+        traceback: t.Optional[t.Any],
+    ) -> None:
+        await self.api.__aexit__(exc_type, exc_value, traceback)
+
+    @_ensure_api_ready
+    async def _send_boc(self, boc: str) -> None:
+        await self.api.raw_send_message(bytes.fromhex(boc))
+
+    @_ensure_api_ready
+    async def _get_blockchain_config(self) -> t.Dict[int, t.Any]:
+        return await self.api.get_config_all()
+
+    @_ensure_api_ready
+    async def _get_contract_info(self, address: str) -> ContractStateInfo:
+        account, shard_account = await self.api.raw_get_account_state(address)
+
+        simple_account = SimpleAccount.from_raw(account, Address(address))
+        contract_info = ContractStateInfo(balance=simple_account.balance)
+
+        if simple_account.state is not None:
+            state_init = simple_account.state.state_init
+            if state_init is not None:
+                if state_init.code is not None:
+                    contract_info.code_raw = cell_to_hex(state_init.code)
+                if state_init.data is not None:
+                    contract_info.data_raw = cell_to_hex(state_init.data)
+
+            contract_info.state = ContractState(
+                "uninit"
+                if simple_account.state.type_ == "uninitialized"
+                else simple_account.state.type_
+            )
+
+        if shard_account is not None:
+            if shard_account.last_trans_lt is not None:
+                contract_info.last_transaction_lt = int(shard_account.last_trans_lt)
+            if shard_account.last_trans_hash is not None:
+                contract_info.last_transaction_hash = (
+                    shard_account.last_trans_hash.hex()
+                )
+        if (
+            contract_info.last_transaction_lt is None
+            and contract_info.last_transaction_hash is None
+            and contract_info.state == ContractState.UNINIT
+        ):
+            contract_info.state = ContractState.NONEXIST
+
+        return contract_info
+
+    @_ensure_api_ready
+    async def _get_contract_transactions(
+        self,
+        address: str,
+        limit: int = 100,
+        from_lt: t.Optional[int] = None,
+        to_lt: t.Optional[int] = 0,
+    ) -> t.List[Transaction]:
+        return await self.api.get_transactions(
+            address=Address(address),
+            count=limit,
+            from_lt=from_lt,
+            to_lt=to_lt,
+        )
+
+    @_ensure_api_ready
+    async def _run_get_method(
+        self,
+        address: str,
+        method_name: str,
+        stack: t.Optional[t.List[t.Any]] = None,
+    ) -> t.List[t.Any]:
+        stack_codec = StackCodec(ClientType.LITESERVER)
+        stack_result = await self.api.run_get_method(
+            address=address,
+            method=method_name,
+            stack=stack_codec.encode(stack or []),
+        )
+        return stack_codec.decode(stack_result or [])
+
+    async def startup(self) -> None:
+        await self.api.start_up()
+
+    async def close(self) -> None:
+        await self.api.close_all()

tonutils/clients/liteserver/stub.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import typing as t
+from types import TracebackType
+
+from pytoniq_core import Address, Transaction
+
+from ...exceptions import PytoniqDependencyError
+
+
+class LiteBalancer:
+    inited: bool = False
+
+    @staticmethod
+    def from_config(
+        config: t.Dict[str, t.Any],
+        trust_level: int,
+    ) -> LiteBalancer:
+        raise PytoniqDependencyError()
+
+    @staticmethod
+    def from_testnet_config(trust_level: int) -> LiteBalancer:
+        raise PytoniqDependencyError()
+
+    @staticmethod
+    def from_mainnet_config(trust_level: int) -> LiteBalancer:
+        raise PytoniqDependencyError()
+
+    async def __aenter__(self) -> LiteBalancer:
+        raise PytoniqDependencyError()
+
+    async def __aexit__(
+        self,
+        exc_type: t.Optional[type[BaseException]],
+        exc_value: t.Optional[BaseException],
+        traceback: t.Optional[TracebackType],
+    ) -> None:
+        raise PytoniqDependencyError()
+
+    async def run_get_method(
+        self,
+        address: t.Union[str, Address],
+        method: str,
+        stack: t.List[t.Any],
+    ) -> t.Any:
+        raise PytoniqDependencyError()
+
+    async def raw_send_message(self, message: bytes) -> None:
+        raise PytoniqDependencyError()
+
+    async def start_up(self):
+        raise PytoniqDependencyError()
+
+    async def close_all(self):
+        raise PytoniqDependencyError()
+
+    async def raw_get_account_state(self, address):
+        raise PytoniqDependencyError()
+
+    async def get_config_all(self) -> t.Dict[int, t.Any]:
+        raise PytoniqDependencyError()
+
+    async def get_transactions(
+        self,
+        address: t.Union[str, Address],
+        count: int,
+        from_lt: t.Optional[int] = None,
+        to_lt: int = 0,
+    ) -> t.List[Transaction]:
+        raise PytoniqDependencyError()

tonutils/clients/quicknode/__init__.py

@@ -0,0 +1,3 @@
+from .client import QuicknodeClient
+
+__all__ = ["QuicknodeClient"]

tonutils/clients/quicknode/api.py

@@ -0,0 +1,19 @@
+import typing as t
+
+from ..toncenter.api import ToncenterAPI
+
+
+class QuicknodeAPI(ToncenterAPI):
+
+    def __init__(
+        self,
+        http_provider_url: str,
+        rps: t.Optional[int] = None,
+        max_retries: t.Optional[int] = None,
+    ) -> None:
+        super().__init__(
+            is_testnet=False,
+            base_url=http_provider_url,
+            rps=rps,
+            max_retries=max_retries,
+        )

tonutils/clients/quicknode/client.py

@@ -0,0 +1,20 @@
+import typing as t
+
+from .api import QuicknodeAPI
+from ..toncenter.client import ToncenterClient
+
+
+class QuicknodeClient(ToncenterClient):
+
+    def __init__(
+        self,
+        http_provider_url: str,
+        rps: t.Optional[int] = None,
+        max_retries: int = 2,
+    ) -> None:
+        super().__init__(is_testnet=False)
+        self.api = QuicknodeAPI(
+            http_provider_url=http_provider_url,
+            rps=rps,
+            max_retries=max_retries,
+        )

tonutils/clients/tatum/__init__.py

@@ -0,0 +1,3 @@
+from .client import TatumClient
+
+__all__ = ["TatumClient"]

tonutils/clients/tatum/api.py

@@ -0,0 +1,28 @@
+import typing as t
+
+from ..toncenter.api import ToncenterAPI
+
+
+class TatumAPI(ToncenterAPI):
+
+    def __init__(
+        self,
+        api_key: str,
+        is_testnet: bool = False,
+        base_url: t.Optional[str] = None,
+        rps: t.Optional[int] = None,
+        max_retries: t.Optional[int] = None,
+    ) -> None:
+        mainnet_url = "https://ton-mainnet.gateway.tatum.io"
+        testnet_url = "https://ton-testnet.gateway.tatum.io"
+        default_url = testnet_url if is_testnet else mainnet_url
+
+        base_url = base_url or default_url
+
+        super().__init__(
+            api_key=api_key,
+            is_testnet=is_testnet,
+            base_url=base_url,
+            rps=rps,
+            max_retries=max_retries,
+        )

tonutils/clients/tatum/client.py

@@ -0,0 +1,24 @@
+import typing as t
+
+from .api import TatumAPI
+from ..toncenter.client import ToncenterClient
+
+
+class TatumClient(ToncenterClient):
+
+    def __init__(
+        self,
+        api_key: str,
+        is_testnet: bool = False,
+        base_url: t.Optional[str] = None,
+        rps: t.Optional[int] = None,
+        max_retries: int = 2,
+    ) -> None:
+        super().__init__(is_testnet=is_testnet)
+        self.api = TatumAPI(
+            api_key=api_key,
+            is_testnet=is_testnet,
+            base_url=base_url,
+            rps=rps,
+            max_retries=max_retries,
+        )

tonutils/clients/tonapi/__init__.py

@@ -0,0 +1,3 @@
+from .client import TonapiClient
+
+__all__ = ["TonapiClient"]

tonutils/clients/tonapi/api.py

@@ -0,0 +1,93 @@
+import typing as t
+
+from pyapiq import AsyncClientAPI, async_endpoint
+from pyapiq.types import ReturnType, RepeatQuery, HTTPMethod
+
+from .models import (
+    BlockchainMessagePayload,
+    BlockchainConfigResult,
+    BlockchainAccountResult,
+    BlockchainAccountTransactionsResult,
+    BlockchainAccountMethodResult,
+)
+
+
+class TonapiAPI(AsyncClientAPI):
+    version = "v2"
+
+    def __init__(
+        self,
+        api_key: str,
+        is_testnet: bool = False,
+        base_url: t.Optional[str] = None,
+        rps: t.Optional[int] = None,
+        max_retries: t.Optional[int] = None,
+    ) -> None:
+        mainnet_url = "https://tonapi.io"
+        testnet_url = "https://testnet.tonapi.io"
+        default_url = testnet_url if is_testnet else mainnet_url
+
+        base_url = base_url or default_url
+        headers = {"Authorization": f"Bearer {api_key}"}
+
+        super().__init__(
+            base_url=base_url,
+            headers=headers,
+            rps=rps,
+            max_retries=max_retries,
+        )
+
+    @async_endpoint(
+        HTTPMethod.POST,
+        path="/blockchain/message",
+        return_as=ReturnType.NONE,
+    )
+    async def blockchain_message(  # type: ignore[empty-body]
+        self,
+        payload: BlockchainMessagePayload,
+    ) -> None: ...
+
+    @async_endpoint(
+        HTTPMethod.GET,
+        path="/blockchain/config",
+        return_as=BlockchainConfigResult,
+    )
+    async def blockchain_config(  # type: ignore[empty-body]
+        self,
+    ) -> BlockchainConfigResult: ...
+
+    @async_endpoint(
+        HTTPMethod.GET,
+        path="/blockchain/accounts/{address}",
+        return_as=BlockchainAccountResult,
+    )
+    async def blockchain_account(  # type: ignore[empty-body]
+        self,
+        address: str,
+    ) -> BlockchainAccountResult: ...
+
+    @async_endpoint(
+        HTTPMethod.GET,
+        path="/blockchain/accounts/{address}/transactions",
+        return_as=BlockchainAccountTransactionsResult,
+    )
+    async def blockchain_account_transactions(  # type: ignore[empty-body]
+        self,
+        address: str,
+        limit: int = 100,
+        after_lt: t.Optional[int] = None,
+        before_lt: t.Optional[int] = 0,
+        sort_order: t.Optional[t.Literal["asc", "desc"]] = "desc",
+    ) -> BlockchainAccountTransactionsResult: ...
+
+    @async_endpoint(
+        HTTPMethod.GET,
+        path="/blockchain/accounts/{address}/methods/{method_name}",
+        return_as=BlockchainAccountMethodResult,
+    )
+    async def blockchain_account_method(  # type: ignore[empty-body]
+        self,
+        address: str,
+        method_name: str,
+        args: t.Annotated[t.List[t.Any], RepeatQuery],
+    ) -> BlockchainAccountMethodResult: ...

tonutils/clients/tonapi/client.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import typing as t
+from functools import wraps
+
+from pyapiq import AsyncClientAPI
+from pytoniq_core import Cell, Slice, Transaction
+
+from .api import TonapiAPI
+from .models import BlockchainMessagePayload
+from ..base import BaseClient
+from ...exceptions import ClientError
+from ...types import (
+    ContractStateInfo,
+    ContractState,
+    ClientType,
+)
+from ...utils import (
+    StackCodec,
+    cell_to_hex,
+    parse_config,
+)
+
+F = t.TypeVar("F", bound=t.Callable[..., t.Any])
+
+
+def _ensure_api_ready(func: F) -> F:
+
+    @wraps(func)
+    async def wrapper(self: "TonapiClient", *args: t.Any, **kwargs: t.Any) -> t.Any:
+        if self.api.session is None:
+            await self.api.ensure_session()
+        return await func(self, *args, **kwargs)
+
+    return t.cast(F, wrapper)
+
+
+class TonapiClient(BaseClient[TonapiAPI]):
+
+    def __init__(
+        self,
+        api_key: str,
+        is_testnet: bool = False,
+        base_url: t.Optional[str] = None,
+        rps: t.Optional[int] = None,
+        max_retries: int = 2,
+    ) -> None:
+        self.is_testnet = is_testnet
+        self.api = TonapiAPI(
+            api_key=api_key,
+            is_testnet=is_testnet,
+            base_url=base_url,
+            rps=rps,
+            max_retries=max_retries,
+        )
+
+    async def __aenter__(self) -> AsyncClientAPI:
+        return await self.api.__aenter__()
+
+    async def __aexit__(
+        self,
+        exc_type: t.Optional[t.Type[BaseException]],
+        exc_value: t.Optional[BaseException],
+        traceback: t.Optional[t.Any],
+    ) -> None:
+        await self.api.__aexit__(exc_type, exc_value, traceback)
+
+    @_ensure_api_ready
+    async def _send_boc(self, boc: str) -> None:
+        payload = BlockchainMessagePayload(boc=boc)
+        return await self.api.blockchain_message(payload=payload)
+
+    @_ensure_api_ready
+    async def _get_blockchain_config(self) -> t.Dict[int, t.Any]:
+        result = await self.api.blockchain_config()
+
+        if result.raw is None:
+            raise ClientError("Invalid config response: missing 'raw' field")
+
+        config_cell = Cell.one_from_boc(result.raw)[0]
+        config_slice = config_cell.begin_parse()
+        return parse_config(config_slice)
+
+    @_ensure_api_ready
+    async def _get_contract_info(self, address: str) -> ContractStateInfo:
+        result = await self.api.blockchain_account(address)
+
+        contract_info = ContractStateInfo(
+            balance=result.balance,
+            state=ContractState(result.status),
+            last_transaction_lt=result.last_transaction_lt,
+            last_transaction_hash=result.last_transaction_hash,
+        )
+        if result.code is not None:
+            contract_info.code_raw = cell_to_hex(result.code)
+        if result.data is not None:
+            contract_info.data_raw = cell_to_hex(result.data)
+
+        return contract_info
+
+    @_ensure_api_ready
+    async def _get_contract_transactions(
+        self,
+        address: str,
+        limit: int = 100,
+        from_lt: t.Optional[int] = None,
+        to_lt: t.Optional[int] = 0,
+    ) -> t.List[Transaction]:
+        if from_lt is not None:
+            from_lt += 1
+
+        result = await self.api.blockchain_account_transactions(
+            address=address,
+            limit=limit,
+            after_lt=to_lt,
+            before_lt=from_lt,
+        )
+
+        transactions = []
+        for tx in result.transactions or []:
+            if tx.raw is not None:
+                tx_slice = Slice.one_from_boc(tx.raw)
+                transactions.append(Transaction.deserialize(tx_slice))
+
+        return transactions
+
+    @_ensure_api_ready
+    async def _run_get_method(
+        self,
+        address: str,
+        method_name: str,
+        stack: t.Optional[t.List[t.Any]] = None,
+    ) -> t.List[t.Any]:
+        stack_codec = StackCodec(ClientType.TONAPI)
+        result = await self.api.blockchain_account_method(
+            address=address,
+            method_name=method_name,
+            args=stack_codec.encode(stack or []),
+        )
+        return stack_codec.decode(result.stack or [])
+
+    async def startup(self) -> None:
+        await self.api.ensure_session()
+
+    async def close(self) -> None:
+        await self.api.close()