0 Fork 0

Files

T

davideandClaude Sonnet 5.5 a4b160e240 Abandon a transaction only on proof, and keep watching failed rows (B-78, TX-15, TX-17, TX-23, TX-26, ELC-28, DAT-33, DAT-36, DAT-69, DAT-72, AUD-11, AUD-12, AUD-31, AUD-39, API-32)

reconcile_once abandoned a row when the *active* server's history lacked its txid:
after 120s for `building` (which a restart onto a different server makes likely),
after 6h for `pending`, and all at once after a forward clock jump. It re-checked the
status but not the txid, so it raced the bumper, and a `failed` row was never looked at
again.

- The reconciler asks every server (ElectrumListener.get_histories, active + others) for
  the history of the row's address and looks for every txid of the row. Present on any
  server -> promoted (adopting the version found). Absent is only "no server of the
  quorum knows it" and needs the active server plus the quorum minimum of the others to
  have answered; even then nothing is released without proof:
  (a) an input spent in a block by a transaction that is none of the row's versions,
      agreed by a strict majority of a quorum of the other servers (confirmed_spender), or
  (b) a rebroadcast of the latest raw tx to every server (rebroadcast_everywhere)
      refused by all of them, explicitly, for missing/spent inputs.
  Accepted or "already known" by any server means alive; a fee refusal is not proof
  (`building` -> `pending` for the bumper, `pending` untouched); too few answers or
  anything else leaves the row alone. failure_reason names the proof.
- The write re-reads status *and* current_txid under begin_immediate (TX-26).
- pending_transactions.failed_at (set by _abandon and _release_failed_withdrawal) starts
  a 14-day watch: a failed row that a majority of the other servers (at least the quorum
  minimum) list in a block becomes `confirmed`, writes pending_tx_resurrected once and
  pauses the lottery with paused_reason `resurrected_tx`; linked rows are not corrected.
  The confirmation is by quorum of histories for now; merkle proofs come with B-83.
- round_config.paused_reason (migration b7d2e41c9a05, with the failed_at one): `operator`
  from POST /admin/pause (which accepts an optional `note` and never overwrites an
  automatic reason), cleared by resume, which logs the reason it lifted; exposed on
  /admin/config and GET /rounds/current. rounds/pause.py:pause_automatically is the
  system's way in.
- PendingTransactionReconciler takes the listener as `network`; with none it can promote
  but never abandon.

Tests changed because the spec changed: the three reconciler tests that expect an
abandonment (and the one in test_tx_versions) now supply a network that proves the
transaction is gone.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

2026-10-14 15:07:09 +02:00

adr

Abandon a transaction only on proof, and keep watching failed rows (B-78, TX-15, TX-17, TX-23, TX-26, ELC-28, DAT-33, DAT-36, DAT-69, DAT-72, AUD-11, AUD-12, AUD-31, AUD-39, API-32)

2026-10-14 15:07:09 +02:00

api.md

Abandon a transaction only on proof, and keep watching failed rows (B-78, TX-15, TX-17, TX-23, TX-26, ELC-28, DAT-33, DAT-36, DAT-69, DAT-72, AUD-11, AUD-12, AUD-31, AUD-39, API-32)

2026-10-14 15:07:09 +02:00

architettura.md

Track every version of a bumped transaction and write the RBF replacement before broadcasting it (B-77, TX-12, TX-13, TX-19, TX-21, DAT-13, DAT-14, DAT-34, DAT-44, DAT-45, DAT-70, DAT-71)

2026-10-14 14:46:43 +02:00

audit-log.md

Abandon a transaction only on proof, and keep watching failed rows (B-78, TX-15, TX-17, TX-23, TX-26, ELC-28, DAT-33, DAT-36, DAT-69, DAT-72, AUD-11, AUD-12, AUD-31, AUD-39, API-32)

2026-10-14 15:07:09 +02:00

ciclo-di-vita-del-round.md

Abandon a transaction only on proof, and keep watching failed rows (B-78, TX-15, TX-17, TX-23, TX-26, ELC-28, DAT-33, DAT-36, DAT-69, DAT-72, AUD-11, AUD-12, AUD-31, AUD-39, API-32)

2026-10-14 15:07:09 +02:00

come-funziona.md

Restructure docs: docs-first, SSOT, one ADR per decision

2026-10-14 12:05:57 +02:00

connessione-electrum.md

Abandon a transaction only on proof, and keep watching failed rows (B-78, TX-15, TX-17, TX-23, TX-26, ELC-28, DAT-33, DAT-36, DAT-69, DAT-72, AUD-11, AUD-12, AUD-31, AUD-39, API-32)

2026-10-14 15:07:09 +02:00

guida-admin.md

Restructure docs: docs-first, SSOT, one ADR per decision

2026-10-14 12:05:57 +02:00

guida-utente.md

Replace flowchart/ with a traceable specification in docs/

2026-09-28 12:16:01 +02:00

limiti-noti.md

Abandon a transaction only on proof, and keep watching failed rows (B-78, TX-15, TX-17, TX-23, TX-26, ELC-28, DAT-33, DAT-36, DAT-69, DAT-72, AUD-11, AUD-12, AUD-31, AUD-39, API-32)

2026-10-14 15:07:09 +02:00

modello-dati.md

Abandon a transaction only on proof, and keep watching failed rows (B-78, TX-15, TX-17, TX-23, TX-26, ELC-28, DAT-33, DAT-36, DAT-69, DAT-72, AUD-11, AUD-12, AUD-31, AUD-39, API-32)

2026-10-14 15:07:09 +02:00

operativita.md

Abandon a transaction only on proof, and keep watching failed rows (B-78, TX-15, TX-17, TX-23, TX-26, ELC-28, DAT-33, DAT-36, DAT-69, DAT-72, AUD-11, AUD-12, AUD-31, AUD-39, API-32)

2026-10-14 15:07:09 +02:00

piano-correzioni.md

Restructure docs: docs-first, SSOT, one ADR per decision

2026-10-14 12:05:57 +02:00

processo-di-modifica.md

Restructure docs: docs-first, SSOT, one ADR per decision

2026-10-14 12:05:57 +02:00

README.md

Restructure docs: docs-first, SSOT, one ADR per decision

2026-10-14 12:05:57 +02:00

registrazione-e-depositi.md

Give every round its own pool address (B-80, RND-35, DAT-60, DAT-11, REG-14, SEC-08, BET-12, RND-22, WDR-14, SEC-43, API-23, API-36)

2026-10-14 13:52:32 +02:00

running-the-server.md

Restructure docs: docs-first, SSOT, one ADR per decision

2026-10-14 12:05:57 +02:00

scommesse-e-prelievi.md

Never roll back an ambiguous broadcast as if it had been refused (B-76, TX-04, TX-05, TX-20, TX-21, BET-16, BET-17, BET-23, WDR-11, WDR-12, WDR-16, API-13)

2026-10-14 14:22:20 +02:00

setup.md

Require a real Electrum quorum and allow certificate pinning (B-84, ELC-01, ELC-03, ELC-14, ELC-19, ARC-20, OPS-12)

2026-10-14 14:04:35 +02:00

sicurezza.md

Require a real Electrum quorum and allow certificate pinning (B-84, ELC-01, ELC-03, ELC-14, ELC-19, ARC-20, OPS-12)

2026-10-14 14:04:35 +02:00

storico-bug.md

Abandon a transaction only on proof, and keep watching failed rows (B-78, TX-15, TX-17, TX-23, TX-26, ELC-28, DAT-33, DAT-36, DAT-69, DAT-72, AUD-11, AUD-12, AUD-31, AUD-39, API-32)

2026-10-14 15:07:09 +02:00

transazioni-e-riconciliazione.md

Abandon a transaction only on proof, and keep watching failed rows (B-78, TX-15, TX-17, TX-23, TX-26, ELC-28, DAT-33, DAT-36, DAT-69, DAT-72, AUD-11, AUD-12, AUD-31, AUD-39, API-32)

2026-10-14 15:07:09 +02:00

README.md

Documentazione di PLM Lottery

Questa cartella è la fonte di verità del progetto: si lavora docs-first (prima si scrive o si modifica la documentazione, poi il codice) e ogni informazione ha un solo proprietario (SSOT). Questo file è l'indice: da qui si raggiunge tutto il resto.

I tre principi

Docs-first. Nessuna modifica di comportamento parte dal codice. Si modifica il requisito (o si scrive l'ADR, se è una scelta nuova), poi si implementa, poi si testa. Spec, codice e test entrano nello stesso commit.
SSOT — un solo proprietario per ogni informazione. Il perché di una scelta sta in un ADR; il cosa verificabile in un requisito (PREFISSO-NN) del documento di dominio; il come nel codice; la cronologia dei difetti in storico-bug.md. Gli altri documenti rimandano all'ID, non ripetono il testo. Se due documenti dicono cose diverse, vince la specifica e si corregge l'altro.
Un ADR per ogni funzionalità. Ogni funzionalità nuova inizia con un ADR in adr/ (modello: adr/TEMPLATE.md) che registra contesto, decisione, alternative scartate e conseguenze, e ne elenca i requisiti.

Dove si trova cosa

Domanda	Dove
Perché è fatto così? Quali alternative sono state scartate?	adr/ — indice per area e tabella funzionalità → ADR
Cosa deve fare esattamente il software?	I documenti di dominio qui sotto (requisiti con ID stabile)
Quali limiti abbiamo accettato?	limiti-noti.md (`LIM-nn`)
Che bug sono stati trovati/corretti? Quali restano aperti?	storico-bug.md; i soli aperti in ../BUGS.md
In che ordine si implementano le correzioni aperte?	piano-correzioni.md
Come si modifica la documentazione/il codice?	processo-di-modifica.md
Come si installa, si avvia, si usa?	Guide operative qui sotto

Specifica (documenti di dominio)

Punto d'ingresso narrativo: come-funziona.md.

Documento	Prefisso	Contenuto
registrazione-e-depositi.md	`REG`, `DEP`	Account, indirizzi, depositi, saldo
scommesse-e-prelievi.md	`BET`, `WDR`	Scommesse e prelievi
ciclo-di-vita-del-round.md	`RND`	Apertura, chiusura, estrazione, pagamento
transazioni-e-riconciliazione.md	`TX`	Ciclo di vita delle transazioni, RBF, riconciliazione
connessione-electrum.md	`ELC`	Accesso alla rete PLM e difese
architettura.md	`ARC`	Struttura del codice, processi, frontend, test
modello-dati.md	`DAT`	Tabelle, campi, stati, vincoli
api.md	`API`	Endpoint, risposte, codici di errore
sicurezza.md	`SEC`	Fiducia, chiavi, autenticazione, limiti sui tentativi
audit-log.md	`AUD`	Catalogo degli eventi di audit
operativita.md	`OPS`	Backup, riavvii, incidenti

Decisioni, limiti, storia

Documento	Prefisso	Contenuto
adr/	`ADR`	Una decisione di progetto per file (53 al momento)
limiti-noti.md	`LIM`	Limiti accettati consapevolmente
storico-bug.md	`B-nn`	Tutti i bug trovati e corretti
piano-correzioni.md	—	Ordine di implementazione delle correzioni aperte

Guide operative (senza requisiti)

setup.md · running-the-server.md · guida-utente.md · guida-admin.md. Si aggiornano quando la specifica cambia qualcosa di visibile.

Lingua

La documentazione di docs/ è in italiano, per scelta esplicita; tutto il resto del repository (codice, commenti, commit, CLAUDE.md, BUGS.md) è in inglese.