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

tonutils/{protocols/contract.py → contracts/protocol.py}

@@ -4,7 +4,7 @@ import typing as t
 
 from pytoniq_core import Address, Cell, StateInit
 
-from tonutils.protocols.client import ClientProtocol
+from tonutils.clients.protocol import ClientProtocol
 from tonutils.types import AddressLike, ContractState, ContractStateInfo, WorkchainID
 
 if t.TYPE_CHECKING:
@@ -32,7 +32,7 @@ class ContractProtocol(t.Protocol[_D]):
         Implementations usually resolve compiled code from a global registry
         (e.g. CONTRACT_CODES) by using cls.VERSION as a key.
 
-        :return: Compiled contract code cell
+        :return: Compiled contract code cell.
         """
 
     @property
@@ -70,7 +70,7 @@ class ContractProtocol(t.Protocol[_D]):
         """
         Current contract balance in nanotons.
 
-        :return: Balance from the latest known state
+        :return: Balance from the latest known state.
         """
 
     @property
@@ -78,7 +78,7 @@ class ContractProtocol(t.Protocol[_D]):
         """
         Current lifecycle state of the contract.
 
-        :return: One of ContractState values
+        :return: One of ContractState values.
         """
 
     @property
@@ -86,7 +86,7 @@ class ContractProtocol(t.Protocol[_D]):
         """
         Check whether the contract is active.
 
-        :return: True if state is ACTIVE
+        :return: True if state is ACTIVE.
         """
 
     @property
@@ -94,7 +94,7 @@ class ContractProtocol(t.Protocol[_D]):
         """
         Check whether the contract is frozen.
 
-        :return: True if state is FROZEN
+        :return: True if state is FROZEN.
         """
 
     @property
@@ -102,7 +102,7 @@ class ContractProtocol(t.Protocol[_D]):
         """
         Check whether the contract is uninitialized.
 
-        :return: True if state is UNINIT
+        :return: True if state is UNINIT.
         """
 
     @property
@@ -110,7 +110,7 @@ class ContractProtocol(t.Protocol[_D]):
         """
         Check whether the contract does not exist on-chain.
 
-        :return: True if state is NONEXIST
+        :return: True if state is NONEXIST.
         """
 
     @property
@@ -118,7 +118,7 @@ class ContractProtocol(t.Protocol[_D]):
         """
         Logical time of the last known transaction for this contract.
 
-        :return: Transaction LT or None if unknown
+        :return: Transaction LT or None if unknown.
         """
 
     @property
@@ -126,7 +126,7 @@ class ContractProtocol(t.Protocol[_D]):
         """
         Hash of the last known transaction for this contract.
 
-        :return: Transaction hash as hex string or None if unknown
+        :return: Transaction hash as hex string or None if unknown.
         """
 
     @property
@@ -134,7 +134,7 @@ class ContractProtocol(t.Protocol[_D]):
         """
         Contract code cell from the latest known state.
 
-        :return: Code cell
+        :return: Code cell.
         """
 
     @property
@@ -142,7 +142,7 @@ class ContractProtocol(t.Protocol[_D]):
         """
         Contract data cell from the latest known state.
 
-        :return: Data cell
+        :return: Data cell.
         """
 
     async def refresh(self) -> None:
@@ -158,10 +158,10 @@ class ContractProtocol(t.Protocol[_D]):
         """
         Construct a contract wrapper from a StateInit object.
 
-        :param client: TON client to bind to the contract
-        :param state_init: StateInit containing code and data
-        :param workchain: Target workchain (default: BASECHAIN)
-        :return: New contract instance
+        :param client: TON client to bind to the contract.
+        :param state_init: StateInit containing code and data.
+        :param workchain: Target workchain (default: BASECHAIN).
+        :return: New contract instance.
         """
 
     @classmethod
@@ -178,11 +178,11 @@ class ContractProtocol(t.Protocol[_D]):
         Implementations usually compose a StateInit from code and data and then
         delegate to from_state_init().
 
-        :param client: TON client to bind to the contract
-        :param code: Contract code cell
-        :param data: Contract data cell
-        :param workchain: Target workchain (default: BASECHAIN)
-        :return: New contract instance
+        :param client: TON client to bind to the contract.
+        :param code: Contract code cell.
+        :param data: Contract data cell.
+        :param workchain: Target workchain (default: BASECHAIN).
+        :return: New contract instance.
         """
 
     @classmethod
@@ -198,10 +198,10 @@ class ContractProtocol(t.Protocol[_D]):
         Composes StateInit by combining default code with the provided data,
         then delegates to from_state_init().
 
-        :param client: TON client to bind to the contract
-        :param data: Typed data object conforming to _data_model
-        :param workchain: Target workchain (default: BASECHAIN)
-        :return: New contract instance
+        :param client: TON client to bind to the contract.
+        :param data: Typed data object conforming to _data_model.
+        :param workchain: Target workchain (default: BASECHAIN).
+        :return: New contract instance.
         """
 
     @classmethod
@@ -216,8 +216,8 @@ class ContractProtocol(t.Protocol[_D]):
 
         Optionally fetches and caches the current contract state from the blockchain.
 
-        :param client: TON client to bind to the contract
-        :param address: Address of the deployed contract
-        :param load_state: Whether to fetch current state from blockchain (default: True)
-        :return: Contract instance bound to the specified address
+        :param client: TON client to bind to the contract.
+        :param address: Address of the deployed contract.
+        :param load_state: Whether to fetch current state from blockchain (default: True).
+        :return: Contract instance bound to the specified address.
         """

tonutils/contracts/telegram/methods.py

@@ -2,8 +2,8 @@ import typing as t
 
 from pytoniq_core import 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/vanity/__init__.py

@@ -0,0 +1,17 @@
+from .models import (
+    VanityConfig,
+    VanityInit,
+    VanityResult,
+    VanitySpecial,
+)
+from .tlb import VanityDeployBody
+from .vanity import Vanity
+
+__all__ = [
+    "Vanity",
+    "VanityConfig",
+    "VanityDeployBody",
+    "VanityInit",
+    "VanityResult",
+    "VanitySpecial",
+]

tonutils/contracts/vanity/models.py

@@ -0,0 +1,39 @@
+import base64
+import typing as t
+
+from pydantic import BaseModel, Field
+from pytoniq_core import Cell
+
+
+class VanitySpecial(BaseModel):
+    tick: bool
+    tock: bool
+
+
+class VanityConfig(BaseModel):
+    owner: str
+    start: t.Optional[str] = None
+    end: t.Optional[str] = None
+    masterchain: bool
+    non_bounceable: bool
+    testnet: bool
+    case_sensitive: bool
+    only_one: bool
+
+
+class VanityInit(BaseModel):
+    code: str
+    split_depth: t.Optional[int] = Field(default=None, alias="fixedPrefixLength")
+    special: t.Optional[VanitySpecial] = None
+
+    @property
+    def code_cell(self) -> Cell:
+        raw = base64.urlsafe_b64decode(self.code)
+        return Cell.one_from_boc(raw)
+
+
+class VanityResult(BaseModel):
+    address: str
+    init: VanityInit
+    config: VanityConfig
+    timestamp: float

tonutils/contracts/vanity/tlb.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from pytoniq_core import Cell, Slice, TlbScheme, begin_cell
+
+
+class VanityDeployBody(TlbScheme):
+    """Message body structure for deploying contracts via Vanity."""
+
+    def __init__(self, code: Cell, data: Cell) -> None:
+        """
+        Initialize Vanity deploy message body.
+
+        :param code: Contract code cell to deploy
+        :param data: Contract initial data cell
+        """
+        self.code = code
+        self.data = data
+
+    def serialize(self) -> Cell:
+        """
+        Serialize deploy body to Cell.
+
+        Layout: code:^Cell data:^Cell
+
+        :return: Serialized message body cell
+        """
+        cell = begin_cell()
+        cell.store_ref(self.code)
+        cell.store_ref(self.data)
+        return cell.end_cell()
+
+    @classmethod
+    def deserialize(cls, cs: Slice) -> VanityDeployBody:
+        """
+        Deserialize deploy body from Cell slice.
+
+        :param cs: Cell slice to deserialize from
+        :return: Deserialized VanityDeployBody instance
+        """
+        raise NotImplementedError

tonutils/contracts/vanity/vanity.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from pytoniq_core import StateInit, Address
+from pytoniq_core.tlb.account import TickTock
+
+from tonutils.clients.protocol import ClientProtocol
+from tonutils.contracts.base import BaseContract
+from tonutils.contracts.vanity.models import VanityResult
+
+
+class Vanity(BaseContract):
+    """Vanity contract."""
+
+    @classmethod
+    def from_result(
+        cls,
+        client: ClientProtocol,
+        result: VanityResult,
+    ) -> Vanity:
+        """
+        Construct Vanity contract wrapper from generated result.
+
+        :param client: TON client to bind to the contract
+        :param result: Vanity generation result with address and init data
+        :return: Vanity contract instance
+        """
+        address = Address(result.address)
+        state_init = StateInit(code=result.init.code_cell)
+        if result.init.split_depth:
+            state_init.split_depth = result.init.split_depth
+        if result.init.special:
+            state_init.special = TickTock(
+                tick=result.init.special.tick,
+                tock=result.init.special.tock,
+            )
+        return cls(
+            client=client,
+            address=address,
+            state_init=state_init,
+        )

tonutils/contracts/wallet/__init__.py

@@ -44,6 +44,7 @@ from .params import (
     WalletV5BetaParams,
     WalletV5Params,
 )
+from .protocol import WalletProtocol
 from .tlb import (
     EncryptedTextCommentBody,
     OutActionSendMsg,
@@ -96,6 +97,7 @@ __all__ = [
     "WalletHighloadV3Data",
     "WalletHighloadV3Params",
     "WalletHighloadV3R1",
+    "WalletProtocol",
     "WalletPreprocessedV2",
     "WalletPreprocessedV2Config",
     "WalletPreprocessedV2Data",

tonutils/contracts/wallet/base.py

@@ -7,6 +7,7 @@ from pytoniq_core import Address, Cell, StateInit, WalletMessage, begin_cell
 from pytoniq_core.crypto.keys import mnemonic_new, mnemonic_to_private_key, words
 from pytoniq_core.crypto.signature import sign_message
 
+from tonutils.clients.protocol import ClientProtocol
 from tonutils.contracts.base import BaseContract
 from tonutils.contracts.codes import CONTRACT_CODES
 from tonutils.contracts.wallet.configs import BaseWalletConfig
@@ -16,10 +17,9 @@ from tonutils.contracts.wallet.messages import (
     TONTransferBuilder,
 )
 from tonutils.contracts.wallet.params import BaseWalletParams
+from tonutils.contracts.wallet.protocol import WalletProtocol
 from tonutils.contracts.wallet.tlb import BaseWalletData
 from tonutils.exceptions import ContractError
-from tonutils.protocols.client import ClientProtocol
-from tonutils.protocols.wallet import WalletProtocol
 from tonutils.types import (
     AddressLike,
     ContractStateInfo,
@@ -330,7 +330,7 @@ class BaseWallet(BaseContract, WalletProtocol[_D, _C, _P], abc.ABC):
         :param body: Optional message body (Cell or text comment)
         :param state_init: Optional StateInit for contract deployment
         :param send_mode: Message send mode (default: pay fees separately)
-        :param bounce: Whether message should bounce on error (default: auto)
+        :param bounce: Whether message should bounce on error
         :param params: Optional transaction parameters
         :return: Signed external message that was sent
         """

tonutils/contracts/wallet/messages.py

@@ -15,8 +15,8 @@ from pytoniq_core import (
 from tonutils.contracts.jetton.methods import get_wallet_address_get_method
 from tonutils.contracts.jetton.tlb import JettonTransferBody
 from tonutils.contracts.nft.tlb import NFTTransferBody
+from tonutils.contracts.wallet.protocol import WalletProtocol
 from tonutils.contracts.wallet.tlb import TextCommentBody
-from tonutils.protocols.wallet import WalletProtocol
 from tonutils.types import AddressLike, SendMode, DEFAULT_SENDMODE
 from tonutils.utils import (
     cell_to_hex,

tonutils/contracts/wallet/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, Binary, PublicKey
 
 

tonutils/{protocols/wallet.py → contracts/wallet/protocol.py}

@@ -4,8 +4,8 @@ import typing as t
 
 from pytoniq_core import Cell, StateInit, WalletMessage
 
-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,
     PublicKey,
@@ -71,11 +71,11 @@ class WalletProtocol(ContractProtocol, t.Protocol[_D, _C, _P]):
         """
         Create wallet instance from a private key.
 
-        :param client: TON client for blockchain interactions
-        :param private_key: Ed25519 PrivateKey instance
-        :param workchain: Target workchain (default: BASECHAIN)
-        :param config: Optional wallet configuration
-        :return: New wallet instance
+        :param client: TON client for blockchain interactions.
+        :param private_key: Ed25519 PrivateKey instance.
+        :param workchain: Target workchain (default: BASECHAIN).
+        :param config: Optional wallet configuration.
+        :return: New wallet instance.
         """
 
     @classmethod
@@ -90,12 +90,12 @@ class WalletProtocol(ContractProtocol, t.Protocol[_D, _C, _P]):
         """
         Create wallet instance from a mnemonic phrase.
 
-        :param client: TON client for blockchain interactions
-        :param mnemonic: BIP39 mnemonic phrase (list or space-separated string)
-        :param validate: Whether to validate mnemonic checksum (default: True)
-        :param workchain: Target workchain (default: BASECHAIN)
-        :param config: Optional wallet configuration
-        :return: Tuple of (wallet, public_key, private_key, mnemonic_list)
+        :param client: TON client for blockchain interactions.
+        :param mnemonic: BIP39 mnemonic phrase (list or space-separated string).
+        :param validate: Whether to validate mnemonic checksum (default: True).
+        :param workchain: Target workchain (default: BASECHAIN).
+        :param config: Optional wallet configuration.
+        :return: Tuple of (wallet, public_key, private_key, mnemonic_list).
         """
 
     @classmethod
@@ -109,11 +109,11 @@ class WalletProtocol(ContractProtocol, t.Protocol[_D, _C, _P]):
         """
         Create a new wallet with a randomly generated mnemonic.
 
-        :param client: TON client for blockchain interactions
-        :param mnemonic_length: Number of words in mnemonic (12, 18, or 24; default: 24)
-        :param workchain: Target workchain (default: BASECHAIN)
-        :param config: Optional wallet configuration
-        :return: Tuple of (wallet, public_key, private_key, mnemonic_list)
+        :param client: TON client for blockchain interactions.
+        :param mnemonic_length: Number of words in mnemonic (12, 18, or 24; default: 24).
+        :param workchain: Target workchain (default: BASECHAIN).
+        :param config: Optional wallet configuration.
+        :return: Tuple of (wallet, public_key, private_key, mnemonic_list).
         """
 
     async def build_external_message(
@@ -126,9 +126,9 @@ class WalletProtocol(ContractProtocol, t.Protocol[_D, _C, _P]):
 
         Constructs a signed external message but does not send it.
 
-        :param messages: List of internal messages or message builders
-        :param params: Optional transaction parameters (seqno, timeout, etc.)
-        :return: Signed external message ready for sending
+        :param messages: List of internal messages or message builders.
+        :param params: Optional transaction parameters (seqno, timeout, etc.).
+        :return: Signed external message ready for sending.
         """
 
     async def batch_transfer_message(
@@ -139,9 +139,9 @@ class WalletProtocol(ContractProtocol, t.Protocol[_D, _C, _P]):
         """
         Build and send a batch transfer message with multiple recipients.
 
-        :param messages: List of internal messages or message builders
-        :param params: Optional transaction parameters
-        :return: Signed external message that was sent
+        :param messages: List of internal messages or message builders.
+        :param params: Optional transaction parameters.
+        :return: Signed external message that was sent.
         """
 
     async def transfer_message(
@@ -152,9 +152,9 @@ class WalletProtocol(ContractProtocol, t.Protocol[_D, _C, _P]):
         """
         Build and send a transfer message for a single recipient.
 
-        :param message: Internal message or message builder
-        :param params: Optional transaction parameters
-        :return: Signed external message that was sent
+        :param message: Internal message or message builder.
+        :param params: Optional transaction parameters.
+        :return: Signed external message that was sent.
         """
 
     async def transfer(
@@ -170,12 +170,12 @@ class WalletProtocol(ContractProtocol, t.Protocol[_D, _C, _P]):
         """
         Build and send a transfer to a single destination.
 
-        :param destination: Recipient address (Address, string, or domain)
-        :param amount: Amount to send in nanotons
-        :param body: Optional message body (Cell or text comment)
-        :param state_init: Optional StateInit for contract deployment
-        :param send_mode: Message send mode (default: pay fees separately)
-        :param bounce: Whether message should bounce on error (default: auto)
-        :param params: Optional transaction parameters
-        :return: Signed external message that was sent
+        :param destination: Recipient address (Address, string, or domain).
+        :param amount: Amount to send in nanotons.
+        :param body: Optional message body (Cell or text comment).
+        :param state_init: Optional StateInit for contract deployment.
+        :param send_mode: Message send mode (default: pay fees separately).
+        :param bounce: Whether message should bounce on error.
+        :param params: Optional transaction parameters.
+        :return: Signed external message that was sent.
         """

tonutils/contracts/wallet/versions/v5.py

@@ -3,6 +3,7 @@ import typing as t
 
 from pytoniq_core import Cell, WalletMessage, begin_cell
 
+from tonutils.clients.protocol import ClientProtocol
 from tonutils.contracts.versions import ContractVersion
 from tonutils.contracts.wallet.base import BaseWallet
 from tonutils.contracts.wallet.configs import (
@@ -19,8 +20,7 @@ from tonutils.contracts.wallet.methods import (
 from tonutils.contracts.wallet.params import WalletV5BetaParams, WalletV5Params
 from tonutils.contracts.wallet.tlb import OutActionSendMsg, WalletV5SubwalletID
 from tonutils.contracts.wallet.tlb import WalletV5BetaData, WalletV5Data
-from tonutils.exceptions import NotRefreshedError
-from tonutils.protocols.client import ClientProtocol
+from tonutils.exceptions import StateNotLoadedError
 from tonutils.types import NetworkGlobalID, PrivateKey, WorkchainID
 from tonutils.utils import calc_valid_until
 
@@ -220,7 +220,7 @@ class WalletV5R1(
         :return: Typed wallet data
         """
         if not (self._state_info and self._state_info.data):
-            raise NotRefreshedError(self, "state_data")
+            raise StateNotLoadedError(self, missing="state_data")
 
         network_global_id = (
             NetworkGlobalID.TESTNET if self.client.network else NetworkGlobalID.MAINNET