blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/network/systems/replication.py

@@ -0,0 +1,122 @@
+"""The CAP trade-off (Brewer 2000; Gilbert and Lynch 2002) on a replicated register.
+
+A register is copied on several replicas. When the network partitions them,
+a replica that cannot reach the others must choose: answer from what it
+knows (stay *available*, risking stale reads and lost writes) or refuse
+(stay *consistent*). Gilbert and Lynch proved no system can guarantee both
+during a partition. A blockchain makes the same choice: Bitcoin keeps
+producing blocks on both sides of a split and reconciles later.
+"""
+
+from collections.abc import Iterable
+
+from blockchainkit._validation import integer
+from blockchainkit.network.core.base import Operation
+
+MODES = ("consistent", "available")
+"""tuple of str: The two policies a replica can follow during a partition."""
+
+
+class ReplicatedRegister:
+    """A string register replicated on ``replicas`` nodes that can be partitioned.
+
+    Parameters
+    ----------
+    replicas : int
+        Number of replicas, at least 1; they are numbered from 0.
+    mode : {"consistent", "available"}
+        ``"consistent"``: a request succeeds only if the contacted replica
+        reaches a strict majority, and it then writes to or reads from every
+        reachable replica. Any two majorities overlap, so a read sees the
+        latest successful write. ``"available"``: every request succeeds
+        using the replicas the contacted one can reach.
+    initial : str
+        The value every replica starts with.
+
+    Notes
+    -----
+    Every value carries a version ``(counter, replica)``; a write's counter
+    is one more than the highest it can see. :meth:`heal` reconnects all
+    replicas and keeps the highest version (last writer wins), so in
+    available mode a write made on the losing side of a partition is lost.
+
+    Examples
+    --------
+    >>> from blockchainkit.network import ReplicatedRegister
+    >>> register = ReplicatedRegister(3, mode="consistent")
+    >>> register.partition([0], [1, 2])
+    >>> register.write(0, "x").ok, register.write(1, "y").ok
+    (False, True)
+    """
+
+    def __init__(self, replicas: int, *, mode: str = "consistent", initial: str = "") -> None:
+        integer(replicas, "replicas", 1)
+        if mode not in MODES:
+            raise ValueError(f"mode must be one of {MODES}")
+        self._mode = mode
+        self._store: list[tuple[tuple[int, int], str]] = [((0, 0), initial)] * replicas
+        self._group = [frozenset(range(replicas))] * replicas
+        self._history: list[Operation] = []
+
+    def __repr__(self) -> str:
+        return f"ReplicatedRegister(replicas={len(self._store)}, mode={self._mode!r})"
+
+    @property
+    def history(self) -> tuple[Operation, ...]:
+        """Every request so far, in order."""
+        return tuple(self._history)
+
+    def values(self) -> tuple[str, ...]:
+        """The value each replica currently holds, indexed by replica."""
+        return tuple(value for _, value in self._store)
+
+    def partition(self, *groups: Iterable[int]) -> None:
+        """Split the replicas into groups that can talk only within themselves.
+
+        The groups must cover every replica exactly once.
+        """
+        sets = [frozenset(group) for group in groups]
+        if sorted(r for group in sets for r in group) != list(range(len(self._store))):
+            raise ValueError("groups must cover every replica exactly once")
+        for group in sets:
+            for replica in group:
+                self._group[replica] = group
+
+    def heal(self) -> None:
+        """Reconnect every replica and converge on the highest version."""
+        self._group = [frozenset(range(len(self._store)))] * len(self._store)
+        self._store = [max(self._store)] * len(self._store)
+
+    def _reachable(self, replica: int) -> frozenset[int] | None:
+        integer(replica, "replica")
+        if replica >= len(self._store):
+            raise ValueError("unknown replica")
+        group = self._group[replica]
+        if self._mode == "consistent" and 2 * len(group) <= len(self._store):
+            return None  # No majority: refuse rather than risk inconsistency.
+        return group
+
+    def write(self, replica: int, value: str) -> Operation:
+        """Ask ``replica`` to store ``value``; return the recorded operation."""
+        if not isinstance(value, str):
+            raise TypeError("value must be a str")
+        group = self._reachable(replica)
+        if group is None:
+            operation = Operation("write", replica, None, False)
+        else:
+            counter = max(self._store[r][0][0] for r in group) + 1
+            for r in group:
+                self._store[r] = ((counter, replica), value)
+            operation = Operation("write", replica, value, True)
+        self._history.append(operation)
+        return operation
+
+    def read(self, replica: int) -> Operation:
+        """Ask ``replica`` for the value; return the recorded operation."""
+        group = self._reachable(replica)
+        if group is None:
+            operation = Operation("read", replica, None, False)
+        else:
+            operation = Operation("read", replica, max(self._store[r] for r in group)[1], True)
+        self._history.append(operation)
+        return operation

blockchainkit/network/systems/topology.py

@@ -0,0 +1,238 @@
+"""Peer graphs: random (Erdős–Rényi 1959), small-world (Watts–Strogatz 1998),
+and scale-free (Barabási–Albert 1999).
+
+Who is connected to whom decides how fast news spreads, how many links an
+attacker must cut, and how much a single peer can see. These generators build
+the three classic families so experiments can compare them on equal terms.
+"""
+
+from collections import deque
+from collections.abc import Iterable
+from random import Random
+
+from blockchainkit._validation import integer, probability
+from blockchainkit._validation import seed as check_seed
+
+
+class Graph:
+    """An immutable undirected simple graph on the nodes ``0, 1, ..., n - 1``.
+
+    Parameters
+    ----------
+    n : int
+        Number of nodes, at least 1.
+    edges : iterable of tuple of int
+        Unordered pairs of distinct nodes; duplicates are merged.
+
+    Examples
+    --------
+    >>> from blockchainkit.network import Graph
+    >>> path = Graph(3, [(0, 1), (1, 2)])
+    >>> path.distances(0)
+    (0, 1, 2)
+    >>> path.is_connected()
+    True
+    """
+
+    def __init__(self, n: int, edges: Iterable[tuple[int, int]]) -> None:
+        integer(n, "n", 1)
+        adjacency: list[set[int]] = [set() for _ in range(n)]
+        for left, right in edges:
+            integer(left, "edge endpoint")
+            integer(right, "edge endpoint")
+            if left >= n or right >= n or left == right:
+                raise ValueError("edges join two distinct nodes in range(n)")
+            adjacency[left].add(right)
+            adjacency[right].add(left)
+        self._neighbors = tuple(tuple(sorted(nodes)) for nodes in adjacency)
+        self._adjacent = tuple(frozenset(nodes) for nodes in adjacency)
+
+    def __repr__(self) -> str:
+        return f"Graph(n={self.n}, edges={len(self.edges)})"
+
+    @property
+    def n(self) -> int:
+        """Number of nodes."""
+        return len(self._neighbors)
+
+    @property
+    def edges(self) -> tuple[tuple[int, int], ...]:
+        """Every edge once, as ``(smaller, larger)``, in sorted order."""
+        return tuple((u, v) for u in range(self.n) for v in self._neighbors[u] if u < v)
+
+    def neighbors(self, node: int) -> tuple[int, ...]:
+        """Sorted neighbors of ``node``."""
+        return self._neighbors[node]
+
+    def degrees(self) -> tuple[int, ...]:
+        """Number of neighbors of every node, indexed by node."""
+        return tuple(len(nodes) for nodes in self._neighbors)
+
+    def distances(self, source: int) -> tuple[int | None, ...]:
+        """Hop counts from ``source`` by breadth-first search; None if unreachable."""
+        result: list[int | None] = [None] * self.n
+        result[source] = 0
+        queue = deque([source])
+        while queue:
+            node = queue.popleft()
+            hops = result[node]
+            assert hops is not None  # Only reached nodes are queued.
+            for neighbor in self._neighbors[node]:
+                if result[neighbor] is None:
+                    result[neighbor] = hops + 1
+                    queue.append(neighbor)
+        return tuple(result)
+
+    def components(self) -> tuple[frozenset[int], ...]:
+        """Connected components, largest first (ties by smallest node)."""
+        unseen, found = set(range(self.n)), []
+        while unseen:
+            start = min(unseen)
+            reached = frozenset(i for i, d in enumerate(self.distances(start)) if d is not None)
+            found.append(reached)
+            unseen -= reached
+        return tuple(sorted(found, key=lambda c: (-len(c), min(c))))
+
+    def is_connected(self) -> bool:
+        """True if every node can reach every other node."""
+        return len(self.components()) == 1
+
+    def average_path_length(self) -> float:
+        """Mean hop count over all ordered pairs of distinct, mutually reachable nodes.
+
+        This is the *L* of Watts and Strogatz. A graph with no such pair
+        (a single node, or no edges) has length 0.
+        """
+        total = pairs = 0
+        for source in range(self.n):
+            for d in self.distances(source):
+                if d:
+                    total += d
+                    pairs += 1
+        return total / pairs if pairs else 0.0
+
+    def clustering(self) -> float:
+        """Average local clustering coefficient: the *C* of Watts and Strogatz.
+
+        A node's coefficient is the fraction of pairs of its neighbors that
+        are themselves linked ("my friends know each other"). Nodes with fewer
+        than two neighbors contribute 0.
+        """
+        total = 0.0
+        for nodes in self._neighbors:
+            k = len(nodes)
+            if k >= 2:
+                linked = sum(
+                    1 for i, u in enumerate(nodes) for v in nodes[i + 1 :] if v in self._adjacent[u]
+                )
+                total += linked / (k * (k - 1) / 2)
+        return total / self.n
+
+
+def complete_graph(n: int) -> Graph:
+    """Every pair of the ``n`` nodes linked: the setting of classic rumor-spreading results.
+
+    >>> from blockchainkit.network import complete_graph
+    >>> len(complete_graph(5).edges)
+    10
+    """
+    integer(n, "n", 1)
+    return Graph(n, ((u, v) for u in range(n) for v in range(u + 1, n)))
+
+
+def erdos_renyi(n: int, p: float, *, seed: int = 0) -> Graph:
+    """Random graph G(n, p): each of the n(n-1)/2 possible links exists with probability p.
+
+    Erdős and Rényi showed that connectivity appears abruptly: for large n,
+    G(n, p) is almost surely disconnected when ``p < (1 - e) ln n / n`` and
+    almost surely connected when ``p > (1 + e) ln n / n``.
+
+    >>> from blockchainkit.network import erdos_renyi
+    >>> erdos_renyi(30, 1.0).is_connected()
+    True
+    """
+    integer(n, "n", 1)
+    probability(p, "p")
+    check_seed(seed)
+    random = Random(seed)
+    return Graph(n, ((u, v) for u in range(n) for v in range(u + 1, n) if random.random() < p))
+
+
+def ring_lattice(n: int, k: int) -> Graph:
+    """Ring where each node links to its ``k`` nearest nodes, ``k / 2`` on each side.
+
+    >>> from blockchainkit.network import ring_lattice
+    >>> ring_lattice(6, 2).neighbors(0)
+    (1, 5)
+    """
+    integer(n, "n", 3)
+    integer(k, "k", 2)
+    if k % 2 or k >= n:
+        raise ValueError("k must be even and smaller than n")
+    return Graph(n, ((u, (u + j) % n) for u in range(n) for j in range(1, k // 2 + 1)))
+
+
+def watts_strogatz(n: int, k: int, beta: float, *, seed: int = 0) -> Graph:
+    """Small-world graph: rewire each ring-lattice edge with probability ``beta``.
+
+    Following Watts and Strogatz, each edge ``(u, u + j)`` of
+    :func:`ring_lattice` keeps its endpoint ``u`` and, with probability
+    ``beta``, moves its other end to a uniformly random node, avoiding
+    self-loops and duplicate links. A few shortcuts (small ``beta``) shrink
+    the average path length almost to that of a random graph while the
+    clustering stays close to the lattice's.
+
+    >>> from blockchainkit.network import watts_strogatz
+    >>> len(watts_strogatz(20, 4, 0.3, seed=1).edges)
+    40
+    """
+    lattice = ring_lattice(n, k)
+    probability(beta, "beta")
+    check_seed(seed)
+    random = Random(seed)
+    adjacency = [set(lattice.neighbors(u)) for u in range(n)]
+    for j in range(1, k // 2 + 1):  # Rewire lap by lap, as in the 1998 paper.
+        for u in range(n):
+            v = (u + j) % n
+            if random.random() >= beta:
+                continue
+            choices = [w for w in range(n) if w != u and w not in adjacency[u]]
+            if not choices:
+                continue  # u already links to everyone; nothing to rewire to.
+            w = random.choice(choices)
+            adjacency[u].discard(v)
+            adjacency[v].discard(u)
+            adjacency[u].add(w)
+            adjacency[w].add(u)
+    return Graph(n, ((u, v) for u in range(n) for v in adjacency[u] if u < v))
+
+
+def barabasi_albert(n: int, m: int, *, seed: int = 0) -> Graph:
+    """Scale-free graph by preferential attachment.
+
+    Start from ``m + 1`` fully linked nodes. Each new node links to ``m``
+    distinct existing nodes, chosen with probability proportional to their
+    current degree ("the rich get richer"). The degree distribution
+    approaches the power law ``P(k) ~ k^-3``: a few hubs, many small nodes.
+
+    >>> from blockchainkit.network import barabasi_albert
+    >>> g = barabasi_albert(50, 2, seed=3)
+    >>> len(g.edges) == 3 + 2 * (50 - 3)
+    True
+    """
+    integer(m, "m", 1)
+    integer(n, "n", m + 1)
+    check_seed(seed)
+    random = Random(seed)
+    edges = [(u, v) for u in range(m + 1) for v in range(u + 1, m + 1)]
+    # Each node appears in ``ends`` once per incident edge, so a uniform pick
+    # from ``ends`` is a pick proportional to degree.
+    ends = [node for edge in edges for node in edge]
+    for new in range(m + 1, n):
+        targets: set[int] = set()
+        while len(targets) < m:
+            targets.add(random.choice(ends))
+        for target in sorted(targets):
+            edges.append((target, new))
+            ends.extend((target, new))
+    return Graph(n, edges)

blockchainkit/network/visualizers/__init__.py

@@ -0,0 +1,14 @@
+"""Plotting helpers for blockchainkit.network.
+
+Imports matplotlib, so ``import blockchainkit`` does not load this module;
+import it explicitly: ``from blockchainkit.network.visualizers import ...``.
+"""
+
+from blockchainkit.network.visualizers.plots import (
+    plot_gossip_timeline,
+    plot_graph,
+    plot_rumor_spread,
+    plot_space_time,
+)
+
+__all__ = ["plot_gossip_timeline", "plot_graph", "plot_rumor_spread", "plot_space_time"]

blockchainkit/network/visualizers/plots.py

@@ -0,0 +1,177 @@
+"""Plotting helpers for blockchainkit.network: graphs, space-time diagrams, and spreading."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.axes import Axes
+
+from blockchainkit.network.core.base import Delivery, RumorRun
+from blockchainkit.network.systems.clocks import Event, lamport_timestamps
+from blockchainkit.network.systems.topology import Graph
+
+__all__ = ["plot_gossip_timeline", "plot_graph", "plot_rumor_spread", "plot_space_time"]
+
+
+def plot_gossip_timeline(
+    deliveries: Sequence[Delivery], *, payload: bytes | None = None, ax: Axes | None = None
+) -> Axes:
+    """Show when each peer first accepted a payload, earliest at the top.
+
+    Parameters
+    ----------
+    deliveries : sequence of Delivery
+        Usually ``SimulatedNetwork.deliveries``.
+    payload : bytes, optional
+        Payload to plot; required when deliveries contain several payloads.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    payloads = {d.payload for d in deliveries}
+    if payload is None:
+        if len(payloads) != 1:
+            raise ValueError("deliveries hold several payloads; choose one with payload=")
+        (payload,) = payloads
+    chosen = sorted(
+        (d for d in deliveries if d.payload == payload), key=lambda d: (d.time, d.recipient)
+    )
+    if not chosen:
+        raise ValueError("no deliveries of that payload")
+    if ax is None:
+        _, ax = plt.subplots()
+    ordered = chosen[::-1]  # barh draws bottom-up; keep the earliest peer on top.
+    rows = range(len(ordered))
+    ax.barh(rows, [d.time for d in ordered], color="#2563eb")
+    ax.set_yticks(rows, [d.recipient for d in ordered])
+    for row, d in zip(rows, ordered, strict=True):
+        source = "origin" if d.sender == d.recipient else f"from {d.sender}"
+        ax.text(d.time, row, f" t={d.time} ({source})", va="center", fontsize=8)
+    ax.set_xlabel("simulation time of first acceptance")
+    ax.set_title(f"Gossip reached {len(chosen)} peers by t={chosen[-1].time}")
+    return ax
+
+
+def plot_graph(graph: Graph, *, highlight: Iterable[int] = (), ax: Axes | None = None) -> Axes:
+    """Draw a peer graph with its nodes on a circle.
+
+    A circle shows the structure of ring lattices and small worlds directly:
+    lattice links hug the rim and rewired shortcuts cut across it.
+
+    Parameters
+    ----------
+    graph : Graph
+        The graph to draw.
+    highlight : iterable of int
+        Nodes to draw in a contrasting color, such as spies or hubs.
+    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()
+    angles = 2 * np.pi * np.arange(graph.n) / graph.n
+    x, y = np.cos(angles), np.sin(angles)
+    for u, v in graph.edges:
+        ax.plot([x[u], x[v]], [y[u], y[v]], color="#94a3b8", linewidth=0.6, zorder=1)
+    marked = set(highlight)
+    colors = ["#dc2626" if node in marked else "#2563eb" for node in range(graph.n)]
+    ax.scatter(x, y, s=18, c=colors, zorder=2)
+    ax.set_aspect("equal")
+    ax.set_axis_off()
+    ax.set_title(f"{graph.n} peers, {len(graph.edges)} links")
+    return ax
+
+
+def plot_space_time(processes: Sequence[Sequence[Event]], *, ax: Axes | None = None) -> Axes:
+    """Draw Lamport's space-time diagram, labeling each event with its Lamport clock.
+
+    Each process is a horizontal line, time runs left to right, and each
+    message is an arrow from its send to its receive. An event is placed at
+    its Lamport timestamp, so every arrow points forward in time.
+
+    Parameters
+    ----------
+    processes : sequence of sequence of Event
+        A history as accepted by
+        :func:`~blockchainkit.network.systems.clocks.lamport_timestamps`.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    stamps = lamport_timestamps(processes)
+    if ax is None:
+        _, ax = plt.subplots()
+    sends: dict[str, tuple[int, int]] = {}
+    for p, events in enumerate(processes):
+        ax.axhline(p, color="#cbd5e1", linewidth=1, zorder=0)
+        for i, (kind, label) in enumerate(events):
+            if kind == "send":
+                sends[label] = (stamps[p][i], p)
+    for p, events in enumerate(processes):
+        for i, (kind, label) in enumerate(events):
+            clock = stamps[p][i]
+            if kind == "receive":
+                start = sends[label]
+                ax.annotate(
+                    "",
+                    xy=(clock, p),
+                    xytext=start,
+                    arrowprops={"arrowstyle": "->", "color": "#2563eb"},
+                )
+            ax.scatter(clock, p, s=30, color="black", zorder=2)
+            ax.annotate(
+                f"{label} ({clock})",
+                (clock, p),
+                xytext=(3, 6),
+                textcoords="offset points",
+                fontsize=8,
+            )
+    ax.set_yticks(range(len(processes)), [f"P{p}" for p in range(len(processes))])
+    ax.set_xlabel("Lamport time")
+    ax.set_title("Space-time diagram")
+    return ax
+
+
+def plot_rumor_spread(runs: Mapping[str, RumorRun], *, ax: Axes | None = None) -> Axes:
+    """Plot the fraction of peers still uninformed after each round, on a log scale.
+
+    On a log scale, push's slow final phase shows as a straight line
+    (the residue shrinks by a constant factor per round), while pull's
+    accelerating fall shows the residue squaring each round.
+
+    Parameters
+    ----------
+    runs : mapping of str to RumorRun
+        Runs to compare, keyed by their legend label.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if not runs:
+        raise ValueError("provide at least one run")
+    if ax is None:
+        _, ax = plt.subplots()
+    for label, run in runs.items():
+        residue = [1 - count / run.n for count in run.informed]
+        rounds = [r for r, value in enumerate(residue) if value > 0]
+        ax.semilogy(rounds, [residue[r] for r in rounds], marker="o", markersize=3, label=label)
+    ax.set_xlabel("round")
+    ax.set_ylabel("fraction still uninformed")
+    ax.set_title("Rumor spreading")
+    ax.legend()
+    return ax

blockchainkit/structures/__init__.py

@@ -0,0 +1,61 @@
+"""Authenticated data, signed transactions, immutable blocks, and fork state."""
+
+from blockchainkit.structures.core.base import (
+    Coin,
+    MerkleProof,
+    MerkleTrace,
+    MMRProof,
+    OutPoint,
+    ProofStep,
+    SparseMerkleProof,
+)
+from blockchainkit.structures.systems.block import Block, BlockHeader
+from blockchainkit.structures.systems.bloom import BloomFilter
+from blockchainkit.structures.systems.chain import Blockchain
+from blockchainkit.structures.systems.hash_chain import hash_chain, verify_one_time_password
+from blockchainkit.structures.systems.headers import verify_header_chain
+from blockchainkit.structures.systems.ledger import Ledger
+from blockchainkit.structures.systems.merkle import (
+    MerkleTree,
+    bitcoin_merkle_root,
+    consistency_proof,
+    trace_proof,
+    verify_consistency,
+    verify_proof,
+)
+from blockchainkit.structures.systems.mmr import MerkleMountainRange, verify_mmr_proof
+from blockchainkit.structures.systems.sparse_merkle import SparseMerkleTree, verify_sparse_proof
+from blockchainkit.structures.systems.transaction import Transaction, address
+from blockchainkit.structures.systems.utxo import UTXOSet, UTXOTransaction
+
+__all__ = [
+    "Coin",
+    "MMRProof",
+    "MerkleProof",
+    "MerkleTrace",
+    "OutPoint",
+    "ProofStep",
+    "SparseMerkleProof",
+    "Block",
+    "BlockHeader",
+    "BloomFilter",
+    "Blockchain",
+    "hash_chain",
+    "verify_one_time_password",
+    "verify_header_chain",
+    "Ledger",
+    "MerkleTree",
+    "bitcoin_merkle_root",
+    "consistency_proof",
+    "trace_proof",
+    "verify_consistency",
+    "verify_proof",
+    "MerkleMountainRange",
+    "verify_mmr_proof",
+    "SparseMerkleTree",
+    "verify_sparse_proof",
+    "Transaction",
+    "address",
+    "UTXOSet",
+    "UTXOTransaction",
+]

blockchainkit/structures/core/__init__.py

@@ -0,0 +1,21 @@
+"""Result containers for blockchainkit.structures."""
+
+from blockchainkit.structures.core.base import (
+    Coin,
+    MerkleProof,
+    MerkleTrace,
+    MMRProof,
+    OutPoint,
+    ProofStep,
+    SparseMerkleProof,
+)
+
+__all__ = [
+    "Coin",
+    "MMRProof",
+    "MerkleProof",
+    "MerkleTrace",
+    "OutPoint",
+    "ProofStep",
+    "SparseMerkleProof",
+]