mm-btc 0.5.5__py3-none-any.whl → 0.6.0__py3-none-any.whl

mm_btc/__init__.py

@@ -0,0 +1 @@
+"""mm-btc: Bitcoin wallet, transaction, and blockchain utilities."""

mm_btc/blockstream.py

@@ -1,3 +1,5 @@
+"""Blockstream Esplora API client for querying Bitcoin blockchain data."""
+
 from collections.abc import Sequence
 
 from mm_http import HttpResponse, http_request
@@ -5,18 +7,19 @@ from mm_result import Result
 from mm_web3 import random_proxy
 from pydantic import BaseModel
 
+# Blockstream API base URLs.
 MAINNET_BASE_URL = "https://blockstream.info/api"
 TESTNET_BASE_URL = "https://blockstream.info/testnet/api"
 
-# ERROR_INVALID_ADDRESS = "INVALID_ADDRESS"
-# ERROR_INVALID_NETWORK = "INVALID_NETWORK"
-
+# Error constant for HTTP 400 responses.
 ERROR_400_BAD_REQUEST = "400 Bad Request"
 
 type Proxy = str | Sequence[str] | None
 
 
 class Mempool(BaseModel):
+    """Bitcoin mempool summary statistics."""
+
     count: int
     vsize: int
     total_fee: int
@@ -24,7 +27,11 @@ class Mempool(BaseModel):
 
 
 class Address(BaseModel):
+    """Bitcoin address information with on-chain and mempool statistics."""
+
     class ChainStats(BaseModel):
+        """Confirmed on-chain transaction statistics for an address."""
+
         funded_txo_count: int
         funded_txo_sum: int
         spent_txo_count: int
@@ -32,6 +39,8 @@ class Address(BaseModel):
         tx_count: int
 
     class MempoolStats(BaseModel):
+        """Unconfirmed mempool transaction statistics for an address."""
+
         funded_txo_count: int
         funded_txo_sum: int
         spent_txo_count: int
@@ -43,7 +52,11 @@ class Address(BaseModel):
 
 
 class Utxo(BaseModel):
+    """Unspent transaction output."""
+
     class Status(BaseModel):
+        """Confirmation status of a UTXO."""
+
         confirmed: bool
         block_height: int
         block_hash: str
@@ -56,7 +69,10 @@ class Utxo(BaseModel):
 
 
 class BlockstreamClient:
+    """HTTP client for the Blockstream Esplora REST API."""
+
     def __init__(self, testnet: bool = False, timeout: float = 5, proxies: Proxy = None, attempts: int = 1) -> None:
+        """Initialize the client with network, timeout, proxy, and retry settings."""
         self.testnet = testnet
         self.timeout = timeout
         self.proxies = proxies
@@ -64,41 +80,46 @@ class BlockstreamClient:
         self.base_url = TESTNET_BASE_URL if testnet else MAINNET_BASE_URL
 
     async def get_address(self, address: str) -> Result[Address]:
+        """Fetch address information including chain and mempool stats."""
         result: Result[Address] = Result.err("not started yet")
         for _ in range(self.attempts):
             res = await self._request(f"/address/{address}")
             try:
                 if res.status_code == 400:
                     return res.to_result_err("400 Bad Request")
-                return res.to_result_ok(Address(**res.parse_json()))
+                return res.to_result_ok(Address(**res.json_body().unwrap()))
             except Exception as e:
                 result = res.to_result_err(e)
         return result
 
     async def get_confirmed_balance(self, address: str) -> Result[int]:
+        """Fetch the confirmed balance (funded minus spent) for an address."""
         return (await self.get_address(address)).chain(
             lambda a: Result.ok(a.chain_stats.funded_txo_sum - a.chain_stats.spent_txo_sum)
         )
 
     async def get_utxo(self, address: str) -> Result[list[Utxo]]:
+        """Fetch the list of UTXOs for an address."""
         result: Result[list[Utxo]] = Result.err("not started yet")
         for _ in range(self.attempts):
             res = await self._request(f"/address/{address}/utxo")
             try:
-                return res.to_result_ok([Utxo(**out) for out in res.parse_json()])
+                return res.to_result_ok([Utxo(**out) for out in res.json_body().unwrap()])
             except Exception as e:
                 result = res.to_result_err(e)
         return result
 
     async def get_mempool(self) -> Result[Mempool]:
+        """Fetch current mempool summary statistics."""
         result: Result[Mempool] = Result.err("not started yet")
         for _ in range(self.attempts):
             res = await self._request("/mempool")
             try:
-                return res.to_result_ok(Mempool(**res.parse_json()))
+                return res.to_result_ok(Mempool(**res.json_body().unwrap()))
             except Exception as e:
                 result = res.to_result_err(e)
         return result
 
     async def _request(self, url: str) -> HttpResponse:
+        """Send an HTTP GET request to the Blockstream API."""
         return await http_request(f"{self.base_url}{url}", timeout=self.timeout, proxy=random_proxy(self.proxies))

mm_btc/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for mm-btc."""

mm_btc/cli/cli.py

@@ -1,10 +1,12 @@
+"""CLI entry point for mm-btc commands."""
+
 import asyncio
 import importlib.metadata
 from pathlib import Path
 from typing import Annotated
 
-import mm_print
 import typer
+from mm_print import print_plain
 
 from mm_btc.wallet import AddressType
 
@@ -15,7 +17,7 @@ app = typer.Typer(no_args_is_help=True, pretty_exceptions_enable=False, add_comp
 
 @app.command("mnemonic")
 @app.command(name="m", hidden=True)
-def mnemonic_command(  # nosec B107:hardcoded_password_default
+def mnemonic_command(  # nosec B107:hardcoded_password_default — empty string is a safe default, actual passphrase is user-provided
     mnemonic: Annotated[str, typer.Option("--mnemonic", "-m", help="")] = "",
     passphrase: Annotated[str, typer.Option("--passphrase", "-p")] = "",
     path: Annotated[str, typer.Option("--path", help="Derivation path. Examples: bip44, bip88, m/44'/0'/0'/0")] = "bip44",
@@ -66,15 +68,16 @@ def utxo_command(address: str) -> None:
 
 
 def version_callback(value: bool) -> None:
+    """Print the version and exit when --version flag is passed."""
     if value:
-        mm_print.plain(f"mm-btc: v{importlib.metadata.version('mm-btc')}")
+        print_plain(f"mm-btc: v{importlib.metadata.version('mm-btc')}")
         raise typer.Exit
 
 
 @app.callback()
 def main(_version: bool = typer.Option(None, "--version", callback=version_callback, is_eager=True)) -> None:
-    pass
+    """mm-btc CLI application root callback."""
 
 
-if __name__ == "__main_":
+if __name__ == "__main__":
     app()

mm_btc/cli/cmd/__init__.py

@@ -0,0 +1 @@
+"""CLI command handlers for mm-btc."""

mm_btc/cli/cmd/address_cmd.py

@@ -1,10 +1,13 @@
-import mm_print
+"""CLI handler for the address command — fetches address info from Blockstream."""
+
+from mm_print import print_json
 
 from mm_btc.blockstream import BlockstreamClient
 from mm_btc.wallet import is_testnet_address
 
 
 async def run(address: str) -> None:
+    """Fetch and print address information from the Blockstream API."""
     client = BlockstreamClient(testnet=is_testnet_address(address))
     res = await client.get_address(address)
-    mm_print.json(res.value_or_error())
+    print_json(res.value_or_error())

mm_btc/cli/cmd/create_tx_cmd.py

@@ -1,14 +1,20 @@
+"""CLI handler for the create-tx command — builds a Bitcoin transaction from a TOML config."""
+
 from pathlib import Path
 
-import mm_print
 from bit import PrivateKey, PrivateKeyTestnet
+from mm_print import print_json
 from mm_web3 import Web3CliConfig
 
 from mm_btc.wallet import is_testnet_address
 
 
 class Config(Web3CliConfig):
+    """Transaction creation configuration loaded from a TOML file."""
+
     class Output(Web3CliConfig):
+        """Single transaction output with destination address and amount in satoshis."""
+
         address: str
         amount: int
 
@@ -18,6 +24,7 @@ class Config(Web3CliConfig):
 
 
 def run(config_path: Path) -> None:
+    """Build and print a signed Bitcoin transaction from the given config file."""
     config = Config.read_toml_config_or_exit(config_path)
     testnet = is_testnet_address(config.from_address)
     key = PrivateKeyTestnet(config.private) if testnet else PrivateKey(config.private)
@@ -25,4 +32,4 @@ def run(config_path: Path) -> None:
     outputs = [(o.address, o.amount, "satoshi") for o in config.outputs]
 
     tx = key.create_transaction(outputs)
-    mm_print.json(tx)
+    print_json(tx)

mm_btc/cli/cmd/decode_tx_cmd.py

@@ -1,8 +1,11 @@
-import mm_print
+"""CLI handler for the decode-tx command — decodes a raw transaction hex."""
+
+from mm_print import print_json
 
 from mm_btc.tx import decode_tx
 
 
 def run(tx_hex: str, testnet: bool = False) -> None:
+    """Decode and print a raw Bitcoin transaction."""
     res = decode_tx(tx_hex, testnet)
-    mm_print.json(res)
+    print_json(res)

mm_btc/cli/cmd/mnemonic_cmd.py

@@ -1,18 +1,24 @@
+"""CLI handler for the mnemonic command — generates and displays HD wallet keys."""
+
 from dataclasses import dataclass
-from enum import Enum
+from enum import StrEnum
 
-import mm_print
+from mm_print import print_plain
 
 from mm_btc.wallet import AddressType, derive_accounts, generate_mnemonic
 
 
-class PrivateType(str, Enum):
+class PrivateType(StrEnum):
+    """Output format for private keys."""
+
     hex = "hex"
     wif = "wif"
 
 
 @dataclass
 class Args:
+    """Arguments for the mnemonic command."""
+
     mnemonic: str
     passphrase: str
     words: int
@@ -24,20 +30,22 @@ class Args:
 
 
 def run(args: Args) -> None:
+    """Execute the mnemonic command: generate or use a mnemonic and print derived accounts."""
     mnemonic = args.mnemonic or generate_mnemonic()
     passphrase = args.passphrase
     path = get_derivation_path_prefix(args.path, args.testnet)
     accounts = derive_accounts(mnemonic, passphrase, path, args.address_type, args.limit)
 
-    mm_print.plain(f"{mnemonic}")
+    print_plain(f"{mnemonic}")
     if passphrase:
-        mm_print.plain(f"{passphrase}")
+        print_plain(f"{passphrase}")
     for acc in accounts:
         private = acc.private if args.hex else acc.wif
-        mm_print.plain(f"{acc.path} {acc.address} {private}")
+        print_plain(f"{acc.path} {acc.address} {private}")
 
 
 def get_derivation_path_prefix(path: str, testnet: bool) -> str:
+    """Resolve a path alias (bip44, bip84) or custom path to a full derivation path prefix."""
     if path.startswith("m/"):
         return path
     coin = "1" if testnet else "0"

mm_btc/cli/cmd/utxo_cmd.py

@@ -1,10 +1,13 @@
-import mm_print
+"""CLI handler for the utxo command — fetches UTXOs from Blockstream."""
+
+from mm_print import print_json
 
 from mm_btc.blockstream import BlockstreamClient
 from mm_btc.wallet import is_testnet_address
 
 
 async def run(address: str) -> None:
+    """Fetch and print UTXOs for an address from the Blockstream API."""
     client = BlockstreamClient(testnet=is_testnet_address(address))
     res = await client.get_utxo(address)
-    mm_print.json(res.value_or_error())
+    print_json(res.value_or_error())

mm_btc/tx.py

@@ -1,5 +1,8 @@
+"""Bitcoin transaction decoding utilities."""
+
 from bitcoinlib.transactions import Transaction
 
 
 def decode_tx(tx_hex: str, testnet: bool = False) -> dict[str, object]:
-    return Transaction.parse(tx_hex, network="testnet" if testnet else "mainnet").as_dict()  # type: ignore[no-any-return]
+    """Decode a raw Bitcoin transaction hex string into a dictionary."""
+    return Transaction.parse(tx_hex, network="testnet" if testnet else "mainnet").as_dict()  # type: ignore[no-any-return]  # ty: ignore[unused-ignore-comment]  # bitcoinlib has no type stubs, as_dict() returns Any

mm_btc/wallet.py

@@ -1,5 +1,7 @@
+"""Bitcoin wallet operations: mnemonic generation, HD key derivation, and address utilities."""
+
 from dataclasses import dataclass
-from enum import Enum, unique
+from enum import StrEnum, unique
 
 from hdwallet import HDWallet
 from hdwallet.cryptocurrencies import Bitcoin
@@ -8,6 +10,7 @@ from hdwallet.hds import BIP32HD
 from hdwallet.mnemonics import BIP39Mnemonic
 from mnemonic import Mnemonic
 
+# BIP44/BIP84 standard derivation path prefixes for mainnet and testnet.
 BIP44_MAINNET_PATH = "m/44'/0'/0'/0"
 BIP44_TESTNET_PATH = "m/44'/1'/0'/0"
 BIP84_MAINNET_PATH = "m/84'/0'/0'/0"
@@ -16,6 +19,8 @@ BIP84_TESTNET_PATH = "m/84'/1'/0'/0"
 
 @dataclass
 class Account:
+    """Derived Bitcoin account with address, private key, WIF, and derivation path."""
+
     address: str
     private: str
     wif: str
@@ -23,7 +28,9 @@ class Account:
 
 
 @unique
-class AddressType(str, Enum):
+class AddressType(StrEnum):
+    """Supported Bitcoin address types."""
+
     P2PKH = "P2PKH"  # Pay to Public Key Hash
     P2SH = "P2SH"  # Pay to Script Hash
     P2TR = "P2TR"  # Taproot
@@ -34,10 +41,12 @@ class AddressType(str, Enum):
 
 
 def generate_mnemonic(language: str = "english", words: int = 12) -> str:
-    return Mnemonic(language).generate(strength=mnemonic_words_to_strenght(words))
+    """Generate a BIP39 mnemonic phrase."""
+    return Mnemonic(language).generate(strength=mnemonic_words_to_strength(words))
 
 
 def derive_accounts(mnemonic: str, passphrase: str, path_prefix: str, address_type: AddressType, limit: int) -> list[Account]:
+    """Derive multiple Bitcoin accounts from a mnemonic using HD wallet derivation."""
     coin = Bitcoin
     if path_prefix.startswith(("m/84'/1'", "m/44'/1'")):
         network = coin.NETWORKS.TESTNET
@@ -56,13 +65,19 @@ def derive_accounts(mnemonic: str, passphrase: str, path_prefix: str, address_ty
         wallet.clean_derivation()
         path = f"{path_prefix}/{index_path}"
         w = wallet.from_derivation(derivation=CustomDerivation(path=path))
-        accounts.append(Account(address=w.address(address_type), private=w.private_key(), wif=w.wif(), path=path))
+        address = w.address(address_type)
+        private = w.private_key()
+        wif = w.wif()
+        if address is None or private is None or wif is None:
+            raise ValueError(f"Failed to derive wallet data for path: {path}")
+        accounts.append(Account(address=address, private=private, wif=wif, path=path))
         w.clean_derivation()
 
     return accounts
 
 
-def mnemonic_words_to_strenght(words: int) -> int:
+def mnemonic_words_to_strength(words: int) -> int:
+    """Convert mnemonic word count to BIP39 entropy strength in bits."""
     if words == 12:
         return 128
     if words == 15:
@@ -78,4 +93,5 @@ def mnemonic_words_to_strenght(words: int) -> int:
 
 
 def is_testnet_address(address: str) -> bool:
+    """Check if a Bitcoin address belongs to testnet based on its prefix."""
     return address.startswith(("m", "n", "tb1"))

mm_btc-0.6.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: mm-btc
+Version: 0.6.0
+Requires-Python: >=3.14
+Requires-Dist: bitcoinlib~=0.7.6
+Requires-Dist: bit~=0.8.0
+Requires-Dist: hdwallet~=3.6.1
+Requires-Dist: mm-web3~=0.6.2
+Requires-Dist: mnemonic~=0.21
+Requires-Dist: typer~=0.21.1

mm_btc-0.6.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+mm_btc/__init__.py,sha256=nJvUJnW252HgBF__F_DgOYDNI-tUgAiZR149DNlpzWg,69
+mm_btc/blockstream.py,sha256=WE6XAvq25quUZ-EZJsTyA0Fc6jYkLtSJTY2gaF4MsaA,4247
+mm_btc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mm_btc/tx.py,sha256=v90gGuJoss6Vdu40qLkbkouYfeEVgL-Gg8Ko-KBB94g,457
+mm_btc/wallet.py,sha256=YfF9URrLg2f7zTRX7yOV8gX00un7VRLFMmDWeYmFDWY,3128
+mm_btc/cli/__init__.py,sha256=QCh2qW3rj_5Ndi7lOxM47D7ILS8k6V0I01s-4cJscik,30
+mm_btc/cli/cli.py,sha256=PDDijm0BFRYs4JeZA_bzhaPHQqnfoqsoTWfKCgPLucI,2863
+mm_btc/cli/cmd/__init__.py,sha256=TzLfqMlXwZLIivl7NZ4r26uYe3NCfRxhgc0Ml9hWgJ0,39
+mm_btc/cli/cmd/address_cmd.py,sha256=BTdZ0LpqHjHrW4Ot3HtU6aScZdzRsxGcW2XVclJr91s,473
+mm_btc/cli/cmd/create_tx_cmd.py,sha256=WMdxw-YBDkXdzLQGE47Wwhk4Wh_hyhwFRzNoAxOwS2Q,1069
+mm_btc/cli/cmd/decode_tx_cmd.py,sha256=2Lwnh2XzfsJSYMSAVyHMo9-s3p6d2IIUzbW1lJFvCGY,311
+mm_btc/cli/cmd/mnemonic_cmd.py,sha256=dQftPqCvoWbiX7F2CROiOcHE0W69NHGvEhjev07KZE4,1624
+mm_btc/cli/cmd/utxo_cmd.py,sha256=5qPejTeoXRPXw6MjApqHwj5GG6TJUf6XZuqPbwPg5To,461
+mm_btc-0.6.0.dist-info/METADATA,sha256=cR3vKfFP1IGd4oW5e21LwnqktcYWxYWxiNvaOLdjWMI,253
+mm_btc-0.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mm_btc-0.6.0.dist-info/entry_points.txt,sha256=KphzLNE9eb9H1DO-L0gvBQaQT5ImedyVCN4a6svfiRg,46
+mm_btc-0.6.0.dist-info/RECORD,,

{mm_btc-0.5.5.dist-info → mm_btc-0.6.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

mm_btc-0.5.5.dist-info/METADATA

@@ -1,10 +0,0 @@
-Metadata-Version: 2.4
-Name: mm-btc
-Version: 0.5.5
-Requires-Python: >=3.13
-Requires-Dist: bitcoinlib~=0.7.5
-Requires-Dist: bit~=0.8.0
-Requires-Dist: hdwallet~=3.6.1
-Requires-Dist: mm-web3~=0.5.4
-Requires-Dist: mnemonic~=0.21
-Requires-Dist: typer~=0.20.0

mm_btc-0.5.5.dist-info/RECORD

@@ -1,17 +0,0 @@
-mm_btc/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mm_btc/blockstream.py,sha256=i1s1kyJ_sGQ5X_jypIQcVrJuIFtS6O4NwkLoJaMSZPg,3336
-mm_btc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mm_btc/tx.py,sha256=7KTMNuL1n8rRj_245BV1bH9M2_PctNvlvPsLEsRTYx4,245
-mm_btc/wallet.py,sha256=_pGTuAf6Y9KzaWTTSg_tn6WEoRsGqhxJuPof0_xyrmM,2333
-mm_btc/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mm_btc/cli/cli.py,sha256=vmrvmOxjyl6mSkz-OUOTn5pmJ_emRS_pCM1ZAaF6SsA,2626
-mm_btc/cli/cmd/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mm_btc/cli/cmd/address_cmd.py,sha256=8gzARLHv7wVg30SAgK9JDiZbJK0e0YFus4b2Y5NGey0,302
-mm_btc/cli/cmd/create_tx_cmd.py,sha256=VWTW7f8IRxisPWQAddw5fw9CRup2A6OWAJHKEpecLpc,714
-mm_btc/cli/cmd/decode_tx_cmd.py,sha256=oNOVX1_XIBdj0rY7ZMiwdNLVBvBHdnK0niJsXSulxXo,164
-mm_btc/cli/cmd/mnemonic_cmd.py,sha256=N3qaQfoivODj4EQIFn4fN0ULZon7rmoETqJPy3YnKbg,1248
-mm_btc/cli/cmd/utxo_cmd.py,sha256=6xGzi6RhXXUOgvNAFNWMWmO9AIDRWOVh_0X-jaCdeM4,299
-mm_btc-0.5.5.dist-info/METADATA,sha256=VdG3hHfAHyso9d2jUKCuaWeqZhcmgknSnA8dBCa-GA8,253
-mm_btc-0.5.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mm_btc-0.5.5.dist-info/entry_points.txt,sha256=KphzLNE9eb9H1DO-L0gvBQaQT5ImedyVCN4a6svfiRg,46
-mm_btc-0.5.5.dist-info/RECORD,,