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/
│   ├── __init__.py               # Plugin entry point
│   ├── qt.py                     # Main Qt interface
│   ├── heirs.py                  # Heir management logic
│   ├── locktime.py               # Locktime handling
│   ├── checkalive.py             # CheckAlive verification
│   ├── executor.py               # Will executor management
│   ├── dialogs/
│   │   ├── setup_wizard.py       # Main setup interface
│   │   ├── heirs_dialog.py       # Heir configuration
│   │   ├── locktime_dialog.py    # Locktime setup
│   │   ├── checkalive_dialog.py  # CheckAlive configuration
│   │   └── executor_dialog.py    # Executor selection
│   └── utils.py                  # Utility functions
├── README.md
└── LICENSE

---

🎯 Key Features

Heir Management

• 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

• 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

• 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

• 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

---

📖 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

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

# Clone repository
git clone https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin.git
cd bal-electrum-plugin

# Install in development mode
pip install -e .

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

---

🐛 Troubleshooting

Common Issues

Plugin Not Showing in Electrum

• ✅ Verify Electrum version (4.0.0+)
• ✅ Check zip contains bal_electrum_plugin/ directory
• ✅ 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

CheckAlive Not Working

• ✅ Verify CheckAlive mode (interval or fixed date)
• ✅ Ensure CheckAlive is before Locktime
• ✅ Check date calculations are correct

Heir Distribution Errors

• ✅ Verify percentages sum to 100% or amounts are valid
• ✅ Check Bitcoin addresses are valid
• ✅ Ensure no duplicate addresses

---

🤝 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

---

📜 License

MIT License - see LICENSE for details.

---

🔗 Links

• Repository: https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin
• Releases: Releases page
• Issues: Issues tracker

---

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