blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/constants.py

@@ -0,0 +1,66 @@
+"""Consensus-relevant constants shared across blockchainkit.
+
+Every hash domain tag, encoding bound, and default identifier lives here, so
+a change to one of them is visible as a change to the protocol. Changing any
+value changes hashes, signatures, or validation: update
+``docs/source/protocol.rst``, the tests, the examples, and ``CHANGELOG.md``
+together.
+
+>>> from blockchainkit import constants
+>>> constants.UINT64_LIMIT == 2**64
+True
+"""
+
+UINT64_LIMIT = 2**64
+"""int: Exclusive upper bound of the unsigned 64-bit fields (nonces, amounts, heights)."""
+
+WORD_MODULUS = 2**256
+"""int: The virtual machine's word size; arithmetic wraps modulo this value."""
+
+DEFAULT_CHAIN_ID = "blockchainkit-demo"
+"""str: Network identifier signed into every transaction to prevent cross-chain replay."""
+
+COMMIT_DOMAIN = b"blockchainkit:commit:v1\0"
+"""bytes: Domain tag prefixed to hash commitments."""
+
+SCHNORR_DOMAIN = "blockchainkit:schnorr:v1"
+"""str: Domain tag prefixed, with the curve parameters, to Schnorr challenges."""
+
+MERKLE_LEAF_PREFIX = b"\x00"
+"""bytes: Prefix for hashing a Merkle leaf payload."""
+
+MERKLE_NODE_PREFIX = b"\x01"
+"""bytes: Prefix for hashing two child digests into a Merkle node."""
+
+MERKLE_ROOT_PREFIX = b"\x02"
+"""bytes: Prefix for binding the leaf count to the top Merkle digest."""
+
+PUZZLE_DOMAIN = b"blockchainkit:puzzle:v1"
+"""bytes: Domain tag for the keystream that encrypts a Merkle puzzle."""
+
+PUZZLE_MAGIC = b"MERKLE78"
+"""bytes: Known plaintext prefix that tells a solver a puzzle has opened."""
+
+LAMPORT_DOMAIN = b"blockchainkit:lamport:v1"
+"""bytes: Domain tag for deriving Lamport private preimages from a seed."""
+
+PEDERSEN_DOMAIN = b"blockchainkit:pedersen:v1"
+"""bytes: Domain tag for deriving the second Pedersen generator."""
+
+MUSIG_DOMAIN = b"blockchainkit:musig:v1"
+"""bytes: Domain tag for MuSig key-aggregation coefficients."""
+
+MMR_ROOT_PREFIX = b"\x03"
+"""bytes: Prefix for bagging Merkle-mountain-range peaks into one root."""
+
+BLOOM_DOMAIN = b"blockchainkit:bloom:v1"
+"""bytes: Domain tag for deriving Bloom-filter bit positions."""
+
+UTXO_DOMAIN = "blockchainkit:utxo:v1"
+"""str: Domain tag signed into every UTXO transaction."""
+
+SORTITION_DOMAIN = b"blockchainkit:sortition:v1"
+"""bytes: Domain tag for the hash that stands in for a VRF in cryptographic sortition."""
+
+COMPACT_BLOCK_DOMAIN = b"blockchainkit:compact-block:v1"
+"""bytes: Domain tag for the salted short transaction IDs of compact blocks."""

blockchainkit/crypto/__init__.py

@@ -0,0 +1,157 @@
+"""Cryptographic foundations: hashing, public keys, sharing, curves, and proofs."""
+
+from blockchainkit.crypto.core.base import (
+    CollisionResult,
+    DiscreteLogResult,
+    FeldmanShares,
+    LamportKeyPair,
+    Point,
+    PuzzleSolution,
+    SchnorrSignature,
+)
+from blockchainkit.crypto.systems.asymmetric import (
+    TEACHING_GROUP,
+    DHGroup,
+    RSAKeyPair,
+    rsa_blind,
+    rsa_keypair,
+    rsa_unblind,
+)
+from blockchainkit.crypto.systems.commitments import (
+    commit,
+    pedersen_commit,
+    pedersen_generators,
+    verify_commitment,
+)
+from blockchainkit.crypto.systems.curves import (
+    SECP256K1,
+    TOY_CURVE,
+    Curve,
+    add,
+    encode_point,
+    enumerate_points,
+    multiply,
+    public_key,
+)
+from blockchainkit.crypto.systems.discrete_log import (
+    baby_step_giant_step,
+    pohlig_hellman,
+)
+from blockchainkit.crypto.systems.hashing import (
+    find_collision,
+    hamming_distance,
+    hash256,
+    sha256,
+    truncated_hash,
+)
+from blockchainkit.crypto.systems.lamport import (
+    lamport_keypair,
+    lamport_sign,
+    lamport_verify,
+)
+from blockchainkit.crypto.systems.mac import (
+    hmac_sha256,
+    naive_mac,
+)
+from blockchainkit.crypto.systems.merkle_damgard import (
+    SHA256_IV,
+    length_extension,
+    merkle_damgard_sha256,
+    sha256_compress,
+    sha256_padding,
+)
+from blockchainkit.crypto.systems.multisig import (
+    aggregate_public_keys,
+    musig_coefficients,
+    musig_sign,
+)
+from blockchainkit.crypto.systems.one_time_pad import (
+    one_time_pad,
+    xor_bytes,
+)
+from blockchainkit.crypto.systems.puzzles import (
+    merkle_puzzles,
+    solve_puzzle,
+)
+from blockchainkit.crypto.systems.sharing import (
+    feldman_split,
+    feldman_verify,
+    recover_secret,
+    split_secret,
+)
+from blockchainkit.crypto.systems.signatures import (
+    challenge,
+    deterministic_nonce,
+    recover_reused_nonce_key,
+    sign,
+    simulate_transcript,
+    verify,
+    verify_transcript,
+)
+from blockchainkit.crypto.utils.primes import (
+    is_prime,
+)
+
+__all__ = [
+    "CollisionResult",
+    "DiscreteLogResult",
+    "FeldmanShares",
+    "LamportKeyPair",
+    "Point",
+    "PuzzleSolution",
+    "SchnorrSignature",
+    "DHGroup",
+    "RSAKeyPair",
+    "TEACHING_GROUP",
+    "rsa_blind",
+    "rsa_keypair",
+    "rsa_unblind",
+    "commit",
+    "pedersen_commit",
+    "pedersen_generators",
+    "verify_commitment",
+    "SECP256K1",
+    "TOY_CURVE",
+    "Curve",
+    "add",
+    "encode_point",
+    "enumerate_points",
+    "multiply",
+    "public_key",
+    "baby_step_giant_step",
+    "pohlig_hellman",
+    "find_collision",
+    "hamming_distance",
+    "hash256",
+    "sha256",
+    "truncated_hash",
+    "lamport_keypair",
+    "lamport_sign",
+    "lamport_verify",
+    "hmac_sha256",
+    "naive_mac",
+    "SHA256_IV",
+    "length_extension",
+    "merkle_damgard_sha256",
+    "sha256_compress",
+    "sha256_padding",
+    "aggregate_public_keys",
+    "musig_coefficients",
+    "musig_sign",
+    "one_time_pad",
+    "xor_bytes",
+    "merkle_puzzles",
+    "solve_puzzle",
+    "feldman_split",
+    "feldman_verify",
+    "recover_secret",
+    "split_secret",
+    "challenge",
+    "deterministic_nonce",
+    "recover_reused_nonce_key",
+    "sign",
+    "simulate_transcript",
+    "verify",
+    "verify_transcript",
+    "is_prime",
+]

blockchainkit/crypto/core/__init__.py

@@ -0,0 +1,21 @@
+"""Shared types and result containers for blockchainkit.crypto."""
+
+from blockchainkit.crypto.core.base import (
+    CollisionResult,
+    DiscreteLogResult,
+    FeldmanShares,
+    LamportKeyPair,
+    Point,
+    PuzzleSolution,
+    SchnorrSignature,
+)
+
+__all__ = [
+    "CollisionResult",
+    "DiscreteLogResult",
+    "FeldmanShares",
+    "LamportKeyPair",
+    "Point",
+    "PuzzleSolution",
+    "SchnorrSignature",
+]

blockchainkit/crypto/core/base.py

@@ -0,0 +1,109 @@
+"""Shared types and result containers for blockchainkit.crypto."""
+
+from dataclasses import dataclass
+
+Point = tuple[int, int] | None
+"""An affine curve point ``(x, y)``, or ``None`` for the point at infinity."""
+
+
+@dataclass(frozen=True)
+class SchnorrSignature:
+    """A finite commitment point R and response scalar s."""
+
+    commitment: tuple[int, int]
+    response: int
+
+
+@dataclass(frozen=True)
+class DiscreteLogResult:
+    """An exponent x with base**x = target, and the work spent finding it.
+
+    Attributes
+    ----------
+    exponent : int
+        The smallest non-negative solution.
+    group_operations : int
+        Group multiplications in the baby-step and giant-step tables, the
+        dominant cost.
+    """
+
+    exponent: int
+    group_operations: int
+
+
+@dataclass(frozen=True)
+class CollisionResult:
+    """Two distinct inputs whose truncated hashes agree.
+
+    Attributes
+    ----------
+    first, second : bytes
+        The colliding inputs.
+    digest : int
+        Their shared truncated hash.
+    trials : int
+        Hashes computed before the collision appeared.
+    """
+
+    first: bytes
+    second: bytes
+    digest: int
+    trials: int
+
+
+@dataclass(frozen=True)
+class PuzzleSolution:
+    """The contents of one solved Merkle puzzle, and the trials it took.
+
+    Attributes
+    ----------
+    puzzle_id : bytes
+        The identifier the solver announces publicly.
+    key : bytes
+        The session key, which stays secret.
+    trials : int
+        Weak keys tried before the puzzle opened.
+    """
+
+    puzzle_id: bytes
+    key: bytes
+    trials: int
+
+
+@dataclass(frozen=True)
+class LamportKeyPair:
+    """A Lamport one-time key: 256 pairs of secret preimages and their hashes.
+
+    Attributes
+    ----------
+    private : tuple
+        256 pairs of bytes: for each digest bit, the preimage revealed when
+        that bit is 0 or 1.
+    public : tuple
+        256 pairs of bytes: the SHA-256 of each private preimage.
+    """
+
+    private: tuple[tuple[bytes, bytes], ...]
+    public: tuple[tuple[bytes, bytes], ...]
+
+    def __repr__(self) -> str:
+        return (
+            f"LamportKeyPair(public[0]={self.public[0][0].hex()[:16]}..., pairs={len(self.public)})"
+        )
+
+
+@dataclass(frozen=True)
+class FeldmanShares:
+    """Shamir shares plus public commitments that let each holder check theirs.
+
+    Attributes
+    ----------
+    shares : tuple
+        ``(x, f(x))`` pairs of int, points over the integers modulo the group
+        order q.
+    commitments : tuple of int
+        ``g**a_j mod p`` for each polynomial coefficient ``a_j``.
+    """
+
+    shares: tuple[tuple[int, int], ...]
+    commitments: tuple[int, ...]

blockchainkit/crypto/systems/__init__.py

@@ -0,0 +1,137 @@
+"""Concrete cryptographic constructions, one module per family."""
+
+from blockchainkit.crypto.systems.asymmetric import (
+    TEACHING_GROUP,
+    DHGroup,
+    RSAKeyPair,
+    rsa_blind,
+    rsa_keypair,
+    rsa_unblind,
+)
+from blockchainkit.crypto.systems.commitments import (
+    commit,
+    pedersen_commit,
+    pedersen_generators,
+    verify_commitment,
+)
+from blockchainkit.crypto.systems.curves import (
+    SECP256K1,
+    TOY_CURVE,
+    Curve,
+    add,
+    encode_point,
+    enumerate_points,
+    multiply,
+    public_key,
+)
+from blockchainkit.crypto.systems.discrete_log import (
+    baby_step_giant_step,
+    pohlig_hellman,
+)
+from blockchainkit.crypto.systems.hashing import (
+    find_collision,
+    hamming_distance,
+    hash256,
+    sha256,
+    truncated_hash,
+)
+from blockchainkit.crypto.systems.lamport import (
+    lamport_keypair,
+    lamport_sign,
+    lamport_verify,
+)
+from blockchainkit.crypto.systems.mac import (
+    hmac_sha256,
+    naive_mac,
+)
+from blockchainkit.crypto.systems.merkle_damgard import (
+    SHA256_IV,
+    length_extension,
+    merkle_damgard_sha256,
+    sha256_compress,
+    sha256_padding,
+)
+from blockchainkit.crypto.systems.multisig import (
+    aggregate_public_keys,
+    musig_coefficients,
+    musig_sign,
+)
+from blockchainkit.crypto.systems.one_time_pad import (
+    one_time_pad,
+    xor_bytes,
+)
+from blockchainkit.crypto.systems.puzzles import (
+    merkle_puzzles,
+    solve_puzzle,
+)
+from blockchainkit.crypto.systems.sharing import (
+    feldman_split,
+    feldman_verify,
+    recover_secret,
+    split_secret,
+)
+from blockchainkit.crypto.systems.signatures import (
+    challenge,
+    deterministic_nonce,
+    recover_reused_nonce_key,
+    sign,
+    simulate_transcript,
+    verify,
+    verify_transcript,
+)
+
+__all__ = [
+    "DHGroup",
+    "RSAKeyPair",
+    "TEACHING_GROUP",
+    "rsa_blind",
+    "rsa_keypair",
+    "rsa_unblind",
+    "commit",
+    "pedersen_commit",
+    "pedersen_generators",
+    "verify_commitment",
+    "SECP256K1",
+    "TOY_CURVE",
+    "Curve",
+    "add",
+    "encode_point",
+    "enumerate_points",
+    "multiply",
+    "public_key",
+    "baby_step_giant_step",
+    "pohlig_hellman",
+    "find_collision",
+    "hamming_distance",
+    "hash256",
+    "sha256",
+    "truncated_hash",
+    "lamport_keypair",
+    "lamport_sign",
+    "lamport_verify",
+    "hmac_sha256",
+    "naive_mac",
+    "SHA256_IV",
+    "length_extension",
+    "merkle_damgard_sha256",
+    "sha256_compress",
+    "sha256_padding",
+    "aggregate_public_keys",
+    "musig_coefficients",
+    "musig_sign",
+    "one_time_pad",
+    "xor_bytes",
+    "merkle_puzzles",
+    "solve_puzzle",
+    "feldman_split",
+    "feldman_verify",
+    "recover_secret",
+    "split_secret",
+    "challenge",
+    "deterministic_nonce",
+    "recover_reused_nonce_key",
+    "sign",
+    "simulate_transcript",
+    "verify",
+    "verify_transcript",
+]

blockchainkit/crypto/systems/asymmetric.py

@@ -0,0 +1,136 @@
+"""Textbook Diffie--Hellman, RSA, and RSA blinding for small experiments.
+
+These deliberately expose the mathematics. They are not encryption APIs
+for sensitive data: textbook RSA has no padding and DH has no authentication.
+"""
+
+from dataclasses import dataclass
+from math import gcd
+
+from blockchainkit._validation import integer
+from blockchainkit.crypto.utils.primes import is_prime
+
+
+@dataclass(frozen=True)
+class DHGroup:
+    """A prime-order subgroup of the multiplicative group modulo ``p``.
+
+    Parameters
+    ----------
+    p, q : int
+        Small primes (below 2**64) with q dividing p-1.
+    g : int
+        Nonidentity generator of order q.
+
+    Examples
+    --------
+    >>> from blockchainkit.crypto import DHGroup
+    >>> group = DHGroup()
+    >>> group.shared(group.public(7), 3) == group.shared(group.public(3), 7)
+    True
+    """
+
+    p: int = 23
+    q: int = 11
+    g: int = 2
+
+    def __post_init__(self) -> None:
+        if not is_prime(self.p) or not is_prime(self.q) or (self.p - 1) % self.q:
+            raise ValueError("p and q must be primes with q dividing p-1")
+        integer(self.g, "g", 2)
+        if self.g >= self.p or pow(self.g, self.q, self.p) != 1:
+            raise ValueError("g must generate the subgroup of order q")
+
+    def public(self, private: int) -> int:
+        """Return g**private modulo p, for private in [1, q)."""
+        integer(private, "private", 1)
+        if private >= self.q:
+            raise ValueError("private must be below q")
+        return pow(self.g, private, self.p)
+
+    def shared(self, peer_public: int, private: int) -> int:
+        """Derive a shared group element after validating subgroup membership.
+
+        This is not a key derivation function and does not authenticate peers.
+        """
+        self.public(private)
+        integer(peer_public, "peer_public", 2)
+        if peer_public >= self.p or pow(peer_public, self.q, self.p) != 1:
+            raise ValueError("invalid peer public element")
+        return pow(peer_public, private, self.p)
+
+
+TEACHING_GROUP = DHGroup(4611686018427377339, 2305843009213688669, 4)
+"""DHGroup: The order-q subgroup of a 62-bit safe prime p = 2q + 1, generated by 4.
+
+Large enough that its discrete logs take real work by hand-written baby-step
+giant-step (about 2**31 steps), small enough for exact arithmetic to stay
+instant. Still far too small for real security."""
+
+
+@dataclass(frozen=True)
+class RSAKeyPair:
+    """Textbook RSA exponents: modulus n, public e, and private d.
+
+    Construct with :func:`rsa_keypair`; tiny factors make the algebra visible.
+    """
+
+    n: int
+    e: int
+    d: int
+
+    def encrypt(self, message: int) -> int:
+        """Apply the public exponent to an integer in [0, n)."""
+        return _rsa_apply(message, self.e, self.n)
+
+    def decrypt(self, ciphertext: int) -> int:
+        """Apply the private exponent; no padding or timing protections."""
+        return _rsa_apply(ciphertext, self.d, self.n)
+
+
+def _rsa_apply(value: int, exponent: int, modulus: int) -> int:
+    integer(value, "value")
+    if value >= modulus:
+        raise ValueError("value must be below n")
+    return pow(value, exponent, modulus)
+
+
+def rsa_keypair(p: int = 61, q: int = 53, e: int = 17) -> RSAKeyPair:
+    """Build a textbook key pair from distinct primes below 2**64.
+
+    >>> from blockchainkit.crypto import rsa_keypair
+    >>> key = rsa_keypair()
+    >>> key.encrypt(65), key.decrypt(2790)
+    (2790, 65)
+    """
+    if not is_prime(p) or not is_prime(q) or p == q:
+        raise ValueError("p and q must be distinct primes below 2**64")
+    phi = (p - 1) * (q - 1)
+    integer(e, "e", 2)
+    if e >= phi or gcd(e, phi) != 1:
+        raise ValueError("e must be below phi(n) and coprime to it")
+    return RSAKeyPair(p * q, e, pow(e, -1, phi))
+
+
+def _check_blinding(value: int, factor: int, key: RSAKeyPair) -> None:
+    integer(value, "value")
+    if value >= key.n:
+        raise ValueError("value must be below n")
+    integer(factor, "factor", 1)
+    if factor >= key.n or gcd(factor, key.n) != 1:
+        raise ValueError("factor must be invertible modulo n and below n")
+
+
+def rsa_blind(message: int, factor: int, key: RSAKeyPair) -> int:
+    """Return m*r**e mod n for a caller-selected invertible blinding factor.
+
+    The signer applies its private exponent to this blinded integer.
+    """
+    _check_blinding(message, factor, key)
+    return message * pow(factor, key.e, key.n) % key.n
+
+
+def rsa_unblind(blind_signature: int, factor: int, key: RSAKeyPair) -> int:
+    """Remove blinding so signature**e mod n equals the original message."""
+    _check_blinding(blind_signature, factor, key)
+    return blind_signature * pow(factor, -1, key.n) % key.n