From b63dc5ba4f75defd34b4eac1a55b90d2655557df Mon Sep 17 00:00:00 2001
From: kaibot <kaibot@bitcoin-after.life>
Date: Thu, 9 Apr 2026 11:06:08 +0000
Subject: [PATCH] docs(README): Update with accurate plugin functionality
 description

---
 README.md | 522 ++++++++++++++++++++++--------------------------------
 1 file changed, 207 insertions(+), 315 deletions(-)

diff --git a/README.md b/README.md
index 06f7eeb..f44a4fa 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,6 @@
 # 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
+⚡ **Bitcoin Electrum plugin for managing heir inheritance with locktime-based will execution**
 
 ---
 
@@ -28,56 +22,69 @@ This plugin extends Electrum wallet to support:
 
 ### 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
-   ```
+```bash
+git clone https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin.git
+cd bal-electrum-plugin
+zip -r bal-electrum-plugin.zip 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)
+Then install using Method 1, step 2.
 
 ---
 
-## 🚀 Quick Start
+## 🚀 How It Works
 
-### 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
+### Core Functionality
 
-### 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
+The plugin allows users to create a **Bitcoin will** that automatically executes under specific conditions:
 
-### 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
+1. **Define Heirs** - Create a list of beneficiaries
+2. **Set Distribution** - Specify Bitcoin addresses and inheritance amounts (percentage or fixed amount)
+3. **Configure Locktime** - Set when transactions can be spent
+4. **Set CheckAlive** - Configure health verification mechanism
+5. **Select Executor** - Choose which will-executor will handle the transaction
 
-### 4. Verify Heir Distribution
-- Go to **Tools → Bal Electrum Plugin → View Heirs**
-- Check the distribution summary
-- Verify all percentages sum to 100%
+### Detailed Workflow
+
+#### Step 1: Define Heirs
+- 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/          # Main plugin code (what you zip)
+├── bal_electrum_plugin/
 │   ├── __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
+│   ├── 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                     # 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
+├── README.md
+└── LICENSE
 ```
 
 ---
@@ -134,79 +115,124 @@ 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
+- **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 Transactions
-✅ **Absolute Locktime** - Transaction can only be spent after a specific:
-   - Block height (e.g., `700000`)
-   - Timestamp (Unix timestamp, e.g., `1609459200`)
+### Locktime Configuration
+- **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
 
-✅ **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)
+### CheckAlive Mechanism
+- **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
 
-✅ **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
+### Will Executor System
+- **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
 
 ---
 
 ## 📖 Usage Examples
 
-### Example 1: Simple Heir Setup
+### Example 1: Simple Inheritance Will
 
-1. **Add an heir**:
-   - Address: `bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq`
-   - Percentage: `50%`
-   - Locktime: `1y` (1 year from now)
+**Scenario**: Leave 1 BTC to three heirs after 1 year, with 180-day CheckAlive
 
-2. **Add second heir**:
-   - Address: `bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4`
-   - Percentage: `50%`
-   - Locktime: `2y` (2 years from now)
+**Steps**:
 
-3. **Create transaction**:
-   - Send 0.5 BTC to heir1 after 1 year
-   - Send 0.5 BTC to heir2 after 2 years
+1. **Add Heirs**:
+   ```
+   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
-# Create a transaction that can only be spent after 6 months
-from bal_electrum_plugin.locktime import Locktime
+3. **Set CheckAlive**: `180d` (180 days before locktime)
 
-locktime = Locktime(
-    type="relative",
-    value="6m",  # 6 months from now
-    unit="blocks"  # or "seconds"
-)
+4. **Select Executor**: "Alice Executor" (fee: 0.01 BTC)
 
-# This transaction will be locked for 6 months
-tx = create_transaction(
-    recipients=[recipient_address],
-    amount=0.1,
-    locktime=locktime
-)
+5. **Create Transaction**:
+   - Input: All UTXOs in wallet
+   - Outputs:
+     - Heir 1: 0.4 BTC
+     - 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
@@ -215,39 +241,19 @@ Total: 100% distributed over 3 years
 - Electrum Bitcoin wallet (version 4.0.0 or later)
 - Python 3.7+
 - PyQt5
-- pytest (for testing)
+- pytest
 
-### Setup Development Environment
+### Setup
 
 ```bash
-# Clone the repository
+# Clone 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 in development mode
+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
 
 ```bash
@@ -263,181 +269,67 @@ 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
+- Follow PEP 8 guidelines
+- Use descriptive variable names
+- Add type hints for public functions
+- Write comprehensive docstrings
 
 ---
 
 ## 🐛 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**:
-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 Format Errors
+- ✅ Use valid formats: `180d`, `1y`, or Unix timestamp
+- ✅ Ensure locktime is in the future
+- ✅ Check for typos in interval format
 
-### 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
-
-✅ **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 |
+#### Heir Distribution Errors
+- ✅ Verify percentages sum to 100% or amounts are valid
+- ✅ Check Bitcoin addresses are valid
+- ✅ Ensure no duplicate addresses
 
 ---
 
 ## 🤝 Contributing
 
-We welcome contributions from the community! Here's how to help:
+We welcome contributions! Please follow these guidelines:
 
-### 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
-```
+1. Fork the repository and create feature branch
+2. Add tests for new functionality
+3. Follow PEP 8 style guide
+4. Write clear commit messages
+5. Update documentation
+6. Open Pull Request to `main` branch
 
 ---
 
 ## 📜 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 |
+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**: [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)
+- **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)
 
 ---
 
-**⚠️ 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.