kaibot/bal-electrum-plugin
1
0
Fork 0
forked from bitcoinafterlife/bal-electrum-plugin
Code Pull Requests Activity

docs(README): Update with correct file structure and module descriptions

Browse Source
This commit is contained in:
kaibot
2026-04-09 11:16:38 +00:00
parent b63dc5ba4f
commit 22fa6cd708
1 changed files with 103 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
README.md
View File

@@ -92,52 +92,58 @@ The plugin allows users to create a **Bitcoin will** that automatically executes
``` ```
bal-electrum-plugin/ bal-electrum-plugin/
├── bal_electrum_plugin/ ├── bal_electrum_plugin/ # Main plugin directory (what to zip)
│ ├── __init__.py # Plugin entry point │ ├── __init__.py # Plugin initialization and entry point
│ ├── qt.py # Main Qt interface │ ├── bal.py # Main plugin logic and core functionality
│ ├── bal_resources.py # Resource management and asset handling
│ ├── heirs.py # Heir management logic │ ├── heirs.py # Heir management logic
│ ├── locktime.py # Locktime handling │ ├── qt.py # Main Qt interface and GUI components
│ ├── checkalive.py # CheckAlive verification │ ├── util.py # Utility functions and helpers
│ ├── executor.py # Will executor management │ ├── wallet_util/
│ ├── dialogs/ │ │ ├── bal_wallet_utils.py # Wallet utility functions
│ │ ├── setup_wizard.py # Main setup interface │ │ └── bal_wallet_utils_qt.py # Qt-specific wallet utilities
│ │ ├── heirs_dialog.py # Heir configuration │ ├── will.py # Will creation and management
│ │ ├── locktime_dialog.py # Locktime setup │ └── willexecutors.py # Will executor functionality
│ │ ├── checkalive_dialog.py # CheckAlive configuration ├── README.md # This file
│ │ └── executor_dialog.py # Executor selection └── LICENSE # MIT License
│ └── utils.py # Utility functions
├── README.md
└── LICENSE
``` ```
**Important**: Only the `bal_electrum_plugin/` directory needs to be zipped for installation.
--- ---
## 🎯 Key Features ## 🎯 Key Features
### Heir Management ### Heir Management (heirs.py)
- **Multiple heirs**: Add unlimited beneficiaries - **Multiple heirs**: Add unlimited beneficiaries
- **Flexible distribution**: Percentage-based or fixed amount - **Flexible distribution**: Percentage-based or fixed amount
- **Address validation**: Verify Bitcoin addresses before saving - **Address validation**: Verify Bitcoin addresses before saving
- **Distribution summary**: View total inheritance breakdown - **Distribution summary**: View total inheritance breakdown
### Locktime Configuration ### Locktime Configuration (will.py)
- **Timestamp format**: Unix timestamp (e.g., `1735689600`) - **Timestamp format**: Unix timestamp (e.g., `1735689600`)
- **Interval format**: Days (`180d`) or years (`1y`) - **Interval format**: Days (`180d`) or years (`1y`)
- **Automatic conversion**: Intervals converted to timestamps internally - **Automatic conversion**: Intervals converted to timestamps internally
- **Validation**: Ensures locktime is in the future - **Validation**: Ensures locktime is in the future
### CheckAlive Mechanism ### CheckAlive Mechanism (will.py)
- **Two verification modes**: Interval or fixed date - **Two verification modes**: Interval or fixed date
- **Automatic validation**: Checks if testator is still alive - **Automatic validation**: Checks if testator is still alive
- **Will invalidation**: Old wills marked invalid if CheckAlive expires - **Will invalidation**: Old wills marked invalid if CheckAlive expires
- **Flexible timing**: Configure based on your needs - **Flexible timing**: Configure based on your needs
### Will Executor System ### Will Executor System (willexecutors.py)
- **Multiple executors**: Choose from available executors - **Multiple executors**: Choose from available executors
- **Fee structure**: Executors receive a fee for services - **Fee structure**: Executors receive a fee for services
- **Automatic transmission**: Transaction sent to executor after creation - **Automatic transmission**: Transaction sent to executor after creation
- **Blockchain monitoring**: Executor broadcasts at locktime - **Blockchain monitoring**: Executor broadcasts at locktime
### Main Interface (qt.py)
- **User-friendly wizards**: Step-by-step setup interface
- **Real-time validation**: Immediate feedback on inputs
- **Transaction preview**: Review before finalizing
- **Status monitoring**: Track will execution progress
--- ---
## 📖 Usage Examples ## 📖 Usage Examples
@@ -220,7 +226,13 @@ After installation, configure in Electrum:
- **Executor Fee**: Set percentage or fixed fee for executors - **Executor Fee**: Set percentage or fixed fee for executors
- **Debug Mode**: Enable for troubleshooting - **Debug Mode**: Enable for troubleshooting
### Configuration File ### Configuration File Location
```
~/.electrum/plugins/bal_electrum_plugin/config.json
```
### Example Configuration
```json ```json
{ {
@@ -243,15 +255,35 @@ After installation, configure in Electrum:
- PyQt5 - PyQt5
- pytest - pytest
### Setup ### Setup Development Environment
```bash ```bash
# Clone repository # Clone repository
git clone https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin.git git clone https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin.git
cd bal-electrum-plugin cd bal-electrum-plugin
# Install in development mode # Create development zip
pip install -e . zip -r bal-electrum-plugin-dev.zip bal_electrum_plugin/
```
### Install for Development
1. Copy zip to Electrum plugins directory:
```bash
cp bal-electrum-plugin-dev.zip ~/.electrum/plugins/
```
2. Install in Electrum (Tools → Plugins → Add)
3. Make changes to files in `bal_electrum_plugin/` directory
4. Re-zip and reinstall to test:
```bash
cd ~/.electrum/plugins/
unzip bal-electrum-plugin-dev.zip -d bal_electrum_plugin_temp
# Make changes to bal_electrum_plugin_temp/
zip -r bal-electrum-plugin-dev.zip bal_electrum_plugin_temp/
rm -rf bal_electrum_plugin_temp
``` ```
### Running Tests ### Running Tests
@@ -273,6 +305,7 @@ pytest tests/test_heirs.py -v
- Use descriptive variable names - Use descriptive variable names
- Add type hints for public functions - Add type hints for public functions
- Write comprehensive docstrings - Write comprehensive docstrings
- Keep functions focused and small
--- ---
@@ -283,23 +316,32 @@ pytest tests/test_heirs.py -v
#### Plugin Not Showing in Electrum #### Plugin Not Showing in Electrum
- ✅ Verify Electrum version (4.0.0+) - ✅ Verify Electrum version (4.0.0+)
- ✅ Check zip contains `bal_electrum_plugin/` directory - ✅ Check zip contains `bal_electrum_plugin/` directory
- ✅ Verify directory structure inside zip
- ✅ Restart Electrum after installation - ✅ Restart Electrum after installation
- ✅ Check Electrum logs (Help → Debug → Console) - ✅ Check Electrum logs (Help → Debug → Console)
#### Locktime Format Errors #### Locktime Format Errors
- ✅ Use valid formats: `180d`, `1y`, or Unix timestamp - ✅ Use valid formats: `180d`, `1y`, or Unix timestamp
- ✅ Ensure locktime is in the future - ✅ Ensure locktime is in the future
- ✅ Check for typos in interval format - ✅ Check for typos in interval format (must be lowercase d/y)
#### CheckAlive Not Working #### CheckAlive Not Working
- ✅ Verify CheckAlive mode (interval or fixed date) - ✅ Verify CheckAlive mode (interval or fixed date)
- ✅ Ensure CheckAlive is before Locktime - ✅ Ensure CheckAlive is before Locktime
- ✅ Check date calculations are correct - ✅ Check date calculations are correct
- ✅ Verify logic: interval mode uses `locktime - interval > now`
#### Heir Distribution Errors #### Heir Distribution Errors
- ✅ Verify percentages sum to 100% or amounts are valid - ✅ Verify percentages sum to 100% or amounts are valid
- ✅ Check Bitcoin addresses are valid - ✅ Check Bitcoin addresses are valid (use testnet for testing)
- ✅ Ensure no duplicate addresses - ✅ Ensure no duplicate addresses
- ✅ Verify fixed amounts don't exceed wallet balance
#### Transaction Creation Fails
- ✅ Check wallet has sufficient funds
- ✅ Verify all heirs have valid addresses
- ✅ Ensure locktime is properly formatted
- ✅ Check executor is selected and available
--- ---
@@ -314,6 +356,37 @@ We welcome contributions! Please follow these guidelines:
5. Update documentation 5. Update documentation
6. Open Pull Request to `main` branch 6. Open Pull Request to `main` branch
### Development Workflow
```bash
# Fork repository on Gitea
# Clone your fork
git clone https://bitcoin-after.life/gitea/YOUR_USERNAME/bal-electrum-plugin.git
cd bal-electrum-plugin
# Add upstream remote
git remote add upstream https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin.git
# Create feature branch
git checkout -b feature/your-feature-name
# Make changes
# ...
# Test changes
pytest tests/
# Commit changes
git add .
git commit -m "feat: add new feature description"
# Push to your fork
git push origin feature/your-feature-name
# Open Pull Request on Gitea
```
--- ---
## 📜 License ## 📜 License
@@ -325,11 +398,14 @@ MIT License - see [LICENSE](LICENSE) for details.
## 🔗 Links ## 🔗 Links
- **Repository**: [https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin) - **Repository**: [https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin)
- **Releases**: [Releases page](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases) - **Releases**: [https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases)
- **Issues**: [Issues tracker](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/issues) - **Issues**: [https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/issues](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/issues)
- **Discussions**: [https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/discussions](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/discussions)
--- ---
**⚠️ Important**: Always test with small amounts first. This plugin deals with Bitcoin transactions that may be irreversible. **⚠️ Important**: Always test with small amounts first. This plugin deals with Bitcoin transactions that may be irreversible.
**🔒 Security**: Never share your seed phrase or private keys. This plugin only creates transactions, it doesn't store your keys. **🔒 Security**: Never share your seed phrase or private keys. This plugin only creates transactions, it doesn't store your keys.
**📝 Note**: The plugin creates timelocked transactions that can only be spent after the locktime expires. Executors are trusted to broadcast at the correct time.