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:

  1. Tier 1 — P2P Swarm Meshing (Mesh-Cast): Viewers form cooperative clusters over blob_wire (blob/1.0), transport.lan (mDNS), and iroh_rung, verifying sub-segment slices on the fly via Rhio Bao Merkle trees (RhioBaoTree) and tracking manifest state via p2panda append-only logs.

  2. 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).

  3. 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).

  4. Two-Tier Commercial Cashu Settlement: Commercial transit operators meter outbound egress in real time using PaidFetch’s dual-item HTTP 402 engine (operator NUT-03 mint swap + creator NUT-11 P2PK-locked custody) for segmented video, and CrossProtocolSettlementGateway prepaid token buckets or PaidFetch.quote_session for 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>.m4s and account-priced at GET /<npub>/<sha256>.m4s via BlossomServer.

  • ATProto & IPFS (CIDv1 raw-sha2-256): Translated deterministically via fleetmesh_core.identity.cid (sha256_to_cid / cid_to_sha256) and served at GET /cid/bafkrei... and GET /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 / Document attachments and SSB &<sha256>.sha256 blob 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 Kind 1 note with imeta / r stream manifest tags.

  • ATProto: app.bsky.feed.post record committed to the node’s Merkle Search Tree (fleetmesh_core.storage.mst) and emitted on the subscribeRepos firehose.

  • ActivityPub: Signed Create { Video } activity federated to follower inboxes using RFC 9421 Ed25519 HTTP Signatures.

  • p2panda & Rhio: Appended to P2PandaLogStore and published to fleetmesh.posts over 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

ProtocolHost HTTP (BlossomServer, /rhio/blobs) + blob_wire (blob/1.0)

fips-native encrypted FSP flows + iroh_rung UDP stream/datagram framing

Target Latency

1–4 seconds (LL-HLS sub-segments) / 2–6 seconds (standard CMAF)

100–350 milliseconds

Manifest & Ordering

p2panda append-only operation log (seq_num, backlink, canonical CBOR) + .m3u8 view

Ephemeral catalog over DIDComm / FIPS control flow

Integrity Verification

sha256 segment digest + RhioBaoTree 1024-byte chunked Merkle tree_root

Per-frame / per-group Ed25519 or Schnorr signature (or fips-native link encryption)

Storage & Retention

Content-addressed BlobStore + IntakeStore replica pinning + Rhio S3 cold sync

Ephemeral in-memory ring buffer (st.RING); drop-on-congestion, no backfill

Commercial Settlement

Per-segment PaidFetch dual-item HTTP 402 (X-Cashu)

Session-gated PaidFetch.quote_session or CrossProtocolSettlementGateway TokenBucket

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):

  1. Genesis Operation (``seq_num == 0``): Declares stream metadata (codec parameters, init segment sha256 and tree_root, target duration, broadcaster did:key / npub, and active transit reflectors).

  2. 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 - 1 and backlink == prev_op.id).

  3. Legacy Player Compatibility: ProtocolHost dynamically renders a standard HLS .m3u8 sliding-window playlist view directly from the latest verified operations in P2PandaLogStore, while native Fleetmesh peers sync the operation log via GET /p2panda/operations/<author> or P2PandaRung.

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 across iroh_rung peers, the receiver verifies 1 KB leaf hashes against tree_root immediately upon arrival.

  • Corrupted slices are rejected at the first kilobyte, triggering an immediate StrainLedger penalty 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:

  1. Rung 1 — FIPS Native Datagram Flows (``fleetmesh_node.transport.fips_rung``): - Connects to the local FIPS v0.5.1 socket (/var/run/fips/api.sock or ~/.fips/api.sock) and acquires connected AF_UNIX SOCK_DGRAM flow descriptors via SCM_RIGHTS. - Provides mesh-encrypted, identity-authenticated datagram transport with 8-byte binary framing (0x4D 0x01 magic, seq, flags, msg_id) and Reassembler support up to MAX_FRAGMENTS = 64 at max_payload (1170–1362 bytes). - Used for low-latency MoQ interactive media flows (FSP port 30820) and encrypted transit control signaling (FSP port 30821) between mesh peers.

  2. 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_RESP STUN-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: Because IrohLiveEngine does not perform a TLS 1.3 handshake on the wire, all control messages on this rung must pass through didcomm_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.

  3. Rung 3 — Rhio NATS JetStream & S3 Cluster Sync (``fleetmesh_node.protocols.rhio`` & ``fleetmesh_node.sidecar.fleetmesh_rhio``): - Operates at rank 12 in TransportRouter via RhioRung and RhioSidecarDaemon. - When an operator supernode ingests a stream, RhioSidecarDaemon fans 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 = 1 in rhio_blobs).

  4. 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.0 messages (have, offer, pull, chunk, refuse). Each node enforces BlobWireConfig per-peer limits (bytes_per_day, max_concurrent, max_blob_bytes, max_total_bytes) tracked in IntakeStore (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_out in planes.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):

  1. Pressure Evaluation: On each tick, Capacity.pressure() evaluates open-window aggregate counters (Budget.aggregate()) against the operator’s live capacity ceiling ($p = max_c (text{measured}_c / text{total}_c)$).

  2. Shed Engagement (``narrow_scope`` / ``amend_down``): - When outbound bandwidth pressure $p$ engages narrow_scope or amend_down, Capacity snapshots existing peer grant limits in its before store (persist=st.SNAPSHOT) and scales direct non-transit peer limits toward shed_floor(probation) with cause: 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 to BlossomServer receive an HTTP 307 Temporary Redirect to the active Transit Reflector’s endpoint, and a new p2panda manifest operation announces the reflector URLs.

  3. Hysteresis & Recovery (``restore_below``): - Once stream demand subsides and pressure drops below restore_below, Capacity.restore_grants() returns remembered limits to direct peers (clamped by window.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):

  1. Transit Handshake (``video-transit/1.0``): - The origin sends a DIDComm transit-solicitation specifying stream_id, expected bitrate, and requested max_transit_bytes. - The operator replies with a signed transit-grant establishing the window duration, receipt cadence, and max_unsettled_transit_bytes ceiling.

  2. Cumulative Hash-Chained Receipts (``TransitReceipt``): - At the configured cadence, the transit operator (or origin) produces a cumulative, monotonic receipt chained via accounting.link(body) (OutChain with seq, prev, heads, and cumulative counters['transit_bytes_out']). - Gap Tolerance vs. Rewrite Detection: Following ReceiptsMixin.on_receipt, if a UDP or relay drop causes seq > expected_seq, the receiver records a diagnostic receipt_gap without faulting the window because counters are cumulative and monotonic; however, a counter that moves backward or rewrites an existing seq triggers an immediate S2 finding. - Record-Then-Answer Durability (``docs/record-then-answer.md``): Chain heads and meter snapshots are persisted to the node’s backing store (SQLite WAL or PostgreSQL via fleetmesh_node.storage.locator.Locator) with durability=commit on session open/close and durability=window before any receipt or farewell() message leaves the wire.

  3. 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 in MediationStore.

  4. Soft Debt Ceilings: - If unsettled debt reaches max_unsettled_transit_bytes without 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_partners or free_bytes_per_day allowance in PriceStore) requests a segment at /<broadcaster_npub>/<sha256>.m4s, PaidFetch returns an HTTP 402 Payment Required quote containing up to two items:

    1. Item(to='operator', payee=node_pk, msat=operator_msat): Covers the transit operator’s bandwidth egress fee (priced via msat_per_mb rules in FetchPricingConfig).

    2. Item(to='account', payee=broadcaster_pk, msat=account_msat): Covers the creator’s content fee (capped by max_account_fee_msat), with the NUT-18 payment request locked to cashu.x_only_to_compressed(broadcaster_pk).

  • Atomic Verification & Non-Custodial Split (``PaidFetch.settle``): The viewer retries with comma-separated cashuB tokens in the X-Cashu header:

    • Operator Leg: AllowlistBackend.verify() checks ProofStore.seen(ys) and executes a live NUT-03 swap at the allowlisted mint (deducting input_fee_ppk), storing fresh unspent proofs in cashu_proofs (later swept to Lightning via sweep_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 the Y points in cashu_taken to prevent replay, and stores the locked proofs in ProofStore.account_proofs for 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 via settle_cashu('video', peer_id, token), crediting peer.balance_sat and refilling their TokenBucket. - As video frames or sub-segments flow, check_access('video', peer_id, cost) deducts tokens in memory at line rate, automatically converting balance_sat into fresh token batches (tokens_per_topup) and issuing a PaymentChallenge (to_http_402, to_nostr_notice, or to_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 by sidecar_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:

  1. Phase 1: Canonical Wire & Schemas (``video-transit/1.0``): - Define video-transit/1.0 message schemas (transit-solicitation, transit-grant, transit-receipt, transit-close) in schema/ and add transit_bytes_out to schema/constants.json and fleetmesh_core.wire.wire_types.

  2. 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 to P2PandaLogStore, and mounts dynamic .m3u8 and /<npub>/<sha256>.m4s routes on ProtocolHost.

  3. Phase 3: Transit Reflector Compartment (``fleetmesh_node.planes.transport.transit``): - Implement the Transit compartment subscribing to Capacity shed transitions (narrow_scope / amend_down), managing fips-native (port 30820) and iroh_rung MoQ ring-buffer reflection, and triggering RhioSidecarDaemon NATS JetStream cluster fanout.

  4. Phase 4: Bilateral Transit IOU Ledger & Barter Settlement: - Extend AccountStore / ReceiptsMixin (via fleetmesh_node.storage.locator.Locator on SQLite and PostgreSQL) to track unsettled transit_bytes_out debt and credit bartered repayments from blob_replication, compute / dvm, and mediation.

  5. Phase 5: ``meshctl stream`` CLI & Conformance Vectors: - Add meshctl stream commands (start, watch, transit-status, settle), add video-transit.json conformance test vectors to core/vectors/, and register the PIURI in scripts/check-interop.py and scripts/check-implementing.py.