Allow tracking of pendingstake through the subgraph

[rickstaa]

Goal

Enable both orchestrators and delegators to easily calculate their effective stake (bonded stake + unclaimed rewards) using subgraph data, without requiring direct smart contract queries.

This will:

• Simplify stake-related logic in Explore (orchestrator & delegator views)
• Enable historical estimated rewards in delegator history
• Unlock downstream use cases such as tax tracking

Problem Description

The bondedAmount field in the Livepeer subgraph accurately reflects a delegator’s or orchestrator’s bonded stake as of the last explicit bonding transaction (Bond, Unbond, Rebond, TransferBond). However, it does not include unclaimed rewards, which leads to discrepancies when compared with on-chain views (e.g. Arbiscan).

Example:

• Subgraph bondedAmount: 1.002563476329049571 LPT
• On-chain effective stake: 2.536529849800865 LPT

This occurs because bondedAmount is intentionally static and excludes rewards that have accumulated but have not yet been claimed.

While bondedAmount is technically correct, users and applications often need access to the effective stake value to provide accurate UX and match on-chain expectations.

How This Can Be Derived Deterministically

Livepeer uses a lazy accounting model for rewards. Instead of updating each user’s stake on every reward event, rewards are tracked using a cumulative reward factor.

A user’s effective stake can be derived as:

effectiveStake =
  bondedAmount ×
  (currentCumulativeRewardFactor / cumulativeRewardFactorAtLastClaim)

All required inputs (bonded amount, cumulative reward factors, last claim round) are deterministic and already indexable, making this approach applicable to both orchestrators and delegators.

Design Constraints

• Individual delegator pending stake is not emitted in events and cannot be directly indexed from BondingManager
• Fully materializing pending stake in the subgraph risks:
  • Increased indexing complexity
  • Higher sync times and compute costs
  • Limited extensibility (e.g. orchestrators only)

Proposed Direction

Instead of materializing pendingStake directly, expose sufficient deterministic data that allows clients to derive pending stake reliably for both orchestrators and delegators.

This approach:

• Keeps the subgraph lean
• Avoids contract calls during indexing
• Works uniformly across participant types
• Enables historical reward reconstruction

Alternatives Considered

Option 1 — Subgraph-computed pendingStake (orchestrators only)

• Pros: Simple consumer queries
• Cons:
  • Orchestrators only
  • Requires contract calls during indexing
  • Increases sync time and compute cost

Option 2 — Deterministic, client-side calculation (preferred)

• Pros:
  • Works for orchestrators and delegators
  • Enables historical reward estimation
  • Lightweight and scalable
• Cons:
  • Requires a small amount of client-side logic

Benefits

• Unified solution for orchestrators and delegators
• Accurate effective stake without smart contract queries
• Supports historical analytics (e.g. tax reporting)
• Lower subgraph operational risk
• Future-proof and easier to evolve

Success Criteria

• Clients can calculate pending stake using only subgraph data
• Derived values match on-chain results within rounding tolerance
• No additional contract calls are required during indexing

[rickstaa]

Created draft in #165.

[rickstaa]

@mehrdadmms here’s some context for the team.

The primary goal of this work is to enable orchestrators and delegators to easily calculate their pending stake without needing to query the smart contracts directly. This would allow us to simplify the explorer’s orchestrator information and enable the addition of historical estimated rewards in the delegator history tab, which in turn supports use cases like tax tracking.

I explored two possible approaches:

• Option 1 – Subgraph-computed pending stake
  feat: add pendingStake to transcoder and pool objects #165
  This approach exposes pending stake directly via the subgraph, but only for orchestrators. The main drawback is that it significantly increases subgraph complexity, sync time, and compute cost, and it does not generalize to delegators.
• Option 2 – Deterministic, client-side calculation
  feat(pool): add cumulative reward factor #166
  This approach keeps the subgraph lean and shifts a small amount of computation to the client. Since Livepeer’s cumulative rewards mechanism is deterministic, users can derive pending stake using only the bonded amount and the last claim round. This works for both orchestrators and delegators. There is also an equivalent PR that applies the same pattern to fees.

Right now without diving deeper into this I personally lean toward Option 2, as it offers a better balance between simplicity, flexibility, and long-term maintainability. That said, the team should evaluate which approach best aligns with our goals and operational constraints.