tonutils 2.0.1b7__tar.gz → 2.0.1b8__tar.gz

{tonutils-2.0.1b7/tonutils.egg-info → tonutils-2.0.1b8}/PKG-INFO

@@ -1,13 +1,11 @@
 Metadata-Version: 2.4
 Name: tonutils
-Version: 2.0.1b7
+Version: 2.0.1b8
 Summary: Tonutils is a high-level, object-oriented Python library designed to facilitate seamless interactions with the TON blockchain.
 Author: nessshon
 Maintainer: nessshon
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/nessshon/tonutils/
-Project-URL: Documentation, https://nessshon.github.io/tonutils/
-Project-URL: Repository, https://github.com/nessshon/tonutils/
 Project-URL: Examples, https://github.com/nessshon/tonutils/tree/main/examples/
 Keywords: AsyncIO,TON,TON blockchain,The Open Network,blockchain,crypto,smart contracts
 Classifier: Development Status :: 4 - Beta

{tonutils-2.0.1b7 → tonutils-2.0.1b8}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=61"]
+requires = ["setuptools>=80"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -46,8 +46,6 @@ license = "MIT"
 
 [project.urls]
 Homepage = "https://github.com/nessshon/tonutils/"
-Documentation = "https://nessshon.github.io/tonutils/"
-Repository = "https://github.com/nessshon/tonutils/"
 Examples = "https://github.com/nessshon/tonutils/tree/main/examples/"
 
 [tool.setuptools.packages.find]
@@ -60,4 +58,4 @@ tonutils = ["py.typed"]
 tonutils = "tonutils.cli:main"
 
 [tool.setuptools.dynamic]
-version = { attr = "tonutils.__meta__.__version__" }
+version = { attr = "tonutils.__init__.__version__" }

tonutils-2.0.1b8/tonutils/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) 2024 Shon Ness
+#
+# This source code is licensed under the MIT License found in the
+# LICENSE file in the root directory of this source tree.
+
+__all__ = [
+    "__uri__",
+    "__version__",
+]
+
+__version__ = "2.0.1b8"
+__uri__ = "https://github.com/nessshon/tonutils"

{tonutils-2.0.1b7 → tonutils-2.0.1b8}/tonutils/cli.py

@@ -2,7 +2,7 @@ import argparse
 import asyncio
 import typing as t
 
-from tonutils.__meta__ import __version__
+from tonutils import __version__
 from tonutils.clients.adnl.provider.config import (
     get_mainnet_global_config,
     get_testnet_global_config,

tonutils-2.0.1b8/tonutils/clients/adnl/provider/config.py

@@ -0,0 +1,35 @@
+from pydantic import ValidationError
+
+from tonutils.clients.adnl.provider.models import GlobalConfig
+from tonutils.utils import load_json
+
+
+def load_global_config(source: str) -> GlobalConfig:
+    """
+    Fetch global configuration from source.
+
+    :return: Parsed GlobalConfig instance
+    """
+    try:
+        data = load_json(source)
+        return GlobalConfig.model_validate(data)
+    except ValidationError as e:
+        raise RuntimeError(f"Config validation failed: {e} ({source})") from e
+
+
+def get_mainnet_global_config() -> GlobalConfig:
+    """
+    Fetch mainnet global configuration.
+
+    :return: Parsed GlobalConfig instance
+    """
+    return load_global_config("https://ton.org/global-config.json")
+
+
+def get_testnet_global_config() -> GlobalConfig:
+    """
+    Fetch testnet global configuration.
+
+    :return: Parsed GlobalConfig instance
+    """
+    return load_global_config("https://ton.org/testnet-global-config.json")

{tonutils-2.0.1b7 → tonutils-2.0.1b8}/tonutils/contracts/__init__.py

@@ -127,6 +127,8 @@ from .vanity import (
 from .versions import ContractVersion
 from .wallet import (
     BaseMessageBuilder,
+    BaseWalletData,
+    BaseWalletParams,
     EncryptedTextCommentBody,
     ExternalMessage,
     InternalMessage,
@@ -194,6 +196,7 @@ __all__ = [
     "ALLOWED_DNS_ZONES",
     "BaseContract",
     "BaseMessageBuilder",
+    "BaseWalletData",
     "ChangeDNSRecordBody",
     "CONTRACT_CODES",
     "ContractProtocol",

{tonutils-2.0.1b7 → tonutils-2.0.1b8}/tonutils/contracts/telegram/tlb.py

@@ -296,7 +296,7 @@ class TeleItemContent(TlbScheme):
         """
         Initialize item content.
 
-        :param nft_content: Off-chain NFT metadata (image, description, etc)
+        :param nft_content: Off-chain NFT metadata (image, description, etc.)
         :param dns: DNS records for the username/domain
         :param token_info: Token name and domain information
         """

{tonutils-2.0.1b7 → tonutils-2.0.1b8}/tonutils/contracts/wallet/__init__.py

@@ -34,6 +34,7 @@ from .methods import (
     seqno_get_method,
 )
 from .params import (
+    BaseWalletParams,
     WalletHighloadV2Params,
     WalletHighloadV3Params,
     WalletPreprocessedV2Params,
@@ -46,6 +47,7 @@ from .params import (
 )
 from .protocol import WalletProtocol
 from .tlb import (
+    BaseWalletData,
     EncryptedTextCommentBody,
     OutActionSendMsg,
     TextCommentBody,
@@ -81,6 +83,8 @@ __all__ = [
     "VALID_MNEMONIC_LENGTHS",
     "BaseMessageBuilder",
     "BaseWallet",
+    "BaseWalletData",
+    "BaseWalletParams",
     "EncryptedTextCommentBody",
     "ExternalMessage",
     "InternalMessage",

{tonutils-2.0.1b7 → tonutils-2.0.1b8}/tonutils/contracts/wallet/tlb.py

@@ -203,7 +203,7 @@ class WalletV5SubwalletID:
         subwallet_number: int = 0,
         workchain: WorkchainID = WorkchainID.BASECHAIN,
         version: int = 0,
-        network_global_id: NetworkGlobalID = NetworkGlobalID.MAINNET,
+        network: NetworkGlobalID = NetworkGlobalID.MAINNET,
     ) -> None:
         """
         Initialize Wallet v5 subwallet ID.
@@ -211,19 +211,19 @@ class WalletV5SubwalletID:
         :param subwallet_number: Subwallet number (0-32767)
         :param workchain: Target workchain (default: BASECHAIN)
         :param version: Wallet version identifier (default: 0)
-        :param network_global_id: Network identifier (default: MAINNET)
+        :param network: Network identifier (default: MAINNET)
         """
         self.subwallet_number = subwallet_number
         self.workchain = workchain
         self.version = version
-        self.network_global_id = network_global_id
+        self.network = network
 
     def pack(self) -> int:
         """
         Pack subwallet ID components into 32-bit integer.
 
         Format: (1 << 31) | (workchain << 23) | (version << 15) | subwallet_number
-        XORed with network_global_id for network isolation.
+        XORed with network for network isolation.
 
         :return: Packed 32-bit subwallet ID
         """
@@ -232,22 +232,22 @@ class WalletV5SubwalletID:
         ctx |= (self.workchain & 0xFF) << 23
         ctx |= (self.version & 0xFF) << 15
         ctx |= self.subwallet_number & 0x7FFF
-        return ctx ^ (self.network_global_id & 0xFFFFFFFF)
+        return ctx ^ (self.network & 0xFFFFFFFF)
 
     @classmethod
     def unpack(
         cls,
         value: int,
-        network_global_id: NetworkGlobalID,
+        network: NetworkGlobalID,
     ) -> WalletV5SubwalletID:
         """
         Unpack 32-bit integer into subwallet ID components.
 
         :param value: Packed 32-bit subwallet ID
-        :param network_global_id: Network identifier for XOR decoding
+        :param network: Network identifier for XOR decoding
         :return: Unpacked WalletV5SubwalletID instance
         """
-        ctx = (value ^ network_global_id) & 0xFFFFFFFF
+        ctx = (value ^ network) & 0xFFFFFFFF
 
         subwallet_number = ctx & 0x7FFF
         version = (ctx >> 15) & 0xFF
@@ -258,7 +258,7 @@ class WalletV5SubwalletID:
             subwallet_number=subwallet_number,
             workchain=WorkchainID(workchain),
             version=version,
-            network_global_id=network_global_id,
+            network=network,
         )
 
     def __repr__(self) -> str:
@@ -298,7 +298,7 @@ class WalletV5BetaData(BaseWalletData):
 
         :param builder: Cell builder to store to
         """
-        builder.store_int(self.subwallet_id.network_global_id, 32)
+        builder.store_int(self.subwallet_id.network, 32)
         builder.store_int(self.subwallet_id.workchain, 8)
         builder.store_uint(self.subwallet_id.version, 8)
         builder.store_uint(self.subwallet_id.subwallet_number, 32)
@@ -328,7 +328,7 @@ class WalletV5BetaData(BaseWalletData):
         :return: Loaded WalletV5SubwalletID
         """
         return WalletV5SubwalletID(
-            network_global_id=NetworkGlobalID(cs.load_int(32)),
+            network=NetworkGlobalID(cs.load_int(32)),
             workchain=WorkchainID(cs.load_int(8)),
             version=cs.load_uint(8),
             subwallet_number=cs.load_uint(32),
@@ -398,20 +398,22 @@ class WalletV5Data(BaseWalletData):
         return cell.end_cell()
 
     @classmethod
-    def deserialize(cls, cs: Slice, network_global_id: NetworkGlobalID) -> WalletV5Data:
+    def deserialize(
+        cls,
+        cs: Slice,
+        network: NetworkGlobalID = NetworkGlobalID.MAINNET,
+    ) -> WalletV5Data:
         """
         Deserialize wallet data from Cell slice.
 
         :param cs: Cell slice to deserialize from
-        :param network_global_id: Network ID for unpacking subwallet_id
+        :param network: Network ID for unpacking subwallet_id
         :return: Deserialized WalletV5Data instance
         """
         return cls(
             is_signature_allowed=cs.load_bool(),
             seqno=cs.load_uint(32),
-            subwallet_id=WalletV5SubwalletID.unpack(
-                cs.load_uint(32), network_global_id
-            ),
+            subwallet_id=WalletV5SubwalletID.unpack(cs.load_uint(32), network),
             public_key=PublicKey(cs.load_bytes(32)),
             plugins=cs.load_maybe_ref(),
         )

{tonutils-2.0.1b7 → tonutils-2.0.1b8}/tonutils/contracts/wallet/versions/v5.py

@@ -63,7 +63,7 @@ class _WalletV5(
         cls._validate_config_type(config)
 
         if config.subwallet_id is None:
-            config.subwallet_id = WalletV5SubwalletID(network_global_id=client.network)
+            config.subwallet_id = WalletV5SubwalletID(network=client.network)
 
         return super().from_private_key(client, private_key, workchain, config)
 
@@ -163,7 +163,7 @@ class WalletV5Beta(
 
         cell = begin_cell()
         cell.store_uint(params.op_code, 32)
-        cell.store_int(subwallet_id.network_global_id, 32)
+        cell.store_int(subwallet_id.network, 32)
         cell.store_int(subwallet_id.workchain, 8)
         cell.store_uint(subwallet_id.version, 8)
         cell.store_uint(subwallet_id.subwallet_number, 32)
@@ -222,11 +222,11 @@ class WalletV5R1(
         if not (self._info and self._info.data):
             raise StateNotLoadedError(self, missing="state_data")
 
-        network_global_id = (
+        network = (
             NetworkGlobalID.TESTNET if self.client.network else NetworkGlobalID.MAINNET
         )
         cs = self._info.data.begin_parse()
-        return self._data_model.deserialize(cs, network_global_id)
+        return self._data_model.deserialize(cs, network)
 
     async def _build_msg_cell(
         self,

tonutils-2.0.1b8/tonutils/exceptions.py

@@ -0,0 +1,155 @@
+import asyncio
+import typing as t
+
+__all__ = [
+    "TonutilsError",
+    "TransportError",
+    "ProviderError",
+    "ClientError",
+    "ContractError",
+    "BalancerError",
+    "NotConnectedError",
+    "ProviderTimeoutError",
+    "ProviderResponseError",
+    "RetryLimitError",
+    "RunGetMethodError",
+    "StateNotLoadedError",
+    "CDN_CHALLENGE_MARKERS",
+]
+
+
+class TonutilsError(Exception):
+    """Base exception for tonutils."""
+
+
+class TransportError(TonutilsError):
+    """Transport-level failure (connect/handshake/send/recv)."""
+
+    def __init__(self, *, endpoint: str, operation: str, reason: str) -> None:
+        self.endpoint = endpoint
+        self.operation = operation
+        self.reason = reason
+        super().__init__(f"{operation} failed: {reason} ({endpoint})")
+
+
+class ProviderError(TonutilsError):
+    """Provider-level failure (protocol/parsing/backend/state)."""
+
+
+class ClientError(TonutilsError):
+    """Client misuse, validation errors, or unsupported operations."""
+
+
+class BalancerError(TonutilsError):
+    """Balancer failure (no alive backends, failover exhausted)."""
+
+
+class NotConnectedError(TonutilsError, RuntimeError):
+    """Raised when an operation requires an active connection."""
+
+    def __init__(
+        self,
+        *,
+        component: str = "client",
+        endpoint: t.Optional[str] = None,
+        operation: t.Optional[str] = None,
+    ) -> None:
+        self.component = component
+        self.endpoint = endpoint
+        self.operation = operation
+
+        op = f"cannot `{operation}`: " if operation else ""
+        where = f" ({endpoint})" if endpoint else ""
+        super().__init__(f"{op}{component} is not connected{where}")
+
+
+class ProviderTimeoutError(ProviderError, asyncio.TimeoutError):
+    """Provider operation exceeded its timeout."""
+
+    def __init__(self, *, timeout: float, endpoint: str, operation: str) -> None:
+        self.timeout = float(timeout)
+        self.endpoint = endpoint
+        self.operation = operation
+        super().__init__(f"{operation} timed out after {self.timeout}s ({endpoint})")
+
+
+class ProviderResponseError(ProviderError):
+    """Backend returned an error response."""
+
+    def __init__(self, *, code: int, message: str, endpoint: str) -> None:
+        self.code = int(code)
+        self.message = message
+        self.endpoint = endpoint
+        super().__init__(f"request failed: {self.code} {self.message} ({endpoint})")
+
+
+class RetryLimitError(ProviderError):
+    """Retry policy exhausted."""
+
+    def __init__(
+        self,
+        attempts: int,
+        max_attempts: int,
+        last_error: ProviderError,
+    ) -> None:
+        self.attempts = int(attempts)
+        self.max_attempts = int(max_attempts)
+        self.last_error = last_error
+        ratio = f"{self.attempts}/{self.max_attempts}"
+        super().__init__(f"retry limit reached {ratio}: {last_error}")
+
+
+class ContractError(ClientError):
+    """Contract wrapper operation failed."""
+
+    def __init__(self, target: t.Any, details: str) -> None:
+        self.target = target
+        self.details = details
+
+        if isinstance(target, type):
+            name = target.__name__
+        else:
+            name = target.__class__.__name__
+
+        super().__init__(f"{name} failed: {details}")
+
+
+class StateNotLoadedError(ContractError):
+    """Contract wrapper requires state that is not loaded."""
+
+    def __init__(self, contract: t.Any, *, missing: str) -> None:
+        self.missing = missing
+        name = contract.__class__.__name__
+        super().__init__(contract, f"{missing} is not loaded. Call {name}.refresh().")
+
+
+class RunGetMethodError(ClientError):
+    """Contract get-method returned a non-zero TVM exit code."""
+
+    def __init__(self, *, address: str, exit_code: int, method_name: str) -> None:
+        self.address = address
+        self.exit_code = int(exit_code)
+        self.method_name = method_name
+        super().__init__(
+            f"get-method `{method_name}` failed: exit code {self.exit_code} ({address})"
+        )
+
+
+CDN_CHALLENGE_MARKERS: t.Dict[str, str] = {
+    # Cloudflare
+    "cloudflare": "Cloudflare protection triggered or blocked the request.",
+    "cf-ray": "Cloudflare intermediate error (cf-ray header detected).",
+    "just a moment": "Cloudflare browser verification page.",
+    "checking your browser": "Cloudflare browser verification page.",
+    "attention required": "Cloudflare challenge page.",
+    "captcha": "Cloudflare CAPTCHA challenge.",
+    # Other CDNs / proxies
+    "akamai": "Akamai CDN blocked or intercepted the request.",
+    "fastly": "Fastly CDN error response detected.",
+    "varnish": "Varnish cache/CDN interference.",
+    "nginx": "Reverse proxy (nginx) error response.",
+    # Upstream failures
+    "502 bad gateway": "Bad gateway from upstream or proxy.",
+    "503 service unavailable": "Service temporarily unavailable (proxy or CDN).",
+    "ddos": "Possible DDoS protection or mitigation page.",
+}

{tonutils-2.0.1b7 → tonutils-2.0.1b8}/tonutils/types.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 import base64
+import re
 import typing as t
+from contextlib import suppress
 from dataclasses import dataclass
 from enum import Enum
 
@@ -280,22 +282,34 @@ class Binary:
         return self._size
 
     def _parse(self, value: t.Any) -> bytes:
-        """Parse input value into bytes."""
         if isinstance(value, bytes):
             return value
         if isinstance(value, int):
             length = max(1, (value.bit_length() + 7) // 8)
             return value.to_bytes(length, "big")
+
         if isinstance(value, str):
             s = value.strip()
+
+            # 0x... hex
             if s.lower().startswith("0x"):
-                return int(s, 16).to_bytes(self._size, "big")
-            try:
-                return base64.b64decode(s)
-            except (Exception,):
-                n = int(s, 10)
-                length = max(1, (n.bit_length() + 7) // 8)
-                return n.to_bytes(length, "big")
+                return bytes.fromhex(s[2:])
+
+            # plain hex (common case for publicKey)
+            if len(s) % 2 == 0 and re.compile(r"^[0-9a-fA-F]+$").fullmatch(s):
+                if len(s) == self._size * 2:
+                    return bytes.fromhex(s)
+
+            # base64 (strict)
+            with suppress(Exception):
+                b = base64.b64decode(s, validate=True)
+                return b
+
+            # decimal int as string fallback
+            n = int(s, 10)
+            length = max(1, (n.bit_length() + 7) // 8)
+            return n.to_bytes(length, "big")
+
         raise ValueError(f"Invalid binary type: {type(value).__name__}.")
 
     @property

{tonutils-2.0.1b7 → tonutils-2.0.1b8}/tonutils/utils.py

@@ -5,9 +5,13 @@ import binascii
 import decimal
 import hashlib
 import hmac
+import json
 import os
 import time
 import typing as t
+import urllib.request
+from pathlib import Path
+from urllib.error import HTTPError, URLError
 
 from Cryptodome.Cipher import AES
 from nacl.bindings import (
@@ -40,6 +44,7 @@ __all__ = [
     "cell_to_hex",
     "decode_dns_name",
     "encode_dns_name",
+    "load_json",
     "maybe_stack_addr",
     "norm_stack_cell",
     "norm_stack_num",
@@ -387,15 +392,15 @@ class TextCipher:
         if isinstance(payload, bytes):
             return payload[:32], payload[32:48], payload[48:]
         elif isinstance(payload, str):
+            # Try hex first; if that fails, try base64.
             try:
-                payload = bytes.fromhex(payload)
+                data = bytes.fromhex(payload)
             except ValueError:
-                pass
-            try:
-                payload = base64.b64decode(payload, validate=True)
-            except (binascii.Error, ValueError):
-                raise ValueError("Invalid payload encoding: not hex or base64.")
-            return payload[:32], payload[32:48], payload[48:]
+                try:
+                    data = base64.b64decode(payload, validate=True)
+                except (binascii.Error, ValueError):
+                    raise ValueError("Invalid payload encoding: not hex or base64.")
+            return data[:32], data[32:48], data[48:]
 
         cell = EncryptedTextCommentBody.deserialize(payload.begin_parse())
         return cell.pub_xor, cell.msg_key, cell.ciphertext
@@ -501,3 +506,38 @@ class TextCipher:
 
         comment = dec_data[padding_size:]
         return comment.decode()
+
+
+def load_json(source: str, timeout: float = 5.0) -> t.Any:
+    """
+    Load and parse JSON from a URL or a local file.
+
+    :param source: URL or file path
+    :param timeout: Network timeout in seconds
+    :return: Parsed JSON object
+    """
+    try:
+        if source.startswith(("http://", "https://")):
+            req = urllib.request.Request(
+                source,
+                method="GET",
+                headers={
+                    "User-Agent": "tonutils (+https://github.com/nessshon/tonutils)",
+                    "Accept": "application/json,text/plain,*/*",
+                },
+            )
+            with urllib.request.urlopen(req, timeout=timeout) as r:
+                return json.loads(r.read().decode("utf-8"))
+
+        return json.loads(Path(source).read_text(encoding="utf-8"))
+
+    except HTTPError as e:
+        raise RuntimeError(f"JSON fetch failed: {e} ({source})") from e
+    except URLError as e:
+        raise RuntimeError(f"JSON fetch failed: {e.reason} ({source})") from e
+    except json.JSONDecodeError as e:
+        raise RuntimeError(f"JSON is invalid: {e.msg} ({source})") from e
+    except OSError as e:
+        raise RuntimeError(f"JSON read failed: {e} ({source})") from e
+    except Exception as e:
+        raise RuntimeError(f"JSON load failed: {e} ({source})") from e

{tonutils-2.0.1b7 → tonutils-2.0.1b8/tonutils.egg-info}/PKG-INFO

@@ -1,13 +1,11 @@
 Metadata-Version: 2.4
 Name: tonutils
-Version: 2.0.1b7
+Version: 2.0.1b8
 Summary: Tonutils is a high-level, object-oriented Python library designed to facilitate seamless interactions with the TON blockchain.
 Author: nessshon
 Maintainer: nessshon
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/nessshon/tonutils/
-Project-URL: Documentation, https://nessshon.github.io/tonutils/
-Project-URL: Repository, https://github.com/nessshon/tonutils/
 Project-URL: Examples, https://github.com/nessshon/tonutils/tree/main/examples/
 Keywords: AsyncIO,TON,TON blockchain,The Open Network,blockchain,crypto,smart contracts
 Classifier: Development Status :: 4 - Beta

{tonutils-2.0.1b7 → tonutils-2.0.1b8}/tonutils.egg-info/SOURCES.txt

@@ -2,7 +2,6 @@ LICENSE
 README.md
 pyproject.toml
 tonutils/__init__.py
-tonutils/__meta__.py
 tonutils/cli.py
 tonutils/exceptions.py
 tonutils/py.typed
@@ -93,12 +92,6 @@ tonutils/contracts/wallet/versions/v2.py
 tonutils/contracts/wallet/versions/v3.py
 tonutils/contracts/wallet/versions/v4.py
 tonutils/contracts/wallet/versions/v5.py
-tonutils/tonconnect/__init__.py
-tonutils/tonconnect/events.py
-tonutils/tonconnect/storage.py
-tonutils/tonconnect/tonconnect.py
-tonutils/tonconnect/bridge/__init__.py
-tonutils/tonconnect/models/__init__.py
 tonutils/tools/__init__.py
 tonutils/tools/block_scanner/__init__.py
 tonutils/tools/block_scanner/events.py

tonutils-2.0.1b7/tonutils/__init__.py

@@ -1,17 +0,0 @@
-from . import (
-    clients,
-    contracts,
-    exceptions,
-    types,
-    utils,
-)
-from .__meta__ import __version__
-
-__all__ = [
-    "__version__",
-    "clients",
-    "contracts",
-    "exceptions",
-    "types",
-    "utils",
-]

tonutils-2.0.1b7/tonutils/__meta__.py

@@ -1 +0,0 @@
-__version__ = "2.0.1b7"