qorechain-sdk 0.3.0__py3-none-any.whl

qorechain/__init__.py

@@ -0,0 +1,239 @@
+"""QoreChain Python SDK.
+
+A typed, pip-installable mirror of the QoreChain TypeScript SDK: network presets,
+denom/address utilities, HD account derivation (native / EVM / SVM), post-quantum
+(ML-DSA-87) signing primitives, and read clients (REST + ``qor_`` JSON-RPC).
+"""
+
+from __future__ import annotations
+
+from .accounts import (
+    Ed25519Account,
+    Secp256k1Account,
+    derive_evm_account,
+    derive_native_account,
+    derive_svm_account,
+    generate_mnemonic,
+    validate_mnemonic,
+)
+from .address import (
+    bech32_to_hex,
+    bytes_to_bech32,
+    hex_to_bech32,
+    is_valid_bech32,
+)
+from .client import QoreChainClient, create_client
+from .denom import from_base, to_base
+from .errors import (
+    DecodedTxError,
+    QoreTxError,
+    decode_tx_error,
+    is_tx_failure,
+    tx_error_from,
+)
+from .fees import estimate_fee
+from .gas import (
+    DEFAULT_GAS_MULTIPLIER,
+    DEFAULT_GAS_PRICE,
+    GasPrice,
+    auto_fee,
+    calculate_fee,
+    estimate_gas,
+    simulate_gas_used,
+)
+from .jsonrpc import AsyncJsonRpcClient, JsonRpcClient, JsonRpcError
+from .messages import (
+    COSMOS_REGISTRY_TYPES,
+    QORECHAIN_REGISTRY_TYPES,
+    Msg,
+    composer,
+    decode_any,
+    msg,
+    qorechain_registry,
+    resolve_message_type,
+)
+from .networks import (
+    NETWORKS,
+    Bech32Prefixes,
+    CoinInfo,
+    NetworkConfig,
+    NetworkEndpoints,
+    get_network,
+    list_networks,
+)
+from .pqc import (
+    ALGORITHM_DILITHIUM5,
+    ALGORITHM_MLKEM1024,
+    ALGORITHM_UNSPECIFIED,
+    HYBRID_SIG_TYPE_URL,
+    ML_DSA_87_PUBLIC_KEY_LENGTH,
+    ML_DSA_87_SECRET_KEY_LENGTH,
+    ML_DSA_87_SIGNATURE_LENGTH,
+    PqcKeypair,
+    algorithm_name,
+    build_hybrid_signature_extension,
+    generate_pqc_keypair,
+    is_signature_algorithm,
+    pqc_sign,
+    pqc_verify,
+)
+from .qor import QOR_METHODS, AsyncQorClient, QorClient
+from .query import QueryClients, connect_query_clients
+from .rest import AsyncRestClient, QoreHttpError, RestClient
+from .search import (
+    build_events_query,
+    get_block,
+    get_latest_block,
+    get_tx,
+    search_txs,
+)
+from .subscribe import SubscriptionClient, build_tx_query
+from .track import (
+    IncludedTx,
+    broadcast_and_wait,
+    wait_for_tx,
+    with_retry,
+)
+from .tx import (
+    MSG_SEND_TYPE_URL,
+    BroadcastMode,
+    BuiltTx,
+    bank_send,
+    broadcast,
+    build_hybrid_tx,
+    send_messages,
+)
+from .utils import (
+    format_units,
+    is_checksum_address,
+    is_valid_evm_address,
+    is_valid_svm_address,
+    keccak256,
+    keccak256_hex,
+    parse_units,
+    ripemd160,
+    ripemd160_hex,
+    sha256,
+    sha256_hex,
+    to_checksum_address,
+)
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "__version__",
+    # networks
+    "NETWORKS",
+    "Bech32Prefixes",
+    "CoinInfo",
+    "NetworkConfig",
+    "NetworkEndpoints",
+    "get_network",
+    "list_networks",
+    # denom
+    "to_base",
+    "from_base",
+    # address
+    "bech32_to_hex",
+    "hex_to_bech32",
+    "bytes_to_bech32",
+    "is_valid_bech32",
+    # accounts
+    "Secp256k1Account",
+    "Ed25519Account",
+    "generate_mnemonic",
+    "validate_mnemonic",
+    "derive_native_account",
+    "derive_evm_account",
+    "derive_svm_account",
+    # pqc
+    "ALGORITHM_UNSPECIFIED",
+    "ALGORITHM_DILITHIUM5",
+    "ALGORITHM_MLKEM1024",
+    "HYBRID_SIG_TYPE_URL",
+    "ML_DSA_87_PUBLIC_KEY_LENGTH",
+    "ML_DSA_87_SECRET_KEY_LENGTH",
+    "ML_DSA_87_SIGNATURE_LENGTH",
+    "PqcKeypair",
+    "algorithm_name",
+    "is_signature_algorithm",
+    "generate_pqc_keypair",
+    "pqc_sign",
+    "pqc_verify",
+    "build_hybrid_signature_extension",
+    # query
+    "RestClient",
+    "AsyncRestClient",
+    "QoreHttpError",
+    "JsonRpcClient",
+    "AsyncJsonRpcClient",
+    "JsonRpcError",
+    "QorClient",
+    "AsyncQorClient",
+    "QOR_METHODS",
+    "estimate_fee",
+    # tx
+    "MSG_SEND_TYPE_URL",
+    "BroadcastMode",
+    "BuiltTx",
+    "bank_send",
+    "send_messages",
+    "build_hybrid_tx",
+    "broadcast",
+    # messages
+    "Msg",
+    "composer",
+    "msg",
+    "qorechain_registry",
+    "resolve_message_type",
+    "decode_any",
+    "QORECHAIN_REGISTRY_TYPES",
+    "COSMOS_REGISTRY_TYPES",
+    # typed query clients
+    "QueryClients",
+    "connect_query_clients",
+    # gas / auto-fee
+    "GasPrice",
+    "calculate_fee",
+    "estimate_gas",
+    "simulate_gas_used",
+    "auto_fee",
+    "DEFAULT_GAS_MULTIPLIER",
+    "DEFAULT_GAS_PRICE",
+    # errors
+    "DecodedTxError",
+    "QoreTxError",
+    "decode_tx_error",
+    "is_tx_failure",
+    "tx_error_from",
+    # tx tracking
+    "IncludedTx",
+    "wait_for_tx",
+    "broadcast_and_wait",
+    "with_retry",
+    # search
+    "get_tx",
+    "get_block",
+    "get_latest_block",
+    "search_txs",
+    "build_events_query",
+    # subscriptions
+    "SubscriptionClient",
+    "build_tx_query",
+    # utils
+    "sha256",
+    "sha256_hex",
+    "keccak256",
+    "keccak256_hex",
+    "ripemd160",
+    "ripemd160_hex",
+    "parse_units",
+    "format_units",
+    "is_valid_evm_address",
+    "to_checksum_address",
+    "is_checksum_address",
+    "is_valid_svm_address",
+    # client
+    "QoreChainClient",
+    "create_client",
+]

qorechain/accounts.py

@@ -0,0 +1,173 @@
+"""Mnemonic generation/validation and hierarchical-deterministic (HD) derivation
+of QoreChain accounts in all three supported schemes:
+
+1. native — Cosmos-style secp256k1, BIP-44 path ``m/44'/118'/0'/0/{index}``,
+   address = bech32(``qor``, ripemd160(sha256(compressed_pubkey))).
+2. evm    — secp256k1, BIP-44 path ``m/44'/60'/0'/0/{index}``,
+   address = ``0x`` + last 20 bytes of keccak256(uncompressed_pubkey[1:]),
+   rendered with an EIP-55 mixed-case checksum.
+3. svm    — ed25519, SLIP-0010 path ``m/44'/501'/{index}'/0'`` (all hardened,
+   the Solana standard), address = base58(32-byte ed25519 public key).
+
+Derivation uses the audited ``bip-utils`` library (BIP-39 mnemonic + seed,
+BIP-44/SLIP-0010 HD for secp256k1 and ed25519, and the address schemes). Secret
+material is returned explicitly from the derive functions and is never logged.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+
+import base58
+from bip_utils import (
+    Bip32Slip10Ed25519,
+    Bip32Slip10Secp256k1,
+    Bip39MnemonicGenerator,
+    Bip39MnemonicValidator,
+    Bip39SeedGenerator,
+    Bip39WordsNum,
+    EthAddrEncoder,
+)
+from bip_utils.bech32 import Bech32Encoder
+
+#: Bech32 human-readable prefix for native QoreChain account addresses.
+NATIVE_PREFIX = "qor"
+
+# Coin types per SLIP-0044.
+_COIN_TYPE_NATIVE = 118  # Cosmos
+_COIN_TYPE_EVM = 60  # Ethereum
+_COIN_TYPE_SVM = 501  # Solana
+
+_STRENGTH_TO_WORDS = {
+    128: Bip39WordsNum.WORDS_NUM_12,
+    256: Bip39WordsNum.WORDS_NUM_24,
+}
+
+
+@dataclass(frozen=True)
+class Secp256k1Account:
+    """A secp256k1-based account (native or EVM). Treat ``private_key`` secret."""
+
+    type: str
+    address: str
+    public_key: bytes
+    private_key: bytes
+
+
+@dataclass(frozen=True)
+class Ed25519Account:
+    """An ed25519-based (SVM/Solana) account. Treat ``secret_key`` as secret."""
+
+    type: str
+    address: str
+    public_key: bytes
+    #: 64-byte Solana-style secret key (``private_seed32 || public_key32``).
+    secret_key: bytes
+
+
+def generate_mnemonic(strength: int = 128) -> str:
+    """Generate a fresh BIP-39 mnemonic.
+
+    :param strength: Entropy in bits: ``128`` -> 12 words (default),
+        ``256`` -> 24 words.
+    :returns: A space-separated English mnemonic phrase.
+    """
+    words_num = _STRENGTH_TO_WORDS.get(strength)
+    if words_num is None:
+        raise ValueError(f"unsupported strength: {strength} (use 128 or 256)")
+    return str(Bip39MnemonicGenerator().FromWordsNumber(words_num).ToStr())
+
+
+def validate_mnemonic(mnemonic: str) -> bool:
+    """Validate a BIP-39 mnemonic against the English wordlist and checksum.
+
+    :returns: ``True`` if valid; ``False`` otherwise. Never raises.
+    """
+    return bool(Bip39MnemonicValidator().IsValid(mnemonic))
+
+
+def _resolve_index(account_index: int) -> int:
+    if not isinstance(account_index, int) or isinstance(account_index, bool) or account_index < 0:
+        raise ValueError(
+            f"account_index must be a non-negative integer, got {account_index}"
+        )
+    return account_index
+
+
+def _seed_from_mnemonic(mnemonic: str) -> bytes:
+    """Validate a mnemonic and derive its BIP-39 seed.
+
+    Centralizing this here guards against the fund-loss footgun where a typo'd
+    phrase (valid words, wrong checksum) would silently derive a valid-looking
+    but WRONG account. The error deliberately omits the mnemonic text.
+    """
+    if not validate_mnemonic(mnemonic):
+        raise ValueError("invalid mnemonic")
+    return bytes(Bip39SeedGenerator(mnemonic).Generate())
+
+
+def derive_native_account(mnemonic: str, account_index: int = 0) -> Secp256k1Account:
+    """Derive a native QoreChain account (Cosmos-style secp256k1).
+
+    Path: ``m/44'/118'/0'/0/{account_index}``. The address is the bech32
+    (``qor``) encoding of ``ripemd160(sha256(compressed_public_key))``.
+    """
+    index = _resolve_index(account_index)
+    seed = _seed_from_mnemonic(mnemonic)
+    node = Bip32Slip10Secp256k1.FromSeed(seed).DerivePath(
+        f"44'/{_COIN_TYPE_NATIVE}'/0'/0/{index}"
+    )
+    compressed = bytes(node.PublicKey().RawCompressed().ToBytes())
+    digest = hashlib.new("ripemd160", hashlib.sha256(compressed).digest()).digest()
+    address = str(Bech32Encoder.Encode(NATIVE_PREFIX, digest))
+    private_key = bytes(node.PrivateKey().Raw().ToBytes())
+    return Secp256k1Account(
+        type="native", address=address, public_key=compressed, private_key=private_key
+    )
+
+
+def derive_evm_account(mnemonic: str, account_index: int = 0) -> Secp256k1Account:
+    """Derive an EVM account from a mnemonic.
+
+    Path: ``m/44'/60'/0'/0/{account_index}``. The address is the last 20 bytes
+    of ``keccak256(uncompressed_public_key[1:])``, EIP-55 checksummed.
+    """
+    index = _resolve_index(account_index)
+    seed = _seed_from_mnemonic(mnemonic)
+    node = Bip32Slip10Secp256k1.FromSeed(seed).DerivePath(
+        f"44'/{_COIN_TYPE_EVM}'/0'/0/{index}"
+    )
+    pub = node.PublicKey()
+    compressed = bytes(pub.RawCompressed().ToBytes())
+    # EthAddrEncoder applies keccak256(uncompressed[1:])[-20:] with EIP-55.
+    address = str(EthAddrEncoder.EncodeKey(pub.KeyObject()))
+    private_key = bytes(node.PrivateKey().Raw().ToBytes())
+    return Secp256k1Account(
+        type="evm", address=address, public_key=compressed, private_key=private_key
+    )
+
+
+def derive_svm_account(mnemonic: str, account_index: int = 0) -> Ed25519Account:
+    """Derive an SVM (Solana-style ed25519) account from a mnemonic.
+
+    Path: ``m/44'/501'/{account_index}'/0'`` — the conventional Solana
+    derivation, all segments hardened (SLIP-0010 for ed25519 supports hardened
+    keys only). The address is the base58 encoding of the 32-byte public key.
+    The returned ``secret_key`` is the 64-byte Solana form
+    (``private_seed32 || public_key32``).
+    """
+    index = _resolve_index(account_index)
+    seed = _seed_from_mnemonic(mnemonic)
+    node = Bip32Slip10Ed25519.FromSeed(seed).DerivePath(
+        f"44'/{_COIN_TYPE_SVM}'/{index}'/0'"
+    )
+    # bip-utils prepends a 0x00 prefix byte to raw ed25519 public keys.
+    raw_pub = bytes(node.PublicKey().RawCompressed().ToBytes())
+    public_key = raw_pub[1:] if len(raw_pub) == 33 else raw_pub
+    private_seed = bytes(node.PrivateKey().Raw().ToBytes())
+    secret_key = private_seed + public_key
+    address = base58.b58encode(public_key).decode("ascii")
+    return Ed25519Account(
+        type="svm", address=address, public_key=public_key, secret_key=secret_key
+    )

qorechain/address.py

@@ -0,0 +1,79 @@
+"""Conversion and validation for QoreChain bech32 addresses (e.g. ``qor1...``)
+and their underlying byte payloads expressed as ``0x``-prefixed hex.
+
+bech32 stores data as 5-bit groups ("words"), so encoding/decoding converts
+between those groups and the 8-bit byte representation callers work with.
+"""
+
+from __future__ import annotations
+
+import re
+
+from bech32 import bech32_decode, bech32_encode, convertbits
+
+#: Default bech32 human-readable prefix for QoreChain account addresses.
+DEFAULT_PREFIX = "qor"
+
+_HEX_RE = re.compile(r"^[0-9a-fA-F]+$")
+
+
+def _strip_hex_prefix(hex_str: str) -> str:
+    return hex_str[2:] if hex_str[:2] in ("0x", "0X") else hex_str
+
+
+def _hex_to_bytes(hex_str: str) -> bytes:
+    body = _strip_hex_prefix(hex_str)
+    if not body or len(body) % 2 != 0 or not _HEX_RE.match(body):
+        raise ValueError(f"invalid hex string: {hex_str}")
+    return bytes.fromhex(body)
+
+
+def bytes_to_bech32(data: bytes, prefix: str = DEFAULT_PREFIX) -> str:
+    """Encode raw bytes to a bech32 address with the given prefix.
+
+    This is the primitive encoder; callers holding a ``bytes`` payload (e.g. the
+    20-byte ``ripemd160(sha256(pubkey))`` account hash) should use it directly
+    rather than round-tripping through hex.
+    """
+    words = convertbits(data, 8, 5, pad=True)
+    if words is None:
+        raise ValueError("failed to convert bytes to bech32 words")
+    encoded = bech32_encode(prefix, words)
+    if encoded is None:
+        raise ValueError("failed to encode bech32 address")
+    return encoded
+
+
+def hex_to_bech32(hex_str: str, prefix: str = DEFAULT_PREFIX) -> str:
+    """Encode hex bytes to a bech32 address with the given prefix.
+
+    :raises ValueError: If ``hex_str`` is not a valid hex string.
+    """
+    return bytes_to_bech32(_hex_to_bytes(hex_str), prefix)
+
+
+def bech32_to_hex(addr: str) -> str:
+    """Decode a bech32 address to a ``0x``-prefixed hex string of its payload.
+
+    :raises ValueError: If ``addr`` is not a valid bech32 string.
+    """
+    _hrp, words = bech32_decode(addr)
+    if words is None:
+        raise ValueError(f"invalid bech32 address: {addr}")
+    data = convertbits(words, 5, 8, pad=False)
+    if data is None:
+        raise ValueError(f"invalid bech32 payload: {addr}")
+    return "0x" + bytes(data).hex()
+
+
+def is_valid_bech32(addr: str, prefix: str | None = None) -> bool:
+    """Validate a bech32 address, optionally requiring a specific prefix.
+
+    :returns: ``True`` if ``addr`` is a structurally valid bech32 string
+        (correct checksum) and, when ``prefix`` is supplied, its prefix matches;
+        ``False`` otherwise. Never raises.
+    """
+    hrp, words = bech32_decode(addr)
+    if hrp is None or words is None:
+        return False
+    return True if prefix is None else hrp == prefix

qorechain/client.py

@@ -0,0 +1,115 @@
+"""Top-level ``create_client`` factory for the QoreChain Python SDK.
+
+:func:`create_client` resolves a :class:`~qorechain.networks.NetworkConfig`
+(applying any endpoint overrides) and composes the read clients
+(:class:`~qorechain.rest.RestClient` and the ``qor_`` :class:`~qorechain.qor.QorClient`)
+plus a fee-estimate convenience.
+
+Network resolution rules:
+  - The default network is ``testnet``. Both ``testnet`` and ``mainnet`` are live
+    and ship localhost endpoint defaults; callers can override them with real
+    hostnames.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any
+
+from .fees import estimate_fee
+from .networks import NETWORKS, NetworkConfig, NetworkEndpoints
+from .qor import QorClient
+from .rest import FeeUrgency, RestClient
+
+_ENDPOINT_KEYS = ("rest", "grpc", "rpc", "evm_rpc", "evm_ws", "svm_rpc")
+
+
+class _Fees:
+    """Fee-estimate convenience surface bound to a :class:`RestClient`."""
+
+    def __init__(self, rest: RestClient) -> None:
+        self._rest = rest
+
+    def estimate(self, urgency: FeeUrgency = "normal") -> dict[str, Any]:
+        """Estimate a fee for the given urgency via the AI fee oracle.
+
+        Falls back to a deterministic static fee when the oracle is unavailable.
+        Returns a Cosmos ``StdFee``-shaped dict: ``{"amount": [...], "gas": ...}``.
+        """
+        return estimate_fee(self._rest, urgency=urgency)
+
+
+@dataclass
+class QoreChainClient:
+    """A composed QoreChain client: resolved config, read clients, fee helper."""
+
+    network: NetworkConfig
+    rest: RestClient
+    qor: QorClient
+    fees: _Fees
+
+    def close(self) -> None:
+        self.rest.close()
+        self.qor.close()
+
+    def __enter__(self) -> QoreChainClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+def _resolve_network(
+    network: str, endpoints: dict[str, str] | None, chain_id: str | None
+) -> NetworkConfig:
+    overrides = endpoints or {}
+    bad = set(overrides) - set(_ENDPOINT_KEYS)
+    if bad:
+        raise ValueError(f"unknown endpoint keys: {sorted(bad)}")
+
+    base = NETWORKS.get(network)
+    if base is None:
+        raise ValueError(f"unknown network: {network}")
+
+    # Live preset (testnet or mainnet): overlay endpoint overrides onto the defaults.
+    current = {k: getattr(base.endpoints, k) for k in _ENDPOINT_KEYS}
+    current.update(overrides)
+    return replace(
+        base,
+        chain_id=chain_id or base.chain_id,
+        endpoints=NetworkEndpoints(**current),
+    )
+
+
+def _require_endpoint(network: NetworkConfig, key: str) -> str:
+    value: str | None = getattr(network.endpoints, key, None) if network.endpoints else None
+    if not value:
+        raise ValueError(
+            f'endpoint "{key}" is not configured — pass it via '
+            f"create_client(endpoints={{'{key}': '...'}})"
+        )
+    return value
+
+
+def create_client(
+    network: str = "testnet",
+    endpoints: dict[str, str] | None = None,
+    *,
+    chain_id: str | None = None,
+    timeout: float = 30.0,
+) -> QoreChainClient:
+    """Create a composed :class:`QoreChainClient`.
+
+    :param network: Network preset to target. Defaults to ``"testnet"``.
+    :param endpoints: Endpoint overrides (keys: ``rest``, ``grpc``, ``rpc``,
+        ``evm_rpc``, ``evm_ws``, ``svm_rpc``). Both presets default to localhost.
+    :param chain_id: Chain ID override.
+    :raises ValueError: If the network or an endpoint key is unknown.
+    """
+    resolved = _resolve_network(network, endpoints, chain_id)
+    rest = RestClient(_require_endpoint(resolved, "rest"), timeout=timeout)
+    qor = QorClient(_require_endpoint(resolved, "evm_rpc"), timeout=timeout)
+    return QoreChainClient(network=resolved, rest=rest, qor=qor, fees=_Fees(rest))
+
+
+__all__ = ["QoreChainClient", "create_client"]

qorechain/denom.py

@@ -0,0 +1,87 @@
+"""Conversion between human display amounts and integer base amounts.
+
+All value math is performed with integer arithmetic on decimal strings — there
+is no floating-point arithmetic anywhere in this module, so conversions are
+exact for any magnitude and never drift (e.g. ``to_base("0.1") == "100000"``).
+
+QoreChain's staking coin uses a default exponent of ``6`` (1 QOR = 10^6 uqor),
+but every function accepts a custom ``exponent`` for other denominations.
+"""
+
+from __future__ import annotations
+
+import re
+
+#: The QoreChain staking coin's default decimal exponent (1 QOR = 10^6 uqor).
+DEFAULT_EXPONENT = 6
+
+_DECIMAL_RE = re.compile(r"^\d+(\.\d+)?$")
+_INT_RE = re.compile(r"^\d+$")
+
+
+def _resolve_exponent(exponent: int) -> int:
+    if not isinstance(exponent, int) or isinstance(exponent, bool) or exponent < 0:
+        raise ValueError(f"invalid exponent: {exponent} (must be a non-negative integer)")
+    return exponent
+
+
+def to_base(amount: str, exponent: int = DEFAULT_EXPONENT) -> str:
+    """Convert a human display amount to its integer base amount string.
+
+    :param amount: A non-negative decimal string, e.g. ``"1.5"``. Surrounding
+        whitespace and a single leading ``+`` are tolerated. Scientific
+        notation, thousands separators, and other formatting are rejected.
+    :param exponent: Decimal exponent (defaults to 6).
+    :returns: The integer base amount as a string with no leading zeros.
+    :raises ValueError: If ``amount`` is not a valid decimal string, is
+        negative, or has more fractional digits than ``exponent`` allows.
+    """
+    exponent = _resolve_exponent(exponent)
+    body = amount.strip()
+
+    if body.startswith("-"):
+        raise ValueError(f"negative amounts are not supported: {amount}")
+    if body.startswith("+"):
+        body = body[1:]
+
+    if not _DECIMAL_RE.match(body):
+        raise ValueError(f"invalid decimal amount: {amount}")
+
+    int_part, _, frac_part = body.partition(".")
+    if len(frac_part) > exponent:
+        raise ValueError(
+            f"too many decimal places in {amount}: {len(frac_part)} > exponent {exponent}"
+        )
+
+    padded = frac_part.ljust(exponent, "0")
+    return str(int(int_part + padded))
+
+
+def from_base(base: str, exponent: int = DEFAULT_EXPONENT) -> str:
+    """Convert an integer base amount string to a normalized display string.
+
+    :param base: A non-negative integer string, e.g. ``"1500000"``.
+    :param exponent: Decimal exponent (defaults to 6).
+    :returns: The display amount with no trailing zeros and no trailing dot,
+        e.g. ``"1.5"``. ``"1000000"`` becomes ``"1"``, ``"1"`` becomes
+        ``"0.000001"``, ``"0"`` becomes ``"0"``.
+    :raises ValueError: If ``base`` is not a valid non-negative integer string.
+    """
+    exponent = _resolve_exponent(exponent)
+    trimmed = base.strip()
+
+    if trimmed.startswith("-"):
+        raise ValueError(f"negative amounts are not supported: {base}")
+    if not _INT_RE.match(trimmed):
+        raise ValueError(f"invalid base amount: {base}")
+
+    if exponent == 0:
+        return str(int(trimmed))
+
+    padded = trimmed.rjust(exponent + 1, "0")
+    int_part = padded[: len(padded) - exponent]
+    frac_part = padded[len(padded) - exponent :]
+
+    normalized_int = str(int(int_part))
+    trimmed_frac = frac_part.rstrip("0")
+    return f"{normalized_int}.{trimmed_frac}" if trimmed_frac else normalized_int