docs(README): Update with correct file structure and module descriptions

2026-04-09 11:16:38 +00:00
parent b63dc5ba4f
commit 22fa6cd708
1 changed files with 103 additions and 27 deletions
--- a/README.md
+++ b/README.md
@@ -92,52 +92,58 @@ The plugin allows users to create a **Bitcoin will** that automatically executes

 ```
 bal-electrum-plugin/
-├── bal_electrum_plugin/
-│   ├── __init__.py               # Plugin entry point
-│   ├── qt.py                     # Main Qt interface
+├── 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
-│   ├── 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
+│   ├── 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
+### 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
+### 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
+### 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
+### 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
@@ -220,7 +226,13 @@ After installation, configure in Electrum:
   - **Executor Fee**: Set percentage or fixed fee for executors
   - **Debug Mode**: Enable for troubleshooting

-### Configuration File
+### Configuration File Location
+
+```
+~/.electrum/plugins/bal_electrum_plugin/config.json
+```
+
+### Example Configuration

 ```json
 {
@@ -243,17 +255,37 @@ After installation, configure in Electrum:
 - PyQt5
 - pytest

-### Setup
+### Setup Development Environment

 ```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 .
+# 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
@@ -273,6 +305,7 @@ pytest tests/test_heirs.py -v
 - Use descriptive variable names
 - Add type hints for public functions
 - Write comprehensive docstrings
+- Keep functions focused and small

 ---

@@ -283,23 +316,32 @@ pytest tests/test_heirs.py -v
 #### 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
+- ✅ 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
+- ✅ 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

 ---

@@ -314,6 +356,37 @@ We welcome contributions! Please follow these guidelines:
 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
@@ -325,11 +398,14 @@ 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)
+- **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.