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
   • 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

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
• No separate payment needed - fee is part of the timelocked transaction

---

📁 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
• 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 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

---

📖 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: 1% of total)

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

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
• 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: 2% of total)

---

🔧 Configuration

Plugin Settings

After installation, configure in Electrum:

1. Go to Tools → Bal Electrum Plugin → Settings
2. Configure:
   • 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

~/.electrum/plugins/bal_electrum_plugin/config.json

Example Configuration

{
  "locktime_format": "interval",
  "default_locktime": "365d",
  "checkalive_mode": "interval",
  "checkalive_value": "180d",
  "executor_fee_type": "percentage",
  "executor_fee_value": 1.0,
  "debug": false
}

---

🛠️ Development

Prerequisites

• Electrum Bitcoin wallet (version 4.0.0 or later)
• Python 3.7+
• PyQt5
• pytest

Setup Development Environment

# 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 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:

   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 Tests

# Install test dependencies
pip install pytest

# Run all tests
pytest tests/

# Run specific test
pytest tests/test_heirs.py -v

Code Style

• 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 (< 50 lines)
• Document complex logic thoroughly

---

🐛 Troubleshooting

Common Issues

Plugin Not Showing in Electrum

• ✅ 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 (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

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

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

---

🤝 Contributing

We welcome contributions! Please follow these guidelines:

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

# Fork repository on Gitea

# Clone your fork
git clone https://bitcoin-after.life/gitea/YOUR_USERNAME/bal-electrum-plugin.git
cd bal-electrum-plugin

# Add upstream remote
git remote add upstream https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin.git

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes to bal_electrum_plugin/ files
# ...

# Test changes
pytest tests/

# Commit changes with clear message
git add .
git commit -m "feat(heirs): add percentage validation for heir distribution"

# Push to your fork
git push origin feature/your-feature-name

# Open Pull Request on Gitea

---

📜 License

MIT License - see LICENSE for details.

---

🔗 Links

• Repository: 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
• 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 included in the transaction output. The executor is financially incentivized to broadcast the transaction and ensure it confirms on the Bitcoin network.