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

cryptochief/__init__.py

@@ -0,0 +1,336 @@
+"""Crypto Chief Python SDK - the official async client for the
+`Crypto Chief <https://crypto-chief.com/processing/>`_ crypto processing API.
+
+Accept crypto payments, send single and mass payouts, sign on-chain
+transactions and smart-contract calls, manage wallets, convert fiat to crypto,
+and verify webhooks across Ethereum, Tron, TON, Solana, Bitcoin, XRP and 20+
+more blockchains.
+
+>>> import asyncio
+>>> from cryptochief import CryptoChiefClient, Chain
+>>> from cryptochief import EstimatePayoutRequest
+>>>
+>>> async def main():
+...     async with CryptoChiefClient(merchant_id="M", api_key="K") as client:
+...         est = await client.payouts.estimate(EstimatePayoutRequest(
+...             network=Chain.ETH_SEPOLIA, coin="ETH", amount="0.0001",
+...             to_address="0x...",
+...         ))
+...         print(est.amount_to_receive)
+>>> asyncio.run(main())  # doctest: +SKIP
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .amount import InvalidAmountError, base_to_human, human_to_base, nano_ton
+from .assets import Asset, AssetsPolicy
+from .chains import Chain, ChainFamily, chain_family, supports_contract_calls
+from .client import DEFAULT_BASE_URL, VERSION, CryptoChiefClient
+from .contract import (
+    BorshValue,
+    anchor_discriminator,
+    base58_decode,
+    base58_encode,
+    borsh_bool,
+    borsh_bytes,
+    borsh_fixed_bytes,
+    borsh_i8,
+    borsh_i16,
+    borsh_i32,
+    borsh_i64,
+    borsh_option,
+    borsh_pubkey,
+    borsh_string,
+    borsh_struct,
+    borsh_u8,
+    borsh_u16,
+    borsh_u32,
+    borsh_u64,
+    borsh_u128,
+    borsh_vec,
+    canonical_signature,
+    decode_solana_pubkey,
+    encode_anchor_instruction,
+    encode_evm_call,
+    encode_evm_call_hex,
+    evm_selector,
+    hex_to_tron,
+    keccak_256,
+    tron_to_hex,
+)
+from .errors import APIError, CryptoChiefError, ErrorCode, is_api_error, is_retryable
+from .pagination import HistoryMeta, HistoryQuery
+from .poll import PollTimeoutError, wait_for_terminal
+from .rsa import (
+    RsaKeyNotConfiguredError,
+    decrypt_rsa_oaep,
+    load_rsa_private_key_file,
+    load_rsa_private_key_pem,
+)
+from .services.blockchain import (
+    AvailableContract,
+    AvailableContractsResponse,
+    BlockchainService,
+    TxStatusRow,
+    WalletBalanceRow,
+)
+from .services.currencies import ConvertRequest, ConvertResponse, CurrenciesService
+from .services.payins import (
+    CoinOption,
+    CreatePayInRequest,
+    PayIn,
+    PayInHistoryResponse,
+    PayInMode,
+    PayInsService,
+    PayInStatus,
+    SelectAssetRequest,
+    is_payin_terminal,
+)
+from .services.payouts import (
+    BatchItemResult,
+    BatchPayoutRequest,
+    BatchPayoutResponse,
+    EstimatePayoutRequest,
+    EstimatePayoutResponse,
+    ExecutePayoutRequest,
+    PayoutFeeInfo,
+    PayoutHistoryResponse,
+    PayoutInfo,
+    PayoutsService,
+    PayoutSource,
+    PayoutStatus,
+    is_payout_terminal,
+)
+from .services.static_deposits import (
+    StaticDeposit,
+    StaticDepositHistoryQuery,
+    StaticDepositHistoryResponse,
+    StaticDepositsService,
+    StaticDepositStatus,
+)
+from .services.sweeps import (
+    ForceSweepResponse,
+    Sweep,
+    SweepHistoryQuery,
+    SweepHistoryResponse,
+    SweepMode,
+    SweepsService,
+)
+from .services.transactions import (
+    AnchorCallRequest,
+    ContractCall,
+    Erc20TransferRequest,
+    EvmCallRequest,
+    ExecuteTransactionRequest,
+    JettonTransferRequest,
+    NftTransferRequest,
+    SignTransactionRequest,
+    SignTransactionResponse,
+    SolanaAccount,
+    SolanaCallRequest,
+    TonCallRequest,
+    TonCommentRequest,
+    TransactionHistoryResponse,
+    TransactionInfo,
+    TransactionsService,
+    TxStatus,
+    TxType,
+    is_transaction_terminal,
+)
+from .services.wallets import (
+    GenerateWalletRequest,
+    ListWalletsResponse,
+    Wallet,
+    WalletCoinBalance,
+    WalletsService,
+    WalletType,
+)
+from .services.withdrawals import Withdrawal, WithdrawalHistoryResponse, WithdrawalsService
+from .sign import canonical_json, sign, sign_value
+from .ton import (
+    TonAddress,
+    crc16_xmodem,
+    parse_ton_address,
+    ton_address_to_raw,
+    ton_address_to_string,
+)
+from .webhook import (
+    WEBHOOK_HEADER,
+    WEBHOOK_SENDER_IPS,
+    PayInWebhookEvent,
+    PayoutWebhookEvent,
+    StaticDepositWebhookEvent,
+    TransactionWebhookEvent,
+    WebhookSignatureError,
+    coerce_webhook_event,
+    parse_webhook_event,
+    verify_webhook_signature,
+)
+
+__all__ = [
+    "__version__",
+    # Client
+    "CryptoChiefClient",
+    "VERSION",
+    "DEFAULT_BASE_URL",
+    # Errors
+    "CryptoChiefError",
+    "APIError",
+    "ErrorCode",
+    "is_api_error",
+    "is_retryable",
+    # Signing
+    "canonical_json",
+    "sign",
+    "sign_value",
+    # Amounts
+    "human_to_base",
+    "base_to_human",
+    "nano_ton",
+    "InvalidAmountError",
+    # Chains / assets / pagination
+    "Chain",
+    "ChainFamily",
+    "chain_family",
+    "supports_contract_calls",
+    "Asset",
+    "AssetsPolicy",
+    "HistoryQuery",
+    "HistoryMeta",
+    # Polling
+    "wait_for_terminal",
+    "PollTimeoutError",
+    # RSA
+    "load_rsa_private_key_pem",
+    "load_rsa_private_key_file",
+    "decrypt_rsa_oaep",
+    "RsaKeyNotConfiguredError",
+    # Webhooks
+    "verify_webhook_signature",
+    "parse_webhook_event",
+    "coerce_webhook_event",
+    "WebhookSignatureError",
+    "WEBHOOK_HEADER",
+    "WEBHOOK_SENDER_IPS",
+    "PayoutWebhookEvent",
+    "TransactionWebhookEvent",
+    "PayInWebhookEvent",
+    "StaticDepositWebhookEvent",
+    # Services
+    "PayoutsService",
+    "TransactionsService",
+    "PayInsService",
+    "WalletsService",
+    "SweepsService",
+    "WithdrawalsService",
+    "StaticDepositsService",
+    "BlockchainService",
+    "CurrenciesService",
+    # Payout types
+    "EstimatePayoutRequest",
+    "ExecutePayoutRequest",
+    "EstimatePayoutResponse",
+    "PayoutInfo",
+    "PayoutFeeInfo",
+    "PayoutSource",
+    "PayoutHistoryResponse",
+    "BatchPayoutRequest",
+    "BatchPayoutResponse",
+    "BatchItemResult",
+    "PayoutStatus",
+    "is_payout_terminal",
+    # Transaction types
+    "SignTransactionRequest",
+    "SignTransactionResponse",
+    "ExecuteTransactionRequest",
+    "TransactionInfo",
+    "TransactionHistoryResponse",
+    "ContractCall",
+    "SolanaAccount",
+    "EvmCallRequest",
+    "Erc20TransferRequest",
+    "AnchorCallRequest",
+    "SolanaCallRequest",
+    "TonCallRequest",
+    "JettonTransferRequest",
+    "NftTransferRequest",
+    "TonCommentRequest",
+    "TxType",
+    "TxStatus",
+    "is_transaction_terminal",
+    # Pay-in types
+    "CreatePayInRequest",
+    "SelectAssetRequest",
+    "PayIn",
+    "CoinOption",
+    "PayInHistoryResponse",
+    "PayInMode",
+    "PayInStatus",
+    "is_payin_terminal",
+    # Wallet types
+    "GenerateWalletRequest",
+    "Wallet",
+    "WalletCoinBalance",
+    "ListWalletsResponse",
+    "WalletType",
+    # Sweep types
+    "Sweep",
+    "SweepHistoryQuery",
+    "SweepHistoryResponse",
+    "ForceSweepResponse",
+    "SweepMode",
+    # Withdrawal types
+    "Withdrawal",
+    "WithdrawalHistoryResponse",
+    # Static deposit types
+    "StaticDeposit",
+    "StaticDepositHistoryQuery",
+    "StaticDepositHistoryResponse",
+    "StaticDepositStatus",
+    # Blockchain types
+    "AvailableContract",
+    "AvailableContractsResponse",
+    "WalletBalanceRow",
+    "TxStatusRow",
+    # Currency types
+    "ConvertRequest",
+    "ConvertResponse",
+    # Contract encoders
+    "encode_evm_call",
+    "encode_evm_call_hex",
+    "evm_selector",
+    "canonical_signature",
+    "keccak_256",
+    "BorshValue",
+    "borsh_u8",
+    "borsh_u16",
+    "borsh_u32",
+    "borsh_u64",
+    "borsh_i8",
+    "borsh_i16",
+    "borsh_i32",
+    "borsh_i64",
+    "borsh_u128",
+    "borsh_bool",
+    "borsh_string",
+    "borsh_bytes",
+    "borsh_fixed_bytes",
+    "borsh_pubkey",
+    "borsh_option",
+    "borsh_vec",
+    "borsh_struct",
+    "anchor_discriminator",
+    "encode_anchor_instruction",
+    "decode_solana_pubkey",
+    "tron_to_hex",
+    "hex_to_tron",
+    "base58_encode",
+    "base58_decode",
+    # TON address utilities (offline)
+    "parse_ton_address",
+    "ton_address_to_string",
+    "ton_address_to_raw",
+    "crc16_xmodem",
+    "TonAddress",
+]

cryptochief/_models.py

@@ -0,0 +1,93 @@
+"""Dataclass <-> wire helpers.
+
+The public API is modeled with dataclasses whose field names already match the
+snake_case wire format, so there is no case conversion to do - requests serialize
+straight to the body and responses parse straight back.
+
+:func:`to_payload` turns a request (dataclass / dict / list / enum / scalar) into
+a JSON-ready value, dropping ``None`` fields. :func:`from_dict` builds a typed
+dataclass from a response dict, recursing into nested dataclass and list fields
+and tolerating unknown keys (forward-compatible with new server fields).
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+from typing import Any, Mapping, Optional, Type, TypeVar, Union, get_args, get_origin, get_type_hints
+
+T = TypeVar("T")
+
+_hints_cache: dict[type, dict[str, Any]] = {}
+
+
+def _type_hints(cls: type) -> dict[str, Any]:
+    cached = _hints_cache.get(cls)
+    if cached is None:
+        cached = get_type_hints(cls)
+        _hints_cache[cls] = cached
+    return cached
+
+
+def to_payload(value: Any) -> Any:
+    """Recursively convert a request value to a JSON-ready form, dropping ``None``."""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, enum.Enum):
+        return value.value
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        out: dict[str, Any] = {}
+        for f in dataclasses.fields(value):
+            v = getattr(value, f.name)
+            if v is None:
+                continue
+            out[f.name] = to_payload(v)
+        return out
+    if isinstance(value, dict):
+        return {k: to_payload(v) for k, v in value.items() if v is not None}
+    if isinstance(value, (list, tuple)):
+        return [to_payload(v) for v in value]
+    return value
+
+
+def _unwrap_optional(tp: Any) -> Any:
+    if get_origin(tp) is Union:
+        args = [a for a in get_args(tp) if a is not type(None)]
+        if len(args) == 1:
+            return args[0]
+        return args[0] if args else Any
+    return tp
+
+
+def _coerce(tp: Any, value: Any) -> Any:
+    if value is None:
+        return None
+    tp = _unwrap_optional(tp)
+    origin = get_origin(tp)
+    if origin in (list, tuple):
+        args = get_args(tp)
+        elem = args[0] if args else Any
+        return [_coerce(elem, v) for v in value]
+    if isinstance(tp, type) and dataclasses.is_dataclass(tp):
+        return from_dict(tp, value)
+    return value
+
+
+def from_dict(cls: Type[T], data: Optional[Mapping[str, Any]]) -> T:
+    """Build a dataclass of type ``cls`` from a response mapping.
+
+    Recurses into nested dataclass / list fields and ignores keys the dataclass
+    does not declare (forward-compatible with new server fields). A ``None`` or
+    empty body yields an all-defaults instance - every response model is
+    constructible with no arguments.
+    """
+    if not isinstance(data, Mapping):
+        data = {}
+    hints = _type_hints(cls)
+    kwargs: dict[str, Any] = {}
+    for f in dataclasses.fields(cls):  # type: ignore[arg-type]  # cls is a dataclass type
+        if f.name in data:
+            kwargs[f.name] = _coerce(hints.get(f.name, Any), data[f.name])
+    return cls(**kwargs)

cryptochief/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version."""
+
+__version__ = "0.1.0"

cryptochief/amount.py

@@ -0,0 +1,97 @@
+"""Amount conversion helpers backed by Python's arbitrary-precision ``int``.
+
+**Never use ``float`` for crypto amounts**: ``0.1 + 0.2 != 0.3`` and large token
+values lose precision. These helpers parse decimal strings exactly and return
+``int`` base units.
+"""
+
+from __future__ import annotations
+
+from .errors import CryptoChiefError
+
+
+class InvalidAmountError(CryptoChiefError):
+    """Raised by :func:`human_to_base` when its input is not a plain decimal."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(f"cryptochief: invalid amount: {message}")
+
+
+def _is_ascii_digits(s: str) -> bool:
+    return len(s) > 0 and all("0" <= c <= "9" for c in s)
+
+
+def human_to_base(human: str, decimals: int) -> int:
+    """Convert a decimal human amount (e.g. ``"0.0001"``) to its base-unit ``int``.
+
+    Precise to the last digit. Negative amounts and scientific notation are
+    rejected. Sub-base-unit precision is truncated, since it is meaningless
+    on-chain.
+
+    >>> human_to_base("1.5", 18)
+    1500000000000000000
+    >>> human_to_base("0.0001", 8)
+    10000
+    """
+    s = human.strip()
+    if s == "":
+        raise InvalidAmountError("empty")
+    if not isinstance(decimals, int) or isinstance(decimals, bool) or decimals < 0:
+        raise InvalidAmountError(f"negative or non-integer decimals {decimals!r}")
+    if "e" in s or "E" in s:
+        raise InvalidAmountError(f"scientific notation not allowed: {human!r}")
+    if s.startswith("-"):
+        raise InvalidAmountError(f"negative not allowed: {human!r}")
+
+    dot = s.find(".")
+    if dot < 0:
+        if not _is_ascii_digits(s):
+            raise InvalidAmountError(repr(human))
+        int_part, frac_part = s, ""
+    else:
+        int_part = s[:dot] or "0"
+        frac_part = s[dot + 1 :]
+        if frac_part == "":
+            raise InvalidAmountError(repr(human))
+        if not _is_ascii_digits(int_part) or not _is_ascii_digits(frac_part):
+            raise InvalidAmountError(repr(human))
+
+    if len(frac_part) > decimals:
+        frac_part = frac_part[:decimals]
+    else:
+        frac_part = frac_part.ljust(decimals, "0")
+
+    combined = (int_part + frac_part).lstrip("0") or "0"
+    return int(combined)
+
+
+def base_to_human(base: int, decimals: int) -> str:
+    """Inverse of :func:`human_to_base`: a base-unit ``int`` to a decimal string.
+
+    Trailing zeroes are trimmed.
+
+    >>> base_to_human(1500000000000000000, 18)
+    '1.5'
+    >>> base_to_human(0, 18)
+    '0'
+    """
+    if decimals < 0:
+        decimals = 0
+    abs_s = str(-base if base < 0 else base)
+    if decimals == 0:
+        return abs_s
+    if len(abs_s) <= decimals:
+        abs_s = "0" * (decimals - len(abs_s) + 1) + abs_s
+    cut = len(abs_s) - decimals
+    int_part = abs_s[:cut]
+    frac_part = abs_s[cut:].rstrip("0")
+    return int_part if frac_part == "" else f"{int_part}.{frac_part}"
+
+
+def nano_ton(human: str) -> int:
+    """Convert a human TON amount (``"0.05"``) into base-unit nanoTON (``50000000``).
+
+    Equivalent to ``human_to_base(human, 9)`` - the form the TON helpers'
+    ``attached_ton`` / ``forward_ton_amount`` fields expect.
+    """
+    return human_to_base(human, 9)

cryptochief/assets.py

@@ -0,0 +1,32 @@
+"""Asset selection policies used by payouts and FIAT-mode pay-ins."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass(kw_only=True)
+class Asset:
+    """A specific coin on a specific network.
+
+    ``network`` takes a chain code (e.g. ``Chain.ETH_MAINNET``) or the wildcard
+    ``"ANY"``; ``coin`` is the symbol (e.g. ``"USDT"``). Either field may be
+    omitted to mean "any".
+    """
+
+    network: Optional[str] = None
+    coin: Optional[str] = None
+
+
+@dataclass(kw_only=True)
+class AssetsPolicy:
+    """An allow / exclude filter over :class:`Asset` entries.
+
+    Omitting both lists means "no restriction". Used for payout auto-convert
+    source selection and to restrict which coins a FIAT-mode pay-in customer may
+    pick.
+    """
+
+    allow: Optional[List[Asset]] = None
+    exclude: Optional[List[Asset]] = None

cryptochief/chains.py

@@ -0,0 +1,115 @@
+"""Chain codes and protocol families.
+
+:class:`Chain` is the value of the ``network`` / ``chain`` / ``network_code``
+fields across the API; :class:`ChainFamily` (the ``chain_family`` field) groups
+chains by underlying protocol and drives capability checks such as "does this
+chain accept contract calls?".
+
+Both are ``str`` enums: a member compares equal to its wire string, and any
+plain string is accepted wherever a chain is expected, so new chains work before
+this SDK is updated.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+
+class Chain(str, Enum):
+    """Chain codes the API currently supports."""
+
+    ETH_MAINNET = "ETH_MAINNET"
+    ETH_SEPOLIA = "ETH_SEPOLIA"
+    BSC_MAINNET = "BSC_MAINNET"
+    BSC_TESTNET = "BSC_TESTNET"
+    POLYGON_MAINNET = "POLYGON_MAINNET"
+    POLYGON_AMOY = "POLYGON_AMOY"
+    ARBITRUM_ONE = "ARBITRUM_ONE"
+    ARBITRUM_SEPOLIA = "ARBITRUM_SEPOLIA"
+    OPTIMISM_MAINNET = "OPTIMISM_MAINNET"
+    OPTIMISM_SEPOLIA = "OPTIMISM_SEPOLIA"
+    AVAX_MAINNET = "AVAX_MAINNET"
+    AVAX_TESTNET = "AVAX_TESTNET"
+
+    BTC_MAINNET = "BTC_MAINNET"
+    BTC_TESTNET_4 = "BTC_TESTNET_4"
+    LITECOIN_MAINNET = "LITECOIN_MAINNET"
+    BITCOIN_CASH_MAINNET = "BITCOIN_CASH_MAINNET"
+    DOGECOIN_MAINNET = "DOGECOIN_MAINNET"
+
+    TRON_MAINNET = "TRON_MAINNET"
+    TRON_NILE = "TRON_NILE"
+
+    SOLANA_MAINNET = "SOLANA_MAINNET"
+    SOLANA_DEVNET = "SOLANA_DEVNET"
+
+    TON_MAINNET = "TON_MAINNET"
+    TON_TESTNET = "TON_TESTNET"
+
+    XRP_MAINNET = "XRP_MAINNET"
+    XRP_TESTNET = "XRP_TESTNET"
+
+
+class ChainFamily(str, Enum):
+    """Protocol families (the ``chain_family`` field in API responses)."""
+
+    EVM = "EVM"
+    TRON = "TRON"
+    SOLANA = "SOLANA"
+    XRP_LEDGER = "XRP_LEDGER"
+    TON = "TON"
+    BTC_UTXO = "BTC_UTXO"
+    BTC_UTXO_TESTNET = "BTC_UTXO_TESTNET"
+    DOGECOIN_UTXO = "DOGECOIN_UTXO"
+    BTC_CASH_UTXO = "BTC_CASH_UTXO"
+    LITECOIN_UTXO = "LITECOIN_UTXO"
+
+
+_CHAIN_TO_FAMILY = {
+    Chain.ETH_MAINNET: ChainFamily.EVM,
+    Chain.ETH_SEPOLIA: ChainFamily.EVM,
+    Chain.BSC_MAINNET: ChainFamily.EVM,
+    Chain.BSC_TESTNET: ChainFamily.EVM,
+    Chain.POLYGON_MAINNET: ChainFamily.EVM,
+    Chain.POLYGON_AMOY: ChainFamily.EVM,
+    Chain.ARBITRUM_ONE: ChainFamily.EVM,
+    Chain.ARBITRUM_SEPOLIA: ChainFamily.EVM,
+    Chain.OPTIMISM_MAINNET: ChainFamily.EVM,
+    Chain.OPTIMISM_SEPOLIA: ChainFamily.EVM,
+    Chain.AVAX_MAINNET: ChainFamily.EVM,
+    Chain.AVAX_TESTNET: ChainFamily.EVM,
+    Chain.BTC_MAINNET: ChainFamily.BTC_UTXO,
+    Chain.BTC_TESTNET_4: ChainFamily.BTC_UTXO_TESTNET,
+    Chain.LITECOIN_MAINNET: ChainFamily.LITECOIN_UTXO,
+    Chain.BITCOIN_CASH_MAINNET: ChainFamily.BTC_CASH_UTXO,
+    Chain.DOGECOIN_MAINNET: ChainFamily.DOGECOIN_UTXO,
+    Chain.TRON_MAINNET: ChainFamily.TRON,
+    Chain.TRON_NILE: ChainFamily.TRON,
+    Chain.SOLANA_MAINNET: ChainFamily.SOLANA,
+    Chain.SOLANA_DEVNET: ChainFamily.SOLANA,
+    Chain.TON_MAINNET: ChainFamily.TON,
+    Chain.TON_TESTNET: ChainFamily.TON,
+    Chain.XRP_MAINNET: ChainFamily.XRP_LEDGER,
+    Chain.XRP_TESTNET: ChainFamily.XRP_LEDGER,
+}
+# Allow plain-string lookups too (e.g. the value off a response).
+_CHAIN_TO_FAMILY_STR = {k.value: v for k, v in _CHAIN_TO_FAMILY.items()}
+
+
+def chain_family(chain: str) -> Optional[ChainFamily]:
+    """Return the protocol family for a chain, or ``None`` if unrecognized."""
+    return _CHAIN_TO_FAMILY_STR.get(str(chain))
+
+
+def supports_contract_calls(family: str) -> bool:
+    """Whether a chain family accepts the ``contract`` transaction type.
+
+    Only EVM, TRON, Solana, and TON do.
+    """
+    return family in (
+        ChainFamily.EVM,
+        ChainFamily.TRON,
+        ChainFamily.SOLANA,
+        ChainFamily.TON,
+    )