# 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/MEMPOOL
`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
`MEMPOOL` | Tx in the Electrum mempool | seen on‑chain, height 0 (named `PENDING` before v0.3.4)
`INVALIDATED` | Inputs spent → can never confirm | invalidation tx / inputs gone
`REPLACED` | Superseded by an earlier‑locktime child | a replacing child found
`ANTICIPATED` | Locktime anticipated by 1 day vs a pre‑existing tx with the same heirs | `set_anticipate` (tx stays VALID)
`UPDATED` | Replaced by a new tx keeping the same locktime + same heirs | same‑locktime replacement (tx stays VALID)
`EXPIRED` | Locktime already in the past vs the check date | `check_will_expired`

### Safety rules baked into `set_status`

- Setting `INVALIDATED` / `REPLACED` / `CONFIRMED` / `MEMPOOL` → clears `VALID`.
- Setting `ANTICIPATED` → keeps `VALID` (only moves the locktime 1 day earlier).
- Setting `UPDATED` → keeps `VALID` (same locktime + same heirs).
- Setting `CONFIRMED` / `MEMPOOL` → clears `INVALIDATED`.
- Setting `PUSHED` → clears `PUSH_FAIL` and `CHECK_FAIL`.
- Setting `CHECKED` → implies `PUSHED`.

### How states map to row colour

Priority | State | Colour | Hex
--- | --- | --- | ---
1 | `INVALIDATED` | orange | `#f87838`
2 | `REPLACED` | pink | `#ff97e9`
3 | `UPDATED` | light violet | `#b266b2`
4 | `CONFIRMED` | grey | `#bfbfbf`
5 | `MEMPOOL` | yellow | `#ffce30`
6 | `CHECK_FAIL` (and not `CHECKED`) | red | `#e83845`
7 | `CHECKED` | green | `#8afa6c`
8 | `PUSH_FAIL` | red | `#e83845`
9 | `PUSHED` | teal | `#73f3c8`
10 | `COMPLETE` (signed, not pushed) | blue | `#2bc8ed`
— | none of the above (plain `VALID`) | default white | `#ffffff`

> 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{New delivery date already in the PAST?}

        D -- "Yes date is now expired" --> INV2[[Invalidate on-chain FIRST
    WillExpired]]
        D -- "No date still in the future" --> AN{Did you move the date EARLIER anticipate?}

        AN -- "Yes anticipate — signed or not" --> R1[[Rebuild only
    no on-chain cost
    NEVER invalidates]]
        AN -- 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, still in the future (anticipate) | any (signed or not) | Plain rebuild with the new earlier locktime — never invalidates | No
Move date EARLIER into the past (new date already passed) | — | Will is genuinely 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.

> Why anticipate (move earlier, still future) is NOT on‑chain: moving the delivery date earlier only makes the inheritance available sooner; there is no early‑execution risk, so the plugin simply rebuilds the transactions with the new earlier locktime — no on‑chain invalidation and no Bitcoin fee. This holds even if the will was already signed/sent: anticipating never invalidates. Only a date that lands in the past is treated as expired and invalidated (`WillExpired`).

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

### 4.8 An heir's share is below the dust limit (DUST)

Bitcoin refuses outputs that are too small to spend — the dust limit (the wallet's `dust_threshold`). BAL resolves each heir's final amount when it builds the will (`Heirs.prepare_lists`) and compares every share against that limit.

- Some heirs are dust, others valid → build continues. Each dust heir is skipped (its share would be unspendable) and listed in the build report as “… is DUST – excluded (amount below dust limit)”. The will is still prepared, signed and checked with the payable heirs (unchanged behaviour).
- EVERY heir is dust → build blocked. If all shares are below the dust limit the inheritance would pay nobody. As of v0.4.7 BAL refuses it (`HeirAmountIsDustException`) and the Building Will window stops with a clear red message: “All heirs' shares are below the dust limit: the inheritance cannot be created. Increase the amounts or reduce the number of heirs.” Nothing is built, signed, checked or added to the list.

> When? Typically with a very small balance split among percentage heirs, or when every fixed amount is below the dust limit. Fix: raise the per‑heir amounts or use fewer heirs.

> Note (v0.4.7): the dust check lives in `prepare_lists`, which sees all heirs across all locktimes — a single transaction only covers the earliest locktime, so checking there would wrongly block a will whose later dates still have valid heirs. On‑chain fee: none (pre‑build safety check).

## 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, still in the future (anticipate) — signed or not | Yes | No
Move date earlier into the past (new date already passed) | 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 that postpones it or expires it | Yes after | Yes
Nothing changed | No | No
Every heir's share below the dust limit (all‑dust) — build blocked (§4.8) | No | No

## 7. Golden rules

1. Before it's signed, changing anything is free — just Prepare again.
2. After it's signed/sent, only postponing the date (moving it later), or letting it expire (a date now in the past), requires an on‑chain invalidation first (a small Bitcoin fee) so an old transaction can never execute early. Anticipating (moving the date earlier, still in the future) never invalidates — it is just a free rebuild.
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.
5. Mind the dust limit. A share below Bitcoin's dust limit is skipped; if every heir is dust the build is blocked with a clear message (§4.8) — raise the amounts or use fewer heirs.