From 22fa6cd708ae3969bb3bc5b32b19b158460ba18d Mon Sep 17 00:00:00 2001 From: kaibot Date: Thu, 9 Apr 2026 11:16:38 +0000 Subject: [PATCH] docs(README): Update with correct file structure and module descriptions --- README.md | 130 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 103 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index f44a4fa..d77367b 100644 --- a/README.md +++ b/README.md @@ -92,52 +92,58 @@ The plugin allows users to create a **Bitcoin will** that automatically executes ``` bal-electrum-plugin/ -├── bal_electrum_plugin/ -│ ├── __init__.py # Plugin entry point -│ ├── qt.py # Main Qt interface +├── bal_electrum_plugin/ # Main plugin directory (what to zip) +│ ├── __init__.py # Plugin initialization and entry point +│ ├── bal.py # Main plugin logic and core functionality +│ ├── bal_resources.py # Resource management and asset handling │ ├── heirs.py # Heir management logic -│ ├── locktime.py # Locktime handling -│ ├── checkalive.py # CheckAlive verification -│ ├── executor.py # Will executor management -│ ├── dialogs/ -│ │ ├── 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 -├── README.md -└── LICENSE +│ ├── qt.py # Main Qt interface and GUI components +│ ├── util.py # Utility functions and helpers +│ ├── wallet_util/ +│ │ ├── bal_wallet_utils.py # Wallet utility functions +│ │ └── bal_wallet_utils_qt.py # Qt-specific wallet utilities +│ ├── will.py # Will creation and management +│ └── willexecutors.py # Will executor functionality +├── README.md # This file +└── LICENSE # MIT License ``` +**Important**: Only the `bal_electrum_plugin/` directory needs to be zipped for installation. + --- ## 🎯 Key Features -### Heir Management +### Heir Management (heirs.py) - **Multiple heirs**: Add unlimited beneficiaries - **Flexible distribution**: Percentage-based or fixed amount - **Address validation**: Verify Bitcoin addresses before saving - **Distribution summary**: View total inheritance breakdown -### Locktime Configuration +### Locktime Configuration (will.py) - **Timestamp format**: Unix timestamp (e.g., `1735689600`) - **Interval format**: Days (`180d`) or years (`1y`) - **Automatic conversion**: Intervals converted to timestamps internally - **Validation**: Ensures locktime is in the future -### CheckAlive Mechanism +### CheckAlive Mechanism (will.py) - **Two verification modes**: Interval or fixed date - **Automatic validation**: Checks if testator is still alive - **Will invalidation**: Old wills marked invalid if CheckAlive expires - **Flexible timing**: Configure based on your needs -### Will Executor System +### Will Executor System (willexecutors.py) - **Multiple executors**: Choose from available executors - **Fee structure**: Executors receive a fee for services - **Automatic transmission**: Transaction sent to executor after creation - **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 @@ -220,7 +226,13 @@ After installation, configure in Electrum: - **Executor Fee**: Set percentage or fixed fee for executors - **Debug Mode**: Enable for troubleshooting -### Configuration File +### Configuration File Location + +``` +~/.electrum/plugins/bal_electrum_plugin/config.json +``` + +### Example Configuration ```json { @@ -243,17 +255,37 @@ After installation, configure in Electrum: - PyQt5 - pytest -### Setup +### Setup Development Environment ```bash # Clone repository git clone https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin.git cd bal-electrum-plugin -# Install in development mode -pip install -e . +# Create development zip +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 ```bash @@ -273,6 +305,7 @@ pytest tests/test_heirs.py -v - Use descriptive variable names - Add type hints for public functions - Write comprehensive docstrings +- Keep functions focused and small --- @@ -283,23 +316,32 @@ pytest tests/test_heirs.py -v #### Plugin Not Showing in Electrum - ✅ Verify Electrum version (4.0.0+) - ✅ Check zip contains `bal_electrum_plugin/` directory +- ✅ Verify directory structure inside zip - ✅ Restart Electrum after installation - ✅ Check Electrum logs (Help → Debug → Console) #### Locktime Format Errors - ✅ Use valid formats: `180d`, `1y`, or Unix timestamp - ✅ 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 - ✅ Verify CheckAlive mode (interval or fixed date) - ✅ Ensure CheckAlive is before Locktime - ✅ Check date calculations are correct +- ✅ Verify logic: interval mode uses `locktime - interval > now` #### Heir Distribution Errors - ✅ 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 +- ✅ 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 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 @@ -325,11 +398,14 @@ MIT License - see [LICENSE](LICENSE) for details. ## 🔗 Links - **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) -- **Issues**: [Issues tracker](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/issues) +- **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**: 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. + +**📝 Note**: The plugin creates timelocked transactions that can only be spent after the locktime expires. Executors are trusted to broadcast at the correct time.