bal-electrum-plugin/CHANGELOG_REFACTOR.md

BAL — Resoconto del refactoring (per l'autore originale)

Questo documento elenca tutte le modifiche apportate al plugin BAL (Bitcoin After Life) rispetto alla versione originale 0.2.8.

Principio guida: refactoring conservativo e a comportamento invariato (Approccio A). La logica di business è stata mantenuta byte-identica dove possibile; sono cambiati soprattutto la disposizione dei file e gli import. Nessuna riscrittura algoritmica.

Ambiente di verifica: Electrum 4.7.2 + PyQt6 (l'ultima release stabile che espone json_db.register_dict).

---

1. Riorganizzazione della struttura (separazione logica / GUI)

Il problema principale segnalato era che la logica e la grafica erano mescolate, in particolare in un unico file qt.py da 4131 righe.

Struttura PRIMA (flat, 7 file)

BAL/
├── __init__.py        (vuoto, 0 righe)
├── bal.py             (243)  logica + plugin base
├── util.py            (533)  helper
├── heirs.py           (791)  modello eredi + costruzione tx
├── will.py            (927)  modello will/WillItem
├── willexecutors.py   (374)  networking will-executor
├── qt.py              (4131) TUTTA la GUI + il Plugin in un solo file
└── bal_resources.py   (14)

Struttura DOPO (core/ vs gui/)

bal/
├── manifest.json            metadati conformi allo standard
├── qt.py                    shim di caricamento (re-export di Plugin)
├── __init__.py              docstring di architettura + __version__
├── core/                    LOGICA senza dipendenze Qt
│   ├── util.py              (ex util.py)
│   ├── plugin_base.py       (ex bal.py)
│   ├── heirs.py             (ex heirs.py)
│   ├── will.py              (ex will.py)
│   └── willexecutors.py     (ex willexecutors.py)
└── gui/qt/                  PRESENTAZIONE PyQt6
    ├── theme.py      (59)   mappatura stato → colore
    ├── common.py     (155)  import condivisi + helper GUI
    ├── widgets.py    (782)  widget "foglia"
    ├── calendar.py   (80)   BalCalendar
    ├── dialogs.py    (1127) finestre di dialogo
    ├── lists.py      (957)  viste ad albero (eredi/preview/executor)
    ├── window.py     (952)  controller GUI per-wallet (BalWindow)
    └── plugin.py     (273)  classe Plugin (@hook Electrum → GUI)

Il file qt.py da 4131 righe è stato suddiviso per responsabilità. I corpi delle classi sono stati copiati verbatim (riga per riga) per non toccare la logica delicata delle transazioni di eredità.

Mappa: dove sono finite le 40 classi/funzioni di qt.py

Classe/funzione (riga orig.)	Nuovo modulo
Plugin (67)	gui/qt/plugin.py
shown_cv (317)	gui/qt/common.py
BalWindow (330)	gui/qt/window.py
add_widget (1257)	gui/qt/common.py
ClickableLabel (1263)	gui/qt/widgets.py
BalTxFeesWidget (1271)	gui/qt/widgets.py
_LockTimeEditor (1340)	gui/qt/widgets.py
BalTimeEditWidget (1374)	gui/qt/widgets.py
TimeRawEditWidget (1508)	gui/qt/widgets.py
LockTimeRawEdit (1527)	gui/qt/widgets.py
LockTimeDateEdit (1605)	gui/qt/widgets.py
ThresholdTimeWidget (1644)	gui/qt/widgets.py
LockTimeWidget (1664)	gui/qt/widgets.py
WillSettingsWidget (1683)	gui/qt/widgets.py
PercAmountEdit (1818)	gui/qt/widgets.py
BalDialog (1883)	gui/qt/dialogs.py
BalWizardDialog (1913)	gui/qt/dialogs.py
BalWizardWidget (2002)	gui/qt/dialogs.py
BalWizardHeirsWidget (2068)	gui/qt/dialogs.py
BalWizardWEDownloadWidget (2103)	gui/qt/dialogs.py
BalWizardWEWidget (2190)	gui/qt/dialogs.py
BalWizardLocktimeAndFeeWidget(2207)	gui/qt/dialogs.py
BalWaitingDialog (2224)	gui/qt/dialogs.py
BalBlockingWaitingDialog (2285)	gui/qt/dialogs.py
BalLineEdit (2304)	gui/qt/widgets.py
BalTextEdit (2312)	gui/qt/widgets.py
BalCheckBox (2320)	gui/qt/widgets.py
BalBuildWillDialog (2335)	gui/qt/dialogs.py
HeirListWidget (2858)	gui/qt/lists.py
PreviewList (3059)	gui/qt/lists.py
WillDetailDialog (3445)	gui/qt/dialogs.py
WillWidget (3545)	gui/qt/widgets.py
WillExecutorListWidget (3637)	gui/qt/lists.py
WillExecutorWidget (3873)	gui/qt/lists.py
WillExecutorDialog (3982)	gui/qt/dialogs.py
CheckAliveError (4018)	gui/qt/common.py
log_error (4028)	gui/qt/common.py
export_meta_gui (4043)	gui/qt/common.py
BalCalendar (4066)	gui/qt/calendar.py

---

2. Rimozioni (codice morto / debug) — comportamento invariato

Tutte le rimozioni seguenti sono state verificate come non utilizzate o puramente di debug, quindi non alterano il comportamento del plugin.

1. util.py → core/util.py: rimossi tre helper di debug usati solo per stampe a console:

   • print_var() (orig. riga 439)
   • print_utxo() (orig. riga 474)
   • print_prevout() (orig. riga 486)

2. bal.py → core/plugin_base.py: rimossa la funzione stub vuota get_will_settings(x) (orig. righe 12-14):

   def get_will_settings(x):
       # print(x)
       pass
   

   ⚠️ Verificato: non era riferita da nessun register_dict — i tre register_dict usano tuple, dict, lambda x: x. Quindi era codice morto. La funzione usata get_will(x) è stata mantenuta identica.

3. will.py (WillItem) → spostato in gui/qt/theme.py: il metodo WillItem.get_color() (orig. riga 852) restituiva colori esadecimali — è logica di presentazione, non di dominio. È stato spostato fuori dal modello e trasformato nella funzione status_color(will_item) in gui/qt/theme.py. Verificato byte-identico su tutte le combinazioni di stato (stessa catena di get_status(...), stessi codici colore).

---

3. Cambi di import (necessari per la nuova struttura)

Gli import sono stati aggiornati da "flat" a "a package". Esempi:

Prima	Dopo
from .bal import BalPlugin	from .plugin_base import BalPlugin (in willexecutors)
from .util import Util	from .util import Util (invariato, ora dentro core/)
(in qt.py) from .bal import ...	i moduli GUI importano da ...core.X

• Aggiunti from .common import _, _logger nei moduli GUI, perché import * non esporta i nomi che iniziano con underscore.
• Aggiunti 3 import "lazy" (dentro le funzioni) in dialogs.py per spezzare il ciclo dialogs ↔ lists (lists importa BalBuildWillDialog da dialogs).

La logica interna dei metodi non è stata toccata: prepare_transactions(), buildTransactions() ecc. sono verbatim.

---

4. Packaging conforme allo standard Electrum

manifest.json reso conforme a https://plugins.electrum.org/developers.html :

Campo	Prima	Dopo
name	"BAL"	"bal" (minuscolo = nome dir)
version	(assente, era solo nella description)	"0.2.8"
description	con <br> HTML	testo pulito
licence	(assente)	"MIT"
fullname/author/available_for/icon	presenti	invariati

• __init__.py (era vuoto): ora contiene la docstring di architettura e __version__ = "0.2.8".
• Portati nel package: LICENSE, VERSION, README.md, bal_resources.py, e la cartella wallet_util/ (invariata).

---

5. CORREZIONE BUG: caricamento come plugin esterno (.zip)

Durante i test su Electrum 4.7.2 portable per Windows sono emersi due problemi reali nel caricare il plugin come plugin esterno da .zip:

Bug 5a — ModuleNotFoundError: No module named 'electrum_external_plugins'

• Causa: Electrum carica i plugin esterni da zip sotto il package sintetico electrum_external_plugins.bal, ed esegue solo l'__init__ del package e il modulo qt. Non registra il package radice sintetico né i sotto-package annidati (gui, gui.qt). Un semplice from .gui.qt.plugin import Plugin fallisce risalendo ai parent mancanti.
• Fix: qt.py ora è uno shim resiliente che (1) rileva a runtime il proprio nome di package (__package__), (2) ricostruisce in sys.modules gli eventuali package padre mancanti, (3) importa Plugin con importlib.import_module. Funziona sia come plugin interno (electrum.plugins.bal) sia esterno (electrum_external_plugins.bal).

Bug 5b — zlib.error: Error -5 ... incomplete or truncated stream

• Causa: alcune build portable di Electrum su Windows non riescono a decomprimere con zipimport archivi che contengono voci di directory o compressione non standard.
• Fix: aggiunto build_zip.py, che genera un archivio "zipimport-friendly": solo file (nessuna voce di directory), DEFLATE standard, ordine deterministico (SHA-256 riproducibile), escludendo __pycache__/*.pyc. Stampa anche l'hash SHA-256 per verificare l'integrità del download.

---

6. Test aggiunti

• tests/smoke_test.py — verifica import + comportamento di base (BalTimestamp, helper di Util, costanti HEIR_*, stati di WillItem, hook del Plugin).
• tests/external_zip_test.py — riproduce fedelmente la sequenza di caricamento di un plugin esterno da zip di Electrum (regressione per il Bug 5a/5b).

Tutti i test passano sotto Electrum 4.7.2 + PyQt6.

---

7. Riepilogo: cosa NON è cambiato

• La logica di costruzione delle transazioni (heirs.py, will.py).
• I valori e i tipi di json_db.register_dict(...).
• I codici colore degli stati (solo spostati in theme.py).
• L'algoritmo di tutte le classi GUI (copiate verbatim).
• Il formato dei dati salvati nel wallet.

8. Note / raccomandazioni

• Il plugin richiede Electrum 4.7.2: json_db.register_dict è stato rimosso nelle versioni successive (master), dove andrebbe sostituito con stored_dict.register_name. Valutare un adeguamento se si vuole supportare Electrum più recente.
• Prima del rilascio è consigliata una prova end-to-end in una sessione Electrum reale (preferibilmente su testnet), oltre agli smoke test.

---

9. CORREZIONI GUI — finestre e ciclo di vita (B1-B10)

Dopo il refactoring di struttura sono stati corretti dieci difetti grafici e di ciclo di vita delle finestre, già presenti nel codice originale. La logica di business è rimasta byte-identica (nessuna modifica a bal/core/*): sono cambiati solo presentazione, parent, modalità, z-order, ciclo di vita e cleanup delle finestre Qt.

Sintomi segnalati dall'utente, ora risolti:

• (S1) le finestre del plugin sparivano dietro la finestra di Electrum;
• (S2) alcuni meccanismi funzionavano solo dopo aver chiuso e riavviato Electrum.

ID	Problema (presente nell'originale)	Correzione applicata
B1	self.parent = parent sovrascriveva il metodo parent() di Qt, rompendo la gerarchia delle finestre	rinominato in self._bal_parent (in dialogs.py, lists.py, widgets.py); il parent reale passa da top_level_of(parent)
B2	dialoghi aperti con .show() non modale → finivano sotto la finestra principale	sostituiti con show_on_top() / show_modal() e parent corretto
B3	messaggio "Please restart Electrum to activate the BAL plugin": il plugin si attivava solo dopo riavvio	inizializzazione a caldo con _setup_window() che replica load_wallet — niente più riavvio
B4	chiave del dizionario finestre usava il metodo winId invece del valore	chiave stabile _window_key() basata su id(window)
B5	on_close ingoiava tutti gli errori con except: pass	riscritto: niente except:pass, log per ogni passo, reset pulito dello stato
B6	BalBlockingWaitingDialog bloccava il thread della GUI (processEvents commentato)	ripristinato processEvents() → GUI reattiva durante l'attesa
B7	closeEvent/hideEvent con cleanup del thread commentato	gestione esplicita di closeEvent/hideEvent + chiamata a super()
B8	closeEvent incompleto in alcuni dialog	gestione uniforme dello stato di chiusura
B9	show()+raise_() senza activateWindow() né modalità → finestra non in primo piano	bring_to_front() = raise_() + activateWindow()
B10	gestione multi-wallet / multi-finestra fragile; menu cercato per titolo &Tools	uso dell'API ufficiale window.tools_menu

Nuovo modulo: gui/qt/window_utils.py (119 righe)

Gli helper per la gestione delle finestre sono stati centralizzati in un unico modulo, così la stessa logica non viene duplicata nei vari dialog:

• top_level_of(widget) — risale alla finestra di primo livello corretta da usare come parent;
• bring_to_front(window) — raise_() + activateWindow() per portare in primo piano;
• stop_thread(thread) — stop+wait sicuro di un TaskThread;
• show_modal(dialog) — apertura modale corretta (exec());
• show_on_top(window) — apertura non modale ma sopra le altre finestre.

gui/qt/common.py importa questi helper e li rende disponibili al resto della GUI.

---

10. CORREZIONE BUG: download lista will-executor

Dopo l'installazione del pacchetto con le correzioni GUI, l'utente ha segnalato che il comando "download list" dei will-executor non scaricava più la lista.

Indagine

Il codice di rete (core/willexecutors.py: send_request, handle_response, download_list, initialize_willexecutor) è stato confrontato riga per riga con l'originale Gitea ed è risultato byte-identico (l'unica differenza è il parametro aggiuntivo welist_server in download_list, retro-compatibile).

Durante l'indagine sono comunque emersi e stati corretti due difetti reali introdotti dalle correzioni GUI, che potevano "perdere" il risultato del download:

1. BalDialog.closeEvent/hideEvent fermavano il TaskThread. In Electrum TaskThread.on_done esegue cb_done (cioè self.accept, che chiude il dialog) prima di cb_result (cioè on_success, che aggiorna la lista). Fermare il thread alla chiusura del dialog scartava quindi il risultato appena scaricato. → I due metodi sono stati riportati a non fermare il thread (con commento esplicativo nel codice).
2. BalWaitingDialog.exe() usava una modalità sbagliata (show_modal / WindowModal). → Ripristinato l'originale self.exec(), aggiungendo prima bring_to_front(self) per garantire il primo piano.

Inoltre i percorsi del pulsante e del wizard (che prima scaricavano in modi diversi e con messaggi diversi) sono stati unificati in un unico helper fetch_will_executors_list, eseguito dentro il worker del TaskThread.

Causa vera del mancato download: ambientale, NON del plugin

Una probe di controllo con urllib che bypassava completamente Electrum falliva ugualmente con WinError 10054 ("connection forcibly closed by remote host"): segno che la rete/ISP dell'utente resettava la connessione HTTPS verso welist.bitcoin-after.life. La conferma definitiva: attivando una VPN il download è andato a buon fine.

L'originale "sembrava" funzionare perché spedisce comunque un will-executor di default già incorporato (https://we.bitcoin-after.life), quindi la lista non risultava mai del tutto vuota anche senza un download riuscito.

Pulizia finale (scelta dall'utente — "Opzione 1")

• Finestra di attesa non bloccante mantenuta (BalWaitingDialog), così la GUI non si congela durante il download.

• Fallback dell'URL: prima l'URL configurato (WELIST_SERVER), poi quello hardcoded https://welist.bitcoin-after.life/.

• Diagnostica dettagliata spostata nei soli log (rimossa la probe urllib dall'interfaccia).

• Messaggio d'errore semplice per l'utente, in inglese (DOWNLOAD_FAILED_MESSAGE):

  "Could not download the will-executors list. This is usually caused by your internet connection or a firewall, not by the plugin. Please check your connection (a VPN often helps) and try again."

File toccati (solo presentazione/GUI, logica invariata)

• gui/qt/window.py — helper condiviso fetch_will_executors_list, download_list con TaskThread + BalWaitingDialog, costante DOWNLOAD_FAILED_MESSAGE.
• gui/qt/lists.py — WillExecutorWidget.download_list instradato sul percorso condiviso con on_success che aggiorna/salva la lista.
• gui/qt/dialogs.py — BalDialog.closeEvent/hideEvent non fermano più il thread; BalWaitingDialog.exe() torna a self.exec() + bring_to_front.
• tests/gui_fixes_test.py — asserzione di regressione: verifica che closeEvent/hideEvent non contengano stop_thread (per non reintrodurre il bug che scartava il download).

---

11. Confronto strutturale finale (originale Gitea → refactor)

Conteggio file .py (escluse cartelle generate):

Originale (Gitea)	righe	→	Refactor (bal/)	righe
__init__.py	1	→	__init__.py	37
bal.py	161	→	core/plugin_base.py	351
util.py	1051	→	core/util.py	614
heirs.py	792	→	core/heirs.py	806
will.py	903	→	core/will.py	938
willexecutors.py	547	→	core/willexecutors.py	390
qt.py (monolite GUI)	3777	→	suddiviso in gui/qt/* (vedi sotto)	—
bal_resources.py	14	→	bal_resources.py	14
wallet_util/*.py	275	→	wallet_util/*.py (invariati)	280

Suddivisione del vecchio qt.py (3777 righe) nei moduli GUI:

Modulo refactor	righe	Contenuto
gui/qt/plugin.py	303	classe Plugin (@hook Electrum → GUI)
gui/qt/window.py	1048	BalWindow (controller per-wallet)
gui/qt/dialogs.py	1155	finestre di dialogo + wizard
gui/qt/lists.py	964	viste ad albero (eredi/preview/executor)
gui/qt/widgets.py	782	widget "foglia"
gui/qt/common.py	157	import condivisi + helper
gui/qt/window_utils.py	119	helper finestre (NUOVO — vedi §9)
gui/qt/calendar.py	80	BalCalendar
gui/qt/theme.py	59	mappatura stato → colore
gui/qt/__init__.py	17	init package GUI

Le differenze nei conteggi di righe rispetto all'originale derivano da: riformattazione/commenti, separazione degli import per modulo, e spostamento di funzioni tra util.py/bal.py e i nuovi moduli. Gli algoritmi non sono stati modificati.

---

12. Cronologia delle modifiche su GitHub

• 4198a51 — import iniziale del refactor strutturale (v0.2.8): separazione core/ (logica) vs gui/qt/ (presentazione), packaging conforme, fix caricamento zip esterno, smoke test (sezioni §1-§8).
• d56fa36 — questo changelog del refactoring (in italiano).
• 4806997 — DIAGNOSI_GUI.md: diagnosi dei bug GUI di z-order e ciclo di vita (Fase A).
• dd6f677 (PR #2, squash) — correzioni GUI B1-B10 + fix download lista will-executor + window_utils.py + test di regressione (sezioni §9-§10).
• PR #3 — fix OverflowError su Windows (anno 2038) che rompeva le schede Will/Heirs e la voce di menu (sezione §13).

---

13. CORREZIONE BUG: OverflowError su Windows (limite anno 2038)

Sintomo (Windows 11)

Dopo aver riavviato Electrum o cambiato wallet, le schede Will e Heirs sparivano e compariva una voce di menu condensata/illeggibile (icona + testo sovrapposti) sotto il logo di Electrum, accanto a Portafogli. Su Linux il problema non si manifestava.

Causa vera (dal log di Electrum dell'utente)

OverflowError: Python int too large to convert to C int
  window.py __init__ -> create_heirs_tab -> WillSettingsWidget
  -> on_locktime_change -> BalTimestamp.to_date
  -> datetime.fromtimestamp(NLOCKTIME_MAX)

• NLOCKTIME_MAX = 2**32 - 1 = 4294967295 viene usato come locktime di default/sentinella.
• Su Windows time_t è a 32 bit, quindi datetime.fromtimestamp(ts) solleva OverflowError per qualsiasi timestamp oltre il 2038.
• Su Linux 64-bit la stessa chiamata funziona: ecco perché il bug si vedeva solo su Windows e i test su Linux non lo intercettavano.
• L'eccezione interrompeva BalWindow.__init__ durante init_menubar / load_wallet, lasciando le schede Will/Heirs e la voce di menu a metà costruzione → l'elemento grafico condensato/illeggibile sotto il logo.

Nota: i due primi tentativi di correzione (status-bar no-op e idempotenza di init_menubar_tools) non centravano la causa; sono stati comunque mantenuti perché innocui e leggermente migliorativi, ma il vero colpevole era questo crash a monte.

Fix (comportamento invariato per tutti i valori normali)

• BalTimestamp._safe_fromtimestamp(): datetime.fromtimestamp con clamp a INT32_MAX (anno 2038) in caso di OverflowError/OSError/ ValueError, esattamente come la funzione get_max_allowed_timestamp() dell'originale (workaround per Electrum issue #6170).
• Usato in to_date / to_timestamp / __str__ / __repr__ di BalTimestamp.
• gui/qt/widgets.py (set_value): usa il converter sicuro.
• core/util.py (timestamp_minus): stessa protezione inline con clamp a INT32_MAX.

I valori entro il 2038 (date assolute normali, durate relative come 90d/5y) producono lo stesso identico risultato di prima.

Test

• tests/windows_overflow_test.py riproduce il limite 32-bit di Windows (monkeypatch di datetime.fromtimestamp) e dimostra che senza il fix si ottiene lo stesso OverflowError del log, mentre con il fix passa. Verificato anche che il test fallisce senza il fix.

Confermato dall'utente: "si ora funziona".

14. NUOVA FUNZIONE: invalidazione automatica al posticipo dell'eredità

Problema

Una transazione di eredità viene firmata con un locktime fisso e immutabile e inviata ai will-executor, che sono economicamente incentivati a trasmetterla (incassano le fee). Se l'utente, dopo aver firmato/inviato, posticipa la data di consegna (es. di un anno), la vecchia transazione gia firmata resta valida sui server dei will-executor. Poiche ha il locktime piu basso, un will-executor potrebbe trasmetterla appena scade, eseguendo l'eredita in anticipo rispetto alla nuova volonta dell'utente. La versione precedente non gestiva questo caso: il posticipo non produceva alcuna azione.

Soluzione (Strategia B — invalidazione esplicita on-chain)

Al posticipo di un'eredita gia firmata e/o inviata (stato COMPLETE o PUSHED), il plugin chiede di invalidare on-chain i fondi prima di ricostruire la nuova eredita. L'invalidazione spende gli stessi UTXO verso un nuovo indirizzo di change con locktime = altezza corrente (RBF), quindi e trasmettibile subito: una volta confermata, la vecchia transazione pre-firmata diventa definitivamente inutilizzabile, vincendo la corsa contro qualunque will-executor.

Dettagli tecnici

• core/will.py:
  • nuova eccezione WillPostponedException (sottoclasse di NotCompleteWillException);
  • check_willexecutors_and_heirs: il confronto del locktime non usa piu l'entry dell'erede memorizzata (their[2]), che viene aggiornata in memoria insieme al nuovo valore al momento del posticipo e quindi risulterebbe sempre uguale. Ora confronta il locktime richiesto con w.tx.locktime, cioe il locktime congelato nella transazione firmata (immutabile, e quello che i will-executor possiedono). Tre casi: invariato → coerente; nuovo > tx su will firmato/inviato → WillPostponedException; nuovo > tx su will mai inviato → semplice ricostruzione (nessuna fee on-chain).
• gui/qt/dialogs.py (BalBuildWillDialog.task_phase1, il percorso reale usato da Tools → Prepare): aggiunto il ramo except WillPostponedException prima di NotCompleteWillException; si comporta come il caso "will scaduto" e ritorna (None, tx) per innescare firma + broadcast dell'invalidazione. L'utente preme di nuovo Prepare per ricostruire, rifirmare e reinviare la nuova eredita (due passi espliciti, per maggior controllo).
• gui/qt/window.py (build_inheritance_transaction): aggiunto lo stesso ramo per completezza del percorso alternativo, con messaggio esplicativo.
• gui/qt/common.py: WillPostponedException esportato.

NUOVA COLONNA "Server" nella lista transazioni

Per dare all'utente visibilita costante sullo stato online delle proprie transazioni di eredita, e stata aggiunta una colonna dedicata "Server" in PreviewList (gui/qt/lists.py), con etichetta sempre leggibile (Confirmed on server, Sent (not checked), Send failed, Not on server, Signed (not sent), Not sent) e tooltip con URL del will-executor e stato. Le funzioni server_status_text() e server_status_tooltip() sono in gui/qt/theme.py e riusano gli stessi flag di stato gia esistenti.

Test

• I 182 test ufficiali continuano a passare; smoke test ed external-zip test OK; ruff senza nuove segnalazioni reali.
• Verificato sui dati reali del log dell'utente: il posticipo di un'eredita firmata ora rileva correttamente la condizione e avvia l'invalidazione.

Confermato dall'utente: "mi pare che funziona".

15. TENTATIVO E REVERT: fix doppia invalidazione al posticipo (v0.3.1 -> v0.3.2)

v0.3.1 (RITIRATA)

Per risolvere la doppia firma dell'invalidazione al posticipo, era stato introdotto Will.mark_invalidated_by_tx(), chiamato in loop_broadcast_invalidating dopo il broadcast dell'invalidazione, per marcare INVALIDATED le will che spendevano gli stessi UTXO della tx di invalidazione e persistere lo stato con save_willitems.

Perche e stata ritirata

La modifica ha introdotto una regressione grave segnalata dall'utente: la lista eredita mostrava ancora le vecchie eredita e l'aggiornamento di eredi/date risultava incoerente.

Causa: loop_broadcast_invalidating e il punto di broadcast usato per TUTTI i tipi di invalidazione (posticipo, CheckAlive, will scaduto/anticipato), non solo per il posticipo. Inoltre il metodo marcava e persisteva lo stato INVALIDATED su tutte le will item che condividevano gli UTXO del wallet (tipicamente tutte). Queste will item invalidate restavano poi in memoria e su disco, inquinando la ricostruzione di eredi/date e lasciando vecchie voci nella lista.

v0.3.2 (questa versione): REVERT completo

• Rimosso Will.mark_invalidated_by_tx() da core/will.py.
• Rimossa la chiamata in gui/qt/dialogs.py (loop_broadcast_invalidating): il metodo torna identico alla v0.3.0.
• Rimossi i due test relativi; mantenuto solo l'assert di gerarchia su WillPostponedException (corretto e indipendente).
• core/will.py e gui/qt/dialogs.py sono ora byte-identici alla v0.3.0 funzionante (verificato con git diff a394cde).

Il bug della doppia invalidazione al posticipo resta quindi aperto e andra riaffrontato in modo piu mirato (senza toccare il percorso di broadcast comune e senza persistere stati su will che condividono gli UTXO), previa conferma dell'utente. La priorita era ripristinare il comportamento corretto di lista/eredi/date.

16. Aggiornamenti mancati, Check/Close coerenti, e rifinitura UI (v0.3.2)

FIX 1 - Rimozione di un erede rilevata su Check / chiusura Electrum

core/will.py (check_willexecutors_and_heirs): prima il plugin rilevava solo l'aggiunta di un erede (raise HeirNotFoundException quando un erede corrente non era piu nella will). Mancava il caso inverso: la rimozione di un erede. Aggiunto il ramo else che lancia HeirNotFoundException anche quando la will porta ancora un erede che non e piu presente nel set di eredi corrente. Cosi la ricostruzione dell'eredita scatta su Check e alla chiusura di Electrum (entrambi usano lo stesso percorso BalBuildWillDialog.build_will_task()), come deciso dall'utente: nessun aggiornamento automatico dopo la modifica, solo manuale con Check / alla chiusura.

FIX 2 - Check interroga i server anche per le will gia inviate

core/will.py (nuovo Will.needs_server_check(w)) e gui/qt/lists.py (PreviewList.check): prima il Check interrogava i server solo per le will in stato PUSHED. Le will gia inviate ma rimaste su "New / Not sent" non venivano ricontrollate ("nothing to do"). Ora needs_server_check include ogni will VALID con un will-executor e non ancora CHECKED, anche se non in stato PUSHED. Stesso controllo usato sia dal pulsante Check sia da on_close.

FIX 3 - Hide invalidated/replaced da finestra Impostazioni aggiornava la lista

core/plugin_base.py (nuovo sync_hide_filters()) e gui/qt/window.py (update_all): le checkbox "Hide Replaced" / "Hide Invalidated" nella finestra Impostazioni scrivono direttamente la config (BalConfig.set) senza toccare i flag in cache _hide_invalidated / _hide_replaced usati dalla lista per filtrare. Risultato: la lista continuava a filtrare col valore vecchio finche non si riavviava Electrum. Ora update_all() chiama sync_hide_filters() che ri-legge i flag dalla config, quindi qualunque sorgente del cambiamento (toolbar o finestra Impostazioni) aggiorna subito la lista.

Rifinitura UI - Risultati in grassetto nel dialog "Building Will"

gui/qt/dialogs.py (BalBuildWillDialog): i risultati mostrati a destra di ogni riga di stato (es. Ok, Ko, Nothing to do, Skipped, Wait, Timeout) sono ora resi in grassetto, mantenendo i loro colori (verde/rosso/giallo). Le etichette di stato a sinistra restano in peso normale. Modifica centralizzata negli helper msg_ok, msg_error, msg_warning, msg_set_status, piu le righe dei will-executor (push e check) che ora mostrano Ok/Ko e True/False in grassetto + colore (verde/rosso).

Test

• 186 test ufficiali passano; smoke test, external-zip test e simulazione dei flussi di aggiornamento (tests/sim_update_flows.py) OK; ruff senza nuove segnalazioni reali (solo falsi positivi pre-esistenti da star-import).
• Aggiunti test in tests/test_core_will.py: test_check_heirs_unchanged_is_coherent, test_check_heir_removed_triggers_rebuild, test_check_heir_added_triggers_rebuild, test_needs_server_check.

Confermato dall'utente sui dati reali: dopo Sign -> Broadcast -> Check le transazioni gia inviate sono tornate verdi ("confirmed on server"); la lista torna pulita; il grassetto e l'aggiornamento delle hide-flag funzionano.

17. UI polish and bug fix — signed-tx colour, wizard, Building Will dialog (v0.3.3)

This session groups several behaviour-invariant UI refinements plus one colour bug fix. All comments and code remain in English; only the chat with the author was in Italian.

FIX — Signed-but-not-sent transaction shown RED instead of blue

core/will.py (needs_server_check): a previous-session change (section 16, "FIX 2") had removed the PUSHED requirement from needs_server_check, so a will that was signed but never broadcast was still server-queried. The query returned CHECK_FAIL, and because status_color() checks CHECK_FAIL (red, #e83845) before COMPLETE (blue, #2bc8ed), the row turned red. Restored the original Gitea check() condition by adding back and w.get_status("PUSHED"), so only already-broadcast wills are server-checked. A signed-but-not-sent will now stays blue (COMPLETE) as in the original.

• tests/test_core_will.py (test_needs_server_check): a freshly-built item (VALID, not PUSHED) now correctly expects False.

Wizard "Will Settings" — equal-width, left-aligned rows

gui/qt/widgets.py (WillSettingsWidget, vertical layout): the calendar button and the fee field used to stretch to the dialog's right edge, far wider than the date rows. Now every row is capped to the widest date-row width (row_w) and left-aligned, so they form a tidy column. The leading icons keep their original HelpButton width (icon_w is used only as a spacer in front of the calendar, never to widen the icons themselves).

Wizard button — icon + text

gui/qt/lists.py (create_toolbar): the "build your will" toolbar button is now more inviting: a 28×28 wizard icon plus a bold "Create your will" caption, setMinimumHeight(40). gui/qt/common.py gained QSize in the QtCore import.

Building Will dialog — clearer final report + manual Close

gui/qt/dialogs.py (BalBuildWillDialog):

• The closing summary line is no longer a bare "Ok": it now has an explicit left-side label, "All done: Ok", like the other result rows.
• A blank separator row is inserted above "All done" so the overall outcome is visually detached from the per-step rows.
• The four "checking variables" status strings are capitalised to "Checking variables" to match the rows below; the redundant trailing colon on the final one was dropped (msg_set_status already adds ":\t").
• The final auto-closing countdown (self.wait(5)) was replaced by an explicit right-aligned "Close" button (_add_close_button / _on_close_clicked). The dialog now stays open until the user dismisses it, so the full report can be read at leisure. The intermediate technical pauses (wait(10), wait(5), wait(3)) are kept. Closing still shows the persistent "next steps" (Sign / Broadcast) popup when self._next_steps_hint is set.

Preview helpers (dev-only, not shipped logic)

tests/preview_wizard_settings_align.py, tests/preview_wizard_button.py, tests/preview_building_will_close_btn.py: small offscreen scripts used to render before/after mock-ups for visual approval.

Test

• 186 official tests pass; smoke test, external-zip test OK.
• ruff reports only the pre-existing baseline false positives (F401/F403/F405 star-import re-exports, one F841, one F541) — no new issues.
• Version bumped to 0.3.3 (bal/VERSION, bal/__init__.py, bal/manifest.json).

18. Documentation site (docs/) — no behaviour change

Added a docs/ tree that renders directly on GitHub and GitHub Pages (no PDF):

• docs/inheritance-options.md + .html: a code‑accurate Inheritance Options Guide covering every change a user can make (date earlier/later, add/remove heir, change percentages, fees, will‑executors), each transaction status flag and its colour, and what happens on the will‑executor servers. Includes a decision flow chart (GitHub‑native Mermaid block in the .md, plus a static SVG fallback docs/images/inheritance-flow.svg, plus a live Mermaid render in the .html). Behaviour is derived directly from core/will.py::is_will_valid / check_willexecutors_and_heirs and gui/qt/window.py::build_inheritance_transaction.
• docs/manual/README.md + manual.html + images/: the official BAL User Manual (revB) converted from the upstream Gitea PDF into GitHub‑friendly Markdown/HTML with the original screenshots re‑rendered at high resolution (docs/manual/images/fig*.png, logo.png).
• docs/README.md: documentation index linking both documents.

No plugin code changed; 186 tests still pass.