Top-level map of the Livepeer Modules Suite: what the domains are, how a unit of work
flows through them, and where the boundaries sit. This is a bird's-eye view — each
module's detail lives in docs/product-specs/.
Status. Confirmed against eight onboarded repos: supply-side core (livepeer-network-modules), demand-side LOC (livepeer-open-clearinghouse), AI/video runners, AI/video gateways, and off-network observability. Reference Apps, a daydream gateway, and vtuber runners remain not-yet-onboarded.
The Livepeer Modules are the productized features that let participants use the Livepeer protocol to get work done (video transcoding, AI inference, and related media compute). Conceptually they divide into four concerns:
- Demand side — Gateways and the Reference Apps built on top of them submit work and pay for it.
- Supply side — Orchestrators, optionally fronted by Pools, perform the work and earn payment.
- Coordination — Service Registry and Discover let the demand side find and select the right supply.
- Settlement — Payment moves value per unit of work; the Payment Clearinghouse settles and accounts for it. SDKs cut across all of the above.
┌──────────────────────────────────────────────────────────────┐
│ Reference Apps │
│ (example apps built on a Gateway / SDKs) │
└───────────────────────────────┬──────────────────────────────┘
│ uses
▼
┌──────────────┐ discover/select ┌───────────┐ register/advertise ┌──────────────────┐
│ Discover │◀───────────────────│ Gateway │───────────────────────▶│ Service Registry │
│ (selection) │ │ (demand) │◀────────────────────── │ (capabilities) │
└──────────────┘ └─────┬─────┘ looks up endpoints └────────┬─────────┘
│ submit work + payment │ advertise
▼ ▼
┌──────────────┐ fronts capacity ┌──────────────────┐
│ Orchestrator │◀───────────────────────│ Pools │
│ (supply) │ │ (capacity aggreg.)│
└──────┬───────┘ └──────────────────┘
│ work done → payment tickets
▼
┌──────────────┐ settle/account ┌──────────────────┐
│ Payment │───────────────────────▶│ Payment │
│ (micropay) │ │ Clearinghouse │
└──────────────┘ │ (+ SDKs) │
└──────────────────┘
Narrative (provisional):
- Service Registry — Orchestrators advertise where they are and what they can do (endpoints, supported capabilities, capacity).
- Discover — A Gateway queries discovery to find candidate orchestrators and selects among them (by capability, price, latency, reliability).
- Gateway — The demand-side entry point. It accepts work from apps/users, opens sessions with selected orchestrators, streams work to them, and sends payment.
- Pools — Optionally aggregate many orchestrators/workers behind one logical endpoint, so a Gateway sees pooled capacity rather than individual nodes.
- Orchestrator — Performs the work and returns results, exchanging it for Payment.
- Payment — Off-chain, per-unit micropayments flow from Gateway to Orchestrator as work is performed.
- Payment Clearinghouse — Settles, reconciles, and accounts for those payments, exposing SDKs for integration.
- Reference Apps — Demonstrate the whole loop end to end on top of a Gateway.
The first repo confirms the supply-side shape. The orchestrator is not a worker binary — it's a workload-agnostic capability broker (one per host) plus payment, publishing, and trust daemons. The broker:
- reads one declarative
host-config.yaml, - routes inbound paid requests by
Livepeer-Capabilityheader to a declared Runner (the backend) wrapped in a fixed interaction mode (http-reqresp,http-stream,ws-realtime,rtmp-ingress-hls-egress,session-control-plus-media, …), - and reports usage to the payment daemon. New capability under an existing mode = a YAML edit, no code.
Discovery is hybrid: an on-chain pointer (ServiceRegistry/AIServiceRegistry
getServiceURI) → an off-chain, cold-key-signed manifest of capability tuples.
A firewalled secure-orch holds the cold key and signs manifests (operator-driven, or
via an opt-in agent that auto-signs only within an operator-authored policy envelope —
plan 0042); the public orch-coordinator only scrapes and publishes; every resolver
re-verifies the signature.
Payment is probabilistic micropayment tickets settled via the on-chain TicketBroker.
Concrete runners now exist in two repos: the openai-runners repo ships OpenAI/Cohere-shaped AI backends (chat, embeddings, audio, TTS, image, rerank), and the transcode-runners repo ships video backends (VOD transcode, ABR ladder, and a live RTMP→HLS runtime). Both implement the broker↔runner HTTP contract and report work units back to the broker.
The live path is one of the suite's fully cross-repo data flows, driven by the transcode-gateway:
transcode-gateway (owns RTMP
:1935, opens/refills/closes LOC sessions, relays frames) → broker (session authority + payment envelope from LOC) → transcode-runners live-runner (RTMP ingest + HLS, emittingoutput_secondsusage events back to the broker)
This is the live-session-gateway-ingest@v0 mode (the transcode-runners repo calls the
topology "Option B"). LOC provides the route/payment/session control plane; the gateway
remains the in-path video surface and RTMP relay.
See docs/repos/livepeer-network-modules.md
for the component map and the glossary for terms.
The Payment Clearinghouse is how app
developers reach the network without managing wallets or keys. It is non-custodial at
the user boundary: developers hold a wei credit balance; an operator-owned pooled
wallet (held only by payment-daemon) signs every ticket.
It operates in handoff mode — it is the control plane, not the data plane:
- The customer's SDK calls the clearinghouse to open a job (one-shot) or session (long-lived, refillable).
- The clearinghouse resolves a route via
service-registry-daemon, checks the credit balance, mints a ticket viapayment-daemon.CreatePayment, and encumbers expected value at issuance. - It returns the signed envelope; the SDK talks to the orchestrator broker directly and reports actual usage back for settle-time reconciliation.
So in the clearinghouse model the gateway role is split: control plane (auth, credit,
discovery proxy, mint) in the clearinghouse; data plane (interaction-mode transport,
Livepeer-Payment) in the SDK. It consumes the supply-side daemons (payment-daemon,
service-registry-daemon) over Unix-socket gRPC.
There are also two full in-path gateways that now consume LOC instead of local
daemon sidecars: the openai-gateway
(OpenAI-compatible AI, fronting the openai-runners) and the
transcode-gateway (video, owns the
RTMP endpoint, fronting the transcode-runners). They open LOC jobs/sessions, receive a
single selected broker route plus Livepeer-Payment, forward work in-path, and settle
actual usage back to LOC. Customers pay nothing in v1; the gateway operator pays from its
LOC credit balance.
So there are now two main demand-side application shapes sharing LOC: customer handoff (customer credit + SDK talks to broker directly) and operator-funded in-path gateways (gateway operator credit + gateway stays in the data path). See Gateways.
A separate axis from supply/demand: two repos track on-chain activity rather than providing or consuming network work.
- protocol-explorer — a Rust + Postgres data
platform that indexes every Livepeer event on Arbitrum One, prices monetary activity per
block (Uniswap V3 TWAP × Chainlink, deterministic replay), derives stake/profile/rollup
analytics, and serves a versioned HTTP API + web explorer. It reads the same contracts
the network side writes to (
BondingManager,TicketBroker,RoundsManager,LivepeerToken, Governor) — directly from chain, not via the suite's daemons. It is the analytical mirror of the network's on-chain output. - network-bot — a Discord reporting bot whose sole upstream is the explorer's API (typed client). It posts payout digests and daily/weekly/monthly summaries, and (commands mode) offers per-user subscriptions + DM alerts.
network side ──writes──▶ Livepeer contracts (Arbitrum One) ──read──▶ protocol-explorer ──API──▶ network-bot ──▶ Discord
(orchestrators/payment/ (index + value +
gateways via on-chain analytics + SPA)
tickets/rewards/rounds)
Each module is its own repository (its own deploy/release unit) mounted under
modules/<name>/. The suite favors explicit, narrow interfaces between modules:
- The Gateway depends on Discover and the Registry for coordination, and on Payment for settlement — not on orchestrator internals.
- Orchestrators and Pools are interchangeable from the Gateway's perspective: a Pool presents an orchestrator-shaped interface.
- SDKs are the only sanctioned client surface for the Clearinghouse (and likely Gateway) APIs; apps should consume SDKs rather than reimplement protocol details.
These boundaries are the thing to protect as the suite evolves. Where they are enforced mechanically (lints, contract tests, schema validation) will be documented per module as repos are onboarded.
| Concern | Where to look |
|---|---|
| Per-module overview & status | docs/product-specs/ |
| Operating principles | docs/design-docs/core-beliefs.md |
| Submodule workflow / release tracking | docs/guides/git-submodules-primer.md |
| The actual code | modules/<name>/ (git submodules) |