btclib-ecc 2026.9.26__py3-none-any.whl

btclib_ecc/__init__.py

@@ -0,0 +1,98 @@
+# Copyright (c) The btclib developers
+# Distributed under the MIT software license, see the accompanying
+# LICENSE file or https://opensource.org/license/mit for the full text.
+
+"""The btclib_ecc package: what it publishes, and the version metadata.
+
+Elliptic curve arithmetic and the signature, commitment and key-agreement
+schemes built on it, over any curve in short Weierstrass form, with
+libsecp256k1 accelerating secp256k1 where the optional `btclib-secp256k1`
+bindings are installed.
+
+`__all__` here is the root of the package's public tree: the packages and
+top-level modules a caller reaches from this name. Each of those, and each
+module below them, declares its own `__all__`, so a walk that starts here
+has a declared surface at every node -- which is why the list is not
+`pkgutil.iter_modules`: discovery would answer the file tree, and a module
+added to the directory would publish itself rather than being published.
+
+`name` is not in it, nor are the metadata dunders. `name` is the
+distribution's name and not a member of the tree, `__version__` bound by
+a star import would overwrite the importing module's own, and each is
+still an attribute here: `btclib_ecc.__version__` is how a caller
+reads the version and `btclib_ecc.name` how it reads the name.
+
+Nothing is imported eagerly. A module is imported when it is first asked
+for, through the `__getattr__` at the bottom of this file, so `import
+btclib_ecc` is the metadata lookup below and nothing else, and the
+import graph keeps its shape: importing every module here would put the
+whole package in `sys.modules` before any single module of it could be
+imported first, which is the situation tests/imports_test.py exists to
+make impossible.
+
+What that costs is worth stating: mypy reads a module-level `__getattr__`
+as a promise that any attribute may exist, so `btclib_ecc.cruves` is
+`Any` to it and a misspelling on this package is a runtime
+`AttributeError` rather than a reported error. The spellings a caller
+actually writes -- `from btclib_ecc import curves`, `import
+btclib_ecc.curves`, `from btclib_ecc.curves import mult` --
+resolve against the real modules and stay checked.
+"""
+
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError, version
+from types import ModuleType
+
+name = "btclib-ecc"
+try:
+    __version__ = version("btclib-ecc")
+except PackageNotFoundError:
+    # a source tree with no metadata beside it: git clone and import, or
+    # read the docs, which builds without installing this package. Any
+    # number here would be a guess, and reading pyproject.toml back is not
+    # the way to stop guessing: the file is not in the wheel. Importing has
+    # to keep working, so the version says it does not know
+    __version__ = "unknown"
+
+__all__ = [
+    "alias",
+    "curves",
+    "ecc",
+    "exceptions",
+    "hashes",
+    "kdf",
+    "number_theory",
+]
+
+
+def __getattr__(published: str) -> ModuleType:
+    """Import a published module the first time it is asked for.
+
+    PEP 562: this runs only for a name the package does not already have,
+    so it answers `btclib_ecc.curves` once and the import machinery's
+    own attribute answers it from then on -- and it never runs for
+    `import btclib_ecc.curves` or `from btclib_ecc import curves`,
+    which import the submodule themselves. What it makes work is
+    `getattr(btclib_ecc, "curves")` on a fresh interpreter, which is
+    how a walker reading `__all__` descends, and `from btclib_ecc
+    import *`, which asks for each name in the list.
+
+    Anything not in `__all__` raises `AttributeError`, private modules
+    included: `import btclib_ecc._utils` still reaches one. The
+    message is the interpreter's own wording, so a typo reads as it does
+    anywhere else.
+    """
+    if published in __all__:
+        return import_module(f"{__name__}.{published}")
+    raise AttributeError(f"module {__name__!r} has no attribute {published!r}")
+
+
+def __dir__() -> list[str]:
+    """Answer with the published tree beside what the package already has.
+
+    `dir(btclib_ecc)` consults this rather than the namespace, so
+    without it a module not yet imported is missing from the completion a
+    caller gets at an interactive prompt -- the same names `__getattr__`
+    above will answer for.
+    """
+    return sorted({*__all__, *globals()})

btclib_ecc/_libsecp256k1.py

@@ -0,0 +1,142 @@
+# Copyright (c) The btclib developers
+# Distributed under the MIT software license, see the accompanying
+# LICENSE file or https://opensource.org/license/mit for the full text.
+
+"""Everything this package asks of libsecp256k1, imported in one place.
+
+The modules that delegate to the bindings import none of them directly:
+they import from here, so the question "are the bindings installed" is
+asked once, at one import, and answered by `INSTALLED` rather than by a
+`try` block in each of them, which could drift apart. `ENABLED` is that
+answer with `BTCLIB_ECC_NO_LIBSECP256K1` applied -- installed, and not
+refused -- and `curves.curve` reads it into `_libsecp256k1_available`,
+which is the seam every dispatch in the package consults, so an absent
+binding is a dispatch that declines rather than an `ImportError` raised
+before any dispatch is reached.
+
+Two names because the seam moves and this import does not. `ENABLED` is
+only the state `curves.curve` starts in, and `set_libsecp256k1_serving`
+may have moved it since; `INSTALLED` is settled here and stays, so it is
+what that function reads to refuse `serving=True` where there is nothing
+to serve, and what the suite skips its `bindings` marker on. The
+difference is this module's and the seam's, not a caller's:
+`curves.is_libsecp256k1_serving` publishes one answer -- whether the next
+call goes to libsecp256k1 or to the Python arithmetic -- which is the
+only difference a caller can act on.
+
+A module that imports nothing else of this package, and is therefore
+below every module that reads it. What it does import is the whole of
+the surface this package uses, so this file is also the answer to "what
+does this package need these bindings for", which no reader has to
+assemble from the delegating modules' own imports.
+
+The names are re-exported under the bindings' own spelling and the caller
+aliases them as it always did: a caller holding `keys` and reaching
+through it, and a caller naming `pubkey_sum` directly, both keep the call
+they had. Neither shape costs an attribute lookup it did not cost before,
+which matters where `curves.curve` counts tenths of a microsecond.
+
+With the bindings absent every name here is None. Nothing may call one:
+`_libsecp256k1_serves` is False in that configuration, and it is the
+predicate in front of every delegation -- which is a rule about the
+package rather than about this file, and is what `tests/no_bindings_test.py`
+checks by importing this package with the bindings out of reach.
+"""
+
+from __future__ import annotations
+
+import os
+
+# the environment variable that refuses the bindings without uninstalling
+# them, read once and here, when this module is first imported. `import
+# btclib_ecc` alone does not import it, the root importing lazily; the
+# first import of `curves`, of `ecc` or of a module under them does, so a
+# caller settling the variable after that has settled it after this module
+# answered. The package's name as its prefix, and "set to ask for it": an
+# empty value is not set, so `BTCLIB_ECC_NO_LIBSECP256K1=` leaves them
+# serving
+NO_LIBSECP256K1 = "BTCLIB_ECC_NO_LIBSECP256K1"
+
+__all__ = [
+    "ENABLED",
+    "INSTALLED",
+    "NO_LIBSECP256K1",
+    "PubkeyTweakChain",
+    "dsa",
+    "ellswift",
+    "ffi",
+    "keys",
+    "musig",
+    "pubkey_from_prvkey",
+    "pubkey_sum",
+    "pubkey_tweak_add",
+    "pubkey_tweak_mul_sum",
+    "recovery",
+    "shared_point",
+    "ssa",
+    "xonly_pubkey_verify",
+    "xonly_to_pubkey",
+]
+
+try:
+    # `ffi` is the one object here that is not a wrapped call: issue
+    # btclib-org/btclib#1009 is why it is needed at all -- `ecc.dsa.Signer`
+    # builds its own `unsigned char[32]` with it, to hold a private key in
+    # memory this package can overwrite, the way `ssa.Signer` already can
+    # through the keypair `ssa` itself builds. Nothing else here needs it,
+    # `dsa.sign` and every other wrapped call taking that buffer as the `prvkey`
+    # a caller may already hold (btclib-org/btclib-secp256k1#253)
+    from btclib_secp256k1 import (
+        dsa,
+        ellswift,
+        ffi,
+        keys,
+        musig,
+        recovery,
+        ssa,
+    )
+    from btclib_secp256k1.ecdh import shared_point
+    from btclib_secp256k1.keys import (
+        PubkeyTweakChain,
+        pubkey_from_prvkey,
+        pubkey_sum,
+        pubkey_tweak_add,
+        pubkey_tweak_mul_sum,
+    )
+    from btclib_secp256k1.xonly import pubkey_verify as xonly_pubkey_verify
+    from btclib_secp256k1.xonly import to_pubkey as xonly_to_pubkey
+
+    INSTALLED = True
+# issue btclib-org/btclib#1002 measured this branch rather than assuming it
+# stays transitional: `test.yml`'s `no-bindings` job executes it every run, and
+# `coverage-union` combines that run's data with the `coverage` job's. The
+# combined report is 100% with this pragma removed -- so the branch is reached
+# and is not dead code -- and the pragma still belongs here regardless, because
+# `coverage-union` is a second gate beside the `coverage` job's, not instead of
+# it: that job's own report, `pytest --cov` on this configuration alone, has
+# bindings installed by construction, an `ImportError` only reachable by
+# actually removing them, and a subprocess that does
+# (`tests/no_bindings_test.py`) whose coverage that job does not collect. So
+# this branch is a structural miss in that report regardless of the union, and
+# removing the pragma would fail the one gate this issue chose to leave
+# unchanged
+except ImportError:  # pragma: no cover -- only the no-bindings job reaches this
+    # None and not a callable that raises: what would raise is never
+    # called, so the object would be a second thing to keep true. The
+    # ignore is on the assignment and not on the module: every other
+    # name here keeps the type the try branch gave it
+    dsa = ellswift = ffi = keys = musig = recovery = ssa = None  # type: ignore[assignment]
+    shared_point = None  # type: ignore[assignment]
+    # a class rather than a function, so mypy calls it an assignment to
+    # a type and wants the second code as well
+    PubkeyTweakChain = None  # type: ignore[misc, assignment]
+    pubkey_from_prvkey = pubkey_sum = None  # type: ignore[assignment]
+    pubkey_tweak_add = pubkey_tweak_mul_sum = None  # type: ignore[assignment]
+    xonly_pubkey_verify = xonly_to_pubkey = None  # type: ignore[assignment]
+
+    INSTALLED = False
+
+# installed and not refused, which is one state and not two: a caller
+# asking whether the bindings serve has no use for the difference, and
+# `curves.curve` starts its seam from this
+ENABLED = INSTALLED and not os.environ.get(NO_LIBSECP256K1)

btclib_ecc/_utils.py

@@ -0,0 +1,418 @@
+# Copyright (c) The btclib developers
+# Distributed under the MIT software license, see the accompanying
+# LICENSE file or https://opensource.org/license/mit for the full text.
+
+"""The coercions every public function runs its inputs through.
+
+Private: these are the conversions an `Octets`, a `String`, an `Integer`
+and a `BinaryData` parameter owe their caller, and the refusals of a
+short read and of trailing bytes, raised through this package's own
+exceptions.
+
+`read_exactly` and `assert_no_trailing` are the two halves of what every
+`parse` owes its caller:
+
+- a field is as long as its encoding says it is, so a short read is an
+  error and not a value
+- octets are one whole object, so bytes after it are refused; a caller's
+  stream is not, so parsing consumes the object and leaves the stream on
+  the byte after it
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from io import BytesIO
+from typing import Any, BinaryIO
+
+from typing_extensions import TypeIs
+
+from btclib_ecc.alias import BinaryData, Integer, Octets, String
+from btclib_ecc.exceptions import BTClibEccTypeError, BTClibEccValueError
+
+__all__ = [
+    "NoneOneOrMoreInt",
+    "assert_no_trailing",
+    "assert_type",
+    "bytes_from_octets",
+    "bytesio_from_binarydata",
+    "hex_string",
+    "int_from_bits",
+    "int_from_integer",
+    "is_integer",
+    "is_octets",
+    "read_exactly",
+    "str_from_string",
+]
+
+NoneOneOrMoreInt = int | Iterable[int] | None
+
+
+def _assert_byte_shaped(octets: bytes | bytearray | memoryview) -> None:
+    """Refuse a memoryview whose layout or format is not plain bytes.
+
+    `bytes` and `bytearray` are always C-contiguous and always format
+    "B" (unsigned bytes); a `memoryview` need not be either, and the
+    copy `bytes_from_octets` makes takes both without a word. A strided
+    slice such as `mv[::2]` is not C-contiguous, and `bytes()` of one
+    gathers its strides into a run that no buffer holds.
+
+    Contiguity is not the only property the octets a caller counts rest on: a
+    `memoryview` cast to a signed `"b"`, or built over an array of a wider
+    format such as `"I"`, is C-contiguous and still not the octets it looks like
+    -- `len()` counts elements where `bytes()` yields `itemsize` of them each,
+    so the caller's count of its own octets and the library's disagree (issue
+    btclib-org/btclib#1430). Format `"B"` is the one every buffer this function
+    accepts shares, `bytes`, `bytearray` and an unformatted `memoryview`
+    included, so it is the property asked for rather than `itemsize == 1`, which
+    a signed `"b"` view or a `"c"` one (bytes objects, not ints) would still
+    pass.
+    """
+    if not isinstance(octets, memoryview):
+        return
+    if not octets.c_contiguous:
+        err_msg = "invalid octets: non-contiguous memoryview"
+        raise BTClibEccValueError(err_msg)
+    if octets.format != "B":
+        err_msg = f"invalid octets: memoryview format {octets.format!r} instead of 'B'"
+        raise BTClibEccValueError(err_msg)
+
+
+def bytes_from_octets(octets: Octets, out_size: NoneOneOrMoreInt = None) -> bytes:
+    """Return bytes from a hex-string, stripping leading/trailing spaces.
+
+    A `bytearray` or a `memoryview` is copied, which is what makes the
+    `bytes` this promises true: handed back as it came, either is still
+    the caller's own object, so a write to it afterwards reaches into
+    whatever kept the return value -- a key, and every encoding of it
+    computed afterwards. The copy is
+    also what reads as octets everywhere the result goes: a `memoryview`
+    has no `+` to concatenate with, and a `bytearray` keys no dict.
+
+    Optionally, it also ensures required output size: one size, or any
+    iterable of them, and a bool is neither -- `out_size=True` would
+    accept a single octet and say it had checked a size.
+
+    A non-contiguous `memoryview` -- what a strided slice such as
+    `mv[::2]` gives -- is refused rather than copied, and so is one whose
+    format is not unsigned bytes: `_assert_byte_shaped` says why neither
+    is the octets it looks like. The refusal is raised through the
+    exception contract at the one place every `Octets` parameter passes,
+    rather than left to whichever consumer trips over it first.
+    """
+    if isinstance(octets, str):  # hex string
+        # `bytes.fromhex` raises a bare ValueError -- the same class the
+        # contract promises, so what was lost is only that it came from
+        # here. This is the one coercion every `Octets` parameter of the
+        # library runs through, so it is the one place worth saying it in.
+        # The message is fromhex's own, which names a position and never
+        # the string: an Octets parameter is candidate key material as
+        # often as not (issue btclib-org/btclib#137)
+        try:
+            octets = bytes.fromhex(octets)
+        except ValueError as e:
+            raise BTClibEccValueError(f"invalid hex string: {e}") from e
+    elif isinstance(octets, (bytes, bytearray, memoryview)):
+        _assert_byte_shaped(octets)
+        # the copy that makes the annotation true (issue
+        # btclib-org/btclib#1255). `bytes(b)` is `b` itself where `b` is already
+        # `bytes`, which is what nearly every call passes, so the arm every
+        # `Octets` parameter of the library runs through allocates nothing
+        octets = bytes(octets)
+    else:
+        # what is neither went through untouched and reached whatever the
+        # caller went on to do with it: `len` of a tuple of 33 ints is 33,
+        # so a size check alone would accept one as a compressed key
+        err_msg = f"invalid octets type: {type(octets).__name__}"  # type: ignore[unreachable]
+        raise BTClibEccTypeError(err_msg)
+
+    if out_size is None:
+        return octets
+
+    # one size or an iterable of them, and nothing else: `tuple()` on
+    # whatever is left would refuse a float with a bare TypeError about
+    # iteration -- a complaint about the wrong thing, and from underneath
+    # the library rather than through its exception contract
+    if isinstance(out_size, int):
+        sizes: tuple[int, ...] = (out_size,)
+    elif isinstance(out_size, Iterable):
+        sizes = tuple(out_size)
+    else:
+        err_msg = f"invalid output size type: {type(out_size).__name__}"  # type: ignore[unreachable]
+        raise BTClibEccTypeError(err_msg)
+
+    for size in sizes:
+        if not is_integer(size):
+            err_msg = f"invalid output size type: {type(size).__name__}"
+            raise BTClibEccTypeError(err_msg)
+
+    size = len(octets)
+    if size in sizes:
+        return octets
+
+    err_msg = f"invalid size: {size} bytes instead of {out_size}"
+    raise BTClibEccValueError(err_msg)
+
+
+def str_from_string(s: String, what: str) -> str:
+    """Return the text of a String, whether it came as text or as ascii bytes.
+
+    What `bytes_from_octets` is to `Octets`, for text: the base64 armor
+    of an envelope is ascii, so a byte outside it is an invalid character
+    like any other and gets the same answer -- a UnicodeDecodeError let
+    out would fly past every caller written to catch a
+    BTClibEccValueError.
+
+    `what` names the string in both messages, the caller knowing what it
+    was reading and this not, exactly as `read_exactly` names a field.
+
+    Nothing is stripped and nothing is lowered: which of those is right
+    is the caller's to know.
+    """
+    if isinstance(s, str):
+        return s
+
+    if not isinstance(s, (bytes, bytearray, memoryview)):
+        # what is neither went through untouched, to fail on `len` or on
+        # a method of str that the value does not have -- a complaint
+        # about a builtin rather than about the argument
+        err_msg = f"invalid {what} type: {type(s).__name__}"  # type: ignore[unreachable]
+        raise BTClibEccTypeError(err_msg)
+
+    try:
+        return bytes(s).decode("ascii")
+    except UnicodeDecodeError as e:
+        raise BTClibEccValueError(f"non-ascii character in {what}: {e}") from e
+
+
+def bytesio_from_binarydata(stream: BinaryData) -> BytesIO:
+    """Return a BytesIO stream object from a BytesIO or from Octets.
+
+    A `BytesIO` is the caller's own and is handed back as it came, the
+    position it is left at being how a transaction is read out of a
+    block. Anything else is octets, and is wrapped in one.
+
+    A `BytesIO` and not any binary stream: `deserialize_map` asks the
+    result for `getbuffer()`, which a file object does not have, so
+    accepting one here would only move the failure. `read_exactly` is
+    the one that takes a `BinaryIO`, and its docstring says why.
+    """
+    if isinstance(stream, BytesIO):
+        return stream
+
+    # the refusal of what is neither a stream nor octets is
+    # bytes_from_octets's to give: without it, what is neither would go
+    # through untouched and be returned as it came, so `parse` would
+    # answer a None with a None and the caller would fail on `.read`
+    # rather than here
+    return BytesIO(bytes_from_octets(stream))
+
+
+def read_exactly(stream: BinaryIO, size: int, what: str) -> bytes:
+    """Return size octets from the stream, or raise: a short read is truncation.
+
+    `BytesIO.read` answers with whatever is left when the buffer holds
+    less than was asked for, and `int.from_bytes` takes the short answer
+    without a word. The size is what makes the field boundary, so it is
+    checked whatever `check_validity` says: see this module's docstring
+    for why that is not the same question.
+
+    `what` names the field in the error message, the caller knowing which
+    one it was reading and the stream not.
+
+    `BinaryIO` and not the `BytesIO` of `alias.BinaryData`: `.read` is
+    the whole of what a short read is about, so a file object is as much
+    an answer here as a buffer.
+    """
+    data = stream.read(size)
+    if len(data) != size:
+        err_msg = f"not enough data for the {what}: "
+        err_msg += f"{len(data)} bytes instead of {size}"
+        raise BTClibEccValueError(err_msg)
+    return data
+
+
+def assert_no_trailing(data: BinaryData, stream: BytesIO, what: str) -> None:
+    """Refuse bytes left over after a complete octet encoding.
+
+    Octets are one whole object, so what follows the object in them is
+    malleability: two buffers deserializing to the one object that
+    serializes back to only the shorter of them. A caller's stream is the
+    other case, and nothing is checked there -- what follows in it is the
+    caller's, a transaction inside a block being read from the very stream
+    the block is read from -- so `parse` leaves the stream on the byte
+    after the object.
+
+    Bitcoin Core splits the two the same way, between `Unserialize` and
+    `DecodeRawPSBT`'s "extra data after PSBT".
+    """
+    if isinstance(data, BytesIO):
+        return
+
+    trailing = stream.read()
+    if trailing:
+        raise BTClibEccValueError(f"{len(trailing)} bytes after the {what}")
+
+
+def is_integer(value: Any) -> bool:
+    """Return whether the value is an integer, a bool not being one.
+
+    `isinstance(x, int)` is True for `True` and `False`, `bool` being a
+    subclass of `int` -- so every field of this library whose contract is
+    an integer quantity accepted a boolean as the number one or zero, and
+    `int(True) == True` slips through a conversion-and-equality check as
+    well. What makes that worth a refusal rather than a shrug is the json
+    boundary: `true` decodes to `True`, so a schema mistake became one
+    satoshi, one virtual byte, one index or a one-sat/kvB fee rate instead
+    of failing next to the input that caused it.
+
+    A boolean is not another spelling of a number, which is the difference
+    from the strings and bytes much of this library accepts: "1" is a
+    number written down, `True` is a different type that Python's
+    inheritance makes indistinguishable from one.
+
+    `isinstance` and not `type(value) is int`, so an `IntEnum` -- what issue
+    btclib-org/btclib#273 asks about for the sighash types -- and any other
+    deliberate integer subclass stay integers. `bool` is the one subclass
+    excluded, and by name.
+    """
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def is_octets(value: Any) -> TypeIs[Octets]:
+    """Return whether the value is one Octets, rather than a sequence of them.
+
+    An `Octets` -- `str`, `bytes`, `bytearray` or `memoryview` -- is
+    itself iterable, so a function that takes a sequence of them and
+    guards against being handed one instead cannot ask `isinstance(value,
+    Sequence)`: every `Octets` answers that too. The guard asks this
+    question instead, once, so a spelling `Octets` gains later is refused
+    at every caller of this rather than at whichever remembered to list
+    it (issue btclib-org/btclib#1261).
+
+    `TypeIs` rather than `bool`: a caller dispatching on this narrows on
+    both branches, `str | bytes | bytearray | memoryview` where it is
+    true and whatever is left of the wider type where it is false, which
+    is what lets a site written as a hand-listed `isinstance` tuple --
+    invisible to a census keyed on that tuple's own element order -- call
+    this instead without losing the narrowing mypy strict mode otherwise
+    needs the tuple for (issue btclib-org/btclib#1433).
+    """
+    return isinstance(value, Octets)
+
+
+def assert_type(value: Any, expected: Any, what: str) -> None:
+    """Refuse a value of a type the signature does not declare.
+
+    `expected` is what `isinstance` takes: one type, or a tuple of them.
+    `bytes_from_octets` and `str_from_string` are the two coercions this
+    library has, and each refuses what it cannot convert; this is the
+    refusal for a position that takes neither -- a `bool` flag deciding
+    which of two serializations is written, the text of a URI or a
+    descriptor, the magic bytes an envelope is read against. Every one of
+    those was compared, walked or handed to a builtin unasked, and left
+    as a complaint about that builtin.
+
+    `value` is `Any` rather than the declared type, which is what makes
+    the check reachable: mypy proves the argument cannot be wrong, and
+    the caller who has not run mypy is who this is for.
+    """
+    if not isinstance(value, expected):
+        raise BTClibEccTypeError(f"invalid {what} type: {type(value).__name__}")
+
+
+def int_from_bits(octets: Octets, nlen: int) -> int:
+    """Return the leftmost nlen bits.
+
+    Take as input a sequence of blen bits and calculate a
+    non-negative integer i that is less than 2^nlen according to
+    SEC 1 v.2 section 4.1.3 (5); ensuring 0 < i < n would take a
+    further reduction modulo n, which is the caller's.
+
+    int_from_bits is not the reverse of i.to_bytes, even
+    for input sequences of length nlen: i.to_bytes will add some
+    bits on the left, while int_from_bits will discard some bits on the
+    right. i.to_bytes is the reverse of int_from_bits only when
+    nlen is a multiple of 8 and bit sequences already have length nlen.
+    See:
+    - https://www.rfc-editor.org/rfc/rfc6979.html#section-2.3.5
+    """
+    octets = bytes_from_octets(octets)
+    i = int.from_bytes(octets, byteorder="big", signed=False)
+
+    blen = len(octets) * 8  # bits
+    n = (blen - nlen) if blen >= nlen else 0
+    return i >> n
+
+
+def int_from_integer(i: Integer) -> int:
+    r"""Return an int from many possible integer representations.
+
+    A bool is not one of them, `is_integer` being where this library
+    says so: every `Integer` parameter runs through here, so the refusal
+    is stated once and inherited (issue btclib-org/btclib#1206).
+
+    Allowed integer representations are:
+
+    * 3735928559
+    * -3735928559
+    * "0xdeadbeef"
+    * "-0xdeadbeef"
+    * "deadbeef"
+    * b'\xde\xad\xbe\xef'
+
+    A str is always read as a hex-string, with or without the "0x" prefix:
+    int_from_integer("1234") is 4660, not one thousand two hundred and
+    thirty-four, and "9" raises ValueError for being a hex-string of odd
+    length rather than evaluating to nine. A decimal representation is
+    what int itself is for, so pass int("1234").
+
+    The binary representation is not allowed because there is no way to
+    discriminate it from a valid hex-string
+    (e.g. "0b11011110101011011011111011101111").
+    """
+    if isinstance(i, int):
+        # `is_integer` and not the `isinstance` above: a bool is an int to
+        # Python and is not a number to this library, which is the rule issue
+        # btclib-org/btclib#326 gave every integer field and issue
+        # btclib-org/btclib#1206 found the key path without. Here rather than at
+        # each caller, this being the one coercion every `Integer` parameter
+        # runs through
+        if not is_integer(i):
+            raise BTClibEccTypeError(f"non-integer: {i}")
+        return i
+
+    if isinstance(i, str):
+        i = i.strip().lower()
+        if i.startswith(("0x", "-0x")):
+            # the same bare ValueError bytes_from_octets names below, out
+            # of the one spelling that does not reach it
+            try:
+                return int(i, 16)
+            except ValueError as e:
+                raise BTClibEccValueError(f"invalid hex integer: {i!r}") from e
+
+    # the hex string, and the refusal of what is neither that nor bytes,
+    # both being bytes_from_octets's to give
+    return int.from_bytes(bytes_from_octets(i), "big", signed=False)
+
+
+def hex_string(i: Integer) -> str:
+    """Return a hex-string from many positive integer representations.
+
+    Negative integers are not allowed.
+
+    The resulting hex-string has an even number of hex-digits and
+    includes a space every four bytes (i.e. every eight hex-digits).
+    """
+    int_ = int_from_integer(i)
+    if int_ < 0:
+        raise BTClibEccValueError(f"negative integer: {int_}")
+    a_str = f"{int_:x}"
+    if len(a_str) % 2 != 0:
+        a_str = f"0{a_str}"
+
+    indexes = list(reversed(range(len(a_str), 0, -8)))
+    lresult = [(a_str[max(0, i - 8) : i]) for i in indexes]
+    result = " ".join(lresult)
+    return result.upper()