bitcoinafterlife/bal-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
steal
2026-07-24 23:32:53 -04:00
commit 968749c10d
24 changed files with 435 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
user-guide/backup-transaction.md Executable file
View File

@@ -0,0 +1,29 @@
# Backup transaction
Accessible from `Tools → Plugins` (BAL parameters).
**Backup Transaction** (default: *Disabled*) lets you keep the inheritance transaction (locktime TX) even **without** relying on the automation of the will-executor online servers.
![Backup transaction parameter](../img/fig_p06_0.png)
When enabled, you get an **offline backup of the signed legacy transaction** — useful in the (highly unrealistic) event that all will-executor servers are destroyed.
The backup can be saved locally, on a USB stick, or wherever you prefer — and delivered through a notary, trusted persons, or even directly to the heir. In the latter case, note that the heir will learn they are receiving an inheritance on a specific date and of a specific amount, which could be imprudent.
Once delivered to the heir, the backup transaction can be sent to the nodes via Electrum (on a date later than the delivery time) to receive the funds.
## Risks of relying only on the backup
1. The transaction is **invalidated** if you accidentally spend even one satoshi from the wallets whose UTXOs were pre-signed in the legacy transaction.
2. Delivering the signed transaction reveals the inheritance and its value to the heir.
3. Every step must be handled by hand, with risk of errors.
## Saving the backup
With Backup Transactions enabled, the transaction appears in the **WILL** tab with status `NONE` in the Will-Executor column.
![Backup transaction in the WILL tab](../img/fig_p07_0.png)
Right-click it, select **Details**, and save the transaction to your preferred medium (USB drive, cloud, NAS, etc.).
![Transaction details](../img/fig_p07_1.png)

7
user-guide/hardware-wallets.md Executable file
View File

@@ -0,0 +1,7 @@
# Hardware wallets
BAL works with hardware keys (Ledger, BitBox02, etc.).
**All hardware keys that are compatible with and recognized by Electrum are compatible with the BAL plugin.**
You can sign your legacy transaction with the hardware key exactly as you would a normal Electrum transaction, and keep using the inheritance-ready wallet for everyday transactions with hardware-key signing.

81
user-guide/heirs.md Executable file
View File

@@ -0,0 +1,81 @@
# Setting up heirs
The **HEIRS** tab is where you define your inheritance. It has three core parameters plus the list of heirs.
![HEIRS tab parameters](../img/fig_p03_0.png)
## 1. Delivery time (locktime)
The date on which the inheritance of your wallet will be transferred to the recipients on the blockchain.
You can enter it in two ways:
- **Raw (relative)** — a delay from today, using suffixes:
- `d` = days (`1d` = tomorrow)
- `y` = years (`1y` = one year from today)
- **Date (absolute)** — a precise date.
!!! note "Raw timing tolerance"
With Raw values the plugin estimates the blockchain block number corresponding to that time, so execution has a tolerance of a few hours. On average the inheritance is executed by nodes about **1 hour after** the set date and time (because of the 11-block Bitcoin median).
The locktime can be **anticipated** to update the will.
## 2. Check-alive (threshold)
The "are you still alive?" check. This parameter — settable as relative (Raw) or absolute (Date) — defines the time window during which the inheritance will **not** be changed by postponing it.
If you open your wallet **after** the threshold has passed, BAL asks whether you want to postpone the inheritance date: since you opened the wallet, you are evidently still alive, and you probably don't want the inheritance delivered while you're around.
**Practical example.** Today is January 1, 2025. You set the inheritance for December 1, 2025 (11 months) and the check-alive threshold at 6 months (June 1, 2025):
| Case | What happens |
|---|---|
| You never access the wallet again | On December 1, 2025 the inheritance is sent to Bitcoin nodes by the will-executors |
| You access the wallet after 4 months (before the threshold) | Inheritance stays set for December 1, 2025 |
| You access the wallet after 7 months (past the threshold) | The plugin asks if you want to postpone the inheritance date |
!!! tip "Quick testing"
Setting the check-alive to a **negative/past** value (a date before today) effectively disables it. Useful for quickly testing the plugin with a near-term delivery time (e.g., 18 hours from now).
## 3. Fees (satoshi/vbyte)
The fee that goes to the **miners** to validate the inheritance transaction on the blockchain — the classic fee you pay every time you send bitcoin.
We recommend keeping the default of **100 sat/vbyte**: it ensures the inheritance is accepted by miners even on days when the network is saturated.
## Adding heirs — the [New HEIR] button
![New heir window](../img/fig_p05_0.png)
For each heir enter:
- **Name** — name of the heir, with any details you prefer.
- **Address** — the Bitcoin address where the inheritance will be sent.
- **Amount** — how much to send, as a **percentage** or a **fixed value**.
You can add many heirs — 10 or more.
## Sizing of inheritance amounts (automatic 100%)
The plugin always makes sure that **all** the value of the wallet is delivered to the heirs.
- Wallet with 3 BTC; you assign 1 BTC to Jonny and 10% to Andrea → BAL sends 1 BTC to Jonny and **all the rest** (2 BTC) to Andrea.
- You assign 5% to Jonny and 80% to Andrea → the plugin recalculates proportionally (5.9% and 94.1%) so the wallet is completely emptied. Without recalculation, 15% would remain stuck in the wallet.
- You own 10 BTC and want to give **exactly** 4 to Jonny and 2 to Andrea → designate a third heir (e.g., another wallet of yours) to receive the remaining 4 BTC.
!!! info "Deliberate burning"
If you want to make part of your wallet inaccessible forever (increasing digital scarcity), add yourself as an heir with the desired percentage pointing to an address of your own — or an unspendable one. This also improves transaction privacy, since destination wallets are harder to interpret.
## Changing the delivery time
If you change the delivery time of a will, BAL notifies you on Electrum close that the inheritance must be updated:
- **Postponed**: the plugin creates a transaction (which you sign, cost ~100 sat/vbyte, sent to the miners) to invalidate the current inheritance, then creates the new postponed one.
- **Anticipated**: the plugin simply sends a new inheritance transaction to the will-executor servers, which anticipates and invalidates the ones already stored.
## One delivery date per wallet
In BAL 1.0 the inheritance date is **unique** per wallet. If you need different dates per heir (e.g., 5 BTC to each of two children when each turns 18), prepare **separate wallets** — Electrum makes creating and managing multiple wallets easy.
!!! info "Staggered inheritance (BAL 2.0)"
Version 1.0 does not support staggering the inheritance over time. Protocol version 2 (in development) will allow e.g. 10% per year for 10 years, or 1% per month — a kind of annuity without third parties or intermediaries.

17
user-guide/installation.md Executable file
View File

@@ -0,0 +1,17 @@
# Installation
Installing the BAL plugin takes four steps:
1. **Install the latest version of Electrum** (Bitcoin wallet) from [electrum.org](https://electrum.org).
2. **Install the BAL plugin**: download the files from the [Bitcoin-after.life](https://bitcoin-after.life) site (or via the links on the Bitcointalk forum) and copy them into the Electrum plugins folder.
3. **Activate the plugin** from the Electrum menu: `Tools → Plugins → BAL`.
4. **Restart Electrum.**
After restarting, two new tabs appear in the Electrum interface: **HEIRS** and **WILL**.
![Electrum with the BAL plugin installed](../img/fig_p02_0.png)
You are now ready to leave your digital legacy to your heirs.
!!! tip "Defaults are fine"
You can leave the default plugin parameters: they are more than fine for 99% of inheritance cases.

25
user-guide/interface.md Executable file
View File

@@ -0,0 +1,25 @@
# Interface overview
With BAL installed, Electrum shows two new tabs:
## HEIRS tab
The screen of the heirs to whom you want to leave your inheritance, together with the three core parameters: **Delivery time (locktime)**, **Check-alive (threshold)**, and **Fees**. See [Setting up heirs](heirs.md).
## WILL tab
The screen that shows the technical details of your inheritance:
| Field | Meaning |
|---|---|
| Locktime | Date of the inheritance |
| Creation time | When the inheritance transaction was created |
| Transaction fee | Fee that goes to the miners |
| Status | Progress of the transaction (see the [status table](will.md#transaction-statuses)) |
| Heirs | The configured heirs |
| Will-executor | Server address and associated base fee |
See [The WILL tab](will.md) for details.
!!! note
Inheritance with the BAL plugin can also be set on a wallet that is still receiving incoming transactions not yet confirmed on the blockchain.

12
user-guide/wallet-backup.md Executable file
View File

@@ -0,0 +1,12 @@
# Wallet backup & recovery
To have a copy of your will, simply save the wallet from Electrum: `File → Save backup`.
If your computer is stolen or breaks down, install Electrum plus the BAL plugin on a new machine and open the previously saved wallet file.
!!! warning "Do not lose your Electrum wallet password"
If you lose it, you can no longer access the inheritance data saved with the wallet file. Restoring the wallet **from seed** gives you back your bitcoin funds, but the BAL inheritance data stored in the wallet file is **lost**.
You can also **export the heirs list** for a printable copy of your inheritance.
![Exporting the heirs list](../img/fig_p08_0.png)

54
user-guide/will.md Executable file
View File

@@ -0,0 +1,54 @@
# The WILL tab
The **WILL** tab shows your inheritance transactions and their progress on each will-executor.
![WILL tab](../img/fig_p11_0.png)
## Columns
| Column | Meaning |
|---|---|
| Locktime | The date of the inheritance |
| Txid | Identifier of the Bitcoin transaction |
| Will-Executor | Address of the will-executor |
| Status | Progress of the transaction (see below) |
## Commands
1. **Prepare** — prepares the inheritance and puts it on the list.
2. **Sign** — signs your legacy transaction with your private key (wallet password or hardware key).
3. **Broadcast** — sends the inheritance transaction to the online will-executor servers in your [service list](../will-executor/service-list.md).
4. **Display** — opens the *Will-Details* window with all available data: locktime, creation time, transaction fee (miners), status, heirs, will-executor address, and the will-executor's base fee.
!!! note "Automatic execution on close"
When you close Electrum, the plugin automatically runs **Prepare → Sign → Broadcast** for any step not yet completed, to ensure the inheritance is correctly executed.
## Checking storage on servers
Transactions pushed to will-executor servers are stored there, but are **not publicly accessible** (for privacy). You can verify at any time that your transaction is properly stored: right-click the inheritance transaction in the WILL tab and select **Check**. If it is online on the server, its status becomes `Checked`.
## Transaction statuses
Transactions in the WILL tab are color-coded by status:
| # | Status | Meaning | Color | HEX |
|---|---|---|---|---|
| 1 | New | New inheritance TX | White (transparent) | `#FFFFFF` |
| 2 | Signed | TX signed in the wallet | Azure | `#2BC8ED` |
| 3 | Pushed | TX sent to will-executor | Azure-green | `#73F3C8` |
| 4 | Checked | TX actually present on the will-executor | Bright green | `#8AFA6C` |
| 5 | Confirmed | TX confirmed on the blockchain | Gray | `#BFBFBF` |
| 6 | Pending | TX awaiting confirmation on the blockchain | Yellow | `#FFCE30` |
| 7 | Failed | Communication failure with the will-executor | Red | `#E83845` |
| 8 | Invalidated | A UTXO input is no longer available | Orange | `#F87838` |
| 9 | Replaced | A backdated-locktime transaction spends the same input | Violet | `#FF97E9` |
## Behavior when the wallet balance or UTXOs change
If the balance or UTXO set of your BAL-managed wallet changes (you receive or spend funds), the inheritance must be updated. **BAL checks this automatically when Electrum closes** and updates the inheritance if needed.
This means you can use an inheritance-ready wallet for everyday Bitcoin transactions (ideally signing with a hardware key), knowing the entire wallet content will go to your heirs.
!!! warning "Read-only wallets and shared seeds"
- If you receive funds on this wallet via a **read-only copy** on another device (Zpub/Xpub), those funds are **not** added to the inheritance until you open the wallet in Electrum with BAL, so the plugin can update the UTXOs and re-send the will to the executors.
- If you use the **same seed on multiple devices** (strongly discouraged), spending even one satoshi elsewhere **invalidates the inheritance**: the UTXO structure changes and nodes discard the inheritance transaction.