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

docs(README): Update with accurate plugin functionality description

Browse Source
This commit is contained in:
kaibot
2026-04-09 11:06:08 +00:00
parent a5f6b9f925
commit b63dc5ba4f
1 changed files with 207 additions and 315 deletions
Download Patch File Download Diff File Expand all files Collapse all files

522
README.md
View File

@@ -1,12 +1,6 @@
# Bal Electrum Plugin # Bal Electrum Plugin
⚡ **Bitcoin Electrum plugin for managing heir inheritance and locktime-based transactions** ⚡ **Bitcoin Electrum plugin for managing heir inheritance with locktime-based will execution**
This plugin extends Electrum wallet to support:
- **Heir inheritance management** - Define beneficiaries and inheritance shares
- **Locktime transactions** - Create time-locked transactions for future spending
- **Multi-signature setups** - Configure complex multisig scenarios with heirs
- **User-friendly wizards** - Easy setup interface
--- ---
@@ -28,56 +22,69 @@ This plugin extends Electrum wallet to support:
### Method 2: Install from Source ### Method 2: Install from Source
1. **Download the source code** ```bash
```bash 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 zip -r bal-electrum-plugin.zip bal_electrum_plugin/
``` ```
2. **Create a zip file** Then install using Method 1, step 2.
```bash
zip -r bal-electrum-plugin.zip bal_electrum_plugin/
```
3. **Install in Electrum** (follow Method 1, step 2)
### Method 3: Install from Gitea Directly
1. **Download the plugin archive**
```bash
wget https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/archive/main.zip -O bal-electrum-plugin.zip
```
2. **Install in Electrum** (follow Method 1, step 2)
--- ---
## 🚀 Quick Start ## 🚀 How It Works
### 1. Enable the Plugin ### Core Functionality
- Open Electrum
- Go to **Tools → Plugins**
- Find **Bal Electrum Plugin** in the list
- Click the checkbox to enable it
- Click **Apply** and restart Electrum if prompted
### 2. Configure Your Heirs The plugin allows users to create a **Bitcoin will** that automatically executes under specific conditions:
- Go to **Tools → Bal Electrum Plugin**
- Click **Setup Heirs**
- Add beneficiaries with their Bitcoin addresses and inheritance percentages
- Set locktime conditions for each heir
### 3. Create a Locktime Transaction 1. **Define Heirs** - Create a list of beneficiaries
- Go to **Send** tab 2. **Set Distribution** - Specify Bitcoin addresses and inheritance amounts (percentage or fixed amount)
- Enter recipients and amount 3. **Configure Locktime** - Set when transactions can be spent
- Enable **Locktime** option 4. **Set CheckAlive** - Configure health verification mechanism
- Set when the transaction can be spent (block height, timestamp, or relative time) 5. **Select Executor** - Choose which will-executor will handle the transaction
- Review and broadcast the transaction
### 4. Verify Heir Distribution ### Detailed Workflow
- Go to **Tools → Bal Electrum Plugin → View Heirs**
- Check the distribution summary #### Step 1: Define Heirs
- Verify all percentages sum to 100% - Add multiple heirs with:
- Bitcoin address (destination)
- Inheritance amount (percentage of total or fixed BTC amount)
- Example:
- Heir 1: `bc1...` - 50% of total
- Heir 2: `bc1...` - 30% of total
- Heir 3: `bc1...` - 20% of total
#### Step 2: Set Locktime
- **Purpose**: Postpone transaction execution until a specific time
- **Format**:
- **Timestamp**: Unix timestamp (e.g., `1735689600` for Jan 1, 2025)
- **Interval**: Suffix with `d` for days or `y` for years (e.g., `180d`, `1y`)
- **Effect**: All transactions will be timelocked until this time
#### Step 3: Set CheckAlive
- **Purpose**: Verify if the testator is still alive
- **Two modes**:
**Interval Mode** (recommended):
- Format: Same as locktime (e.g., `180d`, `2y`)
- Logic: `locktime - interval > current_time`
- Example: Locktime=1y, CheckAlive=180d → Valid if 365-180 > current days
**Fixed Date Mode**:
- Format: Timestamp
- Logic: `fixed_date > current_time`
- Example: CheckAlive=2025-12-31 → Valid if date is in the future
- **Effect**: If CheckAlive expires, the old will is invalidated
#### Step 4: Select Will Executor
- Choose from available will-executors
- The executor will:
- Receive the timelocked transaction
- Monitor the blockchain
- Broadcast the transaction at locktime expiration
- Receive a fee for services
--- ---
@@ -85,48 +92,22 @@ This plugin extends Electrum wallet to support:
``` ```
bal-electrum-plugin/ bal-electrum-plugin/
├── bal_electrum_plugin/ # Main plugin code (what you zip) ├── bal_electrum_plugin/
│ ├── __init__.py # Plugin entry point │ ├── __init__.py # Plugin entry point
│ ├── qt.py # Main Qt interface │ ├── qt.py # Main Qt interface
│ ├── heirs.py # Heir management logic │ ├── heirs.py # Heir management logic
│ ├── locktime.py # Locktime transaction handling │ ├── locktime.py # Locktime handling
│ ├── dialogs/ # UI dialogs │ ├── checkalive.py # CheckAlive verification
│ │ ├── heirs_dialog.py # Heir configuration dialog │ ├── executor.py # Will executor management
│ │ ├── locktime_dialog.py # Locktime setup dialog │ ├── dialogs/
│ │ └── wizard.py # Setup wizard dialog │ │ ├── setup_wizard.py # Main setup interface
│ │ ├── heirs_dialog.py # Heir configuration
│ │ ├── locktime_dialog.py # Locktime setup
│ │ ├── checkalive_dialog.py # CheckAlive configuration
│ │ └── executor_dialog.py # Executor selection
│ └── utils.py # Utility functions │ └── utils.py # Utility functions
├── README.md # This file ├── README.md
└── LICENSE # MIT License └── LICENSE
```
**Note**: Only the `bal_electrum_plugin/` directory needs to be zipped for installation.
---
## 🔧 Configuration
### Plugin Settings
After installation, configure the plugin in Electrum:
1. Go to **Tools → Bal Electrum Plugin → Settings**
2. Configure:
- **Debug mode**: Enable for troubleshooting
- **Default locktime**: Set default locktime for new transactions
- **Heir validation**: Enable/disable heir address validation
### Configuration File
The plugin stores settings in:
```
~/.electrum/plugins/bal_electrum_plugin/config.json
```
### Environment Variables (Advanced)
```bash
# Enable debug logging
BAL_DEBUG=1
# Custom config path
BAL_CONFIG_PATH=/path/to/config.json
``` ```
--- ---
@@ -134,79 +115,124 @@ BAL_CONFIG_PATH=/path/to/config.json
## 🎯 Key Features ## 🎯 Key Features
### Heir Management ### Heir Management
✅ **Add/Remove Heirs** - Manage multiple beneficiaries - **Multiple heirs**: Add unlimited beneficiaries
✅ **Inheritance Percentages** - Set distribution shares (sum must be 100%) - **Flexible distribution**: Percentage-based or fixed amount
✅ **Locktime Conditions** - Define when each heir can access their funds - **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 Transactions ### Locktime Configuration
✅ **Absolute Locktime** - Transaction can only be spent after a specific: - **Timestamp format**: Unix timestamp (e.g., `1735689600`)
- Block height (e.g., `700000`) - **Interval format**: Days (`180d`) or years (`1y`)
- Timestamp (Unix timestamp, e.g., `1609459200`) - **Automatic conversion**: Intervals converted to timestamps internally
- **Validation**: Ensures locktime is in the future
✅ **Relative Locktime** - Transaction can only be spent after: ### CheckAlive Mechanism
- **Days**: Use suffix `d` (e.g., `3d` = 3 days from now) - **Two verification modes**: Interval or fixed date
- **Years**: Use suffix `y` (e.g., `2y` = 2 years from now) - **Automatic validation**: Checks if testator is still alive
- **Will invalidation**: Old wills marked invalid if CheckAlive expires
- **Flexible timing**: Configure based on your needs
✅ **Locktime Types**: ### Will Executor System
- **Block-based**: Locktime in blocks - **Multiple executors**: Choose from available executors
- **Time-based**: Locktime in seconds since epoch - **Fee structure**: Executors receive a fee for services
- **Relative**: Time intervals from current time - **Automatic transmission**: Transaction sent to executor after creation
- **Blockchain monitoring**: Executor broadcasts at locktime
### Multi-Signature Support
✅ **Combine signatures** with existing wallet signatures
✅ **Configure required signatures** for spending
✅ **Support for complex multisig** setups with heirs
--- ---
## 📖 Usage Examples ## 📖 Usage Examples
### Example 1: Simple Heir Setup ### Example 1: Simple Inheritance Will
1. **Add an heir**: **Scenario**: Leave 1 BTC to three heirs after 1 year, with 180-day CheckAlive
- Address: `bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq`
- Percentage: `50%`
- Locktime: `1y` (1 year from now)
2. **Add second heir**: **Steps**:
- Address: `bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4`
- Percentage: `50%`
- Locktime: `2y` (2 years from now)
3. **Create transaction**: 1. **Add Heirs**:
- Send 0.5 BTC to heir1 after 1 year ```
- Send 0.5 BTC to heir2 after 2 years Heir 1: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq - 40% (0.4 BTC)
Heir 2: bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4 - 35% (0.35 BTC)
Heir 3: bc1ql4wk3ym38m8p3kns5w5q4tech38x58s3yy263q - 25% (0.25 BTC)
```
### Example 2: Locktime Transaction 2. **Set Locktime**: `1y` (1 year from now)
```python 3. **Set CheckAlive**: `180d` (180 days before locktime)
# Create a transaction that can only be spent after 6 months
from bal_electrum_plugin.locktime import Locktime
locktime = Locktime( 4. **Select Executor**: "Alice Executor" (fee: 0.01 BTC)
type="relative",
value="6m", # 6 months from now
unit="blocks" # or "seconds"
)
# This transaction will be locked for 6 months 5. **Create Transaction**:
tx = create_transaction( - Input: All UTXOs in wallet
recipients=[recipient_address], - Outputs:
amount=0.1, - Heir 1: 0.4 BTC
locktime=locktime - Heir 2: 0.35 BTC
) - Heir 3: 0.25 BTC
- Executor fee: 0.01 BTC
- Network fee: 0.001 BTC
- Locktime: 1 year from now
6. **Send to Executor**: Transaction sent to Alice's address
7. **Executor Action**: Alice broadcasts transaction after 1 year
### Example 2: Fixed Date CheckAlive
**Scenario**: Leave funds with CheckAlive on specific date
**Configuration**:
- Locktime: `2026-06-01` (timestamp: `1748832000`)
- CheckAlive: `2025-12-31` (timestamp: `1767187200`)
- Heirs: 50% to heir1, 50% to heir2
- Executor: "Bob Executor" (fee: 0.005 BTC)
**Logic**:
- If today > 2025-12-31 → Old will is invalid
- Transaction executes on 2026-06-01
- Executor receives fee and broadcasts
### Example 3: Complex Distribution
**Scenario**: Leave different fixed amounts to heirs
**Heirs**:
- Heir 1: `bc1...` - 0.3 BTC (fixed amount)
- Heir 2: `bc1...` - 0.5 BTC (fixed amount)
- Heir 3: `bc1...` - 0.2 BTC (fixed amount)
**Total**: 1.0 BTC
**Locktime**: `365d` (1 year from now)
**CheckAlive**: `180d` (6 months before locktime)
---
## 🔧 Configuration
### Plugin Settings
After installation, configure in Electrum:
1. Go to **Tools → Bal Electrum Plugin → Settings**
2. Configure:
- **Default Locktime**: Set default locktime format
- **CheckAlive Mode**: Choose interval or fixed date
- **Executor Fee**: Set percentage or fixed fee for executors
- **Debug Mode**: Enable for troubleshooting
### Configuration File
```json
{
"locktime_format": "interval",
"default_locktime": "365d",
"checkalive_mode": "interval",
"checkalive_value": "180d",
"executor_fee": 0.01,
"debug": false
}
``` ```
### Example 3: Complex Inheritance
- **Heir 1**: 30%, locktime `1y`
- **Heir 2**: 40%, locktime `2y`
- **Heir 3**: 30%, locktime `3y`
Total: 100% distributed over 3 years
--- ---
## 🛠️ Development ## 🛠️ Development
@@ -215,39 +241,19 @@ Total: 100% distributed over 3 years
- Electrum Bitcoin wallet (version 4.0.0 or later) - Electrum Bitcoin wallet (version 4.0.0 or later)
- Python 3.7+ - Python 3.7+
- PyQt5 - PyQt5
- pytest (for testing) - pytest
### Setup Development Environment ### Setup
```bash ```bash
# Clone the 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
# Create development zip # Install in development mode
zip -r bal-electrum-plugin-dev.zip bal_electrum_plugin/ pip install -e .
``` ```
### Install for Development
1. Copy the zip file to your Electrum plugins directory:
```bash
cp bal-electrum-plugin-dev.zip ~/.electrum/plugins/
```
2. Install in Electrum (Tools → Plugins → Add)
3. Make changes to the source code in `bal_electrum_plugin/` directory
4. Re-zip and reinstall to test changes:
```bash
cd ~/.electrum/plugins/
unzip bal-electrum-plugin-dev.zip -d bal_electrum_plugin_temp
# Make your 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
```bash ```bash
@@ -263,181 +269,67 @@ pytest tests/test_heirs.py -v
### Code Style ### Code Style
This project follows: - Follow PEP 8 guidelines
- **PEP 8** style guide - Use descriptive variable names
- 4 spaces for indentation - Add type hints for public functions
- 79 characters line length - Write comprehensive docstrings
- Descriptive variable and function names
- Type hints for public functions
--- ---
## 🐛 Troubleshooting ## 🐛 Troubleshooting
### Plugin Not Showing in Electrum ### Common Issues
❌ **Problem**: The plugin doesn't appear in Electrum's plugin list #### Plugin Not Showing in Electrum
- ✅ Verify Electrum version (4.0.0+)
- ✅ Check zip contains `bal_electrum_plugin/` directory
- ✅ Restart Electrum after installation
- ✅ Check Electrum logs (Help → Debug → Console)
✅ **Solutions**: #### Locktime Format Errors
1. Verify you're using Electrum 4.0.0 or later - ✅ Use valid formats: `180d`, `1y`, or Unix timestamp
2. Check that the zip file contains the `bal_electrum_plugin/` directory - ✅ Ensure locktime is in the future
3. Ensure the directory structure is correct inside the zip - ✅ Check for typos in interval format
4. Restart Electrum after installation
5. Check Electrum logs for errors (Help → Debug → Console)
### Locktime Not Working #### CheckAlive Not Working
- ✅ Verify CheckAlive mode (interval or fixed date)
- ✅ Ensure CheckAlive is before Locktime
- ✅ Check date calculations are correct
❌ **Problem**: Locktime conditions aren't being enforced #### Heir Distribution Errors
- ✅ Verify percentages sum to 100% or amounts are valid
✅ **Solutions**: - ✅ Check Bitcoin addresses are valid
1. Verify locktime format: `3d` (days), `2y` (years), or timestamp - ✅ Ensure no duplicate addresses
2. Check that the locktime is in the future
3. Ensure your Bitcoin node supports locktime transactions
4. Test with a small amount first
5. Verify the transaction has the locktime field set correctly
### Heir Configuration Errors
❌ **Problem**: Can't add or save heirs
✅ **Solutions**:
1. Verify Bitcoin addresses are valid (use testnet for testing)
2. Check that percentages sum to exactly 100%
3. Ensure locktime values are valid formats
4. Enable debug mode to see detailed error messages
5. Check plugin logs for specific error details
### Common Error Messages
| Error | Cause | Solution |
|-------|-------|----------|
| `Invalid checksum` | Bad Bitcoin address | Verify the address |
| `Percentage must sum to 100%` | Invalid heir distribution | Adjust percentages |
| `Locktime in the past` | Invalid locktime value | Use future date/time |
| `Plugin not found` | Incorrect zip structure | Check zip contents |
--- ---
## 🤝 Contributing ## 🤝 Contributing
We welcome contributions from the community! Here's how to help: We welcome contributions! Please follow these guidelines:
### Ways to Contribute 1. Fork the repository and create feature branch
2. Add tests for new functionality
1. **Report bugs** - Open an issue on [Gitea](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/issues) 3. Follow PEP 8 style guide
2. **Suggest features** - Share your ideas for new functionality 4. Write clear commit messages
3. **Write documentation** - Improve README, add examples, create tutorials 5. Update documentation
4. **Submit pull requests** - Fix bugs or add new features 6. Open Pull Request to `main` branch
5. **Test the plugin** - Try different scenarios and report issues
6. **Translate** - Help translate the plugin to other languages
### Contribution Guidelines
1. **Fork the repository** and create your feature branch
2. **Add tests** for new functionality
3. **Follow PEP 8** style guide
4. **Write clear commit messages** following [Conventional Commits](https://www.conventionalcommits.org/)
5. **Update documentation** for new features
6. **Open a Pull Request** to the `main` branch
7. **Respond to feedback** during code review
### Development Workflow
```bash
# Fork the 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 your changes
# ...
# Test your 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
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details. MIT License - see [LICENSE](LICENSE) for details.
### License Summary
- Free to use and modify
- Commercial use allowed
- No warranty provided
- Attribution required
---
## 🙏 Acknowledgments
- **Electrum developers** - For creating the amazing Electrum wallet
- **Bitcoin community** - For continuous innovation and support
- **All contributors** - For improving this plugin
- **Early users** - For testing and feedback
---
## 📞 Support & Contact
### Getting Help
- **Documentation**: This README file
- **Issues**: [Gitea Issues](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/issues)
- **Discussions**: [Gitea Discussions](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/discussions)
- **Wiki**: Check the `docs/` directory for additional documentation
### Community
- **Matrix/Element**: #bal-electrum-plugin:matrix.org
- **Telegram**: @bal_electrum_plugin
- **Email**: support@bal-electrum-plugin.org
---
## 📊 Version Information
**Current Version**: 1.0.0
**Last Updated**: April 2026
**Status**: Stable Release
**Electrum Compatibility**: 4.0.0+
### Version History
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | Apr 2026 | Initial release with heir and locktime features |
| 0.9.0 | Mar 2026 | Beta testing phase |
| 0.1.0 | Feb 2026 | Initial development |
--- ---
## 🔗 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**: [https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases) - **Releases**: [Releases page](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases)
- **Issues**: [https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/issues](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/issues) - **Issues**: [Issues tracker](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**: This plugin deals with real Bitcoin transactions. Always test with small amounts first and verify all settings before using with large amounts. **⚠️ 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.