"""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
[docs]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."""
[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,
}