mm-btc 0.5.6__tar.gz → 0.6.0__tar.gz

mm_btc-0.6.0/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run ty check:*)",
+      "Bash(just lint:*)",
+      "Bash(uv run ty:*)",
+      "Bash(just test:*)"
+    ]
+  }
+}

mm_btc-0.6.0/CLAUDE.md

@@ -0,0 +1,24 @@
+# AI Agent Start Guide
+
+## Critical: Language
+RESPOND IN ENGLISH. Always. No exceptions.
+User's language does NOT determine your response language.
+Only switch if user EXPLICITLY requests it (e.g., "respond in {language}").
+Language switching applies ONLY to chat. All code, comments, commit messages, and files must ALWAYS be in English — no exceptions.
+
+## Mandatory Rules (external)
+These files are REQUIRED. Read them fully and follow all rules.
+- `~/.claude/shared-rules/general.md`
+- `~/.claude/shared-rules/python.md`
+
+## Project Reading (context)
+These files are REQUIRED for project understanding.
+- `README.md`
+
+## Preflight (mandatory)
+Before your first response:
+1. Read all files listed above.
+2. Do not answer until all are read.
+3. In your first reply, list every file you have read from this document.
+
+Failure to follow this protocol is considered an error.

{mm_btc-0.5.6 → mm_btc-0.6.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: mm-btc
-Version: 0.5.6
-Requires-Python: >=3.13
+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.5.6
+Requires-Dist: mm-web3~=0.6.2
 Requires-Dist: mnemonic~=0.21
 Requires-Dist: typer~=0.21.1

{mm_btc-0.5.6 → mm_btc-0.6.0}/justfile

@@ -18,6 +18,7 @@ test:
 lint: format
     uv run ruff check src tests
     uv run mypy src
+    uv run ty check
 
 audit:
     uv export --no-dev --all-extras --format requirements-txt --no-emit-project > requirements.txt

{mm_btc-0.5.6 → mm_btc-0.6.0}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "mm-btc"
-version = "0.5.6"
+version = "0.6.0"
 description = ""
-requires-python = ">=3.13"
+requires-python = ">=3.14"
 dependencies = [
-    "mm-web3~=0.5.6",
+    "mm-web3~=0.6.2",
     "hdwallet~=3.6.1",
     "bit~=0.8.0",
     "bitcoinlib~=0.7.6",
@@ -21,19 +21,20 @@ build-backend = "hatchling.build"
 
 [dependency-groups]
 dev = [
-    "bandit~=1.9.2",
+    "bandit~=1.9.3",
     "mypy~=1.19.1",
     "pip-audit~=2.10.0",
     "pytest~=9.0.2",
     "pytest-asyncio~=1.3.0",
     "pytest-xdist~=3.8.0",
-    "ruff~=0.14.11",
+    "ruff~=0.15.0",
     "python-dotenv~=1.2.0",
+    "ty~=0.0.14",
 ]
 
 
 [tool.mypy]
-python_version = "3.13"
+python_version = "3.14"
 warn_no_return = false
 strict = true
 exclude = ["^tests/", "^tmp/"]
@@ -48,7 +49,7 @@ ignore_missing_imports = true
 
 [tool.ruff]
 line-length = 130
-target-version = "py313"
+target-version = "py314"
 [tool.ruff.lint]
 select = ["ALL"]
 ignore = [

mm_btc-0.6.0/src/mm_btc/__init__.py

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

{mm_btc-0.5.6 → mm_btc-0.6.0}/src/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-0.6.0/src/mm_btc/cli/__init__.py

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

{mm_btc-0.5.6 → mm_btc-0.6.0}/src/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-0.6.0/src/mm_btc/cli/cmd/__init__.py

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

{mm_btc-0.5.6 → mm_btc-0.6.0}/src/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-0.5.6 → mm_btc-0.6.0}/src/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-0.6.0/src/mm_btc/cli/cmd/decode_tx_cmd.py

@@ -0,0 +1,11 @@
+"""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)
+    print_json(res)

{mm_btc-0.5.6 → mm_btc-0.6.0}/src/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-0.5.6 → mm_btc-0.6.0}/src/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-0.6.0/src/mm_btc/tx.py

@@ -0,0 +1,8 @@
+"""Bitcoin transaction decoding utilities."""
+
+from bitcoinlib.transactions import Transaction
+
+
+def decode_tx(tx_hex: str, testnet: bool = False) -> dict[str, object]:
+    """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-0.5.6 → mm_btc-0.6.0}/src/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"))