blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/vm/systems/assembler.py

@@ -0,0 +1,80 @@
+"""A two-pass assembler: write programs as text, with labels for jump targets.
+
+Each line holds one instruction, an opcode with an optional operand, or a
+label ending in ``:``. ``#`` starts a comment. A jump may name a label
+instead of an address; the first pass records where each label points, the
+second replaces label names by those addresses.
+
+Example::
+
+    # Sum 1 + 2 + ... + n, with n in slot 0 and the sum in slot 1.
+    loop:
+        LOAD 0
+        JZ done
+        LOAD 1
+        LOAD 0
+        ADD
+        STORE 1
+        LOAD 0
+        PUSH 1
+        SUB
+        STORE 0
+        JMP loop
+    done:
+        STOP
+"""
+
+from blockchainkit.vm.core.base import Instruction, VMError
+from blockchainkit.vm.systems.stack_machine import OPERAND_OPCODES, validate_program
+
+
+def assemble(source: str) -> tuple[Instruction, ...]:
+    """Translate assembly text into ``(opcode, operand)`` instructions.
+
+    Operands are decimal or ``0x`` hexadecimal integers, or labels for
+    ``JMP`` and ``JZ``.
+
+    Examples
+    --------
+    >>> from blockchainkit.vm import assemble
+    >>> assemble('''
+    ... start:
+    ...     PUSH 0x10   # sixteen
+    ...     JZ start
+    ... ''')
+    (('PUSH', 16), ('JZ', 0))
+    """
+    if not isinstance(source, str):
+        raise TypeError("source must be a str")
+    labels: dict[str, int] = {}
+    lines: list[tuple[int, list[str]]] = []
+    for number, raw in enumerate(source.splitlines(), start=1):
+        text = raw.split("#", 1)[0].strip()
+        if not text:
+            continue
+        if text.endswith(":"):
+            name = text[:-1].strip()
+            if not name.isidentifier() or name in labels:
+                raise VMError(f"line {number}: bad or repeated label {name!r}")
+            labels[name] = len(lines)
+            continue
+        lines.append((number, text.split()))
+    program: list[Instruction] = []
+    for number, words in lines:
+        op = words[0].upper()
+        if len(words) > 2:
+            raise VMError(f"line {number}: one operand at most")
+        if len(words) == 1:
+            program.append((op, None))
+            continue
+        word = words[1]
+        if op in {"JMP", "JZ"} and word in labels:
+            program.append((op, labels[word]))
+        elif op in OPERAND_OPCODES:
+            try:
+                program.append((op, int(word, 0)))
+            except ValueError:
+                raise VMError(f"line {number}: unknown label or number {word!r}") from None
+        else:
+            raise VMError(f"line {number}: {op} takes no operand")
+    return validate_program(program)

blockchainkit/vm/systems/expressions.py

@@ -0,0 +1,91 @@
+"""Reverse Polish notation (Łukasiewicz 1924; Hamblin 1957) and its compilation.
+
+Łukasiewicz wrote logical formulas with the operator first, which needs no
+parentheses: ``+ 1 * 2 3``. Hamblin saw that the reversed form,
+``1 2 3 * +``, is exactly the order in which a stack machine computes: push
+operands, and let each operator replace the top two values by its result.
+Dijkstra's shunting-yard algorithm (1961) converts ordinary infix notation
+to that order, which is how expressions become stack-machine code.
+"""
+
+import re
+
+from blockchainkit.vm.core.base import Instruction, VMError
+from blockchainkit.vm.systems.stack_machine import check_word
+
+_PRECEDENCE = {"+": 1, "-": 1, "*": 2, "/": 2}
+_OPCODES = {"+": "ADD", "-": "SUB", "*": "MUL", "/": "DIV"}
+_TOKEN = re.compile(r"\s*(?:(\d+)|(.))")
+
+
+def to_rpn(expression: str) -> tuple[str, ...]:
+    """Convert an infix expression to reverse Polish notation (shunting yard).
+
+    Supports non-negative integers, ``+ - * /`` with the usual precedence
+    and left associativity, and parentheses.
+
+    Examples
+    --------
+    >>> from blockchainkit.vm import to_rpn
+    >>> to_rpn("(1 + 2) * 3 - 4")
+    ('1', '2', '+', '3', '*', '4', '-')
+    """
+    if not isinstance(expression, str):
+        raise TypeError("expression must be a str")
+    output: list[str] = []
+    operators: list[str] = []
+    expect_operand = True
+    for number, symbol in _TOKEN.findall(expression.strip()):
+        if number:
+            if not expect_operand:
+                raise VMError("two operands in a row")
+            output.append(number)
+            expect_operand = False
+        elif symbol == "(":
+            if not expect_operand:
+                raise VMError("missing operator before '('")
+            operators.append(symbol)
+        elif symbol == ")":
+            while operators and operators[-1] != "(":
+                output.append(operators.pop())
+            if not operators or expect_operand:
+                raise VMError("unbalanced or empty parentheses")
+            operators.pop()
+        elif symbol in _PRECEDENCE:
+            if expect_operand:
+                raise VMError(f"operator {symbol!r} is missing an operand")
+            while operators and _PRECEDENCE.get(operators[-1], 0) >= _PRECEDENCE[symbol]:
+                output.append(operators.pop())
+            operators.append(symbol)
+            expect_operand = True
+        else:
+            raise VMError(f"unexpected character {symbol!r}")
+    if expect_operand:
+        raise VMError("the expression is empty or ends with an operator")
+    while operators:
+        if operators[-1] == "(":
+            raise VMError("unbalanced parentheses")
+        output.append(operators.pop())
+    return tuple(output)
+
+
+def compile_expression(expression: str) -> tuple[Instruction, ...]:
+    """Compile an infix expression to stack-machine instructions via RPN.
+
+    Each number becomes ``PUSH`` and each operator its opcode. Arithmetic is
+    then the machine's: modulo ``2**256``, with ``/`` as floor division.
+
+    Examples
+    --------
+    >>> from blockchainkit.vm import compile_expression, execute
+    >>> execute(compile_expression("(1 + 2) * 3 - 4")).stack
+    (5,)
+    """
+    program: list[Instruction] = []
+    for token in to_rpn(expression):
+        if token in _OPCODES:
+            program.append((_OPCODES[token], None))
+        else:
+            check_word(int(token), "every number")
+            program.append(("PUSH", int(token)))
+    return tuple(program)

blockchainkit/vm/systems/programs.py

@@ -0,0 +1,143 @@
+"""Small contracts written for the stack machine.
+
+* :func:`vending_machine`: Szabo's (1994) example of a contract enforced by
+  a mechanism rather than a court: pay at least the price and an item and
+  your change come out; otherwise nothing happens.
+* :func:`batch_transfer`: the token function behind the 2018 BeautyChain
+  (BEC) exploit, where ``count * value`` overflowed 256 bits.
+
+Both are assembled with :func:`~blockchainkit.vm.systems.assembler.assemble`
+and run with :func:`~blockchainkit.vm.systems.stack_machine.execute`.
+"""
+
+from collections.abc import Sequence
+
+from blockchainkit._validation import integer
+from blockchainkit.vm.core.base import Instruction
+from blockchainkit.vm.systems.assembler import assemble
+
+STOCK, PRICE, REVENUE = 0, 1, 2
+"""Storage slots of the vending machine."""
+
+
+def vending_machine() -> tuple[Instruction, ...]:
+    """A vending machine: argument ``payment``; storage holds stock, price and revenue.
+
+    On success the stock drops by one, the revenue grows by the price, and
+    the change ``payment - price`` is left on the stack. Paying too little,
+    or buying from an empty machine, reverts, so neither side can be cheated.
+
+    Examples
+    --------
+    >>> from blockchainkit.vm import execute, vending_machine
+    >>> result = execute(vending_machine(), arguments=(5,), storage={0: 3, 1: 2})
+    >>> result.stack, dict(result.storage)
+    ((3,), {0: 2, 1: 2, 2: 2})
+    """
+    return assemble(
+        f"""
+        # stack: payment
+            DUP
+            LOAD {PRICE}
+            LT              # payment < price?
+            JZ paid
+            REVERT          # too little: nothing happens
+        paid:
+            LOAD {STOCK}
+            JZ sold_out
+            LOAD {STOCK}
+            PUSH 1
+            SUB
+            STORE {STOCK}   # hand over one item
+            LOAD {REVENUE}
+            LOAD {PRICE}
+            ADD
+            STORE {REVENUE}
+            LOAD {PRICE}
+            SUB             # change = payment - price
+            STOP
+        sold_out:
+            REVERT
+        """
+    )
+
+
+def batch_transfer(
+    sender: int, recipients: Sequence[int], *, checked: bool = False
+) -> tuple[Instruction, ...]:
+    """Pay ``value`` (the one argument) from ``sender`` to each recipient.
+
+    Balances live in storage, one slot per account. Like BeautyChain's
+    ``batchTransfer``, the program computes ``amount = count * value``,
+    checks the sender's balance against ``amount``, debits ``amount`` once
+    and credits ``value`` to every recipient. The multiplication wraps
+    modulo ``2**256``: with two recipients and ``value = 2**255``, ``amount``
+    is 0, every check passes, and each recipient receives ``2**255`` tokens
+    from nothing. ``checked=True`` adds the SafeMath test
+    ``amount / count == value``, which rejects the overflow.
+
+    Examples
+    --------
+    >>> from blockchainkit.vm import batch_transfer, execute
+    >>> program = batch_transfer(1, [2, 3])
+    >>> dict(execute(program, arguments=(10,), storage={1: 100}).storage)
+    {1: 80, 2: 10, 3: 10}
+    """
+    integer(sender, "sender")
+    if not recipients:
+        raise ValueError("provide at least one recipient")
+    for account in recipients:
+        integer(account, "recipient")
+    count = len(recipients)
+    overflow_check = (
+        f"""
+            DUP             # value amount amount
+            PUSH {count}
+            DIV             # value amount amount/count
+            ROT             # amount amount/count value
+            DUP
+            ROT             # amount value value amount/count
+            EQ
+            JZ overflow     # SafeMath: the product must divide back
+            SWAP            # value amount
+        """
+        if checked
+        else ""
+    )
+    credits = "\n".join(
+        f"""
+            DUP
+            LOAD {account}
+            ADD
+            STORE {account}"""
+        for account in recipients
+    )
+    return assemble(
+        f"""
+        # stack: value
+            DUP
+            JZ zero_value   # require(value > 0)
+            DUP
+            PUSH {count}
+            MUL             # value amount   (wraps modulo 2**256)
+            {overflow_check}
+            DUP
+            LOAD {sender}
+            SWAP
+            LT              # balance < amount?
+            JZ funded
+            REVERT          # balance too low
+        funded:
+            LOAD {sender}
+            SWAP
+            SUB
+            STORE {sender}  # debit amount once
+            {credits}
+            DROP
+            STOP
+        zero_value:
+            REVERT
+        {"overflow:" if checked else ""}
+            {"REVERT" if checked else ""}
+        """
+    )

blockchainkit/vm/systems/reentrancy.py

@@ -0,0 +1,70 @@
+"""Reentrancy: the DAO attack (2016).
+
+The DAO's withdrawal code sent ether *before* zeroing the caller's balance.
+Sending ether to a contract runs that contract's code, so the attacker's
+contract called ``withdraw`` again from inside the payment, while its
+balance still showed the full deposit, and again, until the funds ran out
+or the call stack's depth limit stopped it. About 3.6 million ether were
+drained in June 2016.
+
+The fix is the *checks-effects-interactions* order: check the conditions,
+update the contract's own state, and only then call out. A re-entrant call
+then finds a zero balance and gets nothing.
+
+This module models the two orders directly in Python: the bank's state is
+two numbers, and "sending" calls the attacker's fallback.
+"""
+
+from blockchainkit._validation import integer
+from blockchainkit.vm.core.base import ReentrancyResult
+
+
+def drain_bank(
+    other_deposits: int,
+    attacker_deposit: int,
+    *,
+    checks_effects_interactions: bool = False,
+    max_depth: int = 1024,
+) -> ReentrancyResult:
+    """Let an attacker that re-enters on every payment withdraw from a bank.
+
+    Parameters
+    ----------
+    other_deposits : int
+        Funds belonging to everyone else.
+    attacker_deposit : int
+        The attacker's own deposit, at least 1.
+    checks_effects_interactions : bool
+        False: the vulnerable order (pay, then zero the balance). True: zero
+        the balance before paying.
+    max_depth : int
+        Maximum call depth (1024 in Ethereum then), bounding the recursion.
+
+    Examples
+    --------
+    >>> from blockchainkit.vm import drain_bank
+    >>> drain_bank(90, 10).stolen, drain_bank(90, 10, checks_effects_interactions=True).stolen
+    (90, 0)
+    """
+    integer(other_deposits, "other_deposits")
+    integer(attacker_deposit, "attacker_deposit", 1)
+    integer(max_depth, "max_depth", 1)
+    bank = other_deposits + attacker_deposit
+    balance = attacker_deposit
+    withdrawn = calls = 0
+    # Each pass is one nested call of withdraw, made from inside the
+    # previous call's payment. (A loop rather than recursion, because the
+    # 1024-call depth exceeds Python's own recursion limit.)
+    for _ in range(max_depth):
+        calls += 1
+        amount = balance  # Checks: the caller's recorded balance.
+        if amount == 0 or bank < amount:
+            break
+        if checks_effects_interactions:
+            balance = 0  # Effects before the interaction.
+        bank -= amount
+        withdrawn += amount
+        # Interaction: the payment runs the attacker's fallback, which calls
+        # withdraw again (the next pass) unless the depth limit ends the loop.
+        # In the vulnerable order the balance is zeroed only as the calls unwind.
+    return ReentrancyResult(withdrawn, attacker_deposit, calls, bank)

blockchainkit/vm/systems/script.py

@@ -0,0 +1,268 @@
+"""Bitcoin-style Script (2009): spending conditions as tiny stack programs.
+
+A coin is locked by a *locking script*; to spend it, one supplies an
+*unlocking script*. The unlocking script runs first, then the locking script
+runs on the stack it left, and the spend is valid if no step fails and the
+top of the stack is true. Script deliberately has no loops, so a script of n
+operations runs at most n steps and needs no gas.
+
+Teaching differences from Bitcoin: stack items are byte strings, but numbers
+are big-endian; ``OP_HASH256`` (double SHA-256) replaces ``OP_HASH160`` in
+pay-to-public-key-hash; and ``OP_CHECKSIG`` checks a blockchainkit Schnorr
+signature over an explicit message rather than a transaction digest.
+"""
+
+from collections.abc import Sequence
+
+from blockchainkit._validation import integer
+from blockchainkit.crypto.core.base import SchnorrSignature
+from blockchainkit.crypto.systems.curves import SECP256K1, encode_point
+from blockchainkit.crypto.systems.hashing import hash256, sha256
+from blockchainkit.crypto.systems.signatures import verify
+from blockchainkit.vm.core.base import ScriptResult
+
+ScriptItem = bytes | str
+"""A data push (bytes) or an opcode name such as ``"OP_DUP"`` (str)."""
+
+OPCODES = frozenset(
+    {
+        "OP_TRUE",
+        "OP_FALSE",
+        "OP_DUP",
+        "OP_DROP",
+        "OP_EQUAL",
+        "OP_EQUALVERIFY",
+        "OP_VERIFY",
+        "OP_SHA256",
+        "OP_HASH256",
+        "OP_CHECKSIG",
+        "OP_CHECKLOCKTIMEVERIFY",
+        "OP_IF",
+        "OP_ELSE",
+        "OP_ENDIF",
+        "OP_RETURN",
+    }
+)
+"""Every opcode the interpreter accepts."""
+
+_WIDTH = 32
+
+
+def encode_public_key(public: tuple[int, int]) -> bytes:
+    """A public key as stack bytes (uncompressed point encoding)."""
+    return encode_point(public)
+
+
+def encode_signature(signature: SchnorrSignature) -> bytes:
+    """A signature as stack bytes: the commitment point, then the 32-byte response."""
+    return encode_point(signature.commitment) + signature.response.to_bytes(_WIDTH, "big")
+
+
+def _point(data: bytes) -> tuple[int, int]:
+    if len(data) != 1 + 2 * _WIDTH or data[0] != 4:
+        raise ValueError("not an encoded point")
+    return int.from_bytes(data[1 : 1 + _WIDTH], "big"), int.from_bytes(data[1 + _WIDTH :], "big")
+
+
+def number(value: int) -> bytes:
+    """Encode a non-negative integer as minimal big-endian bytes (0 is empty)."""
+    integer(value, "value")
+    return value.to_bytes((value.bit_length() + 7) // 8, "big")
+
+
+def _true(item: bytes) -> bool:
+    return any(item)
+
+
+class _Fail(Exception):
+    pass
+
+
+def _run(
+    script: Sequence[ScriptItem],
+    stack: list[bytes],
+    message: bytes,
+    locktime: int,
+    operations: list[int],
+) -> None:
+    executing: list[bool] = []  # One entry per open OP_IF.
+    for item in script:
+        active = all(executing)
+        if isinstance(item, bytes):
+            operations[0] += 1
+            if active:
+                stack.append(item)
+            continue
+        if item not in OPCODES:
+            raise _Fail(f"unknown opcode {item!r}")
+        if item in ("OP_IF", "OP_ELSE", "OP_ENDIF"):
+            operations[0] += 1
+            if item == "OP_IF":
+                if active:
+                    if not stack:
+                        raise _Fail("OP_IF on an empty stack")
+                    executing.append(_true(stack.pop()))
+                else:
+                    executing.append(False)
+            elif not executing:
+                raise _Fail(f"{item} without OP_IF")
+            elif item == "OP_ELSE":
+                executing[-1] = not executing[-1] and all(executing[:-1])
+            else:
+                executing.pop()
+            continue
+        if not active:
+            continue
+        operations[0] += 1
+        if item == "OP_RETURN":
+            raise _Fail("OP_RETURN marks the output unspendable")
+        if item == "OP_TRUE":
+            stack.append(b"\x01")
+            continue
+        if item == "OP_FALSE":
+            stack.append(b"")
+            continue
+        needed = 2 if item in ("OP_EQUAL", "OP_EQUALVERIFY", "OP_CHECKSIG") else 1
+        if len(stack) < needed:
+            raise _Fail(f"{item} needs {needed} stack items")
+        if item == "OP_DUP":
+            stack.append(stack[-1])
+        elif item == "OP_DROP":
+            stack.pop()
+        elif item in ("OP_EQUAL", "OP_EQUALVERIFY"):
+            equal = stack.pop() == stack.pop()
+            if item == "OP_EQUALVERIFY" and not equal:
+                raise _Fail("OP_EQUALVERIFY: items differ")
+            if item == "OP_EQUAL":
+                stack.append(b"\x01" if equal else b"")
+        elif item == "OP_VERIFY":
+            if not _true(stack.pop()):
+                raise _Fail("OP_VERIFY: false")
+        elif item == "OP_SHA256":
+            stack.append(sha256(stack.pop()))
+        elif item == "OP_HASH256":
+            stack.append(hash256(stack.pop()))
+        elif item == "OP_CHECKSIG":
+            public, signature = stack.pop(), stack.pop()
+            try:
+                point = _point(signature[: 1 + 2 * _WIDTH])
+                response = int.from_bytes(signature[1 + 2 * _WIDTH :], "big")
+                ok = len(signature) == 1 + 3 * _WIDTH and verify(
+                    message, SchnorrSignature(point, response), _point(public), SECP256K1
+                )
+            except ValueError:
+                ok = False
+            stack.append(b"\x01" if ok else b"")
+        else:  # OP_CHECKLOCKTIMEVERIFY leaves its operand, as in BIP 65.
+            if int.from_bytes(stack[-1], "big") > locktime:
+                raise _Fail("OP_CHECKLOCKTIMEVERIFY: the lock time has not been reached")
+    if executing:
+        raise _Fail("OP_IF without OP_ENDIF")
+
+
+def verify_script(
+    unlocking: Sequence[ScriptItem],
+    locking: Sequence[ScriptItem],
+    *,
+    message: bytes = b"",
+    locktime: int = 0,
+) -> ScriptResult:
+    """Run the unlocking script, then the locking script on its stack, and judge the spend.
+
+    Parameters
+    ----------
+    unlocking, locking : sequence of bytes or str
+        Data pushes and opcode names.
+    message : bytes
+        What ``OP_CHECKSIG`` signatures must sign (the spending transaction).
+    locktime : int
+        The spending transaction's lock time, compared by
+        ``OP_CHECKLOCKTIMEVERIFY``.
+
+    Returns
+    -------
+    ScriptResult
+
+    Notes
+    -----
+    Running the scripts separately matters: until 2010 Bitcoin concatenated
+    them, and the unlocking script ``OP_TRUE OP_RETURN`` ended execution
+    early with true on top, spending any coin (CVE-2010-5141).
+
+    Examples
+    --------
+    >>> from blockchainkit.crypto import sha256
+    >>> from blockchainkit.vm import verify_script
+    >>> verify_script([b"secret"], ["OP_SHA256", sha256(b"secret"), "OP_EQUAL"]).valid
+    True
+    """
+    if not isinstance(message, bytes):
+        raise TypeError("message must be bytes")
+    integer(locktime, "locktime")
+    stack: list[bytes] = []
+    operations = [0]  # Shared counter, so a failed run still reports its work.
+    try:
+        _run(unlocking, stack, message, locktime, operations)
+        _run(locking, stack, message, locktime, operations)
+    except _Fail as failure:
+        return ScriptResult(False, tuple(stack), str(failure), operations[0])
+    if not stack or not _true(stack[-1]):
+        return ScriptResult(False, tuple(stack), "the top of the stack is not true", operations[0])
+    return ScriptResult(True, tuple(stack), None, operations[0])
+
+
+def p2pkh_locking(public: tuple[int, int]) -> tuple[ScriptItem, ...]:
+    """Pay to public-key hash: ``OP_DUP OP_HASH256 <hash> OP_EQUALVERIFY OP_CHECKSIG``.
+
+    The coin names only the hash of a key; the spender reveals the key and
+    a signature.
+    """
+    return (
+        "OP_DUP",
+        "OP_HASH256",
+        hash256(encode_public_key(public)),
+        "OP_EQUALVERIFY",
+        "OP_CHECKSIG",
+    )
+
+
+def p2pkh_unlocking(signature: SchnorrSignature, public: tuple[int, int]) -> tuple[ScriptItem, ...]:
+    """The matching unlocking script: ``<signature> <public key>``."""
+    return (encode_signature(signature), encode_public_key(public))
+
+
+def htlc_locking(
+    payment_hash: bytes,
+    recipient: tuple[int, int],
+    refund: tuple[int, int],
+    timeout: int,
+) -> tuple[ScriptItem, ...]:
+    """A hash time-locked contract.
+
+    The recipient can claim with a signature and the preimage of
+    ``payment_hash`` (SHA-256); after ``timeout``, the sender can take a
+    refund with its own signature::
+
+        OP_IF
+            OP_SHA256 <payment_hash> OP_EQUALVERIFY <recipient>
+        OP_ELSE
+            <timeout> OP_CHECKLOCKTIMEVERIFY OP_DROP <refund>
+        OP_ENDIF
+        OP_CHECKSIG
+    """
+    if not isinstance(payment_hash, bytes) or len(payment_hash) != 32:
+        raise ValueError("payment_hash must be a 32-byte SHA-256 digest")
+    return (
+        "OP_IF",
+        "OP_SHA256",
+        payment_hash,
+        "OP_EQUALVERIFY",
+        encode_public_key(recipient),
+        "OP_ELSE",
+        number(timeout),
+        "OP_CHECKLOCKTIMEVERIFY",
+        "OP_DROP",
+        encode_public_key(refund),
+        "OP_ENDIF",
+        "OP_CHECKSIG",
+    )