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

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

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

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

---

## 🔗 Links

- **Repository**: [https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin)
- **Releases**: [Releases page](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases)
- **Issues**: [Issues tracker](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/issues)

---

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