diff --git a/README.md b/README.md index ba3ce4a..579a838 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ - Download the latest `bal-electrum-plugin-vX.X.X.zip` file 2. **Install in Electrum** - - Open Electrum Bitcoin wallet + - Open Electrum Bitcoin wallet version **4.7.2 or later** - Go to **Tools → Plugins** - Click **Add** - Select the downloaded `.zip` file @@ -57,7 +57,7 @@ Executor Broadcasts at Locktime → Transaction Confirmed → Heirs Receive Fund - The will-executor receives their fee directly in the transaction output - Fee is paid only when transaction is confirmed on the Bitcoin network - Executor is **financially incentivized** to broadcast and confirm the transaction -- No separate payment needed - fee is part of the timelocked transaction +- Fee is a **fixed amount only** (no percentage option) --- @@ -70,7 +70,7 @@ bal-electrum-plugin/ │ ├── bal.py # Main plugin logic and core functionality │ ├── bal_resources.py # Resource management and asset handling │ ├── heirs.py # Heir management logic and validation -│ ├── qt.py # Main Qt interface and GUI components +│ ├── qt.py # Main Qt interface and GUI components (PyQt6) │ ├── util.py # General utility functions │ ├── wallet_util/ │ │ ├── bal_wallet_utils.py # ⚠️ Advanced wallet utilities for emergency fixes @@ -119,14 +119,14 @@ bal-electrum-plugin/ ### Will Executor System (willexecutors.py) - **Multiple executors**: Choose from available executors -- **Incentive structure**: Executor receives fee **only when transaction confirms** -- **Transaction includes fee**: Fee is part of the timelocked transaction output +- **Fixed fee only**: Executor receives a fixed BTC amount (no percentage option) +- **Fee included in transaction**: Fee is part of the timelocked transaction output - **Financial motivation**: Executor must broadcast to get paid - **Automatic transmission**: Transaction sent to executor after creation - **Blockchain monitoring**: Executor broadcasts at locktime expiration **Executor Fee Details**: -- Fee is specified as percentage of transaction amount or fixed amount +- Fee is specified as fixed BTC amount only - Fee is added to transaction outputs - Executor receives fee only when transaction confirms - No separate payment channel needed @@ -134,12 +134,14 @@ bal-electrum-plugin/ ### Advanced Wallet Utilities (wallet_util/) - **⚠️ Emergency tools only**: For fixing wallet database issues - **Purpose**: Handle compatibility across different Electrum walletdb versions -- **Usage**: Advanced users only, not needed for normal operation +- **Usage**: Advanced users only, requires manual installation +- **Installation**: Copy files to Electrum's plugin directory and load Electrum's virtualenv - **Files**: - `bal_wallet_utils.py`: Core wallet database utilities - `bal_wallet_utils_qt.py`: Qt-specific wallet utilities ### Main Interface (qt.py) +- **PyQt6 only**: Uses PyQt6 (not PyQt5) - **User-friendly wizards**: Step-by-step setup interface - **Real-time validation**: Immediate feedback on inputs - **Transaction preview**: Review before finalizing @@ -172,7 +174,7 @@ Executor: "Alice Executor" (fee: 0.01 BTC fixed) - Heir 1: 0.4 BTC - Heir 2: 0.35 BTC - Heir 3: 0.25 BTC - - Executor fee: 0.01 BTC (1% of 1.0 BTC) + - Executor fee: 0.01 BTC (fixed amount) - Network fee: 0.001 BTC - Locktime: 1 year from creation - Sent to: Alice Executor's address @@ -230,7 +232,7 @@ After installation, configure in Electrum: - **Default Locktime**: Set default locktime format (e.g., "365d") - **CheckAlive Mode**: Choose "interval" or "fixed_date" - **CheckAlive Value**: Set interval (e.g., "180d") or timestamp - - **Executor Fee**: Set percentage (e.g., 1) or fixed amount (e.g., 0.01) + - **Executor Fee**: Set fixed BTC amount (e.g., 0.01) - **Debug Mode**: Enable for troubleshooting ### Configuration File Location @@ -247,7 +249,6 @@ After installation, configure in Electrum: "default_locktime": "365d", "checkalive_mode": "interval", "checkalive_value": "180d", - "executor_fee": 0.01, "debug": false } @@ -258,10 +259,9 @@ After installation, configure in Electrum: ## 🛠️ Development ### Prerequisites -- Electrum Bitcoin wallet (version 4.0.0 or later) -- Python 3.7+ -- PyQt5 -- pytest +- **Electrum Bitcoin wallet**: Version **4.7.2 or later** (not 4.0.0) +- **Python**: 3.7+ +- **PyQt6**: Only PyQt6 is supported (not PyQt5) ### Setup Development Environment @@ -276,10 +276,15 @@ zip -r bal-electrum-plugin-dev.zip bal_electrum_plugin/ ### Important Notes on wallet_util/ -**These utilities are for emergency use only**: +**These utilities require manual installation**: - **Purpose**: Fix wallet database compatibility issues across Electrum versions - **Usage**: Only when experiencing wallet corruption or version mismatches +- **Installation Steps**: + 1. Copy `wallet_util/` files to Electrum's plugin directory + 2. Load Electrum's virtualenv + 3. Restart Electrum + - **Risk**: Advanced operations that can affect wallet data - **Documentation**: Limited to inline code comments @@ -298,27 +303,11 @@ zip -r bal-electrum-plugin-dev.zip bal_electrum_plugin/ 4. Re-zip and reinstall to test -### Running Tests +### Running the Plugin -```bash -# Install test dependencies -pip install pytest - -# Run all tests -pytest tests/ - -# Run specific test -pytest tests/test_heirs.py -v -``` - -### Code Style - -- Follow PEP 8 guidelines strictly -- Use descriptive variable and function names -- Add type hints for public functions -- Write comprehensive docstrings -- Keep functions focused and small (< 50 lines) -- Document complex logic thoroughly +The plugin uses Electrum's existing virtualenv. No additional dependencies needed beyond: +- Electrum 4.7.2+ +- PyQt6 --- @@ -327,12 +316,17 @@ pytest tests/test_heirs.py -v ### Common Issues #### Plugin Not Showing in Electrum -- ✅ Verify Electrum version is 4.0.0 or later +- ✅ Verify Electrum version is **4.7.2 or later** (not 4.0.0) - ✅ Check zip contains `bal_electrum_plugin/` directory at root - ✅ Verify directory structure inside zip is correct - ✅ Restart Electrum completely after installation - ✅ Check Electrum logs: Help → Debug → Console +#### PyQt6 Compatibility Issues +- ✅ Ensure you're using PyQt6, not PyQt5 +- ✅ Verify Electrum 4.7.2+ uses PyQt6 +- ✅ Check import statements in plugin code + #### Locktime Format Errors - ✅ Use valid formats: `180d`, `1y`, or Unix timestamp (e.g., `1735689600`) - ✅ Ensure locktime is in the future (after current time) @@ -357,14 +351,20 @@ pytest tests/test_heirs.py -v - ✅ Verify all heirs have valid, unique addresses - ✅ Ensure locktime format is correct - ✅ Check executor is selected and available -- ✅ Verify executor fee is properly configured +- ✅ Verify executor fee is properly configured (fixed amount only) #### Executor Fee Issues +- ✅ Fee is a fixed BTC amount only (no percentage option) - ✅ Fee is included in transaction output - ✅ Executor receives fee only when transaction confirms -- ✅ No separate payment needed - fee is part of transaction - ✅ Transaction must be broadcast and confirmed for executor to get paid +#### wallet_util/ Not Working +- ✅ Copy files to Electrum's plugin directory +- ✅ Load Electrum's virtualenv before using +- ✅ Only use for emergency wallet fixes +- ✅ Backup wallet before using wallet utilities + --- ## 🤝 Contributing @@ -373,11 +373,10 @@ We welcome contributions! Please follow these guidelines: 1. **Fork the repository** on Gitea 2. **Create feature branch**: `git checkout -b feature/your-feature` -3. **Add tests** for new functionality -4. **Follow PEP 8** style guide strictly -5. **Write clear commit messages** following Conventional Commits -6. **Update documentation** for new features -7. **Open Pull Request** to `main` branch +3. **Follow PEP 8** style guide strictly +4. **Write clear commit messages** following Conventional Commits +5. **Update documentation** for new features +6. **Open Pull Request** to `main` branch ### Development Workflow @@ -397,8 +396,7 @@ git checkout -b feature/your-feature-name # Make changes to bal_electrum_plugin/ files # ... -# Test changes -pytest tests/ +# Test in Electrum 4.7.2+ with PyQt6 # Commit changes with clear message git add . @@ -431,4 +429,6 @@ MIT License - see [LICENSE](LICENSE) for details. **🔒 Security**: Never share your seed phrase or private keys. This plugin only creates transactions, it doesn't store your keys. -**💡 Note**: The executor fee is included in the transaction output. The executor is financially incentivized to broadcast the transaction and ensure it confirms on the Bitcoin network. +**💡 Note**: The executor fee is a fixed BTC amount included in the transaction output. The executor is financially incentivized to broadcast the transaction and ensure it confirms on the Bitcoin network. + +**📋 Requirements**: Electrum 4.7.2+ with PyQt6 only. No pytest or additional dependencies needed.