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

"""Unified peering capacity, rate-limiting, and Cashu ecash settlement.

Enforces bilateral resource quotas and Cashu NUT-18 / NUT-24 ecash settlement
across all four protocol boundaries:
- Nostr relays & paid filters
- ATProto XRPC & Firehose sync
- ActivityPub S2S federation & media delivery
- Secure Scuttlebutt MuxRPC & Blob sync
"""
from __future__ import annotations

import base64
from dataclasses import dataclass, field
import json
import threading
import time
from typing import Any, Mapping, Optional, Tuple

from fleetmesh_core.accounting import cashu
from fleetmesh_core.conformance.errors import FleetmeshError
from fleetmesh_node.protocols.atproto.metering import TokenBucket


[docs]class GatewaySettlementError(FleetmeshError): """Raised on settlement or quota verification failures."""
[docs]@dataclass class CrossProtocolPeer: """A tracked peer communicating across any supported wire protocol.""" protocol: str peer_id: str bucket: TokenBucket balance_sat: int = 0 total_consumed_tokens: int = 0 total_settled_sat: int = 0 penalty_score: float = 0.0 created_at: int = field(default_factory=lambda: int(time.time()))
[docs]@dataclass class PaymentChallenge: """Standardized payment challenge issued when a peer exceeds quota.""" protocol: str peer_id: str required_sat: int mint_url: Optional[str] # None: the operator set no mint; the challenge says so memo: str
[docs] def to_http_402(self) -> tuple[int, Mapping[str, str], bytes]: """Format as HTTP 402 Payment Required with Cashu challenge header & body.""" headers = { "Content-Type": "application/json", "WWW-Authenticate": (f'Cashu mint="{self.mint_url}", amount={self.required_sat}, unit="sat"' if self.mint_url else f'Cashu amount={self.required_sat}, unit="sat", error="no mint configured"'), } body = json.dumps({ "error": "PaymentRequired", "message": f"Peer quota exceeded on {self.protocol}. Deposit Cashu ecash to continue.", "mint": self.mint_url, "amount_sat": self.required_sat, "unit": "sat", "memo": self.memo, }, indent=2).encode('utf-8') return 402, headers, body
[docs] def to_nostr_notice(self) -> str: """Format as Nostr NOTICE message content.""" return ( f"restricted: quota exceeded. Pay {self.required_sat} sats via Cashu to {self.mint_url or 'a mint the operator has not configured'} " f"with memo '{self.memo}'" )
[docs] def to_muxrpc_error(self) -> str: """Format as SSB MuxRPC error message.""" return ( f"PaymentRequired: quota exceeded for @{self.peer_id}. " f"Deposit {self.required_sat} sats at {self.mint_url or 'a mint the operator has not configured'}" )
[docs]@dataclass class SettlementReceipt: """Proof of completed ecash settlement credit.""" protocol: str peer_id: str credited_sat: int new_balance_sat: int proof_count: int timestamp: int = field(default_factory=lambda: int(time.time()))
[docs]class CrossProtocolSettlementGateway: """Unified resource accounting, rate limiting, and ecash settlement gateway."""
[docs] def __init__( self, default_capacity: float = 30.0, default_refill_per_sec: float = 0.5, price_per_topup_sat: int = 21, tokens_per_topup: int = 100, mint_url: Optional[str] = None, max_penalty_score: float = 10.0, ): self.default_capacity = default_capacity self.default_refill_per_sec = default_refill_per_sec self.price_per_topup_sat = price_per_topup_sat self.tokens_per_topup = tokens_per_topup self.mint_url: Optional[str] = mint_url.rstrip('/') if mint_url else None self.max_penalty_score = max_penalty_score self._peers: dict[tuple[str, str], CrossProtocolPeer] = {} self._spent_secrets: set[str] = set() self._total_challenges_issued = 0 self._total_settled_sat = 0 self._lock = threading.RLock()
def _peer_key(self, protocol: str, peer_id: str) -> tuple[str, str]: return (protocol.lower().strip(), peer_id.strip())
[docs] def get_or_create_peer( self, protocol: str, peer_id: str, capacity: Optional[float] = None, refill_rate: Optional[float] = None, ) -> CrossProtocolPeer: """Fetch or initialize a tracked peer record.""" key = self._peer_key(protocol, peer_id) with self._lock: if key not in self._peers: cap = capacity if capacity is not None else self.default_capacity refill = refill_rate if refill_rate is not None else self.default_refill_per_sec bucket = TokenBucket(capacity=cap, refill_rate=refill) self._peers[key] = CrossProtocolPeer( protocol=key[0], peer_id=key[1], bucket=bucket, ) return self._peers[key]
[docs] def record_penalty(self, protocol: str, peer_id: str, penalty: float = 1.0) -> float: """Increase penalty score for bad behavior (e.g. invalid signatures, flooding).""" with self._lock: peer = self.get_or_create_peer(protocol, peer_id) peer.penalty_score += penalty # Also drain tokens proportional to penalty peer.bucket.tokens = max(0.0, peer.bucket.tokens - penalty * 2.0) return peer.penalty_score
[docs] def check_access( self, protocol: str, peer_id: str, cost: int = 1, ) -> Tuple[bool, Optional[PaymentChallenge]]: """Authorize a request or issue a payment challenge. Returns: (True, None) if permitted under current token bucket or satoshi balance. (False, PaymentChallenge) if dry and requires payment. """ with self._lock: peer = self.get_or_create_peer(protocol, peer_id) # 1. Circuit breaker: excessive penalties reject without immediate topup if peer.penalty_score >= self.max_penalty_score: challenge = PaymentChallenge( protocol=protocol, peer_id=peer_id, required_sat=self.price_per_topup_sat * 5, mint_url=self.mint_url, memo=f"penalty-recovery-{peer_id[:16]}", ) self._total_challenges_issued += 1 return False, challenge # 2. Try consuming from rate-limiter token bucket if peer.bucket.consume(float(cost)): peer.total_consumed_tokens += cost return True, None # 3. If bucket dry, attempt to convert prepaid satoshi balance to tokens if peer.balance_sat >= self.price_per_topup_sat: peer.balance_sat -= self.price_per_topup_sat peer.bucket.tokens += self.tokens_per_topup peer.bucket.consume(float(cost)) peer.total_consumed_tokens += cost return True, None # 4. Quota exceeded: Issue payment challenge self._total_challenges_issued += 1 challenge = PaymentChallenge( protocol=protocol, peer_id=peer_id, required_sat=self.price_per_topup_sat, mint_url=self.mint_url, memo=f"quota-{protocol}-{peer_id[:16]}", ) return False, challenge
[docs] def settle_cashu(self, protocol: str, peer_id: str, token_str: str) -> SettlementReceipt: """Parse, validate, and credit Cashu ecash payment (V3 cashuA or V4 cashuB).""" raw_token = token_str.strip() proofs: list[Mapping[str, Any]] = [] if raw_token.startswith(cashu.TOKEN_V4_PREFIX): try: tok_v4 = cashu.decode_token_v4(raw_token) proofs = list(tok_v4.get('proofs', [])) except Exception as e: raise GatewaySettlementError(f"Invalid Cashu V4 token: {e}") from e elif raw_token.startswith('cashuA'): try: payload = raw_token[6:] # Pad base64 if needed payload += '=' * (-len(payload) % 4) data = json.loads(base64.urlsafe_b64decode(payload).decode('utf-8')) token_entries = data.get('token', []) for entry in token_entries: proofs.extend(entry.get('proofs', [])) except Exception as e: raise GatewaySettlementError(f"Invalid Cashu V3 token: {e}") from e else: raise GatewaySettlementError("Unrecognized Cashu token prefix (expected cashuA or cashuB)") proof_count = len(proofs) sat_amount = sum(int(p.get('amount', 0)) for p in proofs) if sat_amount <= 0 or proof_count == 0: raise GatewaySettlementError("Token contains 0 sats or empty proofs") with self._lock: # Double-spend prevention across tokens for p in proofs: sec = p.get('secret') if sec and sec in self._spent_secrets: raise GatewaySettlementError(f"Double-spend attempt: proof secret already redeemed ({sec})") for p in proofs: sec = p.get('secret') if sec: self._spent_secrets.add(sec) peer = self.get_or_create_peer(protocol, peer_id) # Credit balance peer.balance_sat += sat_amount peer.total_settled_sat += sat_amount self._total_settled_sat += sat_amount # Refill tokens proportional to satoshis granted_tokens = (sat_amount // self.price_per_topup_sat) * self.tokens_per_topup if granted_tokens > 0: peer.bucket.tokens = min(peer.bucket.capacity * 2, peer.bucket.tokens + granted_tokens) # Decay penalty score on successful payment peer.penalty_score = max(0.0, peer.penalty_score - 2.0) return SettlementReceipt( protocol=protocol, peer_id=peer_id, credited_sat=sat_amount, new_balance_sat=peer.balance_sat, proof_count=proof_count, )
[docs] def stats(self) -> Mapping[str, Any]: """Aggregate cross-protocol accounting statistics.""" with self._lock: by_proto: dict[str, int] = {} for (proto, _), _ in self._peers.items(): by_proto[proto] = by_proto.get(proto, 0) + 1 return { "total_peers": len(self._peers), "peers_by_protocol": by_proto, "total_challenges_issued": self._total_challenges_issued, "total_settled_sat": self._total_settled_sat, }