Design Doc: https://www.notion.so/primev/RewardDistributor-Design-2696865efd6f80b2a4f0e6b8fc3ab0c4
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.
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.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.(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.
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.
Per-key override: operatorKeyOverrides[operator][keccak256(pubkey)] if set.
Global override (operator default): operatorGlobalOverride[operator] if set.
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).
overrideRecipientByPubkey(bytes[] pubkeys, address recipient) (each pubkey must be 48 bytes, BLS).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.