fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/services/settle/payment.py

@@ -0,0 +1,512 @@
+"""Modular Settlement Rails: the adapters that move money, and nothing portable.
+
+Spec reference: spec.html "Modular Settlement Rails & Zero-Custody Payments
+(PaymentRail)" and "Bridge 4: NIP-60 / NIP-61 Cashu Nutzap Asymmetric
+Settlement".
+
+The maths and wire formats - BDHKE over secp256k1 (NUT-00..03), Cashu tokens,
+NIP-61 Nutzap events and the proof-acceptance policy - live in
+fleetmesh_core.accounting.cashu. What this module owns:
+
+   - `PaymentRail`, the adapter interface and the escrow state machine
+   - `CashuPaymentRail` (Chaumian e-cash blind token settlement)
+   - `LightningHoldPaymentRail` (HTLC hold-invoice escrow lifecycle)
+   - `MockPaymentRail` (in-memory testing rail)
+   - `SpentProofs`, the durable set of proofs this node already took
+"""
+from __future__ import annotations
+
+import abc
+import hashlib
+import logging
+import threading
+import time
+from collections import Counter
+from dataclasses import asdict, dataclass, field
+from typing import Any, Mapping, Optional, Sequence, cast
+
+from fleetmesh_core.accounting.cashu import (
+    BlindSignature, CashuProof, NUTZAP_KIND, ProofVerifier,
+    accept_proofs, deserialize_cashu_token, point_to_hex,
+    proofs_of, verify_nutzap_event,
+)
+from fleetmesh_core.crypto import curve
+from fleetmesh_core.wire.interfaces import NostrEvent
+
+log = logging.getLogger(__name__)
+
+__all__ = [
+    'DEFAULT_MINT_URL',
+    'PaymentError',
+    'IllegalTransition',
+    'TRANSITIONS',
+    'TERMINAL_STATES',
+    'HoldInvoice',
+    'UNKNOWN_INVOICE',
+    'preimage_matches',
+    'SpentProofs',
+    'PaymentRail',
+    'LightningHoldPaymentRail',
+    'CashuPaymentRail',
+    'MockPaymentRail',
+]
+
+DEFAULT_MINT_URL: str = 'https://mint.example.org'
+
+
+class PaymentError(ValueError):
+    """A rail refused to move money. A ValueError so the callers that already
+    catch ValueError around rail actions (settlement subsystem) keep working."""
+
+
+class IllegalTransition(PaymentError):
+    """The one error for an escrow asked to go where its state machine does
+    not: settle from CREATED, hold twice, cancel what is settled, hold what
+    has expired, or act on a hash no rail has seen (from_state UNKNOWN)."""
+
+    def __init__(self, payment_hash: str, from_state: str, to_state: str, why: str = '') -> None:
+        self.payment_hash = payment_hash
+        self.from_state = from_state
+        self.to_state = to_state
+        self.why = why
+        tail = f' ({why})' if why else ''
+        super().__init__(f'escrow {payment_hash[:16]}: {from_state} -> {to_state} is not a legal transition{tail}')
+
+
+# The escrow state machine every rail shares: CREATED -> HELD -> SETTLED |
+# CANCELLED | FAILED, CREATED -> CANCELLED. Terminal states have no exits.
+TRANSITIONS: dict[str, frozenset[str]] = {
+    'CREATED': frozenset({'HELD', 'CANCELLED'}),
+    'HELD': frozenset({'SETTLED', 'CANCELLED', 'FAILED'}),
+    'SETTLED': frozenset(),
+    'CANCELLED': frozenset(),
+    'FAILED': frozenset(),
+}
+TERMINAL_STATES: frozenset[str] = frozenset(s for s, outs in TRANSITIONS.items() if not outs)
+
+
+from .types import HoldInvoiceDict, PaymentRailStats
+
+
+@dataclass(slots=True)
+class HoldInvoice:
+    """One rail's escrow against a payment hash, from CREATED through HELD to
+    SETTLED or CANCELLED. Every rail keeps the same record; the Lightning
+    one adds a bolt11, the Cashu one the proofs it is holding, the NWC one
+    the wallet's invoice. UNKNOWN is what get_status answers for a hash no
+    rail has seen."""
+    rail: str
+    payment_hash: str
+    amount_msat: int
+    status: str = 'CREATED'
+    created_at: int = 0
+    expiry: int = 3600
+    description: str = ''
+    preimage: Optional[str] = None
+    bolt11: Optional[str] = None
+    mint: Optional[str] = None
+    invoice: Optional[str] = None               # the wallet's bolt11, on the NWC rail
+    wallet_payment_hash: Optional[str] = None
+    proofs: list[CashuProof] = field(default_factory=list)
+    held_at: Optional[int] = None
+    settled_at: Optional[int] = None
+    cancelled_at: Optional[int] = None
+    cancel_reason: Optional[str] = None
+    swapped_at: Optional[int] = None            # live Cashu rail: held proofs swapped at the mint
+    new_signatures: list[BlindSignature] = field(default_factory=list)
+
+    def to_dict(self) -> HoldInvoiceDict:
+        return cast(HoldInvoiceDict, asdict(self))
+
+
+UNKNOWN_INVOICE = HoldInvoice(rail='', payment_hash='', amount_msat=0, status='UNKNOWN')
+
+
+# ---------------------------------------------------------------------------
+# Payment Rail Adapter Interface & Drivers
+# ---------------------------------------------------------------------------
+
+def preimage_matches(preimage: Any, payment_hash: str) -> bool:
+    """SHA256(preimage) == payment_hash, and False - never an exception - for
+    a preimage that is not hex. Every rail took bytes.fromhex on the caller's
+    string, so a stranger settling with 'zz' raised ValueError out of the
+    handler rather than being refused like any other wrong preimage."""
+    if not isinstance(preimage, str):
+        return False
+    try:
+        p_bytes = bytes.fromhex(preimage)
+    except ValueError:
+        return False
+    return hashlib.sha256(p_bytes).hexdigest().lower() == payment_hash.lower()
+
+
+class SpentProofs:
+    """The set of proof secrets this node has already accepted.
+
+    An ecash proof is bearer money: whoever shows it first is paid, and the
+    only thing stopping the same proof buying twice is this set. It was a
+    Python set on the rail object, so a restart emptied it, and the
+    `spent_proofs` SQLite table beside it was written to and never read -
+    every proof ever accepted became spendable again on every restart.
+
+    Subclasses back this with a table; the default is in-memory for rails
+    that are constructed without a store (tests, throwaway engines).
+    """
+
+    def __init__(self) -> None:
+        self._mem: set[str] = set()
+
+    def is_spent(self, secret: str) -> bool:
+        return secret in self._mem
+
+    def mark_spent(self, secret: str, keyset_id: Optional[str] = None,
+                   amount: Optional[int] = None, now: Optional[int] = None) -> None:
+        self._mem.add(secret)
+
+    def __contains__(self, secret: object) -> bool:
+        return isinstance(secret, str) and self.is_spent(secret)
+
+
+class PaymentRail(abc.ABC):
+    """The zero-custody escrow state machine every rail shares.
+
+    One escrow per payment hash, CREATED -> HELD -> SETTLED | CANCELLED |
+    FAILED (see TRANSITIONS). The base owns the escrow table, the lock, the
+    transitions, expiry and the bookkeeping (`stats`); a concrete rail only
+    implements its own I/O: `_hold_io` (is this token/proof/payment real
+    money for this escrow?) and `_settle_io` (spend/forward it). Rails that
+    need to talk to a wallet to create an invoice override
+    `create_hold_invoice` and call `_new_invoice` + `_register`.
+
+    The public verbs (`hold_payment`, `settle_payment`, `cancel_payment`)
+    answer False for every illegal move - unknown hash, wrong state, expired
+    invoice, bad preimage - and count the refusal; `create_hold_invoice`
+    raises IllegalTransition for a hash already in flight, and
+    PaymentError for a non-positive amount or expiry. Nothing silently
+    succeeds twice.
+    """
+
+    rail_id: str = ''
+
+    def __init__(self) -> None:
+        self.escrows: dict[str, HoldInvoice] = {}
+        self._lock: threading.RLock = threading.RLock()
+        self._refusals: Counter[str] = Counter()
+
+    # -- the table -----------------------------------------------------------
+
+    @property
+    def invoices(self) -> dict[str, HoldInvoice]:
+        """The escrow table under its Lightning-era name (`rail.invoices`)."""
+        return self.escrows
+
+    def _new_invoice(self, amount_msat: int, payment_hash: str, expiry: int, description: str) -> HoldInvoice:
+        """A CREATED escrow for this rail, not yet registered. Refuses a
+        non-positive amount or expiry and a hash whose escrow is in flight -
+        a second CREATED over a HELD one would be a way to lose the hold."""
+        h = payment_hash.lower()
+        if amount_msat <= 0:
+            raise PaymentError(f'escrow {h[:16]}: amount_msat must be positive, got {amount_msat}')
+        if expiry <= 0:
+            raise PaymentError(f'escrow {h[:16]}: expiry must be positive, got {expiry}')
+        with self._lock:
+            prior = self.escrows.get(h)
+            if prior is not None:
+                raise IllegalTransition(h, prior.status, 'CREATED', 'an escrow for this hash already exists')
+        return HoldInvoice(rail=self.rail_id, payment_hash=h, amount_msat=amount_msat, expiry=expiry,
+                           created_at=int(time.time()), description=description)
+
+    def _register(self, inv: HoldInvoice) -> HoldInvoice:
+        with self._lock:
+            prior = self.escrows.get(inv.payment_hash)
+            if prior is not None:
+                raise IllegalTransition(inv.payment_hash, prior.status, 'CREATED', 'an escrow for this hash already exists')
+            self.escrows[inv.payment_hash] = inv
+        return inv
+
+    def _escrow_for(self, payment_hash: str, to_state: str) -> HoldInvoice:
+        """The escrow for a hash, or IllegalTransition(UNKNOWN -> to_state)."""
+        inv = self.escrows.get(payment_hash.lower())
+        if inv is None:
+            raise IllegalTransition(payment_hash.lower(), 'UNKNOWN', to_state, 'no escrow for this hash')
+        return inv
+
+    # -- the state machine ---------------------------------------------------
+
+    @staticmethod
+    def is_expired(inv: HoldInvoice, now: Optional[int] = None) -> bool:
+        """A CREATED escrow nobody paid within its expiry. HELD and the
+        terminal states do not expire: money already locked is settled or
+        cancelled explicitly."""
+        if inv.status != 'CREATED' or not inv.created_at:
+            return False
+        return (now if now is not None else int(time.time())) >= inv.created_at + inv.expiry
+
+    def _check_transition(self, inv: HoldInvoice, from_states: Sequence[str], to_state: str) -> None:
+        """Raise IllegalTransition unless inv may go to to_state from here."""
+        if inv.status not in from_states or to_state not in TRANSITIONS.get(inv.status, frozenset()):
+            raise IllegalTransition(inv.payment_hash, inv.status, to_state)
+        if to_state == 'HELD' and self.is_expired(inv):
+            raise IllegalTransition(inv.payment_hash, inv.status, to_state, 'invoice expired')
+
+    def _transition(self, inv: HoldInvoice, from_states: Sequence[str], to_state: str) -> HoldInvoice:
+        """Move inv to to_state, stamping the matching *_at field. Caller holds the lock."""
+        self._check_transition(inv, from_states, to_state)
+        now = int(time.time())
+        inv.status = to_state
+        if to_state == 'HELD':
+            inv.held_at = now
+        elif to_state == 'SETTLED':
+            inv.settled_at = now
+        elif to_state in ('CANCELLED', 'FAILED'):
+            inv.cancelled_at = now
+        return inv
+
+    def _refuse(self, action: str, err: PaymentError) -> bool:
+        self._refusals[action] += 1
+        log.info('%s rail refused %s: %s', self.rail_id, action, err)
+        return False
+
+    # -- rail-specific I/O hooks ---------------------------------------------
+
+    def _hold_io(self, inv: HoldInvoice, token_or_proof: Any) -> None:
+        """Verify that token_or_proof pays inv; raise PaymentError if not.
+        The default rail takes the hold on the operator's word (Lightning
+        hold invoice already accepted by the node, mock)."""
+
+    def _settle_io(self, inv: HoldInvoice, preimage: str) -> None:
+        """Spend/forward the held money; raise PaymentError to keep it HELD."""
+
+    # -- the public verbs ----------------------------------------------------
+
+    def create_hold_invoice(
+        self,
+        amount_msat: int,
+        payment_hash: str,
+        expiry: int = 3600,
+        description: str = '',
+    ) -> HoldInvoice:
+        """Create a conditional hold invoice keyed to payment_hash."""
+        return self._register(self._new_invoice(amount_msat, payment_hash, expiry, description))
+
+    def hold_payment(self, payment_hash: str, token_or_proof: Any = None) -> bool:
+        """Lock/hold funds in escrow against payment_hash: CREATED -> HELD."""
+        with self._lock:
+            try:
+                inv = self._escrow_for(payment_hash, 'HELD')
+                self._check_transition(inv, ('CREATED',), 'HELD')
+                self._hold_io(inv, token_or_proof)
+                self._transition(inv, ('CREATED',), 'HELD')
+            except PaymentError as e:
+                return self._refuse('hold', e)
+        return True
+
+    def settle_payment(self, payment_hash: str, preimage: str) -> bool:
+        """Release escrowed funds upon providing the preimage: HELD -> SETTLED."""
+        with self._lock:
+            try:
+                inv = self._escrow_for(payment_hash, 'SETTLED')
+                self._check_transition(inv, ('HELD',), 'SETTLED')
+                if not preimage_matches(preimage, inv.payment_hash):
+                    raise PaymentError(f'escrow {inv.payment_hash[:16]}: preimage does not hash to payment_hash')
+                self._settle_io(inv, preimage)
+                self._transition(inv, ('HELD',), 'SETTLED')
+                inv.preimage = preimage
+            except PaymentError as e:
+                return self._refuse('settle', e)
+        return True
+
+    def cancel_payment(self, payment_hash: str, reason: str = '') -> bool:
+        """Cancel the escrow and release what is locked: CREATED | HELD -> CANCELLED."""
+        with self._lock:
+            try:
+                inv = self._escrow_for(payment_hash, 'CANCELLED')
+                self._transition(inv, ('CREATED', 'HELD'), 'CANCELLED')
+                inv.cancel_reason = reason
+            except PaymentError as e:
+                return self._refuse('cancel', e)
+        return True
+
+    def fail_payment(self, payment_hash: str, reason: str = '') -> bool:
+        """A HELD escrow whose settlement I/O is known lost: HELD -> FAILED."""
+        with self._lock:
+            try:
+                inv = self._escrow_for(payment_hash, 'FAILED')
+                self._transition(inv, ('HELD',), 'FAILED')
+                inv.cancel_reason = reason
+            except PaymentError as e:
+                return self._refuse('fail', e)
+        return True
+
+    def get_status(self, payment_hash: str) -> HoldInvoice:
+        """The escrow as it stands: CREATED, HELD, SETTLED, CANCELLED, FAILED; UNKNOWN_INVOICE for a hash never seen."""
+        return self.escrows.get(payment_hash.lower(), UNKNOWN_INVOICE)
+
+    def stats(self) -> PaymentRailStats:
+        """Escrow counts and msat by state, plus refusals by action."""
+        with self._lock:
+            by_state: Counter[str] = Counter()
+            msat: Counter[str] = Counter()
+            for inv in self.escrows.values():
+                by_state[inv.status] += 1
+                msat[inv.status] += inv.amount_msat
+            return {
+                'rail': self.rail_id,
+                'escrows': len(self.escrows),
+                'by_state': dict(by_state),
+                'msat_by_state': dict(msat),
+                'refusals': dict(self._refusals),
+            }
+
+
+class LightningHoldPaymentRail(PaymentRail):
+    """Native Lightning hold-invoice rail. Its only I/O is minting the bolt11
+    for the escrow; the node's own LN backend accepts the HTLC."""
+
+    rail_id: str = 'lightning'
+
+    def create_hold_invoice(
+        self,
+        amount_msat: int,
+        payment_hash: str,
+        expiry: int = 3600,
+        description: str = 'fleetmesh-compute',
+    ) -> HoldInvoice:
+        inv = self._new_invoice(amount_msat, payment_hash, expiry, description)
+        inv.bolt11 = f"lnbc{amount_msat}u1p{inv.payment_hash[:32]}"
+        return self._register(inv)
+
+
+class CashuPaymentRail(PaymentRail):
+    """Chaumian ecash settlement rail implementing NIP-61 Nutzap tokens."""
+
+    rail_id: str = 'cashu'
+
+    def __init__(
+        self,
+        mint_url: str = DEFAULT_MINT_URL,
+        mint_privkey_hex: Optional[str] = None,
+        spent: Optional[SpentProofs] = None,
+        proof_verifier: Optional[ProofVerifier] = None,
+        allow_unverified_proofs: bool = False,
+    ) -> None:
+        super().__init__()
+        self.mint_url: str = mint_url
+        self.mint_privkey_hex: Optional[str] = mint_privkey_hex
+        self.mint_pubkey_hex: Optional[str] = None
+        if mint_privkey_hex:
+            mint_point = curve.mul_g(int(mint_privkey_hex, 16))
+            # mul_g returns None only for k == 0 mod N, which is not a usable
+            # signing key; refuse it loudly instead of running keyless.
+            if mint_point is None:
+                raise ValueError('mint private key is zero mod N')
+            self.mint_pubkey_hex = point_to_hex(mint_point)
+        # One ledger of spent secrets, shared by the escrow path and the
+        # grant-expansion path, persistent when the engine hands one in.
+        self.spent: SpentProofs = spent if spent is not None else SpentProofs()
+        # How proofs are vouched for when this node is not the mint. None with
+        # no mint key means every nutzap is refused, which is the safe default;
+        # allow_unverified_proofs is the explicit opt-in for a test rail.
+        self.proof_verifier: Optional[ProofVerifier] = proof_verifier
+        self.allow_unverified_proofs: bool = allow_unverified_proofs
+
+    def is_spent(self, secret: str) -> bool:
+        return self.spent.is_spent(secret)
+
+    def mark_spent(self, secret: str, keyset_id: Optional[str] = None, amount: Optional[int] = None,
+                   now: Optional[int] = None) -> None:
+        self.spent.mark_spent(secret, keyset_id, amount, now)
+
+    def verify_nutzap(self, event: NostrEvent | Mapping[str, Any], expected_recipient: Optional[str] = None) -> tuple[bool, str, int]:
+        """`verify_nutzap_event` under this rail's own proof policy."""
+        return verify_nutzap_event(event, expected_recipient=expected_recipient,
+                                   mint_privkey_hex=self.mint_privkey_hex,
+                                   proof_verifier=self.proof_verifier,
+                                   allow_unverified_proofs=self.allow_unverified_proofs)
+
+    def _accept_proofs(self, proofs: Sequence[CashuProof]) -> tuple[bool, str]:
+        """`accept_proofs` under this rail's own proof policy: the same rule
+        verify_nutzap applies, for proofs that did not arrive in a nutzap."""
+        return accept_proofs(proofs, mint_privkey_hex=self.mint_privkey_hex,
+                             proof_verifier=self.proof_verifier,
+                             allow_unverified_proofs=self.allow_unverified_proofs)
+
+    def can_verify_proofs(self) -> bool:
+        """False when this rail would take any JSON with a `secret` as money."""
+        return bool(self.mint_privkey_hex) or self.proof_verifier is not None or self.allow_unverified_proofs
+
+    def create_hold_invoice(
+        self,
+        amount_msat: int,
+        payment_hash: str,
+        expiry: int = 3600,
+        description: str = 'fleetmesh-nutzap',
+    ) -> HoldInvoice:
+        inv = self._new_invoice(amount_msat, payment_hash, expiry, description)
+        inv.mint = self.mint_url
+        return self._register(inv)
+
+    def _hold_io(self, inv: HoldInvoice, token_or_proof: Any) -> None:
+        """Accept Cashu proofs or a Nutzap event as the money behind inv.
+
+        Whatever the shape - a cashuA token string, a NIP-61 event or a bare
+        proof list - the proofs go through the rail's one proof policy
+        (`_accept_proofs`). The string and list shapes used to skip it, so a
+        rail with no mint key held any JSON with a `secret` as payment.
+        """
+        h = inv.payment_hash
+        proofs: list[CashuProof] = []
+        policy_applied = False
+        if isinstance(token_or_proof, str) and token_or_proof.startswith('cashuA'):
+            try:
+                tok = deserialize_cashu_token(token_or_proof)
+            except (ValueError, TypeError) as e:
+                raise PaymentError(f'escrow {h[:16]}: malformed cashu token: {e}') from e
+            for t in tok.get('token', []):
+                proofs.extend(t.get('proofs', []))
+        elif isinstance(token_or_proof, dict) and token_or_proof.get('kind') == NUTZAP_KIND:
+            # verify_nutzap applies the proof policy to these itself.
+            ok_nut, why, _ = self.verify_nutzap(token_or_proof)
+            if not ok_nut:
+                raise PaymentError(f'escrow {h[:16]}: nutzap refused: {why}')
+            policy_applied = True
+            try:
+                proofs = proofs_of(token_or_proof)
+            except ValueError as e:
+                raise PaymentError(f'escrow {h[:16]}: malformed nutzap proofs: {e}') from e
+        elif isinstance(token_or_proof, list):
+            proofs = list(token_or_proof)
+
+        if not proofs:
+            raise PaymentError(f'escrow {h[:16]}: no proofs offered')
+
+        # Verify not double spent
+        for p in proofs:
+            if not isinstance(p, dict):
+                raise PaymentError(f'escrow {h[:16]}: proof is not an object')
+            sec = p.get('secret')
+            if not isinstance(sec, str) or not sec:
+                raise PaymentError(f'escrow {h[:16]}: proof has no secret')
+            if self.is_spent(sec):
+                raise PaymentError(f'escrow {h[:16]}: proof already spent')
+
+        if not policy_applied:
+            ok_proofs, why = self._accept_proofs(proofs)
+            if not ok_proofs:
+                raise PaymentError(f'escrow {h[:16]}: proofs refused: {why}')
+
+        inv.proofs = proofs
+
+    def _settle_io(self, inv: HoldInvoice, preimage: str) -> None:
+        """Mark the held proofs spent; the escrow then goes SETTLED."""
+        now = int(time.time())
+        for p in inv.proofs:
+            if 'secret' in p:
+                self.mark_spent(p['secret'], p.get('id'), p.get('amount'), now)
+
+
+class MockPaymentRail(PaymentRail):
+    """Deterministic in-memory settlement rail for testing: the base state
+    machine with no I/O at all."""
+
+    rail_id: str = 'mock'

node/planes/services/settle/store.py

@@ -0,0 +1,74 @@
+"""SQLite persistence for settlement: the escrow ledger and the spent-proof
+table, plus the `SpentProofs` that reads through to it so "has this secret
+paid before" survives a restart."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from . import payment
+from node.compartment.schema import Column, Index, Table
+from node.storage import SqliteStore
+
+
+class SettlementStore(SqliteStore):
+    """Thread-safe SQLite storage for settlement escrows and spent proofs."""
+
+    SCHEMA = (
+        Table('escrows', (
+            Column('ask_id', 'TEXT', primary_key=True),
+            Column('buyer', 'TEXT', not_null=True),
+            Column('seller', 'TEXT', not_null=True),
+            Column('amount_msat', 'INTEGER', not_null=True),
+            Column('payment_hash', 'TEXT', not_null=True),
+            Column('preimage', 'TEXT'),
+            Column('status', 'TEXT', not_null=True, default="'CREATED'"),
+            Column('rail', 'TEXT', not_null=True),
+            Column('created_at', 'INTEGER', not_null=True),
+            Column('settled_at', 'INTEGER'),
+        ), indices=(
+            Index('idx_escrows_hash', ('payment_hash',)),
+        )),
+        Table('spent_proofs', (
+            Column('secret', 'TEXT', primary_key=True),
+            Column('keyset_id', 'TEXT'),
+            Column('amount', 'INTEGER'),
+            Column('spent_at', 'INTEGER', not_null=True),
+        )),
+    )
+
+class PersistentSpentProofs(payment.SpentProofs):
+    """`SpentProofs` read through to the settlement store's spent_proofs table.
+
+    Loaded whole on init and written through on every mark, so the answer to
+    "has this secret paid before" survives a restart - which is the only
+    question the table exists to answer, and the one it was never asked.
+    The in-memory set is a cache of the table, not a second source of truth:
+    a miss in the cache still asks the table, so a second engine opened on
+    the same file (or a row written by another process) is honoured.
+    """
+
+    def __init__(self, db: SettlementStore, clock: Any) -> None:
+        super().__init__()
+        self.db = db
+        self.clock = clock
+        for (secret,) in self.db._all('SELECT secret FROM spent_proofs'):
+            self._mem.add(secret)
+
+    def is_spent(self, secret: str) -> bool:
+        if secret in self._mem:
+            return True
+        row = self.db._one('SELECT 1 FROM spent_proofs WHERE secret = ?', (secret,))
+        if row:
+            self._mem.add(secret)
+            return True
+        return False
+
+    def mark_spent(self, secret: str, keyset_id: Optional[str] = None,
+                   amount: Optional[int] = None, now: Optional[int] = None) -> None:
+        self.db.execute('''
+            INSERT OR IGNORE INTO spent_proofs (secret, keyset_id, amount, spent_at)
+            VALUES (?, ?, ?, ?)
+        ''', (secret, keyset_id, amount, now if now is not None else self.clock()))
+        self.db.commit()
+        self._mem.add(secret)
+

node/planes/services/settle/types.py

@@ -0,0 +1,58 @@
+"""Types and records for the Settlement compartment."""
+from __future__ import annotations
+
+from typing import Optional, TypedDict
+
+from fleetmesh_core.accounting.cashu import BlindSignature, CashuProof
+
+
+class HoldInvoiceDict(TypedDict, total=False):
+    """Normalized dictionary representation of a HoldInvoice record."""
+    rail: str
+    payment_hash: str
+    amount_msat: int
+    status: str
+    created_at: int
+    expiry: int
+    description: str
+    preimage: Optional[str]
+    bolt11: Optional[str]
+    mint: Optional[str]
+    invoice: Optional[str]
+    wallet_payment_hash: Optional[str]
+    proofs: list[CashuProof]
+    held_at: Optional[int]
+    settled_at: Optional[int]
+    cancelled_at: Optional[int]
+    cancel_reason: Optional[str]
+    swapped_at: Optional[int]
+    new_signatures: list[BlindSignature]
+
+
+class PaymentRailStats(TypedDict):
+    """Aggregate statistics for an escrow settlement rail."""
+    rail: str
+    escrows: int
+    by_state: dict[str, int]
+    msat_by_state: dict[str, int]
+    refusals: dict[str, int]
+
+
+class EscrowRowDict(TypedDict, total=False):
+    """Row from the escrows database table."""
+    ask_id: str
+    buyer: str
+    seller: str
+    amount_msat: int
+    payment_hash: str
+    preimage: Optional[str]
+    status: str
+    rail: str
+    created_at: int
+    settled_at: Optional[int]
+
+
+class SettleShowDict(TypedDict):
+    """Summary of active settlement rails and current held escrows."""
+    rails: list[str]
+    escrows: list[EscrowRowDict]

node/planes/services/sidecars/__init__.py

@@ -0,0 +1,8 @@
+"""Sidecars: fronting off-the-shelf projects the node does not reimplement.
+
+One-module compartment: everything is in compartment.py.
+"""
+from .compartment import Sidecars
+from . import manifest
+
+__all__ = ['Sidecars', 'manifest']