refactor(v2): rename net_sats → principal_sats for semantic clarity

`net` is financial-accounting ambiguous (net of what?). In the
bitSpire/DCA context this column is specifically the principal the
operator distributes to LPs (gross − commission), not a generic net
amount. Renaming locally before any bitSpire firmware locks the
wire-level name; lamassu-next#44 should adopt the same name.

Scope:
- migrations.py: m003 ALTER TABLE … RENAME COLUMN, idempotent probe
  pattern matching m002. Also updates the m001 canonical schema so
  fresh installs land on the new column directly.
- models.py: `CreateDcaSettlementData.principal_sats` /
  `DcaSettlement.principal_sats`. Field-doc comment updated.
- bitspire.py: both happy path and fallback path return
  `principal_sats=…`. Reads `extra.get("principal_sats")` from the
  bitSpire payload (lamassu-next#44 should follow this rename).
- crud.py: INSERT column list + `apply_partial_dispense(
  new_principal_sats=…)` keyword.
- distribution.py: every `settlement.net_sats` → `settlement.
  principal_sats`; partial-dispense memo + helper signatures updated;
  the leg-order docblock at the top reads "principal_sats".
- tasks.py: landed-settlement log line.
- static/js/index.js: settlements-table column `principal_sats` with
  label "Principal (→ LPs)".
- templates/satmachineadmin/index.html: q-td key + binding.

All 86 unit tests still pass. No backwards-compat shim — v2-bitspire
isn't released; the rename is a clean break.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Padreug 2026-05-15 23:21:32 +02:00
commit 1feaba80ed
8 changed files with 97 additions and 106 deletions

12
crud.py
View file

@ -442,13 +442,13 @@ async def create_settlement_idempotent(
"""
INSERT INTO satoshimachine.dca_settlements
(id, machine_id, payment_hash, bitspire_event_id, bitspire_txid,
gross_sats, fiat_amount, fiat_code, exchange_rate, net_sats,
gross_sats, fiat_amount, fiat_code, exchange_rate, principal_sats,
commission_sats, platform_fee_sats, operator_fee_sats,
used_fallback_split, tx_type, bills_json, cassettes_json,
status, error_message, created_at)
VALUES (:id, :machine_id, :payment_hash, :bitspire_event_id,
:bitspire_txid, :gross_sats, :fiat_amount, :fiat_code,
:exchange_rate, :net_sats, :commission_sats,
:exchange_rate, :principal_sats, :commission_sats,
:platform_fee_sats, :operator_fee_sats, :used_fallback_split,
:tx_type, :bills_json, :cassettes_json, :status,
:error_message, :created_at)
@ -463,7 +463,7 @@ async def create_settlement_idempotent(
"fiat_amount": data.fiat_amount,
"fiat_code": data.fiat_code,
"exchange_rate": data.exchange_rate,
"net_sats": data.net_sats,
"principal_sats": data.principal_sats,
"commission_sats": data.commission_sats,
"platform_fee_sats": data.platform_fee_sats,
"operator_fee_sats": data.operator_fee_sats,
@ -728,7 +728,7 @@ async def apply_partial_dispense(
settlement_id: str,
*,
new_gross_sats: int,
new_net_sats: int,
new_principal_sats: int,
new_commission_sats: int,
new_platform_fee_sats: int,
new_operator_fee_sats: int,
@ -746,7 +746,7 @@ async def apply_partial_dispense(
"""
UPDATE satoshimachine.dca_settlements
SET gross_sats = :gross,
net_sats = :net,
principal_sats = :principal,
commission_sats = :commission,
platform_fee_sats = :platform,
operator_fee_sats = :operator,
@ -763,7 +763,7 @@ async def apply_partial_dispense(
{
"id": settlement_id,
"gross": new_gross_sats,
"net": new_net_sats,
"principal": new_principal_sats,
"commission": new_commission_sats,
"platform": new_platform_fee_sats,
"operator": new_operator_fee_sats,