bitwalkit 0.1.0__tar.gz

bitwalkit-0.1.0/COPYING

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Elmeri Niemelä
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

bitwalkit-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include COPYING
+include README.md
+recursive-include tests/vectors *.json

bitwalkit-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: bitwalkit
+Version: 0.1.0
+Summary: Standalone watch-only Bitcoin wallet derivation and monitoring toolkit
+Author: Elmeri Niemelä
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/elmeriniemela/bitwalkit
+Keywords: bitcoin,rpc,bip32,electrum,wallet,watch-only
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: COPYING
+Provides-Extra: dev
+Requires-Dist: build>=1.3; extra == "dev"
+Requires-Dist: pyright>=1.1.400; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# bitwalkit — Watch-only Bitcoin wallet toolkit
+
+`bitwalkit` is a standalone, dependency-free Python toolkit for deriving and
+monitoring Bitcoin watch-only wallets. It handles public wallet data only: the
+library does not accept private extended keys, hold secrets, or sign
+transactions.
+
+Its public API covers three tasks:
+
+1. Derive single-signature and multisignature addresses from extended public
+   keys with `Account` and `MultisigAccount`.
+2. Query address balances, UTXOs, and transaction history through an Electrum
+   server with `ChainQuery`.
+3. Call a Bitcoin Core node over JSON-RPC with `NodeRPC`.
+
+The runtime uses only the Python standard library. A small, public-key-only
+secp256k1 implementation validates compressed public keys, derives
+non-hardened BIP32 child public keys, and applies the BIP341/BIP86 Taproot
+output-key tweak. It is not suitable for private-key handling or transaction
+signing. There are no packages to install at runtime.
+
+## Supported wallets
+
+- Single-key P2PKH (BIP44), P2SH-P2WPKH (BIP49), P2WPKH (BIP84), and P2TR
+  (BIP86)
+- P2WSH and P2SH-P2WSH multisig (BIP48), with optional BIP67 key sorting
+- Mainnet, testnet, and regtest addresses
+- BIP32 and SLIP-0132 public prefixes: xpub/tpub, ypub/upub, zpub/vpub, and the
+  corresponding multisig prefixes
+
+Only non-hardened children can be derived from an extended public key. Export
+an account-level public key from the signing wallet before using this library.
+
+## Install
+
+Install the latest release from PyPI:
+
+```bash
+python -m pip install bitwalkit
+```
+
+For development, clone and install from the repository root:
+
+```bash
+git clone https://github.com/elmeriniemela/bitwalkit.git
+cd bitwalkit
+python -m pip install -e '.[dev]'
+```
+
+## Usage
+
+```python
+import bitwalkit as bw
+
+# The SLIP-0132 prefix selects the default script type.
+account = bw.Account("zpub6r...")
+first_receive = account.receive_address(0)
+first_change = account.change_address(0)
+gap_limit = account.addresses(change=0, count=20)
+
+# Pass script_type explicitly when xpub alone is ambiguous, as with BIP86.
+taproot = bw.Account("xpub6B...", script_type="p2tr")
+
+# Multisig derives the same change/index path for every cosigner.
+multisig = bw.MultisigAccount(
+    ["Zpub...", "Zpub...", "Zpub..."],
+    m=2,
+    script_type="p2wsh",
+)
+
+# Query public chain state by address.
+chain = bw.ChainQuery("electrum.example.com", port=50002, use_ssl=True)
+balance = chain.get_balance(first_receive)
+utxos = chain.get_utxos(first_receive)
+history = chain.get_history(first_receive)
+balances = chain.get_balances(gap_limit)
+
+# Optional direct Bitcoin Core RPC access.
+node = bw.NodeRPC("http://127.0.0.1:8332", "rpcuser", "rpcpassword")
+height = node.getblockcount()
+```
+
+Network access is performed only when calling `ChainQuery` or `NodeRPC`.
+Address derivation and encoding are fully local.
+
+## Tests
+
+```bash
+python -m pytest
+python -m pyright
+```
+
+The suite covers malformed input handling, BIP32 public derivation, address
+encoding, BIP44/49/84/86 derivation, BIP341 taproot vectors, multisig,
+Electrum protocol behavior, and Bitcoin Core JSON-RPC response handling.
+
+## License
+
+MIT. See [COPYING](COPYING).

bitwalkit-0.1.0/README.md

@@ -0,0 +1,99 @@
+# bitwalkit — Watch-only Bitcoin wallet toolkit
+
+`bitwalkit` is a standalone, dependency-free Python toolkit for deriving and
+monitoring Bitcoin watch-only wallets. It handles public wallet data only: the
+library does not accept private extended keys, hold secrets, or sign
+transactions.
+
+Its public API covers three tasks:
+
+1. Derive single-signature and multisignature addresses from extended public
+   keys with `Account` and `MultisigAccount`.
+2. Query address balances, UTXOs, and transaction history through an Electrum
+   server with `ChainQuery`.
+3. Call a Bitcoin Core node over JSON-RPC with `NodeRPC`.
+
+The runtime uses only the Python standard library. A small, public-key-only
+secp256k1 implementation validates compressed public keys, derives
+non-hardened BIP32 child public keys, and applies the BIP341/BIP86 Taproot
+output-key tweak. It is not suitable for private-key handling or transaction
+signing. There are no packages to install at runtime.
+
+## Supported wallets
+
+- Single-key P2PKH (BIP44), P2SH-P2WPKH (BIP49), P2WPKH (BIP84), and P2TR
+  (BIP86)
+- P2WSH and P2SH-P2WSH multisig (BIP48), with optional BIP67 key sorting
+- Mainnet, testnet, and regtest addresses
+- BIP32 and SLIP-0132 public prefixes: xpub/tpub, ypub/upub, zpub/vpub, and the
+  corresponding multisig prefixes
+
+Only non-hardened children can be derived from an extended public key. Export
+an account-level public key from the signing wallet before using this library.
+
+## Install
+
+Install the latest release from PyPI:
+
+```bash
+python -m pip install bitwalkit
+```
+
+For development, clone and install from the repository root:
+
+```bash
+git clone https://github.com/elmeriniemela/bitwalkit.git
+cd bitwalkit
+python -m pip install -e '.[dev]'
+```
+
+## Usage
+
+```python
+import bitwalkit as bw
+
+# The SLIP-0132 prefix selects the default script type.
+account = bw.Account("zpub6r...")
+first_receive = account.receive_address(0)
+first_change = account.change_address(0)
+gap_limit = account.addresses(change=0, count=20)
+
+# Pass script_type explicitly when xpub alone is ambiguous, as with BIP86.
+taproot = bw.Account("xpub6B...", script_type="p2tr")
+
+# Multisig derives the same change/index path for every cosigner.
+multisig = bw.MultisigAccount(
+    ["Zpub...", "Zpub...", "Zpub..."],
+    m=2,
+    script_type="p2wsh",
+)
+
+# Query public chain state by address.
+chain = bw.ChainQuery("electrum.example.com", port=50002, use_ssl=True)
+balance = chain.get_balance(first_receive)
+utxos = chain.get_utxos(first_receive)
+history = chain.get_history(first_receive)
+balances = chain.get_balances(gap_limit)
+
+# Optional direct Bitcoin Core RPC access.
+node = bw.NodeRPC("http://127.0.0.1:8332", "rpcuser", "rpcpassword")
+height = node.getblockcount()
+```
+
+Network access is performed only when calling `ChainQuery` or `NodeRPC`.
+Address derivation and encoding are fully local.
+
+## Tests
+
+```bash
+python -m pytest
+python -m pyright
+```
+
+The suite covers malformed input handling, BIP32 public derivation, address
+encoding, BIP44/49/84/86 derivation, BIP341 taproot vectors, multisig,
+Electrum protocol behavior, and Bitcoin Core JSON-RPC response handling.
+
+## License
+
+MIT. See [COPYING](COPYING).

bitwalkit-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bitwalkit"
+version = "0.1.0"
+description = "Standalone watch-only Bitcoin wallet derivation and monitoring toolkit"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Elmeri Niemelä" }]
+keywords = ["bitcoin", "rpc", "bip32", "electrum", "wallet", "watch-only"]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.3",
+    "pyright>=1.1.400",
+    "pytest>=8",
+]
+
+[project.urls]
+Homepage = "https://github.com/elmeriniemela/bitwalkit"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

bitwalkit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bitwalkit-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)