Merge pull request 'Add COMPATIBILITY_ROADMAP.md - multisig and TrustedCoin analysis' (#6) from SAFE21.io/bal-electrum-plugin:update-compat-docs into main

Reviewed-on: #6

CHANGELOG.md

@@ -2329,3 +2329,23 @@ The request was to make the failure message clearer (no timeout change).
 - `ruff`: no new errors.
 
 **Outcome:** DONE (delivered as test ZIP v0.5.18; commit only after confirmation).
+
+---
+
+## 43. v0.6.0 - Version bump for the official repository release
+
+**Date:** 2026-07-17
+
+**Context:** the plugin content of this version is IDENTICAL to v0.5.18 - no code
+changes. A release was published on the official repository
+(bitcoinafterlife/bal-electrum-plugin) tagged "v0.6.0", but the internal version
+files still read "0.5.18" (a human oversight: the release tag was not matched by
+a version bump in the code), so Electrum displayed "0.5.18" after installing it.
+This entry aligns the internal version with the intended "0.6.0" release tag by
+bumping `bal/VERSION`, `bal/manifest.json`, `bal/__init__.py` and
+`bal/core/plugin_base.py` from 0.5.18 to 0.6.0. No functional changes.
+
+**Verification:** full test suite against Electrum 4.7.2 and 4.8.0 (same 266
+passed / 2 pre-existing unrelated failures as v0.5.18); `ruff` clean.
+
+**Outcome:** DONE.

COMPATIBILITY.md

@@ -0,0 +1,30 @@
+# Wallet Compatibility
+
+BAL (Bitcoin After Life) builds and signs Electrum transactions using
+Electrum's own wallet and signing infrastructure. Its compatibility therefore
+depends on the wallet type in use.
+
+| Wallet type                                    | Status                     | Notes |
+|-------------------------------------------------|-----------------------------|-------|
+| Standard wallet (single-signature, seed-based)  | ✅ Supported                | Primary, fully tested target |
+| Hardware wallets (Ledger, Trezor, Coldcard, BitBox02, Jade, KeepKey, etc.) | ✅ Supported | Any hardware wallet supported by Electrum itself |
+| Multisig wallets                                | ❌ Not yet supported        | Known limitation identified 2026-07-18. Support is planned for a future plugin release. |
+| Electrum TrustedCoin (2FA) wallets              | ❓ Unknown / unsupported    | Known limitation identified 2026-07-18. It has not yet been determined whether or when this will be addressed. |
+
+## What "not supported" means in practice
+
+For multisig and TrustedCoin (2FA) wallets, BAL's behavior has not been
+verified and should be considered **unreliable**. Do not rely on BAL to
+protect an inheritance set up on one of these wallet types until this document
+is updated to mark them as supported.
+
+## Electrum version compatibility
+
+See [`README.md`](README.md) for supported Electrum versions (currently 4.7.2
+and 4.8.0).
+
+## Reporting compatibility issues
+
+If you find a compatibility problem not listed here, please open an issue on
+this repository describing the wallet type, Electrum version, and the exact
+error or unexpected behavior observed.

COMPATIBILITY_ROADMAP.md

@@ -0,0 +1,99 @@
+# Compatibility Roadmap: Multisig and TrustedCoin (2FA) Wallets
+
+Status document, 2026-07-19. Companion to [`COMPATIBILITY.md`](COMPATIBILITY.md):
+that file states *what* is supported today; this one explains *why* multisig and
+TrustedCoin (2FA) wallets are currently unsupported and *how* support can be
+added.
+
+## Root cause (common to both)
+
+BAL currently does two things that are only valid for standard
+(single-signature) wallets:
+
+1. **It builds transactions itself** with `PartialTransaction.from_io(...)`
+   (`bal/core/will.py`), bypassing `wallet.make_unsigned_transaction`.
+2. **It signs with a single call** — `wallet.sign_transaction(tx, password)`
+   (`bal/gui/qt/window.py`, `sign_transactions`) — and considers the will ready
+   when `tx.is_complete()` is true.
+
+On a standard wallet one signature completes the transaction. On multisig and
+2FA wallets **one signature is not enough**: the transaction stays incomplete,
+is never marked `COMPLETE`, and can never be pushed to will-executors.
+
+A secondary single-sig assumption: `plugin.py` uses `wallet.get_keystore()`
+(singular); multisig wallets expose `get_keystores()` (plural).
+
+## Multisig wallets — solvable, medium/large effort
+
+A 2-of-3 multisig wallet typically holds **only one** of the required private
+keys locally; the other cosigners hold theirs. `wallet.sign_transaction` adds
+the local signature only, and BAL has no flow to collect the missing ones.
+
+**Proposed solution: the standard PSBT coordination round** (the same flow
+Electrum itself uses for multisig spending):
+
+1. Build and sign locally as today.
+2. If the transaction is not complete, **export the partially-signed
+   transaction(s)** (file and/or QR) and mark the will with a new status such
+   as `WAITING_COSIGNERS`.
+3. Each cosigner signs in their own Electrum (native feature — no new
+   software needed on their side).
+4. BAL **re-imports and merges the signatures**; once complete, the will is
+   pushed to will-executors as today.
+
+Notes and caveats:
+
+- **Chained will transactions** (a will tx spending the change of a previous
+  will tx) remain workable: with segwit, the txid of an unsigned/partially
+  signed transaction is already stable, so the whole chain can be exported as
+  a batch of PSBTs in one round.
+- **Every rebuild requires a new cosigner round.** Check Alive postponements
+  and balance-change rebuilds re-sign the will, so each of them needs the
+  cosigners again. This is inherent to multisig and must be clearly
+  communicated in the UI.
+- Implementation surface: export/import/merge pipeline, GUI for it, the new
+  status in the transaction list, and tests.
+
+Target: **next plugin release**, as announced.
+
+## TrustedCoin (2FA) wallets — harder, with one blocking unknown
+
+An Electrum 2FA wallet (`Wallet_2fa`, defined in Electrum's `trustedcoin`
+plugin) is technically a **2-of-3 multisig whose second signer is the
+TrustedCoin server**:
+
+- signing requires a **one-time password (OTP) per transaction**
+  (`server.sign(short_id, raw_tx, otp)`);
+- the server co-signs only transactions that include **its billing fee**,
+  which Electrum adds inside `Wallet_2fa.make_unsigned_transaction` — a code
+  path BAL currently bypasses (see root cause #1).
+
+So today: no billing output, no OTP prompt, local signature only → incomplete
+transaction.
+
+Even with full integration (building via the wallet's
+`make_unsigned_transaction`, adding the OTP prompt flow), one **decisive
+unknown** remains: will transactions carry a **locktime years in the future**.
+Whether the TrustedCoin server agrees to co-sign a transaction with such a
+far-future `nLockTime` is an undocumented server-side policy. If it refuses,
+2FA support is **not achievable** without TrustedCoin's cooperation. This is
+why `COMPATIBILITY.md` marks 2FA as *unknown*.
+
+**Proposed plan:**
+
+1. **Empirical test on testnet** (cheap, decisive): create a test 2FA wallet,
+   build a far-future-locktime transaction through the proper 2FA path, and
+   check whether the server signs it.
+2. If it signs → implement support: build via `make_unsigned_transaction`
+   (billing output included), integrate the OTP prompt, and document that
+   every rebuild costs one OTP round and TrustedCoin fees.
+3. If it refuses → document 2FA as unsupported, with the practical
+   workaround: Electrum allows disabling 2FA by restoring the wallet from the
+   full seed, which turns it into a standard wallet — fully supported by BAL.
+
+## Recommended order of work
+
+1. **Multisig first**: deterministic path, standard Electrum tooling, already
+   announced for the next release.
+2. **TrustedCoin empirical test in parallel**: low cost, and its outcome
+   decides whether 2FA support is feasible at all.

README.md

@@ -38,10 +38,19 @@ tests/                   smoke + external-zip regression tests
 
 ## Requirements
 
-- **Electrum 4.7.2** — the last stable release exposing `json_db.register_dict`,
+- **Electrum 4.7.2 or 4.8.0** — the plugin detects which wallet-DB
-  which this plugin relies on. Newer versions removed it.
+  registration API is available (`json_db.register_dict` on 4.7.2,
+  `stored_dict.register_name` on 4.8.0) and adapts automatically.
 - **PyQt6** (bundled with the Electrum desktop GUI).
 
+## Wallet compatibility
+
+BAL currently supports **standard (single-signature) wallets** and
+**hardware wallets** supported by Electrum. **Multisig wallets** and
+**Electrum TrustedCoin (2FA) wallets** are **not yet supported** — see
+[`COMPATIBILITY.md`](COMPATIBILITY.md) for the full compatibility matrix and
+current status.
+
 ## Installation
 
 ### Build the distribution archive

bal/VERSION

@@ -1 +1 @@
-0.6.0
+0.5.18