blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/__init__.py

@@ -0,0 +1,12 @@
+"""Learn cryptography and blockchain systems through reproducible experiments.
+
+>>> import blockchainkit as bk
+>>> bk.crypto.sha256(b"abc").hex()[:8]
+'ba7816bf'
+"""
+
+from blockchainkit import consensus, constants, crypto, network, structures, vm
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__", "consensus", "constants", "crypto", "network", "structures", "vm"]

blockchainkit/_validation.py

@@ -0,0 +1,44 @@
+"""Argument validation shared by every blockchainkit subpackage."""
+
+
+def integer(value: int, name: str, minimum: int = 0) -> None:
+    """Validate an integer with an inclusive lower bound.
+
+    Raises
+    ------
+    TypeError
+        ``value`` is not an ``int``. Booleans are rejected even though
+        ``bool`` subclasses ``int``: ``True`` as a key or an amount is a bug.
+    ValueError
+        ``value`` is below ``minimum``.
+    """
+    if type(value) is not int:
+        raise TypeError(f"{name} must be an integer, not {type(value).__name__}")
+    if value < minimum:
+        raise ValueError(f"{name} must be an integer >= {minimum}")
+
+
+def seed(value: int) -> None:
+    """Validate a simulation seed: any integer, but not a bool, float, or string.
+
+    ``random.Random`` silently accepts strings and bytes, so a typo would
+    still produce a reproducible but unintended stream.
+    """
+    if type(value) is not int:
+        raise TypeError(f"seed must be an integer, not {type(value).__name__}")
+
+
+def probability(value: float, name: str) -> None:
+    """Validate a real number in [0, 1]; booleans are rejected like in :func:`integer`."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise TypeError(f"{name} must be a real number in [0, 1]")
+    if not 0 <= value <= 1:
+        raise ValueError(f"{name} must be in [0, 1]")
+
+
+def positive(value: float, name: str) -> None:
+    """Validate a finite real number greater than zero, such as a delay or an interval."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise TypeError(f"{name} must be a positive real number")
+    if not 0 < value < float("inf"):
+        raise ValueError(f"{name} must be positive and finite")

blockchainkit/consensus/__init__.py

@@ -0,0 +1,66 @@
+"""Consensus: agreement protocols, proof of work and stake, and the attacks they resist."""
+
+from blockchainkit.consensus.core.base import (
+    ConsensusRun,
+    DifficultyRun,
+    GeneralsResult,
+    MiningResult,
+    Offense,
+    PBFTResult,
+    SelfishMiningResult,
+    SquareRootResult,
+    ViewChangeRun,
+)
+from blockchainkit.consensus.systems.byzantine import oral_messages
+from blockchainkit.consensus.systems.catch_up import attacker_success_probability, eventual_catch_up
+from blockchainkit.consensus.systems.difficulty import retarget, simulate_difficulty
+from blockchainkit.consensus.systems.finality import FinalityGadget
+from blockchainkit.consensus.systems.fork_choice import ghost_tip, subtree_work
+from blockchainkit.consensus.systems.pbft import pbft_round, quorum_size
+from blockchainkit.consensus.systems.pos import StakeSampler
+from blockchainkit.consensus.systems.pow import expected_trials, mine, target, valid_pow
+from blockchainkit.consensus.systems.pricing import modular_square_root
+from blockchainkit.consensus.systems.randomized import ben_or
+from blockchainkit.consensus.systems.selfish import (
+    selfish_mining_revenue,
+    selfish_mining_threshold,
+    simulate_selfish_mining,
+)
+from blockchainkit.consensus.systems.sortition import sortition
+from blockchainkit.consensus.systems.stake_games import fork_voting_payoffs
+from blockchainkit.consensus.systems.synchrony import view_changes
+
+__all__ = [
+    "ConsensusRun",
+    "DifficultyRun",
+    "GeneralsResult",
+    "MiningResult",
+    "Offense",
+    "PBFTResult",
+    "SelfishMiningResult",
+    "SquareRootResult",
+    "ViewChangeRun",
+    "oral_messages",
+    "attacker_success_probability",
+    "eventual_catch_up",
+    "retarget",
+    "simulate_difficulty",
+    "FinalityGadget",
+    "ghost_tip",
+    "subtree_work",
+    "pbft_round",
+    "quorum_size",
+    "StakeSampler",
+    "expected_trials",
+    "mine",
+    "target",
+    "valid_pow",
+    "modular_square_root",
+    "ben_or",
+    "selfish_mining_revenue",
+    "selfish_mining_threshold",
+    "simulate_selfish_mining",
+    "sortition",
+    "fork_voting_payoffs",
+    "view_changes",
+]

blockchainkit/consensus/core/__init__.py

@@ -0,0 +1,25 @@
+"""Result containers for blockchainkit.consensus."""
+
+from blockchainkit.consensus.core.base import (
+    ConsensusRun,
+    DifficultyRun,
+    GeneralsResult,
+    MiningResult,
+    Offense,
+    PBFTResult,
+    SelfishMiningResult,
+    SquareRootResult,
+    ViewChangeRun,
+)
+
+__all__ = [
+    "ConsensusRun",
+    "DifficultyRun",
+    "GeneralsResult",
+    "MiningResult",
+    "Offense",
+    "PBFTResult",
+    "SelfishMiningResult",
+    "SquareRootResult",
+    "ViewChangeRun",
+]

blockchainkit/consensus/core/base.py

@@ -0,0 +1,97 @@
+"""Result containers for blockchainkit.consensus."""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from blockchainkit.structures.systems.block import Block
+
+
+@dataclass(frozen=True)
+class MiningResult:
+    """A successful mined block and the number of hashes attempted."""
+
+    block: "Block"
+    attempts: int
+
+
+@dataclass(frozen=True)
+class GeneralsResult:
+    """Outcome of an oral-messages run.
+
+    Attributes
+    ----------
+    decisions : dict
+        Each loyal lieutenant's decision.
+    agreement : bool
+        All loyal lieutenants decided the same (condition IC1).
+    validity : bool
+        If the commander is loyal, every loyal lieutenant followed its order
+        (condition IC2); vacuously true for a traitorous commander.
+    """
+
+    decisions: dict[int, str]
+    agreement: bool
+    validity: bool
+
+
+@dataclass(frozen=True)
+class ConsensusRun:
+    """Outcome of a randomized-consensus run: who decided what, after how many rounds."""
+
+    decisions: dict[int, int]
+    rounds: int
+    decided: bool
+
+
+@dataclass(frozen=True)
+class ViewChangeRun:
+    """Views tried under partial synchrony, until the first one that made progress."""
+
+    view_starts: tuple[int, ...]
+    timeouts: tuple[int, ...]
+    decided_view: int
+    decision_time: int
+
+
+@dataclass(frozen=True)
+class SquareRootResult:
+    """A modular square root and the multiplications spent computing it."""
+
+    root: int
+    multiplications: int
+
+
+@dataclass(frozen=True)
+class PBFTResult:
+    """Values each honest replica prepared and committed (None if it did not)."""
+
+    prepared: dict[int, str | None]
+    commits: dict[int, str | None]
+
+
+@dataclass(frozen=True)
+class DifficultyRun:
+    """Simulated block intervals and the target in force for each block."""
+
+    block_times: tuple[float, ...]
+    targets: tuple[int, ...]
+
+
+@dataclass(frozen=True)
+class SelfishMiningResult:
+    """Blocks each side contributed to the final chain, and the pool's share."""
+
+    selfish_blocks: int
+    honest_blocks: int
+    revenue: float
+
+
+@dataclass(frozen=True)
+class Offense:
+    """Two votes by one validator that violate a Casper slashing condition."""
+
+    validator: str
+    kind: str
+    first: tuple[int, int, bytes]
+    second: tuple[int, int, bytes]

blockchainkit/consensus/systems/__init__.py

@@ -0,0 +1,46 @@
+"""Concrete consensus mechanisms, agreement protocols, and attack models."""
+
+from blockchainkit.consensus.systems.byzantine import oral_messages
+from blockchainkit.consensus.systems.catch_up import attacker_success_probability, eventual_catch_up
+from blockchainkit.consensus.systems.difficulty import retarget, simulate_difficulty
+from blockchainkit.consensus.systems.finality import FinalityGadget
+from blockchainkit.consensus.systems.fork_choice import ghost_tip, subtree_work
+from blockchainkit.consensus.systems.pbft import pbft_round, quorum_size
+from blockchainkit.consensus.systems.pos import StakeSampler
+from blockchainkit.consensus.systems.pow import expected_trials, mine, target, valid_pow
+from blockchainkit.consensus.systems.pricing import modular_square_root
+from blockchainkit.consensus.systems.randomized import ben_or
+from blockchainkit.consensus.systems.selfish import (
+    selfish_mining_revenue,
+    selfish_mining_threshold,
+    simulate_selfish_mining,
+)
+from blockchainkit.consensus.systems.sortition import sortition
+from blockchainkit.consensus.systems.stake_games import fork_voting_payoffs
+from blockchainkit.consensus.systems.synchrony import view_changes
+
+__all__ = [
+    "oral_messages",
+    "attacker_success_probability",
+    "eventual_catch_up",
+    "retarget",
+    "simulate_difficulty",
+    "FinalityGadget",
+    "ghost_tip",
+    "subtree_work",
+    "pbft_round",
+    "quorum_size",
+    "StakeSampler",
+    "expected_trials",
+    "mine",
+    "target",
+    "valid_pow",
+    "modular_square_root",
+    "ben_or",
+    "selfish_mining_revenue",
+    "selfish_mining_threshold",
+    "simulate_selfish_mining",
+    "sortition",
+    "fork_voting_payoffs",
+    "view_changes",
+]

blockchainkit/consensus/systems/byzantine.py

@@ -0,0 +1,91 @@
+"""The Byzantine generals problem and the oral-messages algorithm (1982).
+
+Lamport, Shostak and Pease asked how loyal generals can agree on a plan when
+some generals, possibly including the commander, are traitors who send
+different messages to different recipients. Their algorithm OM(m) has every
+lieutenant relay what it heard, recursively, and take a majority. It
+succeeds whenever there are more than three times as many generals as
+traitors: n > 3m. With three generals and one traitor no algorithm can.
+"""
+
+from collections import Counter
+from collections.abc import Callable, Set
+
+from blockchainkit._validation import integer
+from blockchainkit.consensus.core.base import GeneralsResult
+
+ATTACK, RETREAT = "attack", "retreat"
+
+
+def _default_lie(sender: int, receiver: int, value: str) -> str:
+    """A traitor's strategy: tell even-numbered receivers to attack, odd ones to retreat."""
+    return ATTACK if receiver % 2 == 0 else RETREAT
+
+
+def _majority(values: list[str]) -> str:
+    counts = Counter(values)
+    return ATTACK if counts[ATTACK] > counts[RETREAT] else RETREAT  # Ties retreat.
+
+
+def oral_messages(
+    generals: int,
+    traitors: Set[int],
+    order: str,
+    *,
+    rounds: int,
+    lie: Callable[[int, int, str], str] = _default_lie,
+) -> GeneralsResult:
+    """Run OM(rounds) with general 0 as commander.
+
+    Parameters
+    ----------
+    generals : int
+        Total number of generals n, at least 3; general 0 commands.
+    traitors : set of int
+        Traitorous generals; they send ``lie(sender, receiver, value)``
+        instead of the true value.
+    order : str
+        The commander's order, ``"attack"`` or ``"retreat"``.
+    rounds : int
+        The recursion depth m: OM(m) tolerates m traitors when n > 3m.
+    lie : callable
+        The traitors' strategy.
+
+    Returns
+    -------
+    GeneralsResult
+        Loyal lieutenants' decisions and whether IC1 and IC2 hold.
+
+    Examples
+    --------
+    >>> from blockchainkit.consensus import oral_messages
+    >>> oral_messages(4, {3}, "attack", rounds=1).decisions
+    {1: 'attack', 2: 'attack'}
+    """
+    integer(generals, "generals", 3)
+    integer(rounds, "rounds")
+    if order not in (ATTACK, RETREAT):
+        raise ValueError("order must be 'attack' or 'retreat'")
+    if any(t not in range(generals) for t in traitors):
+        raise ValueError("traitors must be general numbers")
+
+    def send(sender: int, receiver: int, value: str) -> str:
+        return lie(sender, receiver, value) if sender in traitors else value
+
+    def om(m: int, commander: int, value: str, lieutenants: list[int]) -> dict[int, str]:
+        received = {lt: send(commander, lt, value) for lt in lieutenants}
+        if m == 0:
+            return received
+        relayed = {
+            j: om(m - 1, j, received[j], [lt for lt in lieutenants if lt != j]) for j in lieutenants
+        }
+        return {
+            lt: _majority([received[lt]] + [relayed[j][lt] for j in lieutenants if j != lt])
+            for lt in lieutenants
+        }
+
+    result = om(rounds, 0, order, list(range(1, generals)))
+    loyal = {g: v for g, v in result.items() if g not in traitors}
+    agreement = len(set(loyal.values())) <= 1
+    validity = 0 in traitors or all(v == order for v in loyal.values())
+    return GeneralsResult(loyal, agreement, validity)

blockchainkit/consensus/systems/catch_up.py

@@ -0,0 +1,60 @@
+"""Idealized models of an attacker catching up with the honest chain."""
+
+from math import exp
+
+from blockchainkit._validation import integer
+
+
+def eventual_catch_up(attacker_fraction: float, deficit: int) -> float:
+    """Return eventual catch-up probability in an ideal infinite random walk.
+
+    For q<1/2 this is (q/(1-q))**deficit. This is NOT Nakamoto's finite-
+    confirmation Poisson model: there is no propagation delay or time bound.
+
+    >>> from blockchainkit.consensus import eventual_catch_up
+    >>> eventual_catch_up(0.25, 2)
+    0.1111111111111111
+    """
+    if isinstance(attacker_fraction, bool) or not isinstance(attacker_fraction, (int, float)):
+        raise TypeError("attacker_fraction must be a real number in [0, 1]")
+    if not 0 <= attacker_fraction <= 1:
+        raise ValueError("attacker_fraction must be in [0, 1]")
+    integer(deficit, "deficit")
+    if deficit == 0 or attacker_fraction >= 0.5:
+        return 1.0
+    return (attacker_fraction / (1 - attacker_fraction)) ** deficit
+
+
+def attacker_success_probability(attacker_fraction: float, confirmations: int) -> float:
+    """Return Nakamoto's probability that an attacker ever overtakes ``z`` confirmations.
+
+    While the honest chain gains z blocks, the attacker's progress is
+    approximately Poisson with mean ``lambda = z q / p``. From each possible
+    lead k, the attacker still needs to make up ``z - k`` blocks, which by
+    :func:`eventual_catch_up` happens with probability ``(q/p)**(z-k)``
+    (whitepaper, section 11):
+
+    ``P = 1 - sum_{k=0}^{z} e^(-lambda) lambda^k / k! * (1 - (q/p)^(z-k))``.
+
+    Examples
+    --------
+    >>> from blockchainkit.consensus import attacker_success_probability
+    >>> round(attacker_success_probability(0.1, 5), 7)
+    0.0009137
+    """
+    if isinstance(attacker_fraction, bool) or not isinstance(attacker_fraction, (int, float)):
+        raise TypeError("attacker_fraction must be a real number in [0, 1]")
+    if not 0 <= attacker_fraction <= 1:
+        raise ValueError("attacker_fraction must be in [0, 1]")
+    integer(confirmations, "confirmations")
+    q, z = attacker_fraction, confirmations
+    if q >= 0.5:
+        return 1.0
+    p = 1 - q
+    lam = z * q / p
+    total, poisson = 1.0, exp(-lam)
+    for k in range(z + 1):
+        if k:
+            poisson *= lam / k
+        total -= poisson * (1 - (q / p) ** (z - k))
+    return max(0.0, total)

blockchainkit/consensus/systems/difficulty.py

@@ -0,0 +1,74 @@
+"""Difficulty retargeting (Bitcoin 2009): hold the block interval steady as hashrate changes.
+
+The whitepaper (section 4) says proof-of-work difficulty is set by a moving
+average targeting an average number of blocks per hour. Bitcoin's first
+release recomputes the target every 2016 blocks, scaling it by the ratio of
+actual to expected time, clamped to a factor of four in either direction.
+"""
+
+from collections.abc import Sequence
+from random import Random
+
+from blockchainkit._validation import integer
+from blockchainkit._validation import seed as check_seed
+from blockchainkit.consensus.core.base import DifficultyRun
+
+_SCALE = 2**48
+
+
+def retarget(target: int, actual_time: int, expected_time: int) -> int:
+    """Return ``target * actual / expected``, clamped to ``[target/4, 4*target]``.
+
+    A larger target is easier. Blocks that came too fast shrink it.
+
+    >>> from blockchainkit.consensus import retarget
+    >>> retarget(1000, actual_time=600, expected_time=1200)
+    500
+    """
+    integer(target, "target", 1)
+    integer(actual_time, "actual_time", 1)
+    integer(expected_time, "expected_time", 1)
+    clamped = min(max(actual_time, expected_time // 4), expected_time * 4)
+    return max(1, target * clamped // expected_time)
+
+
+def simulate_difficulty(
+    hashrates: Sequence[float], *, interval: int = 600, window: int = 2016, seed: int = 0
+) -> DifficultyRun:
+    """Simulate block discovery with exponential waiting times and periodic retargets.
+
+    With target T, a block needs about ``2**48 / T`` hashes on average, so at
+    hashrate h its waiting time is exponential with mean ``2**48 / (T h)``.
+
+    Parameters
+    ----------
+    hashrates : sequence of float
+        The network hashrate while each successive block is mined.
+    interval : int
+        The target block time, in seconds.
+    window : int
+        Blocks between retargets.
+    seed : int
+        Seed for the waiting times.
+
+    Returns
+    -------
+    DifficultyRun
+        Each block's waiting time and the target it was mined under.
+    """
+    integer(interval, "interval", 1)
+    integer(window, "window", 1)
+    check_seed(seed)
+    if not hashrates or any(h <= 0 for h in hashrates):
+        raise ValueError("hashrates must be positive")
+    rng = Random(seed)
+    target = max(1, round(_SCALE / (interval * hashrates[0])))
+    times: list[float] = []
+    targets: list[int] = []
+    for height, rate in enumerate(hashrates):
+        targets.append(target)
+        times.append(rng.expovariate(target * rate / _SCALE))
+        if (height + 1) % window == 0:
+            actual = max(1, round(sum(times[-window:])))
+            target = retarget(target, actual, interval * window)
+    return DifficultyRun(tuple(times), tuple(targets))

blockchainkit/consensus/systems/finality.py

@@ -0,0 +1,92 @@
+"""Casper the Friendly Finality Gadget (Buterin and Griffith 2017).
+
+Validators with deposits vote for links between checkpoints, ``source ->
+target``. A checkpoint becomes *justified* when two thirds of the stake vote
+for a link to it from a justified source, and its source becomes *finalized*
+when the target is the very next checkpoint. Two slashing conditions make
+conflicting finality cost at least a third of all stake: never cast two
+different votes for the same target height, and never cast a vote that
+surrounds another.
+"""
+
+from collections.abc import Mapping
+
+from blockchainkit._validation import integer
+from blockchainkit.consensus.core.base import Offense
+
+Vote = tuple[int, int, bytes]
+
+
+class FinalityGadget:
+    """Track Casper FFG votes, justification, finality, and slashable offenses.
+
+    Checkpoint 0 (genesis) starts justified and finalized.
+
+    Parameters
+    ----------
+    stakes : Mapping
+        Each validator's deposit.
+
+    Examples
+    --------
+    >>> from blockchainkit.consensus import FinalityGadget
+    >>> ffg = FinalityGadget({"a": 1, "b": 1, "c": 1})
+    >>> for v in "abc":
+    ...     ffg.vote(v, source=0, target=1)
+    >>> sorted(ffg.justified)
+    [0, 1]
+    """
+
+    def __init__(self, stakes: Mapping[str, int]) -> None:
+        for weight in stakes.values():
+            integer(weight, "stake", 1)
+        self._stakes = dict(stakes)
+        self._total = sum(self._stakes.values())
+        self._votes: dict[str, list[Vote]] = {v: [] for v in self._stakes}
+        self._justified, self._finalized = {0}, {0}
+        self._offenses: list[Offense] = []
+
+    @property
+    def justified(self) -> frozenset[int]:
+        """Heights of justified checkpoints."""
+        return frozenset(self._justified)
+
+    @property
+    def finalized(self) -> frozenset[int]:
+        """Heights of finalized checkpoints."""
+        return frozenset(self._finalized)
+
+    @property
+    def slashable(self) -> tuple[Offense, ...]:
+        """Every pair of votes that breaks a slashing condition, in detection order."""
+        return tuple(self._offenses)
+
+    def vote(self, validator: str, source: int, target: int, checkpoint: bytes = b"") -> None:
+        """Record a vote for the link ``source -> target`` and update finality.
+
+        ``checkpoint`` distinguishes conflicting blocks at the same height.
+        """
+        if validator not in self._stakes:
+            raise ValueError(f"unknown validator {validator!r}")
+        integer(source, "source")
+        integer(target, "target", source + 1)
+        new = (source, target, checkpoint)
+        for old in self._votes[validator]:
+            if old == new:
+                return
+            if old[1] == target:
+                self._offenses.append(Offense(validator, "double vote", old, new))
+            elif old[0] < source and target < old[1] or source < old[0] and old[1] < target:
+                self._offenses.append(Offense(validator, "surround vote", old, new))
+        self._votes[validator].append(new)
+        if source not in self._justified:
+            return
+        support = sum(
+            self._stakes[v]
+            for v, votes in self._votes.items()
+            if any(vote == new for vote in votes)
+        )
+        if 3 * support >= 2 * self._total:
+            self._justified.add(target)
+            if target == source + 1:
+                self._finalized.add(source)

blockchainkit/consensus/systems/fork_choice.py

@@ -0,0 +1,44 @@
+"""GHOST fork choice (Sompolinsky and Zohar 2013): follow the heaviest subtree.
+
+When blocks are frequent, many honest blocks end up off the longest chain,
+and that wasted work no longer protects it. GHOST (Greedy Heaviest Observed
+SubTree) walks from genesis and at each fork picks the child whose whole
+subtree carries the most work, counting the honest side branches too.
+Ethereum's proof-of-work chain used a variant through uncle rewards.
+"""
+
+from blockchainkit.consensus.systems.pow import expected_trials
+from blockchainkit.structures.systems.block import Block
+from blockchainkit.structures.systems.chain import Blockchain
+
+
+def _children(chain: Blockchain) -> dict[bytes, list[Block]]:
+    children: dict[bytes, list[Block]] = {}
+    for block in chain.blocks.values():
+        if block.height:
+            children.setdefault(block.previous_hash, []).append(block)
+    return children
+
+
+def subtree_work(chain: Blockchain, block_hash: bytes) -> int:
+    """Return the expected work of a block and all its descendants."""
+    children = _children(chain)
+    stack, total = [chain.blocks[block_hash]], 0
+    while stack:
+        block = stack.pop()
+        total += expected_trials(block.difficulty)
+        stack.extend(children.get(block.hash, []))
+    return total
+
+
+def ghost_tip(chain: Blockchain) -> Block:
+    """Return the tip chosen by GHOST: descend into the heaviest subtree at every fork.
+
+    Ties go to the smaller hash, matching
+    :class:`~blockchainkit.structures.systems.chain.Blockchain`.
+    """
+    children = _children(chain)
+    block = chain.canonical_blocks()[0]
+    while children.get(block.hash):
+        block = min(children[block.hash], key=lambda c: (-subtree_work(chain, c.hash), c.hash))
+    return block