docs(README): Update with correct executor fee details and wallet_utils purpose

README.md

@@ -38,53 +38,26 @@ Then install using Method 1, step 2.
 
 The plugin allows users to create a **Bitcoin will** that automatically executes under specific conditions:
 
-1. **Define Heirs** - Create a list of beneficiaries
+1. **Define Heirs** - Create a list of beneficiaries with Bitcoin addresses and inheritance amounts
-2. **Set Distribution** - Specify Bitcoin addresses and inheritance amounts (percentage or fixed amount)
+2. **Set Locktime** - Configure when transactions can be spent (timestamp or interval)
-3. **Configure Locktime** - Set when transactions can be spent
+3. **Set CheckAlive** - Set health verification mechanism (interval or fixed date)
-4. **Set CheckAlive** - Configure health verification mechanism
+4. **Select Executor** - Choose which will-executor will handle the transaction
-5. **Select Executor** - Choose which will-executor will handle the transaction
+5. **Create Transaction** - Plugin generates a timelocked transaction sent to the executor
 
-### Detailed Workflow
+### Transaction Flow
 
-#### Step 1: Define Heirs
+```
-- Add multiple heirs with:
+User Setup → [Plugin Creates Transaction] → Executor Receives → 
-  - Bitcoin address (destination)
+Executor Broadcasts at Locktime → Transaction Confirmed → Heirs Receive Funds
-  - 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
+### Key Incentive
-- **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
+**Executor Fee is Included in Transaction**:
-- **Purpose**: Verify if the testator is still alive
+- The will-executor receives their fee directly in the transaction output
-- **Two modes**:
+- Fee is paid only when transaction is confirmed on the Bitcoin network
-  
+- Executor is **financially incentivized** to broadcast and confirm the transaction
-  **Interval Mode** (recommended):
+- No separate payment needed - fee is part of the timelocked transaction
-  - 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
 
 ---
 
@@ -96,14 +69,14 @@ bal-electrum-plugin/
 │   ├── __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
+│   ├── heirs.py                  # Heir management logic and validation
 │   ├── qt.py                     # Main Qt interface and GUI components
-│   ├── util.py                   # Utility functions and helpers
+│   ├── util.py                   # General utility functions
 │   ├── wallet_util/
-│   │   ├── bal_wallet_utils.py   # Wallet utility functions
+│   │   ├── bal_wallet_utils.py   # ⚠️ Advanced wallet utilities for emergency fixes
 │   │   └── bal_wallet_utils_qt.py # Qt-specific wallet utilities
-│   ├── will.py                   # Will creation and management
+│   ├── will.py                   # Will creation, locktime, and checkalive logic
-│   └── willexecutors.py          # Will executor functionality
+│   └── willexecutors.py          # Will executor management and fee handling
 ├── README.md                     # This file
 └── LICENSE                       # MIT License
 ```
@@ -119,30 +92,59 @@ bal-electrum-plugin/
 - **Flexible distribution**: Percentage-based or fixed amount
 - **Address validation**: Verify Bitcoin addresses before saving
 - **Distribution summary**: View total inheritance breakdown
+- **Percentage validation**: Ensures percentages sum to 100%
 
 ### Locktime Configuration (will.py)
-- **Timestamp format**: Unix timestamp (e.g., `1735689600`)
+- **Timestamp format**: Unix timestamp (e.g., `1735689600` for Jan 1, 2025)
 - **Interval format**: Days (`180d`) or years (`1y`)
 - **Automatic conversion**: Intervals converted to timestamps internally
 - **Validation**: Ensures locktime is in the future
+- **Flexible timing**: Set exact date or relative intervals
 
 ### CheckAlive Mechanism (will.py)
-- **Two verification modes**: Interval or fixed date
+- **Two verification modes**:
-- **Automatic validation**: Checks if testator is still alive
+  
-- **Will invalidation**: Old wills marked invalid if CheckAlive expires
+  **Interval Mode**:
-- **Flexible timing**: Configure based on your needs
+  - 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
+- **Safety mechanism**: Prevents stale wills from executing
 
 ### Will Executor System (willexecutors.py)
 - **Multiple executors**: Choose from available executors
-- **Fee structure**: Executors receive a fee for services
+- **Incentive structure**: Executor receives fee **only when transaction confirms**
+- **Transaction includes fee**: Fee is part of the timelocked transaction output
+- **Financial motivation**: Executor must broadcast to get paid
 - **Automatic transmission**: Transaction sent to executor after creation
-- **Blockchain monitoring**: Executor broadcasts at locktime
+- **Blockchain monitoring**: Executor broadcasts at locktime expiration
+
+**Executor Fee Details**:
+- Fee is specified as percentage of transaction amount or fixed amount
+- Fee is added to transaction outputs
+- Executor receives fee only when transaction confirms
+- No separate payment channel needed
+
+### Advanced Wallet Utilities (wallet_util/)
+- **⚠️ Emergency tools only**: For fixing wallet database issues
+- **Purpose**: Handle compatibility across different Electrum walletdb versions
+- **Usage**: Advanced users only, not needed for normal operation
+- **Files**:
+  - `bal_wallet_utils.py`: Core wallet database utilities
+  - `bal_wallet_utils_qt.py`: Qt-specific wallet utilities
 
 ### 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
+- **Error handling**: Clear messages for invalid inputs
 
 ---
 
@@ -152,64 +154,68 @@ bal-electrum-plugin/
 
 **Scenario**: Leave 1 BTC to three heirs after 1 year, with 180-day CheckAlive
 
-**Steps**:
+**Configuration**:
+```
+Heirs:
+- Heir 1: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq - 40% (0.4 BTC)
+- Heir 2: bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4 - 35% (0.35 BTC)
+- Heir 3: bc1ql4wk3ym38m8p3kns5w5q4tech38x58s3yy263q - 25% (0.25 BTC)
 
-1. **Add Heirs**:
+Locktime: 1y (1 year from now)
-   ```
+CheckAlive: 180d (180 days before locktime)
-   Heir 1: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq - 40% (0.4 BTC)
+Executor: "Alice Executor" (fee: 1% of total)
-   Heir 2: bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4 - 35% (0.35 BTC)
+```
-   Heir 3: bc1ql4wk3ym38m8p3kns5w5q4tech38x58s3yy263q - 25% (0.25 BTC)
-   ```
 
-2. **Set Locktime**: `1y` (1 year from now)
+**Transaction Created**:
-
+- Input: All UTXOs in wallet (1.0 BTC total)
-3. **Set CheckAlive**: `180d` (180 days before locktime)
+- Outputs:
-
-4. **Select Executor**: "Alice Executor" (fee: 0.01 BTC)
-
-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
+  - Executor fee: 0.01 BTC (1% of 1.0 BTC)
   - Network fee: 0.001 BTC
-   - Locktime: 1 year from now
+- Locktime: 1 year from creation
+- Sent to: Alice Executor's address
 
-6. **Send to Executor**: Transaction sent to Alice's address
+**Executor Incentive**:
-
+- Alice receives 0.01 BTC **only if** she broadcasts and transaction confirms
-7. **Executor Action**: Alice broadcasts transaction after 1 year
+- Alice has financial motivation to ensure transaction is confirmed
+- Transaction cannot be spent until locktime expires
 
 ### 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`)
+Locktime: 2026-06-01 (timestamp: 1748832000)
-- Heirs: 50% to heir1, 50% to heir2
+CheckAlive: 2025-12-31 (timestamp: 1767187200)
-- Executor: "Bob Executor" (fee: 0.005 BTC)
+Heirs: 50% to heir1, 50% to heir2
+Executor: "Bob Executor" (fee: 0.005 BTC fixed)
+```
 
 **Logic**:
 - If today > 2025-12-31 → Old will is invalid
 - Transaction executes on 2026-06-01
-- Executor receives fee and broadcasts
+- Bob receives 0.005 BTC only when transaction confirms
+- Bob is incentivized to broadcast at correct time
 
-### Example 3: Complex Distribution
+### Example 3: Complex Distribution with Fixed Amounts
 
 **Scenario**: Leave different fixed amounts to heirs
 
-**Heirs**:
+**Configuration**:
-- Heir 1: `bc1...` - 0.3 BTC (fixed amount)
+```
-- Heir 2: `bc1...` - 0.5 BTC (fixed amount)
+Heirs:
-- Heir 3: `bc1...` - 0.2 BTC (fixed amount)
+- 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
+Total: 1.0 BTC
-
+Locktime: 365d (1 year from now)
-**Locktime**: `365d` (1 year from now)
+CheckAlive: 180d (6 months before locktime)
-
+Executor: "Charlie Executor" (fee: 2% of total)
-**CheckAlive**: `180d` (6 months before locktime)
+```
 
 ---
 
@@ -221,9 +227,10 @@ After installation, configure in Electrum:
 
 1. Go to **Tools → Bal Electrum Plugin → Settings**
 2. Configure:
-   - **Default Locktime**: Set default locktime format
+   - **Default Locktime**: Set default locktime format (e.g., "365d")
-   - **CheckAlive Mode**: Choose interval or fixed date
+   - **CheckAlive Mode**: Choose "interval" or "fixed_date"
-   - **Executor Fee**: Set percentage or fixed fee for executors
+   - **CheckAlive Value**: Set interval (e.g., "180d") or timestamp
+   - **Executor Fee**: Set percentage (e.g., 1) or fixed amount (e.g., 0.01)
    - **Debug Mode**: Enable for troubleshooting
 
 ### Configuration File Location
@@ -240,7 +247,8 @@ After installation, configure in Electrum:
   "default_locktime": "365d",
   "checkalive_mode": "interval",
   "checkalive_value": "180d",
-  "executor_fee": 0.01,
+  "executor_fee_type": "percentage",
+  "executor_fee_value": 1.0,
   "debug": false
 }
 ```
@@ -266,6 +274,17 @@ cd bal-electrum-plugin
 zip -r bal-electrum-plugin-dev.zip bal_electrum_plugin/
 ```
 
+### Important Notes on wallet_util/
+
+**These utilities are for emergency use only**:
+
+- **Purpose**: Fix wallet database compatibility issues across Electrum versions
+- **Usage**: Only when experiencing wallet corruption or version mismatches
+- **Risk**: Advanced operations that can affect wallet data
+- **Documentation**: Limited to inline code comments
+
+**Normal operation does NOT require wallet_util/ files.**
+
 ### Install for Development
 
 1. Copy zip to Electrum plugins directory:
@@ -277,14 +296,7 @@ zip -r bal-electrum-plugin-dev.zip bal_electrum_plugin/
 
 3. Make changes to files in `bal_electrum_plugin/` directory
 
-4. Re-zip and reinstall to test:
+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
 
@@ -301,11 +313,12 @@ pytest tests/test_heirs.py -v
 
 ### Code Style
 
-- Follow PEP 8 guidelines
+- Follow PEP 8 guidelines strictly
-- Use descriptive variable names
+- Use descriptive variable and function names
 - Add type hints for public functions
 - Write comprehensive docstrings
-- Keep functions focused and small
+- Keep functions focused and small (< 50 lines)
+- Document complex logic thoroughly
 
 ---
 
@@ -314,34 +327,43 @@ pytest tests/test_heirs.py -v
 ### Common Issues
 
 #### Plugin Not Showing in Electrum
-- ✅ Verify Electrum version (4.0.0+)
+- ✅ Verify Electrum version is 4.0.0 or later
-- ✅ Check zip contains `bal_electrum_plugin/` directory
+- ✅ Check zip contains `bal_electrum_plugin/` directory at root
-- ✅ Verify directory structure inside zip
+- ✅ Verify directory structure inside zip is correct
-- ✅ Restart Electrum after installation
+- ✅ Restart Electrum completely after installation
-- ✅ Check Electrum logs (Help → Debug → Console)
+- ✅ Check Electrum logs: Help → Debug → Console
 
 #### Locktime Format Errors
-- ✅ Use valid formats: `180d`, `1y`, or Unix timestamp
+- ✅ Use valid formats: `180d`, `1y`, or Unix timestamp (e.g., `1735689600`)
-- ✅ Ensure locktime is in the future
+- ✅ Ensure locktime is in the future (after current time)
-- ✅ Check for typos in interval format (must be lowercase d/y)
+- ✅ Check for typos: lowercase `d` and `y` only
+- ✅ Verify interval calculations: `1y` = 365 days
 
 #### CheckAlive Not Working
-- ✅ Verify CheckAlive mode (interval or fixed date)
+- ✅ Verify CheckAlive mode setting (interval or fixed_date)
-- ✅ Ensure CheckAlive is before Locktime
+- ✅ Ensure CheckAlive value is before Locktime value
-- ✅ Check date calculations are correct
+- ✅ For interval mode: Check logic `locktime - interval > now`
-- ✅ Verify logic: interval mode uses `locktime - interval > now`
+- ✅ For fixed date: Verify timestamp is in the future
 
 #### Heir Distribution Errors
-- ✅ Verify percentages sum to 100% or amounts are valid
+- ✅ Verify percentages sum to exactly 100%
+- ✅ For fixed amounts: Ensure total doesn't exceed wallet balance
 - ✅ Check Bitcoin addresses are valid (use testnet for testing)
-- ✅ Ensure no duplicate addresses
+- ✅ Ensure no duplicate addresses in heir list
-- ✅ Verify fixed amounts don't exceed wallet balance
+- ✅ Verify address format: bc1... for native segwit, 1... for legacy
 
 #### Transaction Creation Fails
-- ✅ Check wallet has sufficient funds
+- ✅ Check wallet has sufficient funds (including fees)
-- ✅ Verify all heirs have valid addresses
+- ✅ Verify all heirs have valid, unique addresses
-- ✅ Ensure locktime is properly formatted
+- ✅ Ensure locktime format is correct
 - ✅ Check executor is selected and available
+- ✅ Verify executor fee is properly configured
+
+#### Executor Fee Issues
+- ✅ Fee is included in transaction output
+- ✅ Executor receives fee only when transaction confirms
+- ✅ No separate payment needed - fee is part of transaction
+- ✅ Transaction must be broadcast and confirmed for executor to get paid
 
 ---
 
@@ -349,12 +371,13 @@ pytest tests/test_heirs.py -v
 
 We welcome contributions! Please follow these guidelines:
 
-1. Fork the repository and create feature branch
+1. **Fork the repository** on Gitea
-2. Add tests for new functionality
+2. **Create feature branch**: `git checkout -b feature/your-feature`
-3. Follow PEP 8 style guide
+3. **Add tests** for new functionality
-4. Write clear commit messages
+4. **Follow PEP 8** style guide strictly
-5. Update documentation
+5. **Write clear commit messages** following Conventional Commits
-6. Open Pull Request to `main` branch
+6. **Update documentation** for new features
+7. **Open Pull Request** to `main` branch
 
 ### Development Workflow
 
@@ -371,15 +394,15 @@ git remote add upstream https://bitcoin-after.life/gitea/bitcoinafterlife/bal-el
 # Create feature branch
 git checkout -b feature/your-feature-name
 
-# Make changes
+# Make changes to bal_electrum_plugin/ files
 # ...
 
 # Test changes
 pytest tests/
 
-# Commit changes
+# Commit changes with clear message
 git add .
-git commit -m "feat: add new feature description"
+git commit -m "feat(heirs): add percentage validation for heir distribution"
 
 # Push to your fork
 git push origin feature/your-feature-name
@@ -408,4 +431,4 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 **🔒 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.
+**💡 Note**: The executor fee is included in the transaction output. The executor is financially incentivized to broadcast the transaction and ensure it confirms on the Bitcoin network.