bitcoinafterlife/bal-electrum-plugin
1
1
Fork 3
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

docs(README): Update requirements - PyQt6 only, Electrum 4.7.2+, remove pytest, correct wallet_utils usage

Browse Source
This commit is contained in:
kaibot
2026-04-09 11:35:25 +00:00
parent 694e14d851
commit 5dc1ca36ab
1 changed files with 46 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
README.md
View File

@@ -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.