btcaaron 0.2.0__tar.gz → 0.2.2__tar.gz

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

@@ -1,44 +1,50 @@
 Metadata-Version: 2.4
 Name: btcaaron
-Version: 0.2.0
+Version: 0.2.2
 Summary: A Bitcoin Testnet transaction toolkit supporting Legacy, SegWit, and Taproot
 Home-page: https://x.com/aaron_recompile
 Author: Aaron Zhang
 Author-email: aaron.recompile@gmail.com
+Keywords: bitcoin,taproot,tapscript,bip341,bip342,schnorr,p2tr,taptree,script-path,miniscript,psbt,regtest,testnet
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries
-Classifier: Topic :: Internet :: WWW/HTTP
-Requires-Python: >=3.7
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10,<3.13
 Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.25.0
-Requires-Dist: bitcoin-utils>=0.7.1
+Requires-Dist: requests<3.0.0,>=2.25.0
+Requires-Dist: bitcoin-utils<0.8.0,>=0.7.3
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: keywords
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
 # btcaaron<img src="images/mark.png" width="52" alt="btcaaron mark" style="margin-left:4px;vertical-align:middle" />
 
+[![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.
 
 Designed for reproducible testnet experiments, educational workflows, and script-path development.
 
-## Current Status
+If you find btcaaron useful, a GitHub star is appreciated.
 
-**v0.1.2** — Stable foundation release.  
-Core utilities actively used in my Taproot engineering work and on-chain experiments.
+## Current Status
 
-**v0.2.0** — Core Taproot spend-path prototype implemented and testnet-verified.  
-All 5 spend paths working with real transactions. Next: hardening, PSBT support, and comprehensive documentation. See [DESIGN.md](./DESIGN.md) for roadmap.
+**v0.2.2 (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
 
@@ -52,7 +58,7 @@ Production-tested on testnet with real transactions:
 - Broadcast to Blockstream / Mempool endpoints
 - Developer helpers (`WIFKey`, `quick_transfer`)
 
-### Available Now (v0.2.0 - Prototype)
+### Available Now (v0.2.2 - Alpha Preview)
 
 Testnet-verified with real transactions (23 tests, all passing):
 
@@ -64,19 +70,34 @@ Testnet-verified with real transactions (23 tests, all passing):
 
 ### Future (v0.3.x+)
 
-- PSBT v2 support (Taproot-aware)
+- PSBT v2 hardening and broader interoperability validation
 - Custom script templates
 - Multi-input/output transactions
 
+## Positioning (Quick Comparison)
+
+> High-level developer-experience comparison only (not a full feature matrix).
+
+| Library | Typical Use Case | Script-Path UX |
+|---|---|---|
+| `python-bitcoin-utils` | Low-level transaction/script construction and protocol experiments | Manual (build tree/witness/control-block flow yourself) |
+| `btcaaron` | Fast Taproot prototyping, teaching workflows, and reproducible test scaffolds | Declarative (e.g., `.hashlock()`, `.multisig()`, `.timelock()`) |
+| `BitcoinLib` | Wallet-oriented workflows, account management, and persistence layers | Mostly automated for common wallet flows |
+| `embit` | Descriptor/PSBT flows and hardware-wallet-oriented integrations | Descriptor-oriented, standard-policy paths |
+
+_Optional note_: `btcaaron` is designed as a pragmatic Taproot engineering layer on top of low-level primitives, prioritizing readability and reproducible testing workflows.
+
 ## Requirements
 
-- Python >= 3.7
-- Dependencies: `requests>=2.25.0`, `bitcoin-utils>=0.7.1`
+- Python `>=3.10,<3.13`
+- Dependencies:
+  - `requests>=2.25.0,<3.0.0`
+  - `bitcoin-utils>=0.7.3,<0.8.0`
 
 ## Installation
 
 ```bash
-pip install btcaaron
+python -m pip install btcaaron
 ```
 
 Or from source:
@@ -84,7 +105,17 @@ Or from source:
 ```bash
 git clone https://github.com/aaron-recompile/btcaaron.git
 cd btcaaron
-pip install .
+python -m pip install -e .
+```
+
+### IDE environment tip (important)
+
+Most IDE terminals run `python`/`python3` from the currently selected interpreter.
+Install and run with the same interpreter to avoid mismatched environments:
+
+```bash
+python -m pip install -e .
+btcaaron-doctor
 ```
 
 ## Quick Start
@@ -105,7 +136,7 @@ if balance > 1000:
     print("Broadcasted:", txid)
 ```
 
-## v0.2.0 API Example
+## v0.2.2 API Example
 
 *Taproot-native API — core features available now.*
 
@@ -124,6 +155,10 @@ program = (TapTree(internal_key=alice)
 
 print(program.address)  # tb1p...
 
+# Fund commit address without leaving IDE (auto UTXO selection)
+from btcaaron import fund_program
+# txid = fund_program(wif, program, 10_000)  # 打币到 program.address
+
 tx = (program.spend("hash")
     .from_utxo("abc123...", 0, sats=1200)
     .to("tb1p...", 666)
@@ -146,11 +181,26 @@ python -m pytest tests/
 Run specific test suites:
 
 ```bash
-# v0.2.0 comprehensive tests (pytest)
-python -m pytest tests/test_btcaaron_v0.2.py -v
+# v0.2.2 comprehensive tests (pytest)
+python -m pytest tests/test_btcaaron_v02.py -v
 
 # v0.1.x example-based tests
-python tests/test_btcaaron_v0.1.py
+python tests/test_btcaaron_v01.py
+```
+
+## Environment Doctor
+
+Use doctor before reporting install/runtime issues:
+
+```bash
+btcaaron-doctor
+```
+
+If doctor fails, re-install with the same interpreter:
+
+```bash
+python -m pip install -e .
+btcaaron-doctor
 ```
 
 ## Project Structure
@@ -171,8 +221,18 @@ See [DESIGN.md](./DESIGN.md) for architecture details and development roadmap.
 
 ## Notes
 
-- **Testnet Only**: This toolkit is designed for testnet use. Mainnet support may be added in future versions.
-- **v0.2.0 Status**: Core Taproot spend-path flows are implemented and testnet-verified; ongoing work focuses on hardening, PSBT, and documentation.
+- **Default safety posture**: testnet/regtest-first for everyday development and experiments.
+- **Mainnet (experimental)**: available behind explicit guardrails in `Transaction.broadcast(...)`.
+- **Mainnet guardrails**:
+  - 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.
+
+## Acknowledgments
+
+Development of btcaaron is supported by an [OpenSats](https://opensats.org) grant.  
+OpenSats supports open-source contributors working on Bitcoin and related freedom tech.
 
 ## Author
 

btcaaron-0.2.2/README.md

@@ -0,0 +1,212 @@
+# btcaaron<img src="images/mark.png" width="52" alt="btcaaron mark" style="margin-left:4px;vertical-align:middle" />
+
+[![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.
+
+Designed for reproducible testnet experiments, educational workflows, and script-path development.
+
+If you find btcaaron useful, a GitHub star is appreciated.
+
+## Current Status
+
+**v0.2.2 (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
+
+### Available Now (v0.1.x)
+
+Production-tested on testnet with real transactions:
+
+- Generate Legacy / SegWit / Taproot addresses from WIF
+- UTXO scanning and balance lookup via public APIs
+- Build and sign standard transactions
+- Broadcast to Blockstream / Mempool endpoints
+- Developer helpers (`WIFKey`, `quick_transfer`)
+
+### Available Now (v0.2.2 - Alpha Preview)
+
+Testnet-verified with real transactions (23 tests, all passing):
+
+- Declarative Taproot tree builder (`.hashlock()`, `.multisig()`, `.timelock()`, `.checksig()`)
+- Script-path and key-path spend constructors
+- Automatic witness construction and signature ordering
+- All 5 spend paths verified: hashlock, multisig, checksig, CSV timelock, keypath
+- Real transaction TXID reproduction tests
+
+### Future (v0.3.x+)
+
+- PSBT v2 hardening and broader interoperability validation
+- Custom script templates
+- Multi-input/output transactions
+
+## Positioning (Quick Comparison)
+
+> High-level developer-experience comparison only (not a full feature matrix).
+
+| Library | Typical Use Case | Script-Path UX |
+|---|---|---|
+| `python-bitcoin-utils` | Low-level transaction/script construction and protocol experiments | Manual (build tree/witness/control-block flow yourself) |
+| `btcaaron` | Fast Taproot prototyping, teaching workflows, and reproducible test scaffolds | Declarative (e.g., `.hashlock()`, `.multisig()`, `.timelock()`) |
+| `BitcoinLib` | Wallet-oriented workflows, account management, and persistence layers | Mostly automated for common wallet flows |
+| `embit` | Descriptor/PSBT flows and hardware-wallet-oriented integrations | Descriptor-oriented, standard-policy paths |
+
+_Optional note_: `btcaaron` is designed as a pragmatic Taproot engineering layer on top of low-level primitives, prioritizing readability and reproducible testing workflows.
+
+## Requirements
+
+- Python `>=3.10,<3.13`
+- Dependencies:
+  - `requests>=2.25.0,<3.0.0`
+  - `bitcoin-utils>=0.7.3,<0.8.0`
+
+## Installation
+
+```bash
+python -m pip install btcaaron
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/aaron-recompile/btcaaron.git
+cd btcaaron
+python -m pip install -e .
+```
+
+### IDE environment tip (important)
+
+Most IDE terminals run `python`/`python3` from the currently selected interpreter.
+Install and run with the same interpreter to avoid mismatched environments:
+
+```bash
+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
+
+*Taproot-native API — core features available now.*
+
+```python
+from btcaaron import Key, TapTree
+
+alice = Key.from_wif("cRxebG...")
+bob = Key.from_wif("cSNdLF...")
+
+program = (TapTree(internal_key=alice)
+    .hashlock("secret", label="hash")
+    .multisig(2, [alice, bob], label="2of2")
+    .timelock(blocks=144, then=bob, label="csv")
+    .checksig(bob, label="backup")
+).build()
+
+print(program.address)  # tb1p...
+
+# Fund commit address without leaving IDE (auto UTXO selection)
+from btcaaron import fund_program
+# txid = fund_program(wif, program, 10_000)  # 打币到 program.address
+
+tx = (program.spend("hash")
+    .from_utxo("abc123...", 0, sats=1200)
+    .to("tb1p...", 666)
+    .unlock(preimage="secret")
+    .build())
+
+tx.broadcast()
+```
+
+Full specification in [DESIGN.md](./DESIGN.md).
+
+## Testing
+
+Run the test suite:
+
+```bash
+python -m pytest tests/
+```
+
+Run specific test suites:
+
+```bash
+# v0.2.2 comprehensive tests (pytest)
+python -m pytest tests/test_btcaaron_v02.py -v
+
+# v0.1.x example-based tests
+python tests/test_btcaaron_v01.py
+```
+
+## Environment Doctor
+
+Use doctor before reporting install/runtime issues:
+
+```bash
+btcaaron-doctor
+```
+
+If doctor fails, re-install with the same interpreter:
+
+```bash
+python -m pip install -e .
+btcaaron-doctor
+```
+
+## Project Structure
+
+```
+btcaaron/
+├── btcaaron/         # Core library
+├── tests/            # Test suite
+├── DESIGN.md         # Architecture & roadmap
+├── README.md
+├── setup.py
+└── LICENSE
+```
+
+## Development
+
+See [DESIGN.md](./DESIGN.md) for architecture details and development roadmap.
+
+## Notes
+
+- **Default safety posture**: testnet/regtest-first for everyday development and experiments.
+- **Mainnet (experimental)**: available behind explicit guardrails in `Transaction.broadcast(...)`.
+- **Mainnet guardrails**:
+  - 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.
+
+## Acknowledgments
+
+Development of btcaaron is supported by an [OpenSats](https://opensats.org) grant.  
+OpenSats supports open-source contributors working on Bitcoin and related freedom tech.
+
+## Author
+
+**Aaron Zhang**  
+Reproducible Taproot experiments · Script engineering · Educational tooling  
+https://x.com/aaron_recompile
+
+## License
+
+MIT License

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

@@ -2,13 +2,13 @@
 btcaaron - Taproot-focused Bitcoin Toolkit
 
 v0.1.x API (legacy, still supported):
-    from btcaaron import WIFKey, quick_transfer
+    from btcaaron import WIFKey, quick_transfer, fund_program
 
 v0.2.x API (new):
     from btcaaron import Key, TapTree
 """
 
-__version__ = "0.2.0-dev"
+__version__ = "0.2.2"
 
 # ══════════════════════════════════════════════════════════════════
 # Legacy API (v0.1.x) - backward compatible
@@ -19,6 +19,7 @@ from .legacy import (
     BTCTransaction,
     wif_to_addresses, 
     quick_transfer,
+    fund_program,
 )
 
 # ══════════════════════════════════════════════════════════════════
@@ -28,6 +29,7 @@ from .key import Key
 from .tree import TapTree, TaprootProgram, LeafDescriptor
 from .spend import SpendBuilder, Transaction
 from .script import Script, RawScript
+from .psbt import Psbt, PsbtInput, PsbtV2, PsbtV2Input
 from .errors import (
     BtcAaronError,
     BuildError,
@@ -45,6 +47,7 @@ __all__ = [
     "BTCTransaction",
     "wif_to_addresses", 
     "quick_transfer",
+    "fund_program",
     
     # New API
     "Key",
@@ -55,6 +58,10 @@ __all__ = [
     "Transaction",
     "Script",
     "RawScript",
+    "Psbt",
+    "PsbtInput",
+    "PsbtV2",
+    "PsbtV2Input",
     
     # Errors
     "BtcAaronError",

btcaaron-0.2.2/btcaaron/explain/__init__.py

@@ -0,0 +1,8 @@
+"""
+btcaaron.explain - Explanation utilities
+"""
+
+from .program import ProgramExplanation
+from .transaction import TransactionExplanation
+
+__all__ = ["ProgramExplanation", "TransactionExplanation"]

btcaaron-0.2.2/btcaaron/explain/program.py

@@ -0,0 +1,55 @@
+"""
+btcaaron.explain.program - Program explanation
+"""
+
+from dataclasses import dataclass
+from typing import List, Dict, Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..tree.program import TaprootProgram
+
+
+@dataclass
+class ProgramExplanation:
+    """Structured explanation of a TaprootProgram."""
+    
+    program: "TaprootProgram"
+    
+    def to_text(self) -> str:
+        """Generate human-readable text explanation."""
+        p = self.program
+        lines = [
+            "TaprootProgram",
+            f"├── Address: {p.address}",
+            f"├── Internal Key: {p.internal_key}",
+            f"└── Leaves ({p.num_leaves}):",
+        ]
+        
+        for i, label in enumerate(p.leaves):
+            leaf = p.leaf(label)
+            prefix = "    └──" if i == p.num_leaves - 1 else "    ├──"
+            lines.append(f"{prefix} [{i}] \"{label}\": {leaf.script_type}")
+        
+        return "\n".join(lines)
+    
+    def to_markdown(self) -> str:
+        """Generate Markdown explanation."""
+        return f"```\n{self.to_text()}\n```"
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Generate dictionary representation."""
+        p = self.program
+        return {
+            "address": p.address,
+            "internal_key": p.internal_key,
+            "merkle_root": p.merkle_root,
+            "leaves": [
+                {
+                    "label": leaf.label,
+                    "index": leaf.index,
+                    "script_type": leaf.script_type,
+                    "script_hex": leaf.script_hex,
+                }
+                for leaf in [p.leaf(label) for label in p.leaves]
+            ]
+        }

btcaaron-0.2.2/btcaaron/explain/transaction.py

@@ -0,0 +1,53 @@
+"""
+btcaaron.explain.transaction - Transaction explanation
+"""
+
+from dataclasses import dataclass
+from typing import Dict, Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..spend.transaction import Transaction
+
+
+@dataclass
+class TransactionExplanation:
+    """Structured explanation of a Transaction."""
+    
+    tx: "Transaction"
+    
+    def to_text(self) -> str:
+        """Generate human-readable text explanation."""
+        t = self.tx
+        lines = [
+            "Transaction Details",
+            f"├── TXID: {t.txid}",
+            f"├── Size: {t.size} bytes",
+            f"├── Fee: {t.fee} sats ({t.fee_rate:.2f} sat/vB)",
+        ]
+        
+        if t._leaf:
+            lines.append(f"├── Spend Path: Script Path, Leaf \"{t._leaf.label}\"")
+        else:
+            lines.append(f"├── Spend Path: Key Path")
+        
+        lines.append(f"└── Outputs: {len(t._tx.outputs)}")
+        
+        return "\n".join(lines)
+    
+    def to_markdown(self) -> str:
+        """Generate Markdown explanation."""
+        return f"```\n{self.to_text()}\n```"
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Generate dictionary representation."""
+        t = self.tx
+        return {
+            "txid": t.txid,
+            "hex": t.hex,
+            "size": t.size,
+            "vsize": t.vsize,
+            "fee": t.fee,
+            "fee_rate": t.fee_rate,
+            "spend_type": "SCRIPT_PATH" if t._leaf else "KEY_PATH",
+            "leaf_label": t._leaf.label if t._leaf else None,
+        }

{btcaaron-0.2.0 → btcaaron-0.2.2}/btcaaron/key.py

@@ -8,8 +8,33 @@ from typing import Optional
 from bitcoinutils.setup import setup
 from bitcoinutils.keys import PrivateKey
 
-# Ensure testnet is set up
-setup('testnet')
+
+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
+
+
+# Default module context remains testnet-first.
+set_network("testnet")
 
 
 class Key:
@@ -79,6 +104,7 @@ class Key:
         Returns:
             Key instance
         """
+        set_network(network)
         private_key = PrivateKey()
         return cls(private_key)