temp
This commit is contained in:
1 parent
61efbb0e37
commit
c5e7daa9c7
15 files changed
+4514
-1172
No files matched your search
+201
-80
@@ -29,124 +29,206 @@ Prima dei controlli valgono due condizioni di contorno:
|
||||
- **[BET-01]** Se il server non è connesso alla rete, la scommessa è
|
||||
rifiutata con `network_unavailable` (HTTP 503) prima di qualunque altro
|
||||
controllo.
|
||||
*Codice:* `app/api/routes/bets.py:create_bet`
|
||||
*Codice:* `app/api/routes/bets.py:create_bet` ·
|
||||
*Test:* — (nessun test verifica `network_unavailable`)
|
||||
- **[BET-02]** Tutta l'elaborazione di una scommessa, dai controlli all'invio,
|
||||
avviene tenendo il **blocco per-utente**, lo stesso usato dal prelievo
|
||||
([WDR-01](#prelievo)).
|
||||
*Codice:* `app/api/routes/bets.py:create_bet`, `app/tx/locks.py:UserLocks.acquire`
|
||||
([WDR-01](#prelievo)). Il client della rete usato per la scommessa
|
||||
(`listener.client`) viene letto **dopo** aver acquisito il blocco, così
|
||||
un'attesa sul blocco durante una riconnessione non fa usare una connessione
|
||||
già chiusa; il controllo di [BET-01] si fa su quel valore.
|
||||
*Codice:* `app/api/routes/bets.py:create_bet`, `app/tx/locks.py:UserLocks.acquire` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-96) · *Oggi:* `listener.client` viene letto e
|
||||
controllato prima di acquisire il blocco.
|
||||
|
||||
Una scommessa (`POST /bets`, senza corpo) passa solo se **tutte** queste
|
||||
condizioni sono vere, verificate nell'ordine della tabella; altrimenti viene
|
||||
rifiutata con il codice indicato (HTTP 400), prima che si muova qualunque
|
||||
cifra:
|
||||
cifra. Il **costo** è quello del round ([BET-21]):
|
||||
|
||||
| ID | Condizione | Codice di errore |
|
||||
|---|---|---|
|
||||
| **[BET-03]** | C'è un round attivo. Se non ce n'è nessuno e le condizioni di apertura sono soddisfatte ([RND-03](ciclo-di-vita-del-round.md#0--apertura)), è la scommessa stessa ad aprirlo | `no_round_open` |
|
||||
| **[BET-04]** | Il round è in stato `open` e la sua scadenza non è ancora passata | `round_closing` |
|
||||
| **[BET-03]** | C'è un round attivo. Se non ce n'è nessuno e le condizioni di apertura sono soddisfatte ([RND-04](ciclo-di-vita-del-round.md#0--apertura)), è la scommessa stessa ad aprirlo | `no_round_open` |
|
||||
| **[BET-04]** | Il round è in stato `open` e la sua **scadenza** — apertura più la durata fotografata all'apertura (`opened_at + duration_seconds`), non lo stato nel database — non è ancora passata | `round_closing` |
|
||||
| **[BET-05]** | L'utente non ha già una scommessa in questo round (in qualunque stato) | `already_betting` |
|
||||
| **[BET-06]** | Il round ha meno di 400 partecipanti (`MAX_PARTICIPANTS_PER_ROUND`), contando anche quelli non ancora confermati | `round_full` (parametro `max_participants`) |
|
||||
| **[BET-07]** | La somma delle monete confermate e non spese copre il costo della scommessa (`bet_amount_sats`) | `insufficient_balance` (parametro `required_sats`) |
|
||||
| **[BET-08]** | Il costo si copre con al massimo 50 monete (`MAX_TX_INPUTS`), scelte dalla più grande | `too_many_inputs` (parametro `max_inputs`) |
|
||||
| **[BET-09]** | Dopo la scommessa resta un resto di almeno 294 sat (`DUST_LIMIT_SATS`) | `balance_leaves_no_change` (parametro `required_extra_sats`) |
|
||||
| **[BET-20]** | Se il round ha un tetto al montepremi (`max_round_pool_sats` fotografato all'apertura, [RND-05](ciclo-di-vita-del-round.md#0--apertura)) diverso da 0, la somma degli importi netti dei partecipanti del round, contando anche quelli non ancora confermati, è minore del tetto. *Stato:* da implementare (B-95) · *Oggi:* il tetto non esiste | `round_full` |
|
||||
| **[BET-07]** | La somma delle monete confermate e non spese copre il costo della scommessa | `balance_pending_confirmation` se lo coprirebbe il saldo comprensivo di quanto è in corso (parametro `pending_sats`), altrimenti `insufficient_balance` (parametro `required_sats`), come per il prelievo ([WDR-05](#prelievo)). *Stato:* da implementare (B-96) · *Oggi:* sempre `insufficient_balance`, anche quando il saldo mostrato all'utente copre la scommessa |
|
||||
| **[BET-08]** | Il costo si copre con al massimo 50 monete (`MAX_TX_INPUTS`), scelte dalla più grande fino a coprirlo | `too_many_inputs` (parametro `max_inputs`) |
|
||||
| **[BET-09]** | Le monete scelte ([BET-08]) superano il costo di almeno 294 sat (`DUST_LIMIT_SATS`), che restano come resto | `balance_leaves_no_change` (parametro `required_extra_sats`) |
|
||||
| **[BET-10]** | Il costo meno la commissione di rete resta positivo e di almeno 294 sat | `amount_below_network_fee`, `amount_below_dust_limit` |
|
||||
|
||||
*Codice:* `app/bets/service.py:place_bet`, `app/rounds/service.py:round_accepts_bets`,
|
||||
`app/wallet/psbt_builder.py:select_utxos`, `app/wallet/psbt_builder.py:build_signed_transaction` ·
|
||||
*Test:* `tests/unit/test_bets.py`, `tests/unit/test_withdrawals.py`, `tests/unit/test_psbt_builder.py`
|
||||
(nessun test verifica `no_round_open`)
|
||||
|
||||
La **scadenza** è quella del round stesso (apertura + durata fissata
|
||||
all'apertura), non il suo stato nel database: lo scheduler controlla ogni 5
|
||||
secondi, quindi per qualche istante il round potrebbe risultare ancora
|
||||
"aperto" oltre la scadenza.
|
||||
Lo stato nel database non basta per la scadenza ([BET-04]) perché lo
|
||||
scheduler controlla ogni 5 secondi: fino a 5 secondi il round può risultare
|
||||
ancora `open` oltre la scadenza.
|
||||
|
||||
La selezione si ferma alla prima moneta che porta il totale a coprire il
|
||||
costo ([BET-08]): il resto di [BET-09] si misura su quelle monete, non
|
||||
sull'intero saldo.
|
||||
|
||||
- **[BET-21]** Il **costo** di una scommessa è il `bet_amount_sats`
|
||||
fotografato sul round alla sua apertura
|
||||
([RND-05](ciclo-di-vita-del-round.md#0--apertura)), non il valore corrente
|
||||
di `round_config`: una modifica da `/admin` vale dal round successivo.
|
||||
*Codice:* `app/bets/service.py:place_bet` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-95) · *Oggi:* il costo è letto da
|
||||
`round_config` a ogni scommessa, quindi una modifica vale subito anche per
|
||||
il round in corso.
|
||||
- **[BET-11]** La scadenza viene verificata due volte: all'arrivo della
|
||||
richiesta ([BET-04]) e di nuovo dopo aver costruito e firmato la
|
||||
transazione. L'iscrizione al round viene poi salvata nella stessa
|
||||
transazione del database di un *compare-and-set* sulla riga del round
|
||||
transazione del database — aperta con `BEGIN IMMEDIATE`
|
||||
([TX-28](transazioni-e-riconciliazione.md#il-principio-prima-si-scrive-poi-si-invia))
|
||||
— di un *compare-and-set* sulla riga del round
|
||||
(`UPDATE rounds … WHERE status = 'open'`): se il round non è più aperto in
|
||||
quell'istante esatto, o il database segnala un conflitto di scrittura, tutto
|
||||
viene annullato prima dell'invio e la scommessa è rifiutata con
|
||||
`round_closing`. Così nessuna scommessa può finire nel montepremi senza
|
||||
essere inclusa nell'estrazione.
|
||||
quell'istante esatto tutto viene annullato prima dell'invio e la scommessa è
|
||||
rifiutata con `round_closing`. Così nessuna scommessa può finire nel
|
||||
montepremi senza essere inclusa nell'estrazione. Un `OperationalError` in
|
||||
questo punto non è un conflitto di scrittura (SQLite non ne produce): è il
|
||||
blocco in scrittura non ottenuto entro 5 secondi (`database is locked`).
|
||||
Anche in quel caso tutto viene annullato prima dell'invio, ma la risposta è
|
||||
`service_busy` (HTTP 503), perché il round non è necessariamente in
|
||||
chiusura.
|
||||
*Codice:* `app/bets/service.py:place_bet` ·
|
||||
*Test:* `tests/unit/test_bets.py`
|
||||
*Stato:* da implementare (B-88) · *Oggi:* la transazione si apre con la
|
||||
prima scrittura, non con `BEGIN IMMEDIATE`; un `OperationalError` viene
|
||||
trattato come un conflitto di scrittura e risponde `round_closing`.
|
||||
- **[BET-22]** `MAX_PARTICIPANTS_PER_ROUND` è minore di
|
||||
`MAX_PAYOUT_TX_INPUTS`. Il pagamento spende una moneta del montepremi per
|
||||
ogni scommessa, e una singola transazione di pagamento può spenderne al
|
||||
massimo 500; bloccare il 401° giocatore all'ingresso ([BET-06]) fa sì che
|
||||
il numero di monete non impedisca mai di pagare un round. La differenza
|
||||
lascia spazio ad altre monete presenti sull'indirizzo del montepremi del
|
||||
round (pagamenti arrivati da fuori).
|
||||
*Codice:* `app/wallet/psbt_builder.py:MAX_PARTICIPANTS_PER_ROUND`, `app/bets/service.py:place_bet` ·
|
||||
*Test:* `tests/unit/test_payout_builder.py`, `tests/unit/test_bets.py`
|
||||
|
||||
Il limite di **400 partecipanti** esiste perché il pagamento deve spendere una
|
||||
moneta del montepremi per ogni scommessa, e una singola transazione di
|
||||
pagamento può contenerne al massimo 500 (`MAX_PAYOUT_TX_INPUTS`); la
|
||||
differenza lascia spazio ai resti accumulati nel montepremi dai round
|
||||
precedenti. Bloccare il 401° giocatore all'ingresso garantisce che ogni round
|
||||
si possa sempre pagare.
|
||||
Oggi il montepremi è un solo indirizzo per tutti i round, e la differenza fra
|
||||
400 e 500 copre anche i resti accumulati dai pagamenti precedenti; con un
|
||||
indirizzo per round
|
||||
([RND-35](ciclo-di-vita-del-round.md#0--apertura), B-80) restano solo i
|
||||
pagamenti arrivati da fuori. Il numero di ingressi non è l'unica cosa che può
|
||||
impedire un pagamento: vedi
|
||||
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#4--pagamento).
|
||||
|
||||
### Cosa succede
|
||||
|
||||
Comportamento atteso:
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
A["Richiesta di scommessa"] --> N{"Connessi<br/>alla rete?"}
|
||||
A["Richiesta di scommessa"] --> B["Blocco per-utente acquisito"]
|
||||
B --> N{"Connessi<br/>alla rete?"}
|
||||
N -- "No" --> N1["network_unavailable (503)"]
|
||||
N -- "Sì" --> B["Blocco per-utente acquisito"]
|
||||
B --> C["Controlli (tabella sopra)"]
|
||||
N -- "Sì" --> C["Controlli (tabella sopra)"]
|
||||
C --> D["Scelta delle monete,<br/>dalla più grande"]
|
||||
D --> E["Transazione firmata:<br/>costo meno commissione → montepremi<br/>resto → indirizzo utente"]
|
||||
D --> E["Transazione firmata:<br/>costo meno commissione → montepremi del round<br/>resto → indirizzo utente"]
|
||||
E --> CAS{"Scadenza non passata e<br/>round ancora 'open'<br/>(compare-and-set)?"}
|
||||
CAS -- "No" --> CAS1["Annullato prima dell'invio:<br/>round_closing"]
|
||||
CAS -- "Sì" --> F["Salvataggio PRIMA dell'invio:<br/>monete segnate come spese,<br/>partecipante 'building'"]
|
||||
F --> G{"La rete accetta<br/>l'invio?"}
|
||||
G -- "No" --> H["Tutto annullato: monete liberate,<br/>saldo ripristinato,<br/>partecipante rimosso (errore 502)"]
|
||||
G -- "Sì" --> I["Partecipante 'broadcast'<br/>(in attesa)"]
|
||||
F --> G{"Risposta del server"}
|
||||
G -- "Rifiuto esplicito" --> H["Tutto annullato: monete liberate,<br/>saldo ripristinato,<br/>partecipante rimosso (errore 502)"]
|
||||
G -- "Nessuna risposta<br/>(timeout, connessione caduta)" --> U["Nulla liberato: partecipante 'building'<br/>(202), decide il riconciliatore"]
|
||||
G -- "Accettata o già nota" --> I["Partecipante 'broadcast'<br/>(in attesa), inviata anche<br/>agli altri server"]
|
||||
U --> R{"Il riconciliatore<br/>la trova in rete?"}
|
||||
R -- "Sì" --> I
|
||||
R -- "No, e c'è la prova<br/>che non è partita" --> X
|
||||
I --> J{"Confermata entro<br/>il tempo limite?"}
|
||||
J -- "No" --> K["Commissione aumentata (RBF),<br/>pagata dal resto dell'utente"] --> J
|
||||
J -- "Mai, e la rete non<br/>la conosce più" --> X["Abbandonata dal riconciliatore:<br/>monete liberate, partecipante rimosso"]
|
||||
J -- "Sì" --> L["Partecipante confermato:<br/>entra nell'estrazione"]
|
||||
J -- "No" --> K["Commissione aumentata (RBF),<br/>pagata dal resto dell'utente;<br/>un resto che finirebbe sotto 294 sat<br/>va tutto in commissione"] --> J
|
||||
J -- "Mai, e c'è la prova<br/>che non è partita" --> X["Abbandonata dal riconciliatore:<br/>monete liberate, partecipante rimosso"]
|
||||
J -- "Sì (prova merkle del quorum)" --> L["Partecipante confermato:<br/>entra nell'estrazione"]
|
||||
```
|
||||
|
||||
- **[BET-12]** La transazione spende monete **intere** dell'utente, scelte
|
||||
dalla più grande; tutti gli ingressi segnalano la sostituibilità (BIP125,
|
||||
`RBF_SEQUENCE`). Ha due uscite: il costo meno la commissione verso
|
||||
l'indirizzo del montepremi, e il resto (monete spese meno il costo) verso
|
||||
l'indirizzo dell'utente.
|
||||
*Codice:* `app/wallet/psbt_builder.py:select_utxos`, `app/wallet/psbt_builder.py:build_signed_transaction` ·
|
||||
l'**indirizzo del montepremi del round** (`rounds.pool_address`,
|
||||
[RND-35](ciclo-di-vita-del-round.md#0--apertura)), e il resto (monete
|
||||
spese meno il costo) verso l'indirizzo dell'utente.
|
||||
*Codice:* `app/wallet/psbt_builder.py:select_utxos`, `app/wallet/psbt_builder.py:build_signed_transaction`, `app/bets/service.py:place_bet` ·
|
||||
*Test:* `tests/unit/test_psbt_builder.py`
|
||||
*Stato:* da implementare (B-80) · *Oggi:* tutte le scommesse di tutti i
|
||||
round pagano lo stesso indirizzo (`derive_pool_address`,
|
||||
`m/84'/746'/0'/1/0`).
|
||||
- **[BET-13]** La **commissione di rete** è la dimensione stimata della
|
||||
transazione per `fee_rate_sat_vb` (1 sat/vB predefinito, modificabile da
|
||||
`/admin`) ed è **dedotta dal costo** della scommessa: al montepremi arrivano
|
||||
10 PLM meno la commissione, e l'importo registrato per il partecipante
|
||||
`/admin`) ed è **dedotta dal costo** della scommessa: al montepremi arriva
|
||||
il costo meno la commissione, e l'importo registrato per il partecipante
|
||||
(`bet_amount_sats`) è proprio questo netto. Per questo il montepremi si
|
||||
calcola sommando gli importi effettivi delle scommesse, non moltiplicando il
|
||||
numero di giocatori per il costo.
|
||||
*Codice:* `app/wallet/psbt_builder.py:build_signed_transaction`, `app/bets/service.py:place_bet` ·
|
||||
*Test:* `tests/unit/test_psbt_builder.py`, `tests/unit/test_rounds_route.py`
|
||||
- **[BET-14]** Il **resto** torna sempre allo stesso indirizzo dell'utente ed è
|
||||
sempre di almeno 294 sat: senza un'uscita di resto non si potrebbe aumentare
|
||||
la commissione in caso di ritardo. A differenza del prelievo, la scommessa
|
||||
non riduce mai il proprio importo per far posto al resto: la rifiuta
|
||||
([BET-09]). Il saldo di un utente che scommette deve quindi essere
|
||||
strettamente maggiore del costo.
|
||||
sempre di almeno 294 sat (`DUST_LIMIT_SATS`). A differenza del prelievo, la
|
||||
scommessa non riduce mai il proprio importo per far posto al resto: la
|
||||
rifiuta ([BET-09]). Le monete scelte devono quindi superare il costo di
|
||||
almeno 294 sat. Questo resto è l'uscita che l'RBF riduce o elimina, secondo
|
||||
la regola di
|
||||
[TX-11](transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta):
|
||||
un resto di 294 sat non regge una riduzione (l'aumento minimo è di 141 sat a
|
||||
1 sat/vB), quindi garantisce una sola accelerazione, che lo elimina.
|
||||
*Codice:* `app/wallet/psbt_builder.py:build_signed_transaction` ·
|
||||
*Test:* `tests/unit/test_withdrawals.py`, `tests/unit/test_psbt_builder.py`
|
||||
*Test:* `tests/unit/test_withdrawals.py` (i test del resto delle scommesse
|
||||
sono lì: `test_a_bet_from_a_balance_equal_to_the_bet_is_refused`,
|
||||
`test_a_bet_with_a_dust_limit_of_headroom_is_accepted`),
|
||||
`tests/unit/test_psbt_builder.py`
|
||||
- **[BET-15]** **Prima si scrive, poi si invia.** Prima dell'invio, in
|
||||
un'unica transazione del database, le monete spese vengono segnate come tali
|
||||
(con il txid della scommessa), il saldo viene ricalcolato, e si registrano il
|
||||
partecipante (stato `building`, con l'orario di invio che ne determina
|
||||
l'ordine nell'estrazione) e la transazione in corso (stato `building`).
|
||||
partecipante (stato `building`, con l'orario di invio `broadcast_at`) e la
|
||||
transazione in corso (stato `building`). L'ordine dei partecipanti
|
||||
nell'estrazione è definito in
|
||||
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#3--estrazione).
|
||||
Dettagli in
|
||||
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md#il-principio-prima-si-scrive-poi-si-invia).
|
||||
*Codice:* `app/bets/service.py:place_bet` ·
|
||||
*Test:* `tests/unit/test_bets.py`
|
||||
- **[BET-16]** Se l'invio fallisce per qualunque motivo, tutto torna com'era:
|
||||
monete liberate, partecipante e transazione in corso **cancellati**, saldo
|
||||
ricalcolato, evento `bet_broadcast_failed` nel registro di audit, notifica
|
||||
SSE; la risposta è `broadcast_failed` (HTTP 502).
|
||||
- **[BET-16]** Se il server **rifiuta esplicitamente** l'invio
|
||||
([TX-04](transazioni-e-riconciliazione.md#invio-rifiutato)), tutto torna
|
||||
com'era: monete liberate, partecipante e transazione in corso
|
||||
**cancellati**, saldo ricalcolato, evento `bet_broadcast_failed` nel
|
||||
registro di audit, notifica SSE; la risposta è `broadcast_failed`
|
||||
(HTTP 502).
|
||||
*Codice:* `app/bets/service.py:_release_failed_bet`, `app/api/routes/bets.py:create_bet` ·
|
||||
*Test:* `tests/unit/test_bets.py`
|
||||
- **[BET-17]** Se l'invio riesce, il partecipante passa a `broadcast`, la
|
||||
transazione in corso a `pending`, si scrive `bet_placed` (txid e importo
|
||||
netto) e si invia una notifica SSE. La risposta è HTTP 201 con `round_id`,
|
||||
`bet_txid`, `bet_amount_sats` e `status`.
|
||||
*Stato:* da implementare (B-76) · *Oggi:* tutto viene annullato per
|
||||
qualunque errore dell'invio, anche un timeout o una connessione caduta
|
||||
dopo la scrittura, quando la transazione può essere già in rete: i suoi
|
||||
sat arrivano al montepremi senza partecipante.
|
||||
- **[BET-23]** Se l'invio ha un **esito incerto**
|
||||
([TX-20](transazioni-e-riconciliazione.md#invio-rifiutato)), partecipante e
|
||||
transazione in corso restano `building` con le monete ancora segnate come
|
||||
spese, e la risposta è HTTP **202** con `round_id`, `bet_txid`,
|
||||
`bet_amount_sats` e `status` = `building`. Il partecipante conta per il
|
||||
limite di [BET-06] e tiene il round in `closing` finché il riconciliatore
|
||||
non lo promuove o lo abbandona.
|
||||
*Codice:* `app/bets/service.py:place_bet`, `app/api/routes/bets.py:create_bet` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-76) · *Oggi:* un esito incerto è trattato come
|
||||
un rifiuto ([BET-16]).
|
||||
- **[BET-17]** Se l'invio è accettato — anche con un rifiuto "già nota"
|
||||
([TX-04](transazioni-e-riconciliazione.md#invio-rifiutato)) — il
|
||||
partecipante passa a `broadcast`, la transazione in corso a `pending`, si
|
||||
scrive `bet_placed` (txid e importo netto) e si invia una notifica SSE; la
|
||||
transazione viene poi inviata anche agli altri server
|
||||
([TX-21](transazioni-e-riconciliazione.md#invio-rifiutato)). La risposta è
|
||||
HTTP 201 con `round_id`, `bet_txid`, `bet_amount_sats` e `status`. Una
|
||||
scommessa promossa dal riconciliatore scrive `bet_placed` in quel momento
|
||||
([TX-16](transazioni-e-riconciliazione.md#riconciliazione)).
|
||||
*Codice:* `app/bets/service.py:place_bet`, `app/api/routes/bets.py:create_bet` ·
|
||||
*Test:* `tests/unit/test_bets.py`
|
||||
- **[BET-18]** Alla prima conferma il partecipante passa a `confirmed`
|
||||
*Stato:* da implementare (B-76) · *Oggi:* un "già nota" è trattato come un
|
||||
rifiuto e la transazione va solo al server attivo.
|
||||
- **[BET-18]** Alla conferma il partecipante passa a `confirmed`
|
||||
([TX-07](transazioni-e-riconciliazione.md#conferma)). Solo le scommesse
|
||||
**confermate** partecipano all'estrazione; il round, allo scadere, aspetta
|
||||
che tutte quelle già inviate confermino (vedi
|
||||
@@ -167,8 +249,12 @@ esterno scelto dall'utente.
|
||||
|
||||
- **[WDR-01]** Come per la scommessa, un prelievo senza connessione alla rete
|
||||
è rifiutato con `network_unavailable` (HTTP 503), e tutta l'elaborazione
|
||||
avviene tenendo il **blocco per-utente**.
|
||||
*Codice:* `app/api/routes/withdrawals.py:create_withdrawal`, `app/tx/locks.py:UserLocks.acquire`
|
||||
avviene tenendo il **blocco per-utente**; il client della rete viene letto
|
||||
e controllato dopo aver acquisito il blocco, come in [BET-02].
|
||||
*Codice:* `app/api/routes/withdrawals.py:create_withdrawal`, `app/tx/locks.py:UserLocks.acquire` ·
|
||||
*Test:* — (nessun test verifica `network_unavailable`)
|
||||
*Stato:* da implementare (B-96) · *Oggi:* `listener.client` viene letto e
|
||||
controllato prima di acquisire il blocco.
|
||||
|
||||
Le condizioni sono verificate nell'ordine della tabella; un rifiuto risponde
|
||||
HTTP 400 prima che si muova qualunque cifra:
|
||||
@@ -177,7 +263,8 @@ HTTP 400 prima che si muova qualunque cifra:
|
||||
|---|---|---|
|
||||
| **[WDR-02]** | L'indirizzo di destinazione è un indirizzo PLM bech32: inizia con `plm1` ed è decodificabile. Un indirizzo di un'altra catena (ad esempio `bc1…`) o in formato legacy (`P…`) è rifiutato | `invalid_address` |
|
||||
| **[WDR-03]** | L'indirizzo di destinazione non è l'indirizzo di deposito dell'utente stesso | `withdrawal_to_own_address` |
|
||||
| **[WDR-04]** | L'importo è almeno pari al costo corrente di una scommessa (`bet_amount_sats`; non esiste un minimo separato) | `amount_below_minimum` (parametro `minimum_sats`) |
|
||||
| **[WDR-14]** | L'indirizzo di destinazione non è un indirizzo della piattaforma: l'indirizzo del montepremi di un round qualunque (`rounds.pool_address`), l'indirizzo di riserva (`m/84'/746'/0'/1/0`, [RND-35](ciclo-di-vita-del-round.md#0--apertura)), il `fee_address` corrente di `round_config` o quello fotografato su un round. *Stato:* da implementare (B-80) · *Oggi:* nessun controllo; un prelievo verso il montepremi finisce fra le monete di un round | `withdrawal_to_platform_address` |
|
||||
| **[WDR-04]** | L'importo è almeno pari al costo di una scommessa **corrente** in `round_config` (`bet_amount_sats`; non esiste un minimo separato, e non si usa il costo fotografato su un round) | `amount_below_minimum` (parametro `minimum_sats`) |
|
||||
| **[WDR-05]** | La somma delle monete confermate e non spese copre l'importo | `balance_pending_confirmation` se lo coprirebbe il saldo comprensivo di quanto è in corso (parametro `pending_sats`), altrimenti `insufficient_balance` (parametro `required_sats`) |
|
||||
| **[WDR-06]** | L'importo si copre con al massimo 50 monete (`MAX_TX_INPUTS`) | `too_many_inputs` (parametro `max_inputs`) |
|
||||
| **[WDR-07]** | L'importo meno la commissione di rete resta positivo e di almeno 294 sat | `amount_below_network_fee`, `amount_below_dust_limit` |
|
||||
@@ -189,7 +276,7 @@ HTTP 400 prima che si muova qualunque cifra:
|
||||
La struttura è identica alla scommessa: transazione firmata dall'indirizzo
|
||||
dell'utente verso l'indirizzo esterno, resto all'utente, **commissione dedotta
|
||||
dall'importo prelevato**, salvataggio prima dell'invio, annullamento completo
|
||||
se la rete rifiuta, RBF se non conferma in tempo.
|
||||
solo se la rete rifiuta esplicitamente, RBF se non conferma in tempo.
|
||||
|
||||
- **[WDR-08]** La transazione spende monete intere dell'utente (dalla più
|
||||
grande, ingressi sostituibili BIP125); all'indirizzo esterno arriva
|
||||
@@ -198,36 +285,70 @@ se la rete rifiuta, RBF se non conferma in tempo.
|
||||
*Codice:* `app/wallet/psbt_builder.py:build_signed_transaction` ·
|
||||
*Test:* `tests/unit/test_psbt_builder.py`, `tests/unit/test_withdrawals.py`
|
||||
- **[WDR-09]** **Resto garantito.** Se l'importo richiesto lascerebbe un resto
|
||||
inferiore a 294 sat — tipicamente il prelievo dell'intero saldo —, l'importo
|
||||
viene ridotto quanto basta perché il resto sia esattamente 294 sat, che
|
||||
restano sul conto dell'utente. Chi preleva tutto riceve quindi il saldo meno
|
||||
294 sat meno la commissione. Il database registra sia l'importo richiesto
|
||||
(`amount_requested_sats`) sia quello effettivamente inviato al destinatario,
|
||||
al netto della commissione (`amount_sent_sats`).
|
||||
inferiore a 294 sat (`DUST_LIMIT_SATS`) — ad esempio il prelievo
|
||||
dell'intero saldo —, l'importo viene ridotto quanto basta perché il resto
|
||||
sia esattamente 294 sat, che restano sul conto dell'utente. Chi preleva
|
||||
tutto riceve quindi il saldo meno 294 sat meno la commissione. Il database
|
||||
registra sia l'importo richiesto (`amount_requested_sats`) sia quello
|
||||
effettivamente inviato al destinatario, al netto della commissione
|
||||
(`amount_sent_sats`). Come per la scommessa ([BET-14]), questo resto è
|
||||
l'uscita che l'RBF riduce o elimina
|
||||
([TX-11](transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta)).
|
||||
*Codice:* `app/wallet/psbt_builder.py:build_signed_transaction`, `app/withdrawals/service.py:request_withdrawal` ·
|
||||
*Test:* `tests/unit/test_withdrawals.py`, `tests/unit/test_psbt_builder.py`
|
||||
- **[WDR-10]** Prima dell'invio, in un'unica transazione del database, le
|
||||
monete spese vengono segnate come tali, il saldo ricalcolato, e si
|
||||
- **[WDR-15]** L'importo ridotto da [WDR-09] viene verificato di nuovo
|
||||
contro il minimo di [WDR-04]: se è sceso sotto `bet_amount_sats`, il
|
||||
prelievo è rifiutato con `amount_below_minimum` (parametro `minimum_sats`)
|
||||
prima che si muova qualunque cifra.
|
||||
*Codice:* `app/withdrawals/service.py:request_withdrawal` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-96) · *Oggi:* il minimo è verificato solo
|
||||
sull'importo richiesto, quindi un prelievo dell'intero saldo può inviare
|
||||
fino a 294 sat meno del minimo.
|
||||
- **[WDR-10]** Prima dell'invio, in un'unica transazione del database
|
||||
([TX-28](transazioni-e-riconciliazione.md#il-principio-prima-si-scrive-poi-si-invia)),
|
||||
le monete spese vengono segnate come tali, il saldo ricalcolato, e si
|
||||
registrano il prelievo e la transazione in corso, entrambi in stato
|
||||
`building`.
|
||||
*Codice:* `app/withdrawals/service.py:request_withdrawal` ·
|
||||
*Test:* `tests/unit/test_withdrawals.py`
|
||||
- **[WDR-11]** Se l'invio fallisce, le monete vengono liberate e il saldo
|
||||
ricalcolato, ma — a differenza della scommessa — il prelievo **non viene
|
||||
cancellato**: resta come `failed` (senza txid), così come la transazione in
|
||||
corso (con il motivo in `failure_reason`); si scrive
|
||||
`withdrawal_broadcast_failed`, si invia una notifica SSE e la risposta è
|
||||
`broadcast_failed` (HTTP 502).
|
||||
- **[WDR-11]** Se il server **rifiuta esplicitamente** l'invio
|
||||
([TX-04](transazioni-e-riconciliazione.md#invio-rifiutato)), le monete
|
||||
vengono liberate e il saldo ricalcolato, ma — a differenza della
|
||||
scommessa — il prelievo **non viene cancellato**: resta come `failed`
|
||||
(senza txid), così come la transazione in corso (con il motivo in
|
||||
`failure_reason`); si scrive `withdrawal_broadcast_failed`, si invia una
|
||||
notifica SSE e la risposta è `broadcast_failed` (HTTP 502).
|
||||
*Codice:* `app/withdrawals/service.py:_release_failed_withdrawal`, `app/api/routes/withdrawals.py:create_withdrawal` ·
|
||||
*Test:* `tests/unit/test_withdrawals.py`
|
||||
- **[WDR-12]** Se l'invio riesce, il prelievo passa a `broadcast`, la
|
||||
transazione in corso a `pending`, si scrive `withdrawal_sent` (txid, importo
|
||||
inviato, indirizzo esterno) e si invia una notifica SSE. La risposta è
|
||||
HTTP 201 con `txid`, `amount_requested_sats`, `amount_sent_sats` e `status`.
|
||||
Alla prima conferma il prelievo passa a `confirmed`
|
||||
*Test:* `tests/unit/test_withdrawals.py` (nessun test verifica l'evento
|
||||
`withdrawal_broadcast_failed`)
|
||||
*Stato:* da implementare (B-76) · *Oggi:* tutto viene annullato per
|
||||
qualunque errore dell'invio, anche un timeout o una connessione caduta
|
||||
dopo la scrittura: la transazione può essere partita mentre il prelievo
|
||||
risulta `failed` e le monete di nuovo spendibili.
|
||||
- **[WDR-16]** Se l'invio ha un **esito incerto**
|
||||
([TX-20](transazioni-e-riconciliazione.md#invio-rifiutato)), prelievo e
|
||||
transazione in corso restano `building` con le monete ancora segnate come
|
||||
spese, e la risposta è HTTP **202** con `txid`, `amount_requested_sats`,
|
||||
`amount_sent_sats` e `status` = `building`; sarà il riconciliatore a
|
||||
promuoverlo o abbandonarlo.
|
||||
*Codice:* `app/withdrawals/service.py:request_withdrawal`, `app/api/routes/withdrawals.py:create_withdrawal` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-76) · *Oggi:* un esito incerto è trattato come
|
||||
un rifiuto ([WDR-11]).
|
||||
- **[WDR-12]** Se l'invio è accettato — anche con un rifiuto "già nota"
|
||||
([TX-04](transazioni-e-riconciliazione.md#invio-rifiutato)) — il prelievo
|
||||
passa a `broadcast`, la transazione in corso a `pending`, si scrive
|
||||
`withdrawal_sent` (txid, importo inviato, indirizzo esterno) e si invia una
|
||||
notifica SSE; la transazione viene poi inviata anche agli altri server
|
||||
([TX-21](transazioni-e-riconciliazione.md#invio-rifiutato)). La risposta è
|
||||
HTTP 201 con `txid`, `amount_requested_sats`, `amount_sent_sats` e
|
||||
`status`. Alla conferma il prelievo passa a `confirmed`
|
||||
([TX-07](transazioni-e-riconciliazione.md#conferma)).
|
||||
*Codice:* `app/withdrawals/service.py:request_withdrawal`, `app/withdrawals/confirmation.py:_on_withdrawal_confirmed` ·
|
||||
*Test:* `tests/unit/test_withdrawals.py`
|
||||
*Stato:* da implementare (B-76) · *Oggi:* un "già nota" è trattato come un
|
||||
rifiuto e la transazione va solo al server attivo.
|
||||
|
||||
## Scommessa e prelievo insieme
|
||||
|
||||
|
||||
Reference in new issue
Block a user