blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/vm/systems/stack_machine.py

@@ -0,0 +1,239 @@
+"""A bounded deterministic 256-bit stack machine with atomic storage updates.
+
+Instruction encoding: each instruction is a (opcode, operand) pair. Only
+PUSH, LOAD, STORE, JMP, and JZ take an integer operand. All instructions cost
+one teaching gas unit unless a schedule says otherwise; this is not an EVM
+implementation or cost schedule.
+"""
+
+from collections.abc import Iterable, Mapping, Sequence
+from types import MappingProxyType
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import WORD_MODULUS
+from blockchainkit.vm.core.base import ExecutionResult, Instruction, TraceStep, VMError
+
+OPERAND_OPCODES = frozenset({"PUSH", "LOAD", "STORE", "JMP", "JZ"})
+"""Opcodes that take a 256-bit integer operand."""
+
+STACK_EFFECTS: Mapping[str, tuple[int, int]] = MappingProxyType(
+    {
+        "PUSH": (0, 1),
+        "LOAD": (0, 1),
+        "STORE": (1, 0),
+        "JMP": (0, 0),
+        "JZ": (1, 0),
+        "ADD": (2, 1),
+        "SUB": (2, 1),
+        "MUL": (2, 1),
+        "DIV": (2, 1),
+        "EQ": (2, 1),
+        "LT": (2, 1),
+        "DUP": (1, 2),
+        "DROP": (1, 0),
+        "SWAP": (2, 2),
+        "OVER": (2, 3),
+        "ROT": (3, 3),
+        "STOP": (0, 0),
+        "REVERT": (0, 0),
+    }
+)
+"""Values each opcode pops and pushes, as ``(pops, pushes)``.
+
+Forth writes these as stack diagrams: ``OVER`` is ``( a b -- a b a )`` and
+``ROT`` is ``( a b c -- b c a )``.
+"""
+
+OPCODES = frozenset(STACK_EFFECTS)
+"""Every opcode the machine accepts."""
+
+_ARITHMETIC = frozenset({"ADD", "SUB", "MUL", "DIV", "EQ", "LT"})
+
+
+def check_word(value: int, name: str) -> None:
+    """Raise VMError unless ``value`` is an int in ``[0, 2**256)``."""
+    if type(value) is not int or not 0 <= value < WORD_MODULUS:
+        raise VMError(f"{name} must be a 256-bit word")
+
+
+def validate_program(program: Iterable[Instruction]) -> tuple[Instruction, ...]:
+    """Check every instruction's shape before anything runs; return the program as a tuple.
+
+    Raises
+    ------
+    VMError
+        An unknown opcode, a missing or extra operand, an operand outside
+        256 bits, or a jump target outside the program.
+    """
+    code = tuple(program)
+    for instruction in code:
+        if not isinstance(instruction, tuple) or len(instruction) != 2:
+            raise VMError("instructions must be (opcode, operand) pairs")
+        op, arg = instruction
+        if not isinstance(op, str) or op not in OPCODES:
+            raise VMError(f"unknown opcode: {op}")
+        if op in OPERAND_OPCODES:
+            if type(arg) is not int or not 0 <= arg < WORD_MODULUS:
+                raise VMError(f"{op} requires a 256-bit integer operand")
+            if op in {"JMP", "JZ"} and arg >= len(code):
+                raise VMError("jump target outside program")
+        elif arg is not None:
+            raise VMError(f"{op} takes no operand")
+    return code
+
+
+def execute(
+    program: Iterable[Instruction],
+    *,
+    storage: Mapping[int, int] | None = None,
+    arguments: Sequence[int] = (),
+    gas_limit: int = 10_000,
+    stack_limit: int = 1024,
+    gas_costs: Mapping[str, int] | None = None,
+    trace: bool = False,
+) -> ExecutionResult:
+    """Execute a program against a copy of storage, committing only on success.
+
+    Parameters
+    ----------
+    program : iterable of tuple
+        (opcode, operand) pairs. For binary operations the top value is the
+        right operand: PUSH 7; PUSH 2; SUB produces 5.
+    storage : mapping, optional
+        Initial 256-bit integer keys and values. Never mutated by execution.
+    arguments : sequence of int
+        Initial stack, bottom first: the call's inputs, like a contract's
+        call data.
+    gas_limit : int
+        Maximum total gas, including STOP.
+    stack_limit : int
+        Maximum stack depth.
+    gas_costs : mapping, optional
+        Per-opcode gas prices overriding the default of one unit each, for
+        experiments with a cost schedule. Unlisted opcodes cost one unit;
+        every price must be at least one, so gas always bounds the run.
+    trace : bool
+        Record a :class:`~blockchainkit.vm.core.base.TraceStep` after every
+        executed instruction, in ``ExecutionResult.trace`` on success or
+        ``VMError.trace`` on failure.
+
+    Returns
+    -------
+    ExecutionResult
+        Deterministic stack, storage, gas used, and the trace if requested.
+
+    Raises
+    ------
+    VMError
+        Malformed program, stack underflow or overflow, division by zero,
+        ``REVERT``, or running out of gas. Storage is then left unchanged.
+
+    Examples
+    --------
+    >>> from blockchainkit.vm import execute
+    >>> execute([("PUSH", 7), ("PUSH", 2), ("SUB", None)]).stack
+    (5,)
+    >>> [step.stack for step in execute([("PUSH", 7), ("DUP", None)], trace=True).trace]
+    [(7,), (7, 7)]
+    >>> execute([("MUL", None)], arguments=(6, 7)).stack
+    (42,)
+    """
+    integer(gas_limit, "gas_limit")
+    integer(stack_limit, "stack_limit", 1)
+    code = validate_program(program)
+    state = dict(storage or {})
+    for key, value in state.items():
+        if type(key) is not int or type(value) is not int:
+            raise VMError("storage keys and values must be integers")
+        check_word(key, "storage keys and values")
+        check_word(value, "storage keys and values")
+    stack = list(arguments)
+    for value in stack:
+        check_word(value, "every argument")
+    if len(stack) > stack_limit:
+        raise VMError("stack limit exceeded")
+    prices = dict(gas_costs or {})
+    for name, price in prices.items():
+        if name not in OPCODES:
+            raise VMError(f"gas schedule names an unknown opcode: {name}")
+        # A zero price would let a loop run forever without exhausting gas.
+        integer(price, f"gas cost of {name}", 1)
+    steps: list[TraceStep] = []
+    try:
+        gas_used = _run(
+            code, stack, state, prices, gas_limit, stack_limit, steps if trace else None
+        )
+    except VMError as error:
+        error.trace = tuple(steps)
+        raise
+    return ExecutionResult(tuple(stack), MappingProxyType(state), gas_used, tuple(steps))
+
+
+def _run(
+    code: tuple[Instruction, ...],
+    stack: list[int],
+    state: dict[int, int],
+    prices: Mapping[str, int],
+    gas_limit: int,
+    stack_limit: int,
+    steps: list[TraceStep] | None,
+) -> int:
+    pc = gas_used = 0
+    while pc < len(code):
+        start = pc
+        op, arg = code[pc]
+        price = prices.get(op, 1)
+        if gas_used + price > gas_limit:
+            raise VMError("out of gas")
+        gas_used += price
+        pc += 1
+        if len(stack) < STACK_EFFECTS[op][0]:
+            raise VMError("stack underflow")
+        if op == "REVERT":
+            raise VMError("reverted")
+        if op == "STOP":
+            if steps is not None:
+                steps.append(TraceStep(start, op, arg, tuple(stack), dict(state), gas_used))
+            break
+        if op in OPERAND_OPCODES:
+            assert arg is not None  # Checked for every operand opcode before execution.
+            if op == "PUSH":
+                stack.append(arg)
+            elif op == "LOAD":
+                stack.append(state.get(arg, 0))
+            elif op == "STORE":
+                state[arg] = stack.pop()
+            elif op == "JMP" or stack.pop() == 0:
+                pc = arg
+        elif op in _ARITHMETIC:
+            right, left = stack.pop(), stack.pop()
+            if op == "ADD":
+                value = left + right
+            elif op == "SUB":
+                value = left - right
+            elif op == "MUL":
+                value = left * right
+            elif op == "DIV":
+                if right == 0:
+                    raise VMError("division by zero")
+                value = left // right
+            elif op == "EQ":
+                value = int(left == right)
+            else:
+                value = int(left < right)
+            stack.append(value % WORD_MODULUS)
+        elif op == "DUP":
+            stack.append(stack[-1])
+        elif op == "DROP":
+            stack.pop()
+        elif op == "SWAP":
+            stack[-1], stack[-2] = stack[-2], stack[-1]
+        elif op == "OVER":
+            stack.append(stack[-2])
+        else:  # ROT: ( a b c -- b c a )
+            stack.append(stack.pop(-3))
+        if len(stack) > stack_limit:
+            raise VMError("stack limit exceeded")
+        if steps is not None:
+            steps.append(TraceStep(start, op, arg, tuple(stack), dict(state), gas_used))
+    return gas_used

blockchainkit/vm/systems/turing.py

@@ -0,0 +1,111 @@
+"""Turing machines (1936), the halting problem, and Radó's busy beaver (1962).
+
+A Turing machine reads one cell of an unbounded tape, and according to its
+state and the symbol there, writes a symbol, moves left or right, and
+changes state. Turing proved that no program can decide, for every machine,
+whether it halts. Radó turned that into numbers: the *busy beaver* ``S(n)``
+is the most steps any halting ``n``-state, 2-symbol machine takes from a
+blank tape. ``S`` grows faster than any computable function, so no
+fixed budget can separate "still running" from "never halts". Blockchains
+respond the way Radó's search must: they cap the work (gas) and stop there.
+"""
+
+import itertools
+from collections.abc import Iterator, Mapping
+
+from blockchainkit._validation import integer
+from blockchainkit.vm.core.base import BusyBeaverResult, TuringRun
+
+Rule = tuple[int, int, str]
+"""``(write, move, next_state)``: move is -1 (left) or +1 (right); state ``"H"`` halts."""
+
+HALT = "H"
+"""str: The halting state."""
+
+STATE_NAMES = "ABCDEFG"
+
+
+def run_turing_machine(
+    rules: Mapping[tuple[str, int], Rule], *, max_steps: int = 1000, start: str = "A"
+) -> TuringRun:
+    """Run a 2-symbol machine from a blank tape for at most ``max_steps`` steps.
+
+    The transition into the halting state counts as a step, as in Radó's
+    definition. If the machine returns to an earlier configuration (same
+    state, head position and tape), it provably runs forever. Otherwise,
+    when the budget runs out, the outcome is unknown.
+
+    Examples
+    --------
+    >>> from blockchainkit.vm import run_turing_machine
+    >>> champion = {("A", 0): (1, 1, "B"), ("A", 1): (1, -1, "B"),
+    ...             ("B", 0): (1, -1, "A"), ("B", 1): (1, 1, "H")}
+    >>> run = run_turing_machine(champion)
+    >>> run.outcome, run.steps, run.ones
+    ('halted', 6, 4)
+    """
+    integer(max_steps, "max_steps", 1)
+    tape: dict[int, int] = {}
+    state, head = start, 0
+    seen: set[tuple[str, int, frozenset[int]]] = set()
+    for step in range(1, max_steps + 1):
+        config = (state, head, frozenset(cell for cell, symbol in tape.items() if symbol))
+        if config in seen:
+            return TuringRun("looping", step - 1, sum(tape.values()))
+        seen.add(config)
+        try:
+            write, move, state = rules[(state, tape.get(head, 0))]
+        except KeyError:
+            raise ValueError(f"no rule for state {state!r} reading {tape.get(head, 0)}") from None
+        if write not in (0, 1) or move not in (-1, 1):
+            raise ValueError("rules write 0 or 1 and move -1 or +1")
+        tape[head] = write
+        head += move
+        if state == HALT:
+            return TuringRun("halted", step, sum(tape.values()))
+    return TuringRun("unknown", max_steps, sum(tape.values()))
+
+
+def enumerate_machines(states: int) -> Iterator[dict[tuple[str, int], Rule]]:
+    """Yield every ``states``-state, 2-symbol machine: ``(4 (states + 1)) ** (2 states)`` of them.
+
+    >>> from blockchainkit.vm import enumerate_machines
+    >>> sum(1 for _ in enumerate_machines(1))
+    64
+    """
+    integer(states, "states", 1)
+    if states > len(STATE_NAMES):
+        raise ValueError(f"at most {len(STATE_NAMES)} states")
+    names = STATE_NAMES[:states]
+    keys = [(name, symbol) for name in names for symbol in (0, 1)]
+    choices = list(itertools.product((0, 1), (-1, 1), (*names, HALT)))
+    for combination in itertools.product(choices, repeat=len(keys)):
+        yield dict(zip(keys, combination, strict=True))
+
+
+def busy_beaver(states: int, *, max_steps: int = 100) -> BusyBeaverResult:
+    """Search every machine with ``states`` states for the longest halting run.
+
+    Each machine runs for at most ``max_steps`` steps. The answer equals
+    ``S(states)`` only if every machine classified as unknown really runs
+    forever, which this search cannot prove; that gap is the halting problem.
+    Feasible here for 1 or 2 states (20,736 machines for 2).
+
+    Examples
+    --------
+    >>> from blockchainkit.vm import busy_beaver
+    >>> busy_beaver(1).steps
+    1
+    """
+    best: TuringRun | None = None
+    champion: dict[tuple[str, int], Rule] = {}
+    counts = {"halted": 0, "looping": 0, "unknown": 0}
+    for rules in enumerate_machines(states):
+        run = run_turing_machine(rules, max_steps=max_steps)
+        counts[run.outcome] += 1
+        if run.outcome == "halted" and (
+            best is None or (run.steps, run.ones) > (best.steps, best.ones)
+        ):
+            best, champion = run, rules
+    assert best is not None  # A machine whose first rule halts always exists.
+    return BusyBeaverResult(best.steps, best.ones, champion, counts)

blockchainkit/vm/systems/verifier.py

@@ -0,0 +1,81 @@
+"""Static bytecode verification (Gosling 1995; the Java virtual machine).
+
+Java's virtual machine checks downloaded code *before* running it, so the
+interpreter can skip run-time checks. The verifier follows every path
+through the program, tracking how many values are on the stack at each
+instruction, without running anything. It rejects code that could
+underflow the stack on some path, or that reaches the same instruction with
+different stack heights along different paths (as a loop that pushes on
+every turn does). Code that passes has a known maximum stack depth.
+"""
+
+from collections.abc import Iterable
+
+from blockchainkit._validation import integer
+from blockchainkit.vm.core.base import Instruction, VerificationResult
+from blockchainkit.vm.systems.stack_machine import STACK_EFFECTS, validate_program
+
+
+def verify_bytecode(program: Iterable[Instruction], *, arguments: int = 0) -> VerificationResult:
+    """Check stack safety on every path and compute the maximum stack depth.
+
+    This is abstract interpretation: the abstract state at an instruction is
+    a single number, the stack height on entry. Starting from ``arguments``
+    at instruction 0, the verifier propagates heights along every edge
+    (both outcomes of ``JZ``) until nothing changes.
+
+    Parameters
+    ----------
+    program : iterable of tuple
+        Instructions, validated for shape first.
+    arguments : int
+        Values on the stack when execution starts.
+
+    Returns
+    -------
+    VerificationResult
+        ``max_depth`` and the list of problems found; ``ok`` if there are none.
+
+    Examples
+    --------
+    >>> from blockchainkit.vm import verify_bytecode
+    >>> verify_bytecode([("PUSH", 1), ("ADD", None)]).errors
+    ('pc 1: ADD needs 2 values but only 1 can be on the stack',)
+    >>> verify_bytecode([("PUSH", 1), ("PUSH", 2), ("ADD", None)]).max_depth
+    2
+    """
+    code = validate_program(program)
+    integer(arguments, "arguments")
+    heights: dict[int, int] = {0: arguments} if code else {}
+    errors: list[str] = []
+    pending = [0] if code else []
+    max_depth = arguments
+    while pending:
+        pc = pending.pop()
+        height = heights[pc]
+        op, arg = code[pc]
+        pops, pushes = STACK_EFFECTS[op]
+        if height < pops:
+            errors.append(
+                f"pc {pc}: {op} needs {pops} values but only {height} can be on the stack"
+            )
+            continue
+        after = height - pops + pushes
+        max_depth = max(max_depth, after)
+        if op in {"STOP", "REVERT"}:
+            continue
+        successors = [] if op == "JMP" else [pc + 1]
+        if op in {"JMP", "JZ"}:
+            assert arg is not None  # Jumps always carry a validated target.
+            successors.append(arg)
+        for target in successors:
+            if target >= len(code):
+                continue  # Falling off the end halts normally.
+            if target not in heights:
+                heights[target] = after
+                pending.append(target)
+            elif heights[target] != after:
+                message = f"pc {target}: reached with stack heights {heights[target]} and {after}"
+                if message not in errors:
+                    errors.append(message)
+    return VerificationResult(max_depth, tuple(errors))

blockchainkit/vm/visualizers/__init__.py

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

blockchainkit/vm/visualizers/plots.py

@@ -0,0 +1,97 @@
+"""Plotting helpers for blockchainkit.vm: execution traces and stack heights."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+
+from blockchainkit.vm.core.base import TraceStep
+
+__all__ = ["plot_execution_trace", "plot_stack_height"]
+
+
+def plot_execution_trace(
+    trace: Sequence[TraceStep], *, max_rows: int = 30, ax: Axes | None = None
+) -> Axes:
+    """Tabulate the stack, storage, and gas after each executed instruction.
+
+    Parameters
+    ----------
+    trace : sequence of TraceStep
+        ``ExecutionResult.trace`` or ``VMError.trace`` from
+        ``execute(..., trace=True)``.
+    max_rows : int
+        Show at most this many steps (the first ones), so loops stay legible.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if not trace:
+        raise ValueError("empty trace: pass trace=True to execute")
+    shown = list(trace[:max_rows])
+    if ax is None:
+        _, ax = plt.subplots(figsize=(9, 0.35 * len(shown) + 1.4))
+    rows = [
+        [
+            str(step.pc),
+            step.opcode if step.operand is None else f"{step.opcode} {step.operand}",
+            str(list(step.stack)),
+            str(dict(step.storage)),
+            str(step.gas_used),
+        ]
+        for step in shown
+    ]
+    ax.axis("off")
+    table = ax.table(
+        cellText=rows,
+        colLabels=["pc", "instruction", "stack", "storage", "gas"],
+        cellLoc="center",
+        loc="center",
+    )
+    table.auto_set_font_size(False)
+    table.set_fontsize(9)
+    table.scale(1, 1.4)
+    hidden = len(trace) - len(shown)
+    suffix = f" (first {len(shown)} of {len(trace)} steps)" if hidden else ""
+    ax.set_title("State after each instruction" + suffix)
+    return ax
+
+
+def plot_stack_height(
+    trace: Sequence[TraceStep], *, label: str | None = None, ax: Axes | None = None
+) -> Axes:
+    """Plot the stack height after each executed instruction.
+
+    The peak is the stack space the run needed: what a hardware stack must
+    provide, and what static verification bounds in advance.
+
+    Parameters
+    ----------
+    trace : sequence of TraceStep
+        From ``execute(..., trace=True)``.
+    label : str, optional
+        Legend label, to compare several runs on one axes.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if not trace:
+        raise ValueError("empty trace: pass trace=True to execute")
+    if ax is None:
+        _, ax = plt.subplots()
+    heights = [len(step.stack) for step in trace]
+    ax.step(range(1, len(heights) + 1), heights, where="post", label=label)
+    ax.set_xlabel("instructions executed")
+    ax.set_ylabel("stack height")
+    ax.set_title(f"Stack height (peak {max(heights)})")
+    if label is not None:
+        ax.legend()
+    return ax