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

ADR-005 rollout step 2 (slice 1): capture cash-out settlements on the machine's dispense report #49

Merged
padreug merged 4 commits from feat/dispense-outcome into main 2026-10-10 19:55:10 +00:00
Conversation 0 Commits 4 Files changed 11 +1602 -32
padreug commented 2026-10-10 19:53:03 +00:00
Owner
Copy link

The spirekeeper half of bitspire ADR-005 (docs/adr/005-cash-out-dispense-outcome.md in aiolabs/bitspire), pairing with aiolabs/bitspire#123. Fixes the structural root of bitspire#122.

The change in one line: a cash_out settlement is no longer distributed when the payment lands — it lands as awaiting_dispense and waits for the machine's report_dispense. Payment is the authorization; the report is the capture.

What the report does

machine reports settlement then
dispense_confirmed pending distribution runs
some notes out, value short partial_pending held whole; operator records the resolution (ADR-005 Decision 1)
nothing out cash_owed legs never run, funds stay in the machine wallet, first on the worklist
remediates_txid the owed settlement it names → pending distributes in full
no report within the worklist threshold shown as dispense_unreported derived, not stored

Already-captured settlements are recorded, never moved. A byte-identical resend is acked without a new row. A report that arrives before its payment (hold invoices settle after the dispense; the invoice listener can lag) is stored unlinked and adopted when the settlement is inserted — same transition either way. cash_in is untouched.

Schema (m016, additive): append-only dispense_reports (lamassu-server's cash_out_actions shape); dispense_* columns + dispensed_fiat_cents on dca_settlements (and bills_json/cassettes_json finally get written — with what came out, not what was provisioned); cash_out_held_since/_reason/_code on dca_machines, mirrored from the machine's state document.

Dashboard: three owed-cash buckets render first on the worklist; partial_pending rows open the partial-dispense dialog pre-filled from the hardware's own count; machine detail shows a held-cash-out banner with a Resume button → POST /machines/{id}/resume-cash-out, a new machine-wide resume_cash_out op (position 0, no position on the wire) on the existing operator channel. The machine honours it only if stamped after the hold began.

Verified: 284/284 (20 new, project style — monkeypatched crud, no DB); ruff clean on new code; no new mypy errors; m016 smoke-executed against SQLite — every column lands. Not yet exercised end to end: that needs #123 on a machine and an lnbits restart here to run m016. Soft-fails like the other RPCs if register_rpc is missing.

Deliberately not in this PR (slice 2): the Nostr operator notification on cash_owed, the off-machine settle_cash_owed path + settle_transaction op, the cash_out_enabled switch, the error glossary, operator docs. Each carries its own design decision; the capture logic shouldn't wait on them.

After merge: sudo systemctl restart lnbits on bohm runs m016 against the dev DB. Version bump is a release step, not this PR (per the extension release procedure).

Refs aiolabs/bitspire#122, aiolabs/bitspire#123.

The spirekeeper half of bitspire ADR-005 (`docs/adr/005-cash-out-dispense-outcome.md` in aiolabs/bitspire), pairing with aiolabs/bitspire#123. Fixes the structural root of bitspire#122. **The change in one line:** a `cash_out` settlement is no longer distributed when the payment lands — it lands as `awaiting_dispense` and waits for the machine's `report_dispense`. Payment is the authorization; the report is the capture. **What the report does** | machine reports | settlement | then | |---|---|---| | `dispense_confirmed` | `pending` | distribution runs | | some notes out, value short | `partial_pending` | held whole; operator records the resolution (ADR-005 Decision 1) | | nothing out | `cash_owed` | legs never run, funds stay in the machine wallet, first on the worklist | | `remediates_txid` | the owed settlement it names → `pending` | distributes in full | | no report within the worklist threshold | shown as `dispense_unreported` | derived, not stored | Already-captured settlements are recorded, never moved. A byte-identical resend is acked without a new row. A report that arrives *before* its payment (hold invoices settle after the dispense; the invoice listener can lag) is stored unlinked and adopted when the settlement is inserted — same transition either way. `cash_in` is untouched. **Schema (m016, additive):** append-only `dispense_reports` (lamassu-server's `cash_out_actions` shape); `dispense_*` columns + `dispensed_fiat_cents` on `dca_settlements` (and `bills_json`/`cassettes_json` finally get written — with what came out, not what was provisioned); `cash_out_held_since/_reason/_code` on `dca_machines`, mirrored from the machine's state document. **Dashboard:** three owed-cash buckets render first on the worklist; `partial_pending` rows open the partial-dispense dialog pre-filled from the hardware's own count; machine detail shows a held-cash-out banner with a Resume button → `POST /machines/{id}/resume-cash-out`, a new machine-wide `resume_cash_out` op (position 0, no position on the wire) on the existing operator channel. The machine honours it only if stamped after the hold began. **Verified:** 284/284 (20 new, project style — monkeypatched crud, no DB); ruff clean on new code; no new mypy errors; m016 smoke-executed against SQLite — every column lands. Not yet exercised end to end: that needs #123 on a machine and an lnbits restart here to run m016. Soft-fails like the other RPCs if `register_rpc` is missing. **Deliberately not in this PR (slice 2):** the Nostr operator notification on `cash_owed`, the off-machine `settle_cash_owed` path + `settle_transaction` op, the `cash_out_enabled` switch, the error glossary, operator docs. Each carries its own design decision; the capture logic shouldn't wait on them. **After merge:** `sudo systemctl restart lnbits` on bohm runs m016 against the dev DB. Version bump is a release step, not this PR (per the extension release procedure). Refs aiolabs/bitspire#122, aiolabs/bitspire#123. 
m016: an append-only `dispense_reports` table (lamassu-server's
cash_out_actions shape — one row per report the machine sent, so a
retry, a late report and a remediation report stay distinct);
dispense_confirmed / dispense_error / dispense_error_code /
dispense_raw_code / dispense_error_class / dispense_reported_at /
dispensed_fiat_cents on dca_settlements; cash_out_held_since / _reason /
_code on dca_machines beside counts_uncertain_since.

Settlement lifecycle gains awaiting_dispense (cash_out at insert — paid,
waiting for the machine's report), partial_pending (some notes out,
value short; held whole until the operator records the resolution) and
cash_owed (nothing out; legs never run). dispense_unreported is derived
by the worklist, not stored.

resume_cash_out joins CASSETTE_OP_TYPES as a machine-wide op: position 0,
no position on the wire, no bay fields. It rides the operator channel the
machine already consumes; the machine honours it only if stamped after
the hold began. A recount releases the hold too.

crud: get_settlement_by_txid (the join the machine's extra.txid already
provides), apply_dispense_outcome (copies the report onto the settlement
and finally writes bills_json / cassettes_json with what actually came
out), the dispense_reports accessors incl. adopting a report that
arrived before its payment, set_machine_cash_out_hold, and the three
new worklist buckets.
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.
Three buckets render first on the worklist — cash_owed, partial_pending,
dispense_unreported (awaiting_dispense older than the threshold) — the
only ones whose meaning is "a customer is owed money". partial_pending
rows open the partial-dispense dialog pre-filled from the machine's
report: the fraction from dispensed_fiat_cents / fiat_amount and the
dispenser's error in the note, so the operator confirms a number the
hardware produced rather than typing one.

Machine detail shows a held-cash-out banner (code, time, reason) with a
Resume button; POST /machines/{id}/resume-cash-out records a
resume_cash_out op and publishes the window. The machine clears the hold
on receipt and the banner clears on its next state report.
test: dispense outcome capture — handler transitions, payment gate, resume op, hold mirror
Some checks failed
ci.yml / test: dispense outcome capture — handler transitions, payment gate, resume op, hold mirror (pull_request) Failing after 0s
Details
79413dc06d 
Twenty tests in the project's style (asyncio.run, monkeypatched crud, no
DB): confirmed → pending + distribution; nothing out → cash_owed; some
out → partial_pending with nothing spawned; already-captured recorded
not moved; identical resend acked without a row; report-before-payment
stored unlinked and adopted when the payment lands; remediation moves
the owed settlement; a remediation that did not confirm leaves it;
unpaired sender / malformed body refused. The payment gate: cash_out →
awaiting_dispense with no distribution, cash_in unchanged. The
resume_cash_out op's position rule and wire shape, the worklist model's
new buckets, and the state-document hold mirror set-and-clear. The
existing nulls-never-reach-the-wire test learns the machine-wide op.
padreug deleted branch feat/dispense-outcome 2026-10-10 19:55:10 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
aiolabs/spirekeeper!49
No description provided.