feat: cumulative factors and delegator shares for O(1) stake computation

[adamsoffer]

Problem

The subgraph has no way to compute a delegator's actual total stake. The bondedAmount field only reflects the value at the time of the last claim and does not include rewards earned since then. To get a delegator's current stake, clients must call the contract's pendingStake() method directly — and for historical stake at a past round, there is no solution at all.

Similarly, computing an orchestrator's full pending stake (including their unclaimed commission) or their lifetime earnings requires fetching every pool since their last claim and summing across all of them.

This also means there's no way to build time-series charts of delegator stake, show per-round reward breakdowns, or compute orchestrator yield — all of which require knowing stake values across rounds.

Summary

• Store cumulativeRewardFactor and cumulativeFeeFactor on the Pool entity, matching on-chain PreciseMathUtils (27-decimal fixed-point)
• Propagate cumulative factors forward each round during pool creation so every pool has valid values (no gaps for missed reward() calls)
• Add shares field to Delegator (bondedAmount * 10^27 / crf[lastClaimRound]) — invariant across claims, only changes on bond/unbond/rebond
• Add DelegatorSnapshot entity capturing delegator state at each bond/unbond/rebond for time-series chart support
• Compute cumulative fee factor in WinningTicketRedeemed handler using previous round's CRF (matching contract behavior)
• Add orchestrator commission tracking on Transcoder:
  • pendingRewardCommission — unclaimed reward commission (rewardCut portion), resets on claim
  • lifetimeRewardCommission — total reward commission ever earned, never resets
  • pendingFeeCommission — unclaimed fee commission, resets on claim
  • lifetimeFeeCommission — total fee commission ever earned, never resets

What this unlocks

Current pending stake without contract calls — A delegator's up-to-date total stake (equivalent to pendingStake() on-chain) can now be computed entirely from the subgraph: stake = shares * crf / 10^27. For orchestrators specifically, their full pending stake includes unclaimed commission: stake = shares * crf / 10^27 + pendingRewardCommission. No contract calls needed.

Historical stake at any past round — Something previously impossible. Query the delegator's shares (or the relevant DelegatorSnapshot) and the Pool.cumulativeRewardFactor for that round, then compute shares * crf[round] / 10^27.

Per-round reward and fee breakdowns — Rewards earned in a specific round can be derived by comparing cumulative factors between consecutive rounds: rewards = shares * (crf[round] - crf[round-1]) / 10^27. Same pattern applies to fees using cumulativeFeeFactor.

Time-series charts of delegator stake — The shares approach combined with DelegatorSnapshot entities makes it straightforward to build a chart showing a delegator's total stake over time. Between snapshots, shares are constant, so stake at any round is just shares * crf[round] / 10^27. When a bond/unbond/rebond occurs, a new snapshot captures the updated shares value to use going forward.

Live example: The new Livepeer Explorer (livepeer/explorer#828) is built on this data. Its portfolio charts delegated stake, rewards and network share per round across several wallets, and its orchestrator pages show realised yield, all computed from the per-round cumulativeRewardFactor values this PR adds rather than from contract calls.

Orchestrator commission tracking — pendingRewardCommission and pendingFeeCommission give the orchestrator's unclaimed commission in a single field each, without needing to sum across pools. lifetimeRewardCommission and lifetimeFeeCommission provide total lifetime earnings.

Orchestrator pool analytics — Cumulative factors stored per-pool per-round enable computing total rewards distributed, effective yield, and fee revenue for any orchestrator over any time range without replaying events.

All changes are additive — no breaking changes to existing queries.

Test plan

• Run npx graph codegen && npx graph build — verified locally
• Deploy to a staging subgraph and verify cumulative factors match on-chain values
• Verify delegator shares remain constant across claim events
• Verify shares * crf[round] / 10^27 matches actual bonded amounts
• Verify pending stake computed from subgraph matches contract pendingStake() return value
• Verify DelegatorSnapshot entities are created on bond/unbond/rebond but not on claim
• Verify pendingRewardCommission and pendingFeeCommission reset to zero after orchestrator claims
• Verify lifetimeRewardCommission and lifetimeFeeCommission never reset

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added detailed transcoder commission and cumulative reward/fee data to the GraphQL API.
  • Added delegator share tracking and historical snapshots for state-changing events.
  • Improved reward and fee calculations using cumulative factors, supporting more efficient delegator accounting.
  • Added historical commission tracking and automatic updates during rewards, claims, and ticket redemption.
  • Initialized new accounting fields consistently for pools, transcoders, and delegators.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds cumulative reward and fee factors, precise accounting helpers, delegator share tracking with historical snapshots, and transcoder commission fields. Bonding, reward, round, earnings-claim, and ticket-redemption mappings now update these values.

Changes

Accounting factors and commission tracking

Layer / File(s)	Summary
Accounting schema and precise math schema.graphql, utils/helpers.ts	Adds pool factors, delegator shares and snapshots, transcoder commission fields, precise percentage helpers, and initialization logic.
Delegator shares and snapshots src/mappings/bondingManager.ts	Bonding, unbonding, and rebonding calculate shares from pool factors and persist DelegatorSnapshot records.
Reward commission lifecycle src/mappings/bondingManager.ts, src/mappings/roundsManager.ts	Reward processing updates commissions and cumulative reward factors; new rounds snapshot active commissions and self-claims clear them.
Fee commission accounting src/mappings/ticketBroker.ts	Winning ticket redemption updates fee commissions and the pool cumulative fee factor.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant BondingManager
  participant Pool
  participant Transcoder
  participant RoundsManager
  BondingManager->>Pool: update cumulativeRewardFactor
  BondingManager->>Transcoder: accrue reward commission
  RoundsManager->>Transcoder: snapshot active cumulative rewards
  BondingManager->>Pool: update cumulativeFeeFactor during fee accounting
  BondingManager->>Transcoder: accrue fee commission

Loading

Possibly related issues

• Index per-round delegator and orchestrator stake and earnings via cumulative factors #238 — Directly covers cumulative factors, delegator shares, snapshots, and commission tracking.
• Add lastFeeRound to Transcoder for independent fee factor fallback #230 — Relates to cumulative factor tracking and fallback logic across pool, transcoder, round, and fee accounting.

Possibly related PRs

• livepeer/subgraph#246 — Both modify reward handling and pool loading in bondingManager.ts.
• livepeer/subgraph#249 — Extends the same createOrLoadPool factor initialization path used by these mappings.

Suggested reviewers: rickstaa

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 35.71% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately reflects the main change: cumulative factors and delegator shares for stake computation.
Description check	✅ Passed	It includes the problem, summary, benefits, and test plan; only the explicit issue link and dependency section are missing.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

src/mappings/bondingManager.ts (1)

144-159: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Duplicated shares-from-CRF computation across bond/unbond/rebond.

The same ~10-line "load pool → fallback to PRECISE_PERC_DIVISOR → compute shares" block is repeated verbatim in bond(), unbond(), and rebond(). Extracting it into a shared helper in utils/helpers.ts (e.g. computeShares(delegateAddress, roundId, bondedAmount)) would remove the duplication and prevent the three copies from silently diverging if the fallback/edge-case logic ever needs to change (e.g. together with the CRF-continuity fix noted in utils/helpers.ts).

Also applies to: 296-313, 418-431

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/mappings/bondingManager.ts` around lines 144 - 159, Extract the repeated
pool-loading, CRF fallback, and shares calculation from bond(), unbond(), and
rebond() into a shared helper in utils/helpers.ts, such as
computeShares(delegateAddress, roundId, bondedAmount). Update all three call
sites to use the helper while preserving the existing PRECISE_PERC_DIVISOR
fallback and cumulativeRewardFactor handling.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@schema.graphql`:
- Around line 231-246: Update DelegatorSnapshot ID construction in the bond,
unbond, and rebond event handlers to include a unique per-event component such
as transaction hash and log index, rather than only delegator and round. Ensure
each state-changing event creates a distinct snapshot while preserving the
existing DelegatorSnapshot fields and save flow.

In `@src/mappings/bondingManager.ts`:
- Around line 166-175: The DelegatorSnapshot identifier in the snapshot creation
block collides with snapshots from unbond() and rebond() within the same round.
Update snapshotId to include a unique event-specific component while retaining
the delegator and round context, ensuring multiple same-round events produce
distinct records without overwriting earlier state.

In `@src/mappings/ticketBroker.ts`:
- Around line 135-145: Update the previous cumulative reward factor lookup in
the ticket-broker flow around prevPoolForFees so it searches backward through
earlier rounds until it finds the transcoder’s most recent Pool with a nonzero
cumulativeRewardFactor, rather than only checking round.id - 1. Preserve
PRECISE_PERC_DIVISOR as the fallback when no prior qualifying Pool exists, and
use the existing pool-loading helpers or lookup pattern from createOrLoadPool.

In `@utils/helpers.ts`:
- Around line 64-79: Update the cumulative-factor initialization in the shown
pool-loading flow to use the transcoder’s persisted last cumulative reward and
fee factors rather than resetting to ZERO_BI when Pool.load for the previous
round returns null. Store or reuse these factors on the Transcoder entity, while
preserving previous-pool values when available and ensuring the updated factors
are persisted for subsequent rounds.

---

Nitpick comments:
In `@src/mappings/bondingManager.ts`:
- Around line 144-159: Extract the repeated pool-loading, CRF fallback, and
shares calculation from bond(), unbond(), and rebond() into a shared helper in
utils/helpers.ts, such as computeShares(delegateAddress, roundId, bondedAmount).
Update all three call sites to use the helper while preserving the existing
PRECISE_PERC_DIVISOR fallback and cumulativeRewardFactor handling.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c79b66a3-23ff-4bca-a971-3b774b9e83c2

📥 Commits

Reviewing files that changed from the base of the PR and between 69340df and 7b101df.

📒 Files selected for processing (5)

• schema.graphql
• src/mappings/bondingManager.ts
• src/mappings/roundsManager.ts
• src/mappings/ticketBroker.ts
• utils/helpers.ts

[Copilot]

Copilot review overview

🟡 Changes recommended

Critical compatibility and stake/commission accounting issues remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 6 · 4

Open (10)

• Backfill new non-null fields for existing entities · New
• Declare DelegatorSnapshot in the data source schema · New
• Use active self-delegated stake for reward shares · New
• Prevent double-counting transcoder stake rewards · New
• Rebase shares after self-claim commission is bonded · New
• Preserve active reward snapshot until the next round · New
• Use latest existing pool for reward factor lookup · New
• Key delegator snapshots by unique event identity · New
• Use propagated CRF instead of exact prior-round pool · New
• Initialize new pool reward factor to the base divisor · New

What changed in this PR

Adds cumulative reward/fee factors, delegator shares and snapshots, and transcoder commission tracking for O(1) stake and earnings queries.

Changes:

• Propagates per-round cumulative factors.
• Tracks delegator shares and state snapshots.
• Adds pending and lifetime commission fields.

File	Summary
utils/​helpers.ts	Factor propagation and entity initialization.
src/​mappings/​ticketBroker.ts	Fee-factor and commission accounting.
src/​mappings/​roundsManager.ts	Round commission snapshots.
src/​mappings/​bondingManager.ts	Shares, snapshots, rewards, and claims.
schema.graphql	New accounting entities and fields.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved accounting errors affect factor propagation, snapshots, and commission-based stake calculations.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 6 · 1

Open (7)

• Missing pools initialize cumulative factors to zero · New
• Preserve active reward snapshot until the next round
• Prevent double-counting transcoder stake rewards
• Use active self-delegated stake for reward shares
• Declare DelegatorSnapshot in the data source schema
• Backfill new non-null fields for existing entities
• Key delegator snapshots by unique event identity

Resolved since last review (4)

• Rebase shares after self-claim commission is bonded
• Initialize new pool reward factor to the base divisor
• Use propagated CRF instead of exact prior-round pool
• Use latest existing pool for reward factor lookup

Previously missed (1)

In code that hasn't changed since last review

Pool creation scans every missed round linearly

utils/​helpers.ts:93

This makes pool creation scan one store key per missed round. A transcoder that has been inactive for a long interval can make newRound perform thousands of loads and delay indexing, even though the new stake calculation is intended to be O(1). Persist the last factor-bearing pool/source on the transcoder or otherwise avoid a linear round-by-round search.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved correctness, performance, manifest, snapshot-ID, and migration issues remain.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 5 · 2

Open (7)

• Declare Pool in the TicketBroker entity list · New
• Missing pools initialize cumulative factors to zero
• Prevent double-counting transcoder stake rewards
• Use active self-delegated stake for reward shares
• Backfill new non-null fields for existing entities
• Avoid rebasing shares for ordinary claims · New
• Key delegator snapshots by unique event identity

Resolved since last review (2)

• Preserve active reward snapshot until the next round
• Declare DelegatorSnapshot in the data source schema

Previously missed (1)

In code that hasn't changed since last review

Prevent snapshot ID collisions within a round

src/​mappings/​bondingManager.ts:168

This key is not unique for the advertised “snapshot at each” behavior: a delegator can bond, unbond, or rebond more than once in the same round, so the later event overwrites the earlier DelegatorSnapshot. Use the transaction hash/log index (or another event-unique suffix) for the snapshot ID, and apply the same change in the other two handlers.

This issue also appears in the following locations of the same file:

• line 345
• line 446

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved correctness, entity-registration, and critical performance issues remain.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Avoid unbounded pool history scans during new rounds · New

Resolved since last review (12)

• Declare Pool in the TicketBroker entity list
• Missing pools initialize cumulative factors to zero
• Preserve active reward snapshot until the next round
• Rebase shares after self-claim commission is bonded
• Prevent double-counting transcoder stake rewards
• Use active self-delegated stake for reward shares
• Backfill new non-null fields for existing entities
• Avoid rebasing shares for ordinary claims
• Initialize new pool reward factor to the base divisor
• Use propagated CRF instead of exact prior-round pool
• Key delegator snapshots by unique event identity
• Use latest existing pool for reward factor lookup

Previously missed (1)

In code that hasn't changed since last review

Write current-round snapshot after self-claim share rebasing

src/​mappings/​bondingManager.ts:808

This branch updates delegator.shares for a self-claim, but no DelegatorSnapshot is written afterward. If the last bond/unbond/rebond was in an earlier round, the snapshot used for historical stake queries retains the pre-claim shares and undercounts the self-delegator's stake from the claim round onward. Update/overwrite the current-round snapshot for self-claims after rebasing shares (and adjust the no-snapshot-on-claim test expectation for this exception).

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved critical and moderate accounting issues affect factor continuity, stake accuracy, snapshots, and indexing performance.

Review effort: Lite
Findings: 2

Open (2)

• Self-claim leaves stake and delegated amount stale · New
• Uninitialized earnings pools incorrectly replace propagated values · New

Resolved since last review (1)

• Avoid unbounded pool history scans during new rounds

Previously missed (1)

In code that hasn't changed since last review

Self-claim does not update the delegator snapshot

src/​mappings/​bondingManager.ts:809

A self-claim changes delegator.shares by adding the orchestrator's commission, but this path does not write a DelegatorSnapshot. Consequently, the snapshot for the prior bond/unbond/rebond remains the only historical share value, so stake charts that switch shares at snapshots undercount this delegator after the claim. Record/update the snapshot when the self-claim rebases shares (using the current event round, consistent with the other snapshot handlers).

[Copilot]

🟡 Changes recommended

Critical and moderate accounting issues remain unresolved.

1 open issue

• Initialized pool values are not persisted after first fee event · New

1 previously missed issue

In code that hasn't changed since last review

Self-claim omits snapshot for changed delegator shares

src/​mappings/​bondingManager.ts:809

This self-claim changes delegator.shares, but no DelegatorSnapshot is created or updated for the claim. A round-based query that uses the latest snapshot at or before this round will continue using the pre-claim shares, so it underestimates the orchestrator's stake after commission is bonded; either snapshot this share-changing self-claim or make the historical-query contract explicitly account for claims.

2 resolved since last review

• Uninitialized earnings pools incorrectly replace propagated values
• Self-claim leaves stake and delegated amount stale

_{Review effort: Lite}

[Copilot]

🔵 Needs a closer look

Unresolved issues affect fee-factor accuracy, self-claim snapshots, and the documented share calculation.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Do not reward successful zero-value earnings pools

src/​mappings/​ticketBroker.ts:190

An all-zero, non-reverted earnings-pool read is the documented no-transfer case, but this condition falls through to the local calculation below and adds faceValue to cumulativeFeeFactor anyway. That creates fee rewards for an uncredited ticket. Only use the local increment when the contract call reverted; for a successful all-zero tuple, retain the propagated factor.

1 resolved since last review

• Initialized pool values are not persisted after first fee event

_{Review effort: Lite}