diff --git a/docs/inheritance-options.html b/docs/inheritance-options.html new file mode 100644 index 0000000..2265429 --- /dev/null +++ b/docs/inheritance-options.html @@ -0,0 +1,267 @@ + + + + + +BAL — Inheritance Options Guide + + + +
+ +

BAL — Inheritance Options Guide

+

How the Bitcoin After Life Electrum plugin reacts to every change you can make to +your will: changing the date (earlier / later), adding or removing an heir, changing percentages, fees or +will‑executors — and what happens to the transactions held by the will‑executor servers.

+ +
This page reflects the actual behaviour of the code +(core/will.py → is_will_valid / check_willexecutors_and_heirs and +gui/qt/window.py → build_inheritance_transaction). It is meant for end users and +for anyone wanting to understand the on‑chain consequences of each action.
+ +

1. The mental model in one paragraph

+

Your will is a tree of pre‑signed Bitcoin transactions. Each leaf transaction sends your +coins to your heirs and is time‑locked (nLockTime) so it can only be broadcast +after a future date/block. A copy of each signed transaction is handed to one or more +will‑executor servers. While you are alive you periodically prove you are alive (the +Check‑Alive threshold). When you change anything, BAL chooses between three outcomes:

+
    +
  1. Do nothing — the will is still coherent.
    2. +
  2. Rebuild (re‑prepare + re‑sign, no on‑chain cost) — the will changed but + nothing dangerous is committed yet.
    3. +
  3. Invalidate on‑chain first (costs a real Bitcoin fee) — a previously + signed/sent transaction must be neutralised by spending its inputs before a + new will can safely replace it.
    4. +
+
The whole point of rule 3 is safety: a will‑executor must never be able to broadcast an old +transaction that would execute your inheritance too early.
+ +

2. Transaction states (status flags)

+ + + + + + + + + + + + + + + +
StatusMeaningSet when
VALIDThe current, usable plandefault; cleared by INVALIDATED/REPLACED/CONFIRMED/PENDING
COMPLETE (Signed)The transaction has been signedafter Sign
PUSHEDSigned tx sent to executor(s)after Broadcast to executors
CHECKEDExecutor confirmed it holds the txafter a successful server Check (implies PUSHED)
CHECK_FAILServer check faileda queried executor did not return the tx
PUSH_FAILSending to the executor failedcleared when PUSHED becomes true
CONFIRMEDTx mined on‑chainseen on‑chain, height > 0
PENDINGTx in the mempoolseen on‑chain, height 0
INVALIDATEDInputs spent → can never confirminvalidation tx / inputs gone
REPLACEDSuperseded by an earlier‑locktime childa replacing child found
EXPIREDLocktime already in the past vs the check datecheck_will_expired
+ +

Safety rules baked into set_status

+ + +

How states map to row colour

+ + + + + + + + + +
State (first match wins)ColourHex
CHECK_FAILred#e83845
INVALIDATED / REPLACEDgreymuted
CONFIRMEDgreenconfirmed
COMPLETE (signed, not pushed)blue#2bc8ed
VALID (prepared, not signed)default—
+
v0.3.3 fix: a will that is signed but not yet broadcast +(COMPLETE and not PUSHED) is not queried on the +server, so it stays blue instead of turning red. Only PUSHED wills are checked.
+ +

3. The decision flow

+

On Prepare (or the periodic Check, or on Electrum close) BAL runs +is_will_valid, raises a specific exception, and each maps to one action:

+ +
+flowchart TD
+    A([You change something & press Prepare / Check]) --> B{Heirs defined?}
+    B -- No --> Z1[/Show: Heirs are not defined — stop/]
+    B -- Yes --> C{Check-Alive threshold in the future?}
+    C -- "No, it's in the past" --> INV1[[Invalidate on-chain
CheckAliveError]]
+    C -- Yes --> D{Any VALID tx with locktime earlier than the new date?}
+
+    D -- "Yes you moved the date EARLIER / anticipate" --> E{Was that tx already signed or sent?}
+    E -- "Not signed yet" --> R1[[Rebuild only
no on-chain cost]]
+    E -- "Signed / sent" --> INV2[[Invalidate on-chain FIRST
WillExpired]]
+
+    D -- No --> F{Will-executor / fee / heirs unchanged?}
+    F -- "Fee changed" --> R2[[Rebuild
TxFeesChanged]]
+    F -- "Will-executor changed/absent" --> R3[[Rebuild
WillExecutorNotPresent / Change]]
+    F -- "Heir added/removed, % or address changed" --> G{POSTPONE of an already signed/sent tx?}
+
+    G -- "Yes date later + signed/sent" --> INV3[[Invalidate on-chain FIRST then rebuild
WillPostponed]]
+    G -- "No never signed, or pure heir/% change" --> R4[[Rebuild only
HeirNotFound / HeirChange]]
+
+    F -- "Nothing changed" --> OK([Will still coherent — do nothing])
+
+    R1 --> SIGN
+    R2 --> SIGN
+    R3 --> SIGN
+    R4 --> SIGN
+    SIGN([Re-sign the new transactions]) --> PUSH([Broadcast to will-executors])
+
+    INV1 --> SB
+    INV2 --> SB
+    INV3 --> SB
+    SB([Sign & broadcast the INVALIDATION tx on-chain]) --> WAIT{Invalidation confirmed?}
+    WAIT -- Yes --> REBUILD([Press Prepare again → build the new will])
+    REBUILD --> SIGN
+
+ +

4. Every option, explained

+ +

4.1 Changing the Check‑Alive date / heir locktime

+

BAL compares the requested locktime against the locktime frozen inside the +already‑signed transaction (w.tx.locktime) — exactly what the will‑executors hold.

+ + + + + + + + +
You do…Tx already signed/sent?ResultOn‑chain fee?
Move date LATER (postpone)No (never signed)Plain rebuildNo
Move date LATER (postpone)YesInvalidate first, then rebuild (WillPostponed)Yes
Move date EARLIER (anticipate)anyOld tx expired → invalidate (WillExpired)Yes
Check‑Alive threshold already passed—Invalidate (CheckAliveError)Yes
+
Why postpone needs on‑chain invalidation: the executor still holds the old +transaction with the earlier locktime. Spending its inputs on‑chain makes it un‑minable, so it can +never execute the inheritance early. The plugin tells you this and offers to build the invalidation tx.
+ +

4.2 Adding an heir

+

An heir present in your set but not yet in the will raises HeirNotFoundException.

+ + +

4.3 Removing an heir

+

The will still carries an heir no longer in your set → HeirNotFoundException (removed‑heir branch).

+ +
v0.3.2 fix: removing an heir is now detected on Check and on +Electrum close, not only on Prepare.
+ +

4.4 Changing an heir's percentage or address

+

A changed [address, amount] is treated like an heir change (HeirChange / HeirNotFound).

+ +
The wallet is always fully emptied by the inheritance; amounts must add up, or an +AmountException warns you to adjust.
+ +

4.5 Changing the transaction fee (sat/byte)

+

A different rate raises TxFeesChangedException.

+ + +

4.6 Changing or removing a will‑executor

+ + + +

4.7 Nothing changed

+

If heirs, percentages, fees, executors and locktimes all still match the signed transactions, +is_will_valid returns True and nothing happens.

+ +

5. What happens on the will‑executor servers

+ + + + + + + + + + +
Your actionEffect on the servers
Prepare (rebuild)Nothing yet — new txs are local until Sign + Broadcast.
SignStill local; tx becomes COMPLETE (blue).
Broadcast to executorsSigned txs uploaded; items become PUSHED.
CheckEach PUSHED will is queried; success → CHECKED (green), failure → CHECK_FAIL (red).
Invalidate (on‑chain)You spend the committed inputs on the network. Once confirmed, the executor's stored tx can no longer be mined and is dropped on the next check.
Re‑broadcast a new willExecutors replace the obsolete copy with the new signed tx.
+
A row turning red (CHECK_FAIL) after a Check means an +executor that should hold your tx did not return it — re‑Broadcast or rebuild. A merely +blue row is signed‑but‑not‑yet‑sent and perfectly normal.
+ +

6. Quick reference — does it cost a Bitcoin fee?

+ + + + + + + + + + + + + + + +
ChangeRebuild?On‑chain invalidation (real fee)?
Add heir (only prepared)YesNo
Remove heir (only prepared)YesNo
Change % / address (only prepared)YesNo
Change fee rateYesNo
Change / remove will‑executorYesNo
Move date earlier (anticipate)Yes afterYes
Move date later — will signed/sentYes afterYes
Move date later — will only preparedYesNo
Check‑Alive threshold already passedYes afterYes
Any change to an already signed/sent willYes afterYes
Nothing changedNoNo
+ +

7. Golden rules

+
    +
  1. Before it's signed, changing anything is free — just Prepare again.
    2. +
  2. After it's signed/sent, moving the date or replacing it requires an on‑chain + invalidation first (a small Bitcoin fee) so an old transaction can never execute early.
    3. +
  3. Always finish with Sign → Broadcast → Check so executors hold the current plan (green).
    4. +
  4. The wallet is always fully emptied by the inheritance, so heir amounts must add up.
    5. +
+ + +
+ + + + diff --git a/docs/manual/manual.html b/docs/manual/manual.html new file mode 100644 index 0000000..eb8327d --- /dev/null +++ b/docs/manual/manual.html @@ -0,0 +1,514 @@ + + + + + +BAL Protocol 1.0 — User Manual (revB) + + + +
+

+ BitcoinAfter.Life logo +

+ +

BitcoinAfter.Life — BAL PROTOCOL 1.0

+

USER MANUAL (revB)

+ +
+

This is the GitHub‑friendly (HTML/Markdown + images) edition of the official +BAL user manual. The original PDF lives in the +bal_plugin_manual +Gitea repository. A styled single‑page version is available as +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. +
  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. +
  3. Activate the plugin from the Electrum menu (Tools → Plugins → BAL).
    4. +
  4. Restart Electrum.
    5. +
+

Now you are ready to leave your digital legacy to your heirs!

+
+

The BAL interface

+

Figure 1 — Electrum with the BAL plugin installed

+

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.

+ +
+

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 — HEIRS tab parameters

+

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:

+ +

* 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:

+ +

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.

+ +
+

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.

+
+ +
+

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 — New Heir window

+

Figure 3 — adding a new heir.

+

Here you enter the following parameters:

+ +
+

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.

+ +
+

👉 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.

+
+
+

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 — Backup Transaction parameter

+

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. +
  2. Difficulty delivering the signed transaction to the heir (the heir would learn + about the inheritance and its value).
    3. +
  3. Each step must be handled by hand, with the risk of errors.
    4. +
+

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 in the WILL screen

+

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

+

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 — Export the heir list

+

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:

+ +

List columns

+
    +
  1. URL — the URL address of the will‑executor.
    2. +
  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. +
  3. Info — server description or website link.
    4. +
  4. Default Address — the bitcoin wallet address where the base fee will be + sent.
    5. +
  5. S — server status. A green dot = server online.
    6. +
+

Right‑click on a server line opens four sub‑commands:

+

Figure 8 — Will‑executor right‑click menu

+

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. +
  2. Edit — edit the relevant column field.
    3. +
  3. Ping — verify that the server is online.
    4. +
  4. Delete — delete the server from the list.
    5. +
+
+

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
#StatusMeaningColourHEX
1NewTX new inheritanceWhite (transparent)#FFFFFF
2SignedTX inheritance signed into the walletAzure#2BC8ED
3PushedTX sent to will‑executorAzure‑green#73F3C8
4CheckedTX actually present in the will‑executorBright green#8AFA6C
5ConfirmedTX confirmed in the blockchainGray#BFBFBF
6PendingTX awaiting confirmation on blockchainYellow#FFCE30
7FailedCommunication failure with will‑executorRed#E83845
8InvalidatedUTXO input is no longer availableOrange#F87838
9ReplacedA backdated‑locktime transaction spends the same inputViolet#FF97E9
+
+

WILL tab — commands

+

Figure 9 — WILL tab and Will‑Details window

+

Figure 9 — the WILL tab with its commands.

+
    +
  1. Prepare — prepares the inheritance and puts it on the list.
    2. +
  2. Sign — sign your legacy transaction with your private key (using your + wallet password or hardware key).
    3. +
  3. Broadcast — sends the inheritance transaction to the online Will‑Executor + servers on your Will‑Executor Service List.
    4. +
  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
    5. +
+

Figure 10 — Will‑Details window

+

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

+
+

Signed,
Svātantrya

+
+ +