aiolabs/spirekeeper
9
0
Fork 0
Code Issues 29 Pull requests Projects Releases Packages Wiki Activity Actions 2

feat(transport): report_dispense RPC — capture a cash-out on the machine's report, not on payment (ADR-005 §1–§2)

Browse source 
The structural fix for bitspire#122. _handle_payment used to spawn
process_settlement the instant a cash_out payment landed — before the
machine had begun to dispense — so a jam two seconds later found the
legs already paid and `processed` was the honest answer. Payment is now
the authorization; the machine's report is the capture.

A cash_out lands as awaiting_dispense and is not distributed. The new
`report_dispense` handler (identity from the VERIFIED transport sender,
same as create_withdraw / get_machine_config) stores every report
append-only and moves the settlement: dispense_confirmed → pending and
distribution runs; some notes out → partial_pending, held whole
(ADR-005 Decision 1, one distribution when the shortfall is resolved);
nothing out → cash_owed, first on the worklist. A report naming
remediates_txid moves the owed settlement it names to pending in full.
Already-captured settlements are recorded but never moved — a report
cannot un-pay legs. A byte-identical resend is acked without a new row.

Both orders of arrival are handled: a report that precedes its payment
(hold invoices settle after the dispense; the invoice listener can lag)
is stored unlinked and adopted when the settlement is inserted, through
the same transition. counts_uncertain on a report mirrors onto the
machine immediately rather than at the next heartbeat. The state-event
consumer mirrors cash_out_held_* onto dca_machines, including clearing it.

Soft-fails like the other RPCs: without register_rpc the settlements sit
in awaiting_dispense and surface as dispense_unreported — the honest state.
This commit is contained in:
Padreug 2026-10-10 21:51:51 +02:00
commit 44c2afa5bb
3 changed files with 368 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

6
__init__.py
View file

@ -6,6 +6,7 @@ from loguru import logger
from .cashin_transport import register_create_withdraw_rpc
from .crud import db
from .dispense_transport import register_dispense_report_rpc
from .machine_config_transport import register_machine_config_rpc
from .nostr_transport_roster import register_with_lnbits as register_roster_with_lnbits
from .tasks import wait_for_cassette_state_events, wait_for_paid_invoices
@ -68,6 +69,11 @@ def spirekeeper_start():
# config over the transport, leaving "awaiting configuration" with no
# per-machine env provisioning. Soft-fails if register_rpc isn't exposed.
register_machine_config_rpc()
# Dispense outcome capture (bitspire ADR-005 §2 / #122): register the
# report_dispense RPC. A cash-out settlement now waits in awaiting_dispense
# until the machine reports; the success report is what distributes it,
# a failure report puts the customer on the owed-cash worklist.
register_dispense_report_rpc()
__all__ = [