tonutils 0.5.2__tar.gz → 0.6.0a1__tar.gz

{tonutils-0.5.2 → tonutils-0.6.0a1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Ness
+Copyright (c) 2025 Ness
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{tonutils-0.5.2/tonutils.egg-info → tonutils-0.6.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tonutils
-Version: 0.5.2
+Version: 0.6.0a1
 Summary: Tonutils is a high-level, object-oriented Python library designed to facilitate seamless interactions with the TON blockchain.
 Home-page: https://github.com/nessshon/tonutils
 Author: nessshon
@@ -24,7 +24,7 @@ Classifier: Environment :: Console
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aiohttp<=3.12.2,>=3.7.0
+Requires-Dist: aiohttp>=3.7.0
 Requires-Dist: aiolimiter~=1.2.1
 Requires-Dist: cachetools~=5.5.0
 Requires-Dist: pycryptodomex~=3.20.0
@@ -46,7 +46,7 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# 📦 Tonutils
+# 📦 Tonutils [ALPHA]
 
 [![TON](https://img.shields.io/badge/TON-grey?logo=TON&logoColor=40AEF0)](https://ton.org)
 [![PyPI](https://img.shields.io/pypi/v/tonutils.svg?color=FFE873&labelColor=3776AB)](https://pypi.python.org/pypi/tonutils)
@@ -77,21 +77,16 @@ on top of the TON ecosystem.
 ## Installation
 
 ```bash
-pip install tonutils
+pip install --pre tonutils
 ```
 
 To use `pytoniq` with Native ADNL connection, install it with the optional dependencies, including
 the [pytoniq](https://github.com/yungwine/pytoniq) library:
 
 ```bash
-pip install 'tonutils[pytoniq]'
+pip install --pre 'tonutils[pytoniq]'
 ```
 
-## Documentation
-
-Find all guides and references here:  
-[nessshon.github.io/tonutils](https://nessshon.github.io/tonutils/)
-
 ## Contribution
 
 We welcome your contributions! If you have ideas for improvement or have identified a bug, please create an issue or

{tonutils-0.5.2 → tonutils-0.6.0a1}/README.md

@@ -1,4 +1,4 @@
-# 📦 Tonutils
+# 📦 Tonutils [ALPHA]
 
 [![TON](https://img.shields.io/badge/TON-grey?logo=TON&logoColor=40AEF0)](https://ton.org)
 [![PyPI](https://img.shields.io/pypi/v/tonutils.svg?color=FFE873&labelColor=3776AB)](https://pypi.python.org/pypi/tonutils)
@@ -29,21 +29,16 @@ on top of the TON ecosystem.
 ## Installation
 
 ```bash
-pip install tonutils
+pip install --pre tonutils
 ```
 
 To use `pytoniq` with Native ADNL connection, install it with the optional dependencies, including
 the [pytoniq](https://github.com/yungwine/pytoniq) library:
 
 ```bash
-pip install 'tonutils[pytoniq]'
+pip install --pre 'tonutils[pytoniq]'
 ```
 
-## Documentation
-
-Find all guides and references here:  
-[nessshon.github.io/tonutils](https://nessshon.github.io/tonutils/)
-
 ## Contribution
 
 We welcome your contributions! If you have ideas for improvement or have identified a bug, please create an issue or

{tonutils-0.5.2 → tonutils-0.6.0a1}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setuptools.setup(
     name="tonutils",
-    version="0.5.2",
+    version="0.6.0a1",
     author="nessshon",
     description=(
         "Tonutils is a high-level, object-oriented Python library "
@@ -24,7 +24,7 @@ setuptools.setup(
     package_data={"tonutils": ["py.typed"]},
     python_requires=">=3.10",
     install_requires=[
-        "aiohttp>=3.7.0,<=3.12.2",
+        "aiohttp>=3.7.0",
         "aiolimiter~=1.2.1",
         "cachetools~=5.5.0",
         "pycryptodomex~=3.20.0",

tonutils-0.6.0a1/tests/tests_clients.py

@@ -0,0 +1,94 @@
+from pytoniq_core import (
+    Address,
+    Cell,
+    StateInit,
+    Transaction,
+)
+
+from tests.helpers import ClientTestCase
+from tonutils.types import (
+    ClientType,
+    ContractStateInfo,
+    ContractState,
+    PublicKey,
+)
+
+WALLET_ADDRESS = Address(
+    "0:83ae019a23a8162beaa5cb0ebdc56668b2eac6c6ba51808812915b206a152dc5"
+)
+WALLET_PUBLIC_KEY = PublicKey(
+    55076642238194142798835029799378000396651553013470455265600214024586038843895
+)
+
+TX_LIMIT = 2
+TX_TO_LT = 60837801000002
+TX_PREV_HASH_HEX = "f86526829c6532063ec13d97231bf3579e9d1321124397766fb27eb76374a4ff"
+
+
+class TestTonapiClient(ClientTestCase):
+    CLIENT_TYPE = ClientType.LITESERVER
+    IS_TESTNET = False
+    RPS = 1
+
+    async def test_send_boc(self) -> None:
+        pass
+
+    async def test_get_blockchain_config(self) -> None:
+        result = await self.client.get_blockchain_config()
+        self.assertIsInstance(result, dict)
+
+    async def test_get_contract_info(self) -> None:
+        result = await self.client.get_contract_info(WALLET_ADDRESS)
+
+        self.assertIsNotNone(result.code_raw)
+        self.assertIsNotNone(result.data_raw)
+        self.assertGreater(result.balance, 0)
+        self.assertIsInstance(result, ContractStateInfo)
+        self.assertIs(result.state, ContractState.ACTIVE)
+        self.assertIsNotNone(result.last_transaction_lt)
+        self.assertIsNotNone(result.last_transaction_hash)
+
+        self.assertIsInstance(result.code, Cell)
+        self.assertIsInstance(result.data, Cell)
+        self.assertIsInstance(result.state_init, StateInit)
+
+    async def test_get_contract_transactions(self) -> None:
+        result = await self.client.get_contract_transactions(
+            address=WALLET_ADDRESS,
+            limit=TX_LIMIT,
+            to_lt=TX_TO_LT,
+        )
+        tx = result[0]
+        prev_tx_hash_hex = tx.prev_trans_hash.hex()
+
+        self.assertEqual(len(result), TX_LIMIT)
+        self.assertIsInstance(tx, Transaction)
+        self.assertEqual(prev_tx_hash_hex, TX_PREV_HASH_HEX)
+
+    async def test_run_get_method(self) -> None:
+        result = await self.client.run_get_method(
+            address=WALLET_ADDRESS,
+            method_name="seqno",
+        )
+        stack_item = result[0]
+
+        self.assertIsInstance(stack_item, int)
+        self.assertGreater(stack_item, 0)
+
+        result = await self.client.run_get_method(
+            address=WALLET_ADDRESS,
+            method_name="get_public_key",
+        )
+        stack_item = result[0]
+        public_key = PublicKey(stack_item)
+
+        self.assertIsInstance(stack_item, int)
+        self.assertEqual(public_key, WALLET_PUBLIC_KEY)
+
+
+class TestToncenterClient(TestTonapiClient):
+    CLIENT_TYPE = ClientType.TONCENTER
+
+
+class TestLiteserverClient(TestTonapiClient):
+    CLIENT_TYPE = ClientType.LITESERVER

tonutils-0.6.0a1/tests/tests_utils.py

@@ -0,0 +1,230 @@
+import typing as t
+from decimal import Decimal
+from unittest import TestCase
+
+from pytoniq_core import (
+    Address,
+    Cell,
+    Slice,
+    begin_cell,
+)
+
+from tonutils.types import ClientType, PrivateKey, WorkchainID, NetworkGlobalID
+from tonutils.utils import (
+    StackCodec,
+    TextCipher,
+    cell_to_b64,
+    cell_to_hex,
+    cell_hash,
+    normalize_hash,
+    slice_hash,
+    string_hash,
+    to_cell,
+    WalletV5SubwalletID,
+    to_amount,
+    to_nano,
+)
+
+CELL_HEX = "b5ee9c7201010101002a0000500168747470733a2f2f6e66742e667261676d656e742e636f6d2f757365726e616d65732e6a736f6e"
+CELL_B64 = "te6ccgEBAQEAKgAAUAFodHRwczovL25mdC5mcmFnbWVudC5jb20vdXNlcm5hbWVzLmpzb24="
+CELL_BYTES = bytes.fromhex(CELL_HEX)
+CELL_SLICE = Slice.one_from_boc(CELL_HEX)
+CELL = CELL_SLICE.to_cell()
+
+MESSAGE_HEX = "b5ee9c7201020d0100028a0003b578379ed1da34943d4d870c33d42263e3cf790affc450cdaf282a4bcc7cea49a9100003754e7847c41d99e0513ab5e320b789f43e493b10315a5f4d3c41f6974022ef4436a22889fdb0000371d09faa34168ac719d00054666febc80102030201e004050082724b09a7b09203b73b83d9293c7108e409d30009cf16f9daaf5a6ebe950cc40dd841477adbde3012580ca1d75367f579bf10907c2df711e13df7cb3ee31ce730bb02130cc08af24619313984400b0c0098880106f3da3b469287a9b0e1867a844c7c79ef215ff88a19b5e50549798f9d4935220108a3816c0055233e112c745f28b689a6a1828da440416ea18060079ce88643bf9225f5bd2468ac719a0201dd0607010120080101200900b7480106f3da3b469287a9b0e1867a844c7c79ef215ff88a19b5e50549798f9d493523001548cf844b1d17ca2da269a860a36910105ba8601801e73a2190efe4897d6f490d312d000608235a00006ea9cf08f884d158e33a1702448d4001b3480106f3da3b469287a9b0e1867a844c7c79ef215ff88a19b5e50549798f9d4935230020eb806688ea058afaa972c3af71599a2cbab1b1ae94602204a456c81a854b715409502f9000060c245c00006ea9cf08f886d158e33ac00a0062000000005468616e6b7320666f7220746f6e7574696c732066726f6d2063726f6e212028efbfa3e296bdefbfa329e3838e009d430d63138800000000000000001f4000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020006fc9879ae04c1447940000000000040000000000051d0eb6386a84e2d8f909cc22fb5eae3909f490962ea348759614866cecd0dc6640d03954"
+NORMALIZED_HASH = "ab49f1d3293243946f8e81f0169524003302688218d718fedbc99dd90163853b"
+
+STRING_HASH_TEXT = "nessshon"
+STRING_HASH = (
+    45354304031421179242460489368440335494304328265643744596791119159788447170008
+)
+
+CELL_HASH_TEXT = "wallet"
+CELL_HASH_CELL = begin_cell().store_snake_string(CELL_HASH_TEXT).end_cell()
+CELL_HASH = (
+    115698008076457823118597424358900481870087387390627058654421588318795409511780
+)
+
+DECRYPTED_PAYLOAD = "Hello from tonutils!"
+SENDER_ADDRESS = Address("UQD_nC7tFgl5S_WvW6LJHRqX-smNCeDYIfYBxbD0tcHnbjxC")
+SENDER_PRIVKEY = PrivateKey("9A4xl6qjn4PrbN0yIPQXAqVi634g78b2MyzJ6psmVak=")
+RECIPIENT_PRIVKEY = PrivateKey("C3tEgYARTXnF+NPD7ufnn7LepZd4+kKigowVFH2kSHk=")
+RECIPIENT_PUBKEY = RECIPIENT_PRIVKEY.public_key
+
+STACK_PALOAD = [-1, CELL, Cell.one_from_boc("b5ee9c7201010101000300000120")]
+STACK_RESPONSE = [-1, CELL, None]
+
+STACK_PAYLOADS = {
+    ClientType.TONAPI: [
+        -1,
+        "te6ccgEBAQEAKgAAUAFodHRwczovL25mdC5mcmFnbWVudC5jb20vdXNlcm5hbWVzLmpzb24=",
+        "te6ccgEBAQEAAwAAASA=",
+    ],
+    ClientType.TONCENTER: [
+        ["num", "-0x1"],
+        [
+            "tvm.Cell",
+            "te6ccgEBAQEAKgAAUAFodHRwczovL25mdC5mcmFnbWVudC5jb20vdXNlcm5hbWVzLmpzb24=",
+        ],
+        ["tvm.Cell", "te6ccgEBAQEAAwAAASA="],
+    ],
+    ClientType.LITESERVER: STACK_PALOAD,
+}
+STACK_RESPONSES: t.Dict[ClientType, t.List[t.Any]] = {
+    ClientType.TONAPI: [
+        {"type": "num", "num": "-0x1"},
+        {
+            "type": "cell",
+            "cell": "b5ee9c7201010101002a0000500168747470733a2f2f6e66742e667261676d656e742e636f6d2f757365726e616d65732e6a736f6e",
+        },
+        {"type": "cell", "cell": "b5ee9c7201010101000300000120"},
+    ],
+    ClientType.TONCENTER: [
+        ["num", "-0x1"],
+        [
+            "cell",
+            {
+                "bytes": "te6cckEBAQEAKgAAUAFodHRwczovL25mdC5mcmFnbWVudC5jb20vdXNlcm5hbWVzLmpzb24K7MvY"
+            },
+        ],
+        ["cell", {"bytes": "te6cckEBAQEAAwAAASCUQYZV"}],
+    ],
+    ClientType.LITESERVER: STACK_RESPONSE,
+}
+
+
+class TestUtils(TestCase):
+
+    def tests_converters(self) -> None:
+        cells = [
+            to_cell(CELL),
+            to_cell(CELL_HEX),
+            to_cell(CELL_B64),
+            to_cell(CELL_BYTES),
+            to_cell(CELL_SLICE),
+        ]
+        self.assertTrue(all(isinstance(x, Cell) for x in cells))
+
+        self.assertEqual(cell_to_hex(CELL), CELL_HEX)
+        self.assertEqual(cell_to_hex(CELL_HEX), CELL_HEX)
+        self.assertEqual(cell_to_hex(CELL_B64), CELL_HEX)
+        self.assertEqual(cell_to_hex(CELL_BYTES), CELL_HEX)
+        self.assertEqual(cell_to_hex(CELL_SLICE), CELL_HEX)
+
+        self.assertEqual(cell_to_b64(to_cell(CELL)), CELL_B64)
+        self.assertEqual(cell_to_b64(to_cell(CELL_HEX)), CELL_B64)
+        self.assertEqual(cell_to_b64(to_cell(CELL_B64)), CELL_B64)
+        self.assertEqual(cell_to_b64(to_cell(CELL_BYTES)), CELL_B64)
+        self.assertEqual(cell_to_b64(to_cell(CELL_SLICE)), CELL_B64)
+
+        self.assertEqual(cell_hash(CELL_HASH_CELL), CELL_HASH)
+        self.assertEqual(string_hash(STRING_HASH_TEXT), STRING_HASH)
+        self.assertEqual(slice_hash(CELL_HASH_CELL.to_slice()), CELL_HASH)
+
+        self.assertEqual(normalize_hash(MESSAGE_HEX), NORMALIZED_HASH)
+
+    def tests_text_cipher(self) -> None:
+        encrypted = TextCipher.encrypt(
+            payload=DECRYPTED_PAYLOAD,
+            sender_address=SENDER_ADDRESS,
+            our_private_key=SENDER_PRIVKEY,
+            their_public_key=RECIPIENT_PUBKEY,
+        )
+        self.assertIsInstance(encrypted, Cell)
+
+        decrypted = TextCipher.decrypt(
+            payload=encrypted,
+            sender_address=SENDER_ADDRESS,
+            our_public_key=RECIPIENT_PUBKEY,
+            our_private_key=RECIPIENT_PRIVKEY,
+        )
+        self.assertEqual(decrypted, DECRYPTED_PAYLOAD)
+
+    def _tests_stack_codec(self, client_type: ClientType) -> None:
+        codec = StackCodec(client_type)
+
+        encoded_payload = codec.encode(STACK_PALOAD)
+        expected_encoded_payload = STACK_PAYLOADS[client_type]
+        self.assertEqual(encoded_payload, expected_encoded_payload)
+
+        decoded_response = codec.decode(STACK_RESPONSES[client_type])
+        expected_decoded_response = STACK_RESPONSE
+        self.assertEqual(decoded_response, expected_decoded_response)
+
+    def tests_stack_codec_tonapi(self) -> None:
+        self._tests_stack_codec(ClientType.TONAPI)
+
+    def tests_stack_codec_toncenter(self) -> None:
+        self._tests_stack_codec(ClientType.TONCENTER)
+
+    def tests_stack_codec_liteserver(self) -> None:
+        self._tests_stack_codec(ClientType.LITESERVER)
+
+    def tests_value_utils(self) -> None:
+        decimals = 9
+        self.assertEqual(to_nano("1", decimals), 1_000_000_000)
+        self.assertEqual(to_nano("0.000000001", decimals), 1)
+        self.assertEqual(to_nano(Decimal("1.234567891"), decimals), 1_234_567_891)
+
+        self.assertEqual(to_nano("1.2345678919", decimals), 1_234_567_891)
+        self.assertEqual(to_nano("0.9999999999", decimals), 999_999_999)
+
+        self.assertEqual(to_nano(1.2, 1), 12)
+        self.assertEqual(to_nano(7, 0), 7)
+        self.assertEqual(to_nano("42", 0), 42)
+        self.assertEqual(
+            to_amount(1_234_567_891, decimals, precision=4),
+            Decimal("1.2345"),
+        )
+        self.assertEqual(
+            to_amount(9_999, 4, precision=2),
+            Decimal("0.99"),
+        )
+        self.assertEqual(to_amount(0, decimals), Decimal(0))
+
+        with self.assertRaises(ValueError):
+            to_amount(-1, decimals)
+        with self.assertRaises(ValueError):
+            to_amount(2 ** 256, decimals)
+        with self.assertRaises(ValueError):
+            to_amount(1, -1)
+
+        for s in ["1.234567891", "0.000000001", "123456789.987654321"]:
+            src = Decimal(s)
+            nano = to_nano(src, decimals)
+            back = to_amount(nano, decimals)
+            self.assertLessEqual(back, src)
+            self.assertLess(src - back, Decimal(f"1e-{decimals}"))
+
+    def tests_wallet_v5_id(self) -> None:
+        subwallet_id = WalletV5SubwalletID(
+            subwallet_number=0,
+            workchain=WorkchainID.BASECHAIN,
+            version=0,
+            network_global_id=NetworkGlobalID.MAINNET,
+        )
+        self.assertEqual(subwallet_id.pack(), 2147483409)
+
+        subwallet_id = WalletV5SubwalletID(
+            subwallet_number=0,
+            workchain=WorkchainID.MASTERCHAIN,
+            version=0,
+            network_global_id=NetworkGlobalID.MAINNET,
+        )
+        self.assertEqual(subwallet_id.pack(), 8388369)
+
+        subwallet_id = WalletV5SubwalletID(
+            subwallet_number=0,
+            workchain=WorkchainID.BASECHAIN,
+            version=0,
+            network_global_id=NetworkGlobalID.TESTNET,
+        )
+        self.assertEqual(subwallet_id.pack(), 2147483645)
+
+        subwallet_id = WalletV5SubwalletID(
+            subwallet_number=0,
+            workchain=WorkchainID.MASTERCHAIN,
+            version=0,
+            network_global_id=NetworkGlobalID.TESTNET,
+        )
+        self.assertEqual(subwallet_id.pack(), 8388605)

{tonutils-0.5.2/tonutils/client → tonutils-0.6.0a1/tonutils/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-0.6.0a1/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-0.6.0a1/tonutils/clients/liteserver/__init__.py

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