Video Streaming & High-Demand Transit Routing ============================================= .. experimental:: 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. 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. 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``): .. code-block:: text +---------------------------------------------------------------------------------------+ | 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 | | // | | JetStream | | Op-Log | | & Firehose| | Video/Note| | | | & S3 Sync | | Ordering | | Blobs | | Delivery | +----------+ +-----------+ +-----------+ +-----------+ +-----------+ 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 /.m4s`` and account-priced at ``GET //.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/`` with 1024-byte chunked Merkle tree root verification (``tree_root``). - **ActivityPub & SSB**: Referenced as federated ActivityStreams 2.0 ``Video`` / ``Document`` attachments and SSB ``&.sha256`` blob links. 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. Dual Streaming Pipelines ------------------------ Fleetmesh establishes two complementary streaming pipelines tailored to latency, verification, and transport characteristics: .. list-table:: :widths: 22 39 39 :header-rows: 1 * - 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`` Cryptographic Manifests & Sub-Segment Verification -------------------------------------------------- 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/`` or ``P2PandaRung``. 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. 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.``) 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. 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. Operator Transit Routing & Capacity Shedding -------------------------------------------- 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. 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. Commercial Fee-Based Transit (Cashu HTTP 402 & Token Buckets) ------------------------------------------------------------- Fleetmesh supports two commercial settlement modes built directly on its shipped Cashu engines: 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 //.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 ``//.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. 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/`` (backed by ``sidecar_session_msat['video']``), unlocking stream access for the duration of the session. 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 ``//.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``.