diff --git a/bitspire.py b/bitspire.py index e40c230..cbf6c67 100644 --- a/bitspire.py +++ b/bitspire.py @@ -17,7 +17,8 @@ from __future__ import annotations import json from typing import Any, Optional -from .models import CreateDcaSettlementData, Machine +from .calculations import split_principal_based +from .models import CreateDcaSettlementData, Machine, SuperConfig # Sentinel value bitSpire sets in Payment.extra.source so we know an inbound # payment originated from an ATM cash-out and not some other extension or @@ -219,23 +220,30 @@ def parse_settlement( payment_hash: str, wire_sats: int, extra: dict, - super_fee_fraction: float, + super_config: SuperConfig, ) -> CreateDcaSettlementData: """Build a CreateDcaSettlementData for an inbound payment landing on `machine`'s wallet. + Splits the fee on a principal-based, direction-aware model + (aiolabs/satmachineadmin#37,#38): + + platform_fee_sats = round(principal_sats * super_cash_{type}_fee_fraction) + operator_fee_sats = round(principal_sats * operator_cash_{type}_fee_fraction) + + where the directional super fraction comes from `super_config` and + the operator fraction comes from `machine`. The bitspire-reported + `fee_sats` field is preserved on the settlement as the customer's + actual paid total, but is NOT used as input to the split. + Requires bitSpire's canonical Payment.extra stamp (source="bitspire" plus the absolute sat amounts) per aiolabs/lamassu-next#44. Raises `SettlementMetadataError` on missing/partial stamp — caller records the settlement as 'rejected' for upstream investigation. Raises `SettlementInvariantError` if the stamped values violate the canonical sat-amount invariants (range + sum, see - `_assert_sat_invariants`). + `_assert_sat_invariants`) or `tx_type` is unknown. """ - if not (0.0 <= super_fee_fraction <= 1.0): - raise SettlementInvariantError( - f"super_fee_fraction must be in [0, 1], got {super_fee_fraction}" - ) if not is_bitspire_payment(extra): raise SettlementMetadataError( f"Payment.extra missing `source: \"bitspire\"` marker on machine " @@ -253,8 +261,20 @@ def parse_settlement( f"(lamassu-next#44) requires both. Investigate the ATM " f"firmware on machine {machine.machine_npub[:12]}..." ) - platform_fee_sats = round(fee_sats * super_fee_fraction) - operator_fee_sats = fee_sats - platform_fee_sats + tx_type = _coerce_str(extra.get("type")) or "cash_out" + if tx_type == "cash_in": + super_frac = float(super_config.super_cash_in_fee_fraction) + operator_frac = float(machine.operator_cash_in_fee_fraction) + elif tx_type == "cash_out": + super_frac = float(super_config.super_cash_out_fee_fraction) + operator_frac = float(machine.operator_cash_out_fee_fraction) + else: + raise SettlementInvariantError( + f"unknown tx_type={tx_type!r}; expected 'cash_in' or 'cash_out'" + ) + platform_fee_sats, operator_fee_sats = split_principal_based( + principal_sats, super_frac, operator_frac + ) exchange_rate = _coerce_float(extra.get("exchange_rate")) if exchange_rate is None or exchange_rate <= 0: # Without exchange rate we can't compute fiat. Use 1.0 as a stand-in @@ -268,7 +288,6 @@ def parse_settlement( # in BTC today, but the cash side has its own ground truth). fiat_amount = _coerce_float(extra.get("fiat_amount")) or 0.0 fiat_code = _coerce_str(extra.get("currency")) or machine.fiat_code - tx_type = _coerce_str(extra.get("type")) or "cash_out" data = CreateDcaSettlementData( machine_id=machine.id, payment_hash=payment_hash, diff --git a/calculations.py b/calculations.py index 5bfadab..c76600b 100644 --- a/calculations.py +++ b/calculations.py @@ -106,36 +106,49 @@ def calculate_distribution( return distributions -def split_two_stage_commission( - fee_sats: int, super_fee_fraction: float +def split_principal_based( + principal_sats: int, + super_frac: float, + operator_frac: float, ) -> Tuple[int, int]: - """Stage-1 of the v2 commission split: super takes `super_fee_fraction` - of the total fee; the remainder is what the operator's own ruleset - acts on. + """Compute platform + operator fee shares as independent fractions of + `principal_sats`. Both shares are derived from the customer's + principal (the canonical source of truth), NOT back-derived from + `fee_sats`. - Returns (platform_fee_sats, operator_fee_sats). Platform is rounded; - operator absorbs the rounding remainder so platform_fee + operator_fee - == fee_sats exactly. + Returns (platform_fee_sats, operator_fee_sats). Both are rounded + independently; rounding remainders do NOT compound — the customer + pays whatever bitspire collected, and any drift between (super + + operator) and the bitspire-reported `fee_sats` surfaces via + `dca_settlements.fee_mismatch_sats`. Examples: - >>> split_two_stage_commission(100, 0.30) - (30, 70) - >>> split_two_stage_commission(7965, 0.30) - (2390, 5575) - >>> split_two_stage_commission(100, 0.0) - (0, 100) - >>> split_two_stage_commission(100, 1.0) - (100, 0) + >>> split_principal_based(100_000, 0.03, 0.05) + (3000, 5000) + >>> split_principal_based(266_800, 0.03, 0.0) + (8004, 0) + >>> split_principal_based(100_000, 0.0, 0.0) + (0, 0) + >>> split_principal_based(100_000, 0.15, 0.0) + (15000, 0) + + The pre-#38 bug this corrects: the old math interpreted the super + fee as `fraction_of_fee` rather than `fraction_of_principal`. On a + 100_000-sat principal with an 8% total bitspire fee (= 8_000 sats + fee_sats) and super_fraction=0.03, the bug paid the super + `round(8_000 * 0.03) = 240` sats — ~13× below the intended + `100_000 * 0.03 = 3_000` sats per-settlement. Repeated on every + cash-out since the bitspire wire-shape landed. See + aiolabs/satmachineadmin#37 (parent) + #38 (this layer). """ - if not (0.0 <= super_fee_fraction <= 1.0): - raise ValueError( - f"super_fee_fraction must be in [0, 1], got {super_fee_fraction}" - ) - if fee_sats <= 0: + if not (0.0 <= super_frac <= 1.0): + raise ValueError(f"super_frac must be in [0, 1], got {super_frac}") + if not (0.0 <= operator_frac <= 1.0): + raise ValueError(f"operator_frac must be in [0, 1], got {operator_frac}") + if principal_sats <= 0: return 0, 0 - platform = round(fee_sats * super_fee_fraction) - platform = max(0, min(platform, fee_sats)) - operator = fee_sats - platform + platform = max(0, round(principal_sats * super_frac)) + operator = max(0, round(principal_sats * operator_frac)) return platform, operator diff --git a/migrations.py b/migrations.py index 5e0b3ec..97e4a68 100644 --- a/migrations.py +++ b/migrations.py @@ -682,9 +682,11 @@ async def m009_split_fee_fractions_by_direction(db): lnbits advisory; option A locked). Idempotency via column-probe pattern (same shape as m006's rename - sweep). The existing `super_config.super_fee_fraction` column is - NOT dropped here — deprecated, removed in a follow-up release after - callers migrate to the directional fields. + sweep). The deprecated `super_config.super_fee_fraction` singleton + is backfilled into the new directional fields, then dropped in the + same migration — strict-from-the-start per workspace CLAUDE.md + "Backwards-compatibility on pre-public-launch code" (v2-bitspire + hasn't shipped to public users). """ additions = [ ("super_config", "super_cash_in_fee_fraction", "DECIMAL(10,4) NOT NULL DEFAULT 0.0000"), @@ -704,17 +706,32 @@ async def m009_split_fee_fractions_by_direction(db): f"ALTER TABLE satoshimachine.{table} ADD COLUMN {col} {coltype}" ) - # Backfill super-config directional fractions from the legacy singleton - # so the live deployment's super_fee_fraction setting carries forward. - # Guarded WHERE clause: only fire when both new fields are still at - # their DEFAULT 0 (i.e., this is a first migrate-up, not a repeat). - await db.execute( - """ - UPDATE satoshimachine.super_config - SET super_cash_in_fee_fraction = super_fee_fraction, - super_cash_out_fee_fraction = super_fee_fraction - WHERE super_cash_in_fee_fraction = 0 - AND super_cash_out_fee_fraction = 0 - AND super_fee_fraction > 0 - """ - ) + # Backfill + drop the legacy singleton, gated on the column still + # existing. Once dropped, a re-run of this migration skips both + # steps cleanly. + try: + await db.fetchone( + "SELECT super_fee_fraction FROM satoshimachine.super_config LIMIT 1" + ) + legacy_present = True + except Exception: + legacy_present = False + + if legacy_present: + # Carry the live deployment's super_fee_fraction setting forward + # into both directional fields, but only when the operator hasn't + # already explicitly set per-direction values (i.e., both are + # still at DEFAULT 0). + await db.execute( + """ + UPDATE satoshimachine.super_config + SET super_cash_in_fee_fraction = super_fee_fraction, + super_cash_out_fee_fraction = super_fee_fraction + WHERE super_cash_in_fee_fraction = 0 + AND super_cash_out_fee_fraction = 0 + AND super_fee_fraction > 0 + """ + ) + await db.execute( + "ALTER TABLE satoshimachine.super_config DROP COLUMN super_fee_fraction" + ) diff --git a/models.py b/models.py index 1ec2ec4..1094f6a 100644 --- a/models.py +++ b/models.py @@ -449,10 +449,6 @@ class TelemetrySnapshot(BaseModel): class SuperConfig(BaseModel): id: str - # Deprecated singleton fee fraction — retained for one release while - # callers migrate to the per-direction fields below. The new math - # (bitspire.py:parse_settlement) only reads the directional fields. - super_fee_fraction: float super_cash_in_fee_fraction: float = 0.0 super_cash_out_fee_fraction: float = 0.0 super_fee_wallet_id: str | None @@ -460,15 +456,11 @@ class SuperConfig(BaseModel): class UpdateSuperConfigData(BaseModel): - # Deprecated; setting either directional field is the supported path. - # Writes here continue to apply for one release for migration safety. - super_fee_fraction: float | None = None super_cash_in_fee_fraction: float | None = None super_cash_out_fee_fraction: float | None = None super_fee_wallet_id: str | None = None @validator( - "super_fee_fraction", "super_cash_in_fee_fraction", "super_cash_out_fee_fraction", ) diff --git a/tasks.py b/tasks.py index 7f2a276..9778a20 100644 --- a/tasks.py +++ b/tasks.py @@ -125,14 +125,14 @@ async def _handle_payment(payment: Payment) -> None: # stamp is missing, SettlementInvariantError on any range/sum # breach. super_config = await get_super_config() - super_fee_fraction = float(super_config.super_fee_fraction) if super_config else 0.0 + assert super_config is not None # m001 inserts the default singleton try: data = parse_settlement( machine=machine, payment_hash=payment.payment_hash, wire_sats=payment.sat, extra=extra, - super_fee_fraction=super_fee_fraction, + super_config=super_config, ) except (SettlementMetadataError, SettlementInvariantError) as exc: await _record_rejected(payment, machine, exc) diff --git a/tests/test_operator_split_legs.py b/tests/test_operator_split_legs.py new file mode 100644 index 0000000..1e0bbca --- /dev/null +++ b/tests/test_operator_split_legs.py @@ -0,0 +1,150 @@ +""" +Tests for `allocate_operator_split_legs` (operator's commission-leg +distribution) and the partial-dispense ratio math in +`apply_partial_dispense_and_redistribute`. + +Both are split-arithmetic concerns that survive the post-#38 +principal-based-math refactor: + + - `allocate_operator_split_legs` slices the operator's share across + their commission legs by their per-leg fractions. Function-level, + no fee-model coupling. + - Partial-dispense ratio math (in distribution.py) preserves the + ORIGINAL platform/operator ratio recorded against a settlement at + land time when an operator partial-dispenses post-hoc. The ratio + comes from the absolute platform_fee_sats / fee_sats recorded on + the settlement row, NOT the current super-config fractions — the + contract is locked at landing. + +Pre-#38 tests for `split_two_stage_commission` lived here; that +function was removed when the principal-based math landed +(aiolabs/satmachineadmin#38). +""" + +import pytest + +from ..calculations import allocate_operator_split_legs + + +class TestAllocateOperatorSplitLegs: + """Operator's remaining share split into commission legs by fraction.""" + + def test_plan_example_50_30_20_on_70(self): + amounts = allocate_operator_split_legs(70, [0.5, 0.3, 0.2]) + assert amounts == [35, 21, 14] + + def test_realistic_50_30_20_on_5575(self): + amounts = allocate_operator_split_legs(5575, [0.5, 0.3, 0.2]) + # Plan-scale: 5575 * (0.5, 0.3, 0.2) = (2787.5, 1672.5, 1115) + # Last leg absorbs rounding remainders so sum == 5575 exactly. + assert sum(amounts) == 5575 + assert amounts[0] == round(5575 * 0.5) + assert amounts[1] == round(5575 * 0.3) + # Last leg absorbs the remainder. + assert amounts[2] == 5575 - amounts[0] - amounts[1] + + def test_single_leg_full_remainder(self): + amounts = allocate_operator_split_legs(7965, [1.0]) + assert amounts == [7965] + + def test_zero_operator_fee_zeros_all_legs(self): + amounts = allocate_operator_split_legs(0, [0.5, 0.3, 0.2]) + assert amounts == [0, 0, 0] + + def test_empty_legs_list_returns_empty(self): + amounts = allocate_operator_split_legs(100, []) + assert amounts == [] + + def test_last_leg_absorbs_rounding_remainder(self): + # 100 sats split [1/3, 1/3, 1/3] — last leg absorbs the +1 remainder. + amounts = allocate_operator_split_legs(100, [1 / 3, 1 / 3, 1 / 3]) + assert sum(amounts) == 100 + assert amounts[0] == round(100 / 3) # 33 + assert amounts[1] == round(100 / 3) # 33 + # Last leg absorbs the rounding (34, not 33) so total == 100. + assert amounts[2] == 100 - amounts[0] - amounts[1] + + @pytest.mark.parametrize( + "operator_fee,fractions", + [ + (1, [0.5, 0.5]), + (7, [0.5, 0.3, 0.2]), + (100, [0.5, 0.5]), + (5575, [0.5, 0.3, 0.2]), + (1_000_000, [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]), + ], + ) + def test_invariant_sum_equals_operator_fee(self, operator_fee, fractions): + amounts = allocate_operator_split_legs(operator_fee, fractions) + assert sum(amounts) == operator_fee + assert all(a >= 0 for a in amounts) + + +class TestPartialDispenseSplitRatio: + """Partial-dispense recompute (closes #11 H6) must preserve the + ORIGINAL platform/operator ratio recorded on the settlement row at + land time. Super raising or lowering a global rate post-hoc must + NOT retroactively change an existing settlement's share split. + + The math is inlined in `apply_partial_dispense_and_redistribute` + (distribution.py) rather than in a standalone function. These tests + mirror the inline math so a future refactor doesn't silently change + the invariant. + """ + + def _recompute(self, original_fee, original_platform_fee, new_fee): + """Mirror of the ratio math in apply_partial_dispense_and_redistribute.""" + if original_fee > 0: + ratio = original_platform_fee / original_fee + else: + ratio = 0.0 + new_platform = round(new_fee * ratio) + new_platform = max(0, min(new_platform, new_fee)) + new_operator = new_fee - new_platform + return new_platform, new_operator + + def test_30pct_lands_then_partial(self): + # Landed at platform ratio 30/100 = 0.30; new fee = 50. + # Original ratio preserved → new_platform = round(50 * 0.30) = 15. + new_platform, new_operator = self._recompute(100, 30, 50) + assert new_platform == 15 + assert new_operator == 35 + assert new_platform + new_operator == 50 + + def test_super_changed_rate_doesnt_affect_existing_settlement(self): + # Landed with platform=2390, fee=7965 (ratio ≈ 0.30). Super then + # bumps the global rate to 50%. Operator partial-dispenses to + # 50% gross → new_fee = round(7965 * 0.5) = 3982. The 30% ratio + # at land time MUST persist regardless of the new super rate. + new_platform, new_operator = self._recompute(7965, 2390, 3982) + # Expected with original ratio: round(3982 * 0.30006...) = 1195 + # With (broken) current rate of 50%: would be 1991 — much higher. + assert 1190 <= new_platform <= 1200 + assert new_platform + new_operator == 3982 + # Original platform share was ~30%; preserved within rounding. + assert abs(new_platform / 3982 - 2390 / 7965) < 0.001 + + def test_zero_original_fee_yields_zero_platform(self): + new_platform, new_operator = self._recompute(0, 0, 0) + assert new_platform == 0 + assert new_operator == 0 + + def test_invariant_sum_equals_new_fee(self): + # Random-ish parameter sweep over realistic values. + cases = [ + (100, 30, 50), + (100, 0, 50), # original platform_fee was 0 + (100, 100, 50), # original platform_fee was full fee + (7965, 2390, 3982), + (7965, 7965, 3982), + (1_000_000, 333_333, 250_000), + ] + for orig_comm, orig_plat, new_comm in cases: + new_platform, new_operator = self._recompute( + orig_comm, orig_plat, new_comm + ) + assert new_platform + new_operator == new_comm, ( + f"sum invariant violated: {orig_comm=} {orig_plat=} " + f"{new_comm=} → {new_platform=} {new_operator=}" + ) + assert 0 <= new_platform <= new_comm diff --git a/tests/test_principal_based_fees.py b/tests/test_principal_based_fees.py new file mode 100644 index 0000000..ebdd040 --- /dev/null +++ b/tests/test_principal_based_fees.py @@ -0,0 +1,270 @@ +""" +Tests for the post-#38 principal-based fee split: + + - `calculations.split_principal_based(principal_sats, super_frac, + operator_frac)` — pure-function math + - `bitspire.parse_settlement` — directional dispatch by tx_type + ("cash_in" → super_cash_in + operator_cash_in; + "cash_out" → super_cash_out + operator_cash_out) + +The bug this layer closes: pre-#38 math interpreted super_fee_fraction +as fraction-of-fee instead of fraction-of-principal, under-paying the +super by ~13× per cashout. Tests below pin the new math to the +intended fraction-of-principal model and verify the per-direction +routing through parse_settlement. + +Fee mismatch recording (`fee_mismatch_sats` column, Phase 1 +observability per coord-log §2026-06-01T07:00Z) lands in the next +commit; those tests live in `test_fee_mismatch_recording.py`. +""" + +from datetime import datetime + +import pytest + +from ..bitspire import SettlementInvariantError, parse_settlement +from ..calculations import split_principal_based +from ..models import Machine, SuperConfig + + +# --------------------------------------------------------------------------- +# split_principal_based — pure-function math +# --------------------------------------------------------------------------- + + +class TestSplitPrincipalBased: + def test_super_fraction_only(self): + """Operator at 0% — super takes exactly super_frac of principal, + operator gets 0.""" + platform, operator = split_principal_based(100_000, 0.03, 0.0) + assert platform == 3_000 + assert operator == 0 + + def test_operator_fraction_only(self): + """Super at 0% — operator takes exactly operator_frac of + principal, platform gets 0.""" + platform, operator = split_principal_based(100_000, 0.0, 0.05) + assert platform == 0 + assert operator == 5_000 + + def test_both_fractions(self): + """Both shares independently computed against principal — total + is super + operator, not anchored to any fee_sats input.""" + platform, operator = split_principal_based(100_000, 0.03, 0.05) + assert platform == 3_000 + assert operator == 5_000 + + def test_zero_principal_yields_zero_shares(self): + platform, operator = split_principal_based(0, 0.03, 0.05) + assert platform == 0 + assert operator == 0 + + def test_negative_principal_yields_zero_shares(self): + """Defensive: negative principal can't happen in production but + the function should not produce negative outputs if it ever does.""" + platform, operator = split_principal_based(-100, 0.03, 0.05) + assert platform == 0 + assert operator == 0 + + def test_rounding_does_not_compound(self): + """The two shares round independently — there is no carryover. + On a 1_000_000-sat principal with super=0.0333, operator=0.0777, + each share rounds against principal individually.""" + platform, operator = split_principal_based(1_000_000, 0.0333, 0.0777) + assert platform == round(1_000_000 * 0.0333) # 33_300 + assert operator == round(1_000_000 * 0.0777) # 77_700 + + def test_super_frac_out_of_range_raises(self): + with pytest.raises(ValueError, match="super_frac"): + split_principal_based(100_000, 1.5, 0.0) + with pytest.raises(ValueError, match="super_frac"): + split_principal_based(100_000, -0.1, 0.0) + + def test_operator_frac_out_of_range_raises(self): + with pytest.raises(ValueError, match="operator_frac"): + split_principal_based(100_000, 0.0, 1.5) + with pytest.raises(ValueError, match="operator_frac"): + split_principal_based(100_000, 0.0, -0.1) + + def test_super_under_payment_bug_regression(self): + """Direct regression test for the bug this layer closes. + + Pre-#38 math (deleted): `round(fee_sats * super_fraction)` with + fee_sats=8_000 (= 8% of 100_000 principal) and super_fraction=0.03 + produced platform_fee_sats=240 — ~13× below intent. + + Post-#38 math: split_principal_based(100_000, 0.03, 0.05) gives + platform=3_000, which IS the intended 3% of principal.""" + platform, operator = split_principal_based(100_000, 0.03, 0.05) + # Post-#38: super gets intended 3% of principal (3_000 sats) + # Pre-#38 would have produced ~240 sats from round(8000 * 0.03). + assert platform == 3_000 + + +# --------------------------------------------------------------------------- +# parse_settlement — directional dispatch via tx_type +# --------------------------------------------------------------------------- + + +def _bitspire_extra( + *, + tx_type: str = "cash_out", + principal_sats: int = 100_000, + fee_sats: int = 8_000, + exchange_rate: float = 0.00001, + fiat_amount: float = 100.0, + currency: str = "EUR", + nostr_sender_pubkey: str = "a" * 64, + extra_overrides: dict | None = None, +): + """Canonical bitspire-stamped Payment.extra dict for tests. Mirrors + the shape required by `is_bitspire_payment` + the canonical sat- + amount invariants in `_assert_sat_invariants`.""" + base = { + "source": "bitspire", + "type": tx_type, + "principal_sats": principal_sats, + "fee_sats": fee_sats, + "fee_fraction": fee_sats / principal_sats if principal_sats else 0.0, + "exchange_rate": exchange_rate, + "fiat_amount": fiat_amount, + "currency": currency, + "txid": "fake-txid", + "nostr_sender_pubkey": nostr_sender_pubkey, + } + if extra_overrides: + base.update(extra_overrides) + return base + + +_NOW = datetime(2026, 6, 1, 12, 0, 0) + + +def _machine( + machine_id: str = "m1", + machine_npub: str = "a" * 64, + op_in: float = 0.0, + op_out: float = 0.0, + fiat_code: str = "EUR", +) -> Machine: + return Machine( + id=machine_id, + operator_user_id="op1", + machine_npub=machine_npub, + wallet_id="w1", + name="Test", + location=None, + fiat_code=fiat_code, + is_active=True, + operator_cash_in_fee_fraction=op_in, + operator_cash_out_fee_fraction=op_out, + created_at=_NOW, + updated_at=_NOW, + ) + + +def _super_config(in_frac: float = 0.0, out_frac: float = 0.0) -> SuperConfig: + return SuperConfig( + id="default", + super_cash_in_fee_fraction=in_frac, + super_cash_out_fee_fraction=out_frac, + super_fee_wallet_id="super-wallet", + updated_at=_NOW, + ) + + +class TestParseSettlementDirectional: + def test_cash_out_uses_cash_out_fractions(self): + """tx_type='cash_out' must route to super_cash_out + + operator_cash_out fractions.""" + machine = _machine(op_in=0.10, op_out=0.05) + super_cfg = _super_config(in_frac=0.10, out_frac=0.03) + extra = _bitspire_extra(tx_type="cash_out", principal_sats=100_000) + + data = parse_settlement( + machine=machine, + payment_hash="ph1", + wire_sats=108_000, + extra=extra, + super_config=super_cfg, + ) + # super_cash_out=0.03, operator_cash_out=0.05 against 100_000 principal + assert data.platform_fee_sats == 3_000 + assert data.operator_fee_sats == 5_000 + assert data.tx_type == "cash_out" + + def test_cash_in_uses_cash_in_fractions(self): + """tx_type='cash_in' must route to super_cash_in + + operator_cash_in fractions (not cash_out).""" + machine = _machine(op_in=0.04, op_out=0.10) + super_cfg = _super_config(in_frac=0.02, out_frac=0.10) + extra = _bitspire_extra(tx_type="cash_in", principal_sats=100_000) + + # cash-in wire invariant: wire = principal - fee + data = parse_settlement( + machine=machine, + payment_hash="ph2", + wire_sats=92_000, + extra=extra, + super_config=super_cfg, + ) + # super_cash_in=0.02, operator_cash_in=0.04 against 100_000 principal + assert data.platform_fee_sats == 2_000 + assert data.operator_fee_sats == 4_000 + assert data.tx_type == "cash_in" + + def test_unknown_tx_type_raises(self): + machine = _machine() + super_cfg = _super_config() + extra = _bitspire_extra( + tx_type="cash_out", + extra_overrides={"type": "withdrawal"}, # not a known direction + ) + with pytest.raises(SettlementInvariantError, match="unknown tx_type"): + parse_settlement( + machine=machine, + payment_hash="ph3", + wire_sats=108_000, + extra=extra, + super_config=super_cfg, + ) + + def test_zero_fractions_zero_split(self): + """Free-charge ATM: both super + operator at 0 → platform and + operator fees are both 0, principal is the full take.""" + machine = _machine(op_in=0.0, op_out=0.0) + super_cfg = _super_config(in_frac=0.0, out_frac=0.0) + extra = _bitspire_extra( + tx_type="cash_out", principal_sats=100_000, fee_sats=0 + ) + + data = parse_settlement( + machine=machine, + payment_hash="ph4", + wire_sats=100_000, + extra=extra, + super_config=super_cfg, + ) + assert data.platform_fee_sats == 0 + assert data.operator_fee_sats == 0 + assert data.principal_sats == 100_000 + + def test_cash_in_does_not_use_cash_out_config(self): + """Cross-direction guard: cash-in must NOT pick up cash-out's + super or operator fractions even when they're set differently. + Pin both directions concretely to prove the dispatch.""" + machine = _machine(op_in=0.01, op_out=0.10) + super_cfg = _super_config(in_frac=0.01, out_frac=0.10) + extra = _bitspire_extra(tx_type="cash_in", principal_sats=100_000) + + # cash-in wire invariant: wire = principal - fee + data = parse_settlement( + machine=machine, + payment_hash="ph5", + wire_sats=92_000, + extra=extra, + super_config=super_cfg, + ) + # Cash-in totals = 0.01 + 0.01 = 0.02; not 0.10 + 0.10 = 0.20 + assert data.platform_fee_sats == 1_000 # 100_000 * 0.01 + assert data.operator_fee_sats == 1_000 # 100_000 * 0.01 diff --git a/tests/test_two_stage_split.py b/tests/test_two_stage_split.py deleted file mode 100644 index d48cb07..0000000 --- a/tests/test_two_stage_split.py +++ /dev/null @@ -1,214 +0,0 @@ -""" -Tests for the v2 two-stage commission split (super first, operator remainder). - -The plan calls out a verification scenario explicitly: - super_fee_fraction=0.30 (i.e. 30%), operator splits [0.5, 0.3, 0.2] on a - 100-sat fee → super_wallet gets 30, operator legs get 35 / 21 / 14. - -Also covers the edge cases: super_fee_fraction=0.0 (no super takes the -whole fee), super_fee_fraction=1.0 (super takes everything), single-leg -operator ruleset, zero operator fee. -""" - -import pytest - -from ..calculations import ( - allocate_operator_split_legs, - split_two_stage_commission, -) - - -class TestSplitTwoStageCommission: - """Stage-1: super takes super_fee_fraction of the fee; operator gets rest.""" - - def test_plan_example_100sats_30pct(self): - platform, operator = split_two_stage_commission(100, 0.30) - assert platform == 30 - assert operator == 70 - assert platform + operator == 100 - - def test_realistic_7965sats_30pct(self): - # From the plan's 2000 GTQ → 266800 sats @ 3% commission example. - platform, operator = split_two_stage_commission(7965, 0.30) - assert platform == 2390 # round(7965 * 0.30) = 2389.5 → 2390 - assert operator == 5575 # 7965 - 2390 - assert platform + operator == 7965 - - def test_super_fraction_zero_leaves_all_to_operator(self): - platform, operator = split_two_stage_commission(7965, 0.0) - assert platform == 0 - assert operator == 7965 - - def test_super_fraction_one_takes_everything(self): - platform, operator = split_two_stage_commission(7965, 1.0) - assert platform == 7965 - assert operator == 0 - - def test_zero_commission(self): - platform, operator = split_two_stage_commission(0, 0.30) - assert platform == 0 - assert operator == 0 - - def test_negative_commission_clamps_to_zero(self): - # Defensive: should never happen, but verify we don't go negative. - platform, operator = split_two_stage_commission(-100, 0.30) - assert platform == 0 - assert operator == 0 - - @pytest.mark.parametrize("fee_sats", [1, 7, 100, 7965, 1_000_000]) - @pytest.mark.parametrize("super_fraction", [0.0, 0.1, 0.30, 0.5, 0.777, 1.0]) - def test_invariant_sum_equals_commission(self, fee_sats, super_fraction): - platform, operator = split_two_stage_commission(fee_sats, super_fraction) - assert platform + operator == fee_sats - assert 0 <= platform <= fee_sats - assert 0 <= operator <= fee_sats - - -class TestAllocateOperatorSplitLegs: - """Stage-2: operator's remainder split across N leg wallets per pct rules.""" - - def test_plan_example_50_30_20_on_70(self): - amounts = allocate_operator_split_legs(70, [0.5, 0.3, 0.2]) - assert amounts == [35, 21, 14] - assert sum(amounts) == 70 - - def test_realistic_50_30_20_on_5575(self): - amounts = allocate_operator_split_legs(5575, [0.5, 0.3, 0.2]) - # 50%: round(2787.5) = 2788; 30%: round(1672.5) = 1672; last absorbs - # remainder: 5575 - 2788 - 1672 = 1115. - # Note: round() uses banker's rounding so 2787.5 → 2788 actually - # because 2788 is even. Confirm by total invariant. - assert sum(amounts) == 5575 - assert len(amounts) == 3 - - def test_single_leg_full_remainder(self): - amounts = allocate_operator_split_legs(100, [1.0]) - assert amounts == [100] - - def test_zero_operator_fee_zeros_all_legs(self): - amounts = allocate_operator_split_legs(0, [0.5, 0.5]) - assert amounts == [0, 0] - - def test_empty_legs_list_returns_empty(self): - amounts = allocate_operator_split_legs(100, []) - assert amounts == [] - - def test_last_leg_absorbs_rounding_remainder(self): - # 100 / 3 ≈ 33.33 each; rounding makes the first two 33 and last 34. - amounts = allocate_operator_split_legs(100, [1 / 3, 1 / 3, 1 / 3]) - assert sum(amounts) == 100 - assert amounts[0] == round(100 / 3) # 33 - assert amounts[1] == round(100 / 3) # 33 - # Last leg absorbs the rounding (34, not 33) so total == 100. - assert amounts[2] == 100 - amounts[0] - amounts[1] - - @pytest.mark.parametrize( - "operator_fee,fractions", - [ - (1, [0.5, 0.5]), - (7, [0.5, 0.3, 0.2]), - (100, [0.5, 0.5]), - (5575, [0.5, 0.3, 0.2]), - (1_000_000, [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]), - ], - ) - def test_invariant_sum_equals_operator_fee(self, operator_fee, fractions): - amounts = allocate_operator_split_legs(operator_fee, fractions) - assert sum(amounts) == operator_fee - assert all(a >= 0 for a in amounts) - - -class TestEndToEndScenarios: - """The full two-stage split — super then operator legs — composed.""" - - def test_plan_example_full(self): - # 100 sats fee, super_fee_fraction=0.30, operator splits [0.5, 0.3, 0.2]. - platform, operator = split_two_stage_commission(100, 0.30) - legs = allocate_operator_split_legs(operator, [0.5, 0.3, 0.2]) - assert platform == 30 - assert legs == [35, 21, 14] - assert platform + sum(legs) == 100 - - def test_super_fraction_zero_full_pipeline(self): - platform, operator = split_two_stage_commission(7965, 0.0) - legs = allocate_operator_split_legs(operator, [1.0]) - assert platform == 0 - assert legs == [7965] - assert platform + sum(legs) == 7965 - - def test_super_fraction_one_full_pipeline(self): - platform, operator = split_two_stage_commission(7965, 1.0) - legs = allocate_operator_split_legs(operator, [0.5, 0.5]) - assert platform == 7965 - # Operator has zero to distribute; both legs get zero. - assert legs == [0, 0] - assert platform + sum(legs) == 7965 - - -class TestPartialDispenseSplitRatio: - """The partial-dispense recompute (H6 fix) must preserve the ORIGINAL - platform/operator ratio from the landed settlement — NOT re-derive - from the current super_fee_fraction. - - These tests cover the math; the actual function lives in distribution.py - and is exercised end-to-end via integration testing. Here we verify the - invariant a future maintainer should never break. - """ - - def _recompute(self, original_fee, original_platform_fee, new_fee): - """Mirror of the ratio math in apply_partial_dispense_and_redistribute.""" - if original_fee > 0: - ratio = original_platform_fee / original_fee - else: - ratio = 0.0 - new_platform = round(new_fee * ratio) - new_platform = max(0, min(new_platform, new_fee)) - new_operator = new_fee - new_platform - return new_platform, new_operator - - def test_plan_scenario_30pct_lands_then_partial(self): - # Landed at super_fee_fraction=0.30: 100-sat fee → 30 / 70. - # Partial-dispense to 50% gross → new_fee = 50. - # Original ratio (30/100 = 0.30) preserved. - new_platform, new_operator = self._recompute(100, 30, 50) - assert new_platform == 15 - assert new_operator == 35 - assert new_platform + new_operator == 50 - - def test_super_changed_rate_doesnt_affect_existing_settlement(self): - # Landed at super_fee_fraction=0.30 (fee 7965, platform 2390). - # Super then raises rate to 50% globally. Operator partial-dispenses - # to 50% gross → new_fee = 3982 (round(7965 * 0.5)). - # Original ratio (2390/7965 ≈ 0.30) MUST still apply, not 50%. - new_platform, new_operator = self._recompute(7965, 2390, 3982) - # Expected with original ratio: round(3982 * 0.30006...) = 1195 - # With (broken) current rate of 50%: would be 1991 — much higher. - assert 1190 <= new_platform <= 1200 - assert new_platform + new_operator == 3982 - # Original platform share was ~30%; preserved within rounding. - assert abs(new_platform / 3982 - 2390 / 7965) < 0.001 - - def test_zero_original_fee_yields_zero_platform(self): - new_platform, new_operator = self._recompute(0, 0, 0) - assert new_platform == 0 - assert new_operator == 0 - - def test_invariant_sum_equals_new_fee(self): - # Random-ish parameter sweep over realistic values. - cases = [ - (100, 30, 50), - (100, 0, 50), # original platform_fee was 0 (super_fraction=0) - (100, 100, 50), # original platform_fee was 100 (super_fraction=100) - (7965, 2390, 3982), - (7965, 7965, 3982), - (1_000_000, 333_333, 250_000), - ] - for orig_comm, orig_plat, new_comm in cases: - new_platform, new_operator = self._recompute( - orig_comm, orig_plat, new_comm - ) - assert new_platform + new_operator == new_comm, ( - f"sum invariant violated: {orig_comm=} {orig_plat=} " - f"{new_comm=} → {new_platform=} {new_operator=}" - ) - assert 0 <= new_platform <= new_comm