blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/crypto/systems/signatures.py

@@ -0,0 +1,232 @@
+"""Educational Schnorr signatures and interactive proof transcripts.
+
+This is a domain-separated teaching scheme, not Bitcoin BIP-340. Python
+curve arithmetic is variable-time. Explicit nonces exist for experiments;
+reusing a nonce reveals the private key.
+"""
+
+import hashlib
+import hmac
+import secrets
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import SCHNORR_DOMAIN
+from blockchainkit.crypto.core.base import SchnorrSignature
+from blockchainkit.crypto.systems.curves import (
+    SECP256K1,
+    Curve,
+    add,
+    encode_point,
+    multiply,
+    public_key,
+)
+from blockchainkit.crypto.systems.hashing import sha256
+
+
+def challenge(
+    message: bytes,
+    commitment: tuple[int, int],
+    public: tuple[int, int],
+    curve: Curve = SECP256K1,
+) -> int:
+    """Hash the curve parameters, public key, commitment, and message to a scalar."""
+    if not isinstance(message, bytes):
+        raise TypeError("message must be bytes")
+    domain = f"{SCHNORR_DOMAIN}:{curve.p}:{curve.a}:{curve.b}:{curve.order}:".encode()
+    framed = domain + encode_point(curve.generator, curve)
+    framed += encode_point(commitment, curve) + encode_point(public, curve) + message
+    return int.from_bytes(sha256(framed), "big") % curve.order
+
+
+def sign(
+    message: bytes,
+    private: int,
+    *,
+    nonce: int | None = None,
+    curve: Curve = SECP256K1,
+) -> SchnorrSignature:
+    """Sign with s = k + H(R, Q, m)*x modulo the subgroup order.
+
+    Parameters
+    ----------
+    message : bytes
+        Exact bytes to authenticate.
+    private : int
+        Secret scalar x.
+    nonce : int, optional
+        Experiment-only scalar k. Defaults to system randomness.
+    curve : Curve
+        Defaults to secp256k1; tiny curves illustrate algebra, not security.
+
+    Returns
+    -------
+    SchnorrSignature
+        Commitment R=kG and response s.
+
+    Examples
+    --------
+    >>> from blockchainkit.crypto import sign, verify, public_key
+    >>> signature = sign(b"lesson", 7, nonce=11)
+    >>> verify(b"lesson", signature, public_key(7))
+    True
+    """
+    public = public_key(private, curve)
+    if nonce is None:
+        nonce = secrets.randbelow(curve.order - 1) + 1
+    commitment = public_key(nonce, curve)
+    c = challenge(message, commitment, public, curve)
+    return SchnorrSignature(commitment, (nonce + c * private) % curve.order)
+
+
+def verify_transcript(
+    public: tuple[int, int],
+    commitment: tuple[int, int],
+    challenge_scalar: int,
+    response: int,
+    curve: Curve = SECP256K1,
+) -> bool:
+    """Check the interactive Schnorr equation sG = R + cQ.
+
+    An accepting transcript is not itself proof of a live interaction:
+    choosing c and s first permits simulation via R=sG-cQ. Soundness needs
+    an unpredictable verifier challenge after the prover commits to R.
+    """
+    for scalar in (challenge_scalar, response):
+        if type(scalar) is not int or not 0 <= scalar < curve.order:
+            return False
+    for point in (public, commitment):
+        if point is None or not curve.contains(point):
+            return False
+        # With cofactor 1 every curve point is in the subgroup (see Curve.cofactor_is_one).
+        if not curve.cofactor_is_one and multiply(curve.order, point, curve) is not None:
+            return False
+    return multiply(response, curve.generator, curve) == add(
+        commitment, multiply(challenge_scalar, public, curve), curve
+    )
+
+
+def simulate_transcript(
+    public: tuple[int, int],
+    challenge_scalar: int,
+    response: int,
+    curve: Curve = SECP256K1,
+) -> tuple[int, int]:
+    """Forge an accepting transcript *without* the private key: R = sG - cQ.
+
+    Choosing the challenge and response first, then solving for the
+    commitment, produces ``(R, c, s)`` that :func:`verify_transcript` accepts.
+    This is the simulator in the zero-knowledge proof (Goldwasser, Micali and
+    Rackoff, 1985): real transcripts and simulated ones look the same, so a
+    transcript teaches the verifier nothing. A live proof is sound only
+    because the verifier picks c *after* seeing R.
+    """
+    for scalar in (challenge_scalar, response):
+        integer(scalar, "scalar")
+        if scalar >= curve.order:
+            raise ValueError("scalars must be below the curve order")
+    negated = multiply(-challenge_scalar, public, curve)
+    commitment = add(multiply(response, curve.generator, curve), negated, curve)
+    if commitment is None:
+        raise ValueError("these scalars give the point at infinity; choose others")
+    return commitment
+
+
+def deterministic_nonce(private: int, message: bytes, order: int = SECP256K1.order) -> int:
+    """Derive a signing nonce from the key and message (RFC 6979, HMAC-SHA256).
+
+    Random nonces fail when the randomness does: a repeated or predictable
+    nonce reveals the private key (see :func:`recover_reused_nonce_key`).
+    RFC 6979 removes the random number generator from signing: the nonce is
+    an HMAC-DRBG output seeded with the private key and the message hash, so
+    it is unpredictable without the key, and distinct messages get distinct
+    nonces. This implements section 3.2 with SHA-256, and reproduces the
+    RFC's published nonces when given the same order.
+
+    Parameters
+    ----------
+    private : int
+        Secret scalar in [1, order).
+    message : bytes
+        The message to be signed (it is hashed here).
+    order : int
+        The group order q; defaults to secp256k1's.
+
+    Examples
+    --------
+    >>> from blockchainkit.crypto import deterministic_nonce, sign, verify, public_key
+    >>> k = deterministic_nonce(7, b"lesson")
+    >>> verify(b"lesson", sign(b"lesson", 7, nonce=k), public_key(7))
+    True
+    """
+    integer(order, "order", 2)
+    integer(private, "private", 1)
+    if private >= order:
+        raise ValueError("private key must be below the order")
+    if not isinstance(message, bytes):
+        raise TypeError("message must be bytes")
+    qlen = order.bit_length()
+    rlen = (qlen + 7) // 8
+
+    def bits2int(data: bytes) -> int:
+        value = int.from_bytes(data, "big")
+        excess = 8 * len(data) - qlen
+        return value >> excess if excess > 0 else value
+
+    def mac(key: bytes, data: bytes) -> bytes:
+        return hmac.new(key, data, hashlib.sha256).digest()
+
+    seed = private.to_bytes(rlen, "big") + (bits2int(sha256(message)) % order).to_bytes(rlen, "big")
+    v, k = b"\x01" * 32, b"\x00" * 32
+    k = mac(k, v + b"\x00" + seed)
+    v = mac(k, v)
+    k = mac(k, v + b"\x01" + seed)
+    v = mac(k, v)
+    while True:
+        t = b""
+        while 8 * len(t) < qlen:
+            v = mac(k, v)
+            t += v
+        nonce = bits2int(t)
+        if 1 <= nonce < order:
+            return nonce
+        k = mac(k, v + b"\x00")
+        v = mac(k, v)
+
+
+def verify(
+    message: bytes,
+    signature: SchnorrSignature,
+    public: tuple[int, int],
+    curve: Curve = SECP256K1,
+) -> bool:
+    """Verify a Schnorr signature; malformed points or scalars return False."""
+    try:
+        c = challenge(message, signature.commitment, public, curve)
+        return verify_transcript(public, signature.commitment, c, signature.response, curve)
+    except (ValueError, TypeError, AttributeError, OverflowError):
+        return False
+
+
+def recover_reused_nonce_key(
+    first: SchnorrSignature,
+    second: SchnorrSignature,
+    first_challenge: int,
+    second_challenge: int,
+    order: int = SECP256K1.order,
+) -> int:
+    """Recover x=(s1-s2)/(c1-c2) when two signatures reuse their nonce.
+
+    This demonstrates special soundness and why nonce reuse is catastrophic.
+    The caller supplies the actual challenges derived from the two messages.
+    """
+    integer(order, "order", 2)
+    if first.commitment != second.commitment:
+        raise ValueError("commitments must be identical")
+    for scalar in (first.response, second.response, first_challenge, second_challenge):
+        integer(scalar, "scalar")
+        if scalar >= order:
+            raise ValueError("scalar must be below order")
+    delta = (first_challenge - second_challenge) % order
+    if delta == 0:
+        raise ValueError("challenges must differ modulo order")
+    return (first.response - second.response) * pow(delta, -1, order) % order

blockchainkit/crypto/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Number-theoretic helpers that support the cryptographic systems."""
+
+from blockchainkit.crypto.utils.primes import is_prime
+
+__all__ = ["is_prime"]

blockchainkit/crypto/utils/primes.py

@@ -0,0 +1,39 @@
+"""Deterministic primality testing for the bounded parameters used in experiments."""
+
+
+def is_prime(value: int) -> bool:
+    """Test primality deterministically for integers below 2**64.
+
+    Uses trial division followed by deterministic Miller--Rabin bases for
+    this bounded domain. Larger numbers are deliberately not accepted.
+
+    >>> from blockchainkit.crypto.utils import is_prime
+    >>> is_prime(7919), is_prime(561)
+    (True, False)
+    """
+    if type(value) is not int:
+        raise TypeError(f"expected an integer, not {type(value).__name__}")
+    if value >= 2**64:
+        raise ValueError("expected an integer below 2**64")
+    if value < 2:
+        return False
+    for p in (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37):
+        if value % p == 0:
+            return value == p
+    d, s = value - 1, 0
+    while d % 2 == 0:
+        d //= 2
+        s += 1
+    for base in (2, 325, 9375, 28178, 450775, 9780504, 1795265022):
+        if base % value == 0:
+            continue
+        x = pow(base, d, value)
+        if x in (1, value - 1):
+            continue
+        for _ in range(s - 1):
+            x = pow(x, 2, value)
+            if x == value - 1:
+                break
+        else:
+            return False
+    return True

blockchainkit/crypto/visualizers/__init__.py

@@ -0,0 +1,9 @@
+"""Plotting helpers for blockchainkit.crypto.
+
+Imports matplotlib, so ``import blockchainkit`` does not load this module;
+import it explicitly: ``from blockchainkit.crypto.visualizers import ...``.
+"""
+
+from blockchainkit.crypto.visualizers.plots import plot_curve_points, plot_hamming_distances
+
+__all__ = ["plot_curve_points", "plot_hamming_distances"]

blockchainkit/crypto/visualizers/plots.py

@@ -0,0 +1,88 @@
+"""Plotting helpers for blockchainkit.crypto: small curve groups and hash avalanche."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from math import comb
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.axes import Axes
+
+from blockchainkit.crypto.systems.curves import Curve, enumerate_points, multiply
+
+__all__ = ["plot_curve_points", "plot_hamming_distances"]
+
+
+def plot_curve_points(
+    curve: Curve, *, label_multiples: bool = True, ax: Axes | None = None
+) -> Axes:
+    """Scatter every finite point of a small curve and label the multiples kG.
+
+    Parameters
+    ----------
+    curve : Curve
+        A curve with p <= 10,000
+        (see :func:`~blockchainkit.crypto.systems.curves.enumerate_points`).
+    label_multiples : bool
+        Annotate each point kG of the generator's subgroup with its k, which
+        shows that scalar multiplication jumps around the plane with no
+        visible pattern: the discrete-log problem.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots()
+    points = np.array(enumerate_points(curve))
+    ax.scatter(points[:, 0], points[:, 1], s=40, color="#94a3b8", label="curve points")
+    if label_multiples:
+        for k in range(1, curve.order):
+            point = multiply(k, curve.generator, curve)
+            assert point is not None  # k < order, so kG is finite.
+            ax.scatter(*point, s=55, color="#2563eb")
+            ax.annotate(f"{k}G", point, xytext=(5, 5), textcoords="offset points", fontsize=8)
+    ax.set_xlim(-1, curve.p)
+    ax.set_ylim(-1, curve.p)
+    ax.set_xlabel("x")
+    ax.set_ylabel("y")
+    ax.set_title(f"y² = x³ + {curve.a}x + {curve.b} over F_{curve.p}: {len(points) + 1} points")
+    return ax
+
+
+def plot_hamming_distances(
+    distances: Sequence[int], bits: int = 256, ax: Axes | None = None
+) -> Axes:
+    """Histogram of output-bit differences against the ideal Binomial(bits, 1/2).
+
+    Parameters
+    ----------
+    distances : sequence of int
+        Hamming distances between digests of related inputs, e.g. from
+        :func:`~blockchainkit.crypto.systems.hashing.hamming_distance` after a one-bit flip.
+    bits : int
+        Digest length in bits.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots()
+    values = np.asarray(distances)
+    ax.hist(values, bins=18, density=True, color="#0d9488", edgecolor="white", label="observed")
+    spread = 4 * np.sqrt(bits) / 2
+    ks = np.arange(int(bits / 2 - spread), int(bits / 2 + spread) + 1)
+    ideal = np.array([comb(bits, int(k)) for k in ks], dtype=float) / 2.0**bits
+    ax.plot(ks, ideal, color="black", label=f"Binomial({bits}, 1/2)")
+    ax.axvline(bits / 2, color="black", linestyle="--", linewidth=1)
+    ax.set_xlabel("differing output bits")
+    ax.set_ylabel("probability")
+    ax.set_title("Avalanche: about half the output bits change")
+    ax.legend()
+    return ax

blockchainkit/network/__init__.py

@@ -0,0 +1,70 @@
+"""Peer-to-peer networks: topologies, logical time, dissemination, overlays, and block relay."""
+
+from blockchainkit.network.core.base import (
+    BroadcastResult,
+    CompactBlockResult,
+    Delivery,
+    LookupResult,
+    Operation,
+    RelayCost,
+    RumorRun,
+)
+from blockchainkit.network.systems.addresses import AddressManager, eclipse_probability
+from blockchainkit.network.systems.broadcast import reliable_broadcast
+from blockchainkit.network.systems.clocks import (
+    concurrent,
+    happened_before,
+    lamport_timestamps,
+    vector_timestamps,
+)
+from blockchainkit.network.systems.epidemics import pittel_rounds, spread_rumor
+from blockchainkit.network.systems.gossip import SimulatedNetwork
+from blockchainkit.network.systems.kademlia import KademliaNetwork, node_id, xor_distance
+from blockchainkit.network.systems.privacy import first_spy_precision
+from blockchainkit.network.systems.propagation import fork_rate, simulate_fork_rate
+from blockchainkit.network.systems.relay import compact_block_relay, relay_cost, short_id
+from blockchainkit.network.systems.replication import ReplicatedRegister
+from blockchainkit.network.systems.topology import (
+    Graph,
+    barabasi_albert,
+    complete_graph,
+    erdos_renyi,
+    ring_lattice,
+    watts_strogatz,
+)
+
+__all__ = [
+    "BroadcastResult",
+    "CompactBlockResult",
+    "Delivery",
+    "LookupResult",
+    "Operation",
+    "RelayCost",
+    "RumorRun",
+    "AddressManager",
+    "eclipse_probability",
+    "reliable_broadcast",
+    "concurrent",
+    "happened_before",
+    "lamport_timestamps",
+    "vector_timestamps",
+    "pittel_rounds",
+    "spread_rumor",
+    "SimulatedNetwork",
+    "KademliaNetwork",
+    "node_id",
+    "xor_distance",
+    "first_spy_precision",
+    "fork_rate",
+    "simulate_fork_rate",
+    "compact_block_relay",
+    "relay_cost",
+    "short_id",
+    "ReplicatedRegister",
+    "Graph",
+    "barabasi_albert",
+    "complete_graph",
+    "erdos_renyi",
+    "ring_lattice",
+    "watts_strogatz",
+]

blockchainkit/network/core/__init__.py

@@ -0,0 +1,21 @@
+"""Event records and result containers."""
+
+from blockchainkit.network.core.base import (
+    BroadcastResult,
+    CompactBlockResult,
+    Delivery,
+    LookupResult,
+    Operation,
+    RelayCost,
+    RumorRun,
+)
+
+__all__ = [
+    "BroadcastResult",
+    "CompactBlockResult",
+    "Delivery",
+    "LookupResult",
+    "Operation",
+    "RelayCost",
+    "RumorRun",
+]

blockchainkit/network/core/base.py

@@ -0,0 +1,149 @@
+"""Event records and result containers for blockchainkit.network."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Delivery:
+    """First receipt of a byte payload at a peer at integer simulation time."""
+
+    time: int
+    sender: str
+    recipient: str
+    payload: bytes
+
+
+@dataclass(frozen=True)
+class RumorRun:
+    """How a rumor spread, round by synchronous round.
+
+    Attributes
+    ----------
+    informed : tuple of int
+        ``informed[r]`` peers knew the rumor after round ``r``;
+        ``informed[0]`` is 1, the source.
+    n : int
+        Number of peers.
+    """
+
+    informed: tuple[int, ...]
+    n: int
+
+    @property
+    def rounds(self) -> int:
+        """Rounds played until the run stopped."""
+        return len(self.informed) - 1
+
+    @property
+    def complete(self) -> bool:
+        """True if every peer heard the rumor."""
+        return self.informed[-1] == self.n
+
+
+@dataclass(frozen=True)
+class BroadcastResult:
+    """Outcome of a Byzantine reliable-broadcast run.
+
+    Attributes
+    ----------
+    delivered : dict
+        Each correct process's delivered value, or None if it delivered nothing.
+    agreement : bool
+        No two correct processes delivered different values.
+    totality : bool
+        Either every correct process delivered or none did.
+    messages : int
+        Messages sent by correct processes.
+    """
+
+    delivered: dict[int, str | None]
+    agreement: bool
+    totality: bool
+    messages: int
+
+
+@dataclass(frozen=True)
+class Operation:
+    """One client request to a replicated register and its outcome.
+
+    Attributes
+    ----------
+    kind : str
+        ``"read"`` or ``"write"``.
+    replica : int
+        The replica the client contacted.
+    value : str or None
+        The value written, or the value read; None if the request failed.
+    ok : bool
+        False if the replica refused the request to stay consistent.
+    """
+
+    kind: str
+    replica: int
+    value: str | None
+    ok: bool
+
+
+@dataclass(frozen=True)
+class LookupResult:
+    """Route of a Kademlia lookup.
+
+    Attributes
+    ----------
+    path : tuple of int
+        Node identifiers visited, from the source to the node that answered.
+    """
+
+    path: tuple[int, ...]
+
+    @property
+    def hops(self) -> int:
+        """Number of messages forwarded, one fewer than the nodes on the path."""
+        return len(self.path) - 1
+
+    @property
+    def found(self) -> int:
+        """The node that answered, the closest to the target that the route reached."""
+        return self.path[-1]
+
+
+@dataclass(frozen=True)
+class RelayCost:
+    """Traffic and time to relay one block from one source to every reachable peer.
+
+    Attributes
+    ----------
+    messages : int
+        Messages of any kind sent.
+    bytes : int
+        Total bytes sent.
+    completion : int
+        Time until the last peer has the block, in one-way link latencies.
+    """
+
+    messages: int
+    bytes: int
+    completion: int
+
+
+@dataclass(frozen=True)
+class CompactBlockResult:
+    """Bytes needed to relay one block in full and as a compact block (BIP 152).
+
+    Attributes
+    ----------
+    full_bytes : int
+        Header plus every transaction.
+    compact_bytes : int
+        Header, nonce, short IDs, and the transactions the receiver lacked.
+    missing : int
+        Transactions the receiver had to request: absent from its mempool, or
+        ambiguous because their short ID collided.
+    round_trips : int
+        1 if the mempool covered the block, 2 if a request was needed.
+    """
+
+    full_bytes: int
+    compact_bytes: int
+    missing: int
+    round_trips: int

blockchainkit/network/systems/__init__.py

@@ -0,0 +1,54 @@
+"""Concrete network models: topologies, clocks, dissemination, overlays, and relay."""
+
+from blockchainkit.network.systems.addresses import AddressManager, eclipse_probability
+from blockchainkit.network.systems.broadcast import reliable_broadcast
+from blockchainkit.network.systems.clocks import (
+    concurrent,
+    happened_before,
+    lamport_timestamps,
+    vector_timestamps,
+)
+from blockchainkit.network.systems.epidemics import pittel_rounds, spread_rumor
+from blockchainkit.network.systems.gossip import SimulatedNetwork
+from blockchainkit.network.systems.kademlia import KademliaNetwork, node_id, xor_distance
+from blockchainkit.network.systems.privacy import first_spy_precision
+from blockchainkit.network.systems.propagation import fork_rate, simulate_fork_rate
+from blockchainkit.network.systems.relay import compact_block_relay, relay_cost, short_id
+from blockchainkit.network.systems.replication import ReplicatedRegister
+from blockchainkit.network.systems.topology import (
+    Graph,
+    barabasi_albert,
+    complete_graph,
+    erdos_renyi,
+    ring_lattice,
+    watts_strogatz,
+)
+
+__all__ = [
+    "AddressManager",
+    "eclipse_probability",
+    "reliable_broadcast",
+    "concurrent",
+    "happened_before",
+    "lamport_timestamps",
+    "vector_timestamps",
+    "pittel_rounds",
+    "spread_rumor",
+    "SimulatedNetwork",
+    "KademliaNetwork",
+    "node_id",
+    "xor_distance",
+    "first_spy_precision",
+    "fork_rate",
+    "simulate_fork_rate",
+    "compact_block_relay",
+    "relay_cost",
+    "short_id",
+    "ReplicatedRegister",
+    "Graph",
+    "barabasi_albert",
+    "complete_graph",
+    "erdos_renyi",
+    "ring_lattice",
+    "watts_strogatz",
+]