bitwalkit 0.1.0__py3-none-any.whl

bitwalkit/__init__.py

@@ -0,0 +1,74 @@
+"""bitwalkit -- Bitcoin Wallet Toolkit.
+
+Three dependency-free capabilities:
+
+* :class:`NodeRPC` -- call a Bitcoin Core node over JSON-RPC.
+* :class:`Account` / :class:`MultisigAccount` -- watch-only HD address
+  derivation from master/account extended public keys (xpub/ypub/zpub/...).
+* :class:`ChainQuery` -- fetch an address's balance / UTXOs / history (backed
+  by an Electrum server, but the caller only ever deals in addresses).
+"""
+
+from __future__ import annotations
+
+from .address import (
+    address_from_pubkey,
+    address_from_script,
+    address_to_script,
+    address_to_scripthash,
+    p2ms_script,
+    script_to_scripthash,
+)
+from .bip32 import ExtendedKey
+from .chain import Balance, ChainQuery, HistoryEntry, Utxo
+from .descriptor import descriptor_checksum
+from .encoding import (
+    base58check_decode,
+    base58check_encode,
+    bech32_decode,
+    bech32_encode,
+)
+from .errors import (
+    BitwalkitError,
+    ConnectionError,
+    DerivationError,
+    EncodingError,
+    RpcError,
+)
+from .hd import Account, MultisigAccount
+from .rpc import NodeRPC
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # rpc
+    "NodeRPC",
+    # derivation
+    "ExtendedKey",
+    "Account",
+    "MultisigAccount",
+    "descriptor_checksum",
+    # balances
+    "ChainQuery",
+    "Balance",
+    "Utxo",
+    "HistoryEntry",
+    # address / encoding helpers
+    "address_from_pubkey",
+    "address_from_script",
+    "address_to_script",
+    "address_to_scripthash",
+    "script_to_scripthash",
+    "p2ms_script",
+    "base58check_encode",
+    "base58check_decode",
+    "bech32_encode",
+    "bech32_decode",
+    # errors
+    "BitwalkitError",
+    "RpcError",
+    "ConnectionError",
+    "DerivationError",
+    "EncodingError",
+]

bitwalkit/_electrum.py

@@ -0,0 +1,136 @@
+"""Internal ElectrumX client: newline-delimited JSON-RPC 2.0 over TCP/SSL.
+
+This is a private module -- callers use :class:`bitwalkit.chain.ChainQuery`,
+which speaks in addresses and hides scripthashes and Electrum method names.
+The client supports TCP or TLS connections, configurable timeouts, and batch
+requests.
+"""
+
+from __future__ import annotations
+
+import json
+import socket
+import ssl
+
+from .errors import ConnectionError, RpcError
+
+__all__ = ["ElectrumClient"]
+
+
+class ElectrumClient:
+    """A short-lived connection to an ElectrumX server."""
+
+    def __init__(self, host: str, port: int, use_ssl: bool = False, timeout: float = 10) -> None:
+        self.host = host
+        self.port = port
+        self.use_ssl = use_ssl
+        self.timeout = timeout
+        self._sock: socket.socket | None = None
+        self._buf = b""
+
+    # -- connection -------------------------------------------------------- #
+
+    def connect(self) -> "ElectrumClient":
+        if self._sock is not None:
+            return self
+        try:
+            sock = socket.create_connection((self.host, self.port), timeout=self.timeout)
+            if self.use_ssl:
+                ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+                ctx.check_hostname = False
+                ctx.verify_mode = ssl.CERT_NONE
+                sock = ctx.wrap_socket(sock, server_hostname=self.host)
+            sock.settimeout(self.timeout)
+        except (OSError, ssl.SSLError) as exc:
+            raise ConnectionError(
+                f"unable to connect to Electrum server {self.host}:{self.port}: {exc}"
+            ) from exc
+        self._sock = sock
+        return self
+
+    def close(self) -> None:
+        if self._sock is not None:
+            try:
+                self._sock.close()
+            finally:
+                self._sock = None
+                self._buf = b""
+
+    def __enter__(self) -> "ElectrumClient":
+        return self.connect()
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # -- transport --------------------------------------------------------- #
+
+    def _send(self, obj) -> None:
+        if self._sock is None:
+            self.connect()
+        assert self._sock is not None
+        try:
+            self._sock.sendall(json.dumps(obj).encode() + b"\n")
+        except OSError as exc:
+            raise ConnectionError(f"Electrum send failed: {exc}") from exc
+
+    def _recv_line(self) -> bytes:
+        assert self._sock is not None
+        while b"\n" not in self._buf:
+            try:
+                chunk = self._sock.recv(4096)
+            except socket.timeout as exc:
+                raise ConnectionError("Electrum server timed out") from exc
+            except OSError as exc:
+                raise ConnectionError(f"Electrum recv failed: {exc}") from exc
+            if not chunk:
+                raise ConnectionError("Electrum server closed the connection")
+            self._buf += chunk
+        line, self._buf = self._buf.split(b"\n", 1)
+        return line
+
+    @staticmethod
+    def _result(item: dict):
+        if not isinstance(item, dict):
+            raise RpcError(f"invalid Electrum response: {item!r}")
+        error = item.get("error")
+        if error:
+            if isinstance(error, dict):
+                raise RpcError(error.get("message", "Electrum error"), error.get("code"))
+            raise RpcError(str(error))
+        if "result" not in item:
+            raise RpcError(f"Electrum response has no result: {item!r}")
+        return item["result"]
+
+    def _receive(self):
+        try:
+            return json.loads(self._recv_line())
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise RpcError("invalid JSON from Electrum server") from exc
+
+    # -- public calls ------------------------------------------------------ #
+
+    def call(self, method: str, params: list):
+        self._send({"jsonrpc": "2.0", "id": 0, "method": method, "params": params})
+        data = self._receive()
+        if not isinstance(data, dict) or data.get("id") != 0:
+            raise RpcError(f"mismatched Electrum response: {data!r}")
+        return self._result(data)
+
+    def batch(self, method: str, params_list: list[list]) -> list:
+        """Call ``method`` once per entry in ``params_list``; results stay in order."""
+        if not params_list:
+            return []
+        reqs = [
+            {"jsonrpc": "2.0", "id": i, "method": method, "params": params}
+            for i, params in enumerate(params_list)
+        ]
+        self._send(reqs)
+        data = self._receive()
+        if not isinstance(data, list) or len(data) != len(params_list):
+            raise RpcError("malformed Electrum batch response")
+        if any(not isinstance(item, dict) or "id" not in item for item in data):
+            raise RpcError("malformed Electrum batch response")
+        by_id = {item["id"]: item for item in data}
+        if set(by_id) != set(range(len(params_list))):
+            raise RpcError("mismatched Electrum batch response ids")
+        return [self._result(by_id[i]) for i in range(len(params_list))]

bitwalkit/_secp.py

@@ -0,0 +1,126 @@
+"""Minimal secp256k1 public-key arithmetic used by bitwalkit.
+
+The implementation is intentionally limited to parsing, serializing, adding,
+and multiplying public curve points. It is variable-time and must not be used
+with private or otherwise secret scalars.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+__all__ = ["G", "GE"]
+
+_FIELD = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F
+_ORDER = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141
+_GX = 0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798
+_GY = 0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8
+
+
+@dataclass(frozen=True, slots=True)
+class GE:
+    """A secp256k1 curve point, or infinity when coordinates are absent."""
+
+    x: int | None = None
+    y: int | None = None
+
+    ORDER: ClassVar[int] = _ORDER
+
+    def __post_init__(self) -> None:
+        if self.x is None or self.y is None:
+            if self.x is not None or self.y is not None:
+                raise ValueError("both point coordinates must be present")
+            return
+        if not (0 <= self.x < _FIELD and 0 <= self.y < _FIELD):
+            raise ValueError("point coordinate out of range")
+        if (self.y * self.y - self.x * self.x * self.x - 7) % _FIELD:
+            raise ValueError("point is not on secp256k1")
+
+    @property
+    def infinity(self) -> bool:
+        """Whether this is the point at infinity."""
+        return self.x is None
+
+    def __add__(self, other: object) -> GE:
+        """Add two curve points."""
+        if not isinstance(other, GE):
+            return NotImplemented
+        if self.infinity:
+            return other
+        if other.infinity:
+            return self
+
+        x1, y1, x2, y2 = self.x, self.y, other.x, other.y
+        assert x1 is not None and y1 is not None
+        assert x2 is not None and y2 is not None
+
+        if x1 == x2:
+            if y1 != y2 or y1 == 0:
+                return GE()
+            numerator = 3 * x1 * x1
+            denominator = 2 * y1
+        else:
+            numerator = y2 - y1
+            denominator = x2 - x1
+
+        slope = numerator * pow(denominator % _FIELD, -1, _FIELD) % _FIELD
+        x3 = (slope * slope - x1 - x2) % _FIELD
+        y3 = (slope * (x1 - x3) - y1) % _FIELD
+        return GE(x3, y3)
+
+    def __rmul__(self, scalar: object) -> GE:
+        """Multiply this point by an integer using double-and-add."""
+        if not isinstance(scalar, int):
+            return NotImplemented
+
+        scalar %= self.ORDER
+        result = GE()
+        addend = self
+        while scalar:
+            if scalar & 1:
+                result = result + addend
+            addend = addend + addend
+            scalar >>= 1
+        return result
+
+    @classmethod
+    def lift_x(cls, x: int) -> GE:
+        """Lift an x-coordinate to the curve point whose y-coordinate is even."""
+        if not isinstance(x, int) or not 0 <= x < _FIELD:
+            raise ValueError("x-coordinate out of range")
+        y_squared = (pow(x, 3, _FIELD) + 7) % _FIELD
+        y = pow(y_squared, (_FIELD + 1) // 4, _FIELD)
+        if y * y % _FIELD != y_squared:
+            raise ValueError("x-coordinate is not on secp256k1")
+        if y & 1:
+            y = _FIELD - y
+        return cls(x, y)
+
+    @classmethod
+    def from_bytes_compressed(cls, encoded: bytes) -> GE:
+        """Parse a 33-byte compressed public key."""
+        if len(encoded) != 33 or encoded[0] not in (2, 3):
+            raise ValueError("invalid compressed public key")
+        point = cls.lift_x(int.from_bytes(encoded[1:], "big"))
+        assert point.x is not None and point.y is not None
+        if (point.y & 1) != (encoded[0] & 1):
+            return cls(point.x, _FIELD - point.y)
+        return point
+
+    def to_bytes_compressed(self) -> bytes:
+        """Serialize a finite point as a 33-byte compressed public key."""
+        if self.infinity:
+            raise ValueError("cannot serialize the point at infinity")
+        assert self.x is not None and self.y is not None
+        return bytes([2 | (self.y & 1)]) + self.x.to_bytes(32, "big")
+
+    def to_bytes_xonly(self) -> bytes:
+        """Serialize the x-coordinate of a finite point."""
+        if self.infinity:
+            raise ValueError("cannot serialize the point at infinity")
+        assert self.x is not None
+        return self.x.to_bytes(32, "big")
+
+
+G = GE(_GX, _GY)

bitwalkit/address.py

@@ -0,0 +1,190 @@
+"""Bitcoin scripts, addresses, and Electrum protocol scripthashes.
+
+Build a scriptPubKey and address from a public key or multisig script for
+P2PKH, P2SH-P2WPKH, P2WPKH, P2WSH, P2SH-P2WSH, and P2TR. Addresses can also
+be decoded back to scriptPubKeys for watch-only chain queries.
+"""
+
+from __future__ import annotations
+
+from ._secp import G, GE
+from .encoding import base58check_decode, base58check_encode, bech32_decode, bech32_encode
+from .errors import EncodingError
+from .hashing import hash160, sha256, tagged_hash
+
+__all__ = [
+    "NETWORKS",
+    "address_from_pubkey",
+    "address_from_script",
+    "address_to_script",
+    "address_to_scripthash",
+    "script_to_scripthash",
+    "p2pkh_script",
+    "p2sh_script",
+    "p2wpkh_script",
+    "p2wsh_script",
+    "p2tr_script",
+    "p2ms_script",
+    "p2pk_script",
+]
+
+# Base58 version bytes and bech32 HRP per network.
+NETWORKS: dict[str, dict] = {
+    "mainnet": {"p2pkh": 0x00, "p2sh": 0x05, "hrp": "bc"},
+    "testnet": {"p2pkh": 0x6F, "p2sh": 0xC4, "hrp": "tb"},
+    "regtest": {"p2pkh": 0x6F, "p2sh": 0xC4, "hrp": "bcrt"},
+}
+_HRPS = {params["hrp"]: net for net, params in NETWORKS.items()}
+
+# Opcodes.
+OP_DUP = 0x76
+OP_HASH160 = 0xA9
+OP_EQUAL = 0x87
+OP_EQUALVERIFY = 0x88
+OP_CHECKSIG = 0xAC
+OP_CHECKMULTISIG = 0xAE
+OP_0 = 0x00
+OP_1 = 0x51  # OP_1..OP_16 are 0x51..0x60
+
+
+def _pushdata(data: bytes) -> bytes:
+    """Minimal push of ``data`` (adequate for keys/hashes, all < 76 bytes)."""
+    if len(data) < 0x4C:
+        return bytes([len(data)]) + data
+    raise EncodingError("pushdata too large for this helper")
+
+
+# --------------------------------------------------------------------------- #
+# Raw scriptPubKey / script builders
+# --------------------------------------------------------------------------- #
+
+def p2pkh_script(pubkey: bytes) -> bytes:
+    h = hash160(pubkey)
+    return bytes([OP_DUP, OP_HASH160, len(h)]) + h + bytes([OP_EQUALVERIFY, OP_CHECKSIG])
+
+
+def p2sh_script(script_hash: bytes) -> bytes:
+    return bytes([OP_HASH160, len(script_hash)]) + script_hash + bytes([OP_EQUAL])
+
+
+def p2wpkh_script(pubkey: bytes) -> bytes:
+    h = hash160(pubkey)
+    return bytes([OP_0, len(h)]) + h
+
+
+def p2wsh_script(witness_script: bytes) -> bytes:
+    h = sha256(witness_script)
+    return bytes([OP_0, len(h)]) + h
+
+
+def p2pk_script(pubkey: bytes) -> bytes:
+    return _pushdata(pubkey) + bytes([OP_CHECKSIG])
+
+
+def p2ms_script(m: int, pubkeys: list[bytes]) -> bytes:
+    """Bare multisig script (used as the witness/redeem script for P2WSH/P2SH)."""
+    n = len(pubkeys)
+    if not (1 <= m <= n <= 16):
+        raise EncodingError(f"invalid multisig m-of-n: {m}-of-{n}")
+    body = b"".join(_pushdata(pk) for pk in pubkeys)
+    return bytes([OP_1 - 1 + m]) + body + bytes([OP_1 - 1 + n, OP_CHECKMULTISIG])
+
+
+def _taproot_output_key(internal_pubkey: bytes) -> bytes:
+    """BIP86 output key: tweak the internal key with no script tree."""
+    xonly = internal_pubkey[-32:] if len(internal_pubkey) in (32, 33) else internal_pubkey
+    if len(xonly) != 32:
+        raise EncodingError("invalid taproot internal key length")
+    t = int.from_bytes(tagged_hash("TapTweak", xonly), "big")
+    if t >= GE.ORDER:
+        raise EncodingError("invalid taproot tweak")
+    try:
+        internal_point = GE.lift_x(int.from_bytes(xonly, "big"))
+    except ValueError as exc:
+        raise EncodingError("invalid taproot internal key") from exc
+    q = internal_point + (t * G)
+    if q.infinity:
+        raise EncodingError("taproot output key is infinity")
+    return q.to_bytes_xonly()
+
+
+def p2tr_script(internal_pubkey: bytes) -> bytes:
+    program = _taproot_output_key(internal_pubkey)
+    return bytes([OP_1, len(program)]) + program
+
+
+# --------------------------------------------------------------------------- #
+# Address encoding
+# --------------------------------------------------------------------------- #
+
+def _b58(version_byte: int, payload: bytes) -> str:
+    return base58check_encode(bytes([version_byte]) + payload)
+
+
+def address_from_pubkey(pubkey: bytes, script_type: str, network: str = "mainnet") -> str:
+    """Address for a single public key under ``script_type``.
+
+    ``script_type`` is one of p2pkh, p2sh-p2wpkh, p2wpkh, or p2tr.
+    """
+    params = NETWORKS[network]
+    if script_type == "p2pkh":
+        return _b58(params["p2pkh"], hash160(pubkey))
+    if script_type == "p2wpkh":
+        return bech32_encode(params["hrp"], 0, hash160(pubkey))
+    if script_type == "p2sh-p2wpkh":
+        redeem = p2wpkh_script(pubkey)  # 0x00 0x14 <hash160(pubkey)>
+        return _b58(params["p2sh"], hash160(redeem))
+    if script_type == "p2tr":
+        return bech32_encode(params["hrp"], 1, _taproot_output_key(pubkey))
+    raise EncodingError(f"unsupported single-key script type: {script_type}")
+
+
+def address_from_script(witness_script: bytes, script_type: str, network: str = "mainnet") -> str:
+    """Address wrapping a redeem/witness script (multisig): p2wsh or p2sh-p2wsh."""
+    params = NETWORKS[network]
+    if script_type == "p2wsh":
+        return bech32_encode(params["hrp"], 0, sha256(witness_script))
+    if script_type == "p2sh-p2wsh":
+        redeem = p2wsh_script(witness_script)  # 0x00 0x20 <sha256(script)>
+        return _b58(params["p2sh"], hash160(redeem))
+    if script_type == "p2sh":
+        return _b58(params["p2sh"], hash160(witness_script))
+    raise EncodingError(f"unsupported script-wrapping type: {script_type}")
+
+
+# --------------------------------------------------------------------------- #
+# Address decoding + scripthash
+# --------------------------------------------------------------------------- #
+
+def address_to_script(address: str, network: str | None = None) -> bytes:
+    """Decode an address into its scriptPubKey bytes."""
+    lowered = address.lower()
+    pos = lowered.rfind("1")
+    hrp = lowered[:pos] if pos > 0 else None
+    if hrp in _HRPS:
+        if network is not None and _HRPS[hrp] != network:
+            raise EncodingError(f"address is {_HRPS[hrp]}, expected {network}")
+        _hrp, witver, program = bech32_decode(address)
+        op = OP_0 if witver == 0 else (OP_1 - 1 + witver)
+        return bytes([op, len(program)]) + program
+
+    payload = base58check_decode(address)
+    version, h = payload[0], payload[1:]
+    for net, params in NETWORKS.items():
+        if network is not None and net != network:
+            continue
+        if version == params["p2pkh"]:
+            return bytes([OP_DUP, OP_HASH160, len(h)]) + h + bytes([OP_EQUALVERIFY, OP_CHECKSIG])
+        if version == params["p2sh"]:
+            return p2sh_script(h)
+    raise EncodingError(f"unrecognized address version byte {version:#04x}")
+
+
+def script_to_scripthash(script: bytes) -> str:
+    """Electrum protocol scripthash: ``sha256(scriptPubKey)`` reversed, hex."""
+    return sha256(script)[::-1].hex()
+
+
+def address_to_scripthash(address: str, network: str | None = None) -> str:
+    """Electrum scripthash for an address (SHA256 of scriptPubKey, reversed)."""
+    return script_to_scripthash(address_to_script(address, network))