Logo
0.5.0-dev.0

Get started

  • Get started
  • Experimental features

Core Protocol Library

  • 1. Fleetmesh Core Library (fleetmesh_core)
  • 2. Cryptographic Primitives (fleetmesh_core.crypto)
  • 3. Identity & Addressing (fleetmesh_core.identity)
  • 4. Peering & Reputation (fleetmesh_core.peering)
  • 5. Accounting & Capacity (fleetmesh_core.accounting)
  • 6. Storage & Synchronization (fleetmesh_core.storage)
  • 7. Services & Lifecycle (fleetmesh_core.services)
  • 8. Wire Protocol & Encodings (fleetmesh_core.wire)
  • 9. Conformance & Verification (fleetmesh_core.conformance)

Meshnode Host Daemon

  • 1. Meshnode Host Daemon (node)
  • 2. Application Host & Subsystems (fleetmesh_node.app)
  • 3. The Six Architectural Planes (fleetmesh_node.planes)
  • 4. Transport Subsystem (fleetmesh_node.transport)
  • 5. Storage Engines & Backends (fleetmesh_node.storage)
  • 6. Pluggable Protocol Packages (fleetmesh_node.protocols)
  • 7. Nostr Protocol Layer (fleetmesh_node.protocols.nostr)
  • 8. Command Dispatcher & CLI (fleetmesh_node.commands)
  • 9. Compartment Framework (fleetmesh_node.compartment)
  • 10. Configuration Engine (fleetmesh_node.config)
  • 11. Channels & Metrics (fleetmesh_node.channels / fleetmesh_node.metrics)
  • 12. Keystore & Enclave (fleetmesh_node.keystore)
  • 13. Node Interfaces (fleetmesh_node.interfaces)
  • 14. Daemon CLI & Entrypoint (fleetmesh_node.meshnode)

meshctl CLI & Orchestration

  • 1. meshctl CLI & Orchestration
  • 2. meshctl CLI Reference
  • 3. Non-Destructive Hot-Reconciliation
  • 4. Multi-Target Deployment Compiler
  • 5. Fleet Monitoring & Supervision (meshctl watch)
  • 6. Independent Rust Conformance Engine

Strfry Relay Bridge

  • 1. Strfry Relay Bridge (fleetmesh-strfry)
  • 2. Operational Modes & Deployment
  • 3. Write Policy Engine & Grant Enforcement
  • 4. Bulk Data Synchronization (StrfryPipe)
  • 5. Python API Reference (fleetmesh_strfry)

Canonical Schemas & Protocols

  • 1. Canonical Schemas & Protocols (fleetmesh_schema)
  • 2. Nostr Event Kinds Registry
  • 3. Wire Message Catalog & DIDComm Protocols
  • 4. Declarative Manifests & CRDs
  • 5. The Protocol Digest & Version Verification
  • 6. JSON Schema Specifications (Draft 2020-12)
  • 7. Python API Reference (fleetmesh_schema)

Architecture & Specs

  • 1. Architecture & Protocol Specifications
    • 1.1. Fleetmesh Architecture Overview
    • 1.2. Compartments Architecture
    • 1.3. Mechanisms & Architectural Invariants
    • 1.4. Implementing a Second Node
    • 1.5. Protocol Conformance Catalogue
    • 1.6. Protocol Versioning & Wire Digest
    • 1.7. Extending the Mesh Node
    • 1.8. Updates & Release Verification
    • 1.9. Codebase Guide
    • 1.10. Pluggable Protocol Architecture & Ecosystem Interoperability
    • 1.11. Protocol Interoperability & External Standards
    • 1.12. Storage Backends & Engine Design
    • 1.13. Sidecars & Pluggable Bridges
    • 1.14. Paid Fetch & Cashu Micropayments
    • 1.15. Verified Compute Methods & Execution Fabrics
    • 1.16. Non-Deterministic Compute & Workload Routing
    • 1.17. FIPS Native Transport Architecture
    • 1.18. Running Over FIPS
    • 1.19. Discovery, libp2p, and FIPS
    • 1.20. Record-Then-Answer Accounting
    • 1.21. Reversible Apoptosis & Capacity Shedding
    • 1.22. Video Streaming & High-Demand Transit Routing
Fleetmesh
  • 1. Architecture & Protocol Specifications
  • 1.14. Paid Fetch & Cashu Micropayments
  • View page source

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 job mint-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.

Previous Next

© Copyright 2026, Fleetmesh Contributors.

Built with Sphinx using a theme provided by Read the Docs.