Padreug
116df46d38
When the caller omits settled_entry_links (the default), the endpoint
auto-detects open entries across both directions for the user and writes
a single transaction that:
- Zeros every per-user account that has an open balance, not just the
net (the libra-#33 bug — previously the 2-leg form left both Payable
and Receivable carrying non-zero balances after a complete cash
settlement, while only netting the cash side).
- Routes any cash above the net obligation to Liabilities:Credit:User-X
(libra-#41), so over-payment lands on a real liability account
instead of silently drifting.
- Attaches every reconciled source entry's link
(exp-..., rcv-...) so a reader scanning the settlement transaction
can trace what it cleared.
Cash less than the net obligation, with no explicit links, returns 400
with a structured diff (cash_paid, net_obligation, receivable_total,
payable_total). The operator either pays the exact net or passes
settled_entry_links to settle a specific subset; partial settlement
without a coherent target is not silently absorbed.
The legacy explicit-links code path is unchanged — callers that pass
settled_entry_links keep the 2-leg shape with no auto-detection. None
of the callers in libra or aiolabs/webapp currently use that field, but
the contract is preserved for the partial-settle-of-specific-entries
flow.
format_fiat_net_settlement_entry is the new helper for the 2/3/4-leg
shape; it enforces the cash-balance constraint inline so callers can't
accidentally produce an unbalanced transaction.
tests/test_settlement_api.py (6 tests) locks in:
- Nancy's #33 scenario: receivable 100 + payable 50 + cash 50
zeros both per-user accounts, links both source entries
- Overpay: cash 70 against net 50 → credit balance 20
- Pure receivable overpay → credit appears
- Underpay without explicit links → 400 with diff
- No open receivables → 400 with hint pointing at /payables/pay
- Explicit settled_entry_links uses legacy 2-leg path
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
342 lines
13 KiB
Python
342 lines
13 KiB
Python
"""Settlement netting + credit overflow — libra-#33 + libra-#41.
|
|
|
|
`POST /libra/api/v1/receivables/settle` with `settled_entry_links=None`
|
|
(the default) auto-detects open entries in both directions, builds a
|
|
3-leg settlement transaction that zeros out both per-user accounts when
|
|
the user has open balances on both sides (libra-#33's nancy scenario),
|
|
and routes any excess cash to `Liabilities:Credit:User-X` (libra-#41).
|
|
|
|
Underpay without explicit entry-picks returns 400 with diff details so
|
|
the operator can either pay the exact net or specify `settled_entry_links`.
|
|
"""
|
|
import importlib
|
|
from uuid import uuid4
|
|
|
|
import pytest
|
|
|
|
from .helpers import (
|
|
approve_entry,
|
|
get_balance,
|
|
list_user_entries,
|
|
post_expense,
|
|
post_receivable,
|
|
settle_receivable,
|
|
)
|
|
|
|
|
|
def _libra_module(submodule: str):
|
|
for prefix in ("lnbits.extensions.libra", "libra"):
|
|
try:
|
|
return importlib.import_module(f"{prefix}.{submodule}")
|
|
except ModuleNotFoundError:
|
|
continue
|
|
raise ModuleNotFoundError(f"libra.{submodule}")
|
|
|
|
|
|
async def _approve_and_refresh(client, wallet, super_user_headers, entry_id):
|
|
"""Approve a pending entry and force a Fava reload (libra-#37 workaround)."""
|
|
await approve_entry(client, super_user_headers=super_user_headers, entry_id=entry_id)
|
|
await list_user_entries(client, wallet_inkey=wallet.inkey)
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Nancy's #33 scenario and variants
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_exact_net_settlement_zeroes_both_per_user_accounts(
|
|
client, super_user_headers, configured_user, standard_accounts,
|
|
):
|
|
"""Nancy: receivable 100 EUR + payable 50 EUR + 50 EUR cash → 3-leg
|
|
settlement that zeros both Receivable and Payable for this user.
|
|
|
|
Acceptance criteria from libra-#33:
|
|
- Settlement links every source entry it reconciles.
|
|
- Per-user balances drop to 0 (not just net to 0 leaving each side open).
|
|
"""
|
|
user, wallet = configured_user
|
|
tag = uuid4().hex[:6]
|
|
|
|
# Admin records the receivable (cleared on creation).
|
|
await post_receivable(
|
|
client,
|
|
super_user_headers=super_user_headers,
|
|
user_id=user.id,
|
|
amount="100.00", currency="EUR",
|
|
description=f"Rent share {tag}",
|
|
revenue_account=standard_accounts["revenue_rent"]["name"],
|
|
)
|
|
# User submits an expense (pending until admin approves).
|
|
exp = await post_expense(
|
|
client,
|
|
wallet_inkey=wallet.inkey,
|
|
user_wallet_id=wallet.id,
|
|
amount="50.00", currency="EUR",
|
|
description=f"Drill purchase {tag}",
|
|
expense_account=standard_accounts["expense_food"]["name"],
|
|
)
|
|
await _approve_and_refresh(client, wallet, super_user_headers, exp["id"])
|
|
|
|
# Sanity check: user owes 50 EUR net (100 receivable - 50 payable).
|
|
balance_before = await get_balance(client, wallet_inkey=wallet.inkey)
|
|
eur_before = balance_before.get("fiat_balances", {}).get("EUR")
|
|
assert float(eur_before) == pytest.approx(50.0), (
|
|
f"expected +50 EUR net (user owes libra), got {eur_before}"
|
|
)
|
|
|
|
# Settle the net cash: 50 EUR.
|
|
await settle_receivable(
|
|
client,
|
|
super_user_headers=super_user_headers,
|
|
user_id=user.id,
|
|
amount="50.00", currency="EUR",
|
|
description=f"Cash settlement {tag}",
|
|
)
|
|
await list_user_entries(client, wallet_inkey=wallet.inkey)
|
|
|
|
# After settlement: net balance is 0.
|
|
balance_after = await get_balance(client, wallet_inkey=wallet.inkey)
|
|
eur_after = balance_after.get("fiat_balances", {}).get("EUR", 0)
|
|
assert float(eur_after or 0) == pytest.approx(0.0), (
|
|
f"expected 0 EUR after exact net settlement, got {eur_after}"
|
|
)
|
|
|
|
# Per-account breakdown: every user-side account is at 0.
|
|
# (The acceptance criterion is that NEITHER Receivable nor Payable
|
|
# carries an open balance — not just that they net to 0.)
|
|
breakdown = balance_after.get("account_balances", [])
|
|
for row in breakdown:
|
|
if user.id[:8] in (row.get("account") or ""):
|
|
assert float(row.get("eur", 0) or 0) == pytest.approx(0.0), (
|
|
f"per-user account {row['account']} still has "
|
|
f"{row.get('eur')} EUR open after complete settlement; "
|
|
f"libra-#33 acceptance criterion violated"
|
|
)
|
|
|
|
# The settlement entry's links must cover both source entries.
|
|
# Both rcv-* and exp-* links should appear via Fava query.
|
|
fava_client_mod = _libra_module("fava_client")
|
|
fava = fava_client_mod.get_fava_client()
|
|
unsettled_receivables = await fava.get_unsettled_entries_bql(user.id, "receivable")
|
|
unsettled_payables = await fava.get_unsettled_entries_bql(user.id, "expense")
|
|
assert not unsettled_receivables, (
|
|
f"receivable left as unsettled after complete settlement: "
|
|
f"{unsettled_receivables}"
|
|
)
|
|
assert not unsettled_payables, (
|
|
f"payable left as unsettled after complete settlement: "
|
|
f"{unsettled_payables}"
|
|
)
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_overpay_routes_excess_to_credit(
|
|
client, super_user_headers, configured_user, standard_accounts,
|
|
):
|
|
"""Receivable 100 + payable 50 + cash 70 EUR → settles both per-user
|
|
accounts to 0, and the 20 EUR excess lands on Liabilities:Credit:User-X
|
|
(libra now owes the user 20 going forward).
|
|
|
|
Headline libra-#41 case: cash > net obligation absorbed into credit.
|
|
"""
|
|
user, wallet = configured_user
|
|
tag = uuid4().hex[:6]
|
|
|
|
await post_receivable(
|
|
client,
|
|
super_user_headers=super_user_headers,
|
|
user_id=user.id,
|
|
amount="100.00", currency="EUR",
|
|
description=f"Receivable {tag}",
|
|
revenue_account=standard_accounts["revenue_rent"]["name"],
|
|
)
|
|
exp = await post_expense(
|
|
client,
|
|
wallet_inkey=wallet.inkey,
|
|
user_wallet_id=wallet.id,
|
|
amount="50.00", currency="EUR",
|
|
description=f"Payable {tag}",
|
|
expense_account=standard_accounts["expense_food"]["name"],
|
|
)
|
|
await _approve_and_refresh(client, wallet, super_user_headers, exp["id"])
|
|
|
|
# User pays 70 EUR — 20 EUR over the 50 EUR net obligation.
|
|
await settle_receivable(
|
|
client,
|
|
super_user_headers=super_user_headers,
|
|
user_id=user.id,
|
|
amount="70.00", currency="EUR",
|
|
description=f"Overpay settlement {tag}",
|
|
)
|
|
await list_user_entries(client, wallet_inkey=wallet.inkey)
|
|
|
|
# Net balance should be -20 EUR (libra owes user 20 via credit).
|
|
balance = await get_balance(client, wallet_inkey=wallet.inkey)
|
|
eur = balance.get("fiat_balances", {}).get("EUR")
|
|
assert float(eur) == pytest.approx(-20.0), (
|
|
f"expected -20 EUR (libra owes user via credit), got {eur} from {balance}"
|
|
)
|
|
|
|
# Credit account should appear in the breakdown with -20 EUR.
|
|
breakdown = balance.get("account_balances", [])
|
|
credit_row = next(
|
|
(r for r in breakdown if "Credit" in (r.get("account") or "")), None,
|
|
)
|
|
assert credit_row is not None, (
|
|
f"Credit account missing from breakdown: {breakdown}"
|
|
)
|
|
assert float(credit_row.get("eur", 0)) == pytest.approx(-20.0), (
|
|
f"expected -20 EUR on Credit:User-X, got {credit_row.get('eur')}"
|
|
)
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_pure_receivable_overpay_creates_credit(
|
|
client, super_user_headers, configured_user, standard_accounts,
|
|
):
|
|
"""No payable side — receivable 50 + cash 70 → receivable cleared,
|
|
20 EUR moves to credit. 2-leg + credit overflow leg."""
|
|
user, wallet = configured_user
|
|
tag = uuid4().hex[:6]
|
|
|
|
await post_receivable(
|
|
client,
|
|
super_user_headers=super_user_headers,
|
|
user_id=user.id,
|
|
amount="50.00", currency="EUR",
|
|
description=f"Pure receivable {tag}",
|
|
revenue_account=standard_accounts["revenue_rent"]["name"],
|
|
)
|
|
await list_user_entries(client, wallet_inkey=wallet.inkey)
|
|
|
|
await settle_receivable(
|
|
client,
|
|
super_user_headers=super_user_headers,
|
|
user_id=user.id,
|
|
amount="70.00", currency="EUR",
|
|
description=f"Pure overpay {tag}",
|
|
)
|
|
await list_user_entries(client, wallet_inkey=wallet.inkey)
|
|
|
|
balance = await get_balance(client, wallet_inkey=wallet.inkey)
|
|
eur = balance.get("fiat_balances", {}).get("EUR")
|
|
# Receivable cleared (0) - credit (-20) = -20 net
|
|
assert float(eur) == pytest.approx(-20.0), (
|
|
f"expected -20 EUR after pure overpay, got {eur}"
|
|
)
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Validation: underpay without explicit links → 400 with diff
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_underpay_without_explicit_links_returns_400(
|
|
client, super_user_headers, configured_user, standard_accounts,
|
|
):
|
|
"""Cash < net obligation and no `settled_entry_links` → 400 with the
|
|
diff payload so operator can fix the amount or specify entries.
|
|
|
|
Without #41's credit overflow + #33's auto-detect, this was the
|
|
silent-drift case that motivated both issues. Now: explicit, recoverable.
|
|
"""
|
|
user, wallet = configured_user
|
|
|
|
await post_receivable(
|
|
client,
|
|
super_user_headers=super_user_headers,
|
|
user_id=user.id,
|
|
amount="100.00", currency="EUR",
|
|
description="Receivable to underpay against",
|
|
revenue_account=standard_accounts["revenue_rent"]["name"],
|
|
)
|
|
await list_user_entries(client, wallet_inkey=wallet.inkey)
|
|
|
|
r = await client.post(
|
|
"/libra/api/v1/receivables/settle",
|
|
headers=super_user_headers,
|
|
json={
|
|
"user_id": user.id,
|
|
"amount": "30.00",
|
|
"currency": "EUR",
|
|
"payment_method": "cash",
|
|
"description": "Underpay attempt",
|
|
},
|
|
)
|
|
assert r.status_code == 400, f"expected 400, got {r.status_code}: {r.text}"
|
|
payload = r.json().get("detail")
|
|
assert isinstance(payload, dict), f"expected structured detail, got {payload!r}"
|
|
assert payload.get("cash_paid") == 30.0
|
|
assert payload.get("net_obligation") == 100.0
|
|
assert payload.get("receivable_total") == 100.0
|
|
assert payload.get("payable_total") == 0.0
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_no_open_receivable_returns_400(
|
|
client, super_user_headers, configured_user,
|
|
):
|
|
"""User has no open receivables → endpoint can't settle. 400 with a
|
|
hint pointing at `/payables/pay` for the inverse direction."""
|
|
user, _ = configured_user
|
|
|
|
r = await client.post(
|
|
"/libra/api/v1/receivables/settle",
|
|
headers=super_user_headers,
|
|
json={
|
|
"user_id": user.id,
|
|
"amount": "50.00",
|
|
"currency": "EUR",
|
|
"payment_method": "cash",
|
|
"description": "Random deposit attempt",
|
|
},
|
|
)
|
|
assert r.status_code == 400, f"expected 400, got {r.status_code}: {r.text}"
|
|
assert "no open receivables" in r.text.lower() or "payables/pay" in r.text
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Legacy explicit-links path: preserved for partial-settle-of-specific-entries
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_explicit_settled_entry_links_uses_legacy_2_leg_path(
|
|
client, super_user_headers, configured_user, standard_accounts,
|
|
):
|
|
"""When `settled_entry_links` is provided, backend trusts the caller's
|
|
list and writes the legacy 2-leg shape. No auto-netting, no credit
|
|
overflow validation. Required for callers that want to settle a
|
|
specific subset of entries.
|
|
|
|
Requires `amount_sats` per the legacy path's existing contract.
|
|
"""
|
|
user, wallet = configured_user
|
|
|
|
await post_receivable(
|
|
client,
|
|
super_user_headers=super_user_headers,
|
|
user_id=user.id,
|
|
amount="50.00", currency="EUR",
|
|
description="Receivable for explicit-link test",
|
|
revenue_account=standard_accounts["revenue_rent"]["name"],
|
|
)
|
|
await list_user_entries(client, wallet_inkey=wallet.inkey)
|
|
|
|
# Caller passes explicit (but possibly empty) link list → legacy path.
|
|
r = await client.post(
|
|
"/libra/api/v1/receivables/settle",
|
|
headers=super_user_headers,
|
|
json={
|
|
"user_id": user.id,
|
|
"amount": "50.00",
|
|
"currency": "EUR",
|
|
"amount_sats": 55_000,
|
|
"payment_method": "cash",
|
|
"description": "Explicit-link settle",
|
|
"settled_entry_links": [], # opts out of auto-detect
|
|
},
|
|
)
|
|
assert r.status_code == 200, f"legacy explicit-link path: {r.status_code} {r.text}"
|