blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/consensus/systems/pbft.py

@@ -0,0 +1,78 @@
+"""Practical Byzantine Fault Tolerance (Castro and Liskov 1999): the normal-case round.
+
+With n = 3f + 1 replicas, any two quorums of 2f + 1 overlap in at least f + 1
+replicas, so at least one honest replica is in both. A replica *prepares* a
+value after 2f matching prepare messages and *commits* it after 2f + 1
+matching commits. Two honest replicas can then never commit different values
+in one view, even if the leader equivocates, as long as at most f replicas
+are faulty.
+"""
+
+from collections.abc import Set
+
+from blockchainkit._validation import integer
+from blockchainkit.consensus.core.base import PBFTResult
+
+
+def quorum_size(replicas: int) -> int:
+    """Return 2f + 1 for the largest f with n >= 3f + 1.
+
+    >>> from blockchainkit.consensus import quorum_size
+    >>> quorum_size(4), quorum_size(7)
+    (3, 5)
+    """
+    integer(replicas, "replicas", 4)
+    return 2 * ((replicas - 1) // 3) + 1
+
+
+def pbft_round(
+    replicas: int, faulty: Set[int], value: str, *, equivocate: bool = False, other: str = "B"
+) -> PBFTResult:
+    """Run one PBFT pre-prepare / prepare / commit exchange with leader 0.
+
+    Faulty replicas send prepare and commit messages for *both* values to
+    everyone, the most confusing thing they can do. A faulty leader with
+    ``equivocate=True`` pre-prepares ``value`` to the first half of the honest
+    replicas and ``other`` to the rest.
+
+    Parameters
+    ----------
+    replicas : int
+        Number of replicas n, at least 4.
+    faulty : set of int
+        Faulty replica numbers. The protocol is sized for f = (n - 1) // 3;
+        pass more to see safety fail.
+    value, other : str
+        The leader's value, and the conflicting one an equivocating leader
+        also sends.
+
+    Returns
+    -------
+    PBFTResult
+        What each honest replica prepared and committed.
+    """
+    f = (quorum_size(replicas) - 1) // 2
+    if any(r not in range(replicas) for r in faulty):
+        raise ValueError("faulty replicas must be replica numbers")
+    honest = [r for r in range(replicas) if r not in faulty]
+    faulty_backups = len(faulty - {0})
+
+    # 1. Pre-prepare: the leader (replica 0) proposes a value to each replica.
+    equivocating = 0 in faulty and equivocate
+    split = (len(honest) + 1) // 2
+    proposal = {r: other if equivocating and i >= split else value for i, r in enumerate(honest)}
+
+    # 2. Prepare: honest backups echo their proposal; faulty backups echo both values.
+    def prepares(v: str) -> int:
+        return sum(1 for r in honest if r != 0 and proposal[r] == v) + faulty_backups
+
+    prepared = {r: proposal[r] if prepares(proposal[r]) >= 2 * f else None for r in honest}
+
+    # 3. Commit: honest replicas commit what they prepared; faulty ones commit both.
+    def commits(v: str) -> int:
+        return sum(1 for r in honest if prepared[r] == v) + len(faulty)
+
+    committed = {
+        r: v if v is not None and commits(v) >= 2 * f + 1 else None for r, v in prepared.items()
+    }
+    return PBFTResult(prepared, committed)

blockchainkit/consensus/systems/pos.py

@@ -0,0 +1,53 @@
+"""Stake-weighted proposer sampling, not a complete PoS consensus protocol."""
+
+from bisect import bisect_right
+from collections.abc import Mapping
+from itertools import accumulate
+from random import Random
+
+from blockchainkit._validation import integer
+from blockchainkit._validation import seed as check_seed
+
+
+class StakeSampler:
+    """Select proposers with exact integer weights and reproducible randomness.
+
+    Parameters
+    ----------
+    stakes : Mapping
+        Nonnegative weights with a positive total. Names are sorted so mapping
+        insertion order does not alter results.
+    seed : int
+        Simulation seed, not an unpredictable consensus randomness beacon.
+
+    Examples
+    --------
+    >>> from blockchainkit.consensus import StakeSampler
+    >>> StakeSampler({"alice": 1, "bob": 0}, seed=7).sample(3)
+    ('alice', 'alice', 'alice')
+    """
+
+    def __init__(self, stakes: Mapping[str, int], *, seed: int = 0) -> None:
+        check_seed(seed)
+        if not stakes or any(not isinstance(name, str) or not name for name in stakes):
+            raise ValueError("provide nonempty validator names")
+        for weight in stakes.values():
+            integer(weight, "stake")
+        self._stakes = tuple(sorted(stakes.items()))
+        self._total = sum(stakes.values())
+        if self._total == 0:
+            raise ValueError("total stake must be positive")
+        self._cumulative = tuple(accumulate(weight for _, weight in self._stakes))
+        self._random = Random(seed)
+
+    def choose(self) -> str:
+        """Select one validator with probability stake / total stake."""
+        ticket = self._random.randrange(self._total)
+        # ticket < total guarantees an index inside the cumulative weights.
+        # bisect_right skips repeated boundaries from zero-weight validators.
+        return self._stakes[bisect_right(self._cumulative, ticket)][0]
+
+    def sample(self, rounds: int) -> tuple[str, ...]:
+        """Return proposers for a bounded number of rounds."""
+        integer(rounds, "rounds")
+        return tuple(self.choose() for _ in range(rounds))

blockchainkit/consensus/systems/pow.py

@@ -0,0 +1,58 @@
+"""Bounded proof-of-work experiments with explicit success probabilities."""
+
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+from blockchainkit._validation import integer
+from blockchainkit.consensus.core.base import MiningResult
+from blockchainkit.constants import UINT64_LIMIT
+from blockchainkit.crypto.systems.hashing import sha256
+
+if TYPE_CHECKING:
+    from blockchainkit.structures.systems.block import Block
+
+
+def target(difficulty: int) -> int:
+    """Return the inclusive target for a leading-zero-bit difficulty.
+
+    >>> from blockchainkit.consensus import target
+    >>> target(0) == 2**256 - 1
+    True
+    """
+    integer(difficulty, "difficulty")
+    if difficulty > 256:
+        raise ValueError("difficulty cannot exceed 256")
+    return (1 << (256 - difficulty)) - 1
+
+
+def expected_trials(difficulty: int) -> int:
+    """Return 2**difficulty, assuming independent uniform 256-bit hashes."""
+    target(difficulty)
+    return 1 << difficulty
+
+
+def valid_pow(block: "Block") -> bool:
+    """Check that the block hash, interpreted big-endian, is at most its target."""
+    return int.from_bytes(block.hash, "big") <= target(block.difficulty)
+
+
+def mine(block: "Block", *, max_attempts: int = 100_000) -> MiningResult:
+    """Search sequential nonces starting at block.nonce, with a strict bound.
+
+    Raises
+    ------
+    TimeoutError
+        No solution was found within max_attempts (not evidence of no solution).
+    ValueError
+        The search would exceed the 64-bit nonce space.
+    """
+    integer(max_attempts, "max_attempts", 1)
+    if block.nonce + max_attempts > UINT64_LIMIT:
+        raise ValueError("search exceeds the 64-bit nonce space")
+    limit = target(block.difficulty)
+    # Only the header changes between attempts; the Merkle root is computed once.
+    for attempt in range(max_attempts):
+        nonce = block.nonce + attempt
+        if int.from_bytes(sha256(block.header(nonce=nonce)), "big") <= limit:
+            return MiningResult(replace(block, nonce=nonce), attempt + 1)
+    raise TimeoutError(f"no solution in {max_attempts} attempts")

blockchainkit/consensus/systems/pricing.py

@@ -0,0 +1,50 @@
+"""Pricing via processing (Dwork and Naor 1992): make each message cost computation.
+
+To fight junk mail, Dwork and Naor proposed that a sender compute a
+*pricing function*, moderately hard to evaluate but easy to check, for each
+message. One of their examples is a square root modulo a prime: computing
+it takes an exponentiation, checking it takes one multiplication.
+Back's Hashcash later used hash preimages for the same purpose, and
+Bitcoin's proof of work descends from that.
+"""
+
+from blockchainkit._validation import integer
+from blockchainkit.consensus.core.base import SquareRootResult
+from blockchainkit.crypto.utils.primes import is_prime
+
+
+def modular_square_root(value: int, prime: int) -> SquareRootResult:
+    """Compute a square root modulo a prime ``p = 3 (mod 4)``, counting multiplications.
+
+    For such primes, ``value**((p + 1) / 4)`` is a square root of any
+    quadratic residue. Square-and-multiply needs about ``1.5 log2 p``
+    multiplications; checking the answer needs one.
+
+    Raises
+    ------
+    ValueError
+        ``prime`` is not a prime congruent to 3 modulo 4, or ``value`` has no
+        square root (it is not a quadratic residue).
+
+    Examples
+    --------
+    >>> from blockchainkit.consensus import modular_square_root
+    >>> result = modular_square_root(4, 7)
+    >>> result.root ** 2 % 7
+    4
+    """
+    integer(value, "value")
+    integer(prime, "prime", 3)
+    if not is_prime(prime) or prime % 4 != 3:
+        raise ValueError("prime must be a prime congruent to 3 modulo 4")
+    exponent, base, root, multiplications = (prime + 1) // 4, value % prime, 1, 0
+    while exponent:
+        if exponent & 1:
+            root = root * base % prime
+            multiplications += 1
+        base = base * base % prime
+        multiplications += 1
+        exponent >>= 1
+    if root * root % prime != value % prime:
+        raise ValueError("value is not a quadratic residue modulo prime")
+    return SquareRootResult(root, multiplications)

blockchainkit/consensus/systems/randomized.py

@@ -0,0 +1,114 @@
+"""Ben-Or's randomized consensus (1983), and the FLP impossibility (1985) it sidesteps.
+
+Fischer, Lynch and Paterson proved that no *deterministic* protocol can
+guarantee agreement in an asynchronous network if even one process may
+crash: an adversary scheduling message delivery can keep it undecided
+forever. Ben-Or's protocol escapes by tossing coins. In each round processes
+exchange values, propose a strong majority if they see one, and adopt a
+proposal or flip a coin. Whatever the schedule, the coins eventually line up.
+"""
+
+from collections.abc import Callable, Sequence
+from random import Random
+
+from blockchainkit._validation import integer
+from blockchainkit._validation import seed as check_seed
+from blockchainkit.consensus.core.base import ConsensusRun
+
+_UNDECIDED = -1
+
+
+def _adversarial_pick(values: dict[int, int], quota: int, favor_mixed: bool) -> list[int]:
+    """Choose ``quota`` senders that keep the receiver as undecided as possible."""
+    ones = [p for p, v in values.items() if v == 1]
+    zeros = [p for p, v in values.items() if v == 0]
+    others = [p for p, v in values.items() if v not in (0, 1)]
+    if favor_mixed:  # Phase 1: alternate values so no strong majority appears.
+        order: list[int] = []
+        while zeros or ones:
+            for group in (zeros, ones):
+                if group:
+                    order.append(group.pop())
+        return order[:quota]
+    return (others + zeros + ones)[:quota]  # Phase 2: as few concrete proposals as possible.
+
+
+def ben_or(
+    initial: Sequence[int],
+    faults: int,
+    *,
+    coin: Callable[[int, int], int] | None = None,
+    adversarial: bool = True,
+    seed: int = 0,
+    max_rounds: int = 1000,
+) -> ConsensusRun:
+    """Run Ben-Or's binary consensus for crash faults (n > 2f).
+
+    Each process waits for ``n - f`` messages per phase, the most it can
+    wait for when f processes may have crashed; the scheduler chooses which.
+
+    Parameters
+    ----------
+    initial : sequence of int
+        Each process's input bit.
+    faults : int
+        The number of crashes f the protocol is sized for.
+    coin : callable, optional
+        ``coin(process, round) -> 0 or 1``. Defaults to a seeded fair coin.
+        Pass a deterministic function to see the FLP adversary win.
+    adversarial : bool
+        If True, the scheduler delivers the messages most likely to delay a
+        decision; otherwise a random ``n - f`` subset.
+    seed : int
+        Seed for the coin and the random scheduler.
+    max_rounds : int
+        Give up after this many rounds.
+
+    Returns
+    -------
+    ConsensusRun
+        Decisions so far, rounds run, and whether every process decided.
+
+    Examples
+    --------
+    >>> from blockchainkit.consensus import ben_or
+    >>> ben_or([1, 1, 1], faults=1).decisions
+    {0: 1, 1: 1, 2: 1}
+    """
+    n = len(initial)
+    integer(faults, "faults")
+    integer(max_rounds, "max_rounds", 1)
+    check_seed(seed)
+    if n <= 2 * faults:
+        raise ValueError("Ben-Or needs n > 2f processes")
+    if any(v not in (0, 1) for v in initial):
+        raise ValueError("inputs must be bits")
+    rng = Random(seed)
+    flip = coin or (lambda process, round_: rng.getrandbits(1))
+    quota = n - faults
+    values = dict(enumerate(initial))
+    decisions: dict[int, int] = {}
+    for round_ in range(1, max_rounds + 1):
+        proposals = {}
+        for p in range(n):
+            heard = (
+                _adversarial_pick(dict(values), quota, True)
+                if adversarial
+                else rng.sample(range(n), quota)
+            )
+            counts = [sum(values[q] == bit for q in heard) for bit in (0, 1)]
+            strong = [bit for bit in (0, 1) if counts[bit] > n / 2]
+            proposals[p] = strong[0] if strong else _UNDECIDED
+        for p in range(n):
+            heard = (
+                _adversarial_pick(dict(proposals), quota, False)
+                if adversarial
+                else rng.sample(range(n), quota)
+            )
+            seen = [proposals[q] for q in heard if proposals[q] != _UNDECIDED]
+            if seen and len(seen) >= faults + 1:
+                decisions.setdefault(p, seen[0])
+            values[p] = seen[0] if seen else flip(p, round_)
+        if len(decisions) == n:
+            return ConsensusRun(decisions, round_, True)
+    return ConsensusRun(decisions, max_rounds, False)

blockchainkit/consensus/systems/selfish.py

@@ -0,0 +1,81 @@
+"""Selfish mining (Eyal and Sirer 2014): majority is not enough.
+
+A pool that withholds the blocks it finds, and publishes them only to
+overtake or tie the honest chain, wastes the honest miners' work. Above a
+threshold hashrate its share of the chain exceeds its share of the hashrate,
+so honest miners gain by joining it. ``gamma`` is the fraction of honest
+miners who build on the pool's block during a tie.
+"""
+
+from random import Random
+
+from blockchainkit._validation import integer
+from blockchainkit._validation import seed as check_seed
+from blockchainkit.consensus.core.base import SelfishMiningResult
+
+
+def _check(alpha: float, gamma: float) -> None:
+    if not 0 < alpha < 0.5:
+        raise ValueError("alpha must be in (0, 0.5)")
+    if not 0 <= gamma <= 1:
+        raise ValueError("gamma must be in [0, 1]")
+
+
+def selfish_mining_revenue(alpha: float, gamma: float) -> float:
+    """Return the selfish pool's long-run share of blocks (Eyal and Sirer, eq. 8).
+
+    ``R = (alpha (1-alpha)**2 (4 alpha + gamma (1 - 2 alpha)) - alpha**3)
+    / (1 - alpha (1 + (2 - alpha) alpha))``
+
+    >>> from blockchainkit.consensus import selfish_mining_revenue
+    >>> round(selfish_mining_revenue(0.4, 0.0), 3)
+    0.484
+    """
+    _check(alpha, gamma)
+    a = alpha
+    numerator = a * (1 - a) ** 2 * (4 * a + gamma * (1 - 2 * a)) - a**3
+    return float(numerator / (1 - a * (1 + (2 - a) * a)))
+
+
+def selfish_mining_threshold(gamma: float) -> float:
+    """Return the hashrate above which selfish mining pays: ``(1 - gamma) / (3 - 2 gamma)``."""
+    if not 0 <= gamma <= 1:
+        raise ValueError("gamma must be in [0, 1]")
+    return (1 - gamma) / (3 - 2 * gamma)
+
+
+def simulate_selfish_mining(
+    alpha: float, gamma: float, *, blocks: int, seed: int = 0
+) -> SelfishMiningResult:
+    """Simulate the selfish-mining state machine (Eyal and Sirer, Algorithm 1).
+
+    Each event, the pool finds a block with probability alpha, otherwise the
+    honest network does. The state is the pool's private lead, plus a tie
+    state after the pool publishes to match an honest block.
+    """
+    _check(alpha, gamma)
+    integer(blocks, "blocks", 1)
+    check_seed(seed)
+    rng = Random(seed)
+    lead, tie, selfish, honest = 0, False, 0, 0
+    for _ in range(blocks):
+        pool_found = rng.random() < alpha
+        if tie:
+            if pool_found:
+                selfish += 2  # The pool extends its own branch and wins both blocks.
+            elif rng.random() < gamma:
+                selfish, honest = selfish + 1, honest + 1  # Honest block on the pool's branch.
+            else:
+                honest += 2  # Honest block on the honest branch.
+            tie = False
+        elif pool_found:
+            lead += 1
+        elif lead == 0:
+            honest += 1
+        elif lead == 1:
+            lead, tie = 0, True  # Publish and race.
+        elif lead == 2:
+            lead, selfish = 0, selfish + 2  # Publish both and orphan the honest block.
+        else:
+            lead, selfish = lead - 1, selfish + 1  # Reveal one block; stay ahead.
+    return SelfishMiningResult(selfish, honest, selfish / max(1, selfish + honest))

blockchainkit/consensus/systems/sortition.py

@@ -0,0 +1,48 @@
+"""Cryptographic sortition (Algorand 2017): secret, stake-weighted committee selection.
+
+Algorand picks each round's committee by lottery. Every unit of stake is a
+ticket; a user hashes a round seed with their private key (in Algorand a
+verifiable random function, so others can check the result) and maps the
+hash to a number of selected tickets that is Binomial(stake, tau / W).
+Nobody, not even the user, knows who is on the committee before they speak,
+and splitting stake across accounts does not change the expected seats.
+"""
+
+from math import comb
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import SORTITION_DOMAIN
+from blockchainkit.crypto.systems.hashing import sha256
+
+
+def sortition(
+    secret: bytes, stake: int, total_stake: int, expected: int, *, round_seed: bytes
+) -> int:
+    """Return how many of a user's stake units are selected this round.
+
+    The hash of ``secret || round_seed``, read as a uniform number in [0, 1),
+    is located in the cumulative Binomial(stake, expected / total_stake)
+    distribution. Teaching simplification: a hash of the secret replaces
+    the verifiable random function, so others cannot verify the draw.
+
+    Examples
+    --------
+    >>> from blockchainkit.consensus import sortition
+    >>> sortition(b"my key", 0, 1000, 20, round_seed=b"r1")
+    0
+    """
+    if not isinstance(secret, bytes) or not isinstance(round_seed, bytes):
+        raise TypeError("secret and round_seed must be bytes")
+    integer(stake, "stake")
+    integer(total_stake, "total_stake", 1)
+    integer(expected, "expected", 1)
+    if stake > total_stake or expected > total_stake:
+        raise ValueError("stake and expected committee size cannot exceed total stake")
+    draw = int.from_bytes(sha256(SORTITION_DOMAIN + secret + round_seed), "big") / 2**256
+    p = expected / total_stake
+    cumulative = 0.0
+    for j in range(stake):
+        cumulative += comb(stake, j) * p**j * (1 - p) ** (stake - j)
+        if draw < cumulative:
+            return j
+    return stake  # The last bucket, which also absorbs floating-point rounding.

blockchainkit/consensus/systems/stake_games.py

@@ -0,0 +1,44 @@
+"""The nothing-at-stake problem (Buterin 2014): voting on every fork is free.
+
+A proof-of-work miner must split its hashrate between forks. A proof-of-stake
+validator can sign blocks on every fork at no cost, and collect the reward
+whichever fork wins. If everyone does, forks never resolve. The remedy,
+first proposed in Buterin's Slasher, is a penalty: evidence of signing two
+conflicting blocks destroys the validator's deposit.
+"""
+
+
+def fork_voting_payoffs(
+    fork_a_probability: float, reward: float, penalty: float
+) -> dict[str, float]:
+    """Expected payoff of voting for fork A, fork B, or both.
+
+    Parameters
+    ----------
+    fork_a_probability : float
+        Chance that fork A becomes canonical.
+    reward : float
+        Reward for having voted on the winning fork.
+    penalty : float
+        Deposit destroyed when a validator is caught voting on both (slashing).
+
+    Returns
+    -------
+    dict
+        Expected payoff of the strategies ``"A"``, ``"B"`` and ``"both"``.
+
+    Examples
+    --------
+    >>> from blockchainkit.consensus import fork_voting_payoffs
+    >>> fork_voting_payoffs(0.5, 1.0, 0.0)
+    {'A': 0.5, 'B': 0.5, 'both': 1.0}
+    """
+    if not 0 <= fork_a_probability <= 1:
+        raise ValueError("fork_a_probability must be in [0, 1]")
+    if reward < 0 or penalty < 0:
+        raise ValueError("reward and penalty must be non-negative")
+    return {
+        "A": fork_a_probability * reward,
+        "B": (1 - fork_a_probability) * reward,
+        "both": reward - penalty,
+    }

blockchainkit/consensus/systems/synchrony.py

@@ -0,0 +1,49 @@
+"""Partial synchrony (Dwork, Lynch and Stockmeyer 1988): progress after an unknown GST.
+
+Real networks are neither synchronous (known delay bound) nor fully
+asynchronous (FLP applies). Partial synchrony assumes a bound Delta holds
+after some unknown Global Stabilization Time (GST). Protocols stay safe
+always, and make progress once a leader's view lasts long enough: doubling
+the timeout each view guarantees that eventually it exceeds Delta.
+"""
+
+from blockchainkit._validation import integer
+from blockchainkit.consensus.core.base import ViewChangeRun
+
+
+def view_changes(
+    gst: int, delta: int, base_timeout: int, *, growth: int = 2, max_views: int = 64
+) -> ViewChangeRun:
+    """Simulate leader views with growing timeouts until one makes progress.
+
+    Before GST the adversary delays the leader's message past every timeout;
+    from GST on it arrives after ``delta`` ticks. View v lasts
+    ``base_timeout * growth**v`` and succeeds when it starts at or after GST
+    and its timeout is at least ``delta``.
+
+    Raises
+    ------
+    TimeoutError
+        No view succeeded within ``max_views`` (for example, timeouts that
+        never grow past delta).
+
+    Examples
+    --------
+    >>> from blockchainkit.consensus import view_changes
+    >>> view_changes(gst=10, delta=5, base_timeout=1).decided_view
+    4
+    """
+    integer(gst, "gst")
+    integer(delta, "delta", 1)
+    integer(base_timeout, "base_timeout", 1)
+    integer(growth, "growth", 1)
+    integer(max_views, "max_views", 1)
+    starts, timeouts, time = [], [], 0
+    for view in range(max_views):
+        timeout = base_timeout * growth**view
+        starts.append(time)
+        timeouts.append(timeout)
+        if time >= gst and delta <= timeout:
+            return ViewChangeRun(tuple(starts), tuple(timeouts), view, time + delta)
+        time += timeout
+    raise TimeoutError(f"no view made progress in {max_views} views")

blockchainkit/consensus/visualizers/__init__.py

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

blockchainkit/consensus/visualizers/plots.py

@@ -0,0 +1,80 @@
+"""Plotting helpers for blockchainkit.consensus: mining effort and stake weighting."""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Mapping, Sequence
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.axes import Axes
+
+__all__ = ["plot_mining_trials", "plot_stake_shares"]
+
+
+def plot_mining_trials(
+    difficulties: Sequence[int], attempts: Sequence[int], ax: Axes | None = None
+) -> Axes:
+    """Compare measured hash attempts with the expected 2**difficulty.
+
+    Parameters
+    ----------
+    difficulties : sequence of int
+        Difficulty of each mined block.
+    attempts : sequence of int
+        Hash attempts each search needed (``MiningResult.attempts``).
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if len(difficulties) != len(attempts):
+        raise ValueError("difficulties and attempts must have the same length")
+    if ax is None:
+        _, ax = plt.subplots()
+    ax.scatter(difficulties, attempts, color="#2563eb", alpha=0.6, label="measured")
+    grid = np.arange(min(difficulties), max(difficulties) + 1)
+    ax.plot(grid, 2.0**grid, color="black", label="expected 2^d")
+    ax.set_yscale("log", base=2)
+    ax.set_xlabel("difficulty d (leading zero bits)")
+    ax.set_ylabel("hash attempts")
+    ax.set_title("Each extra zero bit doubles the expected work")
+    ax.legend()
+    return ax
+
+
+def plot_stake_shares(
+    stakes: Mapping[str, int], proposers: Sequence[str], ax: Axes | None = None
+) -> Axes:
+    """Compare each validator's stake fraction with its observed proposer fraction.
+
+    Parameters
+    ----------
+    stakes : Mapping
+        Validator weights, as given to :class:`~blockchainkit.consensus.systems.pos.StakeSampler`.
+    proposers : sequence of str
+        Sampled proposers, e.g. from ``StakeSampler.sample``.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if not proposers:
+        raise ValueError("need at least one sampled proposer")
+    if ax is None:
+        _, ax = plt.subplots()
+    names = sorted(stakes)
+    total = sum(stakes.values())
+    counts = Counter(proposers)
+    xs = np.arange(len(names))
+    ax.bar(xs - 0.18, [stakes[n] / total for n in names], 0.36, label="stake fraction")
+    ax.bar(xs + 0.18, [counts[n] / len(proposers) for n in names], 0.36, label="proposer fraction")
+    ax.set_xticks(xs, names)
+    ax.set_ylabel("fraction")
+    ax.set_title(f"Stake-weighted selection over {len(proposers)} rounds")
+    ax.legend()
+    return ax