kaibot/bal-electrum-plugin

Fork 0

forked from bitcoinafterlife/bal-electrum-plugin

Files

kaibot b63dc5ba4f docs(README): Update with accurate plugin functionality description

2026-04-09 11:06:08 +00:00

9.4 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
Set Distribution - Specify Bitcoin addresses and inheritance amounts (percentage or fixed amount)
Configure Locktime - Set when transactions can be spent
Set CheckAlive - Configure health verification mechanism
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:

Add Heirs:

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

Set Locktime: 1y (1 year from now)
Set CheckAlive: 180d (180 days before locktime)
Select Executor: "Alice Executor" (fee: 0.01 BTC)
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
Send to Executor: Transaction sent to Alice's address
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:

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

Fork the repository and create feature branch
Add tests for new functionality
Follow PEP 8 style guide
Write clear commit messages
Update documentation
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.

9.4 KiB Raw Blame History