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

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

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