bitcoinafterlife/bal-electrum-plugin

Fork 3

Files

kaibot 60fc08ad5a docs(README): Update with correct executor fee details and wallet_utils purpose

2026-04-09 11:26:03 +00:00

14 KiB

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)

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

Define Heirs - Create a list of beneficiaries with Bitcoin addresses and inheritance amounts
Set Locktime - Configure when transactions can be spent (timestamp or interval)
Set CheckAlive - Set health verification mechanism (interval or fixed date)
Select Executor - Choose which will-executor will handle the transaction
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:

Go to Tools → Bal Electrum Plugin → Settings
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

Copy zip to Electrum plugins directory:

cp bal-electrum-plugin-dev.zip ~/.electrum/plugins/

Install in Electrum (Tools → Plugins → Add)
Make changes to files in bal_electrum_plugin/ directory
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:

Fork the repository on Gitea
Create feature branch: git checkout -b feature/your-feature
Add tests for new functionality
Follow PEP 8 style guide strictly
Write clear commit messages following Conventional Commits
Update documentation for new features
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.

14 KiB Raw Blame History

Bal Electrum Plugin

📥 Installation

Method 1: Install from Release (Recommended)

Method 2: Install from Source

🚀 How It Works

Core Functionality

Transaction Flow

Key Incentive

📁 Plugin Structure

🎯 Key Features

Heir Management (heirs.py)

Locktime Configuration (will.py)

CheckAlive Mechanism (will.py)

Will Executor System (willexecutors.py)

Advanced Wallet Utilities (wallet_util/)

Main Interface (qt.py)

📖 Usage Examples

Example 1: Simple Inheritance Will

Example 2: Fixed Date CheckAlive

Example 3: Complex Distribution with Fixed Amounts

🔧 Configuration

Plugin Settings

Configuration File Location

Example Configuration

🛠️ Development

Prerequisites

Setup Development Environment

Important Notes on wallet_util/

Install for Development

Running Tests

Code Style

🐛 Troubleshooting

Common Issues

Plugin Not Showing in Electrum

Locktime Format Errors

CheckAlive Not Working

Heir Distribution Errors

Transaction Creation Fails

Executor Fee Issues

🤝 Contributing

Development Workflow

📜 License

🔗 Links

14 KiB

Raw Blame History