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

docs(adr-005): record the NIP-17 alert and the settle-cash-owed path as built

Browse source
This commit is contained in:
Padreug 2026-10-10 22:27:39 +02:00
commit 5a4f70c90e
1 changed files with 14 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

22
docs/adr/005-cash-out-dispense-outcome.md
View file

@ -246,9 +246,13 @@ rather than pausing it.
Server: `cash_owed` and `dispense_unreported` are two new buckets on
`StuckSettlementsResponse`. They are the only buckets whose meaning is *a customer is owed
money*, and they render first. Arrival in either bucket triggers the operator notification
path (whatever `notifyOperator` equivalent spirekeeper grows; at minimum the dashboard banner
— but the push is the point, and it belongs in the same transaction that writes the row).
money*, and they render first. Arrival in `cash_owed` or `partial_pending` sends the operator
a **NIP-17 gift-wrapped DM** (kind 14 → 13 → 1059) to their own LNbits-account pubkey, or to
`super_config.alerts_pubkey` when set — a note to self any NIP-46 client renders. It is signed
through the operator's signer (no key at rest), is best-effort (a failed publish is logged and
the report is still acked — the worklist is the durable record), and sets
`operator_notified_at` so a report resend never re-alerts. Not email, not NIP-04.
*(Implemented: spirekeeper `notify.py`, slice 2.)*
Resolution closes **both** ledgers:
@ -256,11 +260,13 @@ Resolution closes **both** ledgers:
to `remediated` via `remediateTransaction`. The machine sends a `report_dispense` for the
remediation with `remediates_txid`, and the server moves the settlement from `cash_owed` to
`pending` and distributes.
- **Off-machine settlement.** The operator paid the customer by hand. A new `settle_cash_owed`
operator action records provenance (free text, author, time) on the settlement, moves it to
`pending`, and publishes a `settle_transaction { txid, note }` operator op; the machine
applies it by setting `remediated_by` to the note and `status = 'remediated'`. Today there is
no way to record this at all, and the machine's ledger asserts the debt forever.
- **Off-machine settlement.** The operator paid the customer by hand.
`POST /settlements/{id}/settle-cash-owed` records provenance (free text, author, time) on the
settlement, moves it to `pending` and distributes **at the full amount** (the customer is
whole), and publishes a machine-wide `settle_transaction { id, at, txid, note }` operator op;
the machine applies it through `remediateTransaction(txid, "settled-off-machine:<op id>:<note>")`,
which only touches rows still in an error state, so re-delivery is harmless. Before slice 2
there was no way to record this at all, and the machine's ledger asserted the debt forever.
`PartialDispenseData` is pre-filled from the report's `bills` so the operator confirms a
number the hardware produced rather than typing one.