feat: update_current_epoch_block_rewards

[noa-starkware]

This change is 

---

Note

Medium Risk
Touches reward computation and adds new persistent state used to derive payouts, so mis-calculation or snapshot-update edge cases could affect consensus rewards; access is restricted to the staking contract and covered by new tests.

Overview
Adds update_current_epoch_block_rewards to the L2 RewardSupplier, enabling consensus-era per-block reward calculation by converting yearly_mint into block rewards using an on-chain avg_block_duration updated once per epoch from (block_number, timestamp) snapshots.

This introduces new RewardSupplier storage (avg_block_duration, block_snapshot), new validation/errors for invalid block number/timestamp and block-duration overflow, centralizes SECONDS_IN_YEAR in constants.cairo, updates docs/spec and interfaces accordingly, and extends tests/utilities (including renaming AVG_BLOCK_TIME to AVG_BLOCK_DURATION) to cover the new behavior and failure cases.

^{Written by Cursor Bugbot for commit 768f359. This will update automatically on new commits. Configure here.}

[codecov]

Codecov Report

❌ Patch coverage is 95.19231% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.78%. Comparing base (b37679f) to head (768f359).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/reward_supplier/reward_supplier.cairo	82.75%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #63      +/-   ##
==========================================
- Coverage   95.81%   95.78%   -0.03%     
==========================================
  Files          42       42              
  Lines       10194    10295     +101     
==========================================
+ Hits         9767     9861      +94     
- Misses        427      434       +7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[NirLevi-starkware]

Reviewable status: 0 of 10 files reviewed, 1 unresolved discussion (waiting on @noa-starkware)

---

src/reward_supplier/reward_supplier.cairo line 141 at r2 (raw file):

    #[abi(embed_v0)]
    impl RewardSupplierImpl of IRewardSupplier<ContractState> {
        fn calculate_current_epoch_rewards(self: @ContractState) -> (Amount, Amount) {

Can't we use the code here? it looks the same. maybe we need to split the update function? to calculate_current_block_rewards and a setter to the block avg, WDYT?
This happend only once during epoch, so preformance is not an issue.

[remollemo]

@remollemo reviewed 8 files and all commit messages, and made 1 comment.
Reviewable status: 8 of 10 files reviewed, 2 unresolved discussions (waiting on noa-starkware).

---

src/reward_supplier/reward_supplier.cairo line 336 at r3 (raw file):

                .expect_with_err(err: Error::BLOCK_DURATION_OVERFLOW);
            // TODO: Adjust calculated_block_duration with MIN_BLOCK_TIME and MAX_BLOCK_TIME.
            self.avg_block_duration.write(calculated_block_duration);

I don't like this way of maintaining avg_block_duration.
it's totally unregulated.
I know it's not really a topic we can address now, but maybe add a TODO (TODO: Rething avg block duration algorithm)

Code quote:

            let num_blocks = current_block_number - snapshot_block_number;
            let calculated_block_duration = mul_wide_and_div(
                lhs: time_delta, rhs: BLOCK_DURATION_SCALE, div: num_blocks,
            )
                .expect_with_err(err: Error::BLOCK_DURATION_OVERFLOW);
            // TODO: Adjust calculated_block_duration with MIN_BLOCK_TIME and MAX_BLOCK_TIME.
            self.avg_block_duration.write(calculated_block_duration);

[remollemo]

@remollemo reviewed 2 files.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on noa-starkware).

[NirLevi-starkware]

@NirLevi-starkware resolved 1 discussion.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on noa-starkware).

[NirLevi-starkware]

@NirLevi-starkware made 1 comment.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on noa-starkware).