cryptochief-crypto-processing-python 0.1.0__py3-none-any.whl

cryptochief/sign.py

@@ -0,0 +1,112 @@
+"""Canonical JSON + request signing.
+
+Crypto Chief signs the *canonical* serialization of a request body. The
+canonical form is fully deterministic:
+
+* object keys sorted lexicographically by their UTF-8 bytes, recursively;
+* compact (no insignificant whitespace);
+* the HTML-sensitive characters ``<``, ``>``, ``&`` and the U+2028 / U+2029
+  line / paragraph separators emitted as their JSON unicode escapes;
+* standard JSON escapes for ``"``, ``\\``, and control characters (``\\n``,
+  ``\\r``, ``\\t`` short forms; everything else below 0x20 as ``\\u00XX``,
+  lowercase hex).
+
+The gateway re-derives this canonical form from the bytes it receives and
+checks the signature against it, so the client must emit byte-identical output.
+The regression vectors in ``tests/test_sign.py`` lock this down.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+from typing import Any, Tuple
+
+from .errors import CryptoChiefError
+
+_SHORT_ESCAPES = {
+    0x22: '\\"',
+    0x5C: "\\\\",
+    0x0A: "\\n",
+    0x0D: "\\r",
+    0x09: "\\t",
+    0x3C: "\\u003c",
+    0x3E: "\\u003e",
+    0x26: "\\u0026",
+    0x2028: "\\u2028",
+    0x2029: "\\u2029",
+}
+
+
+def _encode_string(s: str) -> str:
+    out = ['"']
+    for ch in s:
+        code = ord(ch)
+        esc = _SHORT_ESCAPES.get(code)
+        if esc is not None:
+            out.append(esc)
+        elif code < 0x20:
+            out.append("\\u%04x" % code)
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def _encode_number(n: "int | float") -> str:
+    if isinstance(n, bool):  # bool is a subclass of int - guard first
+        return "true" if n else "false"
+    if isinstance(n, int):
+        return str(n)
+    # Floats are not expected in signed bodies (amounts travel as strings), but
+    # match the gateway's shortest-form rendering: integral floats drop the dot.
+    if n != n or n in (float("inf"), float("-inf")):
+        raise CryptoChiefError(f"cryptochief: cannot canonicalize non-finite number {n}")
+    if n == int(n) and abs(n) < 1e21:
+        return str(int(n))
+    return repr(n)
+
+
+def _encode_value(v: Any) -> str:
+    if v is None:
+        return "null"
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, str):
+        return _encode_string(v)
+    if isinstance(v, (int, float)):
+        return _encode_number(v)
+    if isinstance(v, dict):
+        keys = [k for k, val in v.items() if val is not None]
+        keys.sort(key=lambda k: str(k).encode("utf-8"))
+        parts = [_encode_string(str(k)) + ":" + _encode_value(v[k]) for k in keys]
+        return "{" + ",".join(parts) + "}"
+    if isinstance(v, (list, tuple)):
+        return "[" + ",".join(_encode_value(el) for el in v) + "]"
+    raise CryptoChiefError(f"cryptochief: cannot canonicalize value of type {type(v).__name__}")
+
+
+def canonical_json(value: Any) -> str:
+    """Produce the canonical JSON string for a value.
+
+    ``None`` collapses to an empty body, which signs as ``md5(api_key)``.
+    """
+    if value is None:
+        return ""
+    return _encode_value(value)
+
+
+def sign(canonical_body: str, api_key: str) -> str:
+    """Compute the ``Signature`` header for an already-canonical body.
+
+    ``hex(md5(base64(canonical_body) + api_key))``. An empty body signs as
+    ``md5(api_key)``.
+    """
+    b64 = base64.b64encode(canonical_body.encode("utf-8")).decode("ascii")
+    return hashlib.md5((b64 + api_key).encode("utf-8")).hexdigest()
+
+
+def sign_value(value: Any, api_key: str) -> Tuple[str, str]:
+    """Canonicalize then sign a value, returning ``(canonical, signature)``."""
+    canonical = canonical_json(value)
+    return canonical, sign(canonical, api_key)

cryptochief/ton/__init__.py

@@ -0,0 +1,19 @@
+"""TON helpers: offline address parsing (public) and cell builders (used internally)."""
+
+from __future__ import annotations
+
+from .address import (
+    TonAddress,
+    crc16_xmodem,
+    parse_ton_address,
+    ton_address_to_raw,
+    ton_address_to_string,
+)
+
+__all__ = [
+    "TonAddress",
+    "crc16_xmodem",
+    "parse_ton_address",
+    "ton_address_to_raw",
+    "ton_address_to_string",
+]

cryptochief/ton/address.py

@@ -0,0 +1,109 @@
+"""Offline parsing / validation of TON addresses.
+
+TON addresses come in three skins, all wrapping the same 33 bytes (1 tag +
+1 workchain + 32 hash):
+
+* user-friendly bounceable     ``EQ...`` (mainnet) / ``kQ...`` (testnet)
+* user-friendly non-bounceable ``UQ...`` (mainnet) / ``0Q...`` (testnet)
+* raw                          ``<workchain>:<32-byte-hex>``
+
+The user-friendly forms add a 2-byte CRC16-XMODEM checksum, which this parser
+validates. No network access - this is purely for local validation / display.
+"""
+
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+
+from ..errors import CryptoChiefError
+
+
+@dataclass
+class TonAddress:
+    workchain: int
+    hash: bytes  # 32 bytes
+    bounceable: bool
+    testnet: bool
+
+
+def crc16_xmodem(data: bytes) -> int:
+    """CRC-16/XMODEM (poly 0x1021, init 0x0000, non-reflected) - TON's checksum."""
+    crc = 0
+    for b in data:
+        crc ^= b << 8
+        for _ in range(8):
+            crc = ((crc << 1) ^ 0x1021) & 0xFFFF if crc & 0x8000 else (crc << 1) & 0xFFFF
+    return crc & 0xFFFF
+
+
+def _parse_raw(s: str, colon: int) -> TonAddress:
+    try:
+        wc = int(s[:colon], 10)
+    except ValueError as err:
+        raise CryptoChiefError(f"cryptochief/ton: bad raw workchain {s[:colon]!r}") from err
+    if wc < -128 or wc > 127:
+        raise CryptoChiefError(f"cryptochief/ton: bad raw workchain {s[:colon]!r}")
+    hash_hex = s[colon + 1 :]
+    if len(hash_hex) != 64:
+        raise CryptoChiefError(f"cryptochief/ton: hash hex length {len(hash_hex)}, want 64")
+    try:
+        h = bytes.fromhex(hash_hex)
+    except ValueError as err:
+        raise CryptoChiefError("cryptochief/ton: bad hash hex") from err
+    return TonAddress(workchain=wc, hash=h, bounceable=True, testnet=False)
+
+
+def _parse_friendly(s: str) -> TonAddress:
+    if len(s) != 48:
+        raise CryptoChiefError(f"cryptochief/ton: user-friendly address length {len(s)}, want 48")
+    # TON uses URL-safe base64; accept the standard alphabet too.
+    try:
+        raw = base64.b64decode(s.replace("-", "+").replace("_", "/"))
+    except (ValueError, base64.binascii.Error) as err:  # type: ignore[attr-defined]
+        raise CryptoChiefError(f"cryptochief/ton: bad base64 address: {err}") from err
+    if len(raw) != 36:
+        raise CryptoChiefError(f"cryptochief/ton: decoded length {len(raw)}, want 36")
+    want = crc16_xmodem(raw[:34])
+    got = (raw[34] << 8) | raw[35]
+    if want != got:
+        raise CryptoChiefError("cryptochief/ton: CRC mismatch")
+    tag = raw[0]
+    workchain = raw[1] - 256 if raw[1] > 127 else raw[1]  # sign-extend to int8
+    return TonAddress(
+        workchain=workchain,
+        hash=raw[2:34],
+        bounceable=(tag & 0x40) == 0,
+        testnet=(tag & 0x80) != 0,
+    )
+
+
+def parse_ton_address(value: str) -> TonAddress:
+    """Parse any of the three TON address forms; raises on CRC / length errors."""
+    s = value.strip()
+    if s == "":
+        raise CryptoChiefError("cryptochief/ton: empty address")
+    colon = s.find(":")
+    if colon > 0:
+        return _parse_raw(s, colon)
+    return _parse_friendly(s)
+
+
+def ton_address_to_string(a: TonAddress) -> str:
+    """Render the user-friendly form (URL-safe base64, no padding)."""
+    tag = 0x11 if a.bounceable else 0x51
+    if a.testnet:
+        tag |= 0x80
+    buf = bytearray(36)
+    buf[0] = tag
+    buf[1] = a.workchain & 0xFF
+    buf[2:34] = a.hash[:32]
+    crc = crc16_xmodem(bytes(buf[:34]))
+    buf[34] = crc >> 8
+    buf[35] = crc & 0xFF
+    return base64.urlsafe_b64encode(bytes(buf)).decode("ascii").rstrip("=")
+
+
+def ton_address_to_raw(a: TonAddress) -> str:
+    """Render the raw ``workchain:hex`` form."""
+    return f"{a.workchain}:{a.hash.hex()}"

cryptochief/ton/messages.py

@@ -0,0 +1,105 @@
+"""TON message-body builders.
+
+BoC (de)serialization is delegated to ``pytoniq-core``; the SDK does not encode
+cells by hand. These helpers produce the raw BoC bytes the contract-call
+``data`` field expects (base64-encoded by the caller).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pytoniq_core import Address, Cell, begin_cell
+
+from ..errors import CryptoChiefError
+
+# TON internal-message op codes from the public TEP standards.
+OP_JETTON_TRANSFER = 0x0F8A7EA5  # TEP-74
+OP_NFT_TRANSFER = 0x5FCC3D14  # TEP-62
+OP_TEXT_COMMENT = 0x00000000
+
+
+def parse_ton_addr(s: str) -> Address:
+    """Parse any TON address form (``EQ`` / ``UQ`` or raw ``workchain:hex``)."""
+    try:
+        return Address(s)
+    except Exception as err:  # noqa: BLE001 - library raises various types
+        raise CryptoChiefError(
+            f"cryptochief/ton: invalid TON address {s!r} "
+            f"(expected EQ/UQ or workchain:hex): {err}"
+        ) from err
+
+
+def build_jetton_transfer_body(
+    *,
+    query_id: int,
+    amount: int,
+    destination: Address,
+    response_dest: Optional[Address],
+    custom_payload: Optional[Cell] = None,
+    forward_ton: int,
+    forward_payload: Optional[Cell] = None,
+) -> bytes:
+    """Standard Jetton "transfer" body (TEP-74, op ``0x0f8a7ea5``).
+
+    ``destination`` is the recipient's *main* TON wallet; the network handles the
+    wallet-to-wallet hop.
+    """
+    if amount < 0:
+        raise CryptoChiefError("cryptochief/ton: jetton amount must be non-negative")
+    b = (
+        begin_cell()
+        .store_uint(OP_JETTON_TRANSFER, 32)
+        .store_uint(query_id, 64)
+        .store_coins(amount)
+        .store_address(destination)
+        .store_address(response_dest)
+        .store_maybe_ref(custom_payload)
+        .store_coins(max(forward_ton, 0))
+    )
+    # forward_payload: Either Cell ^Cell - ref when supplied, empty-inline otherwise.
+    if forward_payload is not None:
+        b = b.store_bit(1).store_ref(forward_payload)
+    else:
+        b = b.store_bit(0)
+    return bytes(b.end_cell().to_boc())
+
+
+def build_nft_transfer_body(
+    *,
+    query_id: int,
+    new_owner: Address,
+    response_dest: Optional[Address],
+    custom_payload: Optional[Cell] = None,
+    forward_ton: int,
+    forward_payload: Optional[Cell] = None,
+) -> bytes:
+    """Standard NFT "transfer" body (TEP-62, op ``0x5fcc3d14``)."""
+    b = (
+        begin_cell()
+        .store_uint(OP_NFT_TRANSFER, 32)
+        .store_uint(query_id, 64)
+        .store_address(new_owner)
+        .store_address(response_dest)
+        .store_maybe_ref(custom_payload)
+        .store_coins(max(forward_ton, 0))
+    )
+    if forward_payload is not None:
+        b = b.store_bit(1).store_ref(forward_payload)
+    else:
+        b = b.store_bit(0)
+    return bytes(b.end_cell().to_boc())
+
+
+def build_text_comment_cell(text: str) -> Cell:
+    """A standalone text-comment cell (op ``0`` + UTF-8 snake string).
+
+    Used both as a top-level body and as a Jetton transfer's ``forward_payload``
+    ref when a memo is supplied.
+    """
+    return begin_cell().store_uint(OP_TEXT_COMMENT, 32).store_snake_string(text).end_cell()
+
+
+def build_text_comment_body(text: str) -> bytes:
+    """Simple text-comment body (what wallets show as the transfer note)."""
+    return bytes(build_text_comment_cell(text).to_boc())

cryptochief/ton/rpc.py

@@ -0,0 +1,159 @@
+"""Internal TON RPC client.
+
+Exists only to feed parameters (the sender's Jetton wallet address; whether a
+recipient already has a Jetton wallet) into the high-level TON sign helpers - it
+is not part of the public API surface.
+
+URL pattern: ``<base_url>/ton-v3/<merchant_id>/<endpoint>``. The merchant ID is
+the same credential used by the processing API; no separate token.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any, Optional
+from urllib.parse import urlencode
+
+import httpx
+from pytoniq_core import Cell, begin_cell
+
+from ..errors import CryptoChiefError
+from .messages import parse_ton_addr
+
+DEFAULT_TON_RPC_BASE_URL = "https://rpc.crypto-chief.com"
+
+
+class TonRpc:
+    def __init__(
+        self,
+        *,
+        merchant_id: str,
+        http: httpx.AsyncClient,
+        base_url: Optional[str] = None,
+        user_agent: str,
+    ) -> None:
+        self._merchant_id = merchant_id
+        self._http = http
+        self._base_url = (base_url or DEFAULT_TON_RPC_BASE_URL).rstrip("/")
+        self._user_agent = user_agent
+        self._cache: dict[str, str] = {}
+
+    def _url(self, path: str, query: Optional[dict[str, str]] = None) -> str:
+        u = f"{self._base_url}/ton-v3/{self._merchant_id}/{path.lstrip('/')}"
+        if query:
+            u += "?" + urlencode(query)
+        return u
+
+    async def _get(self, path: str, query: dict[str, str], timeout: float) -> Any:
+        resp = await self._http.get(
+            self._url(path, query),
+            headers={"Accept": "application/json", "User-Agent": self._user_agent},
+            timeout=timeout,
+        )
+        return self._handle(resp, path)
+
+    async def _post(self, path: str, body: Any, timeout: float) -> Any:
+        resp = await self._http.post(
+            self._url(path),
+            json=body,
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": self._user_agent,
+            },
+            timeout=timeout,
+        )
+        return self._handle(resp, path)
+
+    @staticmethod
+    def _handle(resp: httpx.Response, path: str) -> Any:
+        text = resp.text
+        if resp.status_code >= 400:
+            raise CryptoChiefError(
+                f"cryptochief/ton: {path}: HTTP {resp.status_code}: {text[:256]}"
+            )
+        if not text:
+            return None
+        try:
+            return resp.json()
+        except ValueError as err:
+            raise CryptoChiefError(f"cryptochief/ton: decode {path}: {err}") from err
+
+    async def lookup_jetton_wallet(self, jetton_master: str, owner: str) -> str:
+        """Resolve the Jetton wallet holding ``owner``'s balance of ``jetton_master``.
+
+        Primary path: the deterministic ``get_wallet_address`` get-method on the
+        master (works even for an owner that never received the Jetton). Fallback:
+        the indexer. Cached for the client's lifetime.
+        """
+        if not jetton_master or not owner:
+            raise CryptoChiefError("cryptochief/ton: jetton_master and owner are required")
+        cache_key = f"{owner}|{jetton_master}"
+        cached = self._cache.get(cache_key)
+        if cached:
+            return cached
+
+        resolved = ""
+        try:
+            resolved = await self._via_run_method(jetton_master, owner)
+        except Exception:  # noqa: BLE001 - fall back to the indexer
+            resolved = ""
+        if not resolved:
+            resolved = await self._via_index(jetton_master, owner)
+        self._cache[cache_key] = resolved
+        return resolved
+
+    async def _via_run_method(self, jetton_master: str, owner: str) -> str:
+        owner_cell = begin_cell().store_address(parse_ton_addr(owner)).end_cell()
+        owner_boc = base64.b64encode(bytes(owner_cell.to_boc())).decode("ascii")
+        out = await self._post(
+            "/runGetMethod",
+            {
+                "address": jetton_master,
+                "method": "get_wallet_address",
+                "stack": [{"type": "slice", "value": owner_boc}],
+            },
+            15.0,
+        )
+        exit_code = out.get("exit_code") if isinstance(out, dict) else None
+        if exit_code not in (0, None):
+            raise CryptoChiefError(f"cryptochief/ton: get_wallet_address: exit_code={exit_code}")
+        stack = out.get("stack") if isinstance(out, dict) else None
+        if not stack:
+            raise CryptoChiefError("cryptochief/ton: get_wallet_address: empty stack")
+        value = stack[0].get("value")
+        result_cell = Cell.one_from_boc(base64.b64decode(value))
+        return result_cell.begin_parse().load_address().to_str()
+
+    async def _via_index(self, jetton_master: str, owner: str) -> str:
+        out = await self._get(
+            "/jetton/wallets",
+            {"owner_address": owner, "jetton_address": jetton_master, "limit": "1"},
+            15.0,
+        )
+        wallets = (out or {}).get("jetton_wallets") or []
+        if not wallets:
+            raise CryptoChiefError(
+                f"cryptochief/ton: no Jetton wallet found for owner {owner} on master "
+                f"{jetton_master} - owner has never received this Jetton"
+            )
+        wallet = wallets[0]
+        address_book = (out or {}).get("address_book") or {}
+        friendly = (address_book.get(wallet["address"]) or {}).get("user_friendly")
+        return friendly or wallet["address"]
+
+    async def has_jetton_wallet(self, jetton_master: str, owner: str) -> bool:
+        """Whether ``owner`` already holds an initialized Jetton wallet for ``jetton_master``.
+
+        Used to size the attached gas budget on transfers. Returns ``False`` (the
+        conservative answer) on any RPC error.
+        """
+        try:
+            out = await self._get(
+                "/jetton/wallets",
+                {"owner_address": owner, "jetton_address": jetton_master, "limit": "1"},
+                5.0,
+            )
+            return len((out or {}).get("jetton_wallets") or []) > 0
+        except Exception:  # noqa: BLE001 - conservative default
+            return False

cryptochief/transport.py

@@ -0,0 +1,48 @@
+"""Transport helpers: error-envelope parsing and retry backoff."""
+
+from __future__ import annotations
+
+import json
+import random
+
+from .errors import APIError, ErrorCode
+
+
+def parse_api_error(status: int, body: str) -> APIError:
+    """Parse a non-2xx response body into an :class:`APIError` with a stable code.
+
+    The code is ``msg or error or HTTP_<status>``, and the message prefers
+    ``msg`` when it differs from ``error``.
+    """
+    env: dict = {}
+    try:
+        parsed = json.loads(body)
+        if isinstance(parsed, dict):
+            env = parsed
+    except ValueError:
+        pass  # non-JSON error body -> fall back to HTTP_<status>
+    code = env.get("msg") or env.get("error") or f"HTTP_{status}"
+    message = env.get("error") or ""
+    if env.get("msg") and env.get("msg") != env.get("error"):
+        message = env.get("msg")
+    return APIError(code, http_status=status, message=message, raw=body)
+
+
+def backoff_delay(attempt: int, base_ms: float, max_ms: float) -> float:
+    """Exponential backoff with full jitter, capped at ``max_ms``.
+
+    ``attempt`` is 1-indexed (first retry = 1). Returns seconds.
+    """
+    if base_ms <= 0:
+        base_ms = 200
+    if max_ms <= 0:
+        max_ms = 5000
+    d = base_ms * (2 ** (attempt - 1))
+    if d <= 0 or d > max_ms:
+        d = max_ms
+    return random.uniform(0, d) / 1000.0  # full jitter, uniform in [0, d] ms
+
+
+def network_error(message: str) -> APIError:
+    """Build an :class:`APIError` for a transport-level (network) failure."""
+    return APIError(ErrorCode.NETWORK_ERROR, message=message)