kaibot/bal-electrum-plugin
1
0
Fork 0
forked from bitcoinafterlife/bal-electrum-plugin
Code Pull Requests Activity
Files
22fa6cd708ae3969bb3bc5b32b19b158460ba18d
bal-electrum-plugin/README.md

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

  1. Download the plugin

  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

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

View Git Blame Copy Permalink