fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/services/settle/engine.py

@@ -0,0 +1,456 @@
+"""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 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
+
+
+def paid_ceilings(tier: str) -> Mapping[str, Any]:
+    """The most a paid grant at `tier` may hold on each limit."""
+    return {k: v * PAID_CEILING_MULTIPLIER for k, v in window.ceilings(tier).items() if k != 'dup_ratio'}
+
+
+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."""
+
+
+class SettlementEngine:
+    """Manages multi-rail escrow lifecycle and proof persistence."""
+
+    def __init__(
+        self,
+        db_path: str = ':memory:',
+        clock: Optional[Any] = None,
+        mint_url: 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))
+
+    def register_rail(self, rail_id: str, rail: payment.PaymentRail) -> None:
+        with self._lock:
+            self.rails[rail_id.lower()] = rail
+
+    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
+
+    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
+
+    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(),
+        }
+
+    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
+
+    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
+
+    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
+
+    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,
+        }
+
+    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',
+        }
+
+    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],
+        }
+
+    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
+
+    def close(self) -> None:
+        """Safely close underlying settlement database."""
+        self.db.close()
+
+    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,
+        }
+