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

291
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:
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)
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:
**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
- 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
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.