From 60fc08ad5aeb06e4c0a236335c14b56426a748dc Mon Sep 17 00:00:00 2001 From: kaibot Date: Thu, 9 Apr 2026 11:26:03 +0000 Subject: [PATCH] docs(README): Update with correct executor fee details and wallet_utils purpose --- README.md | 299 +++++++++++++++++++++++++++++------------------------- 1 file changed, 161 insertions(+), 138 deletions(-) diff --git a/README.md b/README.md index d77367b..34b50c5 100644 --- a/README.md +++ b/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 -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 +1. **Define Heirs** - Create a list of beneficiaries with Bitcoin addresses and inheritance amounts +2. **Set Locktime** - Configure when transactions can be spent (timestamp or interval) +3. **Set CheckAlive** - Set health verification mechanism (interval or fixed date) +4. **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: - - 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 +``` +User Setup → [Plugin Creates Transaction] → Executor Receives → +Executor Broadcasts at Locktime → Transaction Confirmed → Heirs Receive Funds +``` -#### 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 +### Key Incentive -#### 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 +**Executor Fee is Included in Transaction**: +- The will-executor receives their fee directly in the transaction output +- Fee is paid only when transaction is confirmed on the Bitcoin network +- Executor is **financially incentivized** to broadcast and confirm the transaction +- No separate payment needed - fee is part of the timelocked transaction --- @@ -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 -│ └── willexecutors.py # Will executor functionality +│ ├── will.py # Will creation, locktime, and checkalive logic +│ └── 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 -- **Automatic validation**: Checks if testator is still alive -- **Will invalidation**: Old wills marked invalid if CheckAlive expires -- **Flexible timing**: Configure based on your needs +- **Two verification modes**: + + **Interval Mode**: + - 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**: - ``` - Heir 1: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq - 40% (0.4 BTC) - Heir 2: bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4 - 35% (0.35 BTC) - Heir 3: bc1ql4wk3ym38m8p3kns5w5q4tech38x58s3yy263q - 25% (0.25 BTC) - ``` +Locktime: 1y (1 year from now) +CheckAlive: 180d (180 days before locktime) +Executor: "Alice Executor" (fee: 1% of total) +``` -2. **Set Locktime**: `1y` (1 year from now) +**Transaction Created**: +- Input: All UTXOs in wallet (1.0 BTC total) +- Outputs: + - Heir 1: 0.4 BTC + - Heir 2: 0.35 BTC + - Heir 3: 0.25 BTC + - Executor fee: 0.01 BTC (1% of 1.0 BTC) + - Network fee: 0.001 BTC +- Locktime: 1 year from creation +- Sent to: Alice Executor's address -3. **Set CheckAlive**: `180d` (180 days before locktime) - -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 - - 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 +**Executor Incentive**: +- Alice receives 0.01 BTC **only if** she broadcasts and transaction confirms +- 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`) -- Heirs: 50% to heir1, 50% to heir2 -- Executor: "Bob Executor" (fee: 0.005 BTC) +``` +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 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**: -- Heir 1: `bc1...` - 0.3 BTC (fixed amount) -- Heir 2: `bc1...` - 0.5 BTC (fixed amount) -- Heir 3: `bc1...` - 0.2 BTC (fixed amount) +**Configuration**: +``` +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) +Total: 1.0 BTC +Locktime: 365d (1 year from now) +CheckAlive: 180d (6 months before locktime) +Executor: "Charlie Executor" (fee: 2% of total) +``` --- @@ -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 - - **CheckAlive Mode**: Choose interval or fixed date - - **Executor Fee**: Set percentage or fixed fee for executors + - **Default Locktime**: Set default locktime format (e.g., "365d") + - **CheckAlive Mode**: Choose "interval" or "fixed_date" + - **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: - ```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 - ``` +4. Re-zip and reinstall to test ### Running Tests @@ -301,11 +313,12 @@ pytest tests/test_heirs.py -v ### Code Style -- Follow PEP 8 guidelines -- Use descriptive variable names +- Follow PEP 8 guidelines strictly +- 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+) -- ✅ Check zip contains `bal_electrum_plugin/` directory -- ✅ Verify directory structure inside zip -- ✅ Restart Electrum after installation -- ✅ Check Electrum logs (Help → Debug → Console) +- ✅ Verify Electrum version is 4.0.0 or later +- ✅ Check zip contains `bal_electrum_plugin/` directory at root +- ✅ Verify directory structure inside zip is correct +- ✅ Restart Electrum completely 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 (must be lowercase d/y) +- ✅ Use valid formats: `180d`, `1y`, or Unix timestamp (e.g., `1735689600`) +- ✅ Ensure locktime is in the future (after current time) +- ✅ Check for typos: lowercase `d` and `y` only +- ✅ Verify interval calculations: `1y` = 365 days #### 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` +- ✅ Verify CheckAlive mode setting (interval or fixed_date) +- ✅ Ensure CheckAlive value is before Locktime value +- ✅ For interval mode: Check logic `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 -- ✅ Verify fixed amounts don't exceed wallet balance +- ✅ Ensure no duplicate addresses in heir list +- ✅ Verify address format: bc1... for native segwit, 1... for legacy #### Transaction Creation Fails -- ✅ Check wallet has sufficient funds -- ✅ Verify all heirs have valid addresses -- ✅ Ensure locktime is properly formatted +- ✅ Check wallet has sufficient funds (including fees) +- ✅ Verify all heirs have valid, unique addresses +- ✅ 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 -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 +1. **Fork the repository** on Gitea +2. **Create feature branch**: `git checkout -b feature/your-feature` +3. **Add tests** for new functionality +4. **Follow PEP 8** style guide strictly +5. **Write clear commit messages** following Conventional Commits +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.