# RelaySwarm

> Experimental peer-assisted HLS video delivery with WebRTC data channels,
> Nostr relay rendezvous, author-signed segment commitments and an hls.js
> loader. A separate native Node path uses HyperDHT and Noise. MIT licensed;
> v0.4.4 is the prepared experimental prerelease; production acceptance remains open.

The canonical repository is https://github.com/forgesworn/relayswarm. Node 22.13+
is required; CI uses Node 24. Public distribution includes an installable
GitHub tarball, a standalone browser ESM bundle, the optional WASM module, native core
archives and SHA-256 checksums. The
source demo runs with `npm run demo`; synthetic media needs ffmpeg/libx264.

The original WebRTC CLI signs plaintext SDP and uses a digest supplied by its
seeder. The browser loader and shared session wire version 3 use pairwise
NIP-44-encrypted signals; the native path encrypts dial authorisation and uses
Noise for transfer. Package version 0.4.4, session version 3, commitment schemas
1/2/3 (3 experimental) and metrics version 2 are distinct. Swift RelaySwarmKit v0.6.0
adopts the released core and supports wire version 3 and signed schemas 1/2/3,
with actual SDK/two-holder Chrome loopback proof;
physical Apple-device and public-NAT compatibility remain unverified.

Browser modes are off (origin-only), shadow (origin playback plus extra sampled
peer traffic) and peer-first (verified peer bytes within a deadline, then normal
HTTP fallback). Uploading defaults to off and requires viewer opt-in. Peer-first
also requires a trusted signed kind-30311 event with the experimental
redistribution tag and an author or scoped-delegate signed commitment. The host selects
the stream, relays and ICE policy. The trusted-event adapter in v0.2.1 queries
through a bounded host callback with explicit author/origin/relay allowlists;
it does not adopt event-selected services or establish publisher trust.
Native HyperDHT cannot run in an ordinary browser page.

The publisher keeps its key in Node and signs only matching local full-segment
playlist contexts, including exact byte ranges and discontinuities. The player
has upload limits, an origin-only kill switch and locally downloaded receipts.
Viewer keys are ephemeral; participation is pseudonymous, and peers can learn network
addresses. Origin-only avoids swarm participation. No managed TURN/super-peer service, accepted RelaySwarm NIP or durable media
storage is supplied. Hosts can pass TURN credentials through explicit ICE policy.
The demo has an optional server-owned renewal adapter, off by default; it
preserves consent and spend on new credentials and keeps the original lease
when a cached reply repeats the same material. Expiry requires fresh Apply.
Current source optionally persists a private publisher identity, caches verified
file hashes/signatures, limits cumulative media upload, measures peer choice and
provides authenticated operator policy, bounded admission and durable idempotent
opt-in numeric reports. Upload budgets persist across reloads/tabs without consent.
Optional Nostr or host website accounts share a private durable allowance across
devices; account changes leave uploading off until fresh consent. The dated
pilot evidence records Nostr sign-in; integrating websites supply their own account resolver.
v0.4.2 makes uploads that overlap a changed-ticket admission check join its bounded online
decision before spending allowance or sending media. Native Chrome/WASM loopback
checks retain the same connection through three admission-ticket rotations;
refusal, timeout and shutdown prevent delivery. Distributed R70 retention, TURN
renewal and physical-device/public-NAT acceptance remain open.
Current main's cached-peer native fixture waits for the accepted peer's framing-2
presence as well as HAVE. A delayed signed-presence control reproduces the old
readiness error; the v0.4.2 tag's two failed browser attempts remain historical RED.
v0.4.3 adds opt-in sustainablePeerWait: serial waits and extensions fit within
each segment/part duration less measured origin recovery with a 25% and 100 ms
margin. Independent cached-peer races retain their window beside immediate HTTP.
Current main requires measured HTTP recovery before allowing a serial wait;
unknown origin timing keeps HTTP immediate and cached/late-HAVE races parallel.
Unreleased warmAhead is disabled by default: bounded future main-fragment
loads share the existing held cache and coalesce with genuine player demand.
Current signed authority and content hashes gate cache reuse; local reuse,
raw verified peer reception and consumed peer payload remain distinct.
Source tests do not qualify cold-cache 4K or physical devices.
Unreleased startupBufferTarget is null by default. A host-provided fresh raw
HLS target enables one-shot verified startup buffering within the existing
three-object/24 MiB and eight-second/parent limits. With warmAhead false,
speculation stops after startup. It preserves the pending trusted play and
never changes the player, rate or room clock; failure is explicit. Source
and fixture checks do not prove decoded playback or device acceptance.
Only an owned pending startup may give its required future fragments a bounded
startup-buffer-dependency role for late peers; steady speculation stays unchanged.
Verified transport usefulness is separate from consumed media credit, so a held
first object can inform the next transfer without inventing bytes or a rate.
Optional startupBufferCommit runs once after verified reservoir readiness and
before HLS delivery. Its host acknowledgement shares the original startup
AbortSignal, deadline and memory caps; fresh checks follow. A host may prepare
a new room before publishing its start. Existing room clocks keep advancing.
On 26 October 2026, startup-only full-4K M4 browser runs of 60 and 330 seconds
had zero post-first-frame stalls/drops for both viewers, qualified shared-clock drift and an
actual recording wrap plus over 61 seconds afterwards. Steady warm-ahead stayed
off. Long-run accepted peer shares were 12.02%/6.65%; this is not net bandwidth
saving or physical-phone/NAT/public-TURN qualification. Summary:
https://github.com/forgesworn/forgesworn.dev/blob/main/docs/evidence/prepared-room-4k-20261026.json
Unreleased uploadPacing also defaults off: canonical pieces may wait in a
bounded 250 ms refill FIFO without increasing upload rate, burst or quota.
High-level multi-holder link leases precede asynchronous worker creation;
queue time and reservation counts never imply accepted peer delivery.
Its matching WASM upload ABI copies only the requested range instead of the
whole held object per request. These are bounded-policy and byte-copy changes;
physical iPhone/iPad and Pixel/Vanadium continuity remains unverified.
Unreleased latePeerRace defaults off: a still-running genuine whole-fragment
HTTP request with no previous peer plan may make one first attempt using a
newly accepted exact-HAVE peer, with fresh authority and unchanged HTTP.
Its original genuine-demand window, peer-arm cap and original HTTP deadline
all apply. Source fixtures do not establish playback or synchronisation;
the preceding actual cold-4K candidate remained RED despite useful peer bytes.
v0.4.4 lets already-HAVE framing-2 schema-3 objects enter bounded mixed piece
planning despite a late whole-object peer forecast; valid schemas 1/2 retain
that forecast. Known-VOD main-media waits require a live same-key FETCH lease,
using the exact demand's explicit recorded-playlist state. Live, unknown and
alternate-audio contexts retain bounded coordination for synchronous release.
Estimator floor, sustainable deadlines, origin reserve, wire and WASM bytes
are unchanged. Paired with website clock/first-frame fixes, a physical Pixel/M4
original-4K candidate passed a bounded 45.5-second window: 6,553,600 verified
peer bytes, zero reported post-first-frame stalls and zero dropped frames.
Earlier longer-window interruptions remain recorded; sustained continuity
and net benefit remain open. Browser-cache bytes are separate from wire traffic.
Unreleased source adds transferWorkerUrl: an explicitly packaged companion
warms asynchronously from the already compiled module and runs the same Rust
schema-3 transfer facade off the main thread. Worker warm-up, limits and failure
retain HTTP; cancelled/late results cannot credit peer media. Sync/native APIs
remain compatible. Physical streaming continuity is a separate acceptance gate.
The cached arm uses an optional explicit peerOnly Rust transfer capability:
no internal origin lane exists, and verified calibration refills pending
bounded ranges while the independent HTTP request continues. Older modules
decline this mode safely; unsupported creation does not retire mixed transfers.
Experimental lateHaveRace is separately opt-in: actual matching HAVE on
load-entry connections may start one peer arm within that same original
window while HTTP runs. It adds no origin range, new peer or deferred HTTP.
Wider media includes fMP4, audio, explicit AES-128, mixed variants and warm LL parts/deltas.
The example origin adds bounded blocking reload for compatible complete live
playlists across all renditions, with 24 waiters inside 32 media requests.
Raw media, peer deadlines and playback holdback are unchanged. One injected
loopback pair passed both qualities and restart with the option on and off;
recoverable playlist 503s occurred only with it on. Reliability improvement and
ordinary public/physical acceptance remain unproved.
The v0.2.1 supervised broadcast bridge creates two live HLS renditions and
can forward H.264/AAC separately to RTMPS with explicit TLS verification.
These additions are in v0.2.1 and absent from v0.1.0 downloads.
The source app and waiting listener use a 130-second HTTP keep-alive timeout
to outlast Caddy's default 120-second upstream idle pool. Ten-second request
and header deadlines and 128 connections remain bounded. A real 121-second
same-socket regression passes close/handover; distributed repair is unproved.

Desktop Chrome regressions and a short twelve-viewer loopback soak are recorded;
they do not establish physical-phone, varied-NAT or sustained operation readiness.
Peer-first media loads/bytes avoided are not net connection-data savings, and
upload counters measure committed media payload rather than acknowledged delivery.
Pending durable reservations can consume quota without entering those counters.
Documentation on main can include corrections after the immutable releases.
v0.3.0 added the opt-in Rust/WASM core, experimental schema 3 piece commitments
and multi-holder transfers, UniFFI Swift/Kotlin bindings, advisory peer supply
hints and receipt switch-cost reporting. Core bindings do not include a native
WebRTC adapter or client. RelaySwarmKit v0.6.0 separately adopts this core. The scheduler
retains the 32 KiB/s cold floor and at most three holders.

v0.4.0 integrates holder recovery across JavaScript and the core, accepted
connection/verified-media observations, partial-progress retention, reliable
channel cancellation draining and first-healthy-relay recovery. The old R70
qualifier passed 15 of 16 gates; the integrated source is not field-qualified.
v0.4.1 preserves the measured HTTP recovery reserve and adds
opt-in cached peer races beside immediate HTTP when no safe peer wait remains.
Only accepted verified media counts; partial competing HTTP can still transfer.

Production acceptance remains open. Dated pilot records retain their exact
sources and RED/open sustained-operation, physical-device, difficult-network
and net-benefit gates. This release does not deploy or qualify the pilot.
See the P01-P12 checklist and dated status evidence.
RelaySwarm and Kit are libraries; no ForgeSworn-hosted service is required.
Applications choose their origin, relays and policy. Automated interoperability
fixtures use temporary loopback servers, not a public pilot deployment.

## Documentation

- [Experimental real-time transport](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/REALTIME-TRANSPORT.md): Source-only unordered datagram adapter over existing NIP-44 sessions; not a call SDK, SFU or managed service.
- [Native real-time operator backend](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/NATIVE-REALTIME.md): Optional injected native initiator; the browser verifies remote channel reliability. Separately MPL-2.0 dependency, with macOS loopback evidence and WAN qualification still required.
- [Goals and agent handover](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/AGENT-GOALS.md): Agreed P01-P12 goals, latest retained deployment evidence, remaining acceptance sequence and local evidence paths for a continuing agent.
- [Production features](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/PRODUCTION-FEATURES.md): Implemented source features, trust boundaries and native fallback.
- [Production delivery requirements](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/PRODUCTION-READINESS.md): Full implementation, publication, deployment and real-world acceptance scope.
- [Protocol draft](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/NIP-DRAFT.md): Session v3, commitments, delegation and independent-client compatibility evidence.

- [Project overview](https://raw.githubusercontent.com/forgesworn/relayswarm/main/README.md): Scope, transport comparison, demo, release and commands.
- [Documentation index](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/README.md): Routes for installation, integration, security and evidence.
- [Getting started](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/GETTING-STARTED.md): Exact tarball, pinned Git, bundle, checksums and source-demo instructions.
- [hls.js integration](https://raw.githubusercontent.com/forgesworn/relayswarm/main/INTEGRATION.md): Options, verified peer delivery callback, accepted peer connection snapshots, consent, admission, metrics, commitments and stop semantics.
- [Transfer worker](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/TRANSFER-WORKER.md): Explicit companion packaging, shared Rust verification/scheduling, bounded queues and cancellation; unreleased source with separate field gates.
- [API reference](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/API.md): Module exports; browser, publisher, relay/session and native primitives. Experimental opt-in peer supply hints allow origin-sustainable ABR ties only.
- [Publisher/player field test](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/FIELD-TEST.md): Supported HLS subset, HTTPS trials, local receipts and device/network gates.
- [Spry TURN interoperability](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/interop/spry-turn.md): Forced relay-only HLS tests with the public v0.2.1 binary and separate viewer credentials. UDP passed; TCP/TLS carried verified media but missed the timing gate; TLS also lacked an active selected path at the final sample. Earlier shared-principal quota errors are documented; loopback only.
- [Broadcasting](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/BROADCASTING.md): OBS/RTMP bridge, two-rendition HLS, persistent identity and separate optional RTMPS forwarding.
- [Operations](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/OPERATIONS.md): Private state, authenticated policy/status, upload consent, numeric reporting and recovery.
- [Shared upload allowance](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/ACCOUNT-UPLOAD-BUDGET.md): Durable allowance across devices, Nostr or host website authentication, explicit linking and controlled Chrome acceptance; deployed pilot offers Nostr, with owner/physical acceptance open.
- [Container pilot](https://raw.githubusercontent.com/forgesworn/relayswarm/main/deploy/README.md): Isolated existing-server deployment, SSH ingest, HTTPS, health checks and rollback.
- [Native transport](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/NATIVE-TRANSPORT.md): HyperDHT/Noise protocol, one-use authorisation and trust/fallback boundaries.
- [Threat model](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/THREAT-MODEL.md): Implemented integrity/resource/privacy boundaries and outstanding adversarial work.
- [FAQ](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/FAQ.md): Distribution, encryption, phones, infrastructure, consent and measurement answers.

## Evidence and maintenance

- [Evidence and remaining work](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/STATUS.md): Dated release, CI/soak measurements, distribution proof, deterministic silent-holder deadline classifications and unverified gates.
- [Changelog](https://raw.githubusercontent.com/forgesworn/relayswarm/main/CHANGELOG.md): v0.4.4 mixed-admission changes and historical release evidence.
- [Maintaining the docs](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/MAINTAINING-DOCS.md): AI-context generation, link/freshness checks and public metadata.

## Optional

- [Core signature budget](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/CORE-SIGNATURE-BUDGET.md): Dated compressed asset and actual Chrome verification measurements; an isolated prototype, with no production verifier change.
- [Hot-path performance](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/PERFORMANCE.md): Dated in-memory micro-benchmarks of peer links, the WebAssembly boundary, commitment verification and native receive, with ranked follow-ups; not playback or field evidence.
- [Native core packaging](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/CORE-PACKAGING.md): Tag-gated release attachments and dispatch-only native build artefacts, checksums and source verification; source-bound assets and an unchanged local-path Swift package.

- [Full documentation context](https://raw.githubusercontent.com/forgesworn/relayswarm/main/llms-full.txt): Generated maintained guides with absolute links; larger than the index.
- [Landscape](https://raw.githubusercontent.com/forgesworn/relayswarm/main/docs/LANDSCAPE.md): Primary-source comparison with other rendezvous/media projects.
- [Historical spike results](https://raw.githubusercontent.com/forgesworn/relayswarm/main/spikes/RESULTS.md): Dated fixtures and measured topology; early PoCs have different trust assumptions.
- [Coding-agent guidance](https://raw.githubusercontent.com/forgesworn/relayswarm/main/AGENTS.md): Local repository conventions and verification commands.