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.

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