tonflow 0.1.0__py3-none-any.whl

tonflow/__init__.py

@@ -0,0 +1,63 @@
+"""TON blockchain parsing and local indexing toolkit."""
+
+from tonflow.addresses import (
+    is_raw_address,
+    is_user_friendly_address,
+    normalize_address,
+    validate_address,
+)
+from tonflow.cache import InMemoryCache, JSONCache, SQLiteCache
+from tonflow.client import TonClient
+from tonflow.export import (
+    jetton_transfers_to_csv,
+    jetton_transfers_to_json,
+    transactions_to_csv,
+    transactions_to_json,
+)
+from tonflow.jettons import (
+    decode_jetton_transfer,
+    extract_jetton_transfers,
+    is_jetton_burn,
+    is_jetton_transfer,
+    is_jetton_transfer_notification,
+    normalize_amount,
+)
+from tonflow.models import (
+    JettonTransfer,
+    Message,
+    MessageDirection,
+    RawPayload,
+    TonflowModel,
+    Transaction,
+    TransactionStatus,
+)
+from tonflow.stream import watch_address
+
+__all__ = [
+    "InMemoryCache",
+    "JSONCache",
+    "JettonTransfer",
+    "Message",
+    "MessageDirection",
+    "RawPayload",
+    "TonClient",
+    "TonflowModel",
+    "Transaction",
+    "TransactionStatus",
+    "SQLiteCache",
+    "decode_jetton_transfer",
+    "extract_jetton_transfers",
+    "is_jetton_burn",
+    "is_jetton_transfer",
+    "is_jetton_transfer_notification",
+    "normalize_amount",
+    "watch_address",
+    "jetton_transfers_to_csv",
+    "jetton_transfers_to_json",
+    "transactions_to_csv",
+    "transactions_to_json",
+    "is_raw_address",
+    "is_user_friendly_address",
+    "normalize_address",
+    "validate_address",
+]

tonflow/addresses.py

@@ -0,0 +1,70 @@
+"""Address helpers for TON account identifiers."""
+
+from __future__ import annotations
+
+import base64
+import re
+
+# User-friendly address: 48 base64url chars, first byte encodes workchain + flags.
+# EQ = bounceable mainnet (workchain 0)
+# UQ = non-bounceable mainnet (workchain 0)
+# kQ = bounceable testnet (workchain 0)
+# 0Q = non-bounceable testnet (workchain 0)
+_USER_FRIENDLY_PREFIXES = ("EQ", "UQ", "kQ", "0Q")
+_USER_FRIENDLY_LENGTH = 48
+_USER_FRIENDLY_RE = re.compile(r"^[A-Za-z0-9_\-]{48}$")
+
+# Raw address: "<workchain>:<64 hex chars>"
+_RAW_RE = re.compile(r"^-?[0-9]+:[0-9a-fA-F]{64}$")
+
+
+def normalize_address(address: str) -> str:
+    """Return the trimmed TON address, raising ValueError if blank."""
+    normalized = address.strip()
+    if not normalized:
+        raise ValueError("TON address cannot be empty.")
+    return normalized
+
+
+def is_user_friendly_address(address: str) -> bool:
+    """Return True if *address* looks like a valid TON user-friendly address.
+
+    Checks:
+    - length is exactly 48 characters
+    - characters are valid base64url (A-Z, a-z, 0-9, ``-``, ``_``)
+    - starts with a known workchain prefix (EQ, UQ, kQ, 0Q)
+    - base64-decoded payload is exactly 36 bytes (tag + workchain + hash + crc)
+    """
+    addr = address.strip()
+    if len(addr) != _USER_FRIENDLY_LENGTH:
+        return False
+    if not addr.startswith(_USER_FRIENDLY_PREFIXES):
+        return False
+    if not _USER_FRIENDLY_RE.match(addr):
+        return False
+    try:
+        decoded = base64.urlsafe_b64decode(addr + "==")
+    except Exception:
+        return False
+    return len(decoded) == 36
+
+
+def is_raw_address(address: str) -> bool:
+    """Return True if *address* is a TON raw address (``workchain:hex``)."""
+    return bool(_RAW_RE.match(address.strip()))
+
+
+def validate_address(address: str) -> str:
+    """Return the trimmed address if it is a recognized TON format.
+
+    Raises:
+        ValueError: if the address is neither user-friendly nor raw.
+    """
+    addr = normalize_address(address)
+    if is_user_friendly_address(addr) or is_raw_address(addr):
+        return addr
+    raise ValueError(
+        f"'{addr}' is not a valid TON address. "
+        "Expected a 48-char user-friendly address (EQ/UQ/kQ/0Q...) "
+        "or a raw address (workchain:64hexchars)."
+    )

tonflow/cache.py

@@ -0,0 +1,120 @@
+"""Small cache primitives used by clients and streams."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+from time import monotonic, time
+from typing import Protocol, TypeVar
+
+from tonflow.models import RawPayload
+
+T = TypeVar("T")
+
+
+class JSONCache(Protocol):
+    """Cache backend interface for JSON-compatible API responses."""
+
+    def get(self, key: str) -> RawPayload | None:
+        """Return a cached JSON payload or None when it is missing/expired."""
+
+    def set(self, key: str, value: RawPayload, ttl_seconds: float | None = None) -> None:
+        """Store a JSON payload with an optional TTL."""
+
+    def clear(self) -> None:
+        """Remove all cached values."""
+
+
+@dataclass(slots=True)
+class _CacheEntry[T]:
+    value: T
+    expires_at: float | None
+
+
+class InMemoryCache:
+    """Simple TTL cache for tests, examples, and short-lived scripts."""
+
+    def __init__(self) -> None:
+        self._items: dict[str, _CacheEntry[object]] = {}
+
+    def get[T](self, key: str) -> T | None:
+        entry = self._items.get(key)
+        if entry is None:
+            return None
+        if entry.expires_at is not None and entry.expires_at <= monotonic():
+            self._items.pop(key, None)
+            return None
+        return entry.value  # type: ignore[return-value]
+
+    def set(self, key: str, value: object, ttl_seconds: float | None = None) -> None:
+        expires_at = None if ttl_seconds is None else monotonic() + ttl_seconds
+        self._items[key] = _CacheEntry(value=value, expires_at=expires_at)
+
+    def clear(self) -> None:
+        self._items.clear()
+
+
+class SQLiteCache:
+    """SQLite-backed TTL cache for local scripts and small services."""
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._initialize()
+
+    def get(self, key: str) -> RawPayload | None:
+        now = time()
+        with self._connect() as connection:
+            row = connection.execute(
+                "SELECT value, expires_at FROM cache_entries WHERE key = ?",
+                (key,),
+            ).fetchone()
+            if row is None:
+                return None
+
+            value, expires_at = row
+            if expires_at is not None and expires_at <= now:
+                connection.execute("DELETE FROM cache_entries WHERE key = ?", (key,))
+                return None
+
+        data = json.loads(value)
+        if not isinstance(data, dict):
+            msg = "Cached payload must be a JSON object."
+            raise ValueError(msg)
+        return data
+
+    def set(self, key: str, value: RawPayload, ttl_seconds: float | None = None) -> None:
+        expires_at = None if ttl_seconds is None else time() + ttl_seconds
+        encoded = json.dumps(value, sort_keys=True, separators=(",", ":"))
+        with self._connect() as connection:
+            connection.execute(
+                """
+                INSERT INTO cache_entries (key, value, expires_at)
+                VALUES (?, ?, ?)
+                ON CONFLICT(key) DO UPDATE SET
+                    value = excluded.value,
+                    expires_at = excluded.expires_at
+                """,
+                (key, encoded, expires_at),
+            )
+
+    def clear(self) -> None:
+        with self._connect() as connection:
+            connection.execute("DELETE FROM cache_entries")
+
+    def _initialize(self) -> None:
+        with self._connect() as connection:
+            connection.execute(
+                """
+                CREATE TABLE IF NOT EXISTS cache_entries (
+                    key TEXT PRIMARY KEY,
+                    value TEXT NOT NULL,
+                    expires_at REAL
+                )
+                """
+            )
+
+    def _connect(self) -> sqlite3.Connection:
+        return sqlite3.connect(self.path)

tonflow/client.py

@@ -0,0 +1,328 @@
+"""Client entry points for reading TON blockchain data."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+
+from tonflow.addresses import normalize_address
+from tonflow.cache import JSONCache
+from tonflow.exceptions import TonflowAPIError, TonflowDecodeError
+from tonflow.jettons import decode_jetton_transfer
+from tonflow.models import (
+    JettonTransfer,
+    Message,
+    MessageDirection,
+    RawPayload,
+    Transaction,
+    TransactionStatus,
+)
+
+
+@dataclass(slots=True)
+class TonClient:
+    """High-level async TON API client."""
+
+    endpoint: str
+    api_key: str | None = None
+    timeout: float = 10.0
+    http_client: httpx.AsyncClient | None = None
+    cache: JSONCache | None = None
+    cache_ttl_seconds: float | None = 30.0
+    _owns_http_client: bool = field(default=False, init=False, repr=False)
+
+    async def __aenter__(self) -> TonClient:
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the owned HTTP client, if tonflow created one."""
+
+        if self.http_client is not None and self._owns_http_client:
+            await self.http_client.aclose()
+            self.http_client = None
+            self._owns_http_client = False
+
+    async def get_transactions(
+        self,
+        address: str,
+        *,
+        limit: int = 20,
+        before_lt: int | None = None,
+    ) -> list[Transaction]:
+        """Fetch and normalize account transactions."""
+
+        normalized = normalize_address(address)
+        if limit <= 0:
+            msg = "limit must be greater than zero."
+            raise ValueError(msg)
+        if before_lt is not None and before_lt < 0:
+            msg = "before_lt must be greater than or equal to zero."
+            raise ValueError(msg)
+
+        payload = await self._request_json(
+            "GET",
+            f"/v2/blockchain/accounts/{normalized}/transactions",
+            params={"limit": limit, "before_lt": before_lt},
+        )
+        transactions = _extract_transactions(payload)
+        return [_parse_transaction(item, account=normalized) for item in transactions]
+
+    async def get_jetton_transfers(
+        self,
+        address: str,
+        *,
+        limit: int = 20,
+        before_lt: int | None = None,
+        decimals: int = 9,
+        jetton_minter: str | None = None,
+        symbol: str | None = None,
+    ) -> list[JettonTransfer]:
+        """Fetch transactions for *address* and return only Jetton transfer events.
+
+        Internally calls :meth:`get_transactions` and filters messages whose
+        op_code matches a TEP-74 Jetton transfer or transfer_notification.
+
+        Args:
+            address: TON account address to query.
+            limit: Maximum number of transactions to scan (not transfers).
+            before_lt: Return transactions with logical time below this value.
+            decimals: Token decimal places used for amount normalization.
+            jetton_minter: Optional minter contract address to attach to results.
+            symbol: Optional token symbol to attach to results.
+
+        Returns:
+            List of :class:`~tonflow.models.JettonTransfer` in the order they
+            appear across the fetched transactions (newest transaction first,
+            matching the API order).
+        """
+        transactions = await self.get_transactions(address, limit=limit, before_lt=before_lt)
+
+        transfers: list[JettonTransfer] = []
+        for tx in transactions:
+            messages: list[Message] = []
+            if tx.in_message is not None:
+                messages.append(tx.in_message)
+            messages.extend(tx.out_messages)
+
+            for msg in messages:
+                result = decode_jetton_transfer(
+                    tx,
+                    msg,
+                    decimals=decimals,
+                    jetton_minter=jetton_minter,
+                    symbol=symbol,
+                )
+                if result is not None:
+                    transfers.append(result)
+
+        return transfers
+
+    async def _request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, int | None] | None = None,
+    ) -> RawPayload:
+        clean_params = {key: value for key, value in (params or {}).items() if value is not None}
+        cache_key = _cache_key(method, path, clean_params)
+        if self.cache is not None and method.upper() == "GET":
+            cached = self.cache.get(cache_key)
+            if cached is not None:
+                return cached
+
+        client = self._get_http_client()
+
+        try:
+            response = await client.request(method, path, params=clean_params)
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise TonflowAPIError(
+                f"TON API request failed with status {exc.response.status_code}.",
+                status_code=exc.response.status_code,
+                url=str(exc.request.url),
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise TonflowAPIError(f"TON API request failed: {exc}") from exc
+
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise TonflowDecodeError("TON API response is not valid JSON.") from exc
+
+        if not isinstance(data, dict):
+            raise TonflowDecodeError("TON API response must be a JSON object.")
+
+        if self.cache is not None and method.upper() == "GET":
+            self.cache.set(cache_key, data, ttl_seconds=self.cache_ttl_seconds)
+        return data
+
+    def _get_http_client(self) -> httpx.AsyncClient:
+        if self.http_client is not None:
+            return self.http_client
+
+        headers = {"Accept": "application/json"}
+        if self.api_key is not None:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        self.http_client = httpx.AsyncClient(
+            base_url=self.endpoint.rstrip("/"),
+            headers=headers,
+            timeout=self.timeout,
+        )
+        self._owns_http_client = True
+        return self.http_client
+
+
+def _cache_key(method: str, path: str, params: dict[str, int]) -> str:
+    query = urlencode(sorted(params.items()))
+    if query:
+        return f"{method.upper()} {path}?{query}"
+    return f"{method.upper()} {path}"
+
+
+def _extract_transactions(payload: RawPayload) -> list[RawPayload]:
+    raw_transactions: Any = payload.get("transactions", payload.get("items"))
+    if raw_transactions is None:
+        raw_transactions = payload.get("result", [])
+    if not isinstance(raw_transactions, list):
+        raise TonflowDecodeError("TON API transactions field must be a list.")
+
+    transactions: list[RawPayload] = []
+    for item in raw_transactions:
+        if not isinstance(item, dict):
+            raise TonflowDecodeError("TON API transaction item must be an object.")
+        transactions.append(item)
+    return transactions
+
+
+def _parse_transaction(raw: RawPayload, *, account: str) -> Transaction:
+    transaction_hash = _required_str(raw, "hash")
+    logical_time = _required_int(raw, "lt", fallback_keys=("logical_time",))
+
+    return Transaction(
+        hash=transaction_hash,
+        account=account,
+        lt=logical_time,
+        timestamp=_optional_int(raw, "now", fallback_keys=("timestamp", "utime")),
+        status=_parse_status(raw),
+        in_message=_parse_message(
+            raw.get("in_msg") or raw.get("in_message"), MessageDirection.INBOUND
+        ),
+        out_messages=tuple(
+            _parse_required_message(item, MessageDirection.OUTBOUND)
+            for item in _raw_message_list(raw.get("out_msgs") or raw.get("out_messages"))
+        ),
+        total_fees=_optional_int(raw, "total_fees", fallback_keys=("fee",)),
+        raw=raw,
+    )
+
+
+def _parse_message(raw: object, direction: MessageDirection) -> Message | None:
+    if raw is None:
+        return None
+    if not isinstance(raw, dict):
+        raise TonflowDecodeError("TON API message must be an object.")
+
+    return Message(
+        source=_optional_str(raw, "source", fallback_keys=("src",)),
+        destination=_optional_str(raw, "destination", fallback_keys=("dst",)),
+        direction=direction,
+        value=_optional_int(raw, "value", fallback_keys=("amount",)),
+        body=_optional_body(raw),
+        op_code=_optional_int(raw, "op_code", fallback_keys=("opcode",)),
+        raw=raw,
+    )
+
+
+def _parse_required_message(raw: object, direction: MessageDirection) -> Message:
+    message = _parse_message(raw, direction)
+    if message is None:
+        raise TonflowDecodeError("TON API message cannot be null in this field.")
+    return message
+
+
+def _raw_message_list(raw: object) -> list[object]:
+    if raw is None:
+        return []
+    if not isinstance(raw, list):
+        raise TonflowDecodeError("TON API out messages field must be a list.")
+    return raw
+
+
+def _parse_status(raw: RawPayload) -> TransactionStatus:
+    if raw.get("success") is True:
+        return TransactionStatus.SUCCESS
+    if raw.get("success") is False:
+        return TransactionStatus.FAILED
+
+    status = _optional_str(raw, "status")
+    if status in {TransactionStatus.SUCCESS, "ok"}:
+        return TransactionStatus.SUCCESS
+    if status in {TransactionStatus.FAILED, "error"}:
+        return TransactionStatus.FAILED
+    return TransactionStatus.UNKNOWN
+
+
+def _optional_body(raw: RawPayload) -> str | None:
+    body = _optional_str(raw, "body")
+    if body is not None:
+        return body
+
+    decoded_body = raw.get("decoded_body")
+    if isinstance(decoded_body, dict):
+        text = decoded_body.get("text") or decoded_body.get("comment")
+        if isinstance(text, str):
+            return text
+    return None
+
+
+def _required_str(raw: RawPayload, key: str, *, fallback_keys: tuple[str, ...] = ()) -> str:
+    value = _optional_str(raw, key, fallback_keys=fallback_keys)
+    if value is None:
+        raise TonflowDecodeError(f"TON API transaction is missing required field '{key}'.")
+    return value
+
+
+def _optional_str(raw: RawPayload, key: str, *, fallback_keys: tuple[str, ...] = ()) -> str | None:
+    value = _first_value(raw, key, fallback_keys)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise TonflowDecodeError(f"TON API field '{key}' must be a string.")
+    return value
+
+
+def _required_int(raw: RawPayload, key: str, *, fallback_keys: tuple[str, ...] = ()) -> int:
+    value = _optional_int(raw, key, fallback_keys=fallback_keys)
+    if value is None:
+        raise TonflowDecodeError(f"TON API transaction is missing required field '{key}'.")
+    return value
+
+
+def _optional_int(raw: RawPayload, key: str, *, fallback_keys: tuple[str, ...] = ()) -> int | None:
+    value = _first_value(raw, key, fallback_keys)
+    if value is None:
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    if isinstance(value, str) and value.isdecimal():
+        return int(value)
+    raise TonflowDecodeError(f"TON API field '{key}' must be an integer.")
+
+
+def _first_value(raw: RawPayload, key: str, fallback_keys: tuple[str, ...]) -> object:
+    if key in raw:
+        return raw[key]
+    for fallback_key in fallback_keys:
+        if fallback_key in raw:
+            return raw[fallback_key]
+    return None

tonflow/exceptions.py

@@ -0,0 +1,26 @@
+"""Custom exceptions raised by tonflow."""
+
+from __future__ import annotations
+
+
+class TonflowError(Exception):
+    """Base error for tonflow."""
+
+
+class TonflowAPIError(TonflowError):
+    """Raised when an upstream TON API request fails."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        url: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.url = url
+
+
+class TonflowDecodeError(TonflowError):
+    """Raised when blockchain payload decoding fails."""

tonflow/export.py

@@ -0,0 +1,101 @@
+"""Helpers for exporting tonflow models to JSON and CSV."""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+from decimal import Decimal
+from typing import Any
+
+from tonflow.models import JettonTransfer, Transaction
+
+
+def _default(obj: object) -> Any:
+    if isinstance(obj, Decimal):
+        return str(obj)
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+def transactions_to_json(transactions: list[Transaction], *, indent: int | None = None) -> str:
+    """Serialize a list of transactions to a JSON string.
+
+    Decimal values are serialized as strings to preserve precision.
+    """
+    data = [tx.model_dump(mode="json") for tx in transactions]
+    return json.dumps(data, default=_default, indent=indent, ensure_ascii=False)
+
+
+def jetton_transfers_to_json(transfers: list[JettonTransfer], *, indent: int | None = None) -> str:
+    """Serialize a list of Jetton transfers to a JSON string."""
+    data = [t.model_dump(mode="json") for t in transfers]
+    return json.dumps(data, default=_default, indent=indent, ensure_ascii=False)
+
+
+# CSV column ordering for each model type
+_TRANSACTION_FIELDS = [
+    "hash",
+    "account",
+    "logical_time",
+    "timestamp",
+    "status",
+    "total_fees",
+]
+
+_JETTON_TRANSFER_FIELDS = [
+    "transaction_hash",
+    "sender",
+    "recipient",
+    "amount",
+    "raw_amount",
+    "decimals",
+    "symbol",
+    "jetton_wallet",
+    "jetton_minter",
+    "comment",
+]
+
+
+def transactions_to_csv(transactions: list[Transaction]) -> str:
+    """Serialize a list of transactions to a CSV string.
+
+    Includes the core scalar fields; nested messages and raw payload are omitted.
+    """
+    output = io.StringIO()
+    writer = csv.DictWriter(output, fieldnames=_TRANSACTION_FIELDS, extrasaction="ignore")
+    writer.writeheader()
+    for tx in transactions:
+        writer.writerow(
+            {
+                "hash": tx.hash,
+                "account": tx.account,
+                "logical_time": tx.logical_time,
+                "timestamp": tx.timestamp,
+                "status": tx.status,
+                "total_fees": tx.total_fees,
+            }
+        )
+    return output.getvalue()
+
+
+def jetton_transfers_to_csv(transfers: list[JettonTransfer]) -> str:
+    """Serialize a list of Jetton transfers to a CSV string."""
+    output = io.StringIO()
+    writer = csv.DictWriter(output, fieldnames=_JETTON_TRANSFER_FIELDS, extrasaction="ignore")
+    writer.writeheader()
+    for t in transfers:
+        writer.writerow(
+            {
+                "transaction_hash": t.transaction_hash,
+                "sender": t.sender,
+                "recipient": t.recipient,
+                "amount": str(t.amount),
+                "raw_amount": t.raw_amount,
+                "decimals": t.decimals,
+                "symbol": t.symbol,
+                "jetton_wallet": t.jetton_wallet,
+                "jetton_minter": t.jetton_minter,
+                "comment": t.comment,
+            }
+        )
+    return output.getvalue()

tonflow/jettons.py

@@ -0,0 +1,126 @@
+"""Jetton event normalization helpers."""
+
+from decimal import Decimal
+
+from tonflow.models import JettonTransfer, Message, Transaction
+
+# TEP-74 Jetton standard op codes
+OP_JETTON_TRANSFER = 0xF8A7EA5
+OP_JETTON_TRANSFER_NOTIFICATION = 0x7362D09C
+OP_JETTON_INTERNAL_TRANSFER = 0x178D4519
+OP_JETTON_BURN = 0x595F07BC
+
+
+def normalize_amount(raw_amount: int | str, decimals: int) -> Decimal:
+    """Convert a raw Jetton amount into a human-readable decimal value."""
+    amount = Decimal(str(raw_amount))
+    scale = Decimal(10) ** decimals
+    return amount / scale
+
+
+def is_jetton_transfer(message: Message) -> bool:
+    """Return True if the message op_code matches a Jetton transfer."""
+    return message.op_code == OP_JETTON_TRANSFER
+
+
+def is_jetton_transfer_notification(message: Message) -> bool:
+    """Return True if op_code matches a Jetton transfer notification."""
+    return message.op_code == OP_JETTON_TRANSFER_NOTIFICATION
+
+
+def is_jetton_burn(message: Message) -> bool:
+    """Return True if op_code matches a Jetton burn."""
+    return message.op_code == OP_JETTON_BURN
+
+
+def decode_jetton_transfer(
+    transaction: Transaction,
+    message: Message,
+    *,
+    decimals: int = 9,
+    jetton_minter: str | None = None,
+    symbol: str | None = None,
+) -> JettonTransfer | None:
+    """Parse a Jetton transfer from a transaction message.
+
+    Returns a JettonTransfer if the message is a recognized Jetton transfer,
+    otherwise returns None.
+
+    Supports both TEP-74 transfer (op 0xf8a7ea5) and transfer_notification
+    (op 0x7362d09c). The raw payload is expected to carry the token amount
+    under the key ``"amount"`` and optionally ``"comment"`` / ``"forward_payload"``.
+    """
+    if message.op_code not in (OP_JETTON_TRANSFER, OP_JETTON_TRANSFER_NOTIFICATION):
+        return None
+
+    raw = message.raw
+
+    # Amount may come from the message value or an explicit ``amount`` field in
+    # the decoded payload (TonAPI style).
+    raw_amount_value = raw.get("amount") or raw.get("jetton_amount")
+    if raw_amount_value is None:
+        raw_amount_value = message.value or 0
+
+    try:
+        raw_amount = int(raw_amount_value)
+    except (TypeError, ValueError):
+        raw_amount = 0
+
+    # Sender/recipient depend on message direction:
+    # - transfer (0xf8a7ea5): sender = message.source (Jetton wallet owner)
+    # - transfer_notification (0x7362d09c): recipient is the destination contract
+    sender = raw.get("sender") or message.source
+    recipient = raw.get("recipient") or raw.get("destination") or message.destination
+
+    comment: str | None = None
+    forward = raw.get("forward_payload") or raw.get("comment")
+    if isinstance(forward, str) and forward:
+        comment = forward
+
+    return JettonTransfer(
+        transaction_hash=transaction.hash,
+        sender=sender,
+        recipient=recipient,
+        amount=normalize_amount(raw_amount, decimals),
+        raw_amount=raw_amount,
+        decimals=decimals,
+        jetton_wallet=(
+            message.destination if message.op_code == OP_JETTON_TRANSFER else message.source
+        ),
+        jetton_minter=jetton_minter,
+        symbol=symbol,
+        comment=comment,
+        raw=dict(raw),
+    )
+
+
+def extract_jetton_transfers(
+    transaction: Transaction,
+    *,
+    decimals: int = 9,
+    jetton_minter: str | None = None,
+    symbol: str | None = None,
+) -> list[JettonTransfer]:
+    """Extract all Jetton transfers from a transaction's messages.
+
+    Scans both the inbound message and all outbound messages.
+    """
+    transfers: list[JettonTransfer] = []
+
+    messages: list[Message] = []
+    if transaction.in_message is not None:
+        messages.append(transaction.in_message)
+    messages.extend(transaction.out_messages)
+
+    for msg in messages:
+        result = decode_jetton_transfer(
+            transaction,
+            msg,
+            decimals=decimals,
+            jetton_minter=jetton_minter,
+            symbol=symbol,
+        )
+        if result is not None:
+            transfers.append(result)
+
+    return transfers

tonflow/models.py

@@ -0,0 +1,82 @@
+"""Core data models returned by tonflow."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+RawPayload = dict[str, Any]
+
+
+class TonflowModel(BaseModel):
+    """Base model with stable serialization defaults."""
+
+    model_config = ConfigDict(frozen=True, populate_by_name=True)
+
+
+class MessageDirection(StrEnum):
+    """Direction of a message relative to the indexed account."""
+
+    INBOUND = "inbound"
+    OUTBOUND = "outbound"
+
+
+class TransactionStatus(StrEnum):
+    """Normalized transaction execution status."""
+
+    SUCCESS = "success"
+    FAILED = "failed"
+    UNKNOWN = "unknown"
+
+
+class Message(TonflowModel):
+    """Normalized TON message."""
+
+    source: str | None
+    destination: str | None
+    direction: MessageDirection | None = None
+    value: int | None = Field(default=None, ge=0)
+    body: str | None = None
+    op_code: int | None = Field(default=None, ge=0)
+    raw: RawPayload = Field(default_factory=dict)
+
+
+class Transaction(TonflowModel):
+    """Normalized TON transaction."""
+
+    hash: str
+    account: str
+    logical_time: int = Field(alias="lt", ge=0)
+    timestamp: int | None = Field(default=None, ge=0)
+    status: TransactionStatus = TransactionStatus.UNKNOWN
+    in_message: Message | None = None
+    out_messages: tuple[Message, ...] = ()
+    total_fees: int | None = Field(default=None, ge=0)
+    raw: RawPayload = Field(default_factory=dict)
+
+
+class JettonTransfer(TonflowModel):
+    """Normalized Jetton transfer event."""
+
+    transaction_hash: str
+    sender: str | None
+    recipient: str | None
+    amount: Decimal = Field(ge=0)
+    raw_amount: int = Field(ge=0)
+    decimals: int = Field(ge=0, le=255)
+    jetton_wallet: str | None = None
+    jetton_minter: str | None = None
+    symbol: str | None = None
+    comment: str | None = None
+    raw: RawPayload = Field(default_factory=dict)
+
+    @field_validator("symbol")
+    @classmethod
+    def normalize_symbol(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = value.strip()
+        return normalized or None

tonflow/stream.py

@@ -0,0 +1,75 @@
+"""Polling-based streaming of new TON transactions."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+
+from tonflow.client import TonClient
+from tonflow.models import Transaction
+
+
+async def watch_address(
+    client: TonClient,
+    address: str,
+    *,
+    interval_seconds: float = 5.0,
+    lookback: int = 10,
+) -> AsyncIterator[Transaction]:
+    """Yield new transactions for *address* as they appear on-chain.
+
+    Polls ``client.get_transactions()`` every *interval_seconds* seconds.
+    On the first call fetches the last *lookback* transactions to establish
+    a baseline; subsequent polls only yield transactions with a logical time
+    greater than the highest seen so far, so duplicates are never emitted.
+
+    ``watch_address`` runs indefinitely. To stop it after a fixed duration or
+    on an external signal, wrap it with :func:`asyncio.timeout` or cancel the
+    enclosing task:
+
+    .. code-block:: python
+
+        import asyncio
+        from tonflow import TonClient, watch_address
+
+        async def main() -> None:
+            async with TonClient(endpoint="https://tonapi.io") as client:
+                # Stop automatically after 60 seconds
+                async with asyncio.timeout(60):
+                    async for tx in watch_address(client, "EQ..."):
+                        print(tx.hash)
+
+    Args:
+        client: A configured :class:`TonClient` instance.
+        address: The TON address to watch.
+        interval_seconds: Seconds to wait between polls.
+        lookback: Number of recent transactions to fetch on the first poll
+            (used to seed the last-seen logical time without yielding old txs).
+
+    Yields:
+        :class:`Transaction` objects in ascending logical-time order.
+    """
+    last_lt: int | None = None
+
+    # Seed: fetch recent transactions to set the baseline lt without yielding them.
+    seed = await client.get_transactions(address, limit=lookback)
+    if seed:
+        last_lt = max(tx.logical_time for tx in seed)
+
+    while True:
+        await asyncio.sleep(interval_seconds)
+
+        txs = await client.get_transactions(address, limit=lookback)
+        if not txs:
+            continue
+
+        new_txs = [tx for tx in txs if last_lt is None or tx.logical_time > last_lt]
+        if not new_txs:
+            continue
+
+        # Yield in ascending order (oldest first).
+        new_txs.sort(key=lambda tx: tx.logical_time)
+        for tx in new_txs:
+            yield tx
+
+        last_lt = max(tx.logical_time for tx in new_txs)

tonflow-0.1.0.dist-info/METADATA

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: tonflow
+Version: 0.1.0
+Summary: Python toolkit for reading, decoding, normalizing, and locally caching TON blockchain data.
+Project-URL: Homepage, https://github.com/kakharov/tonflow
+Project-URL: Repository, https://github.com/kakharov/tonflow
+Project-URL: Issues, https://github.com/kakharov/tonflow/issues
+Author-email: kakharov <kaharov95@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: blockchain,indexing,jetton,ton,web3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tonflow
+
+[![CI](https://github.com/kakharov/tonflow/actions/workflows/ci.yml/badge.svg)](https://github.com/kakharov/tonflow/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/kakharov/tonflow/branch/main/graph/badge.svg)](https://codecov.io/gh/kakharov/tonflow)
+[![PyPI](https://img.shields.io/pypi/v/tonflow)](https://pypi.org/project/tonflow/)
+[![Python](https://img.shields.io/pypi/pyversions/tonflow)](https://pypi.org/project/tonflow/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Python toolkit for reading, decoding, normalizing, and locally caching TON blockchain data.
+
+`tonflow` is a lightweight MIT-licensed library. It does not run a hosted indexer and does not store blockchain data on your behalf — any cache lives on your own machine or infrastructure.
+
+## Install
+
+```bash
+pip install tonflow
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+```python
+import asyncio
+from tonflow import TonClient
+
+async def main() -> None:
+    async with TonClient(endpoint="https://tonapi.io") as client:
+        txs = await client.get_transactions("EQ...", limit=10)
+        for tx in txs:
+            print(tx.hash, tx.logical_time, tx.status)
+
+asyncio.run(main())
+```
+
+## Recipes
+
+### Get Jetton transfers
+
+```python
+transfers = await client.get_jetton_transfers(
+    "EQ...",
+    limit=20,
+    decimals=6,
+    symbol="USDT",
+)
+for t in transfers:
+    print(t.sender, "→", t.recipient, t.amount, t.symbol)
+```
+
+### Stream new transactions in real time
+
+```python
+from tonflow import watch_address
+
+async for tx in watch_address(client, "EQ...", interval_seconds=5):
+    print("new tx:", tx.hash, tx.logical_time)
+```
+
+`watch_address` runs indefinitely. To stop it after a fixed duration, wrap it
+with `asyncio.timeout` (Python 3.11+):
+
+```python
+import asyncio
+from tonflow import TonClient, watch_address
+
+async def main() -> None:
+    async with TonClient(endpoint="https://tonapi.io") as client:
+        async with asyncio.timeout(60):  # stop after 60 seconds
+            async for tx in watch_address(client, "EQ..."):
+                print(tx.hash)
+```
+
+### Cache responses locally (avoid hammering public nodes)
+
+```python
+from tonflow import SQLiteCache, TonClient
+
+client = TonClient(
+    endpoint="https://tonapi.io",
+    cache=SQLiteCache(".tonflow/cache.sqlite3"),
+    cache_ttl_seconds=60,
+)
+```
+
+### Export to CSV or JSON
+
+```python
+from tonflow import jetton_transfers_to_csv, transactions_to_json
+
+json_str = transactions_to_json(txs, indent=2)
+csv_str  = jetton_transfers_to_csv(transfers)
+
+with open("transfers.csv", "w") as f:
+    f.write(csv_str)
+```
+
+### Validate a TON address
+
+```python
+from tonflow import validate_address, is_user_friendly_address, is_raw_address
+
+validate_address("EQ...")        # raises ValueError if invalid
+is_user_friendly_address("EQ...") # True / False
+is_raw_address("0:abcd...")        # True / False
+```
+
+## API reference
+
+### `TonClient`
+
+```python
+TonClient(
+    endpoint: str,
+    api_key: str | None = None,
+    timeout: float = 10.0,
+    cache: JSONCache | None = None,
+    cache_ttl_seconds: float | None = 30.0,
+)
+```
+
+| Method | Description |
+|---|---|
+| `get_transactions(address, limit, before_lt)` | Fetch and normalize account transactions |
+| `get_jetton_transfers(address, limit, before_lt, decimals, jetton_minter, symbol)` | Fetch transactions and return only Jetton transfer events |
+| `aclose()` | Close the underlying HTTP client |
+
+Use as an async context manager (`async with`) for automatic cleanup.
+
+### `watch_address`
+
+```python
+watch_address(
+    client: TonClient,
+    address: str,
+    interval_seconds: float = 5.0,
+    lookback: int = 10,
+) -> AsyncIterator[Transaction]
+```
+
+Polls every `interval_seconds`. Seeds a baseline on the first call so existing transactions are not replayed. Yields new transactions in ascending logical-time order.
+
+> **Note:** `watch_address` runs indefinitely. Use `asyncio.timeout()` or task cancellation to stop it.
+
+### Models
+
+| Model | Key fields |
+|---|---|
+| `Transaction` | `hash`, `account`, `logical_time`, `timestamp`, `status`, `in_message`, `out_messages`, `total_fees` |
+| `Message` | `source`, `destination`, `direction`, `value`, `body`, `op_code` |
+| `JettonTransfer` | `transaction_hash`, `sender`, `recipient`, `amount`, `raw_amount`, `decimals`, `symbol`, `jetton_wallet`, `jetton_minter`, `comment` |
+
+### Cache backends
+
+| Class | Storage | Best for |
+|---|---|---|
+| `InMemoryCache` | In-process dict | Tests, short-lived scripts |
+| `SQLiteCache(path)` | SQLite file on disk | Local scripts, small services |
+
+Both implement the `JSONCache` protocol — you can write your own backend (e.g. Redis) by implementing `get`, `set`, and `clear`.
+
+### Export helpers
+
+| Function | Output |
+|---|---|
+| `transactions_to_json(txs, indent=None)` | JSON string |
+| `transactions_to_csv(txs)` | CSV string |
+| `jetton_transfers_to_json(transfers, indent=None)` | JSON string |
+| `jetton_transfers_to_csv(transfers)` | CSV string |
+
+`Decimal` amounts are serialized as strings in both formats to preserve precision.
+
+### Address helpers
+
+| Function | Description |
+|---|---|
+| `normalize_address(addr)` | Strip whitespace, raise on empty |
+| `is_user_friendly_address(addr)` | Validate EQ/UQ/kQ/0Q 48-char format |
+| `is_raw_address(addr)` | Validate `workchain:64hexchars` format |
+| `validate_address(addr)` | Accept either format, raise `ValueError` on invalid |
+
+### Exceptions
+
+| Exception | Raised when |
+|---|---|
+| `TonflowAPIError` | HTTP error from upstream TON API |
+| `TonflowDecodeError` | API response cannot be parsed into expected models |
+
+## Examples
+
+See the [`examples/`](examples/) directory:
+
+- [`get_transactions.py`](examples/get_transactions.py) — fetch and print recent transactions
+- [`get_jetton_transfers.py`](examples/get_jetton_transfers.py) — fetch and print Jetton transfers
+- [`watch_address.py`](examples/watch_address.py) — stream new transactions in real time
+- [`export_to_csv.py`](examples/export_to_csv.py) — save transactions and transfers to CSV
+- [`cache_with_sqlite.py`](examples/cache_with_sqlite.py) — local SQLite cache in action
+
+## Development
+
+```powershell
+git clone https://github.com/kakharov/tonflow
+cd tonflow
+py -3.12 -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+pytest
+```
+
+Lint and type check:
+
+```bash
+ruff check .
+ruff format .
+mypy src/
+```
+
+## Roadmap
+
+### `0.1.0` — current
+- [x] `TonClient` with `get_transactions()` and `get_jetton_transfers()`
+- [x] TEP-74 Jetton transfer decoder
+- [x] `SQLiteCache` and `InMemoryCache` with TTL
+- [x] `watch_address()` polling stream
+- [x] Address validation (user-friendly and raw formats)
+- [x] JSON and CSV export helpers
+
+### `0.2.0` — planned
+
+**TonCenter adapter**
+
+TON ecosystem has multiple API providers with different trade-offs:
+
+| Provider | Cost | Reliability | Notes |
+|---|---|---|---|
+| TonAPI | Paid | High | More endpoints, better rate limits |
+| TonCenter | Free | Medium | Can drop transactions under load |
+| Lite Server | Free | Highest | Direct node connection, complex setup |
+
+`0.2.0` adds a pluggable provider system so you can switch between TonAPI and TonCenter without changing your code.
+
+**`send_and_confirm()`**
+
+TON is fully asynchronous — sending a transaction does not mean it was executed. Unlike Ethereum, there is no immediate transaction hash to track. Transactions can silently disappear from the mempool due to:
+
+- `valid_until` TTL expiry (transaction not included in a block in time)
+- TonCenter queue drops under high load
+- `seqno` race conditions when sending in parallel
+
+`send_and_confirm()` solves this by:
+
+1. Sending the transaction via any configured provider
+2. Polling every few seconds until the transaction appears on-chain
+3. Automatically retrying with a fresh `seqno` if `valid_until` has passed and the transaction is gone
+4. Returning only after the transaction is confirmed in a block
+
+```python
+result = await client.send_and_confirm(
+    wallet=wallet,
+    messages=[...],
+    timeout=60,
+)
+print(result.hash, result.logical_time)
+```
+
+**Full `0.2.0` scope**
+
+- [ ] TonCenter adapter (pluggable provider interface)
+- [ ] `send_and_confirm()` with polling, TTL tracking and automatic retry
+- [ ] Websocket stream support (TonAPI / TonCenter)
+- [ ] Jetton burn and mint event decoding
+- [ ] Redis cache adapter
+
+### `0.3.0` — planned
+- [ ] NFT transfer event decoding
+- [ ] CLI: `tonflow scan <address>`
+- [ ] Postgres export helper
+- [ ] Backfill utility for historical data
+
+## License
+
+MIT

tonflow-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+tonflow/__init__.py,sha256=UD1Jj3Iiv3XiK8KMW4HmzclG26PC_U5Z7lIkWF0KPmY,1470
+tonflow/addresses.py,sha256=Rn43EgijoTc1-tg38H57fcRfYd-LFijTUVuh9t8OZaY,2301
+tonflow/cache.py,sha256=KmEfV7jYK2hEWw8T5Yy28MdNrbtVNK1_lvb2owGavhA,3898
+tonflow/client.py,sha256=3xbq8Sc1OeHmKbvjJXVOW9u4OWtf7MJntk7LBr7v5p0,11481
+tonflow/exceptions.py,sha256=clPpD2IB_agvtDr0bKy0DXeLNho6EyDztDS9cmTvTS8,590
+tonflow/export.py,sha256=tt7_ETIQ9mYwiEFQ3A6lo8_Nu36SXH4UHTef-h8w9-8,3024
+tonflow/jettons.py,sha256=Yaf6r3AVL5lKsWBc4zw9VsoP1qoHo091_Ssw4qeVGLY,4051
+tonflow/models.py,sha256=WtO7bJvMauH5W7Kdez_IKDSkjUssR7e7ypfSlAxNhLQ,2198
+tonflow/stream.py,sha256=sVaZQPe3qrMBxZxpyhrsNa7ZYsNMfd9ImChlHyDkSVA,2545
+tonflow-0.1.0.dist-info/METADATA,sha256=C_lW1JRvMpRM5ad_rmVwIn-KZMgfPo-kLSoz1oZQPZ4,9715
+tonflow-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tonflow-0.1.0.dist-info/licenses/LICENSE,sha256=YblrJ3l-bZ36jPQrFh3z_ldlBI3BaFdtHPYFYL0iJM8,1065
+tonflow-0.1.0.dist-info/RECORD,,

tonflow-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

tonflow-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kakharov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.