fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/services/paidfetch/compartment.py

@@ -0,0 +1,862 @@
+"""Paid fetch: what a blob costs, who pays nothing, and how a Cashu payment
+is turned into finality before a byte is served.
+
+Three pieces, each replaceable on its own:
+
+* `Pricing` (below) answers "what does this fetch cost?" from operator
+  config, per-item prices in SQLite and the free allowance. It knows
+  nothing about money moving.
+* `MintBackend` is the trust and settlement seam. `AllowlistBackend` is
+  the one shipped: a list of mints the operator chose, tokens accepted
+  only from those, finality by NUT-03 swap at that mint, earnings kept as
+  fresh proofs in SQLite and swept to Lightning by NUT-05 melt above a
+  threshold. A self-hosted nutshell, cdk-mintd or a Fedimint gateway is
+  another `MintBackend`; the 402 and the verify path do not change.
+* `PaidFetch` is the subsystem: it owns both, builds the 402, checks a
+  payment and records every refusal with its reason.
+
+Every amount is msat inside the node. Cashu quotes in sat, so the edge
+rounds up: a 1 msat price costs 1 sat. That is the price of not carrying
+fractions of a sat as debt.
+
+Pricing rules (plan §3.4), first match wins:
+  1. fetcher is a partner or grantee and free_for_partners → 0
+  2. per-item operator price on this blob
+  3. first matching rule: min_bytes / content_type glob / uploader
+  4. default_msat (default 0)
+A free allowance free_bytes_per_day, keyed by the fetcher's key alone
+(anonymous fetches share one pool), is spent before any of these. Unset
+(None) means no free tier.
+"""
+from __future__ import annotations
+
+import fnmatch
+import json
+import math
+import os
+import threading
+import time
+from typing import Any, Callable, Mapping, MutableMapping, Optional, Sequence, cast
+
+from fleetmesh_core.accounting import cashu, paidfetch
+from fleetmesh_core.accounting.cashu import CashuProof
+from node import compartment as compartment_mod, storage
+from node.compartment import stores as st
+from node.channels import Channel, INFO, NOTE
+from node.metrics import COUNTER, Metric
+from node.compartment import Column, Command, Index, Need, Table
+from node.config import FetchPricingConfig
+from node.config.parameter import Parameter
+
+
+from .types import (
+    BalanceReport,
+    MintBackend,
+    Paid,
+    PaidFetchOffer,
+    PriceEntry,
+    PriceGetResult,
+    PriceSetResult,
+    RailDescriptor,
+    StoredProof,
+    SweepReport,
+    Unpaid,
+)
+
+
+DEFAULTS: Mapping[str, Any] = {
+    'default_msat': 0,
+    'free_for_partners': True,
+    'free_bytes_per_day': None,        # None: no free tier
+    'max_account_fee_msat': 0,
+    'rules': [],                       # [{'min_bytes'|'content_type'|'uploader': ..., 'msat'|'msat_per_mb': int}]
+    'rails': {'cashu': {'mints': [], 'unit': 'sat',
+                        'sweep_above_sat': 0,             # 0: never sweep automatically
+                        'sweep_to': None}},               # a Lightning address or bolt11 source
+    'offer_seconds': 600,
+    # GRASP (git smart-http, kinds 30617/30618/1617-1633) cannot be metered per
+    # object by a proxy the way a Blossom GET is: one 402 in front of the
+    # whole clone/fetch session is what is actually enforceable, so it has its
+    # own fixed price rather than reusing the per-blob `rules`/`default_msat`.
+    # ncontainer needs no entry here: it resolves a tag to a sha256 digest and
+    # every blob it serves is already priced (or free) exactly as any other
+    # Blossom fetch, through the same `rules`/`default_msat`/per-item path.
+    'grasp_session_msat': 0,
+    # Any other sidecar whose manifest says pricing.mode == session, by name
+    # (grasp may be given here too; grasp_session_msat is the older spelling
+    # and wins when both are set).
+    'sidecar_session_msat': {},
+}
+
+ANON = ''          # the pooled anonymous fetcher
+
+
+# The 402 shape - Quote, Item, msat_to_sat_ceil - is fleetmesh_core/paidfetch.py's,
+# pinned by vectors/paid-fetch.json.
+msat_to_sat_ceil = paidfetch.msat_to_sat_ceil
+Item = paidfetch.Item
+Quote = paidfetch.Quote
+
+
+
+
+class ProofStore(storage.SqliteStore):
+    """The node's own Cashu proofs (its earnings) and every proof it has taken
+    in payment, by Y, so a token replayed after the swap is refused without a
+    round trip to the mint."""
+
+    SCHEMA = (
+        Table('cashu_proofs', (
+            Column('y', 'TEXT', primary_key=True),
+            Column('mint', 'TEXT', not_null=True),
+            Column('unit', 'TEXT', not_null=True),
+            Column('keyset', 'TEXT', not_null=True),
+            Column('amount', 'INTEGER', not_null=True),
+            Column('secret', 'TEXT', not_null=True),
+            Column('c', 'TEXT', not_null=True),
+            Column('state', 'TEXT', not_null=True),
+            Column('received_at', 'INTEGER', not_null=True),
+            Column('spent_at', 'INTEGER'),
+        ), indices=(
+            Index('idx_cashu_proofs_state', ('mint', 'state')),
+        )),
+        Table('cashu_taken', (
+            Column('y', 'TEXT', primary_key=True),
+            Column('mint', 'TEXT', not_null=True),
+            Column('sha256', 'TEXT'),
+            Column('taken_at', 'INTEGER', not_null=True),
+        )),
+        Table('account_proofs', (
+            Column('y', 'TEXT', primary_key=True),
+            Column('account', 'TEXT', not_null=True),
+            Column('mint', 'TEXT', not_null=True),
+            Column('proof_json', 'TEXT', not_null=True),
+            Column('at', 'INTEGER', not_null=True),
+        ), indices=(
+            Index('idx_account_proofs_account', ('account',)),
+        )),
+    )
+
+    def seen(self, ys: Sequence[str]) -> set[str]:
+        if not ys:
+            return set()
+        q = 'SELECT y FROM cashu_taken WHERE y IN (%s)' % ','.join('?' * len(ys))
+        return {r[0] for r in self._all(q, list(ys))}
+
+    def take(self, ys: Sequence[str], mint: str, sha256: Optional[str], now: int) -> None:
+        with self.transaction() as cur:
+            cur.executemany('INSERT OR IGNORE INTO cashu_taken(y, mint, sha256, taken_at) VALUES (?,?,?,?)',
+                            [(y, mint, sha256, now) for y in ys])
+
+    def add_proofs(self, mint: str, unit: str, proofs: Sequence[CashuProof], now: int) -> None:
+        with self.transaction() as cur:
+            cur.executemany(
+                'INSERT OR REPLACE INTO cashu_proofs(y, mint, unit, keyset, amount, secret, c, state, received_at) '
+                'VALUES (?,?,?,?,?,?,?,?,?)',
+                [(cashu.point_to_hex(cashu.hash_to_curve(p['secret'])), mint, unit, p['id'], int(p['amount']),
+                  p['secret'], p['C'], 'unspent', now) for p in proofs])
+
+    def unspent(self, mint: Optional[str] = None) -> list[StoredProof]:
+        q = 'SELECT y, mint, unit, keyset, amount, secret, c FROM cashu_proofs WHERE state=\'unspent\''
+        args: list[Any] = []
+        if mint:
+            q += ' AND mint=?'
+            args.append(mint)
+        return [{'y': r[0], 'mint': r[1], 'unit': r[2], 'id': r[3], 'amount': r[4], 'secret': r[5], 'C': r[6]}
+                for r in self._all(q + ' ORDER BY received_at', args)]
+
+    def mark_spent(self, ys: Sequence[str], now: int) -> None:
+        with self.transaction() as cur:
+            cur.executemany('UPDATE cashu_proofs SET state=\'spent\', spent_at=? WHERE y=?', [(now, y) for y in ys])
+
+    def balances(self) -> dict[str, int]:
+        return {r[0]: int(r[1]) for r in
+                self._all('SELECT mint, COALESCE(SUM(amount),0) FROM cashu_proofs WHERE state=\'unspent\' GROUP BY mint')}
+
+    # -- proofs paid direct to an account (P2PK-locked; this node cannot spend them) --
+    def add_account_proofs(self, account: str, mint: str, proofs: Sequence[CashuProof], now: int) -> None:
+        """Keep the account's locked proofs so it can collect them later; the
+        node is only the custodian of the ciphertext, never of the value."""
+        with self.transaction() as cur:
+            cur.executemany(
+                'INSERT OR IGNORE INTO account_proofs(y, account, mint, proof_json, at) VALUES (?,?,?,?,?)',
+                [(cashu.point_to_hex(cashu.hash_to_curve(p['secret'])), account.lower(), mint,
+                  json.dumps(dict(p), sort_keys=True, separators=(',', ':')), now) for p in proofs])
+
+    def account_proofs(self, account: str) -> list[StoredProof]:
+        return [cast(StoredProof, dict(json.loads(r[0]), mint=r[1])) for r in
+                self._all('SELECT proof_json, mint FROM account_proofs WHERE account=? ORDER BY at', (account.lower(),))]
+
+    def account_proof_count(self) -> int:
+        r = self._one('SELECT COUNT(*) FROM account_proofs')
+        return int(r[0]) if r else 0
+
+
+def powers_of_two(total: int) -> list[int]:
+    if total < 0:
+        raise ValueError('negative amount: %d' % total)
+    out, bit = [], 1
+    while total:
+        if total & bit:
+            out.append(bit)
+        total &= ~bit
+        bit <<= 1
+    return out
+
+
+class AllowlistBackend:
+    """Plan §3.5 option (a): mints the operator chose, and nobody else's IOUs.
+
+    verify() is the security boundary of the whole feature. It accepts a
+    token only when: the mint is on the list, the unit matches, the amount
+    covers the item, no proof was taken before, and the mint swaps the
+    proofs for fresh ones this node blinded. After the swap the payer's
+    proofs are dead at the mint and the node's are live: that is finality.
+    A mint that is down is an Unpaid('mint unreachable'), never a pass.
+    """
+
+    rail = 'cashu'
+
+    def __init__(self, rail_cfg: Callable[[], Mapping[str, Any]], store: ProofStore, node_pk: Optional[str] = None,
+                 client_factory: Optional[Callable[[str], Any]] = None,
+                 clock: Optional[Callable[[], int]] = None) -> None:
+        # rail_cfg is read on every use: fetch_pricing is a live key, so an
+        # operator can add a mint without restarting the node.
+        self._rail_cfg = rail_cfg
+        self.store = store
+        self.node_pk = node_pk
+        self.clock = clock or (lambda: int(time.time()))
+        if client_factory is None:
+            from node.planes.services.settle.gateways import CashuHttpClient
+            client_factory = lambda url: CashuHttpClient(mint_url=url)  # noqa: E731
+        self._factory = client_factory
+        self._clients: MutableMapping[str, Any] = {}
+        self._keysets: dict[str, tuple[int, Mapping[str, Any]]] = {}   # mint -> (fetched_at, keyset)
+        self._lock = threading.Lock()
+
+    # -- wiring -------------------------------------------------------------
+    @property
+    def mints(self) -> list[str]:
+        raw = self._rail_cfg().get('mints') or []
+        return [cashu.normalize_mint_url(m) for m in raw if isinstance(m, str) and m.strip()]
+
+    @property
+    def unit(self) -> str:
+        return str(self._rail_cfg().get('unit') or 'sat')
+
+    @property
+    def sweep_above_sat(self) -> int:
+        return int(self._rail_cfg().get('sweep_above_sat') or 0)
+
+    @property
+    def sweep_to(self) -> Optional[str]:
+        v = self._rail_cfg().get('sweep_to')
+        return str(v) if v else None
+
+    def client(self, mint: str) -> Any:
+        with self._lock:
+            c = self._clients.get(mint)
+            if c is None:
+                c = self._clients[mint] = self._factory(mint)
+            return c
+
+    def active_keyset(self, mint: str) -> Mapping[str, Any]:
+        now = self.clock()
+        with self._lock:
+            cached = self._keysets.get(mint)
+        if cached and now - cached[0] < 3600:
+            return cached[1]
+        keysets = self.client(mint).get_keys().get('keysets', [])
+        ks = [k for k in keysets if k.get('unit') == self.unit and k.get('keys')]
+        if not ks:
+            raise ValueError('mint %s has no %s keyset' % (mint, self.unit))
+        with self._lock:
+            self._keysets[mint] = (now, ks[0])
+        return ks[0]
+
+    # -- MintBackend --------------------------------------------------------
+    def offer(self, item: Item, quote_id: str, expires: int) -> Optional[PaidFetchOffer]:
+        if not self.mints or item.msat <= 0:
+            return None
+        lock = cashu.x_only_to_compressed(item.payee) if item.to == 'account' else None
+        req = cashu.encode_payment_request(msat_to_sat_ceil(item.msat), self.unit, self.mints,
+                                           payment_id=quote_id, description='fleetmesh fetch', p2pk_pubkey=lock)
+        return {'rail': self.rail, 'request': req}
+
+    def verify(self, item: Item, token: str) -> Paid | Unpaid:
+        try:
+            tok = cashu.decode_token_v4(token)
+        except ValueError as e:
+            return Unpaid('bad token', str(e))
+        if tok['mint'] not in self.mints:
+            return Unpaid('mint not accepted', tok['mint'])
+        if tok['unit'] != self.unit:
+            return Unpaid('wrong unit', tok['unit'])
+        need = msat_to_sat_ceil(item.msat)
+        got = cashu.token_amount(tok)
+        if got < need:
+            return Unpaid('short payment', '%d < %d %s' % (got, need, self.unit))
+        proofs = tok['proofs']
+        ys = [cashu.point_to_hex(cashu.hash_to_curve(p['secret'])) for p in proofs]
+        if item.to == 'account':
+            # Account fees are paid direct: the proofs must be locked to the
+            # account key, so this node could not spend them even if it
+            # wanted to. Nothing to swap; the account collects. There is no
+            # mint round trip to kill a replay, so the Y record is the only
+            # thing standing between one token and unlimited fetches.
+            want = item.payee.lower()
+            if any(cashu.p2pk_locked_to(p['secret']) != want for p in proofs):
+                return Unpaid('not locked to account')
+            if self.store.seen(ys):
+                return Unpaid('proof replayed')
+            now = self.clock()
+            self.store.take(ys, tok['mint'], None, now)
+            self.store.add_account_proofs(want, tok['mint'], proofs, now)
+            return Paid(self.rail, got * 1000, {'mint': tok['mint'], 'locked_to': want, 'proofs': proofs})
+        if any(cashu.p2pk_locked_to(p['secret']) for p in proofs):
+            return Unpaid('locked proofs offered to operator')
+        if self.store.seen(ys):
+            return Unpaid('proof replayed')
+        try:
+            ks = self.active_keyset(tok['mint'])
+            # NUT-02 input fees: the mint keeps ceil(n * fee_ppk / 1000) sat of
+            # the inputs, so the outputs must ask for that much less or the
+            # swap is refused. The fetcher paid the price; the fee is the
+            # operator's cost of using that mint.
+            fee = math.ceil(len(proofs) * int(ks.get('input_fee_ppk') or 0) / 1000)
+        except Exception as e:
+            return Unpaid('swap refused', str(e)[:200])
+        if fee >= got:
+            return Unpaid('fee exceeds payment', '%d sat over %d input(s) costs %d sat at %s' % (got, len(proofs), fee, tok['mint']))
+        try:
+            outs, blinds = [], []
+            for amt in powers_of_two(got - fee):
+                secret = os.urandom(32).hex()
+                b_prime, r = cashu.blind_message(secret)
+                outs.append({'amount': amt, 'id': ks['id'], 'B_': b_prime})
+                blinds.append((secret, r, amt))
+            swapped = self.client(tok['mint']).swap_tokens(proofs, outs)
+        except Exception as e:  # CashuMintError, ValueError, socket errors: all "no finality"
+            return Unpaid('swap refused', str(e)[:200])
+        sigs = swapped.get('signatures') or []
+        if len(sigs) != len(outs):
+            return Unpaid('swap refused', 'mint returned %d signatures for %d outputs' % (len(sigs), len(outs)))
+        now = self.clock()
+        fresh: list[CashuProof] = []
+        for sig, (secret, r, amt) in zip(sigs, blinds):
+            c_hex = cashu.unblind_signature(sig['C_'], r, ks['keys'][str(amt)])
+            fresh.append({'amount': amt, 'id': ks['id'], 'secret': secret, 'C': c_hex})
+        self.store.take(ys, tok['mint'], None, now)
+        self.store.add_proofs(tok['mint'], self.unit, fresh, now)
+        # amount_msat is what the node keeps: the mint's fee is gone.
+        return Paid(self.rail, (got - fee) * 1000, {'mint': tok['mint'], 'swapped': len(fresh), 'fee_sat': fee})
+
+    def balance(self) -> BalanceReport:
+        return {'unit': self.unit, 'by_mint': self.store.balances(),
+                'total': sum(self.store.balances().values())}
+
+    def sweep(self, now: int, force: bool = False) -> Optional[SweepReport]:
+        """NUT-05 melt of everything unspent at a mint into a Lightning
+        payment to sweep_to. Needs a bolt11: sweep_to may be an invoice or a
+        callable/URL that produces one, which is the next piece to build; for
+        now a sweep with no bolt11 source reports that and does nothing."""
+        total = sum(self.store.balances().values())
+        if not force and (self.sweep_above_sat <= 0 or total < self.sweep_above_sat):
+            return None
+        if not self.sweep_to:
+            return {'swept': 0, 'why': 'no sweep_to configured', 'balance': total}
+        return {'swept': 0, 'why': 'lightning melt not wired yet', 'balance': total}
+
+    def describe(self) -> RailDescriptor:
+        return {'rail': self.rail, 'mints': list(self.mints), 'unit': self.unit,
+                'sweep_above_sat': self.sweep_above_sat, 'trust': 'allowlist'}
+
+
+# ---------------------------------------------------------------------------
+# Pricing
+# ---------------------------------------------------------------------------
+
+class PriceStore(storage.SqliteStore):
+    """blob_prices(sha256, account, msat, set_by, at) and the daily allowance counters."""
+
+    SCHEMA = (
+        Table('blob_prices', (
+            Column('sha256', 'TEXT', not_null=True),
+            Column('account', 'TEXT', not_null=True, default="''"),
+            Column('msat', 'INTEGER', not_null=True),
+            Column('set_by', 'TEXT'),
+            Column('at', 'INTEGER', not_null=True),
+        ), primary_key=('sha256', 'account')),
+        Table('fetch_allowance', (
+            Column('fetcher', 'TEXT', not_null=True),
+            Column('day', 'INTEGER', not_null=True),
+            Column('bytes', 'INTEGER', not_null=True),
+        ), primary_key=('fetcher', 'day')),
+    )
+
+    def price(self, sha256: str, account: str = '') -> Optional[int]:
+        r = self._one('SELECT msat FROM blob_prices WHERE sha256=? AND account=?', (sha256.lower(), account))
+        return int(r[0]) if r else None
+
+    def set_price(self, sha256: str, msat: int, set_by: Optional[str], now: int, account: str = '') -> None:
+        with self.transaction() as cur:
+            cur.execute('INSERT OR REPLACE INTO blob_prices(sha256, account, msat, set_by, at) VALUES (?,?,?,?,?)',
+                        (sha256.lower(), account, int(msat), set_by, now))
+
+    def clear_price(self, sha256: str, account: str = '') -> bool:
+        with self.transaction() as cur:
+            cur.execute('DELETE FROM blob_prices WHERE sha256=? AND account=?', (sha256.lower(), account))
+            return cur.rowcount > 0
+
+    def list_prices(self, limit: int = 100) -> list[PriceEntry]:
+        return [{'sha256': r[0], 'account': r[1], 'msat': r[2], 'set_by': r[3], 'at': r[4]} for r in
+                self._all('SELECT sha256, account, msat, set_by, at FROM blob_prices ORDER BY at DESC LIMIT ?', (limit,))]
+
+    def used_today(self, fetcher: str, day: int) -> int:
+        r = self._one('SELECT bytes FROM fetch_allowance WHERE fetcher=? AND day=?', (fetcher, day))
+        return int(r[0]) if r else 0
+
+    def spend_allowance(self, fetcher: str, day: int, size: int) -> None:
+        with self.transaction() as cur:
+            cur.execute('INSERT INTO fetch_allowance(fetcher, day, bytes) VALUES (?,?,?) '
+                        'ON CONFLICT(fetcher, day) DO UPDATE SET bytes = bytes + excluded.bytes', (fetcher, day, size))
+            cur.execute('DELETE FROM fetch_allowance WHERE day < ?', (day - 2,))
+
+
+def _rule_matches(rule: Mapping[str, Any], size: int, ctype: str, uploader: Optional[str]) -> bool:
+    if 'min_bytes' in rule and size < int(rule['min_bytes']):
+        return False
+    if 'max_bytes' in rule and size > int(rule['max_bytes']):
+        return False
+    if 'content_type' in rule and not fnmatch.fnmatch(ctype or '', str(rule['content_type'])):
+        return False
+    if 'uploader' in rule and (uploader or '').lower() != str(rule['uploader']).lower():
+        return False
+    return True
+
+
+def rule_price(rule: Mapping[str, Any], size: int) -> int:
+    if 'msat_per_mb' in rule:
+        return int(math.ceil(size / (1024 * 1024)) * int(rule['msat_per_mb']))
+    return int(rule.get('msat', 0))
+
+
+class Pricing:
+    """§3.4 as a function of (blob stat, fetcher, account)."""
+
+    def __init__(self, cfg: Callable[[], Mapping[str, Any]], prices: PriceStore,
+                 partners: Callable[[], Sequence[str]], clock: Callable[[], int]) -> None:
+        self._cfg = cfg
+        self.prices = prices
+        self.partners = partners
+        self.clock = clock
+
+    def cfg(self) -> Mapping[str, Any]:
+        out = json.loads(json.dumps(DEFAULTS))
+        raw = self._cfg().get('fetch_pricing') or {}
+        for k, v in raw.items():
+            if k == 'rails' and isinstance(v, dict):
+                for rail, rcfg in v.items():
+                    out['rails'].setdefault(rail, {}).update(rcfg or {})
+            else:
+                out[k] = v
+        return out
+
+    def operator_msat(self, stat: Mapping[str, Any], fetcher: Optional[str]) -> int:
+        cfg = self.cfg()
+        if fetcher and cfg.get('free_for_partners', True) and fetcher in set(self.partners()):
+            return 0
+        sha = stat['sha256']
+        per_item = self.prices.price(sha)
+        if per_item is not None:
+            return per_item
+        size, ctype, uploader = int(stat.get('size', 0)), str(stat.get('type') or ''), stat.get('uploaded_by')
+        for rule in cfg.get('rules') or []:
+            if isinstance(rule, Mapping) and _rule_matches(rule, size, ctype, uploader):
+                return rule_price(rule, size)
+        return int(cfg.get('default_msat') or 0)
+
+    def account_msat(self, stat: Mapping[str, Any], account: Optional[str]) -> int:
+        """The fee an account put on its own upload, capped by the operator.
+        Bound to (account, sha256), and only when the fetch names the account."""
+        if not account:
+            return 0
+        cap = int(self.cfg().get('max_account_fee_msat') or 0)
+        if cap <= 0:
+            return 0
+        if (stat.get('uploaded_by') or '').lower() != account.lower():
+            return 0
+        fee = self.prices.price(stat['sha256'], account.lower())
+        return min(int(fee or 0), cap)
+
+    def allowance_covers(self, fetcher: Optional[str], size: int) -> bool:
+        """True when this fetch fits inside the fetcher's free bytes for today.
+        None (the default) means there is no free tier, not an unlimited one:
+        the operator's prices then apply from the first byte."""
+        limit = self.cfg().get('free_bytes_per_day')
+        if limit is None:
+            return False
+        day = self.clock() // 86400
+        return self.prices.used_today(fetcher or ANON, day) + size <= int(limit)
+
+    def spend_allowance(self, fetcher: Optional[str], size: int) -> None:
+        if self.cfg().get('free_bytes_per_day') is None:
+            return
+        self.prices.spend_allowance(fetcher or ANON, self.clock() // 86400, size)
+
+
+# ---------------------------------------------------------------------------
+# The subsystem
+# ---------------------------------------------------------------------------
+
+class PaidFetch(compartment_mod.Compartment):
+    """Prices fetches, issues 402s, verifies payment. Consulted by BlossomServer."""
+
+    name = 'paidfetch'
+    attr = 'paid_fetch'
+    PRICES_DB: str = 'fetch_prices.sqlite'
+    reads = ('fetch_pricing',)
+    live = ('fetch_pricing',)
+    config_cls = FetchPricingConfig
+    SCHEMA = PriceStore.SCHEMA
+    STORE_CLS = PriceStore     # builds its own; the base opens nothing for it (B5)
+    STORES = (
+        st.Store(key='receipts', description='recent fetch payment receipts',
+                 kind=st.RING, shape=dict, bound=1024),
+    )
+    CHANNELS = (
+        Channel('fetch_paid', 'Blob fetch payment verified and settled', level=INFO, say='fetch payment settled for {sha256} ({amount_msat} msat)', tags=('paidfetch', 'settle')),
+        Channel('payment_refused', 'Blob fetch payment refused', level=NOTE, say='fetch payment refused: {reason}', tags=('paidfetch', 'payment')),
+    )
+    METRICS = (
+        Metric(name='paidfetch_fetches_paid', description='Times fetches were paid.', kind=COUNTER, counts='fetch_paid', tags=('paidfetch', 'settle')),
+        Metric(name='paidfetch_payments_refused', description='Times fetch payments were refused.', kind=COUNTER, counts='payment_refused', tags=('paidfetch', 'payment')),
+    )
+    EVERY = (
+        compartment_mod.Every(seconds=60, run='sweep_tick', name='sweep'),
+    )
+    NEEDS = (
+        Need('cfg', 'cfg', getter=True),
+        Need('db_path', path='PRICES_DB'),
+        Need('grant_store', 'stores.grants'),
+        Need('node_pk', 'pubkey'),
+        Need('persist_cfg'),
+        Need('face'),
+    )
+    COMMANDS = (
+        Command(
+            key='price_set',
+            name='Set Price',
+            description='price one blob for fetching (account: a fee that account adds to its own upload)',
+            tags=('paidfetch', 'price'),
+            parameters=(
+                Parameter(key='sha256', name='sha256', description='hex digest of blob to price', type=str, default='', required=True),
+                Parameter(key='msat', name='msat', description='price in millisatoshis', type=int, default=0, required=True),
+                Parameter(key='account', name='account', description='a fee that account adds to its own upload', type=str, default=None, required=False),
+            ),
+            permission='paidfetch/price_set',
+            run='price_set_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='price_get',
+            name='Get Price',
+            description='what one blob costs by rule and by item',
+            tags=('paidfetch', 'price'),
+            parameters=(
+                Parameter(key='sha256', name='sha256', description='hex digest of blob', type=str, default='', required=True),
+            ),
+            permission='paidfetch/price_get',
+            run='price_get_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='price_clear',
+            name='Clear Price',
+            description='remove a per-item price',
+            tags=('paidfetch', 'price'),
+            parameters=(
+                Parameter(key='sha256', name='sha256', description='hex digest of blob', type=str, default='', required=True),
+                Parameter(key='account', name='account', description='account override to clear', type=str, default=None, required=False),
+            ),
+            permission='paidfetch/price_clear',
+            run='price_clear_cmd',
+            reply='bool',
+        ),
+        Command(
+            key='prices',
+            name='List Prices',
+            description='every per-item price set on this node',
+            tags=('paidfetch', 'prices'),
+            permission='paidfetch/prices',
+            run='prices_cmd',
+            reply='list',
+        ),
+        Command(
+            key='rails',
+            name='Payment Rails',
+            description='the payment rails this node offers in a 402',
+            tags=('paidfetch', 'rails'),
+            permission='paidfetch/rails',
+            run='rails_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='wallet',
+            name='Wallet Balance',
+            description="this node's earnings held as ecash, by mint",
+            tags=('paidfetch', 'wallet'),
+            permission='paidfetch/wallet',
+            run='wallet_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='sweep',
+            name='Sweep Wallet',
+            description='move earnings above the threshold out to Lightning now',
+            tags=('paidfetch', 'sweep'),
+            permission='paidfetch/sweep',
+            run='sweep_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='grasp_price_set',
+            name='Set GRASP Price',
+            description='flat price for one GRASP git clone/fetch session (0: free)',
+            tags=('paidfetch', 'grasp'),
+            parameters=(
+                Parameter(key='msat', name='msat', description='session price in millisatoshis', type=int, default=0, required=True),
+            ),
+            permission='paidfetch/grasp_price_set',
+            run='grasp_price_set_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='grasp_price_get',
+            name='Get GRASP Price',
+            description='the current GRASP session price',
+            tags=('paidfetch', 'grasp'),
+            permission='paidfetch/grasp_price_get',
+            run='grasp_price_get_cmd',
+            reply='dict',
+        ),
+    )
+
+    def start(self) -> None:
+        blossom = getattr(self.face, 'blossom', None)
+        if blossom is not None:
+            blossom.pricing = self
+
+    def __init__(self, cfg: Callable[[], Mapping[str, Any]], db_path: str = ':memory:',
+                 partners: Optional[Callable[[], Sequence[str]]] = None, node_pk: Optional[str] = None,
+                 backend: Optional[MintBackend] = None, clock: Optional[Callable[[], int]] = None,
+                 node: Any = None, client_factory: Optional[Callable[[str], Any]] = None,
+                 persist_cfg: Optional[Callable[[], None]] = None,
+                 grant_store: Optional[Any] = None,
+                 face: Optional[Any] = None) -> None:
+        super().__init__(node, clock)
+        self.node_pk = node_pk
+        self.face = face
+        self.prices = PriceStore(db_path)
+        self.db = self.prices
+        if partners is not None:
+            partners_fn = partners
+        elif grant_store is not None:
+            partners_fn = lambda: grant_store.peers()
+        else:
+            partners_fn = lambda: []
+        self.pricing = Pricing(cfg, self.prices, partners_fn, self.clock)
+        if backend is None:
+            proofs_path = ':memory:' if db_path == ':memory:' else os.path.join(os.path.dirname(db_path), 'cashu_wallet.sqlite')
+            backend = AllowlistBackend(lambda: self.pricing.cfg()['rails'].get('cashu') or {}, ProofStore(proofs_path),
+                                       node_pk=node_pk, client_factory=client_factory, clock=self.clock)
+        self.backend: MintBackend = backend
+        self._quotes = 0
+        self._closed = False
+        # Writes a changed price back to the node's config file; a no-op for
+        # a compartment built without a node directory (tests, offline tools).
+        self.persist_cfg: Callable[[], None] = persist_cfg or (lambda: None)
+
+    # -- what Blossom asks ---------------------------------------------------
+    def quote(self, stat: Mapping[str, Any], fetcher: Optional[str], account: Optional[str]) -> Optional[Quote]:
+        """None when the fetch is free (no 402, no headers). Otherwise the
+        itemised price with one offer per item from the backend."""
+        size = int(stat.get('size', 0))
+        op = self.pricing.operator_msat(stat, fetcher)
+        acct = self.pricing.account_msat(stat, account)
+        if op + acct == 0:
+            return None
+        if self.pricing.allowance_covers(fetcher, size):
+            return None
+        items: list[Item] = []
+        if op > 0:
+            items.append(Item('operator', self.node_pk or '', op))
+        if acct > 0 and account:
+            items.append(Item('account', account.lower(), acct))
+        now = self.clock()
+        expires = now + int(self.pricing.cfg().get('offer_seconds') or 600)
+        self._quotes += 1
+        q = Quote(stat['sha256'], size, items, expires)
+        for idx, item in enumerate(items):
+            off = self.backend.offer(item, '%s:%d' % (stat['sha256'][:16], idx), expires)
+            if off:
+                q.offers.append(dict(off, item=idx))
+        return q
+
+    def session_msat(self, name: str) -> int:
+        """The flat per-session price for sidecar `name` (0: free).
+        `grasp_session_msat` is the older spelling for grasp and wins."""
+        cfg = self.pricing.cfg()
+        if name == 'grasp' and cfg.get('grasp_session_msat'):
+            return int(cfg['grasp_session_msat'])
+        table = cfg.get('sidecar_session_msat') or {}
+        return int(table.get(name) or 0) if isinstance(table, Mapping) else 0
+
+    def quote_session(self, subject: str, fetcher: Optional[str]) -> Optional[Quote]:
+        """A sidecar session (a GRASP git clone/fetch is the model), priced
+        as one flat operator item - the proxy in front of a many-request
+        protocol cannot meter individual objects, so the whole session is
+        the billable unit. `subject` is `<sidecar name>:<stable string>`
+        (repo pubkey and identifier is typical for git); the name picks the
+        price (session_msat), the whole string stands in for a blob's
+        sha256 in the 402 and in settle(). It is never hashed or validated
+        here, only quoted against and carried through to the backend.
+        """
+        name = subject.split(':', 1)[0]
+        op = 0 if (fetcher and self.pricing.cfg().get('free_for_partners', True)
+                   and fetcher in set(self.pricing.partners())) else self.session_msat(name)
+        if op == 0:
+            return None
+        now = self.clock()
+        expires = now + int(self.pricing.cfg().get('offer_seconds') or 600)
+        self._quotes += 1
+        item = Item('operator', self.node_pk or '', op)
+        q = Quote(subject, 0, [item], expires)
+        off = self.backend.offer(item, '%s:0' % subject[:16], expires)
+        if off:
+            q.offers.append(dict(off, item=0))
+        return q
+
+    def settle(self, quote: Quote, tokens: Sequence[str]) -> Paid | Unpaid:
+        """One token per item, in item order. Every item must verify; the
+        first failure is the answer and nothing later is touched. An operator
+        item that swapped before a later item fails stays swapped: the node
+        was paid for it, and a refusal is recorded so the operator can see it."""
+        if len(tokens) < len(quote.items):
+            short = Unpaid('missing payment', '%d token(s) for %d item(s)' % (len(tokens), len(quote.items)))
+            self.refusals.refuse('payment', short.reason, subject=quote.sha256, detail={'why': short.detail})
+            return short
+        if not quote.offers:
+            norail = Unpaid('no rail', 'this node lists no mint to pay')
+            self.refusals.refuse('payment', norail.reason, subject=quote.sha256, detail={'why': norail.detail})
+            return norail
+        total = 0
+        for item, tok in zip(quote.items, tokens):
+            res = self.backend.verify(item, tok)
+            if isinstance(res, Unpaid):
+                self.refusals.refuse('payment', res.reason, subject=quote.sha256, detail={'why': res.detail, 'to': item.to})
+                return res
+            total += res.amount_msat
+        return Paid('cashu', total, {'items': len(quote.items)})
+
+    def note_served(self, fetcher: Optional[str], size: int) -> None:
+        self.pricing.spend_allowance(fetcher, size)
+
+    # -- Compartment ------------------------------------------------------------
+    def sweep_tick(self, now: int) -> list[tuple[Any, ...]]:
+        try:
+            r = self.backend.sweep(now)
+        except Exception as e:
+            self.refusals.refuse('sweep', 'failed', detail={'why': str(e)[:200]})
+            return []
+        return [('sweep', r)] if r else []
+
+    _tick_runs_every = True
+
+    def tick(self, now: int) -> list[tuple[Any, ...]]:
+        return self.sweep_tick(now)
+
+    def state(self) -> Mapping[str, Any]:
+        cfg = self.pricing.cfg()
+        if self._closed:
+            # health() is read after stop(); report the config and counters, not the stores.
+            return {'stopped': True, 'default_msat': cfg['default_msat'], 'rules': len(cfg.get('rules') or []),
+                    'quotes': self._quotes}
+        store = getattr(self.backend, 'store', None)
+        return {'default_msat': cfg['default_msat'], 'rules': len(cfg.get('rules') or []),
+                'per_item_prices': len(self.prices.list_prices(10000)), 'quotes': self._quotes,
+                'rail': self.backend.describe(), 'wallet': self.backend.balance(),
+                'account_proofs': store.account_proof_count() if isinstance(store, ProofStore) else 0}
+
+    def trouble(self) -> list[str]:
+        cfg = self.pricing.cfg()
+        priced = cfg['default_msat'] or cfg.get('rules') or self.prices.list_prices(1)
+        if priced and not (cfg['rails'].get('cashu') or {}).get('mints'):
+            return [self.trouble_with(
+                'fetches are priced but fetch_pricing.rails.cashu.mints is empty: every priced fetch is refused with nothing to pay',
+                code='no_mints',
+                severity='trouble',
+                hint='configure mints under fetch_pricing.rails.cashu.mints or set default_msat to 0',
+            )]
+        return []
+
+
+    def descriptor_tags(self) -> list[list[str]]:
+        """What the kind 11801 says: the mints this node takes and that it prices fetches."""
+        d = self.backend.describe()
+        tags = [['mint', m] for m in d.get('mints', [])]
+        cfg = self.pricing.cfg()
+        if cfg['default_msat'] or cfg.get('rules') or self.prices.list_prices(1):
+            tags.append(['price', 'fetch', str(int(cfg['default_msat'] or 0)), 'msat'])
+        names = ['grasp'] + sorted(n for n in (cfg.get('sidecar_session_msat') or {}) if n != 'grasp')
+        for n in names:
+            msat = self.session_msat(n)
+            if msat:
+                tags.append(['price', '%s-session' % n, str(msat), 'msat'])
+        return tags
+
+    def price_set_cmd(self, args: Mapping[str, Any]) -> PriceSetResult:
+        now = self.clock()
+        acct = str(args.get('account') or '').lower()
+        self.prices.set_price(str(args['sha256']), int(args['msat']), self.node_pk, now, account=acct)
+        return {'sha256': str(args['sha256']).lower(), 'account': acct, 'msat': int(args['msat'])}
+
+    def price_get_cmd(self, args: Mapping[str, Any]) -> PriceGetResult:
+        sha = str(args['sha256']).lower()
+        return {'sha256': sha, 'per_item_msat': self.prices.price(sha),
+                'default_msat': self.pricing.cfg()['default_msat']}
+
+    def price_clear_cmd(self, args: Mapping[str, Any]) -> bool:
+        return self.prices.clear_price(str(args['sha256']), str(args.get('account') or '').lower())
+
+    def prices_cmd(self) -> list[PriceEntry]:
+        return self.prices.list_prices()
+
+    def rails_cmd(self) -> Mapping[str, Any]:
+        return {'cashu': self.backend.describe()}
+
+    def wallet_cmd(self) -> Mapping[str, Any]:
+        return self.backend.balance()
+
+    def sweep_cmd(self) -> Mapping[str, Any]:
+        now = self.clock()
+        return self.backend.sweep(now, force=True) or {'swept': 0, 'why': 'nothing to sweep'}
+
+    def grasp_price_set_cmd(self, args: Mapping[str, Any]) -> dict[str, int]:
+        msat = int(args['msat'])
+        raw = self.pricing._cfg()
+        fp = raw.get('fetch_pricing') if isinstance(raw, dict) and 'fetch_pricing' in raw else raw
+        if isinstance(fp, dict):
+            fp['grasp_session_msat'] = msat
+        self.persist_cfg()
+        return {'grasp_session_msat': msat}
+
+    def grasp_price_get_cmd(self) -> dict[str, int]:
+        return {'grasp_session_msat': int(self.pricing.cfg().get('grasp_session_msat') or 0)}
+
+    def stop(self) -> Any:
+        self._closed = True
+        super().stop()
+        store = getattr(self.backend, 'store', None)
+        if store is not None:
+            store.close()