forked from bitcoinafterlife/bal-electrum-plugin
add docs (text only)
This commit is contained in:
bot
508
docs/manual/README.md
Normal file
508
docs/manual/README.md
Normal file
@@ -0,0 +1,508 @@
|
||||
<p align="center">
|
||||
<img src="./images/logo.png" alt="BitcoinAfter.Life logo" width="120" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">BitcoinAfter.Life — BAL PROTOCOL 1.0</h1>
|
||||
<h3 align="center">USER MANUAL (revB)</h3>
|
||||
|
||||
> This is the GitHub‑friendly (HTML/Markdown + images) edition of the official
|
||||
> BAL user manual. The original PDF lives in the
|
||||
> [bal_plugin_manual](https://bitcoin-after.life/gitea/bitcoinafterlife/bal_plugin_manual)
|
||||
> Gitea repository. A styled single‑page version is available as
|
||||
> [`manual.html`](./manual.html).
|
||||
|
||||
---
|
||||
|
||||
Welcome to using **BAL**, the open‑source plugin for Electrum Wallet, dedicated
|
||||
to managing **bitcoin digital inheritance**.
|
||||
|
||||
An open‑source plugin is a software extension that adds functionality to an
|
||||
existing program, and whose source code is publicly available. This means that
|
||||
anyone can view, modify, and distribute the plugin code.
|
||||
|
||||
The plugin was designed for **Electrum**, the Gold standard of Bitcoin wallets.
|
||||
|
||||
It was not considered reasonable to proceed with the development of a new wallet
|
||||
or a fork of a wallet (a bifurcation of Electrum's code) so as not to put funds
|
||||
at risk. Instead, we thought it prudent to lean as a plugin on the most tested
|
||||
and therefore secure open‑source Bitcoin wallet (**Electrum**), trusting that in
|
||||
the future the plugin will be placed directly on Electrum by default.
|
||||
|
||||
## Installing the BAL plugin
|
||||
|
||||
The steps for installing the BAL plugin are very simple:
|
||||
|
||||
1. Install the latest version of **Electrum** (Bitcoin wallet).
|
||||
2. Install the **BAL plugin** (find the files on the Bitcoin‑after.life site or
|
||||
links on the Bitcointalk forum), copying it to the Electrum plugins folder.
|
||||
3. Activate the plugin from the Electrum menu (**Tools → Plugins → BAL**).
|
||||
4. **Restart Electrum.**
|
||||
|
||||
Now you are ready to leave your digital legacy to your heirs!
|
||||
|
||||
---
|
||||
|
||||
## The BAL interface
|
||||
|
||||
|
||||
|
||||
*Figure 1 — the screen that appears after starting Electrum with the BAL plugin
|
||||
installed.*
|
||||
|
||||
As you can see there are now two new tabs (**HEIRS** and **WILL**) on the
|
||||
Electrum interface.
|
||||
|
||||
- **HEIRS** = the screen of heirs to whom you want to leave your inheritance.
|
||||
- **WILL** = the screen that shows you the technical details of your inheritance:
|
||||
- locktime
|
||||
- creation time
|
||||
- transaction fees for miners
|
||||
- status
|
||||
- heirs
|
||||
- will‑executor with associated fees
|
||||
|
||||
> **NB:** Inheritance with the BAL plugin can also be set on a wallet that is
|
||||
> still receiving incoming transactions not yet confirmed on the blockchain.
|
||||
|
||||
---
|
||||
|
||||
## The HEIRS parameters
|
||||
|
||||
You can leave the default plugin parameters; they are more than fine for 99 % of
|
||||
inheritance cases.
|
||||
|
||||
|
||||
|
||||
*Figure 2 — the parameters on the HEIRS tab: (1) Delivery Time, (2) Check Alive,
|
||||
(3) Fees.*
|
||||
|
||||
### 1 — Delivery Time (Locktime)
|
||||
|
||||
Indicates the date on which the inheritance of your wallet on the blockchain
|
||||
will be transferred to the recipient. You can enter the inheritance date either
|
||||
as **Relative** (example: 1 year from today → `RAW = 1y`) or as a **Precise
|
||||
Date** (`Date`).
|
||||
|
||||
If you choose **Raw**, you can insert various options based on a suffix:
|
||||
|
||||
- `d`: number of days after the current day (e.g. `1d` means tomorrow)
|
||||
- `y`: number of years after the current day (e.g. `1y` means one year from today)
|
||||
|
||||
\* The locktime can be **anticipated** to update the will.
|
||||
|
||||
### 2 — Check Alive (Threshold)
|
||||
|
||||
*(i.e. check whether you are still alive, and then postpone the inheritance.)*
|
||||
|
||||
This parameter — settable as relative (`RAW`) or absolute (`DATE`) — indicates
|
||||
the time by which the inheritance will **not** be changed by postponing it.
|
||||
|
||||
> **NB:** if you set it negative (i.e. back in time) it is as if it were not
|
||||
> there. This can be useful for doing quick inheritance tests.
|
||||
|
||||
**Example:** if you set the inheritance to one year from today and the Check
|
||||
Alive (threshold) parameter to 6 months, then in 8 months — if you open
|
||||
Electrum — the BAL plugin will ask whether you want to update the inheritance
|
||||
date.
|
||||
|
||||
**Why does it do this?** Because it assumes that if you open the Electrum wallet
|
||||
with the plugin, you are still alive, and therefore estimates that you will
|
||||
still live a certain amount of time, so you probably want to postpone the
|
||||
inheritance so as not to transfer it too soon while you are still alive.
|
||||
|
||||
#### A practical example
|
||||
|
||||
Today is **January 1, 2025**. I set the inheritance for **December 1, 2025**
|
||||
(11 months from now) and the Check‑Alive (threshold) at **6 months** (so
|
||||
**June 1, 2025**):
|
||||
|
||||
**Future case histories:**
|
||||
|
||||
- **Case 1** — I no longer access the Electrum wallet: the inheritance on
|
||||
December 1, 2025 will be transferred to the heir (sent to Bitcoin nodes by the
|
||||
will‑executors).
|
||||
- **Case 2** — I access the wallet in 4 months (earlier than the set 6‑month
|
||||
Check‑Alive threshold); the inheritance will remain set for December 1, 2025.
|
||||
- **Case 3** — I access the wallet in 7 months (later than the 6 months set);
|
||||
the plugin will ask whether I want to **postpone** the date of the inheritance,
|
||||
because it assumes I am still alive and may want to postpone the inheritance so
|
||||
as not to transfer it while I am still alive.
|
||||
|
||||
### 3 — Fees
|
||||
|
||||
Denoted in **satoshi/vbyte**. This parameter indicates the fees that go to the
|
||||
**miners** to have the transaction validated on the blockchain at the time of
|
||||
inheritance. It is the classic fee/commission you pay every time you send
|
||||
bitcoin to another wallet.
|
||||
|
||||
We recommend leaving the default value of **100 sat/vbyte**; this way you will be
|
||||
sure the inheritance is accepted by the miners, even on days when the blockchain
|
||||
is saturated and network costs are high. (As of January 2025, that is roughly
|
||||
$25 USD for a wallet without too many UTXOs — a value that allows the tx to be
|
||||
placed on the blockchain even on congested days.)
|
||||
|
||||
---
|
||||
|
||||
## IMPORTANT — sizing inheritance transaction amounts
|
||||
|
||||
**Automatic sizing to 100 % of the wallet.** The plugin always makes sure that
|
||||
**ALL** the value of the wallet is delivered to the heirs.
|
||||
|
||||
- **Example:** I have a wallet with 3 BTC. I write as inheritance 1 BTC to JONNY
|
||||
and 10 % to ANDREA. The BAL plugin sends 1 BTC to Jonny and **all the rest**
|
||||
(2 BTC) to Andrea.
|
||||
- Or: I set 5 % to Jonny and 80 % to Andrea. The plugin **recalculates** the
|
||||
percentages proportionally so the wallet is completely emptied. Instead of
|
||||
5 %/80 % it sends **5.9 %** to Jonny and **94.1 %** to Andrea, for a total of
|
||||
100 %. (Otherwise 15 % would be left in the wallet.)
|
||||
|
||||
> **NB:** if you wanted to send only 80 % of the wallet to the heirs and make
|
||||
> 20 % inaccessible forever (bitcoins lost forever — increasing digital scarcity
|
||||
> and giving wealth to all bitcoin participants), just set **yourself** as an
|
||||
> heir with a percentage (e.g. 20 %) to an internal wallet address. This also
|
||||
> improves the privacy of the transaction, as it is difficult to understand the
|
||||
> destination wallets.
|
||||
|
||||
- **Another example:** I own 10 BTC and want to give Jonny exactly 4 BTC and
|
||||
Andrea exactly 2 BTC. What about the missing 4? The plugin recalculates to
|
||||
transfer 100 %. The only way to give Jonny and Andrea the exact BTC is to
|
||||
transfer the missing 4 to another wallet by designating a **third heir**.
|
||||
|
||||
---
|
||||
|
||||
## Staggered inheritance over time
|
||||
|
||||
Currently **BAL version 1.0** does not support this. It is already in development
|
||||
for **version 2** of the protocol. In version 2 it will be possible, for
|
||||
example, to stagger the inheritance 10 % per year until the tenth year, or even
|
||||
1 % per month, month by month for 10 years — as if it were a kind of annuity,
|
||||
but without the need for third parties or intermediaries.
|
||||
|
||||
---
|
||||
|
||||
## The [NEW HEIR] button
|
||||
|
||||
After setting steps 1, 2, 3, press the **[New Heir]** button and the *BAL New
|
||||
Heirs* window appears:
|
||||
|
||||
|
||||
|
||||
*Figure 3 — adding a new heir.*
|
||||
|
||||
Here you enter the following parameters:
|
||||
|
||||
- **Name:** name of the heir, with any details you prefer.
|
||||
- **Address:** the Bitcoin wallet address where the inheritance will be sent.
|
||||
- **Amount:** how much you want to send to this heir (as a **percentage** or a
|
||||
**fixed value**). The plugin always makes sure that 100 % of the inheritance
|
||||
is given to the heirs (see *Sizing inheritance transactions*).
|
||||
|
||||
> **NB:** You can add several heirs — even 10 or more.
|
||||
|
||||
---
|
||||
|
||||
## Delivery time changes
|
||||
|
||||
If you change the **Delivery Time** of a will, when Electrum closes the BAL
|
||||
plugin will notify you that you need to update the inheritance.
|
||||
|
||||
- **If you postponed the Delivery Time:** the plugin will create a transaction to
|
||||
**invalidate** the current inheritance and create a new, postponed one. To do
|
||||
this safely, the BAL plugin creates a transaction that it sends to the miners,
|
||||
which you will have to **sign**, costing **100 sat/vbyte**.
|
||||
- **If you anticipated the Delivery Time:** the plugin simply sends a new
|
||||
inheritance transaction to the **Will‑Executor servers**, which anticipates and
|
||||
thus invalidates the transactions already sent to them.
|
||||
|
||||
> 👉 For a complete, code‑accurate breakdown of every change (add/remove heir,
|
||||
> change percentages, fee, executor, date earlier/later) and whether it costs an
|
||||
> on‑chain fee, see the companion
|
||||
> [**Inheritance Options Guide**](../inheritance-options.md).
|
||||
|
||||
---
|
||||
|
||||
## RAW settings
|
||||
|
||||
If you set, for example, `RAW‑1d` and it is, say, 5 p.m., the plugin will not
|
||||
execute the inheritance precisely 24 hours later (5 p.m. the next day) but will
|
||||
roughly estimate the blockchain block number corresponding to that time — so
|
||||
with a tolerance of a few hours.
|
||||
|
||||
> **NB:** Inheritance is executed on nodes, on average, with a tolerance of about
|
||||
> 1 hour after the date/time set in the BAL plugin (because of the 11‑block
|
||||
> Bitcoin median).
|
||||
|
||||
---
|
||||
|
||||
## Heirs sheet — quick test tip
|
||||
|
||||
If you want a quick test run, enter an upcoming legacy date/time (e.g. 18 hours
|
||||
later). For such short intervals the **Check Alive** could create problems, so
|
||||
set the Check Alive parameter **in the past** (a date before today) — e.g. a
|
||||
previous month.
|
||||
|
||||
---
|
||||
|
||||
## Practical example — multiple dates
|
||||
|
||||
I have 2 children, **Peter** (12) and **Arnold** (16). I own 10 BTC and want
|
||||
each to receive 5 BTC on their respective 18th birthdays.
|
||||
|
||||
In the current BAL plugin (1.0) it is **not** possible to set different delivery
|
||||
dates — the inheritance date is unique. So in this case I prepare **two wallets**
|
||||
of 5 BTC each and set the respective inheritance with the BAL plugin. Electrum
|
||||
helps here, as it lets you easily create and manage multiple wallets.
|
||||
|
||||
---
|
||||
|
||||
## BAL plugin parameters
|
||||
|
||||
Accessible from the menu **Tools → Plugins**.
|
||||
|
||||
### Backup Transaction
|
||||
|
||||
|
||||
|
||||
*Figure 4 — the Backup Transaction option (default: Disabled).*
|
||||
|
||||
**Backup Transaction** (default *Disabled*) is used to manage the inheritance
|
||||
transaction (locktime tx) even **without** the BAL plugin automations that rely
|
||||
on the online Will‑Executor servers.
|
||||
|
||||
By enabling this option you also keep an **offline backup** of the signed legacy
|
||||
transaction, useful in case all online Will‑Executor servers are destroyed (a
|
||||
highly unrealistic event).
|
||||
|
||||
The backup transaction is saved locally — on a USB stick or wherever you prefer.
|
||||
For example, it can be delivered through a notary, trusted persons, or even
|
||||
directly to the heir. (In the latter case, however, the heir becomes aware that
|
||||
they will receive an inheritance on a specific date and amount, which could be
|
||||
imprudent.)
|
||||
|
||||
The backup transaction, once delivered to the heir, can — at a later date than
|
||||
the inheritance delivery time — be sent to the nodes via Electrum to receive the
|
||||
funds in the inheritance wallet.
|
||||
|
||||
**Difficulties and risks of using only the backup transaction** (versus trusting
|
||||
the automation of Will‑Executor servers):
|
||||
|
||||
1. Risk of the transaction being **invalidated** later if you accidentally spend
|
||||
even one satoshi from one of the wallets you pre‑signed the legacy transaction
|
||||
from.
|
||||
2. Difficulty delivering the signed transaction to the heir (the heir would learn
|
||||
about the inheritance and its value).
|
||||
3. Each step must be handled by hand, with the risk of errors.
|
||||
|
||||
If you activated *Backup Transactions* in the parameters, this is visible in the
|
||||
**[WILL]** screen with the status **NONE** in the Will‑Executor column:
|
||||
|
||||
|
||||
|
||||
*Figure 5 — backup transaction shown with "NONE" will‑executor.*
|
||||
|
||||
Then, by right‑clicking it and selecting **[Details]**, the following screen
|
||||
appears, where you can save your transaction to your preferred medium (USB flash
|
||||
drive, cloud, NAS, etc.):
|
||||
|
||||
|
||||
|
||||
*Figure 6 — transaction details / save dialog.*
|
||||
|
||||
---
|
||||
|
||||
## Wallet security — saving your will
|
||||
|
||||
To keep a copy of your will, simply save the wallet from Electrum
|
||||
(**File → Save Backup**).
|
||||
|
||||
If, for example, your notebook is stolen or breaks down, just install Electrum on
|
||||
a new computer together with the BAL plugin and open the previously saved wallet.
|
||||
|
||||
> **Remember** to save (and not lose) your wallet **password** on Electrum, or
|
||||
> you will no longer be able to access the inheritance data saved with the
|
||||
> wallet. If you restore your wallet from **SEED only**, you will regain access
|
||||
> to your bitcoin funds but **lose the BAL inheritance data** saved with the
|
||||
> wallet file.
|
||||
|
||||
You can also **export the heir list** to keep a printable copy of your
|
||||
inheritance:
|
||||
|
||||
|
||||
|
||||
*Figure 7 — exporting / printing the heir list.*
|
||||
|
||||
---
|
||||
|
||||
## Will‑Executor service list
|
||||
|
||||
This window opens from the Electrum menu, **Tools → Will‑executor**, and shows
|
||||
the official list of will‑executor servers.
|
||||
|
||||
If you want to make changes — such as adding an additional will‑executor server —
|
||||
you can enter it manually or import a list of will‑executor servers (found on the
|
||||
bitcointalk.org forum or on the official BAL website).
|
||||
|
||||
**Commands in the window:**
|
||||
|
||||
- **Ping:** checks which servers in the list are online — a **green dot** means
|
||||
active.
|
||||
- **Import:** imports a will‑executor list other than the default.
|
||||
- **Export:** exports the list of will‑executor servers in your plugin (useful to
|
||||
move it to another Electrum + BAL installation).
|
||||
- **Add:** adds a will‑executor server manually.
|
||||
|
||||
### List columns
|
||||
|
||||
1. **URL** — the URL address of the will‑executor.
|
||||
2. **Base Fee** — the commission/reward for the will‑executor. This reward lets
|
||||
the will‑executor cover the cost of keeping the server online. The
|
||||
will‑executor earns the base fee **only on the date of inheritance**, and only
|
||||
if it is the **first** to send the transaction to the nodes — which sets in
|
||||
motion a competition among will‑executors to earn the base fee. *(Example: I
|
||||
set up an inheritance that will happen in 4 years; in that case the
|
||||
will‑executor will only earn the fee in 4 years.)*
|
||||
3. **Info** — server description or website link.
|
||||
4. **Default Address** — the bitcoin wallet address where the base fee will be
|
||||
sent.
|
||||
5. **S** — server status. A **green dot** = server online.
|
||||
|
||||
**Right‑click** on a server line opens four sub‑commands:
|
||||
|
||||
|
||||
|
||||
*Figure 8 — the will‑executor context menu.*
|
||||
|
||||
1. **Select** — right‑click the server, add the green check mark on the left, and
|
||||
this will‑executor will be used in your inheritance.
|
||||
2. **Edit** — edit the relevant column field.
|
||||
3. **Ping** — verify that the server is online.
|
||||
4. **Delete** — delete the server from the list.
|
||||
|
||||
---
|
||||
|
||||
## Privacy of (online) will‑executors
|
||||
|
||||
Transactions sent to will‑executor servers (*pushed*) by the BAL plugin are
|
||||
stored on the servers. They are **not** publicly accessible (for privacy), but
|
||||
from your BAL plugin you can check at any time whether the transaction is
|
||||
properly stored on the servers: right‑click the inheritance transaction in the
|
||||
**WILL** tab and choose **Check**. The transaction will be tagged in the
|
||||
**Status** column as **Checked** if it is indeed online on the server.
|
||||
|
||||
### WILL tab columns
|
||||
|
||||
a. **Locktime** — the date of inheritance.
|
||||
b. **Txid** — identification of the bitcoin transaction.
|
||||
c. **Will‑Executor** — address of the will‑executor.
|
||||
d. **Status** — see the table below.
|
||||
|
||||
---
|
||||
|
||||
## Colour progression of transaction statuses
|
||||
|
||||
Transactions on the **WILL** page are coloured to conveniently display their
|
||||
**status** of progress. Below are the colour progression states your legacy
|
||||
transactions can have in the WILL tab, on each will‑executor that is online.
|
||||
|
||||
### Chromatic progression table
|
||||
|
||||
| # | Status | Meaning | Colour | HEX |
|
||||
|---|--------|---------|--------|-----|
|
||||
| 1 | **New** | TX new inheritance | White (transparent) | `#FFFFFF` |
|
||||
| 2 | **Signed** | TX inheritance signed into the wallet | Azure | `#2BC8ED` |
|
||||
| 3 | **Pushed** | TX sent to will‑executor | Azure‑green | `#73F3C8` |
|
||||
| 4 | **Checked** | TX actually present in the will‑executor | Bright green | `#8AFA6C` |
|
||||
| 5 | **Confirmed** | TX confirmed in the blockchain | Gray | `#BFBFBF` |
|
||||
| 6 | **Pending** | TX awaiting confirmation on blockchain | Yellow | `#FFCE30` |
|
||||
| 7 | **Failed** | Communication failure with will‑executor | Red | `#E83845` |
|
||||
| 8 | **Invalidated** | UTXO input is no longer available | Orange | `#F87838` |
|
||||
| 9 | **Replaced** | A backdated‑locktime transaction spends the same input | Violet | `#FF97E9` |
|
||||
|
||||
---
|
||||
|
||||
## WILL tab — commands
|
||||
|
||||
|
||||
|
||||
*Figure 9 — the WILL tab with its commands.*
|
||||
|
||||
1. **Prepare** — prepares the inheritance and puts it on the list.
|
||||
2. **Sign** — sign your legacy transaction with your private key (using your
|
||||
wallet password or hardware key).
|
||||
3. **Broadcast** — sends the inheritance transaction to the online Will‑Executor
|
||||
servers on your *Will‑Executor Service List*.
|
||||
4. **Display** — brings up the *Will‑Details* window, where you can see the
|
||||
transactions with all available data:
|
||||
- Locktime (date of inheritance)
|
||||
- Creation time
|
||||
- Transaction fee (to the miners)
|
||||
- Status (see table)
|
||||
- Heirs
|
||||
- Will‑executor (server address)
|
||||
- Commission (base fee) — reward for the will‑executor
|
||||
|
||||
|
||||
|
||||
*Figure 10 — the Will‑Details window (Display).*
|
||||
|
||||
> **NB:** When you close Electrum, the plugin automatically proceeds to execute
|
||||
> **Prepare → Sign → Broadcast** (if they have not already been completed) to
|
||||
> ensure the inheritance is correctly executed.
|
||||
|
||||
---
|
||||
|
||||
## Using hardware keys
|
||||
|
||||
**Ledger, BitBox2, etc.** — all hardware keys that are compatible with and
|
||||
recognised by Electrum are compatible with the BAL plugin.
|
||||
|
||||
---
|
||||
|
||||
## Insights (privacy)
|
||||
|
||||
### Caution: consolidation of UTXOs
|
||||
|
||||
When you send the entire contents of a wallet, you risk losing the privacy of
|
||||
your UTXOs. It may be a good rule of thumb to execute the inheritance leaving a
|
||||
small remainder to another wallet, to improve the privacy of the transaction —
|
||||
especially if there is only one heir.
|
||||
|
||||
> **Example:** 99.7 % inheritance to the heir and 0.3 % to a random bitcoin
|
||||
> address (e.g. taken randomly from a block explorer).
|
||||
|
||||
---
|
||||
|
||||
## Wallet inheritance behaviour when the balance / UTXO changes
|
||||
|
||||
If your wallet managed with the BAL plugin changes in balance — e.g. you send
|
||||
additional funds or spend some — the inheritance **must be updated**.
|
||||
|
||||
The BAL plugin takes care, when closing Electrum, to check whether there has been
|
||||
any such change (balance or UTXO) and then **updates the inheritance
|
||||
automatically**.
|
||||
|
||||
Thanks to this you can use an *inheritance‑ready* wallet on Electrum even for
|
||||
everyday Bitcoin transactions (possibly with a hardware key to sign), knowing
|
||||
that in case of death the entire contents of the wallet will be sent to your
|
||||
heirs.
|
||||
|
||||
If you use your **read‑only** wallet on devices other than your Electrum (using
|
||||
the public key `Zpub`/`Xpub`, e.g. to monitor funds remotely), any funds sent
|
||||
directly into the wallet **will not** be added to the inheritance already set up.
|
||||
To work around this, open your wallet on Electrum so the plugin can update the
|
||||
inheritance UTXOs and re‑send them to the will‑executors, updated with the new
|
||||
value.
|
||||
|
||||
> ⚠️ **WARNING:** If you use the same **SEED** on multiple devices (a behaviour
|
||||
> always strongly discouraged), spending even one transaction of even one satoshi
|
||||
> **invalidates** the inheritance, because it changes the wallet's UTXO structure
|
||||
> and therefore the nodes discard the inheritance transaction.
|
||||
|
||||
---
|
||||
|
||||
About installing a will‑executor server or collaboration, send your request to:
|
||||
**info@bitcoin-after.life**
|
||||
|
||||
---
|
||||
|
||||
<p align="right"><em>Signed,<br/>Svātantrya</em></p>
|
||||
Reference in New Issue
Block a user