Skip to content

feat: rewardsmanagerv2 and stipenddistributor contracts#781

Merged
owen-eth merged 24 commits intomainfrom
rewards-manager-v2
Sep 13, 2025
Merged

feat: rewardsmanagerv2 and stipenddistributor contracts#781
owen-eth merged 24 commits intomainfrom
rewards-manager-v2

Conversation

@owen-eth
Copy link
Copy Markdown
Contributor

@owen-eth owen-eth commented Sep 6, 2025

Describe your changes

StipendDistributor:
-Operator can override their recipient address so that stipend rewards from all keys are granted to the specified address.
-Operators set a per-pubkey stipend recipient override (this takes precedence over global override).
-Oracle to track payProposer events/beacon data during the week, resolves the key’s operator in our registries, checks the operator's configured recipient for that key in the Stipend contract, and updates the pending stipend payment to that operator->recipient. At the end of the week post cumulative accruals to accrued[operator][recipient]. Cheaper to do this by recipient rather than by key since many keys will share the same recipient
-When claiming, the operator specifies the recipients they want to claim for and they are sent their accrued[operator][recipient] payment for each recipient.
-We can let an operator delegate claim rights at recipient-level: the delegate can claim only for a specific recipient of an operator.

More information:
https://www.notion.so/primev/StipendDistributor-Design-2696865efd6f80b2a4f0e6b8fc3ab0c4?showMoveTo=true&saveParent=true

BlockRewardManager:
-payProposer() allows a builder/payee send ETH to a specified feeRecipient; an optional protocol fee (rewardsPctBps) can be turned on/adjusted.
-Fee is taken from total amount when fee is turned on; recipient gets the remainder. Fee portion accrues in contract for later withdrawal.
-Owner can withdraw the accrued protocol share to treasury.
-Events to be used by Oracle to help calculate stipend payments.

Issue ticket number and link

Fixes # (issue)

Checklist before requesting a review

  • I have added tests that prove my fix is effective or that my feature works
  • I have made corresponding changes to the documentation

@owen-eth owen-eth changed the title feat: RewardsManagerV2 and StipendDistributor contracts feat: rewardsmanagerv2 and stipenddistributor contracts Sep 6, 2025
Comment thread contracts/contracts/utils/TransientReentrancyGuard.sol Outdated
Comment thread contracts/contracts/interfaces/IStipendDistributor.sol Outdated
Comment thread contracts/contracts/interfaces/IRewardsManagerV2.sol Outdated
Comment thread contracts/contracts/validator-registry/rewards/RewardsManagerV2.sol Outdated
Comment thread contracts/contracts/validator-registry/rewards/RewardsManagerV2.sol Outdated
Copy link
Copy Markdown
Contributor

@shaspitz shaspitz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RewardsManagerV2.sol looks good at a high level 👍

w.r.t stipends distributor contract - the delineation between an "operator" and a "receiver" isn't totally clear to me. Where/how are receivers decided? Will the operator and receiver ever be the same address? Why does the off-chain service need to specify both an "address" and "recipient" in grantStipends?

A polished README.md here explaining the protocol design, high level requirements from murat etc. would be very helpful. Examples are in the validator-registry directory. This README can also prevent a lot of intention related questions coming in from auditors

Comment thread contracts/contracts/validator-registry/rewards/RewardsManagerV2.sol
Comment thread contracts/contracts/validator-registry/rewards/RewardsManagerV2.sol Outdated
Comment thread contracts/contracts/validator-registry/rewards/RewardsManagerV2.sol Outdated
Comment thread contracts/contracts/validator-registry/rewards/RewardsManagerV2.sol Outdated
Comment thread contracts/contracts/validator-registry/rewards/StipendDistributor.sol Outdated
Comment thread contracts/contracts/validator-registry/rewards/StipendDistributorStorage.sol Outdated
Comment thread contracts/contracts/validator-registry/rewards/StipendDistributor.sol Outdated
Comment thread contracts/contracts/validator-registry/rewards/StipendDistributor.sol Outdated
Comment thread contracts/contracts/validator-registry/rewards/StipendDistributor.sol Outdated
@shaspitz
Copy link
Copy Markdown
Contributor

shaspitz commented Sep 9, 2025

Further we need to more explicitly define the role of the off-chain service (can call it oracle or ideally something else etc.) in the README.md, example here. I assume getKeyRecipient is explicitly for the oracle?

Copy link
Copy Markdown
Contributor

@shaspitz shaspitz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work!

Comment thread contracts/contracts/validator-registry/rewards/README.md Outdated
Comment thread contracts/scripts/validator-registry/rewards/DeployBlockRewardManager.s.sol Outdated
Comment thread contracts/scripts/validator-registry/rewards/DeployStipendDistributor.s.sol Outdated
@owen-eth owen-eth merged commit 7bed93a into main Sep 13, 2025
11 of 13 checks passed
@owen-eth owen-eth deleted the rewards-manager-v2 branch September 13, 2025 19:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants