From c739d110d6d3693e4f6c7627873db4123033ea48 Mon Sep 17 00:00:00 2001 From: kaibot Date: Thu, 9 Apr 2026 10:45:46 +0000 Subject: [PATCH] docs(README): Add comprehensive installation and usage guide for Bal Electrum Plugin --- README.md | 445 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 443 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5896ad7..06f7eeb 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,443 @@ -# BalPlugin -Bitcoin After Life Electrum Plugin +# Bal Electrum Plugin + +⚡ **Bitcoin Electrum plugin for managing heir inheritance and locktime-based transactions** + +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 + +--- + +## 📥 Installation + +### Method 1: Install from Release (Recommended) + +1. **Download the plugin** + - Go to: [https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases) + - Download the latest `bal-electrum-plugin-vX.X.X.zip` file + +2. **Install in Electrum** + - Open Electrum Bitcoin wallet + - Go to **Tools → Plugins** + - Click **Add** + - Select the downloaded `.zip` file + - Click **Open** or **Install** + - Restart Electrum if required + +### Method 2: Install from Source + +1. **Download the source code** + ```bash + git clone https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin.git + cd bal-electrum-plugin + ``` + +2. **Create a zip file** + ```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 + +### 1. Enable the Plugin +- 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 +- 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 +- Go to **Send** tab +- Enter recipients and amount +- Enable **Locktime** option +- Set when the transaction can be spent (block height, timestamp, or relative time) +- Review and broadcast the transaction + +### 4. Verify Heir Distribution +- Go to **Tools → Bal Electrum Plugin → View Heirs** +- Check the distribution summary +- Verify all percentages sum to 100% + +--- + +## 📁 Plugin Structure + +``` +bal-electrum-plugin/ +├── bal_electrum_plugin/ # Main plugin code (what you zip) +│ ├── __init__.py # Plugin entry point +│ ├── qt.py # Main Qt interface +│ ├── heirs.py # Heir management logic +│ ├── locktime.py # Locktime transaction handling +│ ├── dialogs/ # UI dialogs +│ │ ├── heirs_dialog.py # Heir configuration dialog +│ │ ├── locktime_dialog.py # Locktime setup dialog +│ │ └── wizard.py # Setup wizard dialog +│ └── utils.py # Utility functions +├── README.md # This file +└── LICENSE # MIT 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 +``` + +--- + +## 🎯 Key Features + +### Heir Management +✅ **Add/Remove Heirs** - Manage multiple beneficiaries +✅ **Inheritance Percentages** - Set distribution shares (sum must be 100%) +✅ **Locktime Conditions** - Define when each heir can access their funds +✅ **Address Validation** - Verify Bitcoin addresses before saving +✅ **Distribution Summary** - View total inheritance breakdown + +### Locktime Transactions +✅ **Absolute Locktime** - Transaction can only be spent after a specific: + - Block height (e.g., `700000`) + - Timestamp (Unix timestamp, e.g., `1609459200`) + +✅ **Relative Locktime** - Transaction can only be spent after: + - **Days**: Use suffix `d` (e.g., `3d` = 3 days from now) + - **Years**: Use suffix `y` (e.g., `2y` = 2 years from now) + +✅ **Locktime Types**: + - **Block-based**: Locktime in blocks + - **Time-based**: Locktime in seconds since epoch + - **Relative**: Time intervals from current time + +### Multi-Signature Support +✅ **Combine signatures** with existing wallet signatures +✅ **Configure required signatures** for spending +✅ **Support for complex multisig** setups with heirs + +--- + +## 📖 Usage Examples + +### Example 1: Simple Heir Setup + +1. **Add an heir**: + - Address: `bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq` + - Percentage: `50%` + - Locktime: `1y` (1 year from now) + +2. **Add second heir**: + - Address: `bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4` + - Percentage: `50%` + - Locktime: `2y` (2 years from now) + +3. **Create transaction**: + - Send 0.5 BTC to heir1 after 1 year + - Send 0.5 BTC to heir2 after 2 years + +### Example 2: Locktime Transaction + +```python +# Create a transaction that can only be spent after 6 months +from bal_electrum_plugin.locktime import Locktime + +locktime = Locktime( + type="relative", + value="6m", # 6 months from now + unit="blocks" # or "seconds" +) + +# This transaction will be locked for 6 months +tx = create_transaction( + recipients=[recipient_address], + amount=0.1, + locktime=locktime +) +``` + +### 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 + +### Prerequisites +- Electrum Bitcoin wallet (version 4.0.0 or later) +- Python 3.7+ +- PyQt5 +- pytest (for testing) + +### Setup Development Environment + +```bash +# Clone the repository +git clone https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin.git +cd bal-electrum-plugin + +# Create development zip +zip -r bal-electrum-plugin-dev.zip bal_electrum_plugin/ +``` + +### 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 + +```bash +# Install test dependencies +pip install pytest + +# Run all tests +pytest tests/ + +# Run specific test +pytest tests/test_heirs.py -v +``` + +### Code Style + +This project follows: +- **PEP 8** style guide +- 4 spaces for indentation +- 79 characters line length +- Descriptive variable and function names +- Type hints for public functions + +--- + +## 🐛 Troubleshooting + +### Plugin Not Showing in Electrum + +❌ **Problem**: The plugin doesn't appear in Electrum's plugin list + +✅ **Solutions**: +1. Verify you're using Electrum 4.0.0 or later +2. Check that the zip file contains the `bal_electrum_plugin/` directory +3. Ensure the directory structure is correct inside the zip +4. Restart Electrum after installation +5. Check Electrum logs for errors (Help → Debug → Console) + +### Locktime Not Working + +❌ **Problem**: Locktime conditions aren't being enforced + +✅ **Solutions**: +1. Verify locktime format: `3d` (days), `2y` (years), or timestamp +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 + +We welcome contributions from the community! Here's how to help: + +### Ways to Contribute + +1. **Report bugs** - Open an issue on [Gitea](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/issues) +2. **Suggest features** - Share your ideas for new functionality +3. **Write documentation** - Improve README, add examples, create tutorials +4. **Submit pull requests** - Fix bugs or add new features +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 + +This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file 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 + +- **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) +- **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**: This plugin deals with real Bitcoin transactions. Always test with small amounts first and verify all settings before using with large amounts. + +**🔒 Security**: Never share your seed phrase or private keys. This plugin only creates transactions, it doesn't store your keys.