bal-electrum-plugin/QML_PLAN.md

# QML PLAN — BAL on Electrum QML / Android (Option B: minimal viable support)

> Goal: let Android users (Electrum QML GUI) use BAL. **The Android device is
> the OFFLINE SIGNING DEVICE**: its primary job is to receive unsigned will
> transactions from an online machine (desktop/another phone), sign them with
> the wallet keys held on it, and return the signed transactions — a classic
> air-gapped signer workflow. Online features (willexecutor contact,
> broadcast, build) are secondary on Android and belong mainly to the online
> machine.
> Strategy: a *third frontend* (`bal/gui/qml/`) that reuses `bal/core` logic
> through the existing GUI-free `BalController`, exactly like `bal/cli/`
> already does. The PyQt6 desktop GUI remains untouched and primary.
>
> Status: DRAFT for owner review (rule R4 — no code until explicit OK).
> Chat language: Italian; this document is in English per rule R1.

---

## 1. Verified facts (research done on the local checkouts)

All items below were verified by reading source, not assumed.

| # | Fact | Where |
|---|------|-------|
| F1 | The fork's Electrum ships a full QML GUI built on **PyQt6.QtQml** (PyQt6 6.11 installed in runtime env imports `QtQml`/`QtQuick` fine). | `electrum/electrum/gui/qml/` |
| F2 | The QML GUI has a **plugin mechanism**: manifest `"available_for"` must contain `"qml"`; Electrum then loads `<plugin>/qml.py` and calls the `init_qml(app)` hook. | `electrum/plugin.py` (`load_plugin_by_name`, gui_name), `gui/qml/__init__.py:88` |
| F3 | On load, `main.qml` reads `plugin.so.loader` and auto-creates the component from `<plugins>/<name>/qml/<loader>.qml`. The plugin itself sets `.so` (a `PluginQObject`). Canonical example: `electrum/plugins/labels/qml.py`. | `gui/qml/components/main.qml` (`onPluginLoaded`), `gui/common_qt/plugins.py` |
| F4 | The plugin must support **both** target versions: the QML GUI + `common_qt/plugins.py` exist in the 4.7.x line too (verified on the local 4.7.0 checkout). Exact 4.7.2 parity is Phase-0 task T1. | `$BAL_HOME/electrum470/electrum/gui/{qml,common_qt}` |
| F5 | `BalController(plugin, wallet)` is GUI-free, per-wallet, and already implements state init + sign/build/broadcast flows against the bare `wallet` object (no `ElectrumWindow` needed). This is the reuse cornerstone of this plan. | `bal/cli/controller.py:119-175`, `sign_transactions` at :646 |
| F6 | In the repo, `bal` is already symlinked into the Electrum tree as an **internal** plugin: `electrum/electrum/plugins/bal -> ../../../bal-electrum-plugin/bal`. Internal plugins are plain files on disk → the QML engine can load `.qml` assets directly. | `ls -la electrum/electrum/plugins/` |
| F7 | The APK build spec lists packaged plugins explicitly and **BAL is not yet in that list**. | `electrum/contrib/android/buildozer_qml.spec:34-48` |
| F8 | The QML Preferences page has **hardcoded toggles only** for `labels` and `psbt_nostr`; there is no generic plugin manager UI. Plugin enabling works via config regardless (`plugins.bal.enabled = true`). | `gui/qml/components/Preferences.qml:168,186,511-512` |
| F9 | Extension points inside the QML app are minimal: `run_hook('init_qml', app)`, `run_hook('load_wallet', wallet)` (**one** argument, unlike Qt's two), `get_tx_extra_fee`, `tc_sign_wrapper`, and one named-component injection slot (`pluginsComponentsByName('export_tx_button')`). No tools menu, no status bar. | grep over `gui/qml/*.py`, `main.qml:778` |
| F10 | External ZIP plugins cannot serve `.qml` files from inside the zip (zipimport exposes Python modules only; `Qt.resolvedUrl` needs real disk paths). Distribution as internal plugin (F6) or runtime extraction avoids this. | consequence of F3 |
| F11 | Core signing path used by the CLI controller calls `wallet.sign_transaction(tx, password)` and updates signature counts — identical flow works under `QEWallet.wallet`. | `bal/cli/controller.py:646-700` |

---

## 2. Scope

### In scope (MVP)

Two usage **profiles** share one codebase:

- **Offline signer profile** (Android, PRIORITY): works with no network.
  1. Import a will bundle exported by the online machine (existing JSON will
     format, see F12) — via file share, paste, or QR.
  2. Review what is being signed (destinations, amounts, locktimes, fees).
  3. Sign internally (`wallet.sign_transaction` + password prompt).
     Partial signatures are combined when the bundle is re-imported
     (`combine_with_other_psbt`, already supported by `merge_will` logic).
  4. Export the signed bundle back to the online machine.
- **Online manager profile** (desktop QML, secondary):
  - Will status overview (state, expiry/check-alive date, reminder info).
  - Heirs list (view/add/edit/remove, addresses or URIs).
  - Will-executor selection (list, enable/disable, fee display, refresh).
  - Build will (simplified wizard reusing core validation).
  - Sign in place (password) or hand off to an offline signer via bundles.
  - Broadcast / push to will-executors; invalidate will; check-alive refresh.
  - Basic settings mapped onto `will_settings`.

The offline signer pages are built first and must function with the network
disabled (Electrum runs fine offline; willexecutor refresh simply degrades).

Also in scope:

- Android packaging: BAL bundled as internal plugin in the custom APK,
  **enabled by default** (owner decision D3).
- Keep desktop (`qt`) and CLI (`cmdline`) behavior byte-for-byte unchanged.

### Out of scope (explicitly deferred)

- Full parity with the PyQt6 GUI (calendar widget, preview list editor,
  advanced fee controls, themes).
- External-ZIP distribution of QML assets (F10 workaround postponed; ZIP
  builds keep working for desktop exactly as today, without `qml` UI).
- iOS, upstream-Electrum (spesmilo) compatibility.
- Lightning-related features (irrelevant to BAL).

---

## 3. Architecture

```
                 ┌───────────────────────────────────────────┐
                 │                bal/core                   │
                 │ heirs, will, willexecutors, checkalive,   │
                 │ reminders, input_rules, plugin_base       │
                 └────────────┬──────────────────────────────┘
                              │ (no Qt anywhere)
        ┌─────────────────────┼──────────────────────┐
        ▼                     ▼                      ▼
  bal/gui/qt/            bal/cli/               bal/gui/qml/   ← NEW
  BalWindow etc.      BalController            qml_plugin.py  (BalQmlPlugin)
  (~9.3k lines)       (headless flows)         models.py      (QObject VMs)
                                               so.py          (PluginQObject)
                                               *.qml          (views)
                                                      ▲
                                              wraps ONE BalController
                                              per loaded wallet
```

Design rules:

- **Reuse, do not duplicate.** `bal/gui/qml/models.py` holds thin QObject
  wrappers around one `BalController` instance per wallet. No business logic
  in QML or in the wrappers beyond formatting.
- **Same persistence.** Wallet DB dicts (`heirs`, `will`, `will_settings`)
  are registered by `bal/core/plugin_base.py` already; QML reads/writes them
  through the controller, so a wallet moves between desktop/Android unchanged.
- **Threading.** Network operations (willexecutor fetch/push, broadcast)
  run in worker threads exactly as the CLI does; results marshalled to the UI
  thread via Qt signals on the wrapper objects. No blocking calls in slots.
- **One transfer format.** The airgap round trip reuses the existing JSON
  will serialization (`WillItem.to_dict()` maps, exactly what the Qt GUI's
  `export_json_file`/`import` + `merge_will` flow already produces and
  consumes — see F12). No new format is invented; export/merge logic gets a
  single shared home usable by both frontends.
- **Version gating.** Every import of `electrum.gui.qml.*` happens lazily and
  defensively; if absent (e.g., odd build), the plugin degrades to core-only
  behavior instead of crashing the daemon.

---

## 4. Work breakdown

### Phase 0 — Verification spikes (no product code)

| Task | Description | Exit criterion |
|------|-------------|----------------|
| T1 | Diff `gui/qml` + `gui/common_qt` between the 4.7.0 checkout here and current 4.8.x, focused on: `PluginQObject`, `init_qml` hook call sites, `onPluginLoaded` handler, `load_wallet` hook arity. If 4.7.2 differs, note shims needed. | Written compatibility note appended to COMPATIBILITY.md draft section |
| T2 | Run desktop QML GUI headless with BAL enabled via config: `QT_QPA_PLATFORM=offscreen run_electrum -g qml` with `plugins.bal.enabled=true`, manifest updated ad-hoc (throwaway branch). Confirms discovery/loading path end-to-end before writing any code. | Log shows `init_qml` called for bal; no crash |
| T3 | APK feasibility: add `electrum/plugins/bal` to `buildozer_qml.spec` package list locally, confirm p4a includes `.qml` data files and icons (may need `source.include_exts` adjustment). Do NOT ship. | Test APK contains `plugins/bal/qml/*.qml` |
| T4 | Decide entry-point UX given F9 (no menu hook): candidate = tiny patch in fork's `main.qml` adding a "BAL" item in the wallet drawer/menu that opens our window object from `app.pluginobjects['bal']`. Confirm with owner. | Decision recorded in this file |

Deliverable: short findings report appended to this document; go/no-go.

### Phase 1 — Skeleton integration

Files (all NEW unless noted):

```
bal/qml.py                     zipimport-style shim mirroring qt.py/cmdline.py
bal/gui/qml/__init__.py        package docstring
bal/gui/qml/qml_plugin.py      class BalQmlPlugin(BalPluginBase)
bal/gui/qml/so.py              class BalSignalObject(PluginQObject)
bal/manifest.json              MODIFIED: available_for += ["qml"]
```

Details:

- `qml_plugin.py`:
  - `@hook init_qml(self, app)`: store app ref; create `so` parented to app;
    for each already-loaded wallet call `_on_wallet_loaded(wallet)`
    (mirrors labels' pattern, see F3).
  - `@hook load_wallet(self, wallet)` — **single argument** (F9); creates the
    per-wallet view-model bundle (Phase 2) keyed by `wallet`.
  - `@hook unload_wallet(self, wallet)`: drop controllers, close windows.
- `so.py`: `BalSignalObject(PluginQObject)` exposing:
  - `loader` property returning `"BalMain.qml"` (drives F3 auto-create);
  - signals: `walletChanged`, `willStateChanged`, `heirsChanged`,
    `willexecutorsChanged`, `busyChanged`;
  - slots called from QML: open/close window, refresh willexecutors,
    check-alive now, build/sign/broadcast/invalidate commands.
- `manifest.json`: append `"qml"` to `available_for`. Desktop untouched
  (Electrum filters per running GUI, verified F2).

Exit criterion: with `-g qml`, plugin loads, `so.loader` component is created
(log line from `onPluginLoaded`), no functional UI yet.

### Phase 2 — View-models (QObject layer)

New file `bal/gui/qml/models.py`:

- `BalQmlWallet(QObject)`: owns one `BalController`; exposes read-only
  properties (`willState`, `dateToCheck`, `expired`, `reminderInfo`,
  `sigsHave/sigsRequired` per tx) + notification signals; forwards actions to
  controller methods (`build_will`, `sign_transactions`, `broadcast_will`,
  `invalidate_will_headless`, `check_alive`... — names per controller).
  - **Airgap methods (priority):** `export_will_bundle()` and
    `import_will_bundle(json_text)` returning summary of what changed. These
    are small ports of the Qt GUI's `export_json_file` (window.py:1605) and
    `merge_will` (window.py:1620) semantics. Preferred implementation: move
    the logic into shared helpers (controller level or `bal/core/will.py`
    static functions) and make the Qt GUI call the same helpers, so the two
    frontends cannot diverge; regression-covered by existing core tests plus
    new round-trip tests.
  - Offline profile detection: expose an `isOffline` property derived from
    `wallet.network is None` / config, so QML can hide online-only pages.
- `HeirListModel(QAbstractListModel)`: roles `name`, `address`, `amountPct`,
  `valid`; edit methods delegate to `Heirs` helpers through controller.
- `WillTxListModel(QAbstractListModel)`: roles `txid`, `status`, `fee`,
  `sigsHave`, `sigsRequired`, `isComplete`.
- `WillExecutorListModel(QAbstractListModel)`: roles `url`, `selected`,
  `fee`, `valid`; toggle + async refresh.
- `BalQrTransferModel(QObject)`: thin scheduler over the shared transfer
  planner `bal.core.qrtransfer` (already battle-tested by the desktop Qt
  plugin, P1-P4). Exposes `encode(items)` → frames, `frameAt(i)` (data URL /
  pixmap for QML), `decode(text)` → tx list, `total`, `current`, presets;
  re-emits a `frameChanged` notifier so the QML page can step 1..N. No QR
  rendering inside the model (QML paints it).
- All list mutations happen on the controller state then `beginResetModel/
  endResetModel` (datasets are small; simplicity over incremental updates).

Exit criterion: pytest-driven model tests pass offscreen (create models over a
regtest/testnet wallet fixture, assert roles after mutations).

### Phase 3 — QML views

New directory `bal/gui/qml/components/`:

```
BalMain.qml            top-level Window; stack of pages below
BalSignPage.qml        PRIORITY (offline signer): import bundle
                       (paste / file / QR), review summary of each tx,
                       password-sign, export signed bundle back
BalQrExportPage.qml    QR export view: drives BalQrTransferModel, one
                       frame at a time (Prev/Next, progress i/N, chunk
                       preset selector), mirror of desktop Qt dialog
BalQrImportPage.qml    QR import view: slot grid (1..N), camera via
                       Electrum `QRScan` reuse, manual paste fallback,
                       then jump into BalSignPage review/sign
BalStatusPage.qml      will state, expiry countdown, check-alive button
                       (works offline with last-known data)
BalHeirsPage.qml       ListView + add/edit dialog            [online profile]
BalExecutorsPage.qml   ListView with switches + refresh      [online profile]
BalBuildPage.qml       simplified build form (threshold selector, fees,
                       executor pick) → runs controller.build_will
                                                              [online profile]
BalSettingsPage.qml    maps onto will_settings subset
controls/BalButton.qml, BalField.qml   minimal styled primitives
qmldir                 module registration
```

Notes:

- **BalSignPage review screen is mandatory**: before signing, the user must
  see per-transaction heir address, amount, locktime (date), and fee — this
  device is the security boundary, so no "blind signing".
- QR transfer: a full will bundle may exceed one QR's capacity when there are
  many heirs/transactions. The desktop Qt plugin now resolves this with
  chunked multi-QR streams (`bal/core/qrtransfer.py`, chunk presets
  150/400/900/1800 bytes/frame, EC level M); the QML GUI reuses the same
  scheduler via a thin model. Order of preference stays (1) share/save file +
  paste text; (2) chunked QR streams through `BalQrTransferModel`.
- Styling minimal, follow existing QML components' look (reuse
  `controls/` from Electrum where importable — prefer copying tiny primitives
  to avoid coupling to upstream churn; decide during implementation).
- Every string wrapped with `electrum.i18n._`.

Exit criterion: full manual walkthrough on desktop QML GUI (offscreen +
interactive) performing BOTH: (a) online profile — configure heirs → select
executors → build → sign → broadcast → invalidate; and (b) offline signer
profile — export unsigned bundle from an online wallet, import into a second
offline wallet instance, sign, re-export, import signed bundle back into the
first wallet and verify signatures combined/status COMPLETE. Walkthrough (b)
must pass with networking disabled.

### Phase 4 — Android integration

- Add `electrum/plugins/bal` (+ data extensions for `.qml`, `icons/*`) to
  `contrib/android/buildozer_qml.spec` in the Electrum fork.
- Patch fork's `Preferences.qml` with a BAL toggle **(owner approved, D1)**
  and default-enable BAL in the APK build (D3: enabled by default).
- Entry point per T4 decision (menu/drawer patch in fork's `main.qml`, D1
  approved). Fallback if T4 picks auto-open: window opens on wallet load.
- Rebuild APK; smoke-test on device/emulator:
  install → BAL already enabled → open wallet → full MVP walkthrough,
  including airplane-mode signing round trip (file/QR transfer between an
  online desktop and the offline device — for emulator testing, "offline" =
  network disabled via settings).
- Watch-outs: filesystem paths (use `os.path.join`, no hardcoded separators —
  already house style), background network on mobile (willexecutor timeouts),
  APK size impact (bal is small; icons only), share-intent/file access
  permissions for bundle import/export.

Exit criterion: signed test APK passes the same walkthrough as Phase 3.

### Phase 5 — Tests & CI hygiene

- New tests following repo conventions (`def test_*` + `__main__` block):
  - `tests/test_qml_models.py` — models over fake/controller-backed wallet
    (offscreen, no network).
  - `tests/test_qml_airgap_roundtrip.py` — PRIORITY: export unsigned bundle
    from wallet A → import into wallet B (same seed, offline) → sign →
    export signed → merge back into A; assert COMPLETE status and signature
    counts. Must pass with no network.
  - `tests/test_qml_plugin_loading.py` — plugin instantiates under a stubbed
    QML app object; `so` wiring correct; load/unload wallet lifecycle.
  - Extend `tests/smoke_test.py` usage: `QT_QPA_PLATFORM=offscreen python3
    tests/smoke_test.py electrum.plugins.bal` still green (qt path intact).
- Regression gate: full `tests/test_core_*.py` batch + ruff (no NEW
  violations) before any delivery ZIP.
- Manual matrix recorded in CHANGELOG entry: [desktop qt, desktop qml
  offscreen, Android APK] × [4.7.2, 4.8.0] where applicable.

### Phase 6 — Release plumbing & docs

- `build_zip.py`: ensure new `bal/gui/qml/**` and `components/*.qml` included
  in deterministic zip (harmless on desktop; enables future extraction-based
  loading).
- `COMPATIBILITY.md`, `README.md`, `HANDOFF.md`: document QML/Android status,
  limitations, and how to enable (`-g qml` / APK toggle).
- `CHANGELOG.md`: numbered entry at END per house rules.
- Version bump + release handled by `make-release.sh` as usual (owner-driven).

---

## 5. Risks & mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| R1: 4.7.2 vs 4.8 QML internals drift | broken load on one version | Phase-0 T1 diff first; lazy imports + capability checks; shim module if needed |
| R2: no generic plugin UI in QML (F8) | users can't enable BAL from UI | config default-enable in fork APK; small Preferences.qml patch in fork (we control it); document manual config for desktop |
| R3: no natural entry point in main.qml (F9) | user can't find/open BAL window | T4 decision: fork-side menu/drawer patch; fallback = auto-open window on wallet load behind a setting |
| R4: dual-GUI maintenance burden | long-term cost | strict reuse of `BalController`; QML layer forbidden from business logic (review rule); parity features stay in qt GUI |
| R5: threading bugs on mobile networks | ANRs/crashes | all network ops in threads like CLI; signals-only UI updates; timeouts already configurable |
| R6: airgap transfer friction (bundle size vs QR capacity, share permissions on Android) | users cannot move bundles reliably | desktop Qt: chunked multi-QR streams + audio-modem optional channel shipped (P1-P4) and regression-gated; QML: file share + paste first, QR via `BalQrTransferModel` (Phase 2/3 notes); Android camera on Qt6 is known-flaky, file/paste stays the primary mobile fallback and is tested first in Phase 4 |
| R7: export/merge semantics divergence between frontends | signed bundles rejected or double-counted | single shared helper used by qt GUI and qml layer (Phase 2); round-trip regression test |
| R8: hidden coupling of qt code into shared modules | qml import pulls QtWidgets | lint guard idea: import-linter/ruff rule forbidding `PyQt6.QtWidgets` under `bal/gui/qml/` |
| R9: zip distribution ambiguity (F10) | confusion about what ships where | clear policy: ZIP = desktop qt+cmdline only; QML requires internal-plugin/APK route (Phase 6 documents this) |
| R10: unknown Android/Electrum baseline (owner to confirm, OQ4) | wrong Qt/PyQt6 assumptions in APK build | Phase-0 T3 builds against the fork's current toolchain; code keeps 4.7.x/4.8.x dual support so the answer can arrive late without rework |

---

## 6. Questions for the owner — ANSWERED (2026-08-25)

1. **Fork patches (T4/R3):** ✅ **D1 — APPROVED.** Patching the fork's
   `main.qml`/`Preferences.qml` is allowed for the BAL menu entry and toggle.
2. **Offline signing topology:** ✅ **D2 — Android IS the offline device.**
   The phone holds the keys and acts as air-gapped signer: import unsigned
   bundle → review → sign → export signed bundle back to the online machine.
   The sign/import/export page is therefore the top priority of Phase 3, and
   the round-trip test is the top priority of Phase 5.
3. **Enable-by-default:** ✅ **D3 — BAL pre-enabled in the custom APK**
   (toggle still available to disable).
4. **Target Android/Electrum baseline:** ⏳ **OPEN (OQ4)** — owner will get
   back later. Not blocking: see risk R10 mitigation.

---

## 7. Effort estimate

| Phase | Rough size |
|-------|-----------|
| 0 spikes | ~half day (mostly reading + one throwaway branch) |
| 1 skeleton | ~300 lines Python |
| 2 models (incl. shared export/merge helpers) | ~600–800 lines Python |
| 3 views (offline signer page first) | ~900–1300 lines QML |
| 4 android | fork-side patches + build iteration (device-dependent) |
| 5 tests | ~500 lines |
| 6 release/docs | small |

Overall: comparable to a medium feature, dominated by Phase 3 UI polish and
Phase 4 device iteration.

---

## 8. Findings log (append-only)

- **F12** — The airgap round trip already exists in the Qt GUI layer and can
  be ported almost verbatim: `export_json_file()` (window.py:1605) exports
  all will items as `{wid: WillItem.to_dict()}` JSON (marking them
  `EXPORTED`); the import side goes through `merge_will()`
  (window.py:1620), which carries operational statuses, combines partial
  signatures via `tx.combine_with_other_psbt()` when txids match, substitutes
  the tx otherwise, and recomputes validity locally without network.
  Conclusion: no new transfer format is needed; the plan is to give this
  logic a shared home (controller/core) so Qt, CLI-adjacent tooling and QML
  all use one implementation.

### Decisions

- **D1** — Fork-side patches to `main.qml` / `Preferences.qml` approved by
  the owner.
- **D2** — Android = offline signing device; sign/import/export flow has
  top priority.
- **D3** — BAL enabled by default in the custom APK.
- **OQ4** — Android/Electrum baseline: open, non-blocking (see R10).