blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/network/systems/addresses.py

@@ -0,0 +1,126 @@
+"""Eclipse attacks on peer selection (Heilman, Kendler, Zohar and Goldberg 2015).
+
+A node picks its outbound connections at random from a table of addresses
+it has heard of. An attacker who fills that table with its own addresses
+can make every connection land on an attacker: the node is *eclipsed*, and
+sees only the blocks and transactions the attacker chooses to show it.
+
+Bitcoin's defense, strengthened after the 2015 paper, is bucketing: an
+address goes to a bucket determined by a secret hash of its network group
+(its /16 IP prefix), and each group can reach only a few buckets. An
+attacker with many addresses but few groups can then fill only a small part
+of the table, however many addresses it sends.
+"""
+
+from random import Random
+
+from blockchainkit._validation import integer, probability
+from blockchainkit._validation import seed as check_seed
+from blockchainkit.crypto.systems.hashing import sha256
+
+
+def eclipse_probability(attacker_fraction: float, outbound: int) -> float:
+    """Chance that all ``outbound`` connections land on attackers: ``f ** outbound``.
+
+    Each connection is modeled as an independent draw from a table in which
+    a fraction ``f`` of the entries belong to the attacker.
+
+    >>> from blockchainkit.network import eclipse_probability
+    >>> eclipse_probability(0.5, 8)
+    0.00390625
+    """
+    probability(attacker_fraction, "attacker_fraction")
+    integer(outbound, "outbound", 1)
+    return float(attacker_fraction**outbound)
+
+
+class AddressManager:
+    """A node's table of known peer addresses, with optional group bucketing.
+
+    Parameters
+    ----------
+    buckets : int
+        Number of buckets.
+    bucket_size : int
+        Capacity of each bucket. Adding to a full bucket evicts a random
+        entry, so a flood of new addresses pushes old ones out.
+    buckets_per_group : int, optional
+        If given, each network group can place addresses in only this many
+        buckets (Bitcoin's defense). If omitted, an address may land in any
+        bucket.
+    seed : int
+        Seeds both the node's secret bucketing key and its random choices.
+
+    Examples
+    --------
+    >>> from blockchainkit.network import AddressManager
+    >>> table = AddressManager(buckets=4, bucket_size=2, seed=1)
+    >>> table.add("10.0.0.1", "10.0")
+    >>> table.addresses
+    ('10.0.0.1',)
+    """
+
+    def __init__(
+        self,
+        *,
+        buckets: int = 64,
+        bucket_size: int = 16,
+        buckets_per_group: int | None = None,
+        seed: int = 0,
+    ) -> None:
+        integer(buckets, "buckets", 1)
+        integer(bucket_size, "bucket_size", 1)
+        if buckets_per_group is not None:
+            integer(buckets_per_group, "buckets_per_group", 1)
+        check_seed(seed)
+        self._random = Random(seed)
+        self._secret = self._random.randbytes(16)
+        self._per_group = buckets_per_group
+        self._buckets: list[list[str]] = [[] for _ in range(buckets)]
+        self._size = bucket_size
+
+    def __repr__(self) -> str:
+        return f"AddressManager(buckets={len(self._buckets)}, addresses={len(self.addresses)})"
+
+    def _hash(self, *parts: str) -> int:
+        return int.from_bytes(sha256(self._secret + "\0".join(parts).encode())[:8], "big")
+
+    def bucket_of(self, address: str, group: str) -> int:
+        """The bucket an address is stored in, derived from the node's secret key."""
+        if self._per_group is None:
+            return self._hash(address) % len(self._buckets)
+        slot = self._hash(address) % self._per_group
+        return self._hash(group, str(slot)) % len(self._buckets)
+
+    def add(self, address: str, group: str) -> None:
+        """Store an address heard from the network, evicting a random entry if needed."""
+        if not isinstance(address, str) or not isinstance(group, str):
+            raise TypeError("address and group must be str")
+        bucket = self._buckets[self.bucket_of(address, group)]
+        if address in bucket:
+            return
+        if len(bucket) >= self._size:
+            bucket.pop(self._random.randrange(len(bucket)))
+        bucket.append(address)
+
+    @property
+    def addresses(self) -> tuple[str, ...]:
+        """Every stored address, bucket by bucket."""
+        return tuple(address for bucket in self._buckets for address in bucket)
+
+    def select(self, count: int) -> tuple[str, ...]:
+        """Choose ``count`` distinct addresses: each time a random nonempty bucket, then an entry.
+
+        Picking a bucket first, as Bitcoin does, means an attacker confined
+        to a few buckets is picked rarely even if those buckets are full.
+        """
+        integer(count, "count", 1)
+        if count > len(self.addresses):
+            raise ValueError("not enough addresses")
+        chosen: list[str] = []
+        while len(chosen) < count:
+            bucket = self._random.choice([b for b in self._buckets if b])
+            address = self._random.choice(bucket)
+            if address not in chosen:
+                chosen.append(address)
+        return tuple(chosen)

blockchainkit/network/systems/broadcast.py

@@ -0,0 +1,124 @@
+"""Byzantine reliable broadcast (Bracha 1987).
+
+A sender wants every correct process to deliver the same value, even if the
+sender lies by telling different processes different things. Bracha's
+protocol adds two all-to-all phases on top of the sender's message:
+
+1. **Echo.** On the sender's value, a process tells everyone "I got v".
+2. **Ready.** On ``ceil((n + t + 1) / 2)`` echoes of v, or ``t + 1`` readies
+   of v (amplification), a process tells everyone "ready for v", once.
+3. **Deliver.** On ``2t + 1`` readies of v, a process delivers v.
+
+Any two echo quorums overlap in a correct process, which echoes only once,
+so correct processes never become ready for different values. Amplification
+makes delivery all-or-nothing. Both arguments need ``n > 3t``.
+"""
+
+from collections.abc import Iterable, Sequence
+
+from blockchainkit._validation import integer
+from blockchainkit.network.core.base import BroadcastResult
+
+SENDER = 0
+"""int: The broadcasting process."""
+
+
+def reliable_broadcast(
+    n: int,
+    faulty: Iterable[int],
+    proposals: Sequence[str],
+    *,
+    tolerance: int | None = None,
+) -> BroadcastResult:
+    """Run Bracha's broadcast in synchronous rounds from process 0.
+
+    Parameters
+    ----------
+    n : int
+        Number of processes, at least 2.
+    faulty : iterable of int
+        Byzantine processes. A faulty sender sends ``proposals[r]`` to each
+        process ``r``. Faulty processes collude with that split: to each
+        correct process ``r`` they echo and ready ``proposals[r]``, the
+        strongest support they can give to a disagreement.
+    proposals : sequence of str
+        One value per process; entries at faulty processes are ignored. If
+        the sender is correct, all correct entries must equal ``proposals[0]``.
+    tolerance : int, optional
+        The ``t`` used in the thresholds; defaults to ``(n - 1) // 3``, the
+        most the protocol can tolerate. Running with more faulty processes
+        than ``tolerance`` shows the bound is needed.
+
+    Returns
+    -------
+    BroadcastResult
+
+    Examples
+    --------
+    >>> from blockchainkit.network import reliable_broadcast
+    >>> result = reliable_broadcast(4, {0}, ["a", "a", "b", "b"])
+    >>> result.agreement, result.totality, sorted(set(result.delivered.values()))
+    (True, True, ['b'])
+    """
+    integer(n, "n", 2)
+    bad = set(faulty)
+    for process in bad:
+        integer(process, "faulty process")
+        if process >= n:
+            raise ValueError("faulty processes must be in range(n)")
+    t = (n - 1) // 3 if tolerance is None else tolerance
+    integer(t, "tolerance")
+    if len(proposals) != n or not all(isinstance(v, str) for v in proposals):
+        raise ValueError("give one str proposal per process")
+    correct = [p for p in range(n) if p not in bad]
+    if SENDER not in bad and any(proposals[p] != proposals[SENDER] for p in correct):
+        raise ValueError("a correct sender sends the same value to everyone")
+    echo_quorum, amplify, deliver_quorum = -(-(n + t + 1) // 2), t + 1, 2 * t + 1
+
+    echoes: dict[int, dict[str, set[int]]] = {p: {} for p in correct}
+    readies: dict[int, dict[str, set[int]]] = {p: {} for p in correct}
+    for r in correct:  # Faulty processes back the value the sender gave r.
+        for f in bad:
+            echoes[r].setdefault(proposals[r], set()).add(f)
+            readies[r].setdefault(proposals[r], set()).add(f)
+    echoed: set[int] = set()
+    ready: dict[int, str] = {}
+    delivered: dict[int, str | None] = dict.fromkeys(correct)
+    messages = len(correct) if SENDER in correct else 0  # The SEND messages.
+
+    def broadcast(table: dict[int, dict[str, set[int]]], source: int, value: str) -> int:
+        for r in correct:
+            table[r].setdefault(value, set()).add(source)
+        return n
+
+    changed = True
+    while changed:
+        changed = False
+        sends: list[tuple[str, int, str]] = []
+        for p in correct:
+            if p not in echoed:
+                sends.append(("echo", p, proposals[p]))
+                echoed.add(p)
+            if p not in ready:
+                candidates = sorted(
+                    v
+                    for v in set(echoes[p]) | set(readies[p])
+                    if len(echoes[p].get(v, ())) >= echo_quorum
+                    or len(readies[p].get(v, ())) >= amplify
+                )
+                if candidates:
+                    ready[p] = candidates[0]
+                    sends.append(("ready", p, candidates[0]))
+            if delivered[p] is None:
+                for v in sorted(readies[p]):
+                    if len(readies[p][v]) >= deliver_quorum:
+                        delivered[p] = v
+                        changed = True
+                        break
+        for kind, p, value in sends:  # Messages of a round arrive together.
+            messages += broadcast(echoes if kind == "echo" else readies, p, value)
+            changed = True
+    values = {v for v in delivered.values() if v is not None}
+    some = any(v is not None for v in delivered.values())
+    every = all(v is not None for v in delivered.values())
+    return BroadcastResult(delivered, len(values) <= 1, every or not some, messages)

blockchainkit/network/systems/clocks.py

@@ -0,0 +1,149 @@
+"""Logical clocks: Lamport timestamps (1978) and vector clocks (Fidge, Mattern 1988).
+
+Peers have no shared clock, so "which happened first?" has no physical
+answer. Lamport defined *happened before* from the messages themselves: an
+event precedes later events at the same process, a send precedes its
+receive, and the relation is transitive. Two events related neither way are
+*concurrent*.
+
+A history is a sequence of processes, each a sequence of events. An event is
+a pair ``(kind, label)``: ``("local", name)``, ``("send", message)`` or
+``("receive", message)``. Each message label is sent once and received at
+most once.
+"""
+
+from collections.abc import Sequence
+
+Event = tuple[str, str]
+"""``(kind, label)`` with kind ``"local"``, ``"send"`` or ``"receive"``."""
+
+_KINDS = ("local", "send", "receive")
+
+
+def _schedule(processes: Sequence[Sequence[Event]]) -> list[tuple[int, int]]:
+    """Positions ``(process, index)`` in an order where every send precedes its receive."""
+    senders: dict[str, tuple[int, int]] = {}
+    received: set[str] = set()
+    for p, events in enumerate(processes):
+        for i, event in enumerate(events):
+            if not isinstance(event, tuple) or len(event) != 2 or event[0] not in _KINDS:
+                raise ValueError(f"event {event!r} is not (kind, label) with a known kind")
+            kind, label = event
+            if kind == "send":
+                if label in senders:
+                    raise ValueError(f"message {label!r} is sent twice")
+                senders[label] = (p, i)
+            elif kind == "receive":
+                if label in received:
+                    raise ValueError(f"message {label!r} is received twice")
+                received.add(label)
+    if missing := received - senders.keys():
+        raise ValueError(f"messages received but never sent: {sorted(missing)}")
+    done: set[tuple[int, int]] = set()
+    order: list[tuple[int, int]] = []
+    cursor = [0] * len(processes)
+    progress = True
+    while progress:
+        progress = False
+        for p, events in enumerate(processes):
+            while cursor[p] < len(events):
+                kind, label = events[cursor[p]]
+                if kind == "receive" and senders[label] not in done:
+                    break  # Wait until the matching send has a timestamp.
+                done.add((p, cursor[p]))
+                order.append((p, cursor[p]))
+                cursor[p] += 1
+                progress = True
+    if len(order) != sum(len(events) for events in processes):
+        raise ValueError("the history has a causal cycle: a receive waits on its own future")
+    return order
+
+
+def lamport_timestamps(processes: Sequence[Sequence[Event]]) -> tuple[tuple[int, ...], ...]:
+    """Assign Lamport clock values to every event.
+
+    Each process keeps a counter. It increments the counter before each
+    event, attaches it to every message it sends, and on receipt jumps to
+    ``max(own, received) + 1``. The result satisfies the *clock condition*:
+    if a happened before b, then ``C(a) < C(b)``. The converse does not hold.
+
+    Returns
+    -------
+    tuple of tuple of int
+        ``result[p][i]`` is the timestamp of event ``i`` at process ``p``.
+
+    Examples
+    --------
+    >>> from blockchainkit.network import lamport_timestamps
+    >>> lamport_timestamps([[("send", "m")], [("local", "x"), ("local", "y"), ("receive", "m")]])
+    ((1,), (1, 2, 3))
+    """
+    stamps = [[0] * len(events) for events in processes]
+    clock = [0] * len(processes)
+    sent: dict[str, int] = {}
+    for p, i in _schedule(processes):
+        kind, label = processes[p][i]
+        if kind == "receive":
+            clock[p] = max(clock[p], sent[label])
+        clock[p] += 1
+        stamps[p][i] = clock[p]
+        if kind == "send":
+            sent[label] = clock[p]
+    return tuple(tuple(row) for row in stamps)
+
+
+def vector_timestamps(
+    processes: Sequence[Sequence[Event]],
+) -> tuple[tuple[tuple[int, ...], ...], ...]:
+    """Assign vector clock values to every event.
+
+    Each process ``p`` keeps one counter per process. It increments entry
+    ``p`` before each event and, on receipt, first takes the entrywise maximum
+    with the vector carried by the message. Entry ``q`` of an event's vector
+    counts the events at ``q`` that happened before or at it, so vectors
+    characterize causality exactly: see :func:`happened_before`.
+
+    Examples
+    --------
+    >>> from blockchainkit.network import vector_timestamps
+    >>> vector_timestamps([[("send", "m")], [("local", "x"), ("receive", "m")]])
+    (((1, 0),), ((0, 1), (1, 2)))
+    """
+    n = len(processes)
+    stamps: list[list[tuple[int, ...]]] = [[()] * len(events) for events in processes]
+    clock = [[0] * n for _ in range(n)]
+    sent: dict[str, tuple[int, ...]] = {}
+    for p, i in _schedule(processes):
+        kind, label = processes[p][i]
+        if kind == "receive":
+            clock[p] = [max(a, b) for a, b in zip(clock[p], sent[label], strict=True)]
+        clock[p][p] += 1
+        stamps[p][i] = tuple(clock[p])
+        if kind == "send":
+            sent[label] = stamps[p][i]
+    return tuple(tuple(row) for row in stamps)
+
+
+def happened_before(a: Sequence[int], b: Sequence[int]) -> bool:
+    """True if the event stamped ``a`` happened before the event stamped ``b``.
+
+    For vector timestamps, ``a -> b`` exactly when ``a <= b`` entrywise and
+    ``a != b``.
+
+    >>> from blockchainkit.network import happened_before
+    >>> happened_before((1, 0), (1, 2)), happened_before((1, 0), (0, 1))
+    (True, False)
+    """
+    if len(a) != len(b):
+        raise ValueError("vector timestamps must have the same length")
+    return all(x <= y for x, y in zip(a, b, strict=True)) and tuple(a) != tuple(b)
+
+
+def concurrent(a: Sequence[int], b: Sequence[int]) -> bool:
+    """True if neither vector-stamped event happened before the other (and they differ).
+
+    >>> from blockchainkit.network import concurrent
+    >>> concurrent((1, 0), (0, 1))
+    True
+    """
+    return tuple(a) != tuple(b) and not happened_before(a, b) and not happened_before(b, a)

blockchainkit/network/systems/epidemics.py

@@ -0,0 +1,111 @@
+"""Epidemic dissemination: push, pull and push-pull rumor spreading.
+
+Each round, every peer calls one neighbor chosen uniformly at random. In
+*push*, informed callers tell the callee; in *pull*, uninformed callers ask
+the callee and learn the rumor if it knows it; *push-pull* does both. Demers
+et al. (1987) compared these for replicated databases. On the complete graph,
+push alone informs everyone in about ``log2 n + ln n`` rounds (Frieze and
+Grimmett 1985, Pittel 1987).
+"""
+
+from math import log, log2
+from random import Random
+
+from blockchainkit._validation import integer
+from blockchainkit._validation import seed as check_seed
+from blockchainkit.network.core.base import RumorRun
+from blockchainkit.network.systems.topology import Graph
+
+MODES = ("push", "pull", "push-pull")
+"""tuple of str: The supported exchange modes."""
+
+
+def pittel_rounds(n: int) -> float:
+    """Rounds push gossip needs on the complete graph: ``log2 n + ln n``, up to O(1).
+
+    The ``log2 n`` term is the doubling phase, while few peers know the
+    rumor; the ``ln n`` term is the coupon-collector tail, while the last
+    uninformed peers wait to be called.
+
+    >>> from blockchainkit.network import pittel_rounds
+    >>> round(pittel_rounds(1024), 2)
+    16.93
+    """
+    integer(n, "n", 1)
+    return log2(n) + log(n)
+
+
+def spread_rumor(
+    network: Graph | int,
+    *,
+    mode: str = "push",
+    source: int = 0,
+    seed: int = 0,
+    max_rounds: int = 10_000,
+) -> RumorRun:
+    """Simulate synchronous random-call rumor spreading.
+
+    Parameters
+    ----------
+    network : Graph or int
+        The peer graph, or an integer ``n`` for the complete graph on ``n``
+        peers (simulated without building its n(n-1)/2 edges).
+    mode : {"push", "pull", "push-pull"}
+        Who learns from each call; see the module docstring.
+    source : int
+        The peer that knows the rumor at round 0.
+    seed : int
+        Seed for the random calls.
+    max_rounds : int
+        Stop after this many rounds even if peers remain uninformed.
+
+    Returns
+    -------
+    RumorRun
+        Informed counts per round. The run also stops once every peer that
+        the source can reach is informed.
+
+    Examples
+    --------
+    >>> from blockchainkit.network import spread_rumor
+    >>> run = spread_rumor(1000, seed=1)
+    >>> run.complete, run.informed[:4]
+    (True, (1, 2, 4, 8))
+    """
+    if mode not in MODES:
+        raise ValueError(f"mode must be one of {MODES}")
+    check_seed(seed)
+    integer(max_rounds, "max_rounds", 1)
+    if isinstance(network, Graph):
+        n = network.n
+        reachable = sum(1 for d in network.distances(source) if d is not None)
+    else:
+        integer(network, "n", 1)
+        n = reachable = network
+    integer(source, "source")
+    if source >= n:
+        raise ValueError("source must be a peer in range(n)")
+    random = Random(seed)
+
+    def call(peer: int) -> int | None:
+        if isinstance(network, Graph):
+            neighbors = network.neighbors(peer)
+            return random.choice(neighbors) if neighbors else None
+        partner = random.randrange(n - 1)  # Any peer but the caller.
+        return partner + 1 if partner >= peer else partner
+
+    informed = [False] * n
+    informed[source] = True
+    counts = [1]
+    while counts[-1] < reachable and len(counts) <= max_rounds:
+        before = informed[:]  # Calls in a round see the state at its start.
+        for caller in range(n):
+            callee = call(caller)
+            if callee is None:
+                continue
+            if mode != "pull" and before[caller]:
+                informed[callee] = True
+            if mode != "push" and before[callee]:
+                informed[caller] = True
+        counts.append(sum(informed))
+    return RumorRun(tuple(counts), n)