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

336 lines
9.4 KiB
Markdown
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**
- 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.
View Git Blame Copy Permalink