"""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,
}