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. Rebuild (re‑prepare + re‑sign, no on‑chain cost) — the will changed but nothing dangerous is committed yet.
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.

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)

Status	Meaning	Set when
VALID	The current, usable plan	default; cleared by INVALIDATED/REPLACED/CONFIRMED/PENDING
COMPLETE (Signed)	The transaction has been signed	after Sign
PUSHED	Signed tx sent to executor(s)	after Broadcast to executors
CHECKED	Executor confirmed it holds the tx	after a successful server Check (implies PUSHED)
CHECK_FAIL	Server check failed	a queried executor did not return the tx
PUSH_FAIL	Sending to the executor failed	cleared when PUSHED becomes true
CONFIRMED	Tx mined on‑chain	seen on‑chain, height > 0
PENDING	Tx in the mempool	seen on‑chain, height 0
INVALIDATED	Inputs spent → can never confirm	invalidation tx / inputs gone
REPLACED	Superseded by an earlier‑locktime child	a replacing child found
EXPIRED	Locktime already in the past vs the check date	check_will_expired

Safety rules baked into set_status

• Setting INVALIDATED / REPLACED / CONFIRMED / PENDING → clears VALID.
• Setting CONFIRMED / PENDING → clears INVALIDATED.
• Setting PUSHED → clears PUSH_FAIL and CHECK_FAIL.
• Setting CHECKED → implies PUSHED.

How states map to row colour

State (first match wins)	Colour	Hex
CHECK_FAIL	red	#e83845
INVALIDATED / REPLACED	grey	muted
CONFIRMED	green	confirmed
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?	Result	On‑chain fee?
Move date LATER (postpone)	No (never signed)	Plain rebuild	No
Move date LATER (postpone)	Yes	Invalidate first, then rebuild (WillPostponed)	Yes
Move date EARLIER (anticipate)	any	Old 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.

• Result: rebuild.
• On‑chain fee: No — unless the changed will was already signed/sent and the change also moves a locktime later (then 4.1 applies).

4.3 Removing an heir

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

• Result: rebuild, so the removed heir disappears.
• On‑chain fee: No for a prepared‑only will; if it was signed/sent, invalidate on‑chain first, then rebuild.

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

• Result: rebuild with new amounts.
• On‑chain fee: No (unless signed/sent → invalidate first).

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.

• Result: rebuild at the new fee rate.
• On‑chain fee: No to rebuild (you pay only when broadcasting on‑chain).

4.6 Changing or removing a will‑executor

• Selected executor not referenced → WillExecutorNotPresent.
• Executor details changed → WillexecutorChangeException.
• “No executor” mode without a backup tx → NoWillExecutorNotPresent.

• Result: rebuild & redistribute to the new executor set.
• On‑chain fee: No to rebuild.

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 action	Effect on the servers
Prepare (rebuild)	Nothing yet — new txs are local until Sign + Broadcast.
Sign	Still local; tx becomes COMPLETE (blue).
Broadcast to executors	Signed txs uploaded; items become PUSHED.
Check	Each 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 will	Executors 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?

Change	Rebuild?	On‑chain invalidation (real fee)?
Add heir (only prepared)	Yes	No
Remove heir (only prepared)	Yes	No
Change % / address (only prepared)	Yes	No
Change fee rate	Yes	No
Change / remove will‑executor	Yes	No
Move date earlier (anticipate)	Yes after	Yes
Move date later — will signed/sent	Yes after	Yes
Move date later — will only prepared	Yes	No
Check‑Alive threshold already passed	Yes after	Yes
Any change to an already signed/sent will	Yes after	Yes
Nothing changed	No	No

7. Golden rules

1. Before it's signed, changing anything is free — just Prepare again.
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. Always finish with Sign → Broadcast → Check so executors hold the current plan (green).
4. The wallet is always fully emptied by the inheritance, so heir amounts must add up.