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

cryptochief/contract/evm_abi.py

@@ -0,0 +1,321 @@
+"""Solidity ABI encoder - turns a function signature + argument values into
+calldata, so callers never hand-encode the ``data`` field. Shared by EVM and
+TRON (TRON uses the same ABI).
+
+Supported types: ``uint<M>`` / ``int<M>`` (M in 8..256, step 8; bare ``uint`` /
+``int`` alias to 256), ``address`` (0x hex, 0x41 TRON hex, or ``T...`` base58),
+``bool``, ``bytes``, ``bytes<N>`` (N in 1..32), ``string``, and fixed / dynamic
+arrays ``T[]`` / ``T[N]`` of any supported ``T``.
+
+Argument value forms: integers accept ``int`` or a string (decimal / ``0x``
+hex); ``bytes`` accept ``bytes`` / ``bytearray`` or a string (raw / ``0x`` hex);
+``address`` / ``string`` take strings; arrays take lists of the above.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, List, Optional
+
+from ..errors import CryptoChiefError
+from .keccak import keccak_256
+from .tron_address import tron_to_hex
+
+
+class EvmAbiError(CryptoChiefError):
+    def __init__(self, message: str) -> None:
+        super().__init__(f"cryptochief/evm: {message}")
+
+
+@dataclass
+class _AbiType:
+    # kind: uint | int | address | bool | bytes | string | bytesN | array
+    kind: str
+    size: int = 0  # bits for int/uint; byte length for bytesN; element count for fixed arrays (-1 dynamic)
+    element: Optional["_AbiType"] = None
+
+
+# -- Signature parsing --------------------------------------------------------
+
+
+def _expand_alias(t: str) -> str:
+    i = t.rfind("[")
+    if i > 0:
+        return _expand_alias(t[:i]) + t[i:]
+    if t == "uint":
+        return "uint256"
+    if t == "int":
+        return "int256"
+    if t == "byte":
+        return "bytes1"
+    return t
+
+
+def _strip_param_name(p: str) -> str:
+    p = p.strip()
+    sp = p.find(" ")
+    if sp >= 0:
+        p = p[:sp].strip()
+    return _expand_alias(p)
+
+
+def canonical_signature(sig: str) -> str:
+    """Canonical form keccak hashes against (no spaces, no parameter names)."""
+    open_i = sig.find("(")
+    close_i = sig.rfind(")")
+    if open_i < 0 or close_i < 0 or close_i < open_i:
+        return sig.replace(" ", "")
+    name = sig[:open_i].strip()
+    body = sig[open_i + 1 : close_i].strip()
+    if body == "":
+        return f"{name}()"
+    parts = [_strip_param_name(p) for p in body.split(",")]
+    return f"{name}({','.join(parts)})"
+
+
+def _parse_signature(sig: str) -> tuple[str, List[str]]:
+    open_i = sig.find("(")
+    close_i = sig.rfind(")")
+    if open_i < 0 or close_i < 0 or close_i < open_i:
+        raise EvmAbiError(f"bad signature {sig!r}")
+    name = sig[:open_i].strip()
+    if name == "":
+        raise EvmAbiError("signature missing name")
+    body = sig[open_i + 1 : close_i].strip()
+    if body == "":
+        return name, []
+    return name, [_strip_param_name(p) for p in body.split(",")]
+
+
+def _parse_int_bits(s: str, kind: str) -> int:
+    if s == "":
+        return 256
+    if not s.isdigit():
+        raise EvmAbiError(f"invalid {kind} width {s!r}")
+    bits = int(s)
+    if bits <= 0 or bits > 256 or bits % 8 != 0:
+        raise EvmAbiError(f"invalid {kind} width {s!r}")
+    return bits
+
+
+def _parse_type(raw: str) -> _AbiType:
+    t = raw.strip()
+    if t == "":
+        raise EvmAbiError("empty type")
+    if t.endswith("]"):
+        open_i = t.rfind("[")
+        if open_i < 0:
+            raise EvmAbiError(f"malformed type {t!r}")
+        element = _parse_type(t[:open_i])
+        span = t[open_i + 1 : len(t) - 1]
+        size = -1
+        if span != "":
+            if not span.isdigit():
+                raise EvmAbiError(f"bad array size in {t!r}")
+            size = int(span)
+        return _AbiType(kind="array", size=size, element=element)
+    if t.startswith("uint"):
+        return _AbiType(kind="uint", size=_parse_int_bits(t[4:], "uint"))
+    if t.startswith("int"):
+        return _AbiType(kind="int", size=_parse_int_bits(t[3:], "int"))
+    if t == "address":
+        return _AbiType(kind="address")
+    if t == "bool":
+        return _AbiType(kind="bool")
+    if t == "string":
+        return _AbiType(kind="string")
+    if t == "bytes":
+        return _AbiType(kind="bytes")
+    if t.startswith("bytes"):
+        rest = t[5:]
+        if not rest.isdigit():
+            raise EvmAbiError(f"invalid fixed bytes type {t!r}")
+        n = int(rest)
+        if n < 1 or n > 32:
+            raise EvmAbiError(f"invalid fixed bytes type {t!r}")
+        return _AbiType(kind="bytesN", size=n)
+    raise EvmAbiError(f"unsupported type {t!r}")
+
+
+def _is_dynamic(t: _AbiType) -> bool:
+    if t.kind in ("bytes", "string"):
+        return True
+    if t.kind == "array":
+        return t.size < 0 or _is_dynamic(t.element)  # type: ignore[arg-type]
+    return False
+
+
+# -- Value coercion -----------------------------------------------------------
+
+
+def _to_int(v: Any) -> int:
+    if isinstance(v, bool):
+        raise EvmAbiError("integer: got bool")
+    if isinstance(v, int):
+        return v
+    if isinstance(v, str):
+        s = v.strip()
+        if s == "":
+            raise EvmAbiError("integer: empty string")
+        try:
+            return int(s, 16) if s[:2].lower() == "0x" else int(s, 10)
+        except ValueError as err:
+            raise EvmAbiError(f"invalid integer string {v!r}") from err
+    raise EvmAbiError(f"integer: unsupported type {type(v).__name__}")
+
+
+def _to_big_uint(v: Any, bits: int) -> int:
+    n = _to_int(v)
+    if n < 0:
+        raise EvmAbiError(f"uint{bits}: negative value {n}")
+    if n >= (1 << bits):
+        raise EvmAbiError(f"uint{bits}: value {n} exceeds max")
+    return n
+
+
+def _to_bytes(v: Any) -> bytes:
+    if isinstance(v, (bytes, bytearray)):
+        return bytes(v)
+    if isinstance(v, str):
+        s = v.strip()
+        if s[:2].lower() == "0x":
+            hexpart = s[2:]
+            try:
+                return bytes.fromhex(hexpart)
+            except ValueError as err:
+                raise EvmAbiError(f"bytes: bad hex {v!r}") from err
+        return s.encode("utf-8")
+    raise EvmAbiError(f"bytes: unsupported type {type(v).__name__}")
+
+
+def _normalize_evm_address(value: Any) -> bytes:
+    """Accept 0x hex, 0x41 TRON hex, or ``T...`` base58; return the 20-byte address."""
+    if not isinstance(value, str):
+        raise EvmAbiError(f"address: want string, got {type(value).__name__}")
+    s = value.strip()
+    if s == "":
+        raise EvmAbiError("address: empty")
+    if len(s) >= 30 and s[0] in "Tt" and s[:2].lower() != "0x":
+        raw = bytes.fromhex(tron_to_hex(s)[2:])
+        if len(raw) == 21 and raw[0] == 0x41:
+            return raw[1:]
+        if len(raw) == 20:
+            return raw
+        raise EvmAbiError(f"address: unexpected TRON length {len(raw)}")
+    if s[:2].lower() == "0x":
+        s = s[2:]
+    if len(s) == 42 and s[:2] == "41":  # 0x41-prefixed TRON hex
+        s = s[2:]
+    if len(s) != 40:
+        raise EvmAbiError(f"address: want 20 hex bytes, got {len(s)} chars")
+    try:
+        return bytes.fromhex(s)
+    except ValueError as err:
+        raise EvmAbiError("address: bad hex") from err
+
+
+# -- Word packing -------------------------------------------------------------
+
+_TWO_256 = 1 << 256
+
+
+def _uint256_bytes(n: int) -> bytes:
+    return (n % _TWO_256).to_bytes(32, "big")
+
+
+def _round_up_32(n: int) -> int:
+    r = n % 32
+    return n if r == 0 else n + 32 - r
+
+
+def _encode_dyn_bytes(b: bytes) -> bytes:
+    return _uint256_bytes(len(b)) + b + b"\x00" * (_round_up_32(len(b)) - len(b))
+
+
+def _encode_one(t: _AbiType, v: Any) -> bytes:
+    if t.kind == "uint":
+        return _uint256_bytes(_to_big_uint(v, t.size))
+    if t.kind == "int":
+        return _uint256_bytes(_to_int(v))
+    if t.kind == "address":
+        return b"\x00" * 12 + _normalize_evm_address(v)
+    if t.kind == "bool":
+        if not isinstance(v, bool):
+            raise EvmAbiError(f"bool: want bool, got {type(v).__name__}")
+        return b"\x00" * 31 + (b"\x01" if v else b"\x00")
+    if t.kind == "bytesN":
+        b = _to_bytes(v)
+        if len(b) != t.size:
+            raise EvmAbiError(f"bytes{t.size}: expected {t.size} bytes, got {len(b)}")
+        return b + b"\x00" * (32 - t.size)
+    if t.kind == "bytes":
+        return _encode_dyn_bytes(_to_bytes(v))
+    if t.kind == "string":
+        if not isinstance(v, str):
+            raise EvmAbiError(f"string: want string, got {type(v).__name__}")
+        return _encode_dyn_bytes(v.encode("utf-8"))
+    if t.kind == "array":
+        if not isinstance(v, (list, tuple)):
+            raise EvmAbiError(f"array: want list, got {type(v).__name__}")
+        if t.size >= 0 and len(v) != t.size:
+            raise EvmAbiError(f"fixed array T[{t.size}]: expected {t.size} items, got {len(v)}")
+        assert t.element is not None  # arrays always carry an element type
+        inner = [t.element] * len(v)
+        body = _encode_components(inner, list(v))
+        if t.size < 0:
+            return _uint256_bytes(len(v)) + body
+        return body
+    raise EvmAbiError(f"cannot encode kind {t.kind}")
+
+
+def _encode_components(types: List[_AbiType], args: List[Any]) -> bytes:
+    tails: List[bytes] = []
+    for i, t in enumerate(types):
+        try:
+            tails.append(_encode_one(t, args[i]))
+        except EvmAbiError as err:
+            raise EvmAbiError(f"arg {i}: {_strip_prefix(str(err))}") from err
+    head_size = 32 * len(types)
+    offsets: List[int] = [0] * len(types)
+    cursor = head_size
+    for i, t in enumerate(types):
+        if _is_dynamic(t):
+            offsets[i] = cursor
+            cursor += len(tails[i])
+    heads: List[bytes] = []
+    for i, t in enumerate(types):
+        heads.append(_uint256_bytes(offsets[i]) if _is_dynamic(t) else tails[i])
+    dynamic_tails = [tails[i] if _is_dynamic(t) else b"" for i, t in enumerate(types)]
+    return b"".join(heads) + b"".join(dynamic_tails)
+
+
+def _strip_prefix(msg: str) -> str:
+    prefix = "cryptochief/evm: "
+    return msg[len(prefix) :] if msg.startswith(prefix) else msg
+
+
+# -- Public API ---------------------------------------------------------------
+
+
+def evm_selector(signature: str) -> bytes:
+    """The 4-byte function selector for a Solidity signature."""
+    return keccak_256(canonical_signature(signature).encode("utf-8"))[:4]
+
+
+def encode_evm_call(signature: str, *args: Any) -> bytes:
+    """Build ABI calldata (selector + encoded args) as raw bytes."""
+    name, type_strs = _parse_signature(signature)
+    if len(type_strs) != len(args):
+        raise EvmAbiError(f"signature has {len(type_strs)} args, got {len(args)}")
+    parsed: List[_AbiType] = []
+    for i, s in enumerate(type_strs):
+        try:
+            parsed.append(_parse_type(s))
+        except EvmAbiError as err:
+            raise EvmAbiError(f"arg {i} ({s}): {_strip_prefix(str(err))}") from err
+    return evm_selector(signature) + _encode_components(parsed, list(args))
+
+
+def encode_evm_call_hex(signature: str, *args: Any) -> str:
+    """Build ABI calldata as a ``0x...`` hex string (the form the ``data`` field expects)."""
+    return "0x" + encode_evm_call(signature, *args).hex()

cryptochief/contract/keccak.py

@@ -0,0 +1,16 @@
+"""Keccak-256 (Ethereum's legacy hash, distinct from NIST SHA3-256).
+
+Used only to derive EVM/TRON function selectors. Backed by pycryptodome's
+well-tested implementation.
+"""
+
+from __future__ import annotations
+
+from Cryptodome.Hash import keccak as _keccak
+
+
+def keccak_256(data: bytes) -> bytes:
+    """Return the 32-byte Keccak-256 digest of ``data``."""
+    h = _keccak.new(digest_bits=256)
+    h.update(data)
+    return h.digest()

cryptochief/contract/tron_address.py

@@ -0,0 +1,60 @@
+"""TRON address conversion (Base58Check <-> 0x41 hex)."""
+
+from __future__ import annotations
+
+import hashlib
+
+from ..errors import CryptoChiefError
+from .base58 import base58_decode, base58_encode
+
+
+def _sha256d(b: bytes) -> bytes:
+    return hashlib.sha256(hashlib.sha256(b).digest()).digest()
+
+
+def tron_to_hex(base58_addr: str) -> str:
+    """Convert a TRON base58 address (``T...``) to its 0x41-prefixed 21-byte hex.
+
+    Validates the Base58Check (double-SHA-256) checksum.
+
+    >>> tron_to_hex("TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t")
+    '0x41a614f803b6fd780986a42c78ec9c7f77e6ded13c'
+    """
+    decoded = base58_decode(base58_addr.strip())
+    if len(decoded) != 25:
+        raise CryptoChiefError(f"cryptochief/tron: decoded length {len(decoded)}, want 25")
+    payload = decoded[:21]
+    checksum = decoded[21:]
+    if payload[0] != 0x41:
+        raise CryptoChiefError(f"cryptochief/tron: leading byte 0x{payload[0]:02x}, want 0x41")
+    if checksum != _sha256d(payload)[:4]:
+        raise CryptoChiefError("cryptochief/tron: checksum mismatch")
+    return "0x" + payload.hex()
+
+
+def hex_to_tron(hex_addr: str) -> str:
+    """Convert a 20-byte EVM-style hex (or a 0x41-prefixed 21-byte TRON hex) to base58.
+
+    A 20-byte input is prefixed with ``0x41`` automatically.
+    """
+    s = hex_addr.strip()
+    if s[:2].lower() == "0x":
+        s = s[2:]
+    try:
+        raw = bytes.fromhex(s)
+    except ValueError as err:
+        raise CryptoChiefError(f"cryptochief/tron: bad hex {hex_addr!r}: {err}") from err
+    if len(raw) == 20:
+        payload = b"\x41" + raw
+    elif len(raw) == 21:
+        if raw[0] != 0x41:
+            raise CryptoChiefError(
+                f"cryptochief/tron: 21-byte input must start with 0x41, got 0x{raw[0]:02x}"
+            )
+        payload = raw
+    else:
+        raise CryptoChiefError(
+            f"cryptochief/tron: want 20- or 21-byte hex address, got {len(raw)} bytes"
+        )
+    checksum = _sha256d(payload)[:4]
+    return base58_encode(payload + checksum)

cryptochief/errors.py

@@ -0,0 +1,111 @@
+"""Error model for the SDK.
+
+Everything the SDK raises derives from :class:`CryptoChiefError`, so a single
+``except CryptoChiefError`` covers the library. API-level failures arrive as
+:class:`APIError` with a stable :attr:`APIError.code` string - branch on
+:class:`ErrorCode` (or ``error.code``) rather than parsing messages.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+
+class CryptoChiefError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class APIError(CryptoChiefError):
+    """A typed Crypto Chief error response.
+
+    The API returns either ``{"error": "SERVICE_ERROR", "msg": "<CODE>", ...}``
+    (then :attr:`code` is ``<CODE>``) or ``{"error": "<CODE>", ...}`` (then
+    :attr:`code` is that value). Either way :attr:`code` is the stable
+    identifier to branch on::
+
+        try:
+            await client.payouts.execute(req)
+        except APIError as e:
+            if e.code == ErrorCode.INSUFFICIENT_FUNDS:
+                ...  # top up and retry
+    """
+
+    code: str
+    http_status: int
+    raw: Optional[str]
+
+    def __init__(
+        self,
+        code: str,
+        *,
+        http_status: int = 0,
+        message: Optional[str] = None,
+        raw: Optional[str] = None,
+    ) -> None:
+        # Normalize an ErrorCode member to its wire string ("NETWORK_ERROR"),
+        # not its enum repr ("ErrorCode.NETWORK_ERROR").
+        self.code = code.value if isinstance(code, Enum) else str(code)
+        self.http_status = http_status
+        self.raw = raw
+        super().__init__(self._format(http_status, self.code, message))
+
+    @staticmethod
+    def _format(status: int, code: str, message: Optional[str]) -> str:
+        if status == 0:
+            return f"cryptochief: {code}"
+        if message and message != code:
+            return f"cryptochief: {status} {code}: {message}"
+        return f"cryptochief: {status} {code}"
+
+
+class ErrorCode(str, Enum):
+    """Stable error codes.
+
+    Not exhaustive - the API defines more per endpoint and may add new ones, so
+    treat an unknown :attr:`APIError.code` as opaque.
+    """
+
+    INSUFFICIENT_FUNDS = "INSUFFICIENT_FUNDS"
+    INSUFFICIENT_CREDITS = "INSUFFICIENT_CREDITS"
+    DEBT_LIMIT_EXCEEDED = "DEBT_LIMIT_EXCEEDED"
+    ASSET_NOT_ENABLED = "ASSET_NOT_ENABLED"
+    ORDER_ALREADY_EXIST = "ORDER_ALREADY_EXIST"
+    ORDER_CANNOT_CANCEL = "ORDER_CANNOT_CANCEL"
+    ORDER_NOT_LIVE = "ORDER_NOT_LIVE"
+    ASSET_ALREADY_SELECTED = "ASSET_ALREADY_SELECTED"
+    INVALID_PARAMS = "INVALID_PARAMS"
+    SERVICE_ERROR = "SERVICE_ERROR"
+    UNAUTHORIZED = "UNAUTHORIZED"
+    URL_CALLBACK_REQUIRED = "URL_CALLBACK_REQUIRED"
+    BATCH_EMPTY = "BATCH_EMPTY"
+    BATCH_TOO_LARGE = "BATCH_TOO_LARGE"
+    BATCH_DUPLICATE_ORDER_ID = "BATCH_DUPLICATE_ORDER_ID"
+    FROM_WALLET_NOT_OWNED = "FROM_WALLET_NOT_OWNED"
+    SIGNATURE_EXPIRED = "SIGNATURE_EXPIRED"
+    ALREADY_EXECUTED = "ALREADY_EXECUTED"
+    PREFLIGHT_FAILED = "PREFLIGHT_FAILED"
+    BROADCAST_FAILED = "BROADCAST_FAILED"
+    SIGNED_TX_MISMATCH = "SIGNED_TX_MISMATCH"
+    CONTRACT_REQUIRED_FOR_TOKEN = "CONTRACT_REQUIRED_FOR_TOKEN"
+    TRANSFER_FIELDS_NOT_ALLOWED_FOR_CONTRACT = "TRANSFER_FIELDS_NOT_ALLOWED_FOR_CONTRACT"
+    CALLS_REQUIRED = "CALLS_REQUIRED"
+    CALLS_NOT_ALLOWED_FOR_TRANSFER = "CALLS_NOT_ALLOWED_FOR_TRANSFER"
+    CONTRACT_CALLS_UNSUPPORTED_ON_NETWORK = "CONTRACT_CALLS_UNSUPPORTED_ON_NETWORK"
+    NETWORK_ERROR = "NETWORK_ERROR"
+
+
+def is_api_error(err: object, code: Optional[str] = None) -> bool:
+    """``True`` when ``err`` is an :class:`APIError` (optionally with ``code``)."""
+    return isinstance(err, APIError) and (code is None or err.code == code)
+
+
+def is_retryable(err: object) -> bool:
+    """Report whether an error is plausibly transient and worth retrying.
+
+    Only 5xx responses and transport ``NETWORK_ERROR`` failures qualify; 4xx is
+    the caller's fault and is never retried.
+    """
+    if isinstance(err, APIError):
+        return err.http_status >= 500 or err.code == ErrorCode.NETWORK_ERROR
+    return False

cryptochief/pagination.py

@@ -0,0 +1,32 @@
+"""Shared pagination shapes for the history endpoints."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(kw_only=True)
+class HistoryQuery:
+    """Common filter for history endpoints with simple pagination.
+
+    Omitted (``None``) fields are not sent.
+    """
+
+    page: Optional[int] = None
+    page_size: Optional[int] = None
+    status: Optional[str] = None
+    coin: Optional[str] = None
+    network: Optional[str] = None
+    date_from: Optional[str] = None
+    date_to: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class HistoryMeta:
+    """Pagination envelope returned by every history endpoint."""
+
+    page: int = 0
+    page_size: int = 0
+    total: int = 0
+    total_pages: Optional[int] = None

cryptochief/poll.py

@@ -0,0 +1,56 @@
+"""Async polling helper used by the ``wait_for`` methods."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Awaitable, Callable, Generic, Optional, TypeVar
+
+from .errors import CryptoChiefError, is_retryable
+
+T = TypeVar("T")
+
+
+class PollTimeoutError(CryptoChiefError, Generic[T]):
+    """Raised when a ``wait_for`` helper times out before reaching a terminal state."""
+
+    last_state: Optional[T]
+
+    def __init__(self, timeout: float, last_state: Optional[T] = None) -> None:
+        super().__init__(
+            f"cryptochief: poll did not reach a terminal state within {timeout}s"
+        )
+        self.last_state = last_state
+
+
+async def wait_for_terminal(
+    fetch_one: Callable[[], Awaitable[T]],
+    is_terminal: Callable[[T], bool],
+    *,
+    interval: float = 5.0,
+    timeout: float = 600.0,
+) -> T:
+    """Poll ``fetch_one`` until ``is_terminal`` holds or ``timeout`` elapses.
+
+    Transient (retryable) fetch errors are tolerated and retried on the next
+    tick; other errors propagate immediately. On timeout a
+    :class:`PollTimeoutError` carrying the last observed state is raised.
+    """
+    interval = interval if interval and interval > 0 else 5.0
+    timeout = timeout if timeout and timeout > 0 else 600.0
+    deadline = time.monotonic() + timeout
+    last: Optional[T] = None
+
+    while True:
+        try:
+            value = await fetch_one()
+            last = value
+            if is_terminal(value):
+                return value
+        except Exception as err:  # noqa: BLE001 - re-raised unless retryable
+            if not is_retryable(err):
+                raise
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise PollTimeoutError(timeout, last)
+        await asyncio.sleep(min(interval, remaining))

cryptochief/rsa.py

@@ -0,0 +1,70 @@
+"""Local RSA decryption of generated wallets' private keys.
+
+When the API generates a wallet it returns the private key encrypted with the
+RSA public key uploaded to your project (Project Settings -> RSA Key). The scheme
+is RSA-OAEP / SHA-256 over base64-encoded ciphertext. Configure the matching
+private key on the client to decrypt it locally.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Union
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey
+
+from .errors import CryptoChiefError
+
+
+class RsaKeyNotConfiguredError(CryptoChiefError):
+    """Raised by ``client.wallets.decrypt_private_key`` when no RSA key was configured."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "cryptochief: RSA private key not configured - pass rsa_private_key to the client"
+        )
+
+
+def load_rsa_private_key_pem(pem: Union[str, bytes, bytearray]) -> RSAPrivateKey:
+    """Parse a PEM-encoded RSA private key (PKCS#1 or PKCS#8) into a key object."""
+    data = pem.encode("utf-8") if isinstance(pem, str) else bytes(pem)
+    try:
+        key = serialization.load_pem_private_key(data, password=None)
+    except Exception as err:  # noqa: BLE001 - normalize to our error type
+        raise CryptoChiefError(f"cryptochief: RSA key: {err}") from err
+    if not isinstance(key, RSAPrivateKey):
+        raise CryptoChiefError("cryptochief: RSA key: not an RSA private key")
+    return key
+
+
+def load_rsa_private_key_file(path: str) -> RSAPrivateKey:
+    """Read and parse a PEM-encoded RSA private key from disk."""
+    try:
+        with open(path, "rb") as fh:
+            data = fh.read()
+    except OSError as err:
+        raise CryptoChiefError(f"cryptochief: read RSA key {path!r}: {err}") from err
+    return load_rsa_private_key_pem(data)
+
+
+def decrypt_rsa_oaep(key: RSAPrivateKey, base64_ciphertext: str) -> str:
+    """Decrypt a single base64-encoded RSA-OAEP / SHA-256 payload.
+
+    The exact encoding the API uses for ``private_key_encrypted``. Returns the
+    wallet's raw private key in the chain's native hex form.
+    """
+    ciphertext = base64.b64decode(base64_ciphertext)
+    try:
+        plaintext = key.decrypt(
+            ciphertext,
+            padding.OAEP(
+                mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                algorithm=hashes.SHA256(),
+                label=None,
+            ),
+        )
+    except Exception as err:  # noqa: BLE001 - normalize to our error type
+        raise CryptoChiefError(f"cryptochief: RSA decrypt: {err}") from err
+    return plaintext.decode("utf-8")

cryptochief/services/__init__.py

@@ -0,0 +1 @@
+"""Domain services exposed as attributes on :class:`cryptochief.CryptoChiefClient`."""