Ship StreamDiffusion playground with hosted-signer trial credits

[rickstaa]

Ship StreamDiffusion playground with sign-in-gated hosted-signer trial

Context

We need to tell Livepeer's story and start funnels that drive real usage — that traffic is what lets us harden the stack. The product could be capability consumption, app-on-the-network deployment, or both; we don't have to pick yet. The goal is a visible showcase of our components working together, so visitors can either integrate them into their own project or decide to run their own apps on the network.

Outcome

A first-time visitor signs in before their first run (a"Sign in to run" CTA), then runs StreamDiffusion from the dashboard on a free-plan trial budget with a personal key.

Scope

• One hosted remote signer (Foundation free plan) with per-user ETH accounting — simplest thing that tracks spend against a cap.
• Sign-in required before the first run. A free-plan trial budget is allocated per account. No anonymous sessions — so there's no anonymous-session tracking or anti-farming to build, and hosted-signer spend stays bounded to known accounts from the first run (lower abuse surface).
• Sign-in flow on the dashboard; personal API key at /keys and embedded in the model page snippet.
• /models/daydreamlive/streamdiffusion runs StreamDiffusion through the signer using the realtime SDK.
• Card structure (camera in/out, arg controls, SDK+signer snippet) built manually but factored so another realtime workflow can be added by hand without rewriting the page.

Not in Scope

• Billing, paid tiers, workspaces, teams, multi-tenant user logic. (Personal keys only. Whether to make auth/account logic workspace-aware from the start vs. retrofit later is a separate call — owned by John, who built workspaces on the operator dashboard. See Notes.)
• Support for multiple payment houses.
• On-chain / LPT / ticket UX.
• Auto-generating cards from OpenAPI / container schemas (must remain possible later, not built now).
• Other capability cards beyond StreamDiffusion.
• Improvements to the SDK / snippet format to make the Python flow simpler.
• Live network data on the card.
• Polish, optimisation, scale.

Acceptance Criteria

• A first-time visitor is prompted to sign in before they can run the job ("Sign in to run"); there is no anonymous run path.
• Signed-in user runs the job on their free-plan trial budget; the snippet uses their key.
• Out-of-credit and other signer errors render via the shared ErrorState.

Success Metrics

• Primary: a non-team member lands on the dashboard, signs in, uses the card to try the job, and can run it from the Python snippet on their own machine.
• Secondary: landing → sign-in conversion on the playground CTA.
• Guardrail: signer spend per account stays inside the configured cap.

Notes / Dependencies

• Prior work: feat: integrate PymtHouse authentication flow website#50
• Context: https://www.notion.so/365660222d088124bf08ebb6c6127eba
• Confirm StreamDiffusion model slug + PymtHouse env values with Rick.
• Open question for John: is making the auth/account logic workspace-aware from the start meaningfully cheaper than retrofitting it later? If yes, consider folding it in; otherwise personal keys only as scoped.

[eliteprox]

Open question for John: is making the auth/account logic workspace-aware from the start meaningfully cheaper than retrofitting it later? If yes, consider folding it in; otherwise personal keys only as scoped.

Workspaces are a feature of Livepeer Dashboard, so it's configuration would be tied to the user account on this system, not the clearinghouse. However, this brings up an important question - which needs further design.

A workspace is meant to be the primary tenancy boundary for a developer or team. Everything operational is scoped to the active workspace:

Concern	Intended workspace scope
API keys	Created, rotated, revoked per workspace
Jobs / runs	History, traces, replay stored per workspace
Usage & limits	Spend, quotas, rate limits per workspace
Billing	Plan, payment method, invoices per workspace
Team	Members, roles, invites per workspace
Network view (signed-in)	GPU pool health and routing framed per workspace

This is important because SDK requests currently go to the Clearinghouse Signer Proxy, not the Livepeer Dashboard website. The API key created by Livepeer Dashboard will not be useful for anything related to streaming.

The clearinghouse does not specifically implement any sort of "workspace" feature. Settings are only defined per application.

For this to work without a separate API call (I'm not sure what you want to do with workspaces exactly), then a new deployment mode should be supported by the clearinghouse which allows for the platform application to proxy requests themselves

Workspaces being the tenant-boundary, in the clearinghouse this would be the application itself.

[eliteprox]

@rickstaa Below is an outline of the changes I recommend to be made on the clearinghouse side for this project.

There is another focus area to separately solve - media streaming from browser - but I understand this is essentially resolved in livepeer/go-livepeer#3938. Wiring up the gateway client into the browser should be tracked as a separate task.

Clearinghouse SDK — Architecture Diagrams

Option A · Platform M2M → PymtHouse OIDC direct · Dashboard credits only · go-livepeer JWKS unchanged

---

Diagram 1 of 3 — Full Flow — Three Phases

End-to-end view across session setup, the signing hot path, and async usage ingest. Dashboard is absent from both the token exchange and the signing path.

Phase 1 — Session Setup

flowchart LR
  subgraph PA["PLATFORM APP"]
    U["Platform User\nsession · any auth"]
    SDK["builder-sdk\nresolveExternalUserId\nM2M creds (scoped)\ntoken cache + refresh\nbeforeSign hook"]
  end

  subgraph PO["PYMTHOUSE OIDC"]
    MT["M2M Token Endpoint\nvalidates client_id + secret\nscope: sign:mint_user_token"]
    MJ["Mint User-Scoped JWT\niss: pymthouse\naud: livepeer-remote-signer\nclient_id · external_user_id · exp\nsigned by PymtHouse JWKS"]
  end

  subgraph DB["LIVEPEER DASHBOARD — credits management only"]
    BR["Balance Read\ndelegates to PymtHouse Usage API\ngranted − consumed = remaining"]
    HG["Hard Gate\nrefuses if granted = 0\nor platform calls at beforeSign"]
  end

  JW["go-livepeer JWKS config\nunchanged — already trusts\nPymtHouse JWKS endpoint"]

  SDK -->|"M2M creds + externalUserId"| MT
  MJ -.->|"JWT + exp + balance"| SDK
  SDK -.->|"optional: check balance"| BR
  PO -.->|"JWKS already trusted"| JW

Loading

Phase 2 — Signing Hot Path

flowchart LR
  subgraph PA2["PLATFORM APP"]
    BS["beforeSign() hook\ncached balance → gate\n→ 402 if exhausted\nforwardSignerRequest(jwt)"]
  end

  subgraph GL["go-livepeer REMOTE SIGNER"]
    JV["JWKS Validation\nPymtHouse JWKS · in-process cache\nzero outbound HTTP on warm cache\nextracts client_id · external_user_id"]
    RP["RemotePaymentState\nidentity bound on first request\nverified on every continuation\nno PymtHouse / Dashboard in path\n→ Kafka emit with identity fields"]
  end

  BS -->|"Bearer JWT"| JV
  JV --> RP
  RP -.->|"signed ticket"| BS

Loading

Phase 3 — Usage Ingest (async)

flowchart LR
  K["Kafka\ncreate_signed_ticket\nclient_id · external_user_id"]
  PI["PymtHouse Ingest\nusage_records\nclient_id · externalUserId\nidempotent by requestId"]
  DC["Dashboard Credits\nbalance = granted − consumed\nreads PymtHouse Usage API"]

  K -->|"emit"| PI
  PI -.->|"reads usage API"| DC

Loading

async · never blocks signing · PymtHouse is usage authority · Dashboard reads from it (no separate debit ledger)

---

Token exchange (PymtHouse OIDC direct)

• Platform SDK holds a PymtHouse M2M credential scoped to sign:mint_user_token only
• Calls PymtHouse OIDC /token with { client_id, client_secret, external_user_id }
• PymtHouse mints JWT: iss=pymthouse · aud=livepeer-remote-signer · external_user_id
• go-livepeer JWKS config unchanged — no deployment change needed

Signing hot path

• SDK presents cached JWT directly to go-livepeer
• PymtHouse JWKS validated in-process — zero outbound HTTP on warm cache
• Identity bound into RemotePaymentState on first request, verified on continuations
• Dashboard entirely absent from this path

Dashboard role (credits only)

• Not in the token exchange path at all
• Manages credit grants and policies per user
• Balance = granted − consumed, where consumed comes from PymtHouse Usage API
• No separate debit ledger — PymtHouse is the single usage authority

---

Diagram 2 of 3 — Trial Credits — Dashboard grants, PymtHouse measures

Dashboard owns the grant ledger (append-only). PymtHouse Usage API owns consumed amounts. Balance is always a read-time computation — no debit writes anywhere.

flowchart TB
  DG["Dashboard Grants Ledger\nlifetime_granted_usd_micros per (dashboard_user, app)\nset at sign-up or via Dashboard API · no debit entries"]
  PU["PymtHouse Usage API\nsum(network_fee_usd_micros) per (client_id, externalUserId)\nsource: Kafka ingest · authoritative consumed amount"]
  BC["remaining = granted − consumed\ncomputed on read · no write-time bookkeeping"]

  subgraph EA["Enforcement A — PymtHouse OIDC token exchange"]
    EA1["PymtHouse checks Dashboard balance\nbefore minting JWT\nrefuses if remaining = 0\n→ no JWT issued"]
  end

  subgraph EB["Enforcement B — beforeSign() platform hook"]
    EB1["receives cached balance from last exchange\nplatform returns 402 or passes\nstale by up to 1 JWT TTL — tunable"]
  end

  subgraph EC["Enforcement C — Token renewal gate"]
    EC1["balance re-checked at every renewal\ncaps over-spend to 1 JWT lifetime\nshorten TTL for tighter enforcement"]
  end

  DG -->|"feeds"| PU
  PU --> BC
  BC --> EA
  BC --> EB
  BC --> EC

Loading

Why no debit ledger in Dashboard

• PymtHouse already accumulates network_fee_usd_micros per user in usage_records via Kafka ingest
• Dashboard balance is always granted − sum(consumed) — a read-time computation, never a write
• Eliminates dual-consumer consistency risk: one source of truth for consumption
• Dashboard only ever writes grant rows — simple, append-only, never updated

PymtHouse OIDC checks balance at mint time

• At token exchange PymtHouse calls Dashboard balance read endpoint before minting
• Hard gate — no JWT means no signing at all for a zero-balance user
• Balance returned in token exchange response body (not JWT claims) for beforeSign use
• TTL tuning: 60s = strict, 300s = default, 3600s = low-frequency batch

---

Diagram 3 of 3 — SDK Token Lifecycle — Cold & Warm Paths

Step-by-step request flow through createHostedSignerProxyHandler(). Cold path performs a token exchange; warm path is pure in-memory with zero outbound HTTP until go-livepeer.

Cold Path — token not in cache

flowchart LR
  C1["1. authenticate()\nplatform session\n401 if null\nany auth model"]
  C2["2. resolveExternalUserId()\nstable string\ne.g. user:123"]
  C3["3. Token Exchange\nPOST PymtHouse OIDC /token\nclient_id · secret · external_user_id\n→ JWT + balanceUsdMicros + exp"]
  C4["4. beforeSign()\nplatform credit gate\nusage.balanceUsdMicros\nreturn 402 to block"]
  C5["5. Forward JWT → go-livepeer\nAuthorization: Bearer {jwt}\nPymtHouse JWKS in-process cached\nidentity → RemotePaymentState"]
  ERR["→ 402 trial_credits_exhausted"]
  CACHE["SDK Token Cache\nkey: externalUserId\nJWT · expiresAt · balanceUsdMicros\nlifetimeGrantedUsdMicros\nproactive refresh at 80% TTL\nre-exchange on 401 from go-livepeer\nbalance stale by up to 1 TTL"]

  C1 --> C2 --> C3 --> C4 --> C5
  C4 -.->|"blocked"| ERR
  C3 -->|"stored"| CACHE

Loading

Warm Path — token in cache

flowchart LR
  W1["1. authenticate()\n+ resolveUserId\nany auth model"]
  W2["2. Cache Hit\nJWT + balance\nzero network"]
  W3["3. beforeSign()\ncached balance\nzero network"]
  W4["4. Forward JWT → go-livepeer direct\nPymtHouse JWKS cached\nRemotePaymentState cached · pure crypto\nzero outbound HTTP\nno PymtHouse / Dashboard in path"]

  W1 --> W2 --> W3 --> W4

Loading

JWT claims: iss=pymthouse · aud=livepeer-remote-signer · client_id · external_user_id · exp · scope=sign:job

Response body: { jwt, expiresAt, balanceUsdMicros, lifetimeGrantedUsdMicros }

M2M credential scoped to sign:mint_user_token only — cannot call Usage API, Builder API, or any other PymtHouse endpoint.

Hot path (warm, per-ticket)

• In-memory cache lookup — zero I/O
• beforeSign with cached balance — zero I/O
• HTTP POST to go-livepeer with Bearer {jwt}
• PymtHouse JWKS in-process (cached) + RemotePaymentState cached — pure crypto

Out of hot path

• Token exchange with PymtHouse OIDC — once per session, proactive at 80% TTL
• Balance read (Dashboard → PymtHouse Usage API) — only at exchange time
• JWKS fetch from PymtHouse — once by go-livepeer, then TTL-cached
• Kafka ingest + usage writes — fully async, never blocking