kaibot/bal-electrum-plugin
1
0
Fork 0
forked from bitcoinafterlife/bal-electrum-plugin
Code Pull Requests Activity

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

Browse Source
This commit is contained in:
kaibot
2026-04-09 11:26:03 +00:00
parent 22fa6cd708
commit 60fc08ad5a
1 changed files with 161 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
README.md
View File

@@ -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: 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 │ ├── __init__.py # Plugin initialization and entry point
│ ├── bal.py # Main plugin logic and core functionality │ ├── bal.py # Main plugin logic and core functionality
│ ├── bal_resources.py # Resource management and asset handling │ ├── 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 │ ├── qt.py # Main Qt interface and GUI components
│ ├── util.py # Utility functions and helpers │ ├── util.py # General utility functions
│ ├── wallet_util/ │ ├── 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 │ │ └── 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 ├── README.md # This file
└── LICENSE # MIT License └── LICENSE # MIT License
``` ```
@@ -119,30 +92,59 @@ bal-electrum-plugin/
- **Flexible distribution**: Percentage-based or fixed amount - **Flexible distribution**: Percentage-based or fixed amount
- **Address validation**: Verify Bitcoin addresses before saving - **Address validation**: Verify Bitcoin addresses before saving
- **Distribution summary**: View total inheritance breakdown - **Distribution summary**: View total inheritance breakdown
- **Percentage validation**: Ensures percentages sum to 100%
### Locktime Configuration (will.py) ### 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`) - **Interval format**: Days (`180d`) or years (`1y`)
- **Automatic conversion**: Intervals converted to timestamps internally - **Automatic conversion**: Intervals converted to timestamps internally
- **Validation**: Ensures locktime is in the future - **Validation**: Ensures locktime is in the future
- **Flexible timing**: Set exact date or relative intervals
### CheckAlive Mechanism (will.py) ### 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) ### Will Executor System (willexecutors.py)
- **Multiple executors**: Choose from available executors - **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 - **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) ### Main Interface (qt.py)
- **User-friendly wizards**: Step-by-step setup interface - **User-friendly wizards**: Step-by-step setup interface
- **Real-time validation**: Immediate feedback on inputs - **Real-time validation**: Immediate feedback on inputs
- **Transaction preview**: Review before finalizing - **Transaction preview**: Review before finalizing
- **Status monitoring**: Track will execution progress - **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 **Scenario**: Leave 1 BTC to three heirs after 1 year, with 180-day CheckAlive
**Steps**: **Configuration**:
1. **Add Heirs**:
``` ```
Heir 1: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq - 40% (0.4 BTC) Heirs:
Heir 2: bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4 - 35% (0.35 BTC) - Heir 1: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq - 40% (0.4 BTC)
Heir 3: bc1ql4wk3ym38m8p3kns5w5q4tech38x58s3yy263q - 25% (0.25 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)
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: - Outputs:
- Heir 1: 0.4 BTC - Heir 1: 0.4 BTC
- Heir 2: 0.35 BTC - Heir 2: 0.35 BTC
- Heir 3: 0.25 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 - 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 ### Example 2: Fixed Date CheckAlive
**Scenario**: Leave funds with CheckAlive on specific date **Scenario**: Leave funds with CheckAlive on specific date
**Configuration**: **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**: **Logic**:
- If today > 2025-12-31 → Old will is invalid - If today > 2025-12-31 → Old will is invalid
- Transaction executes on 2026-06-01 - 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 **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** 1. Go to **Tools → Bal Electrum Plugin → Settings**
2. Configure: 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 - **Debug Mode**: Enable for troubleshooting
### Configuration File Location ### Configuration File Location
@@ -240,7 +247,8 @@ After installation, configure in Electrum:
"default_locktime": "365d", "default_locktime": "365d",
"checkalive_mode": "interval", "checkalive_mode": "interval",
"checkalive_value": "180d", "checkalive_value": "180d",
"executor_fee": 0.01, "executor_fee_type": "percentage",
"executor_fee_value": 1.0,
"debug": false "debug": false
} }
``` ```
@@ -266,6 +274,17 @@ cd bal-electrum-plugin
zip -r bal-electrum-plugin-dev.zip 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 ### Install for Development
1. Copy zip to Electrum plugins directory: 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 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 ### Running Tests
@@ -301,11 +313,12 @@ pytest tests/test_heirs.py -v
### Code Style ### 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 - Add type hints for public functions
- Write comprehensive docstrings - 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 ### Common Issues
#### Plugin Not Showing in Electrum #### 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 #### 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 #### 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 #### 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) - ✅ 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 #### 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 - ✅ 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: 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 ### Development Workflow
@@ -371,15 +394,15 @@ git remote add upstream https://bitcoin-after.life/gitea/bitcoinafterlife/bal-el
# Create feature branch # Create feature branch
git checkout -b feature/your-feature-name git checkout -b feature/your-feature-name
# Make changes # Make changes to bal_electrum_plugin/ files
# ... # ...
# Test changes # Test changes
pytest tests/ pytest tests/
# Commit changes # Commit changes with clear message
git add . 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 # Push to your fork
git push origin feature/your-feature-name 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. **🔒 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.