1.14. Paid Fetch & Cashu Micropayments
Experimental
In the code and tested, but not supported in this alpha: it may change or go away. See Experimental features.
1.14.1. Paid fetch: HTTP 402 with Cashu
A meshnode that serves blobs over Blossom can charge for a fetch. The price is operator policy; the payment is Cashu ecash, verified by swapping it at the mint before the bytes go out. Nothing here is on by default: with no price configured, every fetch is free and no header changes.
1.14.1.1. The wire (NUT-24)
HEAD /<sha256>
200 OK
X-Price-Msat: 2500
X-Cashu: creqA... NUT-18 payment request, no body
GET /<sha256>
402 Payment Required
X-Cashu: creqA...
{"sha256": ..., "size": ..., "price_msat": 2500,
"items": [{"to": "operator", "payee": <node pubkey>, "msat": 2500}],
"offers": [{"rail": "cashu", "request": "creqA...", "unit": "sat", "amount": 3}],
"expires": <unix seconds>}
GET /<sha256>
X-Cashu: cashuB... NUT-00 V4 token worth at least the amount
200 OK (the blob)
The request names the mints this node accepts (m), the unit and the amount
in sat, rounded up from msat (1 msat costs 1 sat). A token from a mint not in
that list is refused without contacting it. The 402 body says what a client
would pay before it decides to; the header alone is enough for one that
already knows.
1.14.1.2. What “verified” means
AllowlistBackend.verify() is the security boundary. A token is accepted only
when the mint has swapped its proofs for fresh ones the node now holds
(NUT-03). A proof the node has already seen is refused locally; a proof the
mint has already seen is refused by the mint; a mint that is unreachable means
the payment did not happen. The mint’s NUT-02 input fee is taken out of the
swap outputs and recorded in the receipt. Fresh proofs live in
cashu_wallet.sqlite; meshnode paid_fetch.wallet shows them and
paid_fetch.sweep melts them to sweep_to when the balance is above
sweep_above_sat (the tick checks once a minute; the command forces it).
The settlement engine’s own live rail is the same shape: settlement.live_cashu: true
requires settlement.mint_url, and a config without one is refused at load
(settlement.live_cashu requires settlement.mint_url) rather than at start.
The sweep is a NUT-05 melt at the mint holding the most. sweep_to is
either a bolt11 invoice, used as-is, or a Lightning address (name@domain)
resolved through LNURL-pay for the balance less a reserve of 1% (2 sat
floor) so the proofs cover the mint’s fee_reserve. The largest proofs are
spent first until amount plus reserve is covered; NUT-08 change is not
implemented, so what the mint does not use of the reserve is its to keep.
Nothing is marked until the mint reports the invoice paid: the spent proofs
then move to state melted with melted_at, and the melts table gets
the quote, amount, fee reserve, invoice, preimage and state. A melt that
fails is a sweep report with a why and a failed row; the proofs stay
unspent and the next tick tries again. With sweep_to null the sweep says
so and does nothing.
Every operator item that settles is a row in sales (subject
blob:<sha256> or <sidecar>:<id>, buyer, msat, mint, rail, at); every
Blossom fetch adds its bytes to served_day in fetch_prices.sqlite per
fetcher (anon when unauthenticated) per day, whether or not a free tier
is configured; every sidecar session the forward_auth check lets through
is a row in sidecar_sessions.sqlite. meshnode account DIR export --json
reads all of it (see the README).
MintBackend is the interface (price_quote, verify, balance, sweep,
describe). The allowlist is the first implementation; a node that runs its
own nutshell, cdk-mintd or Fedimint replaces it without touching the 402 or
the call site in blossom.py.
1.14.1.3. Pricing
Configured under fetch_pricing; every key is live (re-read on each fetch).
fetch_pricing:
default_msat: 0 # everything not matched below
free_for_partners: true # grantees never pay
free_bytes_per_day: null # null = no free tier; bytes per fetcher key per day
max_account_fee_msat: 0 # 0 = uploaders cannot add a fee
rules: # first match wins
- {content_type: "video/*", msat: 2500}
- {min_bytes: 10485760, msat: 1000}
- {uploaded_by: <pubkey>, msat: 0}
rails:
cashu:
mints: ["https://mint.example"]
unit: sat
sweep_above_sat: 0 # 0 = never sweep
sweep_to: null # a bolt11 invoice or a Lightning address (name@domain)
Order of decision for one fetch: partner and free_for_partners -> the
fetcher’s daily allowance (keyed by the Blossom auth pubkey; anonymous
fetches share one pool) -> per-item price (paid_fetch.price_set) -> rules ->
default_msat. The allowance is spent only after the bytes are served.
1.14.1.4. The account fee
GET /<npub>/<sha256> names the uploader. If the operator allows it
(max_account_fee_msat > 0) and the uploader of that blob has set a price with
account=<pubkey>, the 402 carries a second item, "to": "account", capped at
the operator’s maximum, with its own NUT-18 request P2PK-locked (NUT-11) to the
account key. It must be paid with proofs locked the same way; the node checks
the lock and hands those proofs on rather than swapping them, since only the
account can. The same blob under a bare hash, or under someone else’s npub,
carries the operator price only.
1.14.1.5. What the descriptor says
Kind 11801 gains ["mint", <url>] per accepted mint and
["price", "fetch", <default msat>, "msat"] when anything is priced. HEAD is
the exact figure; the tag says that there is one.
A node that also fronts a GRASP (git) sidecar gains
["price", "grasp-session", <msat>, "msat"] when grasp_session_msat is
configured - a coarse, one-quote-per-clone/fetch-session price, not a
per-object one; see docs/sidecars.md. An ncontainer (OCI) sidecar
needs no new price tag: every blob it serves is priced exactly like any
other Blossom fetch through the same quote()/settle() path below.
1.14.1.6. Tests
fleetmesh_node/tests/test_paid_fetch.py- offline, against a fake mint that does the real blind-signature arithmetic and remembers what it swapped.fleetmesh_node/tests/test_cashu_live.py- against nutshell (CI jobmint-live): a real 402, a real swap, the payer’s proofs SPENT at the mint, and the mint alone refusing a replay once the node’s local record is deleted.