Source code for fleetmesh_node.planes.services.settle.engine

"""SettlementEngine: multi-rail escrow lifecycle (create / hold / settle /
reconcile / cancel / stream), and the one asymmetric-settlement write -
expanding a peer's grant with a verified nutzap, bounded by the paid
ceiling for its tier."""
from __future__ import annotations

import hashlib
import threading
import time
from typing import Any, Mapping, Optional

from fleetmesh_core.accounting import cashu, window
from . import gateways, payment
from .types import EscrowRowDict
from fleetmesh_node.storage import grants as grants_mod
from .store import PersistentSpentProofs, SettlementStore


# How far a paid expansion may take a limit past the tier ceiling.
#
# A nutzap added to the grant's limits without bound: 10 bytes_in per msat,
# so a million sats bought ten gigabytes of bytes_in on a probation grant whose
# ceiling is 3.2 MB. `_write_grant` clamps every other writer to
# `window.within(limits, tier)` and this one was not clamped at all. Payment
# is allowed to buy headroom above the tier - that is what asymmetric
# settlement is for - but a bounded amount of it: each limit is held to
# ceiling * PAID_CEILING_MULTIPLIER, so a paid peer cannot outgrow what the
# node's capacity planning assumed for the tier by more than this factor.
# The clamp mirrors `_write_grant`'s: the limit is held at the cap and the
# result says which limits were cut and by how much, so the payer can see
# where its top-up stopped buying anything. A nutzap that would move nothing
# at all is refused before its proofs are spent, so it cannot be burned for
# no return.
PAID_CEILING_MULTIPLIER: int = 4





class _Rollback(Exception):
    """Raised inside a `db.transaction()` block to undo the row write when
    the rail refused; caught by the method that raised it."""


[docs]class SettlementEngine: """Manages multi-rail escrow lifecycle and proof persistence."""
[docs] def __init__( self, db_path: str = ':memory:', clock: Optional[Any] = None, mint_url: Optional[str] = payment.DEFAULT_MINT_URL, mint_privkey_hex: Optional[str] = None, nwc_uri: Optional[str] = None, use_live_cashu: bool = False, node_pk: Optional[str] = None, allow_unverified_proofs: bool = False, db: Optional[Any] = None, ) -> None: self.db_path: str = db_path self.clock = clock or (lambda: int(time.time())) self._lock: threading.RLock = threading.RLock() self.db: Any = db if db is not None else SettlementStore(self.db_path) # The pubkey a nutzap must name in its `p` tag to pay THIS node. None # means the engine has no identity and refuses every expansion: a # nutzap addressed to anyone was accepted as payment to us. self.node_pk: Optional[str] = node_pk.lower() if node_pk else None # One persistent spent-secret ledger for every cashu path. self.spent: PersistentSpentProofs = PersistentSpentProofs(self.db, self.clock) cashu_rail: payment.CashuPaymentRail if use_live_cashu: # A live rail asks the real mint whether the proofs are good. That # is the proof verifier when this node is not itself the mint. cashu_rail = gateways.LiveCashuPaymentRail(mint_url=mint_url, mint_privkey_hex=mint_privkey_hex, spent=self.spent) else: cashu_rail = payment.CashuPaymentRail(mint_url=mint_url, mint_privkey_hex=mint_privkey_hex, spent=self.spent, allow_unverified_proofs=allow_unverified_proofs) # Initialize Payment Rails self.rails: dict[str, payment.PaymentRail] = { 'lightning': payment.LightningHoldPaymentRail(), 'cashu': cashu_rail, 'mock': payment.MockPaymentRail(), } if nwc_uri: self.rails['nwc'] = gateways.NWCLightningPaymentRail(nwc_client=gateways.NWCClient(nwc_uri))
[docs] def register_rail(self, rail_id: str, rail: payment.PaymentRail) -> None: with self._lock: self.rails[rail_id.lower()] = rail
[docs] def get_rail(self, rail_id: str) -> payment.PaymentRail: rail = self.rails.get(rail_id.lower()) if not rail: raise ValueError(f"unsupported settlement rail: {rail_id}") return rail
[docs] def cashu_rail(self) -> payment.CashuPaymentRail: """The cashu rail, or a clear error when an operator registered something under that name that is not one.""" rail = self.get_rail('cashu') if not isinstance(rail, payment.CashuPaymentRail): raise ValueError("the 'cashu' rail is a %s, not a CashuPaymentRail" % type(rail).__name__) return rail
[docs] def create_escrow( self, ask_id: str, buyer_pk: str, seller_pk: str, amount_msat: int, payment_hash: str, rail_id: str = 'lightning', ) -> Mapping[str, Any]: """Create a new escrow entry across chosen settlement rail.""" r = self.get_rail(rail_id) h = payment_hash.lower() now = self.clock() inv = r.create_hold_invoice(amount_msat, h) self.db.execute(''' INSERT OR REPLACE INTO escrows (ask_id, buyer, seller, amount_msat, payment_hash, status, rail, created_at) VALUES (?, ?, ?, ?, ?, 'CREATED', ?, ?) ''', (ask_id.lower(), buyer_pk.lower(), seller_pk.lower(), amount_msat, h, rail_id.lower(), now)) self.db.commit() return { 'ask_id': ask_id.lower(), 'buyer': buyer_pk.lower(), 'seller': seller_pk.lower(), 'amount_msat': amount_msat, 'payment_hash': h, 'status': 'CREATED', 'rail': rail_id.lower(), 'invoice': inv.to_dict(), }
[docs] def hold_escrow(self, ask_id: str, token_or_proof: Any = None) -> bool: """Lock funds into escrow.""" row = self.db._one(''' SELECT payment_hash, rail, status FROM escrows WHERE ask_id = ? ''', (ask_id.lower(),)) if not row or row[2] != 'CREATED': return False pay_hash, rail_id, _ = row r = self.get_rail(rail_id) if not r.hold_payment(pay_hash, token_or_proof): return False self.db.execute("UPDATE escrows SET status = 'HELD' WHERE ask_id = ?", (ask_id.lower(),)) self.db.commit() return True
[docs] def settle_escrow(self, ask_id: str, preimage: str) -> bool: """Settle escrow upon disclosure of verified preimage. Under the engine lock and one sqlite transaction: the row is moved to SETTLED first, then the rail; a rail refusal raises inside the transaction so the row rolls back. The rail only changes state after the DB write has succeeded, so a crash between the two leaves at worst a SETTLED row for an escrow the (in-memory) rail will rebuild from it, never a settled rail with a HELD row. """ with self._lock: try: with self.db.transaction() as cur: row = cur.execute('SELECT payment_hash, rail, status FROM escrows WHERE ask_id = ?', (ask_id.lower(),)).fetchone() if not row or row[2] != 'HELD': return False pay_hash, rail_id, _ = row r = self.get_rail(rail_id) now = self.clock() cur.execute(''' UPDATE escrows SET status = 'SETTLED', preimage = ?, settled_at = ? WHERE ask_id = ? ''', (preimage, now, ask_id.lower())) if not r.settle_payment(pay_hash, preimage): raise _Rollback() return True except _Rollback: return False
[docs] def cancel_escrow(self, ask_id: str, reason: str = '') -> bool: """Cancel escrow and refund locked funds. Same lock + transaction discipline as settle_escrow; a rail that refuses the cancel (already settled under us) rolls the row back.""" with self._lock: try: with self.db.transaction() as cur: row = cur.execute('SELECT payment_hash, rail, status FROM escrows WHERE ask_id = ?', (ask_id.lower(),)).fetchone() if not row or row[2] in ('SETTLED', 'CANCELLED'): return False pay_hash, rail_id, _ = row r = self.get_rail(rail_id) cur.execute("UPDATE escrows SET status = 'CANCELLED' WHERE ask_id = ?", (ask_id.lower(),)) if r.get_status(pay_hash).status in ('CREATED', 'HELD') and not r.cancel_payment(pay_hash, reason=reason): raise _Rollback() return True except _Rollback: return False
[docs] def reconcile_escrow( self, ask_id: str, actual_cost_msat: int, preimage: str, ) -> Mapping[str, Any]: """Reconcile a variable-length token escrow (Pre-Funded Escrow with Delta Refund). The seller claims actual metered cost (N_tokens * rate <= amount_msat) using preimage k, and the remainder (amount_msat - actual_cost_msat) is refunded to the buyer. """ row = self.db._one(''' SELECT payment_hash, rail, status, amount_msat, buyer, seller FROM escrows WHERE ask_id = ? ''', (ask_id.lower(),)) if not row: raise ValueError(f"escrow not found for ask_id {ask_id}") pay_hash, rail_id, status, amount_msat, buyer, seller = row if status != 'HELD': raise ValueError(f"cannot reconcile escrow in status {status} (must be HELD)") if actual_cost_msat < 0: raise ValueError(f"actual_cost_msat cannot be negative: {actual_cost_msat}") if actual_cost_msat > amount_msat: raise ValueError( f"metered cost exceeds escrow ceiling ({actual_cost_msat} > {amount_msat})" ) # Verify preimage hashes to payment_hash calc_hash = hashlib.sha256(bytes.fromhex(preimage)).hexdigest() if calc_hash != pay_hash.lower(): raise ValueError("disclosed preimage does not hash to escrow payment_hash") r = self.get_rail(rail_id) if not r.settle_payment(pay_hash, preimage): raise ValueError(f"rail '{rail_id}' payment settlement failed") refund_msat = amount_msat - actual_cost_msat now = self.clock() self.db.execute(''' UPDATE escrows SET status = 'RECONCILED', amount_msat = ?, preimage = ?, settled_at = ? WHERE ask_id = ? ''', (actual_cost_msat, preimage, now, ask_id.lower())) self.db.commit() return { 'ask_id': ask_id.lower(), 'status': 'RECONCILED', 'buyer': buyer, 'seller': seller, 'budget_ceiling_msat': amount_msat, 'claimed_msat': actual_cost_msat, 'refunded_msat': refund_msat, 'payment_hash': pay_hash, 'preimage': preimage, 'settled_at': now, }
[docs] def stream_micropayment( self, ask_id: str, delta_tokens: int, rate_msat_per_token: int, cashu_token: Optional[str] = None, ) -> Mapping[str, Any]: """Process Pay-As-You-Stream micropayment milestone (Cashu Nutzap).""" if delta_tokens < 0: raise ValueError(f"delta_tokens cannot be negative ({delta_tokens})") if rate_msat_per_token < 0: raise ValueError(f"rate_msat_per_token cannot be negative ({rate_msat_per_token})") cost_msat = delta_tokens * rate_msat_per_token return { 'ask_id': ask_id.lower(), 'delta_tokens': delta_tokens, 'cost_msat': cost_msat, 'token_delivered': bool(cashu_token), 'status': 'STREAM_PAID', }
[docs] def get_escrow(self, ask_id: str) -> Optional[EscrowRowDict]: """Retrieve escrow record by ask_id.""" row = self.db._one(''' SELECT ask_id, buyer, seller, amount_msat, payment_hash, preimage, status, rail, created_at, settled_at FROM escrows WHERE ask_id = ? ''', (ask_id.lower(),)) if not row: return None return { 'ask_id': row[0], 'buyer': row[1], 'seller': row[2], 'amount_msat': row[3], 'payment_hash': row[4], 'preimage': row[5], 'status': row[6], 'rail': row[7], 'created_at': row[8], 'settled_at': row[9], }
[docs] def list_escrows(self, limit: int = 50) -> list[EscrowRowDict]: rows = self.db._all(''' SELECT ask_id, buyer, seller, amount_msat, payment_hash, preimage, status, rail, created_at, settled_at FROM escrows ORDER BY created_at DESC LIMIT ? ''', (limit,)) out: list[EscrowRowDict] = [] for r in rows: out.append({ 'ask_id': r[0], 'buyer': r[1], 'seller': r[2], 'amount_msat': r[3], 'payment_hash': r[4], 'preimage': r[5], 'status': r[6], 'rail': r[7], 'created_at': r[8], 'settled_at': r[9], }) return out
[docs] def close(self) -> None: """Safely close underlying settlement database.""" self.db.close()
[docs] def expand_grant_with_nutzap( self, grant_store: grants_mod.GrantStore, peer_pk: str, nutzap_event: Mapping[str, Any], conversion_rate: Optional[Mapping[str, int]] = None, ) -> Mapping[str, Any]: """Asymmetric settlement: expand peer grant rate-buckets upon receiving verified Nutzap. Spec reference: spec.html line 7268 (Bridge 4: NIP-61 Cashu Nutzap Asymmetric Settlement). Order matters: the nutzap is verified (recipient, amount, proofs) and the grant is found and clamped BEFORE any secret is marked spent, so a refused expansion never burns the payer's proofs. The spent check, the grant read, the clamp and the two writes all happen under self._lock: two threads presenting the same nutzap used to both pass the check outside the lock and both credit the grant. Custody caveat: the proofs are VERIFIED (mint key or NUT-07 check-state), not SWAPPED. Until a swap is wired in, the payer still holds proofs the mint considers unspent and could spend them elsewhere after this node credited the grant; the spent-secret ledger only protects this node from being paid twice with them. A rail that cannot verify at all (no mint key, no verifier, no explicit allow_unverified_proofs) is refused up front. """ if not self.node_pk: raise ValueError("settlement engine has no node_pk; cannot tell whom a nutzap pays") cashu_rail = self.cashu_rail() if not cashu_rail.can_verify_proofs(): raise ValueError("invalid nutzap: no mint key or proof verifier configured: proofs cannot be verified") ok_nut, reason, amount_msat = cashu_rail.verify_nutzap(nutzap_event, expected_recipient=self.node_pk) if not ok_nut: raise ValueError(f"invalid nutzap: {reason}") proofs = cashu.proofs_of(nutzap_event) secrets: list[str] = [] for p in proofs: sec = p.get('secret') if not isinstance(sec, str) or not sec: raise ValueError("cashu proof without a secret") if sec in secrets: raise ValueError(f"double-spend attempt on secret: {sec}") secrets.append(sec) # Conversion rate: default 1 msat -> +10 bytes_in, +1 event per 1000 msat rates = conversion_rate or { 'bytes_in_per_msat': 10, 'events_in_per_sat': 1, } extra_bytes = amount_msat * rates.get('bytes_in_per_msat', 10) extra_events = (amount_msat // 1000) * rates.get('events_in_per_sat', 1) with self._lock: for sec in secrets: if cashu_rail.is_spent(sec): raise ValueError(f"double-spend attempt on secret: {sec}") # Retrieve current issued grant for peer grant = grant_store.get(peer_pk, grants_mod.ISSUED) if not grant: raise ValueError(f"no issued grant found for peer {peer_pk[:16]}") held = grant['payload'] payload = dict(held) limits: dict[str, int] = dict(held.get('limits', {})) before = dict(limits) limits['bytes_in'] = limits.get('bytes_in', 0) + extra_bytes limits['events_in'] = limits.get('events_in', 0) + extra_events limits['blob_bytes'] = limits.get('blob_bytes', 0) + (extra_bytes // 2) # Clamp to the paid ceiling for the grant's tier (see PAID_CEILING_MULTIPLIER). caps = paid_ceilings(held.get('tier') or 'probation') clamped: dict[str, int] = {} for k, cap in caps.items(): # Never lower a limit the grant already holds (e.g. one an operator # set by hand above the paid cap); only stop payment adding to it. floor = max(cap, before.get(k, 0)) if k in limits and limits[k] > floor: clamped[k] = limits[k] - floor limits[k] = floor if all(limits.get(k, 0) <= before.get(k, 0) for k in ('bytes_in', 'events_in', 'blob_bytes')): raise ValueError("grant is already at the paid ceiling for its tier; nutzap would buy nothing") now = self.clock() for p in proofs: cashu_rail.mark_spent(p['secret'], p.get('id'), p.get('amount'), now) payload['limits'] = limits grant_store.put( peer_pk, grants_mod.ISSUED, payload, envelope_id=grant['envelope_id'], now=now, ) return { 'peer': peer_pk, 'amount_msat': amount_msat, 'added_bytes_in': limits['bytes_in'] - before.get('bytes_in', 0), 'added_events_in': limits['events_in'] - before.get('events_in', 0), 'new_limits': limits, 'clamped': clamped, }