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

Detailed Workflow

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

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

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

---

📁 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
│   ├── qt.py                     # Main Qt interface and GUI components
│   ├── util.py                   # Utility functions and helpers
│   ├── wallet_util/
│   │   ├── bal_wallet_utils.py   # Wallet utility functions
│   │   └── bal_wallet_utils_qt.py # Qt-specific wallet utilities
│   ├── will.py                   # Will creation and management
│   └── willexecutors.py          # Will executor functionality
├── 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

Locktime Configuration (will.py)

• Timestamp format: Unix timestamp (e.g., 1735689600)
• Interval format: Days (180d) or years (1y)
• Automatic conversion: Intervals converted to timestamps internally
• Validation: Ensures locktime is in the future

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

Will Executor System (willexecutors.py)

• Multiple executors: Choose from available executors
• Fee structure: Executors receive a fee for services
• Automatic transmission: Transaction sent to executor after creation
• Blockchain monitoring: Executor broadcasts at locktime

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

---

📖 Usage Examples

Example 1: Simple Inheritance Will

Scenario: Leave 1 BTC to three heirs after 1 year, with 180-day CheckAlive

Steps:

1. Add Heirs:

   Heir 1: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq - 40% (0.4 BTC)
   Heir 2: bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4 - 35% (0.35 BTC)
   Heir 3: bc1ql4wk3ym38m8p3kns5w5q4tech38x58s3yy263q - 25% (0.25 BTC)
   

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:
     • Heir 1: 0.4 BTC
     • Heir 2: 0.35 BTC
     • Heir 3: 0.25 BTC
     • Executor fee: 0.01 BTC
     • Network fee: 0.001 BTC
   • Locktime: 1 year from now

6. Send to Executor: Transaction sent to Alice's address

7. Executor Action: Alice broadcasts transaction after 1 year

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)

Logic:

• If today > 2025-12-31 → Old will is invalid
• Transaction executes on 2026-06-01
• Executor receives fee and broadcasts

Example 3: Complex Distribution

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)

Total: 1.0 BTC

Locktime: 365d (1 year from now)

CheckAlive: 180d (6 months before locktime)

---

🔧 Configuration

Plugin Settings

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
   • 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": 0.01,
  "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/

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:

   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

# 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
• Use descriptive variable names
• Add type hints for public functions
• Write comprehensive docstrings
• Keep functions focused and small

---

🐛 Troubleshooting

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)

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)

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

Heir Distribution Errors

• ✅ Verify percentages sum to 100% or amounts are valid
• ✅ Check Bitcoin addresses are valid (use testnet for testing)
• ✅ Ensure no duplicate addresses
• ✅ Verify fixed amounts don't exceed wallet balance

Transaction Creation Fails

• ✅ Check wallet has sufficient funds
• ✅ Verify all heirs have valid addresses
• ✅ Ensure locktime is properly formatted
• ✅ Check executor is selected and available

---

🤝 Contributing

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

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

# Test changes
pytest tests/

# Commit changes
git add .
git commit -m "feat: add new feature description"

# 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 plugin creates timelocked transactions that can only be spent after the locktime expires. Executors are trusted to broadcast at the correct time.