Documentation Index
Fetch the complete documentation index at: https://docs.livepeer.org/llms.txt
Use this file to discover all available pages before exploring further.
Mechanism Map
Seven mechanisms run continuously across the Network. Each answers a different coordination problem; none requires central scheduling. The on-chain Protocol is referenced for ground truth (stake, deposits, registry) but is not in the per-job hot path. The first five mechanisms run thousands of times per minute across the Network. The last two are anchor points: settlement happens occasionally, the heartbeat once per round.Property Provenance
Every property the Network preserves traces back to a specific protocol decision: a Livepeer Improvement Proposal that ratified the change, and a contract or codebase that implements it. The provenance is what lets a researcher cite the running Network with confidence. AI extension was bootstrapped without a dedicated LIP. From 2023, the LIP-90 SPE convention authorised AI work by funding the AI Video Special Purpose Entity through Stages 1 to 4, demonstrating a deliberate property of the SPE model: pipeline-level capability does not need a hard fork. LIP-100 (Cascade, proposed May 2025) later formalised AI-first gateways as a protocol-level upgrade, ratifying what the SPE pipeline had already shipped.Orchestrator Discovery
Discovery is the first thing a gateway does. It reads the on-chain registry to get a list of operator addresses, then resolves each address to a service URI and asks for capability and price. The discovery loop lives indiscovery/discovery.go. A gateway holds an OrchestratorPool of []*url.URL candidate orchestrators, loaded from the Livepeer subgraph or supplied as a static list. The gateway calls GetOrchestratorInfo on each in parallel.
The pool is a moving target. Active orchestrators come and go each round; suspensions clear after a cooldown. Discovery reruns on every new session and on a periodic refresh.
Capability Advertising
Capability advertising is what an orchestrator publishes so a gateway can decide whether to send work. The advertisement is the response toGetOrchestratorInfo and carries everything the gateway needs to evaluate the operator.
Capability matching uses caps.bitstring.CompatibleWith() defined in core/capabilities.go. The check at the gateway is a simple AND across the bitstrings: the gateway’s required capability bits must be a subset of the orchestrator’s offered bits, and all per-model constraints must be satisfiable.
Session Selection
Selection is the gateway’s decision: of the candidates that returned validOrchestratorInfo, which one to open the session with. The decision combines capability match, price ceiling, latency, and operator reputation.
Once selected, the gateway opens a session by sending the first segment with an attached ticket. The orchestrator validates the ticket, queues the segment, and processes the work. The session stays open for the duration of the job; for live workloads it stays open until the stream ends.
Job Dispatch
Job dispatch is the per-unit hand-off. Each segment or frame travels with a ticket attached. The dispatch loop is incore/orchestrator.go:transcodeSegmentLoop. Each orchestrator session has a SegmentChan of buffer size maxSegmentChannels = 4. The gateway POSTs each segment with a TicketSenderParams; the orchestrator’s ProcessPayment validates the ticket via Recipient.ReceiveTicket, debits the gateway’s session balance, and routes the segment to either a local transcoder or, if TranscoderManager is set, a remote transcoder selected by selectTranscoder from the byLoadFactor-sorted pool.
A single OrchestratorNode accepts at most MaxSessions concurrent sessions (default 10, raised by SetMaxSessions or auto-adjusted by AutoSessionLimit). Sessions inactive for transcodeLoopTimeout (70 seconds) are torn down.
Workload classes, lifecycle, state machine, failure modes.
Ticket Plumbing
Tickets are how value moves off-chain. Every dispatched segment carries one. Most are losing tickets that never settle; only winning tickets reach the chain. A ticket is a signed message with five fields the gateway sets and one the orchestrator validates: The win check combinesseed, the orchestrator’s recipientRand, and the round’s stored block hash: H(sig, recipientRand) < winProb × 2^256. Neither party can predict winners alone. The orchestrator queues winning tickets locally and redeems them on-chain in batches when gas conditions are favourable.
Settlement Triggers
Settlement is when the off-chain layer reaches into the on-chain Protocol. Three triggers cover every on-chain transaction in the per-job loop. Three more on-chain events are gateway-side and run alongside but outside the per-job loop:- Gateway exit: gateway calls
unlock()thenwithdraw()onTicketBrokerto recover unredeemed deposit and reserve - Bond changes: delegator or orchestrator calls
bond(),unbond(),rebond(),withdrawStake()onBondingManager - Service URI updates: orchestrator calls
setServiceURI()onServiceRegistrywhen its endpoint changes
Round Heartbeat
Rounds are the on-chain Protocol’s clock. Round transitions ripple through the off-chain Network in three ways. The off-chain Network does not stop or slow down at round boundaries. Job dispatch, ticket exchange, and discovery continue. What changes is which orchestrators are eligible for the next round’s reward call and which are now in the active set.Related Pages
Topology, traffic planes, on-chain anchor.
Market shape, settlement boundary, probabilistic micropayments, trust.
Workload classes, lifecycle, state machine, failure modes.
On-chain mechanics: rounds, staking, rewards, payments, upgrades.