# 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](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

```bash
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 with Bitcoin addresses and inheritance amounts
2. **Set Locktime** - Configure when transactions can be spent (timestamp or interval)
3. **Set CheckAlive** - Set health verification mechanism (interval or fixed date)
4. **Select Executor** - Choose which will-executor will handle the transaction
5. **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:

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

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

```bash
# 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

1. Copy zip to Electrum plugins directory:
   ```bash
   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

### Running Tests

```bash
# 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:

1. **Fork the repository** on Gitea
2. **Create feature branch**: `git checkout -b feature/your-feature`
3. **Add tests** for new functionality
4. **Follow PEP 8** style guide strictly
5. **Write clear commit messages** following Conventional Commits
6. **Update documentation** for new features
7. **Open Pull Request** to `main` branch

### Development Workflow

```bash
# 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](LICENSE) for details.

---

## 🔗 Links

- **Repository**: [https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin)
- **Releases**: [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](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/issues)
- **Discussions**: [https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/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.