btcaaron 0.2.2__tar.gz → 0.2.3__tar.gz

{btcaaron-0.2.2 → btcaaron-0.2.3}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: btcaaron
-Version: 0.2.2
-Summary: A Bitcoin Testnet transaction toolkit supporting Legacy, SegWit, and Taproot
-Home-page: https://x.com/aaron_recompile
+Version: 0.2.3
+Summary: Pragmatic Bitcoin Taproot toolkit: Legacy/SegWit/Taproot, PSBT, optional Signet workflows, and Bitcoin Inquisition opcode templates (OP_CAT, CSFS, CTV).
+Home-page: https://github.com/aaron-recompile/btcaaron
 Author: Aaron Zhang
 Author-email: aaron.recompile@gmail.com
-Keywords: bitcoin,taproot,tapscript,bip341,bip342,schnorr,p2tr,taptree,script-path,miniscript,psbt,regtest,testnet
+Project-URL: X (author), https://x.com/aaron_recompile
+Keywords: bitcoin,taproot,tapscript,bip341,bip342,schnorr,p2tr,taptree,script-path,miniscript,psbt,regtest,testnet,signet,bitcoin-inquisition,checksigfromstack,ctv
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -20,6 +21,8 @@ Requires-Python: >=3.10,<3.13
 Description-Content-Type: text/markdown
 Requires-Dist: requests<3.0.0,>=2.25.0
 Requires-Dist: bitcoin-utils<0.8.0,>=0.7.3
+Requires-Dist: bip32>=4.0.0
+Requires-Dist: base58>=2.1.1
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -27,6 +30,7 @@ Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
 Dynamic: keywords
+Dynamic: project-url
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -35,15 +39,17 @@ Dynamic: summary
 
 [![Supported by OpenSats](https://img.shields.io/badge/supported%20by-OpenSats-orange?style=flat-square&logo=bitcoin)](https://opensats.org)
 
-A pragmatic Bitcoin toolkit with a clear path toward full Taproot engineering.
+A pragmatic Bitcoin toolkit for Taproot engineering — Legacy, SegWit, and Taproot flows, PSBT, and optional **Signet** / **Bitcoin Inquisition** opcode templates (OP_CAT, CSFS, CTV).
 
-Designed for reproducible testnet experiments, educational workflows, and script-path development.
+Designed for reproducible testnet and signet experiments, educational workflows, and script-path development.
 
 If you find btcaaron useful, a GitHub star is appreciated.
 
+👉 Looking for Bitcoin Inquisition experimental opcode templates (OP_CAT / CSFS / CTV)? See **[INQUISITION.md](INQUISITION.md)**.
+
 ## Current Status
 
-**v0.2.2 (alpha preview)** — Core Taproot spend-path workflows are implemented and testnet/regtest-verified.  
+**v0.2.3 (alpha preview)** — Core Taproot spend-path workflows are implemented and testnet/regtest-verified.  
 Current focus is release hardening: broader validation coverage, documentation alignment, and contributor testing feedback.
 
 ## Features
@@ -58,7 +64,7 @@ Production-tested on testnet with real transactions:
 - Broadcast to Blockstream / Mempool endpoints
 - Developer helpers (`WIFKey`, `quick_transfer`)
 
-### Available Now (v0.2.2 - Alpha Preview)
+### Available Now (v0.2.3 - Alpha Preview)
 
 Testnet-verified with real transactions (23 tests, all passing):
 
@@ -118,25 +124,7 @@ python -m pip install -e .
 btcaaron-doctor
 ```
 
-## Quick Start
-
-```python
-from btcaaron import WIFKey, quick_transfer
-
-wif = "your_testnet_wif"
-
-key = WIFKey(wif)
-print("Taproot:", key.get_taproot().address)
-
-balance = key.get_taproot().get_balance()
-print("Balance:", balance, "sats")
-
-if balance > 1000:
-    txid = quick_transfer(wif, "taproot", "tb1q...", amount=500, fee=300)
-    print("Broadcasted:", txid)
-```
-
-## v0.2.2 API Example
+## Quick Start (v0.2.3)
 
 *Taproot-native API — core features available now.*
 
@@ -168,6 +156,51 @@ tx = (program.spend("hash")
 tx.broadcast()
 ```
 
+## Legacy Quick Start (v0.1.x)
+
+For backward compatibility with the v0.1.x API:
+
+```python
+from btcaaron import WIFKey, quick_transfer
+
+wif = "your_testnet_wif"
+
+key = WIFKey(wif)
+print("Taproot:", key.get_taproot().address)
+
+balance = key.get_taproot().get_balance()
+print("Balance:", balance, "sats")
+
+if balance > 1000:
+    txid = quick_transfer(wif, "taproot", "tb1q...", amount=500, fee=300)
+    print("Broadcasted:", txid)
+```
+
+## Descriptor Wallet Quick Start (tprv/xpriv)
+
+For descriptor-style HD wallet flows (RGB-friendly), derive directly from `tprv`:
+
+```python
+from btcaaron import taproot_balance_from_tprv, quick_transfer_tprv, taproot_descriptor_from_tprv
+
+tprv = "tprv8ZgxMBicQKs..."
+print(taproot_descriptor_from_tprv(tprv, branch=0))  # tr(tprv.../86h/1h/0h/0/*)
+
+balance = taproot_balance_from_tprv(tprv, branch=0, index=0)
+print("Balance:", balance, "sats")
+
+txid = quick_transfer_tprv(
+    tprv,
+    "tb1p...",
+    amount=10_000,
+    fee=800,
+    branch=0,
+    index=0,
+    debug=True,
+)
+print("Broadcasted:", txid)
+```
+
 Full specification in [DESIGN.md](./DESIGN.md).
 
 ## Testing
@@ -181,7 +214,7 @@ python -m pytest tests/
 Run specific test suites:
 
 ```bash
-# v0.2.2 comprehensive tests (pytest)
+# v0.2.3 comprehensive tests (pytest)
 python -m pytest tests/test_btcaaron_v02.py -v
 
 # v0.1.x example-based tests
@@ -227,7 +260,7 @@ See [DESIGN.md](./DESIGN.md) for architecture details and development roadmap.
   - default call blocks mainnet broadcast unless `allow_mainnet=True`
   - `dry_run=True` is available for no-side-effect routing checks
   - recommended smoke script: `python3 examples/core_test/scenarios/mainnet_readiness_smoke.py`
-- **v0.2.2 Status**: Core Taproot spend-path flows are implemented and testnet-verified; ongoing work focuses on hardening, PSBT, and documentation.
+- **v0.2.3 Status**: Core Taproot spend-path flows are implemented and testnet-verified; ongoing work focuses on hardening, PSBT, and documentation.
 
 ## Acknowledgments
 

{btcaaron-0.2.2 → btcaaron-0.2.3}/README.md

@@ -2,15 +2,17 @@
 
 [![Supported by OpenSats](https://img.shields.io/badge/supported%20by-OpenSats-orange?style=flat-square&logo=bitcoin)](https://opensats.org)
 
-A pragmatic Bitcoin toolkit with a clear path toward full Taproot engineering.
+A pragmatic Bitcoin toolkit for Taproot engineering — Legacy, SegWit, and Taproot flows, PSBT, and optional **Signet** / **Bitcoin Inquisition** opcode templates (OP_CAT, CSFS, CTV).
 
-Designed for reproducible testnet experiments, educational workflows, and script-path development.
+Designed for reproducible testnet and signet experiments, educational workflows, and script-path development.
 
 If you find btcaaron useful, a GitHub star is appreciated.
 
+👉 Looking for Bitcoin Inquisition experimental opcode templates (OP_CAT / CSFS / CTV)? See **[INQUISITION.md](INQUISITION.md)**.
+
 ## Current Status
 
-**v0.2.2 (alpha preview)** — Core Taproot spend-path workflows are implemented and testnet/regtest-verified.  
+**v0.2.3 (alpha preview)** — Core Taproot spend-path workflows are implemented and testnet/regtest-verified.  
 Current focus is release hardening: broader validation coverage, documentation alignment, and contributor testing feedback.
 
 ## Features
@@ -25,7 +27,7 @@ Production-tested on testnet with real transactions:
 - Broadcast to Blockstream / Mempool endpoints
 - Developer helpers (`WIFKey`, `quick_transfer`)
 
-### Available Now (v0.2.2 - Alpha Preview)
+### Available Now (v0.2.3 - Alpha Preview)
 
 Testnet-verified with real transactions (23 tests, all passing):
 
@@ -85,25 +87,7 @@ python -m pip install -e .
 btcaaron-doctor
 ```
 
-## Quick Start
-
-```python
-from btcaaron import WIFKey, quick_transfer
-
-wif = "your_testnet_wif"
-
-key = WIFKey(wif)
-print("Taproot:", key.get_taproot().address)
-
-balance = key.get_taproot().get_balance()
-print("Balance:", balance, "sats")
-
-if balance > 1000:
-    txid = quick_transfer(wif, "taproot", "tb1q...", amount=500, fee=300)
-    print("Broadcasted:", txid)
-```
-
-## v0.2.2 API Example
+## Quick Start (v0.2.3)
 
 *Taproot-native API — core features available now.*
 
@@ -135,6 +119,51 @@ tx = (program.spend("hash")
 tx.broadcast()
 ```
 
+## Legacy Quick Start (v0.1.x)
+
+For backward compatibility with the v0.1.x API:
+
+```python
+from btcaaron import WIFKey, quick_transfer
+
+wif = "your_testnet_wif"
+
+key = WIFKey(wif)
+print("Taproot:", key.get_taproot().address)
+
+balance = key.get_taproot().get_balance()
+print("Balance:", balance, "sats")
+
+if balance > 1000:
+    txid = quick_transfer(wif, "taproot", "tb1q...", amount=500, fee=300)
+    print("Broadcasted:", txid)
+```
+
+## Descriptor Wallet Quick Start (tprv/xpriv)
+
+For descriptor-style HD wallet flows (RGB-friendly), derive directly from `tprv`:
+
+```python
+from btcaaron import taproot_balance_from_tprv, quick_transfer_tprv, taproot_descriptor_from_tprv
+
+tprv = "tprv8ZgxMBicQKs..."
+print(taproot_descriptor_from_tprv(tprv, branch=0))  # tr(tprv.../86h/1h/0h/0/*)
+
+balance = taproot_balance_from_tprv(tprv, branch=0, index=0)
+print("Balance:", balance, "sats")
+
+txid = quick_transfer_tprv(
+    tprv,
+    "tb1p...",
+    amount=10_000,
+    fee=800,
+    branch=0,
+    index=0,
+    debug=True,
+)
+print("Broadcasted:", txid)
+```
+
 Full specification in [DESIGN.md](./DESIGN.md).
 
 ## Testing
@@ -148,7 +177,7 @@ python -m pytest tests/
 Run specific test suites:
 
 ```bash
-# v0.2.2 comprehensive tests (pytest)
+# v0.2.3 comprehensive tests (pytest)
 python -m pytest tests/test_btcaaron_v02.py -v
 
 # v0.1.x example-based tests
@@ -194,7 +223,7 @@ See [DESIGN.md](./DESIGN.md) for architecture details and development roadmap.
   - default call blocks mainnet broadcast unless `allow_mainnet=True`
   - `dry_run=True` is available for no-side-effect routing checks
   - recommended smoke script: `python3 examples/core_test/scenarios/mainnet_readiness_smoke.py`
-- **v0.2.2 Status**: Core Taproot spend-path flows are implemented and testnet-verified; ongoing work focuses on hardening, PSBT, and documentation.
+- **v0.2.3 Status**: Core Taproot spend-path flows are implemented and testnet-verified; ongoing work focuses on hardening, PSBT, and documentation.
 
 ## Acknowledgments
 

{btcaaron-0.2.2 → btcaaron-0.2.3}/btcaaron/__init__.py

@@ -8,7 +8,7 @@ v0.2.x API (new):
     from btcaaron import Key, TapTree
 """
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 # ══════════════════════════════════════════════════════════════════
 # Legacy API (v0.1.x) - backward compatible
@@ -19,16 +19,35 @@ from .legacy import (
     BTCTransaction,
     wif_to_addresses, 
     quick_transfer,
+    quick_transfer_tprv,
+    taproot_balance_from_tprv,
     fund_program,
 )
 
 # ══════════════════════════════════════════════════════════════════
 # New API (v0.2.x)
 # ══════════════════════════════════════════════════════════════════
-from .key import Key
+from .key import Key, derive_wif_from_tprv, taproot_descriptor_from_tprv, wif_secret_bytes
 from .tree import TapTree, TaprootProgram, LeafDescriptor
 from .spend import SpendBuilder, Transaction
-from .script import Script, RawScript
+from .script import (
+    Script,
+    RawScript,
+    ord_inscription_script,
+    brc20_mint_json,
+    inq_cat_hashlock_script,
+    inq_csfs_script,
+    inq_ctv_script,
+    inq_ctv_template_hash_for_output,
+    inq_ctv_program_for_output,
+)
+from .node_rpc import (
+    broadcast_tx_hex,
+    find_utxo_for_address,
+    sats_from_rpc_amount,
+    wallet_change_address,
+    wallet_send_sats,
+)
 from .psbt import Psbt, PsbtInput, PsbtV2, PsbtV2Input
 from .errors import (
     BtcAaronError,
@@ -47,10 +66,15 @@ __all__ = [
     "BTCTransaction",
     "wif_to_addresses", 
     "quick_transfer",
+    "quick_transfer_tprv",
+    "taproot_balance_from_tprv",
     "fund_program",
     
     # New API
     "Key",
+    "derive_wif_from_tprv",
+    "taproot_descriptor_from_tprv",
+    "wif_secret_bytes",
     "TapTree",
     "TaprootProgram",
     "LeafDescriptor",
@@ -58,6 +82,18 @@ __all__ = [
     "Transaction",
     "Script",
     "RawScript",
+    "ord_inscription_script",
+    "brc20_mint_json",
+    "inq_cat_hashlock_script",
+    "inq_csfs_script",
+    "inq_ctv_script",
+    "inq_ctv_template_hash_for_output",
+    "inq_ctv_program_for_output",
+    "broadcast_tx_hex",
+    "find_utxo_for_address",
+    "sats_from_rpc_amount",
+    "wallet_change_address",
+    "wallet_send_sats",
     "Psbt",
     "PsbtInput",
     "PsbtV2",

btcaaron-0.2.3/btcaaron/key.py

@@ -0,0 +1,296 @@
+"""
+btcaaron.key - Key Management
+
+The Key class provides a clean interface for Bitcoin key operations.
+"""
+
+import hashlib
+from typing import Optional
+from bitcoinutils.setup import setup
+from bitcoinutils.keys import PrivateKey
+
+
+def _normalize_network(network: str) -> str:
+    """
+    Normalize app-level network labels to bitcoinutils setup labels.
+
+    bitcoinutils distinguishes mainnet/testnet/regtest. For signet-family
+    networks we use testnet address/version rules.
+    """
+    n = (network or "testnet").lower()
+    if n == "mainnet":
+        return "mainnet"
+    if n == "regtest":
+        return "regtest"
+    return "testnet"
+
+
+def set_network(network: str) -> str:
+    """
+    Set bitcoinutils global network context and return normalized value.
+    """
+    normalized = _normalize_network(network)
+    setup(normalized)
+    return normalized
+
+
+def _default_coin_type(network: str) -> int:
+    """
+    Default BIP44/86 coin type by network.
+
+    mainnet -> 0, testnet/regtest/signet-family -> 1
+    """
+    return 0 if _normalize_network(network) == "mainnet" else 1
+
+
+def wif_secret_bytes(wif: str) -> bytes:
+    """
+    Decode WIF and return 32-byte raw private key bytes.
+
+    Supports both compressed and uncompressed WIF.
+    """
+    try:
+        import base58
+    except ImportError as exc:
+        raise ValueError("Missing dep: pip install base58") from exc
+
+    try:
+        decoded = base58.b58decode(wif)
+    except Exception as exc:
+        raise ValueError(f"Invalid WIF encoding: {exc}") from exc
+
+    if len(decoded) not in (37, 38):
+        raise ValueError("Invalid WIF length")
+
+    payload, checksum = decoded[:-4], decoded[-4:]
+    expected = hashlib.sha256(hashlib.sha256(payload).digest()).digest()[:4]
+    if checksum != expected:
+        raise ValueError("Invalid WIF checksum")
+
+    prefix = payload[0]
+    if prefix not in (0x80, 0xEF):
+        raise ValueError("Invalid WIF network/version byte")
+
+    if len(payload) == 34:
+        # Compressed key marker must be present.
+        if payload[-1] != 0x01:
+            raise ValueError("Invalid compressed WIF marker")
+        secret = payload[1:-1]
+    else:
+        secret = payload[1:]
+
+    if len(secret) != 32:
+        raise ValueError("Invalid private key length in WIF")
+    return secret
+
+
+def derive_wif_from_tprv(
+    tprv: str,
+    *,
+    branch: int = 0,
+    index: int = 0,
+    purpose: int = 86,
+    coin_type: Optional[int] = None,
+    account: int = 0,
+    network: str = "testnet",
+) -> str:
+    """
+    Derive a compressed child WIF from an account-level xpriv/tprv.
+
+    Default path follows BIP86:
+      m / 86' / coin_type' / account' / branch / index
+    """
+    try:
+        from bip32 import BIP32, HARDENED_INDEX
+        import base58
+    except ImportError as exc:
+        raise ValueError("Missing deps: pip install bip32 base58") from exc
+
+    if min(branch, index, purpose, account) < 0:
+        raise ValueError("branch/index/purpose/account must be non-negative")
+
+    ct = _default_coin_type(network) if coin_type is None else coin_type
+    if ct < 0:
+        raise ValueError("coin_type must be non-negative")
+
+    path = [
+        purpose | HARDENED_INDEX,
+        ct | HARDENED_INDEX,
+        account | HARDENED_INDEX,
+        branch,
+        index,
+    ]
+    try:
+        bip32_obj = BIP32.from_xpriv(tprv)
+        private_key = bip32_obj.get_privkey_from_path(path)
+    except Exception as exc:
+        raise ValueError(f"Invalid tprv/xpriv or derivation path: {exc}") from exc
+
+    prefix = b"\x80" if _normalize_network(network) == "mainnet" else b"\xEF"
+    payload = prefix + private_key + b"\x01"
+    checksum = hashlib.sha256(hashlib.sha256(payload).digest()).digest()[:4]
+    return base58.b58encode(payload + checksum).decode()
+
+
+def taproot_descriptor_from_tprv(
+    tprv: str,
+    *,
+    branch: int = 0,
+    purpose: int = 86,
+    coin_type: Optional[int] = None,
+    account: int = 0,
+    network: str = "testnet",
+    wildcard: bool = True,
+    index: int = 0,
+) -> str:
+    """
+    Build a BIP86-style taproot descriptor string from xpriv/tprv.
+
+    Example:
+      tr(tprv.../86h/1h/0h/0/*)
+    """
+    ct = _default_coin_type(network) if coin_type is None else coin_type
+    suffix = "*" if wildcard else str(index)
+    return f"tr({tprv}/{purpose}h/{ct}h/{account}h/{branch}/{suffix})"
+
+
+# Default module context remains testnet-first.
+set_network("testnet")
+
+
+class Key:
+    """
+    Bitcoin Key Manager (Immutable)
+    
+    Handles private key operations, signing, and public key derivation.
+    
+    Example:
+        alice = Key.from_wif("cRxebG1hY6vVgS9CSLNaEbEJaXkpZvc6nFeqqGT7v6gcW7MbzKNT")
+        print(alice.xonly)  # x-only pubkey for Taproot
+    """
+    
+    def __init__(self, private_key: PrivateKey):
+        """Internal constructor. Use from_wif() or generate() instead."""
+        self._private_key = private_key
+        self._public_key = private_key.get_public_key()
+    
+    @classmethod
+    def from_wif(cls, wif: str) -> "Key":
+        """
+        Create Key from WIF (Wallet Import Format) string.
+        
+        Args:
+            wif: WIF-encoded private key
+            
+        Returns:
+            Key instance
+            
+        Raises:
+            ValueError: If WIF format is invalid
+        """
+        try:
+            private_key = PrivateKey(wif)
+            return cls(private_key)
+        except Exception as e:
+            raise ValueError(f"Invalid WIF private key: {e}")
+    
+    @classmethod
+    def from_hex(cls, hex_privkey: str) -> "Key":
+        """
+        Create Key from hex-encoded private key.
+        
+        Args:
+            hex_privkey: 32-byte hex string
+            
+        Returns:
+            Key instance
+        """
+        try:
+            private_key = PrivateKey(secret_exponent=int(hex_privkey, 16))
+            return cls(private_key)
+        except Exception as e:
+            raise ValueError(f"Invalid hex private key: {e}")
+
+    @classmethod
+    def from_tprv(
+        cls,
+        tprv: str,
+        *,
+        branch: int = 0,
+        index: int = 0,
+        purpose: int = 86,
+        coin_type: Optional[int] = None,
+        account: int = 0,
+        network: str = "testnet",
+    ) -> "Key":
+        """
+        Create Key by deriving child private key from xpriv/tprv.
+
+        Default derivation path:
+          m/86'/coin_type'/account'/branch/index
+        """
+        set_network(network)
+        wif = derive_wif_from_tprv(
+            tprv,
+            branch=branch,
+            index=index,
+            purpose=purpose,
+            coin_type=coin_type,
+            account=account,
+            network=network,
+        )
+        return cls.from_wif(wif)
+    
+    @classmethod
+    def generate(cls, network: str = "testnet") -> "Key":
+        """
+        Generate a new random key.
+        
+        Uses the underlying bitcoin-utils PrivateKey() which generates
+        a cryptographically secure random private key via os.urandom().
+        
+        Args:
+            network: "testnet" | "mainnet" (default: testnet)
+            
+        Returns:
+            Key instance
+        """
+        set_network(network)
+        private_key = PrivateKey()
+        return cls(private_key)
+    
+    @property
+    def wif(self) -> str:
+        """WIF-encoded private key"""
+        return self._private_key.to_wif()
+    
+    @property
+    def pubkey(self) -> str:
+        """33-byte compressed public key (hex)"""
+        return self._public_key.to_hex()
+    
+    @property
+    def xonly(self) -> str:
+        """32-byte x-only public key for Taproot (hex)"""
+        return self._public_key.to_x_only_hex()
+    
+    @property
+    def _internal(self) -> PrivateKey:
+        """Access to underlying bitcoinutils PrivateKey (internal use)"""
+        return self._private_key
+    
+    @property
+    def _internal_pub(self):
+        """Access to underlying bitcoinutils PublicKey (internal use)"""
+        return self._public_key
+    
+    def __repr__(self) -> str:
+        return f"Key(xonly={self.xonly[:16]}...)"
+    
+    def __eq__(self, other) -> bool:
+        if not isinstance(other, Key):
+            return False
+        return self.xonly == other.xonly
+    
+    def __hash__(self) -> int:
+        return hash(self.xonly)