forked from bitcoinafterlife/bal-electrum-plugin
add docs (text only)
This commit is contained in:
bot
36
docs/README.md
Normal file
36
docs/README.md
Normal file
@@ -0,0 +1,36 @@
|
|||||||
|
<p align="center">
|
||||||
|
<img src="./manual/images/logo.png" alt="BitcoinAfter.Life logo" width="110" />
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<h1 align="center">BAL — Bitcoin After Life · Documentation</h1>
|
||||||
|
|
||||||
|
Documentation for the **BAL** open‑source Electrum plugin for Bitcoin digital
|
||||||
|
inheritance. Everything here is plain Markdown + images (and optional styled
|
||||||
|
HTML), so it renders directly on GitHub and via GitHub Pages — **no PDF needed**.
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
|
| Document | Markdown (GitHub) | Styled HTML |
|
||||||
|
|---|---|---|
|
||||||
|
| **User Manual (revB)** — full plugin manual with screenshots | [`manual/README.md`](./manual/README.md) | [`manual/manual.html`](./manual/manual.html) |
|
||||||
|
| **Inheritance Options Guide** — every change (date earlier/later, add/remove heir, change %, fees, executors) + decision flow chart + transaction states & server effects | [`inheritance-options.md`](./inheritance-options.md) | [`inheritance-options.html`](./inheritance-options.html) |
|
||||||
|
|
||||||
|
## Quick links
|
||||||
|
|
||||||
|
- 📖 **New to BAL?** Start with the [User Manual](./manual/README.md).
|
||||||
|
- 🔁 **Changing a will?** See the [Inheritance Options Guide](./inheritance-options.md)
|
||||||
|
to know exactly what happens (and whether it costs an on‑chain fee).
|
||||||
|
|
||||||
|
## Viewing the HTML versions
|
||||||
|
|
||||||
|
- On GitHub Pages: enable Pages for this repository (Settings → Pages → deploy
|
||||||
|
from branch, folder `/docs`), then open
|
||||||
|
`https://<owner>.github.io/<repo>/manual/manual.html`.
|
||||||
|
- Offline: download the `docs/` folder and open the `.html` files in any browser
|
||||||
|
(the styled manual works fully offline; the inheritance‑options page loads
|
||||||
|
Mermaid from a CDN for the live diagram, and also ships a static SVG fallback).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*The manual is the GitHub‑friendly edition of the official BAL PDF
|
||||||
|
([bal_plugin_manual](https://bitcoin-after.life/gitea/bitcoinafterlife/bal_plugin_manual)).*
|
||||||
145
docs/images/inheritance-flow.svg
Normal file
145
docs/images/inheritance-flow.svg
Normal file
@@ -0,0 +1,145 @@
|
|||||||
|
<svg xmlns="http://www.w3.org/2000/svg" width="1180" height="900" viewBox="0 0 1180 900" font-family="Segoe UI, Helvetica, Arial, sans-serif">
|
||||||
|
<defs>
|
||||||
|
<marker id="arr" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">
|
||||||
|
<path d="M0,0 L8,3 L0,6 Z" fill="#9da7b3"/>
|
||||||
|
</marker>
|
||||||
|
<style>
|
||||||
|
.bg{fill:#0d1117}
|
||||||
|
.edge{stroke:#9da7b3;stroke-width:1.6;fill:none;marker-end:url(#arr)}
|
||||||
|
.lbl{fill:#9da7b3;font-size:12px}
|
||||||
|
.start{fill:#1f6feb;stroke:#388bfd}
|
||||||
|
.dec{fill:#21262d;stroke:#8b949e}
|
||||||
|
.rebuild{fill:#143d2b;stroke:#2ea043}
|
||||||
|
.inval{fill:#4a1d22;stroke:#e83845}
|
||||||
|
.ok{fill:#1c2a3a;stroke:#2bc8ed}
|
||||||
|
.term{fill:#2d333b;stroke:#8b949e}
|
||||||
|
text{fill:#e6edf3;font-size:13px}
|
||||||
|
.ttl{font-size:13px;font-weight:600}
|
||||||
|
.sub{font-size:11px;fill:#9da7b3}
|
||||||
|
.leg{font-size:12px}
|
||||||
|
</style>
|
||||||
|
</defs>
|
||||||
|
<rect class="bg" x="0" y="0" width="1180" height="900"/>
|
||||||
|
|
||||||
|
<!-- Title -->
|
||||||
|
<text x="24" y="34" font-size="20" font-weight="700">BAL — Inheritance change decision flow</text>
|
||||||
|
<text x="24" y="56" class="sub">What happens to your pre-signed transactions when you change the will (v0.3.3)</text>
|
||||||
|
|
||||||
|
<!-- Legend -->
|
||||||
|
<g transform="translate(760,76)">
|
||||||
|
<rect class="rebuild" x="0" y="0" width="18" height="14" rx="3"/><text x="24" y="12" class="leg">Rebuild (no on-chain fee)</text>
|
||||||
|
<rect class="inval" x="0" y="22" width="18" height="14" rx="3"/><text x="24" y="34" class="leg">Invalidate on-chain (real fee)</text>
|
||||||
|
<rect class="dec" x="0" y="44" width="18" height="14" rx="3"/><text x="24" y="56" class="leg">Decision</text>
|
||||||
|
<rect class="ok" x="0" y="66" width="18" height="14" rx="3"/><text x="24" y="78" class="leg">Coherent / final</text>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<!-- A start -->
|
||||||
|
<rect class="start" x="430" y="80" width="320" height="44" rx="22"/>
|
||||||
|
<text x="590" y="107" text-anchor="middle" class="ttl">Change something → press Prepare / Check</text>
|
||||||
|
|
||||||
|
<!-- B heirs defined -->
|
||||||
|
<polygon class="dec" points="590,140 720,170 590,200 460,170"/>
|
||||||
|
<text x="590" y="174" text-anchor="middle">Heirs defined?</text>
|
||||||
|
<path class="edge" d="M590,124 L590,140"/>
|
||||||
|
|
||||||
|
<!-- C threshold future -->
|
||||||
|
<polygon class="dec" points="590,222 760,256 590,290 420,256"/>
|
||||||
|
<text x="590" y="254" text-anchor="middle">Check-Alive threshold</text>
|
||||||
|
<text x="590" y="270" text-anchor="middle" class="sub">in the future?</text>
|
||||||
|
<path class="edge" d="M590,200 L590,222"/>
|
||||||
|
<text x="600" y="216" class="lbl">Yes</text>
|
||||||
|
|
||||||
|
<!-- B No -> stop -->
|
||||||
|
<rect class="term" x="120" y="148" width="200" height="44" rx="8"/>
|
||||||
|
<text x="220" y="168" text-anchor="middle">Heirs not defined</text>
|
||||||
|
<text x="220" y="184" text-anchor="middle" class="sub">stop</text>
|
||||||
|
<path class="edge" d="M460,170 L320,170"/>
|
||||||
|
<text x="388" y="162" class="lbl">No</text>
|
||||||
|
|
||||||
|
<!-- C No -> INV1 -->
|
||||||
|
<rect class="inval" x="60" y="234" width="240" height="48" rx="8"/>
|
||||||
|
<text x="180" y="254" text-anchor="middle" class="ttl">Invalidate on-chain</text>
|
||||||
|
<text x="180" y="270" text-anchor="middle" class="sub">CheckAliveError (threshold passed)</text>
|
||||||
|
<path class="edge" d="M420,256 L300,256"/>
|
||||||
|
<text x="330" y="250" class="lbl">No</text>
|
||||||
|
|
||||||
|
<!-- D earlier? -->
|
||||||
|
<polygon class="dec" points="590,312 800,350 590,388 380,350"/>
|
||||||
|
<text x="590" y="346" text-anchor="middle">VALID tx with locktime</text>
|
||||||
|
<text x="590" y="362" text-anchor="middle" class="sub">earlier than the new date? (anticipate)</text>
|
||||||
|
<path class="edge" d="M590,290 L590,312"/>
|
||||||
|
|
||||||
|
<!-- D Yes -> E -->
|
||||||
|
<polygon class="dec" points="930,312 1110,350 930,388 750,350"/>
|
||||||
|
<text x="930" y="346" text-anchor="middle">Already signed</text>
|
||||||
|
<text x="930" y="362" text-anchor="middle" class="sub">or sent?</text>
|
||||||
|
<path class="edge" d="M800,350 L750,350"/>
|
||||||
|
<text x="772" y="344" class="lbl">Yes (earlier)</text>
|
||||||
|
|
||||||
|
<!-- E No -> R1 rebuild -->
|
||||||
|
<rect class="rebuild" x="820" y="410" width="220" height="48" rx="8"/>
|
||||||
|
<text x="930" y="430" text-anchor="middle" class="ttl">Rebuild only</text>
|
||||||
|
<text x="930" y="446" text-anchor="middle" class="sub">no on-chain cost</text>
|
||||||
|
<path class="edge" d="M930,388 L930,410"/>
|
||||||
|
<text x="940" y="402" class="lbl">Not signed</text>
|
||||||
|
|
||||||
|
<!-- E Yes -> INV2 -->
|
||||||
|
<rect class="inval" x="820" y="476" width="240" height="48" rx="8"/>
|
||||||
|
<text x="940" y="496" text-anchor="middle" class="ttl">Invalidate on-chain FIRST</text>
|
||||||
|
<text x="940" y="512" text-anchor="middle" class="sub">WillExpired</text>
|
||||||
|
<path class="edge" d="M1010,386 C1090,430 1080,460 1010,476"/>
|
||||||
|
<text x="1058" y="430" class="lbl">Signed</text>
|
||||||
|
|
||||||
|
<!-- D No -> F -->
|
||||||
|
<polygon class="dec" points="430,420 620,458 430,496 240,458"/>
|
||||||
|
<text x="430" y="452" text-anchor="middle">Executor / fee /</text>
|
||||||
|
<text x="430" y="468" text-anchor="middle" class="sub">heirs unchanged?</text>
|
||||||
|
<path class="edge" d="M520,380 C470,400 450,408 440,420"/>
|
||||||
|
<text x="500" y="404" class="lbl">No</text>
|
||||||
|
|
||||||
|
<!-- F Nothing changed -> OK -->
|
||||||
|
<rect class="ok" x="40" y="436" width="180" height="44" rx="8"/>
|
||||||
|
<text x="130" y="456" text-anchor="middle" class="ttl">Do nothing</text>
|
||||||
|
<text x="130" y="472" text-anchor="middle" class="sub">still coherent</text>
|
||||||
|
<path class="edge" d="M240,458 L220,458"/>
|
||||||
|
<text x="226" y="452" class="lbl">Same</text>
|
||||||
|
|
||||||
|
<!-- F fee/exec/heir -> G -->
|
||||||
|
<polygon class="dec" points="430,524 640,562 430,600 220,562"/>
|
||||||
|
<text x="430" y="556" text-anchor="middle">POSTPONE of an</text>
|
||||||
|
<text x="430" y="572" text-anchor="middle" class="sub">already signed/sent tx?</text>
|
||||||
|
<path class="edge" d="M430,496 L430,524"/>
|
||||||
|
<text x="440" y="516" class="lbl">Changed (fee / executor / heir / %)</text>
|
||||||
|
|
||||||
|
<!-- G No -> R4 rebuild -->
|
||||||
|
<rect class="rebuild" x="40" y="620" width="300" height="48" rx="8"/>
|
||||||
|
<text x="190" y="640" text-anchor="middle" class="ttl">Rebuild only</text>
|
||||||
|
<text x="190" y="656" text-anchor="middle" class="sub">HeirNotFound / HeirChange / TxFees / Executor</text>
|
||||||
|
<path class="edge" d="M340,580 C250,600 220,608 200,620"/>
|
||||||
|
<text x="250" y="600" class="lbl">No (never signed / pure heir change)</text>
|
||||||
|
|
||||||
|
<!-- G Yes -> INV3 -->
|
||||||
|
<rect class="inval" x="430" y="620" width="300" height="48" rx="8"/>
|
||||||
|
<text x="580" y="640" text-anchor="middle" class="ttl">Invalidate FIRST, then rebuild</text>
|
||||||
|
<text x="580" y="656" text-anchor="middle" class="sub">WillPostponed</text>
|
||||||
|
<path class="edge" d="M520,580 C560,600 570,608 580,620"/>
|
||||||
|
<text x="560" y="600" class="lbl">Yes (date later + signed)</text>
|
||||||
|
|
||||||
|
<!-- SIGN -->
|
||||||
|
<rect class="start" x="700" y="700" width="260" height="44" rx="22"/>
|
||||||
|
<text x="830" y="727" text-anchor="middle" class="ttl">Re-sign → Broadcast to executors</text>
|
||||||
|
<path class="edge" d="M930,458 C1000,560 980,650 920,700"/>
|
||||||
|
<path class="edge" d="M340,644 C520,700 600,710 700,722"/>
|
||||||
|
|
||||||
|
<!-- SB invalidation -->
|
||||||
|
<rect class="inval" x="120" y="760" width="360" height="48" rx="8"/>
|
||||||
|
<text x="300" y="780" text-anchor="middle" class="ttl">Sign & broadcast the INVALIDATION tx</text>
|
||||||
|
<text x="300" y="796" text-anchor="middle" class="sub">on-chain, then Prepare again → rebuild</text>
|
||||||
|
<path class="edge" d="M180,282 C60,420 40,650 130,760"/>
|
||||||
|
<path class="edge" d="M940,524 C1000,640 760,740 480,786"/>
|
||||||
|
<path class="edge" d="M580,668 L420,760"/>
|
||||||
|
|
||||||
|
<!-- SB -> SIGN loop -->
|
||||||
|
<path class="edge" d="M480,784 C620,760 660,740 700,728"/>
|
||||||
|
<text x="560" y="745" class="lbl">once confirmed</text>
|
||||||
|
</svg>
|
||||||
|
After Width: | Height: | Size: 7.3 KiB |
267
docs/inheritance-options.html
Normal file
267
docs/inheritance-options.html
Normal file
@@ -0,0 +1,267 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html lang="en">
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8" />
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||||
|
<title>BAL — Inheritance Options Guide</title>
|
||||||
|
<style>
|
||||||
|
:root{
|
||||||
|
--bg:#0d1117; --panel:#161b22; --text:#e6edf3; --muted:#9da7b3;
|
||||||
|
--border:#30363d; --accent:#2bc8ed; --red:#e83845; --green:#2ea043;
|
||||||
|
--blue:#2bc8ed; --grey:#8b949e; --amber:#cfa808;
|
||||||
|
}
|
||||||
|
*{box-sizing:border-box}
|
||||||
|
body{
|
||||||
|
margin:0; background:var(--bg); color:var(--text);
|
||||||
|
font:16px/1.65 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
|
||||||
|
}
|
||||||
|
.wrap{max-width:980px;margin:0 auto;padding:32px 20px 80px}
|
||||||
|
h1{font-size:2rem;margin:.2em 0 .1em;border-bottom:2px solid var(--accent);padding-bottom:.3em}
|
||||||
|
h2{font-size:1.4rem;margin:2em 0 .4em;border-bottom:1px solid var(--border);padding-bottom:.25em}
|
||||||
|
h3{font-size:1.12rem;margin:1.6em 0 .3em;color:#cdd9e5}
|
||||||
|
p,li{color:var(--text)}
|
||||||
|
blockquote{
|
||||||
|
margin:1em 0;padding:.6em 1em;border-left:4px solid var(--accent);
|
||||||
|
background:var(--panel);border-radius:0 8px 8px 0;color:var(--muted)
|
||||||
|
}
|
||||||
|
blockquote strong{color:var(--text)}
|
||||||
|
code{background:#1f2630;padding:.12em .4em;border-radius:5px;font-size:.9em}
|
||||||
|
table{border-collapse:collapse;width:100%;margin:1em 0;font-size:.93rem;display:block;overflow-x:auto}
|
||||||
|
th,td{border:1px solid var(--border);padding:8px 10px;text-align:left;vertical-align:top}
|
||||||
|
th{background:var(--panel)}
|
||||||
|
tr:nth-child(even) td{background:#11161d}
|
||||||
|
.yes{color:var(--green);font-weight:700}
|
||||||
|
.no{color:var(--grey);font-weight:700}
|
||||||
|
.fee{color:var(--red);font-weight:700}
|
||||||
|
.pill{display:inline-block;padding:.05em .55em;border-radius:999px;font-size:.78em;font-weight:700;color:#0d1117}
|
||||||
|
.pill.red{background:var(--red);color:#fff}
|
||||||
|
.pill.blue{background:var(--blue)}
|
||||||
|
.pill.green{background:var(--green);color:#fff}
|
||||||
|
.pill.grey{background:var(--grey);color:#fff}
|
||||||
|
.mermaid{background:var(--panel);border:1px solid var(--border);border-radius:10px;padding:18px;margin:1.2em 0;overflow-x:auto}
|
||||||
|
.lead{color:var(--muted);font-size:1.05rem}
|
||||||
|
footer{margin-top:3em;color:var(--muted);font-size:.85rem;border-top:1px solid var(--border);padding-top:1em}
|
||||||
|
a{color:var(--accent)}
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div class="wrap">
|
||||||
|
|
||||||
|
<h1>BAL — Inheritance Options Guide</h1>
|
||||||
|
<p class="lead">How the <strong>Bitcoin After Life</strong> 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.</p>
|
||||||
|
|
||||||
|
<blockquote>This page reflects the <strong>actual behaviour of the code</strong>
|
||||||
|
(<code>core/will.py</code> → <code>is_will_valid</code> / <code>check_willexecutors_and_heirs</code> and
|
||||||
|
<code>gui/qt/window.py</code> → <code>build_inheritance_transaction</code>). It is meant for end users and
|
||||||
|
for anyone wanting to understand the on‑chain consequences of each action.</blockquote>
|
||||||
|
|
||||||
|
<h2>1. The mental model in one paragraph</h2>
|
||||||
|
<p>Your will is a <strong>tree of pre‑signed Bitcoin transactions</strong>. Each leaf transaction sends your
|
||||||
|
coins to your heirs and is <strong>time‑locked</strong> (<code>nLockTime</code>) so it can only be broadcast
|
||||||
|
<strong>after</strong> a future date/block. A copy of each signed transaction is handed to one or more
|
||||||
|
<strong>will‑executor servers</strong>. While you are alive you periodically prove you are alive (the
|
||||||
|
<em>Check‑Alive threshold</em>). When you change anything, BAL chooses between three outcomes:</p>
|
||||||
|
<ol>
|
||||||
|
<li><strong>Do nothing</strong> — the will is still coherent.</li>
|
||||||
|
<li><strong>Rebuild</strong> (re‑prepare + re‑sign, <em>no on‑chain cost</em>) — the will changed but
|
||||||
|
nothing dangerous is committed yet.</li>
|
||||||
|
<li><strong>Invalidate on‑chain first</strong> (costs a real Bitcoin fee) — a previously
|
||||||
|
<strong>signed/sent</strong> transaction must be neutralised by spending its inputs <em>before</em> a
|
||||||
|
new will can safely replace it.</li>
|
||||||
|
</ol>
|
||||||
|
<blockquote>The whole point of rule 3 is safety: <strong>a will‑executor must never be able to broadcast an old
|
||||||
|
transaction that would execute your inheritance too early.</strong></blockquote>
|
||||||
|
|
||||||
|
<h2>2. Transaction states (status flags)</h2>
|
||||||
|
<table>
|
||||||
|
<thead><tr><th>Status</th><th>Meaning</th><th>Set when</th></tr></thead>
|
||||||
|
<tbody>
|
||||||
|
<tr><td><code>VALID</code></td><td>The current, usable plan</td><td>default; cleared by INVALIDATED/REPLACED/CONFIRMED/PENDING</td></tr>
|
||||||
|
<tr><td><code>COMPLETE</code> (<em>Signed</em>)</td><td>The transaction has been <strong>signed</strong></td><td>after <strong>Sign</strong></td></tr>
|
||||||
|
<tr><td><code>PUSHED</code></td><td>Signed tx <strong>sent to executor(s)</strong></td><td>after <strong>Broadcast</strong> to executors</td></tr>
|
||||||
|
<tr><td><code>CHECKED</code></td><td>Executor <strong>confirmed</strong> it holds the tx</td><td>after a successful server <strong>Check</strong> (implies PUSHED)</td></tr>
|
||||||
|
<tr><td><code>CHECK_FAIL</code></td><td>Server <strong>check failed</strong></td><td>a queried executor did not return the tx</td></tr>
|
||||||
|
<tr><td><code>PUSH_FAIL</code></td><td>Sending to the executor failed</td><td>cleared when PUSHED becomes true</td></tr>
|
||||||
|
<tr><td><code>CONFIRMED</code></td><td>Tx <strong>mined on‑chain</strong></td><td>seen on‑chain, height > 0</td></tr>
|
||||||
|
<tr><td><code>PENDING</code></td><td>Tx <strong>in the mempool</strong></td><td>seen on‑chain, height 0</td></tr>
|
||||||
|
<tr><td><code>INVALIDATED</code></td><td>Inputs spent → can never confirm</td><td>invalidation tx / inputs gone</td></tr>
|
||||||
|
<tr><td><code>REPLACED</code></td><td>Superseded by an earlier‑locktime child</td><td>a replacing child found</td></tr>
|
||||||
|
<tr><td><code>EXPIRED</code></td><td>Locktime already in the past vs the check date</td><td><code>check_will_expired</code></td></tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<h3>Safety rules baked into <code>set_status</code></h3>
|
||||||
|
<ul>
|
||||||
|
<li>Setting <code>INVALIDATED</code> / <code>REPLACED</code> / <code>CONFIRMED</code> / <code>PENDING</code> → clears <code>VALID</code>.</li>
|
||||||
|
<li>Setting <code>CONFIRMED</code> / <code>PENDING</code> → clears <code>INVALIDATED</code>.</li>
|
||||||
|
<li>Setting <code>PUSHED</code> → clears <code>PUSH_FAIL</code> <strong>and</strong> <code>CHECK_FAIL</code>.</li>
|
||||||
|
<li>Setting <code>CHECKED</code> → implies <code>PUSHED</code>.</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>How states map to row colour</h3>
|
||||||
|
<table>
|
||||||
|
<thead><tr><th>State (first match wins)</th><th>Colour</th><th>Hex</th></tr></thead>
|
||||||
|
<tbody>
|
||||||
|
<tr><td><code>CHECK_FAIL</code></td><td><span class="pill red">red</span></td><td><code>#e83845</code></td></tr>
|
||||||
|
<tr><td><code>INVALIDATED</code> / <code>REPLACED</code></td><td><span class="pill grey">grey</span></td><td>muted</td></tr>
|
||||||
|
<tr><td><code>CONFIRMED</code></td><td><span class="pill green">green</span></td><td>confirmed</td></tr>
|
||||||
|
<tr><td><code>COMPLETE</code> (signed, not pushed)</td><td><span class="pill blue">blue</span></td><td><code>#2bc8ed</code></td></tr>
|
||||||
|
<tr><td><code>VALID</code> (prepared, not signed)</td><td>default</td><td>—</td></tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<blockquote><strong>v0.3.3 fix:</strong> a will that is <em>signed but not yet broadcast</em>
|
||||||
|
(<code>COMPLETE</code> and <strong>not</strong> <code>PUSHED</code>) is <strong>not</strong> queried on the
|
||||||
|
server, so it stays <strong>blue</strong> instead of turning red. Only <code>PUSHED</code> wills are checked.</blockquote>
|
||||||
|
|
||||||
|
<h2>3. The decision flow</h2>
|
||||||
|
<p>On <strong>Prepare</strong> (or the periodic <strong>Check</strong>, or on Electrum close) BAL runs
|
||||||
|
<code>is_will_valid</code>, raises a specific exception, and each maps to one action:</p>
|
||||||
|
|
||||||
|
<pre class="mermaid">
|
||||||
|
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<br/>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<br/>no on-chain cost]]
|
||||||
|
E -- "Signed / sent" --> INV2[[Invalidate on-chain FIRST<br/>WillExpired]]
|
||||||
|
|
||||||
|
D -- No --> F{Will-executor / fee / heirs unchanged?}
|
||||||
|
F -- "Fee changed" --> R2[[Rebuild<br/>TxFeesChanged]]
|
||||||
|
F -- "Will-executor changed/absent" --> R3[[Rebuild<br/>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<br/>WillPostponed]]
|
||||||
|
G -- "No never signed, or pure heir/% change" --> R4[[Rebuild only<br/>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
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<h2>4. Every option, explained</h2>
|
||||||
|
|
||||||
|
<h3>4.1 Changing the Check‑Alive date / heir locktime</h3>
|
||||||
|
<p>BAL compares the <strong>requested</strong> locktime against the locktime <strong>frozen inside the
|
||||||
|
already‑signed transaction</strong> (<code>w.tx.locktime</code>) — exactly what the will‑executors hold.</p>
|
||||||
|
<table>
|
||||||
|
<thead><tr><th>You do…</th><th>Tx already signed/sent?</th><th>Result</th><th>On‑chain fee?</th></tr></thead>
|
||||||
|
<tbody>
|
||||||
|
<tr><td>Move date <strong>LATER</strong> (postpone)</td><td>No (never signed)</td><td>Plain <strong>rebuild</strong></td><td class="no">No</td></tr>
|
||||||
|
<tr><td>Move date <strong>LATER</strong> (postpone)</td><td>Yes</td><td><strong>Invalidate first</strong>, then rebuild (WillPostponed)</td><td class="fee">Yes</td></tr>
|
||||||
|
<tr><td>Move date <strong>EARLIER</strong> (anticipate)</td><td>any</td><td>Old tx <strong>expired</strong> → invalidate (WillExpired)</td><td class="fee">Yes</td></tr>
|
||||||
|
<tr><td>Check‑Alive threshold already passed</td><td>—</td><td><strong>Invalidate</strong> (CheckAliveError)</td><td class="fee">Yes</td></tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<blockquote><strong>Why postpone needs on‑chain invalidation:</strong> the executor still holds the <em>old</em>
|
||||||
|
transaction with the <em>earlier</em> 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.</blockquote>
|
||||||
|
|
||||||
|
<h3>4.2 Adding an heir</h3>
|
||||||
|
<p>An heir present in your set but not yet in the will raises <code>HeirNotFoundException</code>.</p>
|
||||||
|
<ul><li><strong>Result:</strong> rebuild.</li>
|
||||||
|
<li><strong>On‑chain fee:</strong> <span class="no">No</span> — unless the changed will was already signed/sent
|
||||||
|
and the change also moves a locktime later (then 4.1 applies).</li></ul>
|
||||||
|
|
||||||
|
<h3>4.3 Removing an heir</h3>
|
||||||
|
<p>The will still carries an heir no longer in your set → <code>HeirNotFoundException</code> (removed‑heir branch).</p>
|
||||||
|
<ul><li><strong>Result:</strong> rebuild, so the removed heir disappears.</li>
|
||||||
|
<li><strong>On‑chain fee:</strong> <span class="no">No</span> for a prepared‑only will; if it was signed/sent,
|
||||||
|
invalidate on‑chain first, then rebuild.</li></ul>
|
||||||
|
<blockquote><strong>v0.3.2 fix:</strong> removing an heir is now detected on <strong>Check</strong> and on
|
||||||
|
Electrum <strong>close</strong>, not only on Prepare.</blockquote>
|
||||||
|
|
||||||
|
<h3>4.4 Changing an heir's percentage or address</h3>
|
||||||
|
<p>A changed <code>[address, amount]</code> is treated like an heir change (<code>HeirChange</code> / <code>HeirNotFound</code>).</p>
|
||||||
|
<ul><li><strong>Result:</strong> rebuild with new amounts.</li>
|
||||||
|
<li><strong>On‑chain fee:</strong> <span class="no">No</span> (unless signed/sent → invalidate first).</li></ul>
|
||||||
|
<blockquote>The wallet is always <strong>fully emptied</strong> by the inheritance; amounts must add up, or an
|
||||||
|
<code>AmountException</code> warns you to adjust.</blockquote>
|
||||||
|
|
||||||
|
<h3>4.5 Changing the transaction fee (sat/byte)</h3>
|
||||||
|
<p>A different rate raises <code>TxFeesChangedException</code>.</p>
|
||||||
|
<ul><li><strong>Result:</strong> rebuild at the new fee rate.</li>
|
||||||
|
<li><strong>On‑chain fee:</strong> <span class="no">No</span> to rebuild (you pay only when broadcasting on‑chain).</li></ul>
|
||||||
|
|
||||||
|
<h3>4.6 Changing or removing a will‑executor</h3>
|
||||||
|
<ul>
|
||||||
|
<li>Selected executor not referenced → <code>WillExecutorNotPresent</code>.</li>
|
||||||
|
<li>Executor details changed → <code>WillexecutorChangeException</code>.</li>
|
||||||
|
<li>“No executor” mode without a backup tx → <code>NoWillExecutorNotPresent</code>.</li>
|
||||||
|
</ul>
|
||||||
|
<ul><li><strong>Result:</strong> rebuild & redistribute to the new executor set.</li>
|
||||||
|
<li><strong>On‑chain fee:</strong> <span class="no">No</span> to rebuild.</li></ul>
|
||||||
|
|
||||||
|
<h3>4.7 Nothing changed</h3>
|
||||||
|
<p>If heirs, percentages, fees, executors and locktimes all still match the signed transactions,
|
||||||
|
<code>is_will_valid</code> returns <code>True</code> and <strong>nothing happens</strong>.</p>
|
||||||
|
|
||||||
|
<h2>5. What happens on the will‑executor servers</h2>
|
||||||
|
<table>
|
||||||
|
<thead><tr><th>Your action</th><th>Effect on the servers</th></tr></thead>
|
||||||
|
<tbody>
|
||||||
|
<tr><td><strong>Prepare</strong> (rebuild)</td><td>Nothing yet — new txs are local until Sign + Broadcast.</td></tr>
|
||||||
|
<tr><td><strong>Sign</strong></td><td>Still local; tx becomes <code>COMPLETE</code> (<span class="pill blue">blue</span>).</td></tr>
|
||||||
|
<tr><td><strong>Broadcast to executors</strong></td><td>Signed txs uploaded; items become <code>PUSHED</code>.</td></tr>
|
||||||
|
<tr><td><strong>Check</strong></td><td>Each <code>PUSHED</code> will is queried; success → <code>CHECKED</code> (<span class="pill green">green</span>), failure → <code>CHECK_FAIL</code> (<span class="pill red">red</span>).</td></tr>
|
||||||
|
<tr><td><strong>Invalidate (on‑chain)</strong></td><td>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.</td></tr>
|
||||||
|
<tr><td><strong>Re‑broadcast a new will</strong></td><td>Executors replace the obsolete copy with the new signed tx.</td></tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<blockquote>A row turning <span class="pill red">red</span> (<code>CHECK_FAIL</code>) after a Check means an
|
||||||
|
executor that <em>should</em> hold your tx did not return it — re‑Broadcast or rebuild. A merely
|
||||||
|
<span class="pill blue">blue</span> row is signed‑but‑not‑yet‑sent and perfectly normal.</blockquote>
|
||||||
|
|
||||||
|
<h2>6. Quick reference — does it cost a Bitcoin fee?</h2>
|
||||||
|
<table>
|
||||||
|
<thead><tr><th>Change</th><th>Rebuild?</th><th>On‑chain invalidation (real fee)?</th></tr></thead>
|
||||||
|
<tbody>
|
||||||
|
<tr><td>Add heir (only prepared)</td><td class="yes">Yes</td><td class="no">No</td></tr>
|
||||||
|
<tr><td>Remove heir (only prepared)</td><td class="yes">Yes</td><td class="no">No</td></tr>
|
||||||
|
<tr><td>Change % / address (only prepared)</td><td class="yes">Yes</td><td class="no">No</td></tr>
|
||||||
|
<tr><td>Change fee rate</td><td class="yes">Yes</td><td class="no">No</td></tr>
|
||||||
|
<tr><td>Change / remove will‑executor</td><td class="yes">Yes</td><td class="no">No</td></tr>
|
||||||
|
<tr><td>Move date <strong>earlier</strong> (anticipate)</td><td class="yes">Yes after</td><td class="fee">Yes</td></tr>
|
||||||
|
<tr><td>Move date <strong>later</strong> — will <strong>signed/sent</strong></td><td class="yes">Yes after</td><td class="fee">Yes</td></tr>
|
||||||
|
<tr><td>Move date <strong>later</strong> — will <strong>only prepared</strong></td><td class="yes">Yes</td><td class="no">No</td></tr>
|
||||||
|
<tr><td>Check‑Alive threshold already passed</td><td class="yes">Yes after</td><td class="fee">Yes</td></tr>
|
||||||
|
<tr><td>Any change to an <strong>already signed/sent</strong> will</td><td class="yes">Yes after</td><td class="fee">Yes</td></tr>
|
||||||
|
<tr><td>Nothing changed</td><td class="no">No</td><td class="no">No</td></tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<h2>7. Golden rules</h2>
|
||||||
|
<ol>
|
||||||
|
<li><strong>Before it's signed</strong>, changing anything is free — just <strong>Prepare</strong> again.</li>
|
||||||
|
<li><strong>After it's signed/sent</strong>, moving the date or replacing it requires an <strong>on‑chain
|
||||||
|
invalidation first</strong> (a small Bitcoin fee) so an old transaction can never execute early.</li>
|
||||||
|
<li>Always finish with <strong>Sign → Broadcast → Check</strong> so executors hold the current plan (green).</li>
|
||||||
|
<li>The wallet is always <strong>fully emptied</strong> by the inheritance, so heir amounts must add up.</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<footer>This document reflects BAL plugin v0.3.3. Behaviour is derived directly from
|
||||||
|
<code>core/will.py</code> and <code>gui/qt/window.py</code>.</footer>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<script type="module">
|
||||||
|
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
|
||||||
|
mermaid.initialize({ startOnLoad: true, theme: 'dark', securityLevel: 'loose' });
|
||||||
|
</script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
278
docs/inheritance-options.md
Normal file
278
docs/inheritance-options.md
Normal file
@@ -0,0 +1,278 @@
|
|||||||
|
# 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 guide describes 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 who wants 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 in your will, BAL must decide 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 already committed.
|
||||||
|
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)
|
||||||
|
|
||||||
|
Every will item (`WillItem`) carries a set of boolean status flags. The most
|
||||||
|
important ones:
|
||||||
|
|
||||||
|
| Status | Meaning | Set when |
|
||||||
|
|---|---|---|
|
||||||
|
| `VALID` | The item is the current, usable plan | default `True`; cleared by INVALIDATED/REPLACED/CONFIRMED/PENDING |
|
||||||
|
| `COMPLETE` (*Signed*) | The transaction has been **signed** | after you press **Sign** |
|
||||||
|
| `PUSHED` | The signed tx was **sent to the will‑executor(s)** | after **Broadcast** to executors |
|
||||||
|
| `CHECKED` | The will‑executor **confirmed** it holds the tx | after a successful server **Check** (implies `PUSHED`) |
|
||||||
|
| `CHECK_FAIL` | The server **check failed** | a queried executor did not return the tx |
|
||||||
|
| `PUSH_FAIL` | Sending to the executor failed | cleared when PUSHED becomes true |
|
||||||
|
| `CONFIRMED` | The tx is **mined on‑chain** | seen on‑chain with height > 0 |
|
||||||
|
| `PENDING` | The tx is **in the mempool** (height 0) | seen on‑chain, not yet mined |
|
||||||
|
| `INVALIDATED` | Its inputs were spent → it can never confirm | invalidation tx created / inputs gone |
|
||||||
|
| `REPLACED` | Superseded by a child tx with earlier locktime | a replacing child was found |
|
||||||
|
| `EXPIRED` | Its locktime is already in the past relative to the check date | `check_will_expired` |
|
||||||
|
|
||||||
|
Flag transitions enforced by `set_status` (the safety rules baked in the code):
|
||||||
|
|
||||||
|
- Setting `INVALIDATED` / `REPLACED` / `CONFIRMED` / `PENDING` → clears `VALID`.
|
||||||
|
- Setting `CONFIRMED` / `PENDING` → clears `INVALIDATED`.
|
||||||
|
- Setting `PUSHED` → clears `PUSH_FAIL` **and** `CHECK_FAIL`.
|
||||||
|
- Setting `CHECKED` → implies `PUSHED` (and clears `PUSH_FAIL`).
|
||||||
|
|
||||||
|
### How states map to row colour in the list
|
||||||
|
|
||||||
|
| State (first match wins) | Colour | Hex |
|
||||||
|
|---|---|---|
|
||||||
|
| `CHECK_FAIL` | red | `#e83845` |
|
||||||
|
| `INVALIDATED` / `REPLACED` | grey | (muted) |
|
||||||
|
| `CONFIRMED` | green | (confirmed on server / chain) |
|
||||||
|
| `COMPLETE` (signed, **not** yet pushed) | blue | `#2bc8ed` |
|
||||||
|
| `VALID` (prepared, not signed) | default | — |
|
||||||
|
|
||||||
|
> **Note (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 server‑checked.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. The decision flow
|
||||||
|
|
||||||
|
When you press **Prepare** (or on the periodic **Check**, or when Electrum
|
||||||
|
closes), BAL runs `is_will_valid`. Depending on what it finds it raises a
|
||||||
|
specific exception, and each exception maps to one action.
|
||||||
|
|
||||||
|
> 📊 A styled version of this guide (with a live diagram) is in
|
||||||
|
> [`inheritance-options.html`](./inheritance-options.html) — open it via GitHub
|
||||||
|
> Pages or download and open it in any browser.
|
||||||
|
|
||||||
|
The static diagram below renders everywhere; the Mermaid block after it renders
|
||||||
|
live on GitHub.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
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<br/>in the future?}
|
||||||
|
C -- No, it's in the past --> INV1[[Invalidate on-chain<br/>CheckAliveError]]
|
||||||
|
C -- Yes --> D{Any VALID tx with<br/>locktime earlier than<br/>the new date?}
|
||||||
|
|
||||||
|
D -- "Yes (you moved the date EARLIER / anticipate)" --> E{Was that tx already<br/>signed or sent?}
|
||||||
|
E -- "Not signed yet" --> R1[[Rebuild only<br/>no on-chain cost]]
|
||||||
|
E -- "Signed / sent" --> INV2[[Invalidate on-chain FIRST<br/>WillExpired]]
|
||||||
|
|
||||||
|
D -- "No" --> F{Will-executor / fee /<br/>heirs unchanged?}
|
||||||
|
F -- "Fee changed" --> R2[[Rebuild<br/>TxFeesChanged]]
|
||||||
|
F -- "Will-executor changed/absent" --> R3[[Rebuild<br/>WillExecutorNotPresent / Change]]
|
||||||
|
F -- "Heir added or removed,<br/>% or address changed" --> G{Is it a POSTPONE of an<br/>already signed/sent tx?}
|
||||||
|
|
||||||
|
G -- "Yes (date later + signed/sent)" --> INV3[[Invalidate on-chain FIRST,<br/>then rebuild — WillPostponed]]
|
||||||
|
G -- "No (never signed, or pure heir/% change)" --> R4[[Rebuild only<br/>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<br/>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
|
||||||
|
|
||||||
|
The locktime is the future moment from which a transaction becomes spendable by
|
||||||
|
the heir. BAL compares the **requested** locktime against the locktime
|
||||||
|
**frozen inside the already‑signed transaction** (`w.tx.locktime`), which is
|
||||||
|
exactly what the will‑executors hold — not the in‑memory copy.
|
||||||
|
|
||||||
|
| You do… | Tx already signed/sent? | Result | On‑chain fee? |
|
||||||
|
|---|---|---|---|
|
||||||
|
| **Move date LATER** (postpone) | **No** (never signed) | Plain **rebuild** (`HeirNotFound` fall‑through) | **No** |
|
||||||
|
| **Move date LATER** (postpone) | **Yes** | **Invalidate first**, then rebuild (`WillPostponed`) | **Yes** |
|
||||||
|
| **Move date EARLIER** (anticipate) | any | Old tx becomes **expired** → **invalidate** (`WillExpired`) | **Yes** |
|
||||||
|
| Check‑Alive threshold already passed | — | **Invalidate** (`CheckAliveError`) | **Yes** |
|
||||||
|
|
||||||
|
> **Why postpone needs an on‑chain invalidation:** the will‑executor still holds
|
||||||
|
> the *old* transaction with the *earlier* locktime. If you simply re‑signed a
|
||||||
|
> later one, a malicious or buggy executor could still broadcast the old one as
|
||||||
|
> soon as its earlier locktime is reached — executing your inheritance too soon.
|
||||||
|
> Spending the old transaction's inputs on‑chain makes the old tx **un‑minable**.
|
||||||
|
> The plugin tells you this explicitly and offers to build the invalidation tx.
|
||||||
|
|
||||||
|
> **Why anticipate is also on‑chain:** moving the date earlier makes the current
|
||||||
|
> committed tx *expired* relative to the new check date; the safe path is the
|
||||||
|
> same — invalidate, then rebuild.
|
||||||
|
|
||||||
|
### 4.2 Adding an heir
|
||||||
|
|
||||||
|
`check_willexecutors_and_heirs` walks every heir in the current set; an heir
|
||||||
|
present in `heirs` but not yet found in the will raises **`HeirNotFoundException`**.
|
||||||
|
|
||||||
|
- **Result:** **rebuild** (re‑prepare + re‑sign).
|
||||||
|
- **On‑chain fee:** **No** — *unless* the will being changed was already
|
||||||
|
signed/sent and the change also moves a locktime later (then the postpone rule
|
||||||
|
in 4.1 applies).
|
||||||
|
|
||||||
|
### 4.3 Removing an heir
|
||||||
|
|
||||||
|
The will still carries an heir that is no longer in your current heirs set →
|
||||||
|
**`HeirNotFoundException`** (the removed‑heir branch).
|
||||||
|
|
||||||
|
- **Result:** **rebuild**, so the removed heir disappears from the new
|
||||||
|
transactions.
|
||||||
|
- **On‑chain fee:** **No** for a will that was only *prepared*. If the old will
|
||||||
|
was already signed/sent, you must invalidate it on‑chain first (same safety
|
||||||
|
reasoning as a postpone), then rebuild.
|
||||||
|
|
||||||
|
> **v0.3.2 fix:** removing an heir is now correctly detected on **Check** and on
|
||||||
|
> Electrum **close**, not only on Prepare.
|
||||||
|
|
||||||
|
### 4.4 Changing an heir's percentage or address
|
||||||
|
|
||||||
|
If the stored heir `[address, amount/percentage]` differs from the current one,
|
||||||
|
the will is no longer coherent → it is treated like an heir change
|
||||||
|
(**`HeirChangeException`** / `HeirNotFound`).
|
||||||
|
|
||||||
|
- **Result:** **rebuild** with the new amounts.
|
||||||
|
- **On‑chain fee:** **No** (unless the old will was signed/sent → invalidate
|
||||||
|
first).
|
||||||
|
|
||||||
|
> Reminder shown by the plugin: *“In the inheritance process the entire wallet is
|
||||||
|
> always fully emptied”* — the amounts across all heirs must add up so that the
|
||||||
|
> whole spendable balance is distributed; otherwise an `AmountException` warns you
|
||||||
|
> to adjust.
|
||||||
|
|
||||||
|
### 4.5 Changing the transaction fee (sat/byte)
|
||||||
|
|
||||||
|
Each will item stores the fee rate it was built with. A different rate raises
|
||||||
|
**`TxFeesChangedException`**.
|
||||||
|
|
||||||
|
- **Result:** **rebuild** at the new fee rate.
|
||||||
|
- **On‑chain fee:** **No** to rebuild (you only pay when the inheritance — or an
|
||||||
|
invalidation — is actually broadcast on‑chain).
|
||||||
|
|
||||||
|
### 4.6 Changing or removing a will‑executor
|
||||||
|
|
||||||
|
- A selected will‑executor that the will does not reference raises
|
||||||
|
**`WillExecutorNotPresent`**.
|
||||||
|
- A will‑executor whose details changed raises **`WillexecutorChangeException`**.
|
||||||
|
- Running with “no will‑executor” but no backup transaction raises
|
||||||
|
**`NoWillExecutorNotPresent`**.
|
||||||
|
|
||||||
|
- **Result:** **rebuild** and re‑distribute to the (new) executor set.
|
||||||
|
- **On‑chain fee:** **No** to rebuild. The new signed transactions are simply
|
||||||
|
pushed to the new/updated executors; the old executor will eventually fail its
|
||||||
|
own check and drop the obsolete tx.
|
||||||
|
|
||||||
|
### 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** — your will
|
||||||
|
stays exactly as broadcast to the executors.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. What happens on the will‑executor servers
|
||||||
|
|
||||||
|
| Your action | Effect on the servers |
|
||||||
|
|---|---|
|
||||||
|
| **Prepare** (rebuild) | Nothing yet — new txs exist only locally until you Sign + Broadcast. |
|
||||||
|
| **Sign** | Still local; tx becomes `COMPLETE` (blue). |
|
||||||
|
| **Broadcast to executors** | The signed txs are 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 Bitcoin network. Once confirmed, the executor's stored tx can no longer be mined; on the next check it is dropped / shown invalidated. |
|
||||||
|
| **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 a will‑executor that
|
||||||
|
> *should* hold your transaction did not return it — re‑Broadcast, or rebuild,
|
||||||
|
> to fix it. A row that is merely **blue** is signed‑but‑not‑yet‑sent and is
|
||||||
|
> perfectly normal.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Quick reference — does it cost a Bitcoin fee?
|
||||||
|
|
||||||
|
| Change | Rebuild? | On‑chain invalidation (real fee)? |
|
||||||
|
|---|---|---|
|
||||||
|
| Add heir (will only prepared) | ✅ | ❌ |
|
||||||
|
| Remove heir (will only prepared) | ✅ | ❌ |
|
||||||
|
| Change % / address (only prepared) | ✅ | ❌ |
|
||||||
|
| Change fee rate | ✅ | ❌ |
|
||||||
|
| Change / remove will‑executor | ✅ | ❌ |
|
||||||
|
| Move date **earlier** (anticipate) | ✅ after | ✅ **yes** |
|
||||||
|
| Move date **later** (postpone) — will **signed/sent** | ✅ after | ✅ **yes** |
|
||||||
|
| Move date **later** (postpone) — will **only prepared** | ✅ | ❌ |
|
||||||
|
| Check‑Alive threshold already in the past | ✅ after | ✅ **yes** |
|
||||||
|
| Any change to an **already signed/sent** will | ✅ after | ✅ **yes** (invalidate first) |
|
||||||
|
| Nothing changed | ❌ | ❌ |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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 otherwise replacing it requires
|
||||||
|
an **on‑chain invalidation first** (a small Bitcoin fee) so an old transaction
|
||||||
|
can never be executed early.
|
||||||
|
3. Always finish with **Sign → Broadcast → Check** so the will‑executors hold the
|
||||||
|
*current* plan (green), not an obsolete one.
|
||||||
|
4. The wallet is always **fully emptied** by the inheritance, so heir amounts must
|
||||||
|
add up.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*This document reflects BAL plugin v0.3.3. Behaviour is derived directly from
|
||||||
|
`core/will.py` and `gui/qt/window.py`.*
|
||||||
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