Skip to content

Commit c36992c

Browse files
committed
eth: adopt upstream bindings and harden transaction handling
- Replace handwritten ABI and RPC plumbing with upstream bindings and geth. - Restore staking hints and add delegation, voting, and reward-caller APIs. - Require dynamic fees, support fee ceilings, and preserve nonce reservations across persistence failures and restarts. - Validate receipt status and identity before settlement, and reject invalid staking arguments without panicking. - Remove RPC destination grants and custom CA options while retaining transport safeguards and canonical-chain checks. - Consolidate tests and update configuration, recovery, and security docs. Source-Repository: https://github.com/livepeer/go-livepeer Source-Revision: bd645a09266833fb859053445d9ac85846330756 Source-History: dd2dc15
2 parents 7b8a9b0 + dd2dc15 commit c36992c

52 files changed

Lines changed: 19124 additions & 883 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 111 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -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
6163
bin/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
6669
exact bytes, including a trailing newline, so operator-managed files or
6770
secret-manager mounts must contain precisely the intended credential. A direct
6871
environment 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

108111
Custom 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
119122
memory; SQLite holds winning tickets (including their redemption randomness),
120123
redemption attempts and chain activity observations. Restarting requires new
121124
paid 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).
126135
The orchestrator SQLite file must be owner-only.
127136

128137
Configure exactly one orchestrator conversion source: a fixed `wei_per_usd`,
@@ -133,33 +142,82 @@ priced discovery/reservations. Existing sessions retain their agreed wei
133142
price. USD/hour discovery is normalized to USD/second alongside wei/second.
134143
Off-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
141159
returns 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

143166
The 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.
145169
It issues enough tickets to reach at least the greater of the fee and one
146170
ticket's expected value, then carries unused expected value in signed state.
147171
The state is not a replay database: reusing an earlier signed state can yield
148172
another batch, and retries need not return identical bytes. The recipient
149173
rejects duplicate tickets.
150174
The recipient checks claimable reserve, withdrawal timing and outstanding
151175
winning 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

164222
Winning tickets wait for parameter expiry before their randomness is exposed
165223
on-chain. Signed transaction bytes and hash are saved before broadcast; safe
@@ -187,17 +245,38 @@ round initialize
187245

188246
Run a state change without `--submit` to review its simulation,
189247
gas 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.
191249
The submission hash is printed before waiting and remains available on errors.
192250
With 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+
193265
An approval needed by `stake bond` is submitted first; without `--wait`, rerun
194266
the bond after that approval is confirmed. `stake rebond --delegate ADDRESS`
195267
uses `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`
197269
and set the public URI with `orchestrator set-config --service-uri URL`. The sender
198270
must match the key and the configured chain ID must match RPC. No command
199271
starts 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+
201280
TODO: add a richer terminal UI after the direct command surface is stable.
202281

203282
## Test

‎chain/app.go‎

Lines changed: 8 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import (
99
"math/big"
1010

1111
"github.com/BurntSushi/toml"
12+
"github.com/ethereum/go-ethereum/common/hexutil"
1213
"github.com/j0sh/boa/pkg/boa"
1314
"github.com/livepeer/node/eth"
1415
)
@@ -22,7 +23,7 @@ func unmarshalConfig(data []byte, target any) error {
2223
// Detach pointers shared with Boa's CLI/env mirrors before TOML writes
2324
// through them. Boa restores higher-priority values after decoding.
2425
if p, ok := target.(*RootParams); ok {
25-
p.ChainID, p.Sender = nil, nil
26+
p.ChainID, p.Sender, p.MaxFeePerGas = nil, nil, nil
2627
}
2728
return toml.Unmarshal(data, target)
2829
}
@@ -33,10 +34,11 @@ func Status(ctx context.Context, p OperatorParams, display DisplayOptions, out i
3334
return err
3435
}
3536
defer client.Close()
36-
block, err := client.CallString(ctx, "eth_blockNumber")
37+
blockNumber, err := client.BlockNumber(ctx)
3738
if err != nil {
3839
return err
3940
}
41+
block := hexutil.EncodeUint64(blockNumber)
4042
if display.Output == "json" {
4143
return json.NewEncoder(out).Encode(map[string]string{"chain_id": chainID.String(), "block_number": block})
4244
}
@@ -74,25 +76,17 @@ func Account(ctx context.Context, p OperatorParams, display DisplayOptions, out
7476
return err
7577
}
7678
defer client.Close()
77-
balanceRaw, err := client.CallString(ctx, "eth_getBalance", sender.Hex(), "latest")
79+
balance, err := client.BalanceAt(ctx, sender, nil)
7880
if err != nil {
7981
return err
8082
}
81-
balance, err := eth.ParseHexQuantity(balanceRaw)
83+
nonce, err := client.PendingNonceAt(ctx, sender)
8284
if err != nil {
8385
return err
8486
}
85-
nonceRaw, err := client.CallString(ctx, "eth_getTransactionCount", sender.Hex(), "pending")
86-
if err != nil {
87-
return err
88-
}
89-
nonce, err := eth.ParseHexQuantity(nonceRaw)
90-
if err != nil || !nonce.IsUint64() {
91-
return errors.New("invalid account nonce from RPC")
92-
}
9387
if display.Output == "json" {
94-
return json.NewEncoder(out).Encode(map[string]any{"address": sender.Hex(), "balance_wei": balance.String(), "nonce": nonce.Uint64()})
88+
return json.NewEncoder(out).Encode(map[string]any{"address": sender.Hex(), "balance_wei": balance.String(), "nonce": nonce})
9589
}
96-
_, err = fmt.Fprintf(out, "Address: %s\nETH balance (wei): %s\nPending nonce: %d\n", sender.Hex(), balance.String(), nonce.Uint64())
90+
_, err = fmt.Fprintf(out, "Address: %s\nETH balance (wei): %s\nPending nonce: %d\n", sender.Hex(), balance.String(), nonce)
9791
return err
9892
}

‎chain/app_test.go‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import (
99
"net/url"
1010
"os"
1111
"path/filepath"
12+
"strings"
1213
"testing"
1314

1415
"github.com/BurntSushi/toml"
@@ -86,10 +87,10 @@ func TestAccountValidatesSenderAndReadsPendingNonce(t *testing.T) {
8687
switch request.Method {
8788
case "eth_chainId":
8889
case "eth_getBalance":
89-
require.Equal(t, []any{sender.Hex(), "latest"}, request.Params)
90+
require.Equal(t, []any{strings.ToLower(sender.Hex()), "latest"}, request.Params)
9091
value = "0xde0b6b3a7640000"
9192
case "eth_getTransactionCount":
92-
require.Equal(t, []any{sender.Hex(), "pending"}, request.Params)
93+
require.Equal(t, []any{strings.ToLower(sender.Hex()), "pending"}, request.Params)
9394
value = "0x2"
9495
default:
9596
t.Errorf("unexpected RPC method %s", request.Method)

0 commit comments

Comments
 (0)