kaibot/bal-electrum-plugin
1
0
Fork 0
forked from bitcoinafterlife/bal-electrum-plugin
Code Pull Requests Activity
Files
2abc99c38f07466b372fd8ebd2c1aaf7d3e63188
bal-electrum-plugin/README.md

358 lines
12 KiB
Markdown
Raw Blame History

# Bal Electrum Plugin
⚡ **Bitcoin Electrum plugin for managing heir inheritance with locktime-based will execution**
---
## 📥 Installation
### Method 1: Install from Release (Recommended)
1. **Download the plugin**
- Go to: [https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases)
- Download the latest `bal-electrum-plugin-vX.X.X.zip` file
2. **Install in Electrum**
- Open Electrum Bitcoin wallet
- Go to **Tools → Plugins**
- Click **Add**
- Select the downloaded `.zip` file
- Click **Open** or **Install**
- Restart Electrum if required
### Method 2: Install from Source
```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/
```
Then install using Method 1, step 2.
---
## 🚀 How It Works
### Core Functionality
The plugin allows users to create a **Bitcoin will** that automatically executes under specific conditions:
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
### Transaction Flow
```
User Setup → [Plugin Creates Transaction] → Executor Receives →
Executor Broadcasts at Locktime → Transaction Confirmed → Heirs Receive Funds
```
### Key Incentive
**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
- Fee is a **fixed amount only** (no percentage option)
---
## 📁 Plugin Structure
```
bal-electrum-plugin/
├── bal_electrum_plugin/ # Main plugin directory (what to zip)
│ ├── __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 and validation
│ ├── qt.py # Main Qt interface and GUI components
│ ├── util.py # General utility functions
│ ├── wallet_util/
│ │ ├── bal_wallet_utils.py # ⚠️ Advanced wallet utilities for emergency fixes
│ │ └── bal_wallet_utils_qt.py # Qt-specific wallet utilities
│ ├── will.py # Will creation, locktime, and checkalive logic
│ └── willexecutors.py # Will executor management and fee handling
├── README.md # This file
└── LICENSE # MIT License
```
**Important**: Only the `bal_electrum_plugin/` directory needs to be zipped for installation.
---
## 🎯 Key Features
### Heir Management (heirs.py)
- **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
- **Percentage validation**: Ensures percentages sum to 100%
### Locktime Configuration (will.py)
- **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 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
- **Fixed fee only**: Executor receives a fixed BTC amount (no percentage option)
- **Fee included in transaction**: 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 expiration
**Executor Fee Details**:
- Fee is specified as fixed BTC amount only
- 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, requires manual installation
- **Installation Steps**:
1. Copy `wallet_util/` files to Electrum's plugin directory
2. Load Electrum's virtualenv
3. Run `./bal_wallet_utils_qt.py`
- **Risk**: Advanced operations that can affect wallet data
- **Documentation**: Limited to inline code comments
**Normal operation does NOT require wallet_util/ files.**
### 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
---
## 📖 Usage Examples
### Example 1: Simple Inheritance Will
**Scenario**: Leave 1 BTC to three heirs after 1 year, with 180-day CheckAlive
**Configuration**:
```
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: 0.01 BTC fixed)
```
**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 (fixed amount)
- Network fee: 0.001 BTC
- Locktime: 1 year from creation
- Sent to: Alice Executor's address
**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 fixed)
```
**Logic**:
- If today > 2025-12-31 → Old will is invalid
- If old will is invalid, a non-timelocked transaction is sent onchain to invalidate the old will
- Transaction executes on 2026-06-01
- Bob receives 0.005 BTC only when transaction confirms
- Bob is incentivized to broadcast at correct time
### Example 3: Complex Distribution with Fixed Amounts
**Scenario**: Leave different fixed amounts to heirs
**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)
Executor: "Charlie Executor" (fee: 0.02 BTC fixed)
```
---
## 🛠️ Development
### Prerequisites
- Electrum Bitcoin wallet
### Setup Development Environment
```bash
# 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/
```
### Important Notes on wallet_util/
**These utilities require manual installation**:
- **Purpose**: Fix wallet database compatibility issues across Electrum versions
- **Usage**: Only when experiencing wallet corruption or version mismatches
- **Installation Steps**:
1. Copy `wallet_util/` files to Electrum's plugin directory
2. Load Electrum's virtualenv
3. Run `./bal_wallet_utils_qt.py`
- **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:
```bash
cp bal-electrum-plugin-dev.zip ~/.electrum/plugins/
```
2. Install in Electrum (Tools → Plugins → Add)
3. Make changes to files in `bal_electrum_plugin/` directory
4. Re-zip and reinstall to test
### Running the Plugin
The plugin uses Electrum's existing virtualenv.
---
## 🐛 Troubleshooting
### Common Issues
#### Plugin Not Showing in Electrum
- ✅ 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 (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 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
- ✅ If CheckAlive expires, old will is invalidated by sending a non-timelocked transaction onchain
#### Heir Distribution Errors
- ✅ 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 in heir list
- ✅ Verify address format: bc1... for native segwit, 1... for legacy
#### Transaction Creation Fails
- ✅ 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 (fixed amount only)
#### Executor Fee Issues
- ✅ Fee is a fixed BTC amount only (no percentage option)
- ✅ Fee is included in transaction output
- ✅ Executor receives fee only when transaction confirms
- ✅ Transaction must be broadcast and confirmed for executor to get paid
#### wallet_util/ Not Working
- ✅ Copy files to Electrum's plugin directory
- ✅ Load Electrum's virtualenv before using
- ✅ Run `./bal_wallet_utils_qt.py`
- ✅ Only use for emergency wallet fixes
- ✅ Backup wallet before using wallet utilities
---
## 🤝 Contributing
Thanks for considering contributing!
---
## 📜 License
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.like/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)
---
**⚠️ 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.
**💡 Note**: The executor fee is a fixed BTC amount included in the transaction output. The executor is financially incentivized to broadcast the transaction and ensure it confirms on the Bitcoin network.
View Git Blame Copy Permalink