bitcoinafterlife/bal-electrum-plugin
3
2
Fork 4
Code Issues Pull Requests Actions Packages Projects Releases 8 Wiki Activity

docs: align all markdown docs with current code (v0.6.1)

Browse Source 
- CHANGELOG: add entries #47 (is_selected/is_valid fee bounds, extremes allowed) and #48 (merge_will crash fix on missing date_to_check)
- HANDOFF: Electrum 4.7.2 and 4.8.0, current layout (qt.py, plugin.py, wallet_util/, docs/, bal_cli.py, 36-file ZIP), runtime/lint venv paths, standalone-script tests (427 collected), direct-to-main workflow, version history up to v0.6.1
- README: drop VERSION from layout, correct anticipate/expire/postpone behavior, update test commands
- docs/manual/README.md: fix Tools menu label to Will-Executors, add BASIC/ADVANCED notes, extend chromatic status table (Partially signed, Updated)
- docs/inheritance-options.md: add PARTIALLY_SIGNED status/transition/colour, version note to v0.6.1
- docs/README.md: make HTML-hosting instructions host-agnostic
- bal/README.md: Prepare button lives on the WILL tab
This commit is contained in:
svatantrya
2026-08-01 23:08:07 -04:00
parent 693479b0da
commit 1e80f7a0e0
7 changed files with 212 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/README.md
View File

@@ -6,11 +6,12 @@
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**.
HTML), so it renders directly on any forge (Gitea/GitHub) and in any browser —
**no PDF needed**.
## Contents
| Document | Markdown (GitHub) | Styled HTML |
| Document | Markdown | 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) |
@@ -23,9 +24,8 @@ HTML), so it renders directly on GitHub and via GitHub Pages — **no PDF needed
## 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`.
- Online: serve the `docs/` folder as static files (e.g. Pages on Gitea or
GitHub) and open `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).

9
docs/inheritance-options.md
View File

@@ -43,6 +43,7 @@ important ones:
|---|---|---|
| `VALID` | The item is the current, usable plan | default `True`; cleared by INVALIDATED/REPLACED/CONFIRMED/MEMPOOL |
| `COMPLETE` (*Signed*) | The transaction has been **signed** | after you press **Sign** |
| `PARTIALLY_SIGNED` | Only **some** of the required signatures are present | a multisig will after a partial sign (cleared by `COMPLETE`) |
| `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 |
@@ -65,6 +66,7 @@ Flag transitions enforced by `set_status` (the safety rules baked in the code):
- Setting `CONFIRMED` / `MEMPOOL` → clears `INVALIDATED`.
- Setting `PUSHED` → clears `PUSH_FAIL` **and** `CHECK_FAIL`.
- Setting `CHECKED` → implies `PUSHED` (and clears `PUSH_FAIL`).
- Setting `COMPLETE` → clears `PARTIALLY_SIGNED`.
### How states map to row colour in the list
@@ -83,7 +85,8 @@ wins:
| 7 | `CHECKED` | green | `#8afa6c` |
| 8 | `PUSH_FAIL` | red | `#e83845` |
| 9 | `PUSHED` | teal | `#73f3c8` |
| 10 | `COMPLETE` (signed, **not** yet pushed) | blue | `#2bc8ed` |
| 10 | `PARTIALLY_SIGNED` | amber | `#ffb347` |
| 11 | `COMPLETE` (signed, **not** yet pushed) | blue | `#2bc8ed` |
| — | none of the above (e.g. plain `VALID`, prepared) | default white | `#ffffff` |
> **Note (v0.3.3 fix):** a will that is *signed but not yet broadcast*
@@ -354,5 +357,5 @@ that limit.
---
*This document reflects BAL plugin v0.4.7. Behaviour is derived directly from
`core/will.py`, `core/heirs.py` and `gui/qt/window.py`.*
*This document reflects the current BAL plugin (v0.6.1). Behaviour is derived
directly from `core/will.py`, `core/heirs.py` and `gui/qt/window.py`.*

47
docs/manual/README.md
View File

@@ -76,6 +76,22 @@ inheritance cases.
*Figure 2 — the parameters on the HEIRS tab: (1) Delivery Time, (2) Check Alive,
(3) Fees.*
### User type: BASIC / ADVANCED
The plugin has two usage modes, chosen from the plugin settings
(**Tools → Plugins → BAL**, *User Type* selector):
- **BASIC** (default) — hides the advanced controls: the **Delivery Time** is
entered only as a precise **Date** (the relative **RAW** durations and the
Raw/Date selector are hidden), the **Check Alive** field is hidden, and the
postpone-on-open behaviour is disabled.
- **ADVANCED** — reveals the **Raw/Date selector** (relative durations such as
`1y` or `30d`) and the **Check Alive** field, and enables the postpone
behaviour described below. Switching to ADVANCED requires typing the
confirmation phrase **"at My Risk"**.
The rest of this section describes the full (ADVANCED) parameter set.
### 1 — Delivery Time (Locktime)
Indicates the date on which the inheritance of your wallet on the blockchain
@@ -94,6 +110,11 @@ If you choose **Raw**, you can insert various options based on a suffix:
*(i.e. check whether you are still alive, and then postpone the inheritance.)*
> **NB:** the **Check Alive** parameter is available only in **ADVANCED** mode.
> In **BASIC** (default) it is hidden and the plugin re-evaluates the will
> against "now" every time you open Electrum, so the postpone behaviour
> described here does not apply.
This parameter — settable as relative (`RAW`) or absolute (`DATE`) — indicates
the time by which the inheritance will **not** be changed by postponing it.
@@ -223,6 +244,9 @@ plugin will notify you that you need to update the inheritance.
## RAW settings
> **NB:** relative (**RAW**) durations are available only in **ADVANCED** mode;
> in **BASIC** the Delivery Time is entered only as a precise date.
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
@@ -239,7 +263,8 @@ with a tolerance of a few hours.
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.
previous month. *(The Check Alive only exists in **ADVANCED** mode; in
**BASIC** this is not needed.)*
---
@@ -335,7 +360,7 @@ inheritance:
## Will‑Executor service list
This window opens from the Electrum menu, **Tools → Will‑executor**, and shows
This window opens from the Electrum menu, **Tools → Will‑Executors**, and shows
the official list of will‑executor servers.
If you want to make changes — such as adding an additional will‑executor server —
@@ -409,14 +434,16 @@ transactions can have in the WILL tab, on each will‑executor that is online.
| # | 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` |
| 2 | **Partially signed** | TX has some, but not all, of the required signatures | Amber | `#FFB347` |
| 3 | **Signed** | TX inheritance signed into the wallet | Azure | `#2BC8ED` |
| 4 | **Pushed** | TX sent to will‑executor | Azure‑green | `#73F3C8` |
| 5 | **Checked** | TX actually present in the will‑executor | Bright green | `#8AFA6C` |
| 6 | **Confirmed** | TX confirmed in the blockchain | Gray | `#BFBFBF` |
| 7 | **Pending** | TX awaiting confirmation on blockchain | Yellow | `#FFCE30` |
| 8 | **Failed** | Communication failure with will‑executor | Red | `#E83845` |
| 9 | **Invalidated** | UTXO input is no longer available | Orange | `#F87838` |
| 10 | **Replaced** | A backdated‑locktime transaction spends the same input | Violet | `#FF97E9` |
| 11 | **Updated** | TX re‑issued keeping the same locktime and heirs | Light violet | `#B266B2` |
---