[eliteprox]

Summary

This PR lets a gateway find out what each call_runner call cost. call_runner takes a new, optional on_payment_session callback. Each time the remote signer signs a payment session, the SDK calls it with that session. The session's new manifest_id property names the orchestrator session the payment funds, so the gateway can match it to Clearinghouse usage records and charge the right job.

Callers that don't pass the callback see no change in results, errors or streams.

Why

The signer charges when it signs a payment, not when the job succeeds. So a call can be charged and still fail: the runner errors, the payment turns out to be unusable, or the caller cancels. A gateway that bills its own users has to know which charges belong to which call, including the failed ones. Today call_runner doesn't tell it.

We need this for the Network Engineering SPE build track (project board). Its second milestone defines how the builder engine reports network cost per job (ISS-04). The engine records the manifest of every payment the signer signs, then matches each one to a Clearinghouse usage record, so every job shows what it cost, whether it succeeded or not. livepeer-builder-core pins this branch until it merges.

An earlier version read AuthID from the signer's state. On livepeer#74, Josh pointed out that the state is opaque and shouldn't become a public contract, and suggested ManifestID instead. This version uses ManifestID and doesn't decode the signer's state.

What callers see

manifest_ids: list[str] = []
result = await call_runner(
    ...,
    on_payment_session=lambda s: manifest_ids.append(s.manifest_id),
)

• When it runs. Once for each payment session, when the signer first signs for it and before the paid request goes to the runner. The callback can be sync or async.
• What it reports. Every session the signer signs: one whose payment proves unusable, one followed by a runner failure, and each new session after the runner asks for payment again (a repeated 402). Fixed-price calls report too.
• What it doesn't report. Sessions the signer refuses, including refresh requests.
• If the callback raises, the paid request isn't sent, and the caller gets the callback's error unchanged.
• If the call is cancelled while a payment is being signed, the SDK lets the signing finish and reports the session before it passes the cancellation on. Because the caller owns the list, a call cancelled under asyncio.wait_for, for example, still accounts for every session it signed.

Known limits

• RunnerSelectionCursor still fails over after a signed payment, so one job can pay twice. Runner selection: pool size, failure classification and payment_sent on rejections livepeer/livepeer-python-gateway#70 tracks that.
• It's still open whether every orchestrator issues a fresh ManifestID for each 402 challenge, or whether that's only how livepeer/node behaves today (call_runner doesn't report the signer sessions it opens livepeer/livepeer-python-gateway#74). Builder core treats a manifest shared by more than one payment session as uncertain, so if the assumption fails, costs show as uncertain rather than wrong.

This replaces livepeer#71, which was closed so the change could target a fork branch.

Test plan

• pytest -W error::ResourceWarning at e6d243b: 227 passed, 2 failed. Both failures are in tests/test_stats_pull.py and fail the same way on main. The new tests cover sync and async callbacks, repeated 402s, a runner failure after payment, a refused session, an unusable payment, a raising callback, a cancelled call, and manifest_id staying the same across a payment refresh.
• Confirm that a fresh ManifestID per challenge is behavior callers can rely on (call_runner doesn't report the signer sessions it opens livepeer/livepeer-python-gateway#74).

[sonarqubecloud]

Quality Gate failed

Failed conditions
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE