Fleetmesh fleetmesh

details · system architecture & design notes · how fleetmesh is built and operated

System Details & Reference Architecture

fleetmesh connects Nostr relays into a federated mesh. This section documents system operation: the reference implementation (meshnode), subsystem compartments, wire protocols, the bilateral accounting engine, and supporting design notes.

Implementation Overview

The reference implementation in fleetmesh_node/ is a typed Python daemon that runs alongside an existing relay to provide peering and accounting.

The daemon isolates execution into twenty-three core compartments, plus up to nine optional ones (p2p, gossip, compute, compute_wire, bridge, dvm, nsite, video, updates) the config enables, coordinates bilateral budgets over DIDComm v2, synchronizes events through Negentropy range reconciliation, and meters transfers with signed receipt hash chains.

Reference Architecture

The anatomy of a mesh node

The reference node is built around the executable specification in fleetmesh_core/. It runs under Python 3.12, requiring only the standard library and the cryptography package. Internal components adhere to typed protocols defined in fleetmesh_node/interfaces.py.

Subsystems & Isolation

Explicit failure boundaries in fleetmesh_node/compartment/base.py prevent cascading faults.

Compartments
23 core compartments in tick order: link, trust, strain, peering, budget, capacity, sync, reporter, discovery, announce, lan, presence, linked, network, retention, scheduler, settlement, mediation, blob_wire, blob_replication, paid_fetch, sidecars, and remote. Up to 9 optional ones join the order when the config enables them: p2p after lan, gossip after p2p (before presence), compute, compute_wire, and bridge after scheduler, dvm, nsite (the NIP-5A static-site gateway, which reads manifests through bridge), video (live CMAF packaging and transit reflection, the other HTTP face), then updates last - it reports on all the others. The list is held to fleetmesh_node/app/core.py by scripts/check-cli.py.
Refusal Channel
Refusals record structured reasons (capacity, auth, rate, schema) in internal logs.
Contracts
Static typing and formal runtime protocols define clear boundaries between storage, sync, peering, and accounting.

State & Storage Model

Pluggable SQLite and PostgreSQL dialects with causal projections.

events.sqlite / PostgreSQL
Deduplicated event store via SqliteDialect or PostgresDialect with tag indexing, Negentropy ranges, and multi-replica store_lease coordination.
ProjectedNodeStore
Content-addressed causal graph projections in fleetmesh_node/storage/projected.py tracking thread roots, reactions, reposts, and deletes.
grants & accounts
Active, pending, and historical peering grants, per-window meters, receipt hash chains, and directional strain records.
control.sock
Local UNIX domain socket exposing the runtime command interface to operator tooling.

Transport & Wire Stack

7-rung transport ladder across native P2P and encrypted overlays.

Identity
Multi-key binding: secp256k1 (did:nostr), X25519 (DIDComm agreement), and Ed25519 (transport signatures), plus did:key, did:peer, did:plc, and did:web.
Transport Ladder
Negotiates fips-native (rank 5), iroh (10), rhio (12), p2panda (15), libp2p (20), ssb (25), and nostr gift-wrap fallback (100).
Sync Face
Async relay server supporting NIP-01, NIP-11, and NIP-77 Negentropy reconciliation in delivery envelopes.

Bilateral Accounting

Bilateral coordination between peers without global consensus.

Grants
Kind 30801 published parameters defining request ceilings, event limits, and cadence.
Receipts
Signed, chained receipts issued on cadence, verified in the issuer frame.
Window Loop
AIMD window evaluation: clean windows expand limits; discrepancies trigger deterministic S0–S3 actions.

Compute, ZK & AI Fabric

Deterministic WASI, Groth16 & zkVM, Multi-Provider LLM, and MCP agents.

WASI & Media
Sandboxed WebAssembly in fleetmesh_node/planes/services/compute/executors/wasm.py and deterministic FFmpeg transcoding in fleetmesh_node/planes/services/compute/executors/media.py.
Groth16 & zkVM
Groth16 verification over alt_bn128 in fleetmesh_core/crypto/zk.py plus RISC Zero and SP1 zkVM receipt verification in fleetmesh_node/planes/services/compute/executors/zk.py.
LLM & MCP Agents
Multi-provider LLM router in fleetmesh_node/planes/services/compute/executors/providers.py and fuel-bounded ReAct agents with MCP tool bridges in fleetmesh_node/planes/services/compute/executors/mcp.py.

Multi-Rail Settlement & Paid Fetch

Micropayment rails, escrow, and HTTP 402 Paid Fetch in fleetmesh_node/settlement/.

Lightning (BOLT11 / BOLT12 / L402)
Preimage escrow, accountable sealed delivery, and invoice settlement.
Cashu Ecash & NUT-24
Chaumian ecash mint swaps/melts and HTTP 402 Paid Fetch in fleetmesh_node/planes/services/paidfetch/compartment.py.
NWC (NIP-47)
Nostr Wallet Connect support for client-delegated automated settlement.

Declarative Orchestration

Declarative manifests, 6-plane conformance, and Ansible ops.

Manifests & meshctl
fleetmesh.org/v1alpha1 resources under manifests/, held to the constants by scripts/check-manifests.py and consumed by meshnode init --manifest. The standalone meshctl CLI (built in Rust) provides production declarative manifest management, non-destructive hot-reconciliation, 523/523 6-plane conformance verification, and multi-target compilation.
Cluster Engine
Multi-node local testnet simulator in fleetmesh_node/testnet/cluster.py configuring mesh, star, ring, and line topologies.
watch.py
Machine-readable invariant auditing daemon with exit codes 0, 1, and 2 for monitoring agents.

Universal Relay Bridge

Bidirectional ingress and egress across standard Nostr relays.

Ingress & Egress
Continuous subscription and delivery in fleetmesh_node/planes/transport/bridge/compartment.py with cryptographic signature verification and provenance tracking.
Smart Shard Routing
Automatic detection and indexing of topic tags (#t) for local mesh replication.
Reconciliation
Range-bounded historical backfill (reconcile) over external WebSocket relays.

DVM Gateway & Projections

NIP-90 deterministic compute, Schema.org Linked Data, and NIP-32/85 projections.

NIP-90 Gateway
Translates compute requests (kinds 5000–5999) into sandboxed WASI jobs in fleetmesh_node/dvm/, producing signed responses.
NIP-32 & NIP-85
Adverse findings project kind 1985 moderation labels under fleetmesh.reputation and kind 30385 relay scores referencing kind 30802 dispute evidence.
Schema.org v30.1
Deterministic JSON-LD projections in fleetmesh_core/projection/linked_data.py mapping descriptors, grants, reports, and offers.

Pluggable Protocol Suites

Six federated protocols hosted on one node in fleetmesh_node/protocols/base.py.

ATProto & ActivityPub
XRPC PDS/Relay, MST over DAG-CBOR, and CAR v1 slices (atproto), alongside ActivityStreams 2.0 Inbox/Outbox, WebFinger RFC 7033, and RFC 9421 HTTP Signatures (activitypub).
SSB & p2panda
Secure Scuttlebutt 4-phase SHS, Box Stream, and MuxRPC (ssb), plus deterministic RFC 8949 CBOR operation logs with checkpoint pruning (p2panda).
Rhio / Bao
1 KiB chunked BLAKE3/Bao Merkle tree verification, HTTP 206 Range serving, and NATS JetStream subject routing (rhio).

Live Video & Hosting Sidecars

CMAF/LL-HLS live video reflection, work-barter, and manifest sidecars.

Video Transit & Barter
Live fMP4/WebM segmenter and MoQ reflector in fleetmesh_node/planes/services/video/compartment.py speaking video-transit/1.0 with HTTP 307 load-shedding and compute-for-transit barter.
NIP-5A nsite
Static site gateway in fleetmesh_node/planes/services/nsite/compartment.py serving kind 15128/35128 manifests with COOP/COEP isolation.
GRASP, OCI & Magpie
Sidecar health and endpoint verification in fleetmesh_node/planes/services/sidecars/compartment.py for Git (grasp/1.0), OCI containers (ncontainer/1.0), and media catalogs (magpie/1.0).

Browser Leaf & Key Login

Edge client SDK and passwordless multi-app authentication.

@fleetmesh/leaf
TypeScript leaf node for Chromium, Firefox, and WebKit with IndexedDB storage, Web Locks tab coordination, NIP-77 sync, and budget/1.0 receipts.
fleetmesh_auth
Sovereign key login via NIP-07 extensions and NIP-46 remote signers, plus NIP-98 (kind 27235) cross-app portable passes (fmpass_...).
Neutral Discovery
Zero-privilege public rendezvous relay at wss://relay.fleetmesh.org for cold-start descriptor and mediator discovery.

Technical Guides & Design Notes

In-depth implementation and design articles

live · read only · § Discovery · § Coverage · § Relay projection

The mesh, as it says it is

Every node publishes descriptors, heartbeats, and coverage claims as standard Nostr events. This page queries relays directly from the browser to display network topology, claims, and relay assertions without external servers.

Watch the mesh →

thesis · vision · § Compute layer · § Shard exchange · § Verifiable delivery · § Identity

The future of the mesh: why bilateral reputation relays matter

Architectural overview: verifiable transmission, shard replication, distributed compute escrow, cryptographic identity, and network resilience against sybil swarms.

Read the overview →

field guide · § Implementation · § Operator surface · § Conformance

Running a node and operator manual

Operational guide to fleetmesh_node/meshnode: four-command setup, systemd service configuration, Caddy TLS reverse proxying, telemetry with meshwatch, the 42-command CLI reference, and troubleshooting procedures.

Read the operator guide →

subsystems · § Grants · § Capacity · § Strain ledger

Capacity management, load shedding & strain ledgers

How fleetmesh_node/planes/peering/capacity/compartment.py manages capacity ceilings and executes a three-rung load-shedding ladder under peak pressure, and how fleetmesh_node/planes/peering/strain/compartment.py tracks directional anomalies.

Read the capacity guide →

identity · § Identity · kinds 30830–30834

Private networks, fleets & enrolment

What a kind 30830 roster is and the four join policies; how a roster-protected relay works (fleetmesh_core.network.relay_allow, the strfry-bridge roster_file); the capability vocabulary, tiers and grant chains; revocation; and the fleet/enrol token flow from meshnode whoami to meshctl fleet list.

Read the networks guide →

accounting · § Grants & receipts · § Severity ladder · § Trust weighting

Reverse reputation and receipt hash chains

Published bilateral budgets, receipt hash chains, and the deterministic five-step severity ladder (S0–S4). Includes an interactive simulator demonstrating convergence and sybil resistance.

Read the deep dive →

economics · § Grants · § Replication · § Settlement

Retrieval-based storage settlement

Why fleetmesh settles discrete retrieval requests rather than charging continuous storage rent, and how storage aligns with transit settlement.

Read the economic analysis →

standards · § Identity · § Cryptography · § FIPS 140-3

Cryptographic boundaries and FIPS 140-3 compliance

Audit of cryptographic algorithms in fleetmesh against NIST standards. Isolates non-approved curves at external relay edges to enable federal deployment compliance.

Read the compliance audit →

comparison · § Transports · § Discovery · § Overlay routing

fleetmesh and the Free Internetworking Peering System

Architectural comparison between fleetmesh and the FIPS overlay network: packet routing and application-level relay federation.

Read the network comparison →

visual overview · § Architecture · 10 Emblems

Protocol concepts in ten emblems

Core mechanisms of fleetmesh rendered visually: cryptographic identity knots, discovery lattices, Negentropy range reconciliation, reverse reputation, and the compute market.

View the concept emblems →

The formal rules and protocol schemas are codified in the fleetmesh Specification and the Schema Browser. These pages document operational rationale and reference code.