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

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.