500 lines
28 KiB
Markdown
500 lines
28 KiB
Markdown
# PLAN — Will transfer via QR codes / audio modem (Qt now, QML planned)
|
||
|
||
> Goal: let the user move an inheritance ("will") between devices over two
|
||
> air-gap channels:
|
||
>
|
||
> 1. **QR codes** (primary): export the **valid** inheritance transactions as
|
||
> a sequence of QR codes, and import them back on another machine with the
|
||
> camera;
|
||
> 2. **Audio modem** (secondary, when Electrum's `audio_modem` plugin is
|
||
> enabled): send/receive the same payload through the PC speaker +
|
||
> microphone.
|
||
>
|
||
> Both channels converge on the same review-and-sign flow afterwards.
|
||
>
|
||
> Status: APPROVED by owner (2026-08-25). No code written yet — this document
|
||
> is the implementation contract. Work top-down through §9 Checklist.
|
||
>
|
||
> Chat language: Italian; this document is in English (global rule R1).
|
||
|
||
---
|
||
|
||
## 1. Scope
|
||
|
||
### In scope
|
||
|
||
- **Desktop PyQt6 GUI** (primary, implemented by this plan):
|
||
- New plugin setting: QR chunk size, offered as **4 standard presets**.
|
||
- *"Export via QR"* action: serializes the **valid** will transactions,
|
||
optionally compresses, splits the resulting string into fixed-size frames,
|
||
shows one QR at a time with prev/next navigation, live re-chunking and
|
||
progress (`i di N`).
|
||
- *"Import via QR"* action: camera capture dialog with a slot grid
|
||
(1..N); the user selects which shot he is about to capture, scans, the
|
||
frame lands in its slot; when 1..N are filled the payload is assembled,
|
||
parsed into `WillItem`s, validity-checked locally.
|
||
- **Post-capture flow (owner decision D6, amended)**: after capture
|
||
completes there is NO read-only preview. Instead a review-and-sign wizard
|
||
walks through every transaction one at a time showing **outputs
|
||
(address + amount), total outputs, total fees**, signs it (wallet
|
||
password asked once), and at the end **proposes exporting the signed
|
||
transactions** (to file and/or back via QR).
|
||
- **Audio-modem channel** (owner decision D7): when the Electrum
|
||
`audio_modem` plugin is enabled and available, the export dialog gains a
|
||
*"Send via Audio Modem…"* button and the import dialog a *"Receive via
|
||
Audio Modem…"* button, reusing the same transfer string (no QR framing).
|
||
- **QML**: document-only update to `QML_PLAN.md` adding dedicated view specs
|
||
(owner decision D1). No QML code in this feature.
|
||
|
||
### Out of scope
|
||
|
||
- Implementing the QML frontend (gated behind `QML_PLAN.md` Phases 0–2).
|
||
- Merging imported wills into the live wallet state (existing Merge flows
|
||
stay unchanged).
|
||
- Broadcast of the reviewed transactions (user exports them; broadcasting
|
||
remains an explicit action elsewhere).
|
||
- CLI/cmdline parity for QR transfer.
|
||
|
||
---
|
||
|
||
## 2. Owner decisions (locked)
|
||
|
||
| # | Decision |
|
||
|---|----------|
|
||
| D1 | QML part = update `QML_PLAN.md` document only; implementation later. |
|
||
| D2 | Frames carry a small **compact** ASCII header (`BAL1<total><index><flag>`, fixed 11 chars, base36 count fields) — import knows the total, auto-fills the grid, detects corrupt/duplicate/mismatched frames. Pure concatenation rejected. Legacy `BALQR1\|N\|i\|flags\|` export removed; legacy import kept. |
|
||
| D3 | Payload = **serialized transaction strings only** (`str(wi.tx)`), NOT the JSON will dump. Loses statuses/metadata on purpose; import rebuilds items like `merge_single_transaction` does. |
|
||
| D4 | Compression (zlib+base64 over the whole payload) exported as **best-of**: `encode_transfer_best` ships compressed when it is shorter, plain otherwise; flag `0` = plain, `Z` = compressed. No user-facing checkbox. |
|
||
| D5 | 4 standard size presets: **~150 / ~400 / ~900 / ~1800 bytes** of payload per QR (low-res cams → high-res cams). Error-correction level fixed **M**. Stored as plugin config default; selectable again inside the export dialog. |
|
||
| D6 | After capture completes: **review + sign each tx one at a time** (show outputs, total outputs, total fees), then **propose export of the signed txs** (file and/or QR). Supersedes the earlier "WillDetailDialog preview" answer. |
|
||
| D7 | Add an **audio-modem transfer path** gated on Electrum's `audio_modem` plugin being enabled and available (`amodem` importable). Same payload semantics as QR (transfer string of serialized txs), but NO BAL frame chunking — `amodem` handles transport framing internally. Buttons simply hidden when the plugin is absent/unavailable (info message pointing at `pip install amodem` when enabled-but-broken); graceful degradation, never a hard dependency. |
|
||
|
||
---
|
||
|
||
## 3. Verified facts (research done on the local checkouts)
|
||
|
||
All verified by reading source; references are `file:line`.
|
||
|
||
| # | Fact | Where |
|
||
|---|------|-------|
|
||
| F1 | Export today: `BalWindow.export_will()` writes `{wid: WillItem.to_dict()}` JSON; subsets All/Valid/Valid-NC built in `WillList` | `bal/gui/qt/window.py:1605-1621`, `lists.py:666-669, 743-767` |
|
||
| F2 | Batch signer: `BalWindow.sign_transactions(password, will, txids)` loops valid txs, resolves input values from change prevouts (`txin._trusted_value_sats` …), calls `wallet.sign_transaction`, updates `COMPLETE` + signature counts | `window.py:1017-1086` |
|
||
| F3 | External-will signing already supported (`will=` param, nothing saved to live wallet/history) | `window.py:1443-1484` |
|
||
| F4 | Single-tx import precedent: `merge_single_transaction` wraps `WillItem({"tx": str(tx)}, _id=tx.txid(), wallet=...)` | `window.py:1715-1724` |
|
||
| F5 | Local validity recomputation recipe (no network): `add_willtree` → `Util.get_available_utxos` → `check_invalidated` → `search_rai` → `check_signatures` | `window.py:1678-1701` |
|
||
| F6 | Plugin config accessor pattern `BalConfig`; keys declared in ctor | `bal/core/plugin_base.py:130-154, 211-264` |
|
||
| F7 | Plugin settings dialog: grid rows 0..12, `add_widget(grid,label,widget,row,help)` + `_make_reset_btn(cfgvar,widget,kind)`; ADVANCED-only rows wrapped with `_hide_if_basic(...)` | `bal/gui/qt/plugin.py:442-850` (rows at 677-850) |
|
||
| F8 | `BalDialog(parent, bal_plugin, title=None, icon=...)` base class anchors to top-level window | `bal/gui/qt/dialogs.py:92-129` |
|
||
| F9 | Fee display precedent: `fee = tx.input_value() - tx.output_value()`, fee rate = `fee / tx.estimated_size()` | `bal/gui/qt/widgets.py:1319-1328` |
|
||
| F10 | Input-value resolution helper exists: `Will.add_info_from_will(will, wid, wallet)` sets trusted input values from sibling will change outputs | `bal/core/will.py:118-136` |
|
||
| F11 | `str(tx)` = `tx.serialize()`: raw hex for complete txs; `PartialTransaction.serialize()` → base64 PSBT. Both accepted by `tx_from_any` (= `Will.get_tx_from_any`). This is exactly how BAL persists/reloads txs today | `electrum/transaction.py:907, 2539`; `will.py:106-113`; `window.py:1041-1044` |
|
||
| F12 | `QRCodeWidget` exists but **hardcodes `ERROR_CORRECT_L`** → cannot satisfy D5/M; must render our own `qrcode` instance | `electrum/gui/qt/qrcodewidget.py:35-37` |
|
||
| F13 | Camera scanning one-shot API with OS-permission handling: `scan_qrcode_from_camera(*, parent, config, callback(success: bool, error: str, data: Optional[str]))`; on Linux uses zbar CLI backend | `electrum/gui/qt/qrreader/__init__.py:47-64` |
|
||
| F14 | QR painting without PIL: `draw_qr(qr, paint_device, ...)` from `electrum.gui.common_qt.util` (what `QRCodeWidget.paintEvent` uses) | `electrum/gui/qt/qrcodewidget.py:63-72` |
|
||
| F15 | QR capacity sanity (byte mode, EC **M**): v40-M ≈ 2331 B ≥ 1800 ✓; v10-M ≈ 213 B ≥ 150 ✓; the `qrcode` lib auto-picks the version | `qrcode` lib |
|
||
| F16 | `build_zip.py` walks the tree with `os.walk` → new `.py` files ship automatically | `build_zip.py:39-47` |
|
||
| F17 | QML fork already has `QRImage.qml`, `QRScan.qml`, `ScanDialog.qml`; ScanDialog carries upstream comment "currently not used on android … qt6 camera support stops crashing" | `electrum/gui/qml/components/ScanDialog.qml:8-9` |
|
||
| F18 | `QML_PLAN.md` currently defers chunked multi-QR streams (Phase 3 note + risk R6) — this feature supersedes that deferral | `QML_PLAN.md:228-231, 304` |
|
||
| F19 | House test conventions: `def test_*` + `if __name__ == "__main__"` + `sys.path.insert(0, ..pardir)`; run standalone or via pytest | `tests/test_core_heirs.py:1-24` |
|
||
| F20 | Fork ships an `audio_modem` plugin. `_send(parent, blob)` zlib-compresses an **ASCII** blob, plays it via speaker through `amodem` inside a `WaitingDialog`; bit-rate selectable in the plugin's own settings (default = `amodem.config.slowest()`) | `electrum/plugins/audio_modem/qt.py:96-110` |
|
||
| F21 | `_recv(parent)` records from mic and delivers the decompressed ASCII text by calling `parent.setText(blob)` — the only integration contract is "an object with `setText(str)`"; there is no callback API | `audio_modem/qt.py:112-127` |
|
||
| F22 | Plugin lookup for enabled plugins: `window.plugins.get(name)` → instance or `None` (`Plugins.get`, electrum/plugin.py:575-576); availability check is the plugin's own `is_available()` (imports `amodem`). **`amodem` is NOT installed in the runtime env today** → optional dependency (pip `amodem` + libportaudio); feature must degrade gracefully | `electrum/plugin.py:575`, runtime-env check |
|
||
| F23 | `amodem.main.send/recv` stream the whole blob with their own framing/training → BAL must NOT apply QR frame chunking on this channel; and since `_send` compresses internally, BAL sends the **plain** transfer string to avoid double compression | consequence of F20/F21 |
|
||
|
||
---
|
||
|
||
## 4. Wire format specification
|
||
|
||
### 4.1 Transfer string
|
||
|
||
```
|
||
transfer_string = "\n".join( tx_str(tx) for tx in valid_txs_sorted_by_txid )
|
||
```
|
||
|
||
- `tx_str(tx)` = `str(tx)` (F11): hex for complete txs, base64-PSBT for
|
||
partially-signed ones. Neither alphabet contains `\n` or `|`, so both are
|
||
safe delimiters.
|
||
- Ordering: ascending `tx.txid()` → deterministic output for identical input.
|
||
- If compression enabled (D4):
|
||
`transfer_string = base64_ascii( zlib_compress( transfer_string ) )`.
|
||
|
||
### 4.2 Frame layout (one frame = content of ONE QR code)
|
||
|
||
Wire format v2 (compact, current export):
|
||
|
||
```
|
||
BAL1<TTT><iii><F><payload>
|
||
```
|
||
|
||
- Magic+version literal `BAL1` (reject anything else with a clear message).
|
||
- `<TTT>` = `<iii>` — **base36** zero-padded 3-char strings (`000`…`ZZZ`),
|
||
representing total N and index i, `1 ≤ i ≤ N ≤ 46655`. Fixed width means a
|
||
3-digit count field costs the same for a 1-frame or a 46655-frame transfer.
|
||
- `<F>`: single flag char — `0` ⇒ plain, `Z` ⇒ zlib+base64 compressed.
|
||
- `<payload>`: the i-th slice of `transfer_string`, exactly
|
||
`chunk_size` bytes each (last slice may be shorter). No separators: both
|
||
base36 count fields are fixed-width, so the header is unambiguously 11
|
||
chars and the payload starts at offset 11.
|
||
- Header overhead is a constant **11 bytes** → effective payload =
|
||
`chunk_size − 11`; the chunker slices the transfer string so that
|
||
**header+payload ≤ preset size**.
|
||
|
||
Legacy frames `BALQR1|<total>|<index>|<flags>|<payload>` (variable-width
|
||
decimal header, pipe-separated) are still **imported** by `parse_frame`
|
||
(`_parse_v1`), so old exports keep working; the exporter emits v2 only.
|
||
That is the one deliberate compatibility break: **v2 frames are not readable
|
||
by builds older than this change.**
|
||
|
||
### 4.3 Size presets (D5)
|
||
|
||
| Preset label | Payload budget (bytes/frame) | Typical QR version @EC-M |
|
||
|--------------|------------------------------|--------------------------|
|
||
| Small (low-res cameras) | 150 | ~v10 |
|
||
| Medium | 400 | ~v15 |
|
||
| Large | 900 | ~v22 |
|
||
| XL (high-res cameras) | 1800 | ~v40 |
|
||
|
||
EC level fixed **M** for scan reliability (D5). Presets live in
|
||
`bal/core/qrtransfer.py::CHUNK_PRESETS` so core tests can cover them.
|
||
|
||
### 4.4 Audio-modem channel (D7, F20-F23)
|
||
|
||
- Payload = the **plain** `transfer_string` of §4.1 — no BAL frames
|
||
(`split_frames`/`parse_frame` are QR-only), no BAL compression (the plugin
|
||
compresses internally; double compression wastes airtime).
|
||
- The existing core functions `encode_transfer(tx_strings,
|
||
compress=False)` + `decode_transfer(text, compressed=False)` are reused
|
||
unchanged; only the transport differs.
|
||
- Bit-rate is owned by the audio_modem plugin's settings dialog — BAL adds
|
||
no setting of its own.
|
||
|
||
---
|
||
|
||
## 5. New core module — `bal/core/qrtransfer.py`
|
||
|
||
GUI-free (never imports Qt — house rule). Public API:
|
||
|
||
```python
|
||
MAGIC = "BALQR"
|
||
VERSION = 1
|
||
FLAG_COMPRESSED = "Z"
|
||
CHUNK_PRESETS = [(label_en, budget_bytes), ...] # §4.3 table
|
||
|
||
def encode_transfer(tx_strings: list[str], compress: bool = False) -> str
|
||
"""Join -> optional zlib+base64 -> return transfer_string."""
|
||
|
||
def split_frames(transfer_string: str, chunk_size: int) -> list[str]
|
||
"""Slice into frames 'BAL1<TTT><iii><F>payload' (v2) — header+payload <=
|
||
chunk_size. Raises QrTransferError over the 46655-frame base36 cap, or
|
||
ValueError if chunk_size < MIN_CHUNK_SIZE."""
|
||
|
||
def encode_transfer_best(tx_strings: list[str]) -> tuple[str, bool]
|
||
"""-> (transfer_string, compressed); ships the shorter of plain vs
|
||
zlib+base64 so the export emits the densest frames."""
|
||
|
||
def parse_frame(frame: str) -> tuple[int, int, bool, str]
|
||
"""-> (total, index, compressed, payload); accepts v2 'BAL1…' and legacy
|
||
'BALQR1|…' (wrapped as _parse_v1/_parse_v2); ValueError on bad magic/
|
||
version/arity/non-numeric fields."""
|
||
|
||
def assemble(frames: dict[int, str]) -> str
|
||
"""Validate indices form exactly range(1..max_total) (taken from any
|
||
frame header), concatenate payloads in order, decode flags ->
|
||
transfer_string. Raises MissingFramesError(indexes) / InconsistentTotalError."""
|
||
|
||
def decode_transfer(transfer_string: str, compressed: bool) -> list[str]
|
||
"""Inverse of encode_transfer -> list of tx strings."""
|
||
```
|
||
|
||
Plus exceptions `QrTransferError(ValueError)`, `MissingFramesError`,
|
||
`InconsistentTotalError`. All docstrings/comments English; ruff-clean
|
||
(line-length 88, E501 ignored).
|
||
|
||
---
|
||
|
||
## 6. Settings (Qt)
|
||
|
||
1. `bal/core/plugin_base.py`: after `REBUILD_ON_CLOSE` (~line 264) add
|
||
|
||
```python
|
||
self.QR_CHUNK_SIZE = BalConfig(config, "bal_qr_chunk_size", 150)
|
||
```
|
||
|
||
2. `bal/gui/qt/plugin.py::settings_dialog` (rows end at 12, ~line 844):
|
||
append row **13** — visible in BASIC and ADVANCED (do NOT wrap with
|
||
`_hide_if_basic`):
|
||
|
||
- Label: `"QR Code Size"`
|
||
- `QComboBox` fed from `CHUNK_PRESETS`; item text e.g.
|
||
`"Small — ~150 bytes/QR (low-res cameras)"`; `currentIndexChanged`
|
||
→ `self.QR_CHUNK_SIZE.set(budget_bytes)`; initial index from
|
||
`QR_CHUNK_SIZE.get()` (fallback to nearest preset if the stored value
|
||
was customized).
|
||
- `HelpButton` text: explains trade-off (small QR = more shots but easier
|
||
to scan with poor cameras; large QR = fewer shots, needs good camera)
|
||
and that the size can also be changed inside the export dialog.
|
||
- Reset button via existing `_make_reset_btn(self.QR_CHUNK_SIZE, combo, ...)`
|
||
pattern (plugin.py:684).
|
||
|
||
---
|
||
|
||
## 7. Qt export flow
|
||
|
||
### 7.1 Entry point
|
||
|
||
`bal/gui/qt/lists.py::WillList.create_toolbar` (menu block lines 666-670):
|
||
|
||
```python
|
||
export_menu.addAction(_("Via QR…"), self.export_will_valid_qr)
|
||
```
|
||
|
||
New `WillList.export_will_valid_qr()` mirrors `export_will_valid`
|
||
(lists.py:743-754): builds `{wid: wi}` subset of `VALID` items, empty →
|
||
`show_message(_("No valid will item to export"))`, else
|
||
`self.bal_window.export_will_via_qr(will=subset)`.
|
||
|
||
### 7.2 `BalWindow.export_will_via_qr(will=None)` (new, `window.py` near
|
||
`export_will`)
|
||
|
||
- Collect `tx_strings = [str(wi.tx) for wid, wi in sorted-by-txid ...]`
|
||
(F11).
|
||
- Mark exported items `EXPORTED` (parity with `export_json_file`,
|
||
window.py:1607-1609) — only when `will` came from the live list.
|
||
- Open `WillQrExportDialog(self, tx_strings)`.
|
||
|
||
Shared helper used by both dialogs:
|
||
|
||
```python
|
||
def get_audio_modem_plugin(self): # on BalWindow
|
||
"""Return the loaded audio_modem plugin if enabled AND available
|
||
(amodem importable), else None. Never raises."""
|
||
p = self.window.plugins.get("audio_modem") # F22
|
||
return p if p is not None and p.is_available() else None
|
||
```
|
||
|
||
### 7.3 `WillQrExportDialog(BalDialog)` (new class in `dialogs.py`)
|
||
|
||
Layout:
|
||
|
||
```
|
||
[Size ▾ Small/Medium/Large/XL] ← compressed best-of automatically (no checkbox)
|
||
[ QR image ] ← BalQrImage (see below)
|
||
«i di N» [◀ Prev] [Next ▶]
|
||
[Save current QR as PNG…] [Send via Audio Modem…] [Close]
|
||
```
|
||
|
||
Behaviour:
|
||
|
||
- On any control change: rebuild `split_frames(encode_transfer_best(...))`,
|
||
reset index to frame 1, refresh counter (owner requirement: "cambiare la
|
||
risoluzione").
|
||
- `BalQrImage(QWidget)` ≈ trimmed copy of `QRCodeWidget`
|
||
(`electrum/gui/qt/qrcodewidget.py:21-72`) but constructing
|
||
`qrcode.QRCode(error_correction=ERROR_CORRECT_M, border=2)` and painting
|
||
via `electrum.gui.common_qt.util.draw_qr` (F12/F14). ~30 lines.
|
||
- Prev/Next wrap or disable at ends (disable chosen: clearer).
|
||
- PNG export optional convenience via existing
|
||
`getSaveFileName` + `QWidget.grab()` (same trick as
|
||
`qrcodewidget.py:110`).
|
||
- **Send via Audio Modem…** (D7): shown only when
|
||
`bal_window.get_audio_modem_plugin()` returns a usable instance (below);
|
||
otherwise hidden. Handler: re-encode the payload **plain**
|
||
(`encode_transfer(tx_strings, compress=False)`) and call the plugin's
|
||
`_send(parent=self, blob=transfer_string)` — its own WaitingDialog owns
|
||
progress/cancellation (F20). Tooltip when hidden is unnecessary; instead,
|
||
if the plugin is enabled but `is_available()` is False, show an info
|
||
message pointing to `pip install amodem` + portaudio (F22).
|
||
|
||
---
|
||
|
||
## 8. Qt import flow + review/sign wizard
|
||
|
||
### 8.1 Entry point
|
||
|
||
`lists.py` toolbar menu, next to Import/Merge (lines 670-671):
|
||
|
||
```python
|
||
menu.addAction(_("Import via QR…"), lambda: self.bal_window.import_will_via_qr())
|
||
```
|
||
|
||
`BalWindow.import_will_via_qr()` opens `WillQrImportDialog(self)`.
|
||
|
||
### 8.2 `WillQrImportDialog(BalDialog)`
|
||
|
||
State: `self.frames: dict[int, str]`, `self.total: int | None`,
|
||
`self.target_index: int | None`.
|
||
|
||
Layout:
|
||
|
||
```
|
||
«Captured k of N» [Scan ▶] [Reset]
|
||
[slot grid: push-buttons 1..N; states: empty / filled ✓ / selected-target]
|
||
hint line («Select a slot, then scan» / «Scan the first QR»)
|
||
[Receive via Audio Modem…] [Review & Sign ▶] [Close]
|
||
```
|
||
|
||
Behaviour:
|
||
|
||
- **Scan** → `scan_qrcode_from_camera(parent=self,
|
||
config=self.bal_window.window.config, callback=self._on_scan)`
|
||
(F13). One-shot per press; dialog stays open between shots (simplest,
|
||
matches Electrum UX; no continuous mode).
|
||
- `_on_scan(success, error, data)`:
|
||
- failure → `show_error(error)` (covers missing zbar/camera too);
|
||
- `parse_frame` errors → `show_warning(_("Not a BAL will QR"))`;
|
||
- first valid frame adopts `total` and materializes the slot grid;
|
||
- frame whose `total` ≠ adopted total → warn + offer Reset (user may have
|
||
restarted the export with another size);
|
||
- valid → `frames[index] = payload`; auto-advance `target_index` to the
|
||
lowest missing index; refresh grid + counter.
|
||
- Clicking an empty slot sets `target_index` (owner requirement: manual
|
||
shot selection); a filled slot click asks to overwrite.
|
||
- **Receive via Audio Modem…** (D7): shown only when
|
||
`bal_window.get_audio_modem_plugin()` returns a usable instance. Handler:
|
||
build a tiny adapter object exposing `setText(str)` that stores the text
|
||
and invokes the shared post-receive continuation, then call
|
||
`plugin._recv(parent=self, ...)`-style flow (F21 contract). On success the
|
||
received string is treated as the **whole payload**: skip frames/slots
|
||
entirely → `decode_transfer(text, compressed=False)` → continue at §8.2's
|
||
item-building step (WillItem construction + validity pass + wizard).
|
||
Errors from the modem surface through the plugin's own dialog; empty
|
||
result (user cancelled) is silently ignored.
|
||
- **Review & Sign** enabled only when `set(frames) == set(range(1, N+1))`:
|
||
runs `assemble` + `decode_transfer` → `list[str]`; any `QrTransferError`
|
||
surfaces as `show_error` and keeps the dialog open.
|
||
- Build items exactly like `merge_single_transaction` (F4):
|
||
`WillItem({"tx": s}, wallet=self.wallet)` per string; failures per-string
|
||
are collected and reported at the end (bad string ≠ fatal for the rest).
|
||
- Local validity pass (F5 recipe) on the resulting dict; items failing
|
||
`VALID` are dropped and listed in a warning. Set
|
||
`wi.set_status("IMPORTED", True)` on survivors (mirrors
|
||
`import_will_into_details`, window.py:1753-1754).
|
||
- Then `close()` and start the wizard (§8.3) with the valid subset. Empty
|
||
result → stop with a message.
|
||
|
||
### 8.3 `WillTxReviewSignDialog(BalDialog)` — post-capture wizard (D6)
|
||
|
||
Constructed with `(bal_window, willitems: dict[str, WillItem])` — the
|
||
imported subset lives **outside** the live wallet state (external mode,
|
||
F3).
|
||
|
||
Flow:
|
||
|
||
1. **Password once**: `password = bal_window.get_wallet_password()`
|
||
(window.py:1088-1100). Returns `False` on cancel → abort wizard; `None`
|
||
means unencrypted wallet → proceed without password.
|
||
2. **Per-transaction page** (one `QStackedWidget` step per tx, ordered by
|
||
txid like export):
|
||
|
||
```
|
||
Tx 2 of 5 — a1b2…c3d1 (short txid)
|
||
Locktime: 2033-04-05 Status: unsigned (0/1 sigs)
|
||
┌ outputs ─────────────────────────────────┐
|
||
│ bc1q…heir1 0,042 BTC │
|
||
│ bc1q…willexec fee 0,00012 BTC │
|
||
│ bc1q…change 0,00988 BTC │
|
||
└───────────────────────────────────────────┘
|
||
Total outputs: 0,052 BTC Fees: 420 sat (1.2 sat/vB)
|
||
[Sign & Next ▶] [Skip] [Cancel all]
|
||
```
|
||
- Outputs from `tx.outputs()` (address via `TxOutput.get_ui_address_str()`
|
||
style helpers already imported in the qt layer; value via
|
||
`bal_window.window.format_amount`).
|
||
- Totals: `output_value()` sum; fees via `input_value() - output_value()`
|
||
after resolving inputs with `Will.add_info_from_will(will, wid, wallet)`
|
||
(F10); `-1`/unknown handled like widgets.py:1319-1324 (F9).
|
||
3. **Sign & Next** → sign this single tx through a **refactored helper**
|
||
extracted from the loop body of `sign_transactions`
|
||
(window.py:1037-1083 → `_sign_single_tx(tx, willitems, password)` kept
|
||
byte-equivalent; batch method calls the helper per iteration so existing
|
||
behaviour/tests are unaffected). Update `COMPLETE`/sig-counts exactly as
|
||
today; then advance.
|
||
4. **Skip** leaves the tx untouched and advances. **Cancel all** stops; the
|
||
already-signed txs remain in the wizard's local dict (still exportable —
|
||
confirmation dialog warns about skipped ones).
|
||
5. **Summary page**: `signed X of Y`, skipped/failed lists, then:
|
||
|
||
```
|
||
[Save signed file…] [Show QR…] [Close]
|
||
```
|
||
- *Save file* = existing JSON path: `export_meta_gui(window,
|
||
"will.json", writer)` writing `{wid: wi.to_dict()}` of the signed
|
||
subset (same serializer as `export_json_file`, window.py:1605).
|
||
- *Show QR* = `WillQrExportDialog` over `[str(wi.tx)]` of the signed
|
||
subset (the online machine can scan them straight into Merge).
|
||
- Nothing touches `self.willitems`/history (external-mode rule, F3).
|
||
|
||
---
|
||
|
||
## 9. Checklist (execution order — tick here when resuming work)
|
||
|
||
- [x] **P0** `bal/core/qrtransfer.py` + unit tests `tests/test_core_qr_transfer.py`
|
||
(cases: round-trip plain/compressed; boundaries: len%size==0, size>len,
|
||
min-size guard; bad magic/version; missing middle frame; duplicate
|
||
overwrite; inconsistent totals; multi-PSBT mixes; presets sanity vs
|
||
qrcode capacities F15). Run:
|
||
`QT_QPA_PLATFORM=offscreen python3 tests/test_core_qr_transfer.py`
|
||
- [x] **P1** Settings: `QR_CHUNK_SIZE` config var + settings-dialog row 16
|
||
(ø16) + reset kind (§6). Verify in `QT_QPA_PLATFORM=offscreen` GUI run.
|
||
- [x] **P2** Export: `BalWindow.export_will_via_qr`, `get_audio_modem_plugin`
|
||
helper, `WillList` menu action, `WillQrExportDialog` + `BalQrImage`,
|
||
audio-modem send button (§7).
|
||
- [x] **P3** Import: `import_will_via_qr`, `WillQrImportDialog` (§8.2),
|
||
incl. camera error paths, audio-modem receive button (local mirror of
|
||
`_recv`, `setText` sink replaced by a callback), plain-payload fast
|
||
path into the wizard.
|
||
- [x] **P4** Wizard: `_prepare_and_sign_tx` refactor + `WillTxReviewSignDialog`
|
||
(§8.3). Regression-gate: full batch sign still green
|
||
(`tests/test_core_*.py` offline batch; `tests/test_gui_*.py` batch
|
||
including new `tests/test_gui_qr_transfer.py`).
|
||
- [x] **P5** Docs & QML plan sync: update `QML_PLAN.md` — Phase 2 models +=
|
||
`BalQrTransferModel` (thin QObject over `bal.core.qrtransfer`),
|
||
Phase 3 += dedicated views `BalQrExportPage.qml` /
|
||
`BalQrImportPage.qml` (slot grid + `QRScan` reuse), delete the
|
||
"chunked streams deferred" note, rewrite R6 mitigation, add Android
|
||
caveat quoting F17 with file/paste fallback; README/HANDOFF sections;
|
||
CHANGELOG numbered entry 56 at END (house rule).
|
||
- [x] **P6** Release hygiene: `python3 build_zip.py` +
|
||
`QT_QPA_PLATFORM=offscreen python3 tests/smoke_test.py
|
||
electrum.plugins.bal` + external-zip test; ruff (repo venv
|
||
`venv/bin/ruff`) no NEW violations; pyright false-positive policy per
|
||
AGENTS.md. Version bump only via `make-release.sh` (owner-driven).
|
||
Docs: document audio-modem as OPTIONAL channel — requires the
|
||
Electrum `audio_modem` plugin enabled plus `pip install amodem`
|
||
and libportaudio (not installed in the dev runtime env today, F22);
|
||
manual test matrix gains an audiomodem round-trip row (two machines,
|
||
default slowest bitrate) marked optional/skippable when hardware
|
||
unavailable.
|
||
|
||
---
|
||
|
||
## 10. Risks & mitigations
|
||
|
||
| Risk | Mitigation |
|
||
|------|------------|
|
||
| High frame counts annoy users (e.g. 40+ QR at 150 B) | Presets span 150→1800; compress option; counter always visible |
|
||
| Big QR versions fail on cheap cameras | EC=M fixed; Small preset targets low-res cams (D5 rationale) |
|
||
| User rescans old export with different total | `InconsistentTotalError` → clear warning + Reset (§8.2) |
|
||
| `_sign_single_tx` refactor regresses batch signing | Byte-equivalent extraction; batch callers unchanged; offline core tests gate P4 |
|
||
| Imported txs reference UTXOs the importing wallet doesn't know | Validity pass drops them with an explicit report instead of silently merging garbage |
|
||
| zbar/camera unavailable (esp. Windows/macOS packaging) | `scan_qrcode_from_camera` error path → suggest file export/import fallback |
|
||
| `amodem`/portaudio not installed (current dev env state, F22) or audio_modem plugin disabled | Buttons simply hidden; QR/file remain the primary channels; P6 documents the optional dependency |
|
||
| Audio transfer fails mid-way (noise, wrong volume) | Plugin's WaitingDialog surfaces the error; user retries — nothing to clean up on BAL side (single atomic blob, no slot state touched) |
|
||
| Very slow airtime at default slowest bitrate | Bitrate is selectable in the audio_modem plugin's own settings (F20); BAL adds no knob; tooltip in export dialog hints at large payloads |
|
||
| Qt6 camera instability on Android (future QML work) | Recorded as caveat in QML_PLAN update (P5), file/paste stays the primary mobile fallback |
|
||
|
||
---
|
||
|
||
## 11. Findings log (append-only)
|
||
|
||
- 2026-08-25: plan drafted after code exploration; owner answered D1-D6
|
||
(D6 amended live from "preview dialog" to "review+sign wizard").
|
||
- Verified F12 (QRCodeWidget hardcodes EC-L) and F11 (str(tx) round-trip
|
||
guarantees) — both shaped §§4/7.
|
||
- 2026-08-25: owner requested an audio-modem transfer path → researched
|
||
`electrum/plugins/audio_modem/qt.py`, added D7 + F20-F23, §4.4, buttons
|
||
in §§7.3/8.2, checklist/risk updates. Key constraint found: `_recv`'s
|
||
only contract is `parent.setText(blob)` (F21) → thin adapter object; and
|
||
BAL must not chunk/compress on this channel (F23). `amodem` is NOT in
|
||
the runtime env yet — feature is strictly optional.
|