bitcoinafterlife/bal-electrum-plugin
1
1
Fork 3
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity
Files
22fa6cd708ae3969bb3bc5b32b19b158460ba18d
bal-electrum-plugin/README.md

412 lines
12 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/ # 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
```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 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/
```
### 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:
```bash
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
```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
- 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
```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
# ...
# 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](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 plugin creates timelocked transactions that can only be spent after the locktime expires. Executors are trusted to broadcast at the correct time.
Reference in New Issue View Git Blame Copy Permalink