btc-toolkit 1.0.0__py3-none-any.whl

btc_toolkit/__init__.py

@@ -0,0 +1,3 @@
+"""btc-toolkit — Bitcoin CLI tools. Zero dependencies, no Bitcoin Core required."""
+
+__version__ = "1.0.0"

btc_toolkit/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as: python -m btc_toolkit <command> ..."""
+
+import sys
+from .cli import run
+
+sys.exit(run())

btc_toolkit/api.py

@@ -0,0 +1,94 @@
+"""
+Shared Mempool.space API client.
+
+Centralizes all HTTP communication with the Mempool.space REST API.
+Every subcommand (opreturn, balance, fees, block, utxo) uses this module
+instead of duplicating connection logic.
+
+No external dependencies — standard library only.
+"""
+
+import json
+import urllib.request
+import urllib.error
+
+from . import __version__
+
+# Mempool.space API base URLs
+MEMPOOL_API = "https://mempool.space/api"
+MEMPOOL_TESTNET_API = "https://mempool.space/testnet/api"
+
+SUPPORTED_NETWORKS = ("mainnet", "testnet")
+
+_USER_AGENT = f"btc-toolkit/{__version__}"
+_TIMEOUT = 15
+
+
+class MempoolAPIError(Exception):
+    """Raised when the Mempool.space API returns an error."""
+
+
+class NotFoundError(MempoolAPIError):
+    """Raised when a requested resource (tx, address, block) is not found."""
+
+
+def get_api_base(network: str) -> str:
+    """Return the correct API base URL for the given network."""
+    if network not in SUPPORTED_NETWORKS:
+        raise ValueError(
+            f"Unsupported network: {network}. Use one of: {SUPPORTED_NETWORKS}"
+        )
+    if network == "testnet":
+        return MEMPOOL_TESTNET_API
+    return MEMPOOL_API
+
+
+def get_json(path: str, network: str = "mainnet") -> dict | list:
+    """
+    GET a Mempool.space API endpoint and return parsed JSON.
+
+    Args:
+        path: API path beginning with '/', e.g. '/tx/<txid>' or '/address/<addr>'.
+        network: 'mainnet' or 'testnet'.
+
+    Returns:
+        Parsed JSON (dict or list).
+
+    Raises:
+        NotFoundError: On HTTP 404.
+        MempoolAPIError: On other HTTP or connection errors.
+    """
+    api_base = get_api_base(network)
+    url = f"{api_base}{path}"
+
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+        with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            raise NotFoundError(f"Not found: {path}") from e
+        raise MempoolAPIError(f"API error {e.code}: {e.reason}") from e
+    except urllib.error.URLError as e:
+        raise MempoolAPIError(f"Connection error: {e.reason}") from e
+
+
+def get_text(path: str, network: str = "mainnet") -> str:
+    """
+    GET a Mempool.space API endpoint that returns plain text (not JSON).
+
+    Used for endpoints like /blocks/tip/height that return a bare number.
+    """
+    api_base = get_api_base(network)
+    url = f"{api_base}{path}"
+
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+        with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp:
+            return resp.read().decode("utf-8").strip()
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            raise NotFoundError(f"Not found: {path}") from e
+        raise MempoolAPIError(f"API error {e.code}: {e.reason}") from e
+    except urllib.error.URLError as e:
+        raise MempoolAPIError(f"Connection error: {e.reason}") from e

btc_toolkit/balance.py

@@ -0,0 +1,132 @@
+"""
+Address balance checker.
+
+Queries the Mempool.space API for an address and computes its
+confirmed and unconfirmed (mempool) balances.
+
+Balance is derived as funded_txo_sum - spent_txo_sum, following the
+Esplora/Mempool.space API model. All amounts are in satoshis, with
+BTC conversion provided for display.
+"""
+
+from dataclasses import dataclass
+
+from .api import get_json, NotFoundError
+
+SATS_PER_BTC = 100_000_000
+
+
+class AddressNotFoundError(NotFoundError):
+    """Raised when an address has no data or is invalid upstream."""
+
+
+@dataclass
+class AddressBalance:
+    """Confirmed and unconfirmed balance for a Bitcoin address."""
+
+    address: str
+    confirmed_sats: int
+    unconfirmed_sats: int
+    confirmed_tx_count: int
+    mempool_tx_count: int
+    funded_sats: int
+    spent_sats: int
+
+    @property
+    def total_sats(self) -> int:
+        """Confirmed + unconfirmed balance."""
+        return self.confirmed_sats + self.unconfirmed_sats
+
+    @staticmethod
+    def sats_to_btc(sats: int) -> str:
+        """Format a satoshi amount as a BTC string with 8 decimals."""
+        # Use integer arithmetic to avoid float precision issues
+        sign = "-" if sats < 0 else ""
+        sats = abs(sats)
+        whole = sats // SATS_PER_BTC
+        frac = sats % SATS_PER_BTC
+        return f"{sign}{whole}.{frac:08d}"
+
+    def to_dict(self) -> dict:
+        return {
+            "address": self.address,
+            "confirmed": {
+                "sats": self.confirmed_sats,
+                "btc": self.sats_to_btc(self.confirmed_sats),
+            },
+            "unconfirmed": {
+                "sats": self.unconfirmed_sats,
+                "btc": self.sats_to_btc(self.unconfirmed_sats),
+            },
+            "total": {
+                "sats": self.total_sats,
+                "btc": self.sats_to_btc(self.total_sats),
+            },
+            "confirmed_tx_count": self.confirmed_tx_count,
+            "mempool_tx_count": self.mempool_tx_count,
+            "funded_sats": self.funded_sats,
+            "spent_sats": self.spent_sats,
+        }
+
+
+def _validate_address(address: str) -> str:
+    """
+    Basic sanity check on a Bitcoin address.
+
+    This is a lightweight format guard, not full validation — the
+    Mempool.space API is the source of truth and will reject malformed
+    addresses. We only catch obviously bad input early.
+    """
+    address = address.strip()
+    if not address:
+        raise ValueError("Address cannot be empty")
+
+    # Bitcoin addresses are alphanumeric and within a reasonable length range.
+    # Bech32 (bc1...) can be up to 90 chars; legacy is ~26-35.
+    if len(address) < 14 or len(address) > 100:
+        raise ValueError(f"Invalid address length: {address}")
+
+    if not all(c.isalnum() for c in address):
+        raise ValueError(f"Invalid characters in address: {address}")
+
+    return address
+
+
+def get_balance(address: str, network: str = "mainnet") -> AddressBalance:
+    """
+    Fetch and compute the balance for a Bitcoin address.
+
+    Args:
+        address: The Bitcoin address (any type: P2PKH, P2SH, Bech32, Taproot).
+        network: 'mainnet' or 'testnet'.
+
+    Returns:
+        An AddressBalance with confirmed and unconfirmed amounts.
+
+    Raises:
+        ValueError: If the address format is obviously invalid.
+        AddressNotFoundError: If the address is not found upstream.
+        MempoolAPIError: On other API errors.
+    """
+    address = _validate_address(address)
+
+    try:
+        data = get_json(f"/address/{address}", network)
+    except NotFoundError as e:
+        raise AddressNotFoundError(f"Address not found: {address}") from e
+
+    chain = data.get("chain_stats", {})
+    mempool = data.get("mempool_stats", {})
+
+    confirmed = chain.get("funded_txo_sum", 0) - chain.get("spent_txo_sum", 0)
+    unconfirmed = mempool.get("funded_txo_sum", 0) - mempool.get("spent_txo_sum", 0)
+
+    return AddressBalance(
+        address=data.get("address", address),
+        confirmed_sats=confirmed,
+        unconfirmed_sats=unconfirmed,
+        confirmed_tx_count=chain.get("tx_count", 0),
+        mempool_tx_count=mempool.get("tx_count", 0),
+        funded_sats=chain.get("funded_txo_sum", 0),
+        spent_sats=chain.get("spent_txo_sum", 0),
+    )

btc_toolkit/block.py

@@ -0,0 +1,139 @@
+"""
+Block info explorer.
+
+Queries the Mempool.space API for block metadata by height, hash,
+or the chain tip.
+
+Endpoints:
+    GET /api/block/:hash          -> block details (JSON)
+    GET /api/block-height/:height -> block hash (plain text)
+    GET /api/blocks/tip/height    -> current tip height (plain text)
+"""
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from .api import get_json, get_text, NotFoundError
+
+
+class BlockNotFoundError(NotFoundError):
+    """Raised when a block height or hash is not found."""
+
+
+@dataclass
+class BlockInfo:
+    """Metadata for a single Bitcoin block."""
+
+    hash: str
+    height: int
+    timestamp: int
+    tx_count: int
+    size: int
+    weight: int
+    version: int
+    merkle_root: str
+    previousblockhash: str
+    nonce: int
+    bits: int
+    difficulty: float
+    mediantime: int
+
+    @property
+    def timestamp_utc(self) -> str:
+        """Block timestamp as an ISO-8601 UTC string."""
+        return datetime.fromtimestamp(self.timestamp, tz=timezone.utc).strftime(
+            "%Y-%m-%d %H:%M:%S UTC"
+        )
+
+    @property
+    def size_mb(self) -> float:
+        """Block size in MB (1 MB = 1_000_000 bytes)."""
+        return self.size / 1_000_000
+
+    def to_dict(self) -> dict:
+        return {
+            "hash": self.hash,
+            "height": self.height,
+            "timestamp": self.timestamp,
+            "timestamp_utc": self.timestamp_utc,
+            "tx_count": self.tx_count,
+            "size_bytes": self.size,
+            "size_mb": round(self.size_mb, 2),
+            "weight": self.weight,
+            "version": self.version,
+            "merkle_root": self.merkle_root,
+            "previousblockhash": self.previousblockhash,
+            "nonce": self.nonce,
+            "bits": self.bits,
+            "difficulty": self.difficulty,
+            "mediantime": self.mediantime,
+        }
+
+
+def _is_block_hash(ref: str) -> bool:
+    """A block hash is 64 hex chars; a height is a decimal number."""
+    ref = ref.strip().lower()
+    return len(ref) == 64 and all(c in "0123456789abcdef" for c in ref)
+
+
+def _is_height(ref: str) -> bool:
+    return ref.strip().isdigit()
+
+
+def get_tip_height(network: str = "mainnet") -> int:
+    """Return the current chain tip height."""
+    return int(get_text("/blocks/tip/height", network))
+
+
+def get_block(ref: str, network: str = "mainnet") -> BlockInfo:
+    """
+    Fetch block metadata by height, hash, or 'latest'.
+
+    Args:
+        ref: Block height (decimal), block hash (64 hex chars),
+             or the literal string 'latest' for the chain tip.
+        network: 'mainnet' or 'testnet'.
+
+    Returns:
+        A BlockInfo with the block's metadata.
+
+    Raises:
+        ValueError: If ref is neither a height, a hash, nor 'latest'.
+        BlockNotFoundError: If the block does not exist.
+        MempoolAPIError: On other API errors.
+    """
+    ref = ref.strip()
+
+    try:
+        if ref.lower() == "latest":
+            height = get_tip_height(network)
+            block_hash = get_text(f"/block-height/{height}", network)
+        elif _is_height(ref):
+            block_hash = get_text(f"/block-height/{ref}", network)
+        elif _is_block_hash(ref):
+            block_hash = ref.lower()
+        else:
+            raise ValueError(
+                f"Invalid block reference: {ref!r}. "
+                "Use a height, a 64-char hash, or 'latest'."
+            )
+
+        data = get_json(f"/block/{block_hash}", network)
+    except NotFoundError as e:
+        raise BlockNotFoundError(f"Block not found: {ref}") from e
+
+    return BlockInfo(
+        hash=data.get("id", block_hash),
+        height=data.get("height", 0),
+        timestamp=data.get("timestamp", 0),
+        tx_count=data.get("tx_count", 0),
+        size=data.get("size", 0),
+        weight=data.get("weight", 0),
+        version=data.get("version", 0),
+        merkle_root=data.get("merkle_root", ""),
+        previousblockhash=data.get("previousblockhash", ""),
+        nonce=data.get("nonce", 0),
+        bits=data.get("bits", 0),
+        difficulty=data.get("difficulty", 0),
+        mediantime=data.get("mediantime", 0),
+    )