The RewardDistributor contract is built to support ERC-20 distributions in the future, but this document covers ETH stipend distribution. The same recipients and claim delegates are used for both ETH and ERC-20 distributions.

Weekly ETH stipend service flow (off-chain → on-chain)

• Stipend service monitors blocks won by mev-commit registered validators, resolves the operator’s recipient for the pubkey via RewardDistributor.getKeyRecipient(operator, pubkey), and adds it to the operator/recipient pair’s cumulative stipend rewards (off chain). At the end of the week, the service grants a array of stipends to each operator-recipient combo, with each stipend representing the total stipend rewards earned by that operator/recipient pair.
• StipendManager watches blocks won by mev-commit–registered validators. For each win, it looks up the operator, resolves the payout address with RewardDistributor.getKeyRecipient(operator, pubkey), and increments an off-chain tally keyed by (operator, recipient). At week’s end it submits a single batch to grantETHRewards, passing a list of stipend rewards (the consolidated totals per (operator, recipient)), where each item is the total earned by that pair for the week.
• All grants and claims are strictly partitioned by (operator, recipient). Because multiple operators can share the same recipient, we isolate balances so one operator can’t trigger payout of another operator’s accruals to that recipient. An operator (or their authorized delegate) can only claim the amount accrued to their (operator, recipient) bucket, nothing else.
  • Example

Stipend Recipients

Operators are the recipients of their key’s stipend rewards by default. If a global override is set, all stipends earned will be attributed to their global override address. In certain cases, the operator may want to override by individual keys. Per-key overrides take precedence over global overrides.

Override Precedence

1. Per-key override: operatorKeyOverrides[operator][keccak256(pubkey)] if set.

2. Global override (operator default): operatorGlobalOverride[operator] if set.

3. Fallback: the operator address itself.

   ⇒ Per-key override wins over global; if neither exists, pay the operator.

• Operational guidance on overrides:

  Use global override (operator default) for the common case—cheaper and one mapping read.

  Use per-key override only for special keys that must route differently—more specific, slightly more expensive (hash + nested mapping).

Setting overrides

• Per-key: overrideRecipientByPubkey(bytes[] pubkeys, address recipient) (each pubkey must be 48 bytes, BLS).
• Global: setOperatorGlobalOverride(address recipient) (applies to all keys without a per-key override).

If the key’s operator changes and the new operator hasn’t set a key override, the new operator will be the fallback recipient until updated.

Claiming

Operators or their delegates claim, not recipients. An operator calls claimRewards(address payable[] recipients, uint256 tokenID) to pay out each listed recipient from its accrued balance. A delegate can claim on behalf of an operator via claimOnbehalfOfOperator(operator, recipients[], uint256 tokenID) if authorized. A token ID of 0 is used to signal an ETH claim.