blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/network/systems/gossip.py

@@ -0,0 +1,201 @@
+"""Deterministic discrete-event gossip; no sockets, wall clock, or background threads."""
+
+import heapq
+from collections.abc import Callable, Iterable
+from random import Random
+from typing import TYPE_CHECKING
+
+from blockchainkit._validation import integer
+from blockchainkit._validation import seed as check_seed
+from blockchainkit.crypto import sha256
+from blockchainkit.network.core.base import Delivery
+
+if TYPE_CHECKING:
+    from blockchainkit.network.systems.topology import Graph
+
+
+class SimulatedNetwork:
+    """An undirected peer graph with seeded link delays and duplicate suppression.
+
+    Parameters
+    ----------
+    peers : iterable of str
+        Unique nonempty peer names. Initially no links exist.
+    seed : int
+        Private PRNG seed; construction does not modify global randomness.
+    on_receive : callable, optional
+        Callback for each first delivery, including the originating peer.
+        Return False to reject that payload at that peer and stop forwarding.
+        Returning None or True accepts it. Rejections remain seen.
+
+    Notes
+    -----
+    Disconnecting a link drops its in-flight messages. Reconnecting does not
+    automatically synchronize old data: call ``broadcast`` again. Latency is
+    sampled at send time, inclusive of both endpoints, and is at least one tick.
+    """
+
+    def __init__(
+        self,
+        peers: Iterable[str],
+        *,
+        seed: int = 0,
+        on_receive: Callable[[Delivery], bool | None] | None = None,
+    ) -> None:
+        check_seed(seed)
+        names = tuple(peers)
+        if not names or any(not isinstance(name, str) or not name for name in names):
+            raise ValueError("provide nonempty peer names")
+        if len(set(names)) != len(names):
+            raise ValueError("peer names must be unique")
+        self._links: dict[tuple[str, str], tuple[int, int, int]] = {}
+        self._seen: dict[str, set[bytes]] = {name: set() for name in sorted(names)}
+        self._accepted: dict[str, set[bytes]] = {name: set() for name in sorted(names)}
+        self._queue: list[tuple[int, int, str, str, bytes, int]] = []
+        self._deliveries: list[Delivery] = []
+        self._random = Random(seed)
+        self._callback = on_receive
+        self._time = 0
+        self._serial = 0
+        self._generation = 0
+        self._sent = 0
+
+    @classmethod
+    def from_graph(
+        cls,
+        graph: "Graph",
+        *,
+        latency: tuple[int, int] = (1, 1),
+        seed: int = 0,
+        on_receive: Callable[[Delivery], bool | None] | None = None,
+    ) -> "SimulatedNetwork":
+        """Build a network whose peers ``"0"``, ``"1"``, ... are linked like ``graph``.
+
+        >>> from blockchainkit.network import SimulatedNetwork, ring_lattice
+        >>> SimulatedNetwork.from_graph(ring_lattice(8, 2))
+        SimulatedNetwork(peers=8, links=8, time=0, pending=0)
+        """
+        network = cls((str(node) for node in range(graph.n)), seed=seed, on_receive=on_receive)
+        for left, right in graph.edges:
+            network.connect(str(left), str(right), latency=latency)
+        return network
+
+    def __repr__(self) -> str:
+        return (
+            f"SimulatedNetwork(peers={len(self._seen)}, links={len(self._links)}, "
+            f"time={self._time}, pending={len(self._queue)})"
+        )
+
+    @property
+    def time(self) -> int:
+        """Current simulated tick."""
+        return self._time
+
+    @property
+    def deliveries(self) -> tuple[Delivery, ...]:
+        """Immutable snapshot of accepted first deliveries."""
+        return tuple(self._deliveries)
+
+    @property
+    def messages_sent(self) -> int:
+        """Messages handed to links so far, including duplicates that receivers discard."""
+        return self._sent
+
+    @property
+    def pending(self) -> int:
+        """Number of queued events, including events invalidated by disconnection."""
+        return len(self._queue)
+
+    def _key(self, left: str, right: str) -> tuple[str, str]:
+        if left not in self._seen or right not in self._seen or left == right:
+            raise ValueError("link endpoints must be distinct known peers")
+        return (left, right) if left < right else (right, left)
+
+    def connect(self, left: str, right: str, *, latency: tuple[int, int] = (1, 1)) -> None:
+        """Create or replace a link with inclusive integer latency bounds."""
+        key = self._key(left, right)
+        low, high = latency
+        integer(low, "minimum latency", 1)
+        integer(high, "maximum latency", low)
+        self._generation += 1
+        self._links[key] = (low, high, self._generation)
+
+    def disconnect(self, left: str, right: str) -> None:
+        """Remove a link, invalidating all in-flight events sent on that link."""
+        self._links.pop(self._key(left, right), None)
+
+    def _forward(self, sender: str, payload: bytes, *, exclude: str | None = None) -> None:
+        for recipient in self._seen:
+            if recipient in (sender, exclude):
+                continue
+            link = self._links.get(self._key(sender, recipient))
+            if link is not None:
+                low, high, generation = link
+                self._serial += 1
+                self._sent += 1
+                heapq.heappush(
+                    self._queue,
+                    (
+                        self.time + self._random.randint(low, high),
+                        self._serial,
+                        sender,
+                        recipient,
+                        payload,
+                        generation,
+                    ),
+                )
+
+    def _receive(self, sender: str, recipient: str, payload: bytes) -> bool:
+        digest = sha256(payload)
+        if digest in self._seen[recipient]:
+            return False
+        # Mark the payload seen before the callback runs, so a callback that
+        # rebroadcasts it cannot recurse; undo the mark if the callback fails.
+        self._seen[recipient].add(digest)
+        delivery = Delivery(self.time, sender, recipient, payload)
+        try:
+            verdict = None if self._callback is None else self._callback(delivery)
+        except BaseException:
+            self._seen[recipient].discard(digest)
+            raise
+        if verdict is False:
+            return False
+        self._accepted[recipient].add(digest)
+        self._deliveries.append(delivery)
+        self._forward(recipient, payload, exclude=sender)
+        return True
+
+    def broadcast(self, sender: str, payload: bytes) -> None:
+        """Originate or retransmit bytes to neighbors; receivers suppress duplicates."""
+        if sender not in self._seen:
+            raise ValueError("unknown sender")
+        if not isinstance(payload, bytes):
+            raise TypeError("payload must be bytes")
+        if sha256(payload) in self._seen[sender]:
+            if sha256(payload) in self._accepted[sender]:
+                self._forward(sender, payload)
+        else:
+            self._receive(sender, sender, payload)
+
+    def run(self, *, until: int | None = None, max_events: int = 100_000) -> int:
+        """Process queued events up to a time/event bound; return events processed.
+
+        With until set, the clock advances to that tick if the event budget
+        was not exhausted. Events after until remain queued for a later run.
+        """
+        integer(max_events, "max_events", 1)
+        if until is not None:
+            integer(until, "until", self.time)
+        processed = 0
+        while self._queue and processed < max_events:
+            if until is not None and self._queue[0][0] > until:
+                break
+            time, _, sender, recipient, payload, generation = heapq.heappop(self._queue)
+            self._time = time
+            processed += 1
+            link = self._links.get(self._key(sender, recipient))
+            if link is not None and link[2] == generation:
+                self._receive(sender, recipient, payload)
+        if until is not None and (not self._queue or self._queue[0][0] > until):
+            self._time = until
+        return processed

blockchainkit/network/systems/kademlia.py

@@ -0,0 +1,147 @@
+"""Kademlia routing by XOR distance (Maymounkov and Mazières 2002).
+
+Every node has a ``bits``-bit identifier, and the distance between two
+identifiers is their bitwise XOR read as an integer. A node sorts the nodes
+it knows into *k-buckets*: bucket ``i`` holds up to ``k`` nodes whose
+distance lies in ``[2**i, 2**(i+1))``, the nodes whose identifier first
+differs from its own at bit ``i``. Knowing a few nodes at every scale lets a
+lookup halve the remaining distance at each hop, so it takes about
+``log2 n`` hops among ``n`` nodes.
+"""
+
+from collections.abc import Iterable
+from random import Random
+
+from blockchainkit._validation import integer
+from blockchainkit._validation import seed as check_seed
+from blockchainkit.crypto.systems.hashing import sha256
+from blockchainkit.network.core.base import LookupResult
+
+
+def xor_distance(a: int, b: int) -> int:
+    """Kademlia's distance: ``a XOR b``. It is symmetric and zero only for ``a == b``.
+
+    >>> from blockchainkit.network import xor_distance
+    >>> xor_distance(0b1010, 0b0110)
+    12
+    """
+    integer(a, "a")
+    integer(b, "b")
+    return a ^ b
+
+
+def node_id(key: bytes, bits: int) -> int:
+    """Derive a ``bits``-bit identifier from a public key: the top bits of its SHA-256.
+
+    Assigning identifiers by hash means a node cannot simply pick a position
+    in the identifier space; it has to search for keys. See the Sybil
+    experiment.
+
+    >>> from blockchainkit.network import node_id
+    >>> node_id(b"alice", 8) < 2**8
+    True
+    """
+    if not isinstance(key, bytes):
+        raise TypeError("key must be bytes")
+    integer(bits, "bits", 1)
+    if bits > 256:
+        raise ValueError("SHA-256 provides at most 256 bits")
+    return int.from_bytes(sha256(key), "big") >> (256 - bits)
+
+
+class KademliaNetwork:
+    """Nodes with idealized k-bucket routing tables.
+
+    Parameters
+    ----------
+    ids : iterable of int
+        Distinct node identifiers in ``[0, 2**bits)``.
+    bits : int
+        Identifier length.
+    k : int
+        Bucket capacity. Each bucket is filled with up to ``k`` nodes drawn
+        uniformly from all nodes at that distance scale.
+    seed : int
+        Seed for filling the buckets.
+
+    Notes
+    -----
+    Real Kademlia nodes fill their buckets gradually from the traffic they
+    see and prefer long-lived contacts. Here every table is filled at once
+    from global knowledge, which isolates the routing geometry.
+
+    Examples
+    --------
+    >>> from blockchainkit.network import KademliaNetwork
+    >>> net = KademliaNetwork([0b000, 0b011, 0b100, 0b110], bits=3, k=1)
+    >>> net.lookup(0b000, 0b111).path
+    (0, 6)
+    """
+
+    def __init__(self, ids: Iterable[int], *, bits: int, k: int = 8, seed: int = 0) -> None:
+        integer(bits, "bits", 1)
+        integer(k, "k", 1)
+        check_seed(seed)
+        nodes = tuple(sorted(ids))
+        if not nodes:
+            raise ValueError("provide at least one node")
+        for node in nodes:
+            integer(node, "node id")
+            if node >= 2**bits:
+                raise ValueError(f"node ids must be below 2**{bits}")
+        if len(set(nodes)) != len(nodes):
+            raise ValueError("node ids must be distinct")
+        self._bits, self._k, self._ids = bits, k, nodes
+        random = Random(seed)
+        self._tables: dict[int, tuple[tuple[int, ...], ...]] = {}
+        for node in nodes:
+            scales: list[list[int]] = [[] for _ in range(bits)]
+            for other in nodes:
+                if other != node:
+                    scales[(node ^ other).bit_length() - 1].append(other)
+            self._tables[node] = tuple(
+                tuple(sorted(random.sample(scale, min(k, len(scale))))) for scale in scales
+            )
+
+    def __repr__(self) -> str:
+        return f"KademliaNetwork(nodes={len(self._ids)}, bits={self._bits}, k={self._k})"
+
+    @property
+    def ids(self) -> tuple[int, ...]:
+        """Node identifiers in increasing order."""
+        return self._ids
+
+    def buckets(self, node: int) -> tuple[tuple[int, ...], ...]:
+        """The k-buckets of ``node``; bucket ``i`` holds contacts at distance [2**i, 2**(i+1))."""
+        if node not in self._tables:
+            raise ValueError("unknown node")
+        return self._tables[node]
+
+    def closest(self, target: int, count: int) -> tuple[int, ...]:
+        """The ``count`` nodes closest to ``target`` by XOR distance (global truth).
+
+        In Kademlia these nodes store the value with key ``target``.
+        """
+        integer(target, "target")
+        integer(count, "count", 1)
+        return tuple(sorted(self._ids, key=lambda node: node ^ target)[:count])
+
+    def lookup(self, source: int, target: int) -> LookupResult:
+        """Route greedily from ``source`` toward ``target``.
+
+        At each hop the current node forwards to the contact in its buckets
+        closest to ``target``, while that is closer than itself. If the
+        current node differs at bit ``i`` from the true closest node, its
+        bucket ``i`` is nonempty and every contact there is closer to the
+        target, so the route always ends at the closest node.
+        """
+        integer(target, "target")
+        current = source
+        path = [current]
+        while True:
+            contacts = [c for bucket in self.buckets(current) for c in bucket]
+            best = min(contacts, key=lambda c: c ^ target, default=current)
+            if best ^ target >= current ^ target:
+                return LookupResult(tuple(path))
+            current = best
+            path.append(current)

blockchainkit/network/systems/privacy.py

@@ -0,0 +1,98 @@
+"""Transaction-origin privacy: diffusion versus Dandelion (Bojja Venkatakrishnan,
+Fanti and Viswanath 2017).
+
+When a peer broadcasts its transaction, it is usually the first to send it.
+*Spy* peers that connect widely record who first sent them each
+transaction and guess that peer is the origin: the *first-spy estimator*.
+Dandelion first passes the transaction along a random path (the *stem*),
+each hop continuing with probability ``q``, and only then diffuses it. The
+spies then see the end of the stem, far from the origin.
+"""
+
+import heapq
+from collections.abc import Iterable
+from random import Random
+
+from blockchainkit._validation import integer, probability
+from blockchainkit._validation import seed as check_seed
+from blockchainkit.network.systems.topology import Graph
+
+MODES = ("diffusion", "dandelion")
+"""tuple of str: The broadcast strategies compared by :func:`first_spy_precision`."""
+
+
+def _first_spy_guess(
+    graph: Graph, spies: frozenset[int], start: int, previous: int, random: Random
+) -> int | None:
+    """Diffuse from ``start`` with exponential link delays; return the first spy's sender.
+
+    ``previous`` is the peer that handed the transaction to ``start``
+    (``start`` itself at the origin). Returns None if no spy is reachable.
+    """
+    if start in spies:
+        return previous
+    heard = {start}
+    queue = [(random.expovariate(1.0), start, neighbor) for neighbor in graph.neighbors(start)]
+    heapq.heapify(queue)
+    while queue:
+        time, sender, peer = heapq.heappop(queue)
+        if peer in heard:
+            continue
+        heard.add(peer)
+        if peer in spies:
+            return sender
+        for neighbor in graph.neighbors(peer):
+            if neighbor not in heard:
+                heapq.heappush(queue, (time + random.expovariate(1.0), peer, neighbor))
+    return None
+
+
+def first_spy_precision(
+    graph: Graph,
+    spies: Iterable[int],
+    *,
+    mode: str = "diffusion",
+    trials: int = 200,
+    stem_probability: float = 0.9,
+    seed: int = 0,
+) -> float:
+    """Fraction of broadcasts whose origin the first-spy estimator identifies.
+
+    Each trial picks an honest origin uniformly at random.
+
+    * ``"diffusion"``: the origin sends to all neighbors, and each peer
+      forwards on first receipt, with independent Exp(1) delay per message.
+    * ``"dandelion"``: the transaction first walks to a random neighbor;
+      after each hop it continues the stem with probability
+      ``stem_probability`` and otherwise diffuses from where it is. A spy on
+      the stem guesses the peer that handed it the transaction.
+
+    The original Dandelion routes stems over a dedicated line-shaped
+    anonymity graph; here the stem is a random walk on ``graph`` itself.
+
+    Examples
+    --------
+    >>> from blockchainkit.network import complete_graph, first_spy_precision
+    >>> first_spy_precision(complete_graph(2), {1}, trials=10)
+    1.0
+    """
+    spy_set = frozenset(spies)
+    honest = [node for node in range(graph.n) if node not in spy_set]
+    if not spy_set or not honest or not spy_set <= set(range(graph.n)):
+        raise ValueError("spies must be a nonempty proper subset of the peers")
+    if mode not in MODES:
+        raise ValueError(f"mode must be one of {MODES}")
+    integer(trials, "trials", 1)
+    probability(stem_probability, "stem_probability")
+    check_seed(seed)
+    random = Random(seed)
+    hits = 0
+    for _ in range(trials):
+        origin = previous = current = random.choice(honest)
+        if mode == "dandelion":
+            while graph.neighbors(current) and current not in spy_set:
+                previous, current = current, random.choice(graph.neighbors(current))
+                if random.random() >= stem_probability:
+                    break
+        hits += _first_spy_guess(graph, spy_set, current, previous, random) == origin
+    return hits / trials

blockchainkit/network/systems/propagation.py

@@ -0,0 +1,60 @@
+"""Propagation delay and forks (Decker and Wattenhofer 2013).
+
+A block takes time to reach the other miners. Until it arrives, they keep
+mining on the old tip, and if one of them finds a block in that window the
+chain forks. Block discovery is a Poisson process, so with propagation delay
+``tau`` and mean block interval ``T`` the chance that a block is followed by a
+competitor within ``tau`` is ``1 - exp(-tau / T)``. Shorter intervals or
+slower relay mean more forks, wasted work, and an easier time for attackers.
+"""
+
+from math import exp
+from random import Random
+
+from blockchainkit._validation import integer, positive
+from blockchainkit._validation import seed as check_seed
+
+
+def fork_rate(delay: float, interval: float) -> float:
+    """Probability that a competing block appears before a block has propagated.
+
+    Parameters
+    ----------
+    delay : float
+        Time for a block to reach the other miners.
+    interval : float
+        Mean time between blocks, in the same unit.
+
+    Examples
+    --------
+    >>> from blockchainkit.network import fork_rate
+    >>> round(fork_rate(12.6, 600), 4)
+    0.0208
+    """
+    if isinstance(delay, bool) or not isinstance(delay, (int, float)):
+        raise TypeError("delay must be a real number >= 0")
+    if not 0 <= delay < float("inf"):
+        raise ValueError("delay must be >= 0 and finite")
+    positive(interval, "interval")
+    return 1 - exp(-delay / interval)
+
+
+def simulate_fork_rate(
+    delay: float, interval: float, *, blocks: int = 10_000, seed: int = 0
+) -> float:
+    """Measure the fork rate on a simulated chain of Poisson block discoveries.
+
+    Draws exponential gaps with mean ``interval`` between successive blocks
+    and counts the blocks whose successor was found less than ``delay``
+    later, when its miner could not yet have seen them.
+
+    >>> from blockchainkit.network import simulate_fork_rate
+    >>> simulate_fork_rate(0.0, 600, blocks=100)
+    0.0
+    """
+    fork_rate(delay, interval)  # Validates both.
+    integer(blocks, "blocks", 1)
+    check_seed(seed)
+    random = Random(seed)
+    forks = sum(1 for _ in range(blocks) if random.expovariate(1 / interval) < delay)
+    return forks / blocks

blockchainkit/network/systems/relay.py

@@ -0,0 +1,123 @@
+"""Block relay: flooding, inv/getdata announcements (Bitcoin 2009), compact blocks (BIP 152, 2016).
+
+Flooding sends the full block over every link. Bitcoin's original protocol
+instead *announces* the block's hash with an ``inv`` message and sends the
+block only to peers that ask with ``getdata``, so each peer downloads it
+once, at the price of a round trip per hop. Compact blocks go further: most
+transactions are already in the receiver's mempool, so the sender lists
+short transaction IDs and the receiver rebuilds the block locally.
+"""
+
+from collections.abc import Iterable, Sequence
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import COMPACT_BLOCK_DOMAIN
+from blockchainkit.crypto.systems.hashing import sha256
+from blockchainkit.network.core.base import CompactBlockResult, RelayCost
+from blockchainkit.network.systems.topology import Graph
+
+HEADER_SIZE = 80
+"""int: Bytes in a block header."""
+
+ANNOUNCE_SIZE = 61
+"""int: Bytes in an ``inv`` or ``getdata`` for one item: a 24-byte message
+header, a one-byte count, and a 36-byte inventory vector."""
+
+MODES = ("flood", "announce")
+"""tuple of str: The relay strategies compared by :func:`relay_cost`."""
+
+
+def relay_cost(graph: Graph, *, size: int, mode: str = "flood", source: int = 0) -> RelayCost:
+    """Count the traffic to relay a ``size``-byte block from ``source`` to its component.
+
+    Every peer, on first receiving the block, passes it on to each neighbor
+    except the one it came from, so ``2E - (n - 1)`` messages cross the
+    links of a connected graph with E edges and n peers.
+
+    * ``"flood"``: each such message carries the whole block, and the block
+      reaches a peer at distance d after d link latencies.
+    * ``"announce"``: each such message is an ``inv``; a peer that lacks the
+      block answers its first ``inv`` with a ``getdata`` and receives the
+      block. Every peer downloads the block once, but each hop costs three
+      latencies.
+
+    Examples
+    --------
+    >>> from blockchainkit.network import complete_graph, relay_cost
+    >>> relay_cost(complete_graph(10), size=1_000_000).bytes
+    81000000
+    """
+    integer(size, "size", 1)
+    if mode not in MODES:
+        raise ValueError(f"mode must be one of {MODES}")
+    distances = graph.distances(source)
+    reached = [node for node, d in enumerate(distances) if d is not None]
+    forwards = sum(graph.degrees()[node] for node in reached) - (len(reached) - 1)
+    depth = max(d for d in distances if d is not None)
+    if mode == "flood":
+        return RelayCost(forwards, forwards * size, depth)
+    downloads = len(reached) - 1
+    return RelayCost(
+        forwards + 2 * downloads,
+        forwards * ANNOUNCE_SIZE + downloads * (ANNOUNCE_SIZE + size),
+        3 * depth,
+    )
+
+
+def short_id(transaction: bytes, nonce: int, size: int = 6) -> bytes:
+    """A ``size``-byte transaction ID salted by the block's ``nonce``.
+
+    Salting with a per-block nonce stops an attacker from crafting
+    transactions whose short IDs collide in every block. BIP 152 uses
+    SipHash keyed by the header and nonce; this teaching version uses
+    SHA-256.
+
+    >>> from blockchainkit.network import short_id
+    >>> len(short_id(b"tx", nonce=7))
+    6
+    """
+    if not isinstance(transaction, bytes):
+        raise TypeError("transaction must be bytes")
+    integer(nonce, "nonce")
+    integer(size, "size", 1)
+    return sha256(COMPACT_BLOCK_DOMAIN + nonce.to_bytes(8, "big") + sha256(transaction))[:size]
+
+
+def compact_block_relay(
+    block: Sequence[bytes],
+    mempool: Iterable[bytes],
+    *,
+    nonce: int = 0,
+    short_id_size: int = 6,
+) -> CompactBlockResult:
+    """Compare sending ``block`` in full with sending it as a compact block.
+
+    The compact form costs the header, an 8-byte nonce, and one short ID
+    per transaction. The receiver matches short IDs against its mempool.
+    A transaction with no match, or with an ambiguous or wrong match, must
+    be requested in a second round trip: a request of ``ANNOUNCE_SIZE``
+    bytes plus 2 bytes per index, then the transactions themselves.
+
+    Examples
+    --------
+    >>> from blockchainkit.network import compact_block_relay
+    >>> block = [bytes([i]) * 250 for i in range(100)]
+    >>> result = compact_block_relay(block, block[:90])
+    >>> result.missing, result.round_trips, result.full_bytes
+    (10, 2, 25080)
+    """
+    integer(short_id_size, "short_id_size", 1)
+    pool: dict[bytes, list[bytes]] = {}
+    for transaction in set(mempool):
+        pool.setdefault(short_id(transaction, nonce, short_id_size), []).append(transaction)
+    missing = [
+        transaction
+        for transaction in block
+        if pool.get(short_id(transaction, nonce, short_id_size)) != [transaction]
+    ]
+    compact = HEADER_SIZE + 8 + short_id_size * len(block)
+    if missing:
+        compact += ANNOUNCE_SIZE + 2 * len(missing) + sum(len(tx) for tx in missing)
+    return CompactBlockResult(
+        HEADER_SIZE + sum(len(tx) for tx in block), compact, len(missing), 2 if missing else 1
+    )