1.22. Video Streaming & High-Demand Transit Routing
Experimental
In the code and tested, but not supported in this alpha: it may change or go away. See Experimental features.
This specification defines the architecture, wire protocols, transport ladder bindings, storage verification primitives, and economic settlement mechanics for delivering high-demand video streams across the Fleetmesh data mesh.
1.22.1. Overview & Problem Statement
Sovereign edge nodes frequently broadcast from home connections, mobile uplinks, or resource-constrained gateways where outbound bandwidth is limited (typically 4–8 Mbps). When audience demand scales from 2–4 peers to hundreds or thousands of concurrent viewers, the origin broadcaster’s upstream uplink saturates immediately, inducing severe latency, packet loss, and broadcast collapse.
Fleetmesh solves this by composing its native planes, pluggable protocol suites, and sidecar transports into a four-pillar delivery fabric:
Tier 1 — P2P Swarm Meshing (Mesh-Cast): Viewers form cooperative clusters over
blob_wire(blob/1.0),transport.lan(mDNS), andiroh_rung, verifying sub-segment slices on the fly via Rhio Bao Merkle trees (RhioBaoTree) and tracking manifest state via p2panda append-only logs.Tier 2 — Operator Transit Routing & Rhio Supernode Clusters: When origin capacity crosses its declared shed thresholds in
planes.peering.capacity, high-capacity operator nodes step in as Transit Reflectors, fanning out segments across micro-datacenter clusters via Rhio (NATS JetStream + S3/MinIO CAS sync).Bilateral Debt & Hash-Chained IOU Accounting: Operators routing traffic pro bono issue cryptographically signed, cumulative Transit Receipts modeled on
budget/1.0’s Record-Then-Answer hash chain, repayable through bartered network utility (Blob Shoring, Verified Compute / DVM, or DIDComm Mediation).Two-Tier Commercial Cashu Settlement: Commercial transit operators meter outbound egress in real time using
PaidFetch’s dual-item HTTP 402 engine (operatorNUT-03mint swap + creatorNUT-11P2PK-locked custody) for segmented video, andCrossProtocolSettlementGatewayprepaid token buckets orPaidFetch.quote_sessionfor continuous real-time streams.
1.22.2. System Architecture & Pluggable Protocol Integration
Rather than locking video delivery into a single monolithic server, video ingestion, discovery,
and egress integrate directly with ProtocolHost (fleetmesh_node.transport.host) and ProtocolManager
(fleetmesh_node.protocols):
+---------------------------------------------------------------------------------------+
| Broadcaster / Transit Node Daemon Core |
| +------------------------+ +------------------------+ +-------------------------+ |
| | Capacity & Shed Ladder | | Budget & IOU Receipts | | PaidFetch & Gateway | |
| | (planes.peering. | | (Record-Then-Answer | | Settle (NUT-03 Swap + | |
| | capacity) | | Sqlite/Postgres Store)| | NUT-11 P2PK Split) | |
| +------------------------+ +------------------------+ +-------------------------+ |
| | |
| +----------------------------------------+ |
| | ProtocolHostRouter (Ingress Multiplex)| |
| +----------------------------------------+ |
+------------------------------------------|--------------------------------------------+
|
+------------------+------------------+------------------+------------------+
| | | | |
v v v v v
+----------+ +-----------+ +-----------+ +-----------+ +-----------+
| nostr | | rhio | | p2panda | | atproto | |activitypub|
| Blossom | | Bao Tree | | Manifest | | CIDv1 CAS | | Federated |
| /<npub>/ | | JetStream | | Op-Log | | & Firehose| | Video/Note|
| <sha256> | | & S3 Sync | | Ordering | | Blobs | | Delivery |
+----------+ +-----------+ +-----------+ +-----------+ +-----------+
1.22.2.1. Unified Multi-Protocol Content Addressing
Every video segment written to the node’s BlobStore (fleetmesh_node.protocols.nostr.blobstore) and indexed
by RhioBlobSync (fleetmesh_node.protocols.rhio.store) is simultaneously addressable across all enabled
protocol suites with zero storage duplication:
Blossom (BUD-01 / BUD-02): Served at
GET /<sha256>.m4sand account-priced atGET /<npub>/<sha256>.m4sviaBlossomServer.ATProto & IPFS (CIDv1 raw-sha2-256): Translated deterministically via
fleetmesh_core.identity.cid(sha256_to_cid/cid_to_sha256) and served atGET /cid/bafkrei...andGET /xrpc/com.atproto.sync.getBlob.Rhio Cluster CAS (Bao Merkle Tree): Served at
GET /rhio/blobs/<sha256>with 1024-byte chunked Merkle tree root verification (tree_root).ActivityPub & SSB: Referenced as federated ActivityStreams 2.0
Video/Documentattachments and SSB&<sha256>.sha256blob links.
1.22.2.2. Cross-Protocol Stream Announcements
When an origin node starts a broadcast or publishes VOD content, ProtocolTranslator
(fleetmesh_node.planes.services.gateway.translate) projects a canonical UnifiedPost across all active
social surfaces:
Nostr: NIP-53 Live Activity replaceable event (Kind
30311) and Kind1note withimeta/rstream manifest tags.ATProto:
app.bsky.feed.postrecord committed to the node’s Merkle Search Tree (fleetmesh_core.storage.mst) and emitted on thesubscribeReposfirehose.ActivityPub: Signed
Create { Video }activity federated to follower inboxes using RFC 9421 Ed25519 HTTP Signatures.p2panda & Rhio: Appended to
P2PandaLogStoreand published tofleetmesh.postsover NATS JetStream.
1.22.3. Dual Streaming Pipelines
Fleetmesh establishes two complementary streaming pipelines tailored to latency, verification, and transport characteristics:
Dimension |
Segmented Chunk Streaming (LL-HLS / CMAF) |
Real-Time Interactive Video (MoQ / Datagram) |
|---|---|---|
Primary Ingress / Egress |
|
|
Target Latency |
1–4 seconds (LL-HLS sub-segments) / 2–6 seconds (standard CMAF) |
100–350 milliseconds |
Manifest & Ordering |
|
Ephemeral catalog over DIDComm / FIPS control flow |
Integrity Verification |
|
Per-frame / per-group Ed25519 or Schnorr signature (or |
Storage & Retention |
Content-addressed |
Ephemeral in-memory ring buffer ( |
Commercial Settlement |
Per-segment |
Session-gated |
1.22.4. Cryptographic Manifests & Sub-Segment Verification
1.22.4.1. Tamper-Evident Manifest Ordering via p2panda
Polling mutable HTTP .m3u8 playlists across decentralized reflectors introduces race conditions,
stale cache windows, and playlist injection risks. Fleetmesh models live stream manifests as an
append-only p2panda operation log (fleetmesh_node.protocols.p2panda):
Genesis Operation (``seq_num == 0``): Declares stream metadata (codec parameters, init segment
sha256andtree_root, target duration, broadcasterdid:key/npub, and active transit reflectors).Segment Operations (``seq_num > 0``): Each new CMAF segment or LL-HLS part is published as a deterministic RFC 8949 CBOR operation (
fleetmesh_core.wire.cbor) enforcing strict chain monotonicity (previous_seq_num == seq_num - 1andbacklink == prev_op.id).Legacy Player Compatibility:
ProtocolHostdynamically renders a standard HLS.m3u8sliding-window playlist view directly from the latest verified operations inP2PandaLogStore, while native Fleetmesh peers sync the operation log viaGET /p2panda/operations/<author>orP2PandaRung.
1.22.4.2. Bao 1024-Byte Chunked Merkle Verification (RhioBaoTree)
In peer-to-peer swarm delivery, waiting for an entire 2–4 MB video segment to download before
checking its sha256 hash stalls playback and allows malicious peers to inject garbage bytes that
waste downstream bandwidth.
Fleetmesh uses RhioBaoTree (fleetmesh_node.protocols.rhio.store) to compute a hierarchical Merkle tree
over 1024-byte slices (using \x00 leaf domain separation and \x01 interior node prefixes):
Every segment announced in the manifest includes
{sha256, tree_root, size}.When pulling sub-chunks via
blob_wire(blob/1.0) or striping acrossiroh_rungpeers, the receiver verifies 1 KB leaf hashes againsttree_rootimmediately upon arrival.Corrupted slices are rejected at the first kilobyte, triggering an immediate
StrainLedgerpenalty against the offending peer and failing over to an alternate swarm source.
1.22.5. Transport Ladder & P2P Swarm Meshing (Mesh-Cast)
Video control and data flows map onto TransportRouter (fleetmesh_node.transport.router) according to
each rung’s cryptographic and framing guarantees:
Rung 1 — FIPS Native Datagram Flows (``fleetmesh_node.transport.fips_rung``): - Connects to the local FIPS v0.5.1 socket (
/var/run/fips/api.sockor~/.fips/api.sock) and acquires connectedAF_UNIXSOCK_DGRAMflow descriptors viaSCM_RIGHTS. - Provides mesh-encrypted, identity-authenticated datagram transport with 8-byte binary framing (0x4D 0x01magic,seq,flags,msg_id) andReassemblersupport up toMAX_FRAGMENTS = 64atmax_payload(1170–1362 bytes). - Used for low-latency MoQ interactive media flows (FSP port30820) and encrypted transit control signaling (FSP port30821) between mesh peers.Rung 2 — Iroh UDP Stream Framing (``fleetmesh_node.transport.iroh_rung.quic.IrohLiveEngine``): - Provides zero-dependency, QUIC-shaped multiplexed UDP streams (
StreamFrame,AckFrame,FRAME_PROBE_REQ/FRAME_PROBE_RESPSTUN-style NAT hole-punching) bounded by strict anti-DoS caps (MAX_CONNECTIONS = 256,MAX_STREAMS_PER_CONN = 64,MAX_CHUNKS_PER_STREAM = 4096). - Security Boundary: BecauseIrohLiveEnginedoes not perform a TLS 1.3 handshake on the wire, all control messages on this rung must pass throughdidcomm_inbound.open_inbound(ECDH-1PU JWE), and all raw media chunks must be verified against the manifest’s signed(sha256, tree_root)digest before playback or re-seeding.Rung 3 — Rhio NATS JetStream & S3 Cluster Sync (``fleetmesh_node.protocols.rhio`` & ``fleetmesh_node.sidecar.fleetmesh_rhio``): - Operates at rank 12 in
TransportRouterviaRhioRungandRhioSidecarDaemon. - When an operator supernode ingests a stream,RhioSidecarDaemonfans segments out over NATS JetStream subjects (fleetmesh.video.<stream_id>) to sibling edge reflectors in the micro-datacenter cluster and asynchronously mirrors cold VOD segments to S3/MinIO (synced_s3 = 1inrhio_blobs).Rung 4 — Store-and-Forward Control Rungs (``P2PandaRung``, ``P2PTransport``, ``SSBRung``, ``RelayRung``): - Used for asynchronous transit negotiations, grant amendments, and signed receipt exchanges when direct UDP/FSP paths are unavailable.
1.22.5.1. Local Subnet Affinity & blob_wire Swarm Exchange
Before offloading traffic to external transit supernodes, local viewer swarms absorb downstream load:
LAN mDNS Discovery (``fleetmesh_node.planes.transport.lan``): Discovers co-located viewers on the same campus, office, or ISP subnet via mDNS, serving cached segments locally at zero WAN egress cost.
Policy-Capped Swarm Pulls (``fleetmesh_node.planes.store.blob_wire``): Viewers exchange held segment hashes and byte ranges using
blob/1.0messages (have,offer,pull,chunk,refuse). Each node enforcesBlobWireConfigper-peer limits (bytes_per_day,max_concurrent,max_blob_bytes,max_total_bytes) tracked inIntakeStore(blob_replicas.sqlite), and automatically unpins/drops temporary stream replicas when a peering grant ends (BlobWire.drop_peer).Bilateral Peering Incentives: Peers serving segment chunks increment
ReceiptCounters.bytes_outinplanes.peering.budget, earning load-weighted AIMD limit growth (window.step_fraction) and priority allocation from the broadcaster.
1.22.6. Operator Transit Routing & Capacity Shedding
1.22.6.1. Automated Handover Driven by Capacity Shed Ladder
Rather than polling ad-hoc bandwidth heuristics, origin transit handover is driven directly by the
node’s formal Capacity compartment (fleetmesh_node.planes.peering.capacity and fleetmesh_core.accounting.capacity):
Pressure Evaluation: On each tick,
Capacity.pressure()evaluates open-window aggregate counters (Budget.aggregate()) against the operator’s livecapacityceiling ($p = max_c (text{measured}_c / text{total}_c)$).Shed Engagement (``narrow_scope`` / ``amend_down``): - When outbound bandwidth pressure $p$ engages
narrow_scopeoramend_down,Capacitysnapshots existing peer grant limits in itsbeforestore (persist=st.SNAPSHOT) and scales direct non-transit peer limits towardshed_floor(probation)withcause: capacity(non-adverse). - Simultaneously, the origin initiates a Transit Handover to one or more pre-peered Transit Supernodes, reserving its remaining local uplink exclusively for feeding the primary stream to those reflectors. - New viewer HTTP requests toBlossomServerreceive anHTTP 307 Temporary Redirectto the active Transit Reflector’s endpoint, and a newp2pandamanifest operation announces the reflector URLs.Hysteresis & Recovery (``restore_below``): - Once stream demand subsides and pressure drops below
restore_below,Capacity.restore_grants()returns remembered limits to direct peers (clamped bywindow.within(was, tier)) and closes the transit session.
1.22.6.2. Pro Bono Routing with Record-Then-Answer Hash-Chained IOUs
Operators supporting community or grassroots broadcasters account for transit egress using the same
cryptographic receipt-chain invariants as budget/1.0 (fleetmesh_node.planes.peering.budget.receipts):
Transit Handshake (``video-transit/1.0``): - The origin sends a DIDComm
transit-solicitationspecifyingstream_id, expected bitrate, and requestedmax_transit_bytes. - The operator replies with a signedtransit-grantestablishing the window duration, receipt cadence, andmax_unsettled_transit_bytesceiling.Cumulative Hash-Chained Receipts (``TransitReceipt``): - At the configured cadence, the transit operator (or origin) produces a cumulative, monotonic receipt chained via
accounting.link(body)(OutChainwithseq,prev,heads, and cumulativecounters['transit_bytes_out']). - Gap Tolerance vs. Rewrite Detection: FollowingReceiptsMixin.on_receipt, if a UDP or relay drop causesseq > expected_seq, the receiver records a diagnosticreceipt_gapwithout faulting the window becausecountersare cumulative and monotonic; however, a counter that moves backward or rewrites an existingseqtriggers an immediateS2finding. - Record-Then-Answer Durability (``docs/record-then-answer.md``): Chain heads and meter snapshots are persisted to the node’s backing store (SQLiteWAL orPostgreSQLviafleetmesh_node.storage.locator.Locator) withdurability=commiton session open/close anddurability=windowbefore any receipt orfarewell()message leaves the wire.Debt Repayment via Bartered Network Utility: - Blob Shoring (``planes.store.blob_replication`` & ``blob_wire``): The debtor origin pins and serves the operator’s cold Blossom/Rhio blobs (
ReplicaStore/IntakeStore), crediting shored byte-days against outstanding transit debt. - Verified Compute & DVM Credit (``planes.services.compute`` & ``planes.services.dvm``): The debtor origin executes deterministic WASM/WASI jobs, Groth16 ZK / zkVM proofs (zk_pinned_vks), or NIP-90 DVM inference/transcode workloads on behalf of the operator. - DIDComm Mediation (``planes.transport.mediation``): The debtor origin buffers and relays store-and-forward envelopes for the operator’s mobile leaf nodes inMediationStore.Soft Debt Ceilings: - If unsettled debt reaches
max_unsettled_transit_byteswithout bartered repayment or ecash top-up, the reflector gracefully degrades forwarding to low-bitrate audio-only tracks rather than severing the broadcast mid-sentence.
1.22.7. Commercial Fee-Based Transit (Cashu HTTP 402 & Token Buckets)
Fleetmesh supports two commercial settlement modes built directly on its shipped Cashu engines:
1.22.7.1. 1. Per-Segment Dual-Item HTTP 402 (PaidFetch + BlossomServer)
For segmented HLS/CMAF streaming, transit nodes utilize PaidFetch (fleetmesh_node.planes.services.paidfetch)
and account-scoped Blossom routes (GET /<npub>/<sha256>.m4s in fleetmesh_node.protocols.nostr.blossom):
Dual-Item 402 Quote (``PaidFetch.quote``): When a viewer (not exempt via
free_for_partnersorfree_bytes_per_dayallowance inPriceStore) requests a segment at/<broadcaster_npub>/<sha256>.m4s,PaidFetchreturns anHTTP 402 Payment Requiredquote containing up to two items:Item(to='operator', payee=node_pk, msat=operator_msat): Covers the transit operator’s bandwidth egress fee (priced viamsat_per_mbrules inFetchPricingConfig).Item(to='account', payee=broadcaster_pk, msat=account_msat): Covers the creator’s content fee (capped bymax_account_fee_msat), with the NUT-18 payment request locked tocashu.x_only_to_compressed(broadcaster_pk).
Atomic Verification & Non-Custodial Split (``PaidFetch.settle``): The viewer retries with comma-separated
cashuBtokens in theX-Cashuheader:Operator Leg:
AllowlistBackend.verify()checksProofStore.seen(ys)and executes a live NUT-03 swap at the allowlisted mint (deductinginput_fee_ppk), storing fresh unspent proofs incashu_proofs(later swept to Lightning viasweep_tick).Broadcaster Leg:
AllowlistBackend.verify()verifies that every proof is NUT-11 P2PK-locked to the broadcaster’s pubkey (cashu.p2pk_locked_to(secret) == broadcaster_pk), records theYpoints incashu_takento prevent replay, and stores the locked proofs inProofStore.account_proofsfor the broadcaster to collect—ensuring the transit operator never takes custody of creator funds.
1.22.7.2. 2. Continuous Stream & Session Settlement (CrossProtocolSettlementGateway)
For real-time MoQ datagram streams or high-frequency sub-segment fetches where per-request mint swaps would introduce latency:
Prepaid Token Bucket Metering (``fleetmesh_node.planes.services.gateway.settle.CrossProtocolSettlementGateway``): - Viewers or origin sponsors deposit Cashu V3 (
cashuA) or V4 (cashuB) tokens viasettle_cashu('video', peer_id, token), creditingpeer.balance_satand refilling theirTokenBucket. - As video frames or sub-segments flow,check_access('video', peer_id, cost)deducts tokens in memory at line rate, automatically convertingbalance_satinto fresh token batches (tokens_per_topup) and issuing aPaymentChallenge(to_http_402,to_nostr_notice, orto_muxrpc_error) only when both the bucket and prepaid balance are exhausted.Flat Session Gating (``PaidFetch.quote_session``): - Alternatively, a viewer can pay a single flat session fee via
GET /sidecar-session/video/<stream_id>(backed bysidecar_session_msat['video']), unlocking stream access for the duration of the session.
1.22.8. Implementation Work Breakdown Structure
With the pluggable protocol host, RhioBaoTree, P2PandaLogStore, fips_rung, iroh_rung,
PaidFetch dual-item 402s, and CrossProtocolSettlementGateway now implemented in the tree, the
remaining video-specific engineering work spans 5 focused phases:
Phase 1: Canonical Wire & Schemas (``video-transit/1.0``): - Define
video-transit/1.0message schemas (transit-solicitation,transit-grant,transit-receipt,transit-close) inschema/and addtransit_bytes_outtoschema/constants.jsonandfleetmesh_core.wire.wire_types.Phase 2: ``p2panda`` Manifest & ``RhioBaoTree`` Segment Pipeline: - Build the live CMAF / LL-HLS packager that stores segments in
BlobStore+RhioBlobSync(computing(sha256, tree_root, size)), appends manifest operations toP2PandaLogStore, and mounts dynamic.m3u8and/<npub>/<sha256>.m4sroutes onProtocolHost.Phase 3: Transit Reflector Compartment (``fleetmesh_node.planes.transport.transit``): - Implement the
Transitcompartment subscribing toCapacityshed transitions (narrow_scope/amend_down), managingfips-native(port30820) andiroh_rungMoQ ring-buffer reflection, and triggeringRhioSidecarDaemonNATS JetStream cluster fanout.Phase 4: Bilateral Transit IOU Ledger & Barter Settlement: - Extend
AccountStore/ReceiptsMixin(viafleetmesh_node.storage.locator.Locatoron SQLite and PostgreSQL) to track unsettledtransit_bytes_outdebt and credit bartered repayments fromblob_replication,compute/dvm, andmediation.Phase 5: ``meshctl stream`` CLI & Conformance Vectors: - Add
meshctl streamcommands (start,watch,transit-status,settle), addvideo-transit.jsonconformance test vectors tocore/vectors/, and register the PIURI inscripts/check-interop.pyandscripts/check-implementing.py.