blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/structures/systems/utxo.py

@@ -0,0 +1,156 @@
+"""The unspent-transaction-output (UTXO) model of Bitcoin (2008).
+
+There are no accounts. Value lives in *coins*, outputs of earlier
+transactions, each owned by an address. A transaction consumes whole coins
+as inputs and creates new ones as outputs; any value not assigned to an
+output is the miner's fee. A coin can be spent once: double spending is
+the attempt to use one input twice.
+"""
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field, replace
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import UINT64_LIMIT, UTXO_DOMAIN
+from blockchainkit.crypto.core.base import SchnorrSignature
+from blockchainkit.crypto.systems.curves import public_key
+from blockchainkit.crypto.systems.hashing import sha256
+from blockchainkit.crypto.systems.signatures import deterministic_nonce, sign, verify
+from blockchainkit.structures.core.base import Coin, OutPoint
+from blockchainkit.structures.systems.transaction import address
+from blockchainkit.structures.utils.accounts import is_account_id
+from blockchainkit.structures.utils.encoding import canonical_json
+
+
+@dataclass(frozen=True)
+class UTXOTransaction:
+    """Spend whole coins and create new ones.
+
+    Parameters
+    ----------
+    inputs : tuple of OutPoint
+        Coins to consume, each at most once.
+    outputs : tuple
+        ``(owner_address, amount)`` pairs; amounts are positive integers.
+    witnesses : tuple
+        One ``(public_key, SchnorrSignature)`` per input, added by
+        :meth:`signed`.
+    """
+
+    inputs: tuple[OutPoint, ...]
+    outputs: tuple[tuple[str, int], ...]
+    witnesses: tuple[tuple[tuple[int, int], SchnorrSignature], ...] = field(default=())
+
+    def __post_init__(self) -> None:
+        if not self.inputs or not self.outputs:
+            raise ValueError("a transaction needs inputs and outputs")
+        if len(set(self.inputs)) != len(self.inputs):
+            raise ValueError("an input cannot be listed twice")
+        for owner, amount in self.outputs:
+            if not is_account_id(owner):
+                raise ValueError("output owners must be account identifiers")
+            integer(amount, "amount", 1)
+            if amount >= UINT64_LIMIT:
+                raise ValueError("amounts must fit unsigned 64-bit integers")
+
+    def payload(self) -> bytes:
+        """Return the bytes each input's owner signs."""
+        return canonical_json(
+            {
+                "domain": UTXO_DOMAIN,
+                "inputs": [[i.txid.hex(), i.index] for i in self.inputs],
+                "outputs": [list(o) for o in self.outputs],
+            }
+        )
+
+    @property
+    def txid(self) -> bytes:
+        """Return the hash of the unsigned payload; outputs are named by it."""
+        return sha256(self.payload())
+
+    def signed(self, privates: Sequence[int]) -> "UTXOTransaction":
+        """Return a copy with one signature per input, keys given in input order.
+
+        Each witness is the signer's public key and a Schnorr signature over
+        :meth:`payload` with an RFC 6979 nonce. Whether the key owns the coin
+        is checked by :meth:`UTXOSet.apply`.
+        """
+        if len(privates) != len(self.inputs):
+            raise ValueError("give exactly one private key per input")
+        payload = self.payload()
+        witnesses = tuple(
+            (public_key(x), sign(payload, x, nonce=deterministic_nonce(x, payload)))
+            for x in privates
+        )
+        return replace(self, witnesses=witnesses)
+
+    def fee(self, utxos: "UTXOSet") -> int:
+        """Return inputs minus outputs: what the miner may claim."""
+        return sum(utxos[i].amount for i in self.inputs) - sum(a for _, a in self.outputs)
+
+
+class UTXOSet:
+    """An immutable set of unspent coins; applying a transaction returns a new set.
+
+    Examples
+    --------
+    >>> import blockchainkit as bk
+    >>> alice = bk.structures.address(bk.crypto.public_key(7))
+    >>> bk.structures.UTXOSet.genesis({alice: 50}).balance(alice)
+    50
+    """
+
+    def __init__(self, coins: Mapping[OutPoint, Coin]) -> None:
+        self._coins = dict(coins)
+
+    @classmethod
+    def genesis(cls, allocations: Mapping[str, int]) -> "UTXOSet":
+        """Create one coin per address from an initial allocation."""
+        coins = {}
+        for index, (owner, amount) in enumerate(sorted(allocations.items())):
+            coins[OutPoint(sha256(b"genesis"), index)] = Coin(owner, amount)
+        return cls(coins)
+
+    def __getitem__(self, outpoint: OutPoint) -> Coin:
+        return self._coins[outpoint]
+
+    def __contains__(self, outpoint: object) -> bool:
+        return outpoint in self._coins
+
+    def __len__(self) -> int:
+        return len(self._coins)
+
+    def __repr__(self) -> str:
+        return f"UTXOSet(coins={len(self)}, total={sum(c.amount for c in self._coins.values())})"
+
+    def coins_of(self, owner: str) -> tuple[OutPoint, ...]:
+        """Return the outpoints of every coin an address owns, sorted."""
+        return tuple(sorted(o for o, coin in self._coins.items() if coin.owner == owner))
+
+    def balance(self, owner: str) -> int:
+        """Return the total value of an address's coins (a wallet's view)."""
+        return sum(self._coins[o].amount for o in self.coins_of(owner))
+
+    def apply(self, tx: UTXOTransaction) -> "UTXOSet":
+        """Validate a transaction and return the set after it.
+
+        Raises
+        ------
+        ValueError
+            An input is spent or unknown, a witness is missing or does not
+            match the coin's owner, or outputs exceed inputs.
+        """
+        if len(tx.witnesses) != len(tx.inputs):
+            raise ValueError("every input needs a signature")
+        for outpoint, (key, signature) in zip(tx.inputs, tx.witnesses, strict=True):
+            if outpoint not in self._coins:
+                raise ValueError(f"{outpoint} is not an unspent output")
+            owner = self._coins[outpoint].owner
+            if address(key) != owner or not verify(tx.payload(), signature, key):
+                raise ValueError(f"bad signature for {outpoint}")
+        if tx.fee(self) < 0:
+            raise ValueError("outputs exceed inputs")
+        coins = {o: c for o, c in self._coins.items() if o not in tx.inputs}
+        for index, (owner, amount) in enumerate(tx.outputs):
+            coins[OutPoint(tx.txid, index)] = Coin(owner, amount)
+        return UTXOSet(coins)

blockchainkit/structures/utils/__init__.py

@@ -0,0 +1,6 @@
+"""Encoding and identifier helpers that support the authenticated data structures."""
+
+from blockchainkit.structures.utils.accounts import is_account_id
+from blockchainkit.structures.utils.encoding import canonical_json
+
+__all__ = ["canonical_json", "is_account_id"]

blockchainkit/structures/utils/accounts.py

@@ -0,0 +1,13 @@
+"""Account identifiers: 64 lowercase hex characters, the SHA-256 of a public key."""
+
+_HEX = frozenset("0123456789abcdef")
+
+
+def is_account_id(value: object) -> bool:
+    """Return whether ``value`` has the shape of an account identifier.
+
+    >>> from blockchainkit.structures.utils import is_account_id
+    >>> is_account_id("ab" * 32), is_account_id("AB" * 32)
+    (True, False)
+    """
+    return isinstance(value, str) and len(value) == 64 and _HEX.issuperset(value)

blockchainkit/structures/utils/encoding.py

@@ -0,0 +1,11 @@
+"""Deterministic byte encodings for hashing and signing records."""
+
+import json
+
+
+def canonical_json(value: object) -> bytes:
+    """Encode internal integer/string records as sorted compact UTF-8 JSON.
+
+    This is a package-specific encoding, not a general canonical-JSON standard.
+    """
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode()

blockchainkit/structures/visualizers/__init__.py

@@ -0,0 +1,13 @@
+"""Plotting helpers for blockchainkit.structures.
+
+Imports matplotlib, so ``import blockchainkit`` does not load this module;
+import it explicitly: ``from blockchainkit.structures.visualizers import ...``.
+"""
+
+from blockchainkit.structures.visualizers.plots import (
+    plot_block_tree,
+    plot_merkle_tree,
+    plot_proof_trace,
+)
+
+__all__ = ["plot_merkle_tree", "plot_proof_trace", "plot_block_tree"]

blockchainkit/structures/visualizers/plots.py

@@ -0,0 +1,154 @@
+"""Plotting helpers for blockchainkit.structures: Merkle trees, proof traces, block trees."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+
+from blockchainkit.structures.core.base import MerkleTrace
+from blockchainkit.structures.systems.chain import Blockchain
+from blockchainkit.structures.systems.merkle import MerkleTree
+
+__all__ = ["plot_merkle_tree", "plot_proof_trace", "plot_block_tree"]
+
+_PATH, _SIBLING, _OTHER = "#2563eb", "#ea580c", "#cbd5e1"
+
+
+def plot_merkle_tree(
+    tree: MerkleTree, *, highlight: int | None = None, ax: Axes | None = None
+) -> Axes:
+    """Draw every level of a Merkle tree, optionally highlighting one proof.
+
+    Parameters
+    ----------
+    tree : MerkleTree
+        A tree with at least one leaf.
+    highlight : int, optional
+        Leaf index whose authentication path (blue) and proof siblings
+        (orange) are colored: the siblings are exactly what a proof sends.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if tree.leaf_count == 0:
+        raise ValueError("cannot draw an empty tree")
+    if ax is None:
+        _, ax = plt.subplots(figsize=(max(6, 1.4 * tree.leaf_count), 1.3 * len(tree.levels) + 1))
+    width = len(tree.levels[0])
+    positions: list[list[float]] = [[i + 0.5 for i in range(width)]]
+    for level in tree.levels[1:]:
+        below = positions[-1]
+        positions.append(
+            [(below[2 * i] + below[min(2 * i + 1, len(below) - 1)]) / 2 for i in range(len(level))]
+        )
+    path = {}
+    if highlight is not None:
+        tree.proof(highlight)  # Validates the index.
+        position = highlight
+        for depth in range(len(tree.levels)):
+            path[(depth, position)] = _PATH
+            if (position ^ 1) < len(tree.levels[depth]):
+                path[(depth, position ^ 1)] = _SIBLING
+            position //= 2
+    for depth, level in enumerate(tree.levels):
+        for i, digest in enumerate(level):
+            x, y = positions[depth][i], depth
+            if depth + 1 < len(tree.levels):
+                ax.plot([x, positions[depth + 1][i // 2]], [y, y + 1], color="#94a3b8", zorder=1)
+            color = path.get((depth, i), _OTHER)
+            ink = "black" if color == _OTHER else "white"
+            ax.scatter([x], [y], s=900, color=color, zorder=2)
+            ax.text(
+                x, y, digest.hex()[:6], ha="center", va="center", fontsize=7, color=ink, zorder=3
+            )
+    top_x = positions[-1][0]
+    note = f"root = H(0x02 || count={tree.leaf_count} || top digest)"
+    ax.text(top_x, len(tree.levels) - 0.55, note, ha="center", fontsize=9)
+    ax.set_ylim(-0.7, len(tree.levels) - 0.2)
+    ax.set_xlim(0, width)
+    ax.axis("off")
+    title = "Merkle tree (digest prefixes)"
+    if highlight is not None:
+        title += f": proof for leaf {highlight} sends the orange siblings"
+    ax.set_title(title)
+    return ax
+
+
+def plot_proof_trace(trace: MerkleTrace, ax: Axes | None = None) -> Axes:
+    """Tabulate each step of reconstructing a root from a leaf and its proof.
+
+    Parameters
+    ----------
+    trace : MerkleTrace
+        From :func:`~blockchainkit.structures.systems.merkle.trace_proof`.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(9, 0.5 * len(trace.steps) + 1.6))
+    describe = {
+        "left": "hash(sibling || node)",
+        "right": "hash(node || sibling)",
+        "promoted": "no sibling: promote",
+    }
+    rows = [["hash(0x00 || leaf)", "", trace.leaf_digest.hex()[:16]]]
+    for step in trace.steps:
+        sibling = "" if step.sibling is None else step.sibling.hex()[:16]
+        rows.append([describe[step.side], sibling, step.digest.hex()[:16]])
+    verdict = "matches trusted root" if trace.valid else "does NOT match trusted root"
+    rows.append([f"bind leaf count; {verdict}", "", trace.root.hex()[:16]])
+    ax.axis("off")
+    table = ax.table(
+        cellText=rows, colLabels=["step", "sibling", "result"], cellLoc="center", loc="center"
+    )
+    table.auto_set_font_size(False)
+    table.set_fontsize(9)
+    table.scale(1, 1.6)
+    ax.set_title("A Merkle proof is a recipe for reconstructing the root")
+    return ax
+
+
+def plot_block_tree(chain: Blockchain, ax: Axes | None = None) -> Axes:
+    """Draw every stored block by height, one lane per fork, canonical chain highlighted.
+
+    Parameters
+    ----------
+    chain : Blockchain
+        A chain, possibly holding side forks.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(8, 3))
+    canonical = {block.hash for block in chain.canonical_blocks()}
+    lane: dict[bytes, int] = {}
+    for index, tip in enumerate(chain.tips()):
+        block = tip
+        while block.hash not in lane:
+            lane[block.hash] = index
+            if block.height == 0:
+                break
+            block = chain.blocks[block.previous_hash]
+    for digest, block in chain.blocks.items():
+        x, y = block.height, -lane[digest]
+        if block.height:
+            parent = chain.blocks[block.previous_hash]
+            ax.plot([parent.height, x], [-lane[parent.hash], y], color="#94a3b8", zorder=1)
+        color = _PATH if digest in canonical else _OTHER
+        ax.scatter([x], [y], s=700, marker="s", color=color, zorder=2)
+        ax.text(x, y, digest.hex()[:4], ha="center", va="center", fontsize=7, zorder=3)
+    ax.set_xlabel("height")
+    ax.set_yticks([])
+    ax.set_title(f"Block tree: canonical chain in blue (work {chain.cumulative_work})")
+    return ax

blockchainkit/vm/__init__.py

@@ -0,0 +1,60 @@
+"""Execution: a deterministic stack machine, its languages, contracts, and attacks."""
+
+from blockchainkit.vm.core.base import (
+    BusyBeaverResult,
+    ExecutionResult,
+    Instruction,
+    ReentrancyResult,
+    ScriptResult,
+    TraceStep,
+    TuringRun,
+    VerificationResult,
+    VMError,
+)
+from blockchainkit.vm.systems.assembler import assemble
+from blockchainkit.vm.systems.expressions import compile_expression, to_rpn
+from blockchainkit.vm.systems.programs import batch_transfer, vending_machine
+from blockchainkit.vm.systems.reentrancy import drain_bank
+from blockchainkit.vm.systems.script import (
+    encode_public_key,
+    encode_signature,
+    htlc_locking,
+    number,
+    p2pkh_locking,
+    p2pkh_unlocking,
+    verify_script,
+)
+from blockchainkit.vm.systems.stack_machine import execute, validate_program
+from blockchainkit.vm.systems.turing import busy_beaver, enumerate_machines, run_turing_machine
+from blockchainkit.vm.systems.verifier import verify_bytecode
+
+__all__ = [
+    "BusyBeaverResult",
+    "ExecutionResult",
+    "Instruction",
+    "ReentrancyResult",
+    "ScriptResult",
+    "TraceStep",
+    "TuringRun",
+    "VerificationResult",
+    "VMError",
+    "assemble",
+    "compile_expression",
+    "to_rpn",
+    "batch_transfer",
+    "vending_machine",
+    "drain_bank",
+    "encode_public_key",
+    "encode_signature",
+    "htlc_locking",
+    "number",
+    "p2pkh_locking",
+    "p2pkh_unlocking",
+    "verify_script",
+    "execute",
+    "validate_program",
+    "busy_beaver",
+    "enumerate_machines",
+    "run_turing_machine",
+    "verify_bytecode",
+]

blockchainkit/vm/core/__init__.py

@@ -0,0 +1,25 @@
+"""Instruction type, errors, and result containers."""
+
+from blockchainkit.vm.core.base import (
+    BusyBeaverResult,
+    ExecutionResult,
+    Instruction,
+    ReentrancyResult,
+    ScriptResult,
+    TraceStep,
+    TuringRun,
+    VerificationResult,
+    VMError,
+)
+
+__all__ = [
+    "BusyBeaverResult",
+    "ExecutionResult",
+    "Instruction",
+    "ReentrancyResult",
+    "ScriptResult",
+    "TraceStep",
+    "TuringRun",
+    "VerificationResult",
+    "VMError",
+]

blockchainkit/vm/core/base.py

@@ -0,0 +1,171 @@
+"""Instruction type, errors, and result containers for blockchainkit.vm."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+Instruction = tuple[str, int | None]
+"""An ``(opcode, operand)`` pair; the operand is ``None`` for simple opcodes."""
+
+
+@dataclass(frozen=True)
+class TraceStep:
+    """Machine state just after one executed instruction.
+
+    Attributes
+    ----------
+    pc : int
+        Index of the instruction that ran.
+    opcode : str
+        Its opcode.
+    operand : int or None
+        Its operand.
+    stack : tuple of int
+        Stack after the instruction, bottom first.
+    storage : Mapping
+        Working storage after the instruction (committed only on success).
+    gas_used : int
+        Cumulative gas, including this instruction.
+    """
+
+    pc: int
+    opcode: str
+    operand: int | None
+    stack: tuple[int, ...]
+    storage: Mapping[int, int]
+    gas_used: int
+
+
+class VMError(ValueError):
+    """Invalid instruction, stack operation, arithmetic operation, or resource limit.
+
+    Attributes
+    ----------
+    trace : tuple of TraceStep
+        Steps executed before the failure, when ``execute(..., trace=True)``
+        was requested; otherwise empty.
+    """
+
+    trace: tuple[TraceStep, ...] = ()
+
+
+@dataclass(frozen=True)
+class ExecutionResult:
+    """Final stack, read-only storage, consumed gas, and optional step trace."""
+
+    stack: tuple[int, ...]
+    storage: Mapping[int, int]
+    gas_used: int
+    trace: tuple[TraceStep, ...] = ()
+
+
+@dataclass(frozen=True)
+class VerificationResult:
+    """Outcome of static bytecode verification.
+
+    Attributes
+    ----------
+    max_depth : int
+        The largest stack height any path can reach.
+    errors : tuple of str
+        Every problem found; empty if the program is safe.
+    """
+
+    max_depth: int
+    errors: tuple[str, ...]
+
+    @property
+    def ok(self) -> bool:
+        """True if no path can underflow and every join agrees on the stack height."""
+        return not self.errors
+
+
+@dataclass(frozen=True)
+class TuringRun:
+    """How a Turing machine run ended.
+
+    Attributes
+    ----------
+    outcome : str
+        ``"halted"``, ``"looping"`` (a configuration repeated, so it never
+        halts), or ``"unknown"`` (the step budget ran out first).
+    steps : int
+        Steps executed, counting the halting transition.
+    ones : int
+        Number of 1s on the tape at the end.
+    """
+
+    outcome: str
+    steps: int
+    ones: int
+
+
+@dataclass(frozen=True)
+class BusyBeaverResult:
+    """The longest-running halting machine found by an exhaustive search.
+
+    Attributes
+    ----------
+    steps : int
+        Its number of steps: the busy-beaver value S if no unknown machine halts later.
+    ones : int
+        The 1s it leaves on the tape.
+    machine : dict
+        Its rules, ``(state, symbol) -> (write, move, next_state)``.
+    counts : dict
+        Machines per outcome: ``"halted"``, ``"looping"``, ``"unknown"``.
+    """
+
+    steps: int
+    ones: int
+    machine: dict[tuple[str, int], tuple[int, int, str]]
+    counts: dict[str, int]
+
+
+@dataclass(frozen=True)
+class ScriptResult:
+    """Outcome of validating a Bitcoin-style script pair.
+
+    Attributes
+    ----------
+    valid : bool
+        Both scripts ran without error and left a true value on top.
+    stack : tuple of bytes
+        The final stack, bottom first.
+    error : str or None
+        Why validation failed, if it did.
+    operations : int
+        Opcodes and pushes executed. Scripts have no loops, so this never
+        exceeds the combined script length.
+    """
+
+    valid: bool
+    stack: tuple[bytes, ...]
+    error: str | None
+    operations: int
+
+
+@dataclass(frozen=True)
+class ReentrancyResult:
+    """What an attacker withdrew from a bank contract.
+
+    Attributes
+    ----------
+    withdrawn : int
+        Total paid out to the attacker.
+    deposited : int
+        What the attacker had deposited.
+    calls : int
+        Times ``withdraw`` was entered, including re-entries.
+    bank_balance : int
+        Funds left in the bank afterwards.
+    """
+
+    withdrawn: int
+    deposited: int
+    calls: int
+    bank_balance: int
+
+    @property
+    def stolen(self) -> int:
+        """Withdrawn beyond the attacker's own deposit."""
+        return self.withdrawn - self.deposited

blockchainkit/vm/systems/__init__.py

@@ -0,0 +1,40 @@
+"""Execution engines and the programs, languages and models built on them."""
+
+from blockchainkit.vm.systems.assembler import assemble
+from blockchainkit.vm.systems.expressions import compile_expression, to_rpn
+from blockchainkit.vm.systems.programs import batch_transfer, vending_machine
+from blockchainkit.vm.systems.reentrancy import drain_bank
+from blockchainkit.vm.systems.script import (
+    encode_public_key,
+    encode_signature,
+    htlc_locking,
+    number,
+    p2pkh_locking,
+    p2pkh_unlocking,
+    verify_script,
+)
+from blockchainkit.vm.systems.stack_machine import execute, validate_program
+from blockchainkit.vm.systems.turing import busy_beaver, enumerate_machines, run_turing_machine
+from blockchainkit.vm.systems.verifier import verify_bytecode
+
+__all__ = [
+    "assemble",
+    "compile_expression",
+    "to_rpn",
+    "batch_transfer",
+    "vending_machine",
+    "drain_bank",
+    "encode_public_key",
+    "encode_signature",
+    "htlc_locking",
+    "number",
+    "p2pkh_locking",
+    "p2pkh_unlocking",
+    "verify_script",
+    "execute",
+    "validate_program",
+    "busy_beaver",
+    "enumerate_machines",
+    "run_turing_machine",
+    "verify_bytecode",
+]