@@ -17,15 +17,17 @@ This repository is the standalone Live Runner extraction from
1717 challenges, validates ` live ` and ` fixed ` ticket batches, charges sessions,
1818 and queues winning tickets for direct Ethereum redemption.
1919- ` livepeer-signer ` serves the retained unversioned signing, payment generation
20- and discovery routes, with optional authorization webhooks. Payment state is
20+ and discovery routes, with required on-chain configuration and optional
21+ authorization webhooks. Payment state is
2122 client-held and signed; replicas sharing a key and webhook configuration are
2223 interchangeable.
2324- ` livepeer-chain ` implements all 17 approved direct Ethereum commands.
2425 State-changing commands simulate and estimate gas first, and require
2526 ` --submit ` to broadcast. ` --wait ` waits for inclusion in a successful receipt.
26- - Outbound runner, generated proxy, static health, and chain RPC destinations
27- have separate exact host: port grants. Private and special-use addresses are
28- denied by default at dial time.
27+ - Outbound runner, generated proxy, and static health destinations have
28+ separate exact host: port grants. Private and special-use addresses are denied
29+ by default at dial time for these clients. Ethereum RPC, discovery, and
30+ webhooks use operator-configured endpoints without destination grants.
2931- Ethereum contract calls, transaction signing and account access stay in
3032 ` eth ` ; ticket, sender, recipient and redemption code stays in ` pm ` .
3133- All executables expose version, help, and shell completion. Boa loads strict
@@ -61,8 +63,9 @@ bin/livepeer signer --config /absolute/path/to/signer.toml
6163bin/livepeer chain status --config /absolute/path/to/chain.toml
6264```
6365
64- Use ` --print-config ` to inspect an audited TOML view. It omits direct secrets,
65- secret file paths and the static runner file path. Boa reads secret files as
66+ The orchestrator and chain commands support ` --print-config ` to inspect an
67+ audited TOML view. It omits direct secrets, secret file paths and the static
68+ runner file path. Boa reads secret files as
6669exact bytes, including a trailing newline, so operator-managed files or
6770secret-manager mounts must contain precisely the intended credential. A direct
6871environment secret and its file path cannot both be set. Direct secret flags
@@ -106,9 +109,9 @@ listener remains loopback and serves only `/metrics`, `/healthz`, and
106109` /readyz ` .
107110
108111Custom CA bundles can be assigned independently to runner traffic, generated
109- session proxies, static health checks, signer discovery and chain RPC . Each bundle extends the
110- system trust roots for only that destination purpose; certificate verification
111- remains enabled .
112+ session proxies, and static health checks. Each bundle extends the system trust
113+ roots for that destination purpose; certificate verification remains enabled.
114+ Ethereum RPC clients use system trust roots without custom CA flags .
112115
113116## Paid operation
114117
@@ -119,10 +122,16 @@ session auth tokens. Challenges, balances and nonce replay guards stay in
119122memory; SQLite holds winning tickets (including their redemption randomness),
120123redemption attempts and chain activity observations. Restarting requires new
121124paid sessions while stored winners remain redeemable. The signer key is the
122- ticket sender. Configure signer RPC, chain ID
123- and controller together: paid generation
124- requires a current coherent sender-funds observation. Without RPC, signing
125- identity and discovery remain available, but paid generation returns 482.
125+ ticket sender. Paid generation requires a
126+ current coherent sender-funds observation. The signer requires
127+ on-chain configuration at startup, including when used for identity signing
128+ or discovery. ` ChainID ` optionally asserts the RPC's chain ID; when omitted,
129+ the signer uses the RPC's chain. Controller and ETH/USD feed defaults match
130+ go-livepeer's Arbitrum mainnet addresses: respectively
131+ ` 0xD8E8328501E9645d16Cf49539efC04f734606ee4 ` and
132+ ` 0x639Fe6ab55C921f74e7fac1ee960C0B6293ba612 ` . Override both when using another
133+ chain. Its TOML keys use implicit Go field names, as shown in
134+ [ ` configs/signer/config.example.toml ` ] ( configs/signer/config.example.toml ) .
126135The orchestrator SQLite file must be owner-only.
127136
128137Configure exactly one orchestrator conversion source: a fixed ` wei_per_usd ` ,
@@ -133,33 +142,82 @@ priced discovery/reservations. Existing sessions retain their agreed wei
133142price. USD/hour discovery is normalized to USD/second alongside wei/second.
134143Off-chain operation accepts quoted runner prices but advertises free service.
135144
136- Paid signer configuration requires positive ` max_live_price_usd_per_second ` and
137- ` max_fixed_price_usd ` and exactly one ` wei_per_usd ` or ` eth_usd_feed ` . Feed
138- observations refresh every 30 seconds and expire after ` price_max_age ` (two
139- hours by default). Rates and ceilings are compared exactly. An unavailable
140- fresh rate returns 503 and makes the signer unready; a price above a ceiling
145+ Signer configuration requires ` KeyFile ` , an RPC URL through ` RPCURLFile ` or
146+ ` LIVEPEER_SIGNER_RPC_URL ` , and positive ` MaxHourlyPrice ` (USD/hour) and
147+ ` MaxFixedPrice ` (USD/request), with USD implicit. Live ceilings are divided by
148+ 3600 before comparison with wei/second quotes. ` ETHUSDFeed ` supplies the rate
149+ unless ` WeiPerUSD ` overrides it with a fixed conversion, mostly for testing;
150+ the fixed rate never refreshes or expires. Feed observations refresh every
151+ 30 seconds and expire after ` ETHUSDMaxAge ` (two hours by default). Rates and
152+ ceilings are compared exactly.
153+
154+ If the feed is unavailable at startup, the signer starts unready and retries.
155+ A failed refresh preserves the last observation only until its expiry. Once
156+ that observation is stale, ` /readyz ` and payment generation return HTTP 503;
157+ identity signing and discovery remain available. A fresh successful observation
158+ restores rate availability. A price above a ceiling
141159returns 481. Request and webhook wei ceilings apply as additional limits.
160+ ` /readyz ` also makes a bounded canonical chain/funds read: RPC or contract
161+ failures, an empty deposit or total reserve, and an imminent withdrawal return
162+ 503 . Readiness recovers on the next successful probe. Recipient-specific
163+ claimable reserve is still checked when paying that recipient. ` /healthz `
164+ reports process liveness independently of payment readiness.
142165
143166The signer limits per-ticket EV, batch EV and face value relative to deposit;
144- see ` max_ticket_ev ` , ` max_batch_ev ` , and ` deposit_multiplier ` in its example.
167+ see ` MaxTicketEV ` , ` MaxBatchEV ` , and ` DepositMultiplier ` in its example.
168+ ` DepositMultiplier ` must be at least one; explicitly setting zero is rejected.
145169It issues enough tickets to reach at least the greater of the fee and one
146170ticket's expected value, then carries unused expected value in signed state.
147171The state is not a replay database: reusing an earlier signed state can yield
148172another batch, and retries need not return identical bytes. The recipient
149173rejects duplicate tickets.
150174The recipient checks claimable reserve, withdrawal timing and outstanding
151175winning liability across sessions. Ethereum reads use canonical block-hash
152- snapshots with Arbitrum's L1 clock and the last initialized round. Refresh
153- returns 480 before parameter/auth expiry and resets the nonce on new randomness.
154-
155- Optional signer authorization uses ` auth_webhook_file ` , purpose-scoped grants
156- and CA, and a file-backed JSON map in ` auth_webhook_headers_file ` . The webhook
157- receives request headers and the proposed updated payment state after ticket
158- calculation, and returns ` status ` ,
159- ` reason ` , Unix-second ` expiry ` , ` auth_id ` , and optional ` maxPrice ` (wei per
160- second or fixed request). Successful authorization is cached in signed state
161- until expiry; identity and price ceilings remain enforced. Changing the
162- webhook URL or configured headers invalidates this cache. Redirects are refused.
176+ snapshots with Arbitrum's L1 clock and the last initialized round. Ticket
177+ recipients must match the OrchestratorInfo address. Parameters must use the
178+ last initialized round and its canonical hash; older rounds, mismatched hashes,
179+ and expiring parameters/auth return 480 for refresh. New randomness resets the
180+ nonce. Parameter expiry is supplied by the caller, not signed by the orchestrator;
181+ these checks do not establish the provenance of an arbitrary challenge.
182+
183+ Optional signer authorization uses ` AuthWebhookFile ` and
184+ ` AuthWebhookHeadersFile ` . Headers use go-livepeer's comma-separated
185+ ` Header: value ` syntax, with CSV quoting for entries containing commas.
186+ Names are case-insensitive, repeated names retain multiple values, and malformed
187+ entries fail configuration parsing. URL and header credentials can also come
188+ from their component-prefixed environment variables. The webhook receives
189+ request headers and the proposed updated payment state. We deliberately generate
190+ and sign the tickets ** before authorization so we know what is being authorized** .
191+ Payment, credentials and updated signed state are released only after approval.
192+ The webhook returns ` status ` , ` reason ` , Unix-second ` expiry ` , ` auth_id ` , and optional
193+ ` maxPrice ` (wei per second or fixed request). ** Signed state is a bearer credential** :
194+ while authorization is cached, possession of it permits continuation without
195+ presenting the original credentials. Keep it out of logs and shared storage.
196+ Caching is generally not recommended outside specific, deliberately scoped
197+ trusted-client cases. Omit ` expiry ` or return zero to authorize each payment;
198+ a future expiry caches approval and delays credential revocation and budget
199+ rechecks until that time. A supplied ` Signer-Auth-Id ` must match the state, but
200+ omitting it does not authenticate a caller. If a proxy supplies identity, it
201+ must authenticate each request and overwrite caller-supplied identity headers.
202+ Price ceilings continue to apply during caching. Changing the webhook URL or
203+ configured headers invalidates the cache. Redirects
204+ are refused. The signer has no shared bearer-token or TLS-assertion flags;
205+ listener access and TLS termination are configured externally. Response writes
206+ are bounded by the request deadline (at most 30 seconds), and cancellation
207+ interrupts blocked writes. None of the signer routes stream beyond the request.
208+
209+ Run the signer alongside a clearinghouse such as
210+ [ livepeer/clearinghouse-batteries] ( https://github.com/livepeer/clearinghouse-batteries )
211+ to manage authorization, allocations and cumulative spending. Price and ticket
212+ limits constrain individual quotes/batches, not a customer's total budget.
213+ That clearinghouse's documented accounting pipeline consumes signing usage
214+ events through Kafka: this signer supports its webhook shape but currently has
215+ no Kafka usage-event producer. Connect and verify the accounting path before
216+ relying on end-to-end budget enforcement; configuring only the webhook is not
217+ the complete integration. An alternative is a synchronous authorization service
218+ with a durable ledger that atomically reserves each payment against a budget,
219+ deduplicates retries, and shares accounting across replicas. This still requires
220+ state somewhere; client-carried signed state alone cannot enforce cumulative caps.
163221
164222Winning tickets wait for parameter expiry before their randomness is exposed
165223on-chain. Signed transaction bytes and hash are saved before broadcast; safe
@@ -187,17 +245,38 @@ round initialize
187245
188246Run a state change without ` --submit ` to review its simulation,
189247gas estimate and call data. Add ` --submit ` and an owner-only
190- ` private_key_file ` to broadcast; add ` --wait ` for a successful receipt.
248+ ` KeyFile ` to broadcast; add ` --wait ` for a successful receipt.
191249The submission hash is printed before waiting and remains available on errors.
192250With JSON output, submission and receipt are separate JSON-line records.
251+ Add ` --quiet ` to suppress normal transaction output, including dry-run plans,
252+ submission hashes and receipt records. Errors still go to stderr and return
253+ exit status 2; broadcast and receipt errors retain the transaction hash.
254+ Transaction switches and action inputs are accepted only on the command line.
255+ TOML contains shared operator settings: RPC connection, expected chain ID,
256+ Controller, sender, key location, and an optional maximum fee per gas.
257+ ` --output ` and ` --print-config ` are also
258+ command-line controls. Shared flags can appear before or after chain subcommands:
259+
260+ ``` sh
261+ livepeer chain --config /path/to/chain.toml --output json stake bond ORCHESTRATOR_ADDRESS --amount 1000000000000000000
262+ livepeer chain ticketbroker fund --config /path/to/chain.toml --amount 1000000000000000000 --reserve 0 --submit --quiet
263+ ```
264+
193265An approval needed by ` stake bond ` is submitted first; without ` --wait ` , rerun
194266the bond after that approval is confirmed. ` stake rebond --delegate ADDRESS `
195267uses ` rebondFromUnbonded ` ; omit the delegate for an already bonded account.
196- Before ` orchestrator activate ` , self-bond using ` stake bond --delegate YOUR_ADDRESS `
268+ Before ` orchestrator activate ` , self-bond using ` stake bond YOUR_ADDRESS --amount AMOUNT `
197269and set the public URI with ` orchestrator set-config --service-uri URL ` . The sender
198270must match the key and the configured chain ID must match RPC. No command
199271starts an HTTP server. Exit status is 0 on success and 2 on command failure.
200272
273+ Transactions require dynamic fees and fail if the RPC header has no base fee.
274+ ` --max-fee-per-gas ` (TOML ` MaxFeePerGas ` ) sets an optional
275+ ceiling in wei per gas; a higher estimate fails before signing. Staking and
276+ reward commands calculate pool-position hints. ` stake bond ` still requires a
277+ positive new-token amount. The ` eth ` APIs also support explicit delegation
278+ changes, voting, and delegated reward callers; their CLI commands follow later.
279+
201280TODO: add a richer terminal UI after the direct command surface is stable.
202281
203282## Test
0 commit comments