feat(staking): update_current_epoch_block_rewards

Author: noa-starkware

docs/spec.md

@@ -119,6 +119,7 @@
 - [L2 Reward supplier contract](#l2-reward-supplier-contract)
   - [Functions](#functions-2)
     - [calculate\_current\_epoch\_rewards](#calculate_current_epoch_rewards)
+    - [update\_current\_epoch\_block\_rewards](#update_current_epoch_block_rewards)
     - [update\_unclaimed\_rewards\_from\_staking\_contract](#update_unclaimed_rewards_from_staking_contract)
     - [claim\_rewards](#claim_rewards-2)
     - [contract\_parameters\_v1](#contract_parameters_v1-2)
@@ -395,6 +396,7 @@ classDiagram
     erc20_dispatcher,
     l1_reward_supplier,
     calculate_current_epoch_rewards()
+    update_current_epoch_block_rewards()
     update_unclaimed_rewards_from_staking_contract()
     claim_rewards()
     on_receive()
@@ -2215,7 +2217,8 @@ Only staking contract can execute.
 fn calculate_current_epoch_rewards(self: @TContractState) -> (Amount, Amount)
 ```
 #### description <!-- omit from toc -->
-Return the amount of rewards for the current epoch (for STRK and BTC).
+Returns the amount of rewards for the current epoch (for STRK and BTC). 
+Used only before the consensus rewards mechanism is activated.
 #### return <!-- omit from toc -->
 rewards: ([Amount](#amount), [Amount](#amount)) - the rewards for the current epoch, in FRI, for STRK and BTC (respectively).
 #### emits <!-- omit from toc -->
@@ -2229,6 +2232,27 @@ rewards: ([Amount](#amount), [Amount](#amount)) - the rewards for the current ep
 #### access control <!-- omit from toc -->
 Any address can execute.
 
+### update_current_epoch_block_rewards
+```rust
+fn update_current_epoch_block_rewards(ref self: TContractState) -> (Amount, Amount);
+```
+#### description <!-- omit from toc -->
+Returns the amount of block rewards for the current epoch (for STRK and BTC). 
+Used after the consensus rewards mechanism is activated.
+#### return <!-- omit from toc -->
+rewards: ([Amount](#amount), [Amount](#amount)) - the block rewards for the current epoch, in FRI, for STRK and BTC (respectively).
+#### emits <!-- omit from toc -->
+#### errors <!-- omit from toc -->
+1. [CALLER\_IS\_NOT\_STAKING\_CONTRACT](#caller_is_not_staking_contract)
+#### logic <!-- omit from toc -->
+1. Update average block duration. 
+2. Invoke the Minting Curve's [yearly_mint](#yearly-mint) to receive the theoretic yearly amount of rewards.
+2. Calculate block total rewards according to the yearly mint and average block duration.
+3. Calculate the fraction of the rewards dedicated to BTC pools.
+4. Subtract the BTC rewards from the total to get the STRK rewards.
+#### access control <!-- omit from toc -->
+Only staking contract.
+
 ### update_unclaimed_rewards_from_staking_contract
 ```rust
 fn update_unclaimed_rewards_from_staking_contract(ref self: TContractState, rewards: Amount)

src/constants.cairo

@@ -16,3 +16,6 @@ pub(crate) const K: u8 = 2;
 pub(crate) const ALPHA: u128 = 25;
 /// Denominator used to scale `ALPHA` when computing BTC and STRK weights.
 pub(crate) const ALPHA_DENOMINATOR: u128 = 100;
+
+/// Number of seconds in one year.
+pub(crate) const SECONDS_IN_YEAR: u64 = 365 * 24 * 60 * 60;

src/errors.cairo

@@ -57,6 +57,8 @@ pub(crate) enum InternalError {
     UNEXPECTED_INTERNAL_MEMBER_INFO_VERSION,
     INVALID_REWARDS_TRACE_IDX,
     MISSING_CLASS_HASH,
+    INVALID_BLOCK_NUMBER,
+    INVALID_BLOCK_TIMESTAMP,
 }
 
 impl DescribableInternalError of Describable<InternalError> {
@@ -73,6 +75,8 @@ impl DescribableInternalError of Describable<InternalError> {
             InternalError::UNEXPECTED_INTERNAL_MEMBER_INFO_VERSION => "Unexpected VInternalPoolMemberInfo version",
             InternalError::INVALID_REWARDS_TRACE_IDX => "Invalid cumulative rewards trace idx",
             InternalError::MISSING_CLASS_HASH => "Missing class hash",
+            InternalError::INVALID_BLOCK_NUMBER => "Invalid block number",
+            InternalError::INVALID_BLOCK_TIMESTAMP => "Invalid block timestamp",
         }
     }
 }

src/flow_test/utils.cairo

@@ -56,7 +56,7 @@ use staking::staking::tests::interface_v1::{
     IStakingV1ForTestsDispatcher, IStakingV1ForTestsDispatcherTrait,
 };
 use staking::test_utils::constants::{
-    AVG_BLOCK_TIME, BTC_18D_CONFIG, BTC_DECIMALS_18, BTC_TOKEN_NAME, BTC_TOKEN_NAME_2,
+    AVG_BLOCK_DURATION, BTC_18D_CONFIG, BTC_DECIMALS_18, BTC_TOKEN_NAME, BTC_TOKEN_NAME_2,
     EPOCH_DURATION, EPOCH_LENGTH, EPOCH_STARTING_BLOCK, INITIAL_SUPPLY, OWNER_ADDRESS,
     STARTING_BLOCK_OFFSET, TESTING_C_NUM, TEST_BTC_DECIMALS, UPGRADE_GOVERNOR,
 };
@@ -1166,7 +1166,7 @@ pub(crate) impl SystemImpl of SystemTrait {
         if current_block < EPOCH_STARTING_BLOCK {
             let blocks = EPOCH_STARTING_BLOCK - current_block;
             advance_block_number_global(:blocks);
-            self.advance_time(time: TimeDelta { seconds: blocks * AVG_BLOCK_TIME });
+            self.advance_time(time: TimeDelta { seconds: blocks * AVG_BLOCK_DURATION });
         } else {
             let epoch_info = self.staking.get_epoch_info();
             /// Note: This calculation of the next epoch's starting block may be incorrect
@@ -1175,7 +1175,7 @@ pub(crate) impl SystemImpl of SystemTrait {
                 + epoch_info.epoch_len_in_blocks().into();
             let blocks = next_epoch_starting_block - current_block;
             advance_block_number_global(:blocks);
-            self.advance_time(time: TimeDelta { seconds: blocks * AVG_BLOCK_TIME });
+            self.advance_time(time: TimeDelta { seconds: blocks * AVG_BLOCK_DURATION });
         }
     }
 

src/reward_supplier/errors.cairo

@@ -4,13 +4,15 @@ use starkware_utils::errors::{Describable, ErrorDisplay};
 pub enum Error {
     ON_RECEIVE_NOT_FROM_STARKGATE,
     UNEXPECTED_TOKEN,
+    BLOCK_DURATION_OVERFLOW,
 }
 
 impl DescribableError of Describable<Error> {
     fn describe(self: @Error) -> ByteArray {
         match self {
             Error::ON_RECEIVE_NOT_FROM_STARKGATE => "Only StarkGate can call on_receive",
             Error::UNEXPECTED_TOKEN => "Unexpected token",
+            Error::BLOCK_DURATION_OVERFLOW => "Block duration calculation overflow",
         }
     }
 }

src/reward_supplier/interface.cairo

@@ -4,12 +4,30 @@ use starknet::{ContractAddress, EthAddress};
 #[starknet::interface]
 pub trait IRewardSupplier<TContractState> {
     /// Returns ([`Amount`](staking::types::Amount), [`Amount`](staking::types::Amount)) of rewards
-    /// for the current epoch, for STRK and BTC respectively.
+    /// for the current epoch, for STRK and BTC respectively (in FRI).
+    /// Used for attestation rewards.
     ///
     /// #### Internal calls:
     /// - [`minting_curve::minting_curve::interface::IMintingCurve::yearly_mint`]
     /// - [`staking::staking::interface::IStaking::get_epoch_info`]
     fn calculate_current_epoch_rewards(self: @TContractState) -> (Amount, Amount);
+    /// Returns ([`Amount`](staking::types::Amount), [`Amount`](staking::types::Amount)) of rewards
+    /// for block in the current epoch, for STRK and BTC respectively (in FRI).
+    /// Used for the consensus rewards.
+    ///
+    /// This function is called once per epoch. It updates `avg_block_duration` and returns (STRK,
+    /// BTC) block rewards for the current epoch.
+    ///
+    /// #### Errors:
+    /// -
+    /// [`CALLER_IS_NOT_STAKING_CONTRACT`](staking::errors::GenericError::CALLER_IS_NOT_STAKING_CONTRACT)
+    ///
+    /// #### Access control:
+    /// Only staking contract.
+    ///
+    /// #### Internal calls:
+    /// - [`minting_curve::minting_curve::interface::IMintingCurve::yearly_mint`]
+    fn update_current_epoch_block_rewards(ref self: TContractState) -> (Amount, Amount);
     /// Updates the unclaimed rewards from the staking contract.
     ///
     /// #### Emits:

src/reward_supplier/reward_supplier.cairo

@@ -6,15 +6,15 @@ pub mod RewardSupplier {
     use openzeppelin::access::accesscontrol::AccessControlComponent;
     use openzeppelin::introspection::src5::SRC5Component;
     use openzeppelin::token::erc20::interface::{IERC20Dispatcher, IERC20DispatcherTrait};
-    use staking::constants::{ALPHA, STRK_IN_FRIS, STRK_TOKEN_ADDRESS};
+    use staking::constants::{ALPHA, SECONDS_IN_YEAR, STRK_IN_FRIS, STRK_TOKEN_ADDRESS};
     use staking::errors::{GenericError, InternalError};
     use staking::minting_curve::interface::{IMintingCurveDispatcher, IMintingCurveDispatcherTrait};
     use staking::reward_supplier::errors::Error;
     use staking::reward_supplier::interface::{Events, IRewardSupplier, RewardSupplierInfoV1};
     use staking::reward_supplier::utils::{calculate_btc_rewards, compute_threshold};
     use staking::staking::interface::{IStakingDispatcher, IStakingDispatcherTrait};
     use staking::staking::objects::EpochInfoTrait;
-    use staking::types::Amount;
+    use staking::types::{Amount, BlockNumber};
     use starknet::storage::{StoragePointerReadAccess, StoragePointerWriteAccess};
     use starknet::syscalls::send_message_to_l1_syscall;
     use starknet::{
@@ -25,9 +25,14 @@ pub mod RewardSupplier {
     use starkware_utils::erc20::erc20_utils::CheckedIERC20DispatcherTrait;
     use starkware_utils::errors::OptionAuxTrait;
     use starkware_utils::interfaces::identity::Identity;
-    use starkware_utils::math::utils::ceil_of_division;
+    use starkware_utils::math::utils::{ceil_of_division, mul_wide_and_div};
+    use starkware_utils::time::time::Timestamp;
     pub const CONTRACT_IDENTITY: felt252 = 'Reward Supplier';
     pub const CONTRACT_VERSION: felt252 = '3.0.0';
+    /// Scale factor for block duration measurements. 100 implies granularity of 100th of second.
+    pub(crate) const BLOCK_DURATION_SCALE: u64 = 100;
+    /// Default avg block duration.
+    pub(crate) const DEFAULT_AVG_BLOCK_DURATION: u64 = 3 * BLOCK_DURATION_SCALE;
 
     component!(path: ReplaceabilityComponent, storage: replaceability, event: ReplaceabilityEvent);
     component!(path: RolesComponent, storage: roles, event: RolesEvent);
@@ -71,6 +76,14 @@ pub mod RewardSupplier {
         l1_reward_supplier: felt252,
         /// Token bridge address.
         starkgate_address: ContractAddress,
+        /// Average block duration in units of 1 / BLOCK_TIME_SCALE seconds.
+        // TODO: Initial in EIC.
+        // TODO: Setter.
+        // TODO: View?
+        avg_block_duration: u64,
+        /// The latest block data used for average block duration calculation.
+        /// Updated at the start of each epoch.
+        block_snapshot: (BlockNumber, Timestamp),
     }
 
     #[event]
@@ -109,6 +122,7 @@ pub mod RewardSupplier {
         self.minting_curve_dispatcher.contract_address.write(minting_curve_contract);
         self.l1_reward_supplier.write(l1_reward_supplier);
         self.starkgate_address.write(starkgate_address);
+        self.avg_block_duration.write(DEFAULT_AVG_BLOCK_DURATION);
     }
 
     #[abi(embed_v0)]
@@ -139,6 +153,30 @@ pub mod RewardSupplier {
             (strk_rewards, btc_rewards)
         }
 
+        // TODO: Emit event?
+        fn update_current_epoch_block_rewards(ref self: ContractState) -> (Amount, Amount) {
+            let staking_contract = self.staking_contract.read();
+            assert!(
+                get_caller_address() == staking_contract,
+                "{}",
+                GenericError::CALLER_IS_NOT_STAKING_CONTRACT,
+            );
+            self.set_avg_block_duration();
+            // Calculate block rewards for the current epoch.
+            let minting_curve_dispatcher = self.minting_curve_dispatcher.read();
+            let yearly_mint = minting_curve_dispatcher.yearly_mint();
+            let avg_block_duration = self.avg_block_duration.read();
+            let total_rewards = mul_wide_and_div(
+                lhs: yearly_mint,
+                rhs: avg_block_duration.into(),
+                div: BLOCK_DURATION_SCALE.into() * SECONDS_IN_YEAR.into(),
+            )
+                .expect_with_err(err: InternalError::REWARDS_COMPUTATION_OVERFLOW);
+            let btc_rewards = calculate_btc_rewards(:total_rewards);
+            let strk_rewards = total_rewards - btc_rewards;
+            (strk_rewards, btc_rewards)
+        }
+
         fn update_unclaimed_rewards_from_staking_contract(
             ref self: ContractState, rewards: Amount,
         ) {
@@ -259,5 +297,43 @@ pub mod RewardSupplier {
             let to_address = self.l1_reward_supplier.read();
             send_message_to_l1_syscall(:to_address, :payload).unwrap_syscall();
         }
+
+        fn set_avg_block_duration(ref self: ContractState) {
+            let current_block_number = starknet::get_block_number();
+            let current_timestamp = starknet::get_block_timestamp();
+            let (snapshot_block_number, snapshot_timestamp) = self.block_snapshot.read();
+            // Sanity asserts.
+            assert!(
+                current_block_number > snapshot_block_number,
+                "{}",
+                InternalError::INVALID_BLOCK_NUMBER,
+            );
+            assert!(
+                current_timestamp > snapshot_timestamp.into(),
+                "{}",
+                InternalError::INVALID_BLOCK_TIMESTAMP,
+            );
+            self
+                .block_snapshot
+                .write((current_block_number, Timestamp { seconds: current_timestamp }));
+            // If this is the first time we're setting the block snapshot, can't calculate avg block
+            // time yet.
+            if snapshot_block_number.is_zero() || snapshot_timestamp.is_zero() {
+                return;
+            }
+            let time_delta = current_timestamp - snapshot_timestamp.into();
+            // *Note*: `num_blocks` should match the epoch length in blocks. This calculation is
+            // expected to run on the first block of each epoch, assuming `update_rewards` is called
+            // every block.
+            // We calculate `num_blocks` instead of using the configured value to keep the average
+            // accurate even if some calls are missed.
+            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);
+        }
     }
 }