[Feature] Configurable Tempo & Owner-Triggered Epochs

eco-tests/src/helpers.rs

@@ -87,9 +87,9 @@ pub fn next_block_no_epoch(netuid: NetUid) -> u64 {
     let high_tempo: u16 = u16::MAX - 1;
     let old_tempo: u16 = SubtensorModule::get_tempo(netuid);
 
-    SubtensorModule::set_tempo(netuid, high_tempo);
+    SubtensorModule::set_tempo_unchecked(netuid, high_tempo);
     let new_block = next_block();
-    SubtensorModule::set_tempo(netuid, old_tempo);
+    SubtensorModule::set_tempo_unchecked(netuid, old_tempo);
 
     new_block
 }
@@ -99,14 +99,14 @@ pub fn run_to_block_no_epoch(netuid: NetUid, n: u64) {
     let high_tempo: u16 = u16::MAX - 1;
     let old_tempo: u16 = SubtensorModule::get_tempo(netuid);
 
-    SubtensorModule::set_tempo(netuid, high_tempo);
+    SubtensorModule::set_tempo_unchecked(netuid, high_tempo);
     run_to_block(n);
-    SubtensorModule::set_tempo(netuid, old_tempo);
+    SubtensorModule::set_tempo_unchecked(netuid, old_tempo);
 }
 
 pub fn step_epochs(count: u16, netuid: NetUid) {
     for _ in 0..count {
-        let blocks_to_next_epoch = SubtensorModule::blocks_until_next_epoch(
+        let blocks_to_next_epoch = SubtensorModule::blocks_until_next_auto_epoch(
             netuid,
             SubtensorModule::get_tempo(netuid),
             SubtensorModule::get_current_block_as_u64(),

pallets/admin-utils/src/lib.rs

@@ -975,7 +975,7 @@ pub mod pallet {
                 pallet_subtensor::Pallet::<T>::if_subnet_exist(netuid),
                 Error::<T>::SubnetDoesNotExist
             );
-            pallet_subtensor::Pallet::<T>::set_tempo(netuid, tempo);
+            pallet_subtensor::Pallet::<T>::apply_tempo_with_cycle_reset(netuid, tempo);
             log::debug!("TempoSet( netuid: {netuid:?} tempo: {tempo:?} ) ");
             Ok(())
         }

pallets/admin-utils/src/tests/mod.rs

@@ -1981,16 +1981,20 @@ fn test_sudo_set_admin_freeze_window_and_rate() {
 fn test_freeze_window_blocks_root_and_owner() {
     new_test_ext().execute_with(|| {
         let netuid = NetUid::from(1);
-        let tempo = 10;
+        let tempo: u16 = 10;
         // Create subnet with tempo 10
         add_network(netuid, tempo);
         // Set freeze window to 3 blocks
         assert_ok!(AdminUtils::sudo_set_admin_freeze_window(
             <<Test as Config>::RuntimeOrigin>::root(),
             3
         ));
-        // Advance to a block where remaining < 3
-        run_to_block((tempo - 2).into());
+        // Pin the state-based scheduler so the next auto-epoch lands at
+        // `tempo + 1`. Freeze window covers blocks (next_auto - 3, next_auto].
+        pallet_subtensor::LastEpochBlock::<Test>::insert(netuid, 0);
+        let next_auto = (tempo as u64).saturating_add(1);
+        // Advance to a block inside the freeze window (remaining < 3).
+        run_to_block(next_auto - 2);
 
         // Root should be blocked during freeze window
         assert_noop!(
@@ -2086,7 +2090,7 @@ fn test_owner_hyperparam_update_rate_limit_enforced() {
         SubnetOwner::<Test>::insert(netuid, owner);
 
         // Set tempo to 1 so owner hyperparam RL = 2 tempos = 2 blocks
-        SubtensorModule::set_tempo(netuid, 1);
+        SubtensorModule::set_tempo_unchecked(netuid, 1);
         // Disable admin freeze window to avoid blocking on small tempo
         assert_ok!(AdminUtils::sudo_set_admin_freeze_window(
             <<Test as Config>::RuntimeOrigin>::root(),
@@ -2141,7 +2145,7 @@ fn test_hyperparam_rate_limit_enforced_by_tempo() {
         SubnetOwner::<Test>::insert(netuid, owner);
 
         // Set tempo to 1 so RL = 2 blocks
-        SubtensorModule::set_tempo(netuid, 1);
+        SubtensorModule::set_tempo_unchecked(netuid, 1);
         // Disable admin freeze window to avoid blocking on small tempo
         assert_ok!(AdminUtils::sudo_set_admin_freeze_window(
             <<Test as Config>::RuntimeOrigin>::root(),
@@ -2189,7 +2193,7 @@ fn test_owner_hyperparam_rate_limit_independent_per_param() {
         SubnetOwner::<Test>::insert(netuid, owner);
 
         // Use small tempo to make RL short and deterministic (2 blocks when tempo=1)
-        SubtensorModule::set_tempo(netuid, 1);
+        SubtensorModule::set_tempo_unchecked(netuid, 1);
         // Disable admin freeze window so it doesn't interfere with small tempo
         assert_ok!(AdminUtils::sudo_set_admin_freeze_window(
             <<Test as Config>::RuntimeOrigin>::root(),

pallets/subtensor/runtime-api/src/lib.rs

@@ -50,6 +50,7 @@ sp_api::decl_runtime_apis! {
         fn get_selective_mechagraph(netuid: NetUid, subid: MechId, metagraph_indexes: Vec<u16>) -> Option<SelectiveMetagraph<AccountId32>>;
         fn get_subnet_to_prune() -> Option<NetUid>;
         fn get_subnet_account_id(netuid: NetUid) -> Option<AccountId32>;
+        fn get_next_epoch_start_block(netuid: NetUid) -> Option<u64>;
     }
 
     pub trait StakeInfoRuntimeApi {

pallets/subtensor/src/benchmarks.rs

@@ -2196,6 +2196,54 @@ mod pallet_benchmarks {
         );
     }
 
+    #[benchmark]
+    fn set_tempo() {
+        let netuid = NetUid::from(1);
+        let coldkey: T::AccountId = account("Owner", 0, 1);
+
+        Subtensor::<T>::init_new_network(netuid, 1u16);
+        SubnetOwner::<T>::insert(netuid, coldkey.clone());
+        SubtokenEnabled::<T>::insert(netuid, true);
+        Subtensor::<T>::set_commit_reveal_weights_enabled(netuid, false);
+        Subtensor::<T>::set_admin_freeze_window(0);
+
+        #[extrinsic_call]
+        _(RawOrigin::Signed(coldkey.clone()), netuid, MIN_TEMPO);
+    }
+
+    #[benchmark]
+    fn set_activity_cutoff_factor() {
+        let netuid = NetUid::from(1);
+        let coldkey: T::AccountId = account("Owner", 0, 1);
+
+        Subtensor::<T>::init_new_network(netuid, 1u16);
+        SubnetOwner::<T>::insert(netuid, coldkey.clone());
+        SubtokenEnabled::<T>::insert(netuid, true);
+        Subtensor::<T>::set_admin_freeze_window(0);
+
+        #[extrinsic_call]
+        _(
+            RawOrigin::Signed(coldkey.clone()),
+            netuid,
+            INITIAL_ACTIVITY_CUTOFF_FACTOR_MILLI,
+        );
+    }
+
+    #[benchmark]
+    fn trigger_epoch() {
+        let netuid = NetUid::from(1);
+        let coldkey: T::AccountId = account("Owner", 0, 1);
+
+        Subtensor::<T>::init_new_network(netuid, 1u16);
+        SubnetOwner::<T>::insert(netuid, coldkey.clone());
+        SubtokenEnabled::<T>::insert(netuid, true);
+        Subtensor::<T>::set_commit_reveal_weights_enabled(netuid, false);
+        Subtensor::<T>::set_admin_freeze_window(0);
+
+        #[extrinsic_call]
+        _(RawOrigin::Signed(coldkey.clone()), netuid);
+    }
+
     impl_benchmark_test_suite!(
         Subtensor,
         crate::tests::mock::new_test_ext(1),

pallets/subtensor/src/coinbase/block_step.rs

@@ -36,9 +36,11 @@ impl<T: Config + pallet_drand::Config> Pallet<T> {
     }
 
     fn try_set_pending_children(block_number: u64) {
+        // Called *after* `run_coinbase` has advanced `LastEpochBlock` for any
+        // subnet whose epoch slot fired this block — `should_run_epoch` is no
+        // longer true. Detect "epoch just fired" by `LastEpochBlock == block`.
         for netuid in Self::get_all_subnet_netuids() {
-            if Self::should_run_epoch(netuid, block_number) {
-                // Set pending children on the epoch.
+            if LastEpochBlock::<T>::get(netuid) == block_number {
                 Self::do_set_pending_children(netuid);
             }
         }

pallets/subtensor/src/coinbase/mod.rs

@@ -7,3 +7,4 @@ pub mod root;
 pub mod run_coinbase;
 pub mod subnet_emissions;
 pub mod tao;
+pub mod tempo_control;

pallets/subtensor/src/coinbase/root.rs

@@ -284,6 +284,9 @@ impl<T: Config> Pallet<T> {
         MaxAllowedUids::<T>::remove(netuid);
         ImmunityPeriod::<T>::remove(netuid);
         ActivityCutoff::<T>::remove(netuid);
+        ActivityCutoffFactorMilli::<T>::remove(netuid);
+        LastEpochBlock::<T>::remove(netuid);
+        PendingEpochAt::<T>::remove(netuid);
         MinAllowedWeights::<T>::remove(netuid);
         RegistrationsThisInterval::<T>::remove(netuid);
         POWRegistrationsThisInterval::<T>::remove(netuid);

pallets/subtensor/src/coinbase/run_coinbase.rs

@@ -64,7 +64,14 @@ impl<T: Config> Pallet<T> {
         let emissions_to_distribute = Self::drain_pending(&subnets, current_block);
 
         // --- 6. Distribute the emissions to the subnets.
+        //   Bonds masking inside `distribute_emission` reads `LastMechansimStepBlock` and
+        //   must see the previous successful run, so we delay the write until after.
         Self::distribute_emissions_to_subnets(&emissions_to_distribute);
+
+        // --- 7. Mark each successful epoch run as the last mechanism step.
+        for netuid in emissions_to_distribute.keys() {
+            LastMechansimStepBlock::<T>::insert(*netuid, current_block);
+        }
     }
 
     pub fn inject_and_maybe_swap(
@@ -318,19 +325,35 @@ impl<T: Config> Pallet<T> {
             NetUid,
             (AlphaBalance, AlphaBalance, AlphaBalance, AlphaBalance),
         > = BTreeMap::new();
-        // --- Drain pending emissions for all subnets hat are at their tempo.
-        // Run the epoch for *all* subnets, even if we don't emit anything.
+        // Per-block cap on number of epochs that may run; the rest are deferred 1 block forward
+        // by setting `PendingEpochAt`.
+        let mut epochs_run_this_block: u32 = 0;
+
         for &netuid in subnets.iter() {
-            // Increment blocks since last step.
+            // Increment blocks since last *successful* step (existing semantics).
             BlocksSinceLastStep::<T>::mutate(netuid, |total| *total = total.saturating_add(1));
 
-            // Run the epoch if applicable.
-            if Self::should_run_epoch(netuid, current_block)
-                && Self::is_epoch_input_state_consistent(netuid)
-            {
-                // Restart counters.
+            if !Self::should_run_epoch(netuid, current_block) {
+                continue;
+            }
+
+            // Per-block cap — defer if already at limit.
+            if epochs_run_this_block >= MAX_EPOCHS_PER_BLOCK {
+                let next_block = current_block.saturating_add(1);
+                PendingEpochAt::<T>::insert(netuid, next_block);
+                Self::deposit_event(Event::EpochDeferred {
+                    netuid,
+                    from_block: current_block,
+                    to_block: next_block,
+                });
+                continue;
+            }
+
+            if Self::is_epoch_input_state_consistent(netuid) {
+                // Reset blocks-since counter; LastMechansimStepBlock is written
+                // post-distribute (see the caller), so bonds masking can read the
+                // previous successful run.
                 BlocksSinceLastStep::<T>::insert(netuid, 0);
-                LastMechansimStepBlock::<T>::insert(netuid, current_block);
 
                 // Get and drain the subnet pending emission.
                 let pending_server_alpha = PendingServerEmission::<T>::get(netuid);
@@ -357,7 +380,19 @@ impl<T: Config> Pallet<T> {
                         owner_cut,
                     ),
                 );
+                epochs_run_this_block = epochs_run_this_block.saturating_add(1);
+            } else {
+                // Schedule advances below; execution skipped. Pending emissions accumulate
+                // and will be drained by the next successful epoch.
+                Self::deposit_event(Event::EpochSkippedDueToInconsistentState {
+                    netuid,
+                    block: current_block,
+                });
             }
+
+            // Advance the schedule unconditionally — the slot is consumed.
+            LastEpochBlock::<T>::insert(netuid, current_block);
+            PendingEpochAt::<T>::insert(netuid, 0);
         }
         emissions_to_distribute
     }
@@ -996,28 +1031,57 @@ impl<T: Config> Pallet<T> {
     /// # Returns
     /// * `bool` - True if the epoch should run, false otherwise.
     pub fn should_run_epoch(netuid: NetUid, current_block: u64) -> bool {
-        Self::blocks_until_next_epoch(netuid, Self::get_tempo(netuid), current_block) == 0
+        let tempo = Self::get_tempo(netuid);
+        if tempo == 0 {
+            return false;
+        }
+        let pending = PendingEpochAt::<T>::get(netuid);
+        if pending > 0 && current_block >= pending {
+            return true;
+        }
+        if BlocksSinceLastStep::<T>::get(netuid) > MAX_TEMPO as u64 {
+            return true;
+        }
+        let last = LastEpochBlock::<T>::get(netuid);
+        let blocks_since = current_block.saturating_sub(last);
+        blocks_since > tempo as u64
     }
 
-    /// Helper function which returns the number of blocks remaining before we will run the epoch on this
-    /// network. Networks run their epoch when (block_number + netuid + 1 ) % (tempo + 1) = 0
-    /// tempo | netuid | # first epoch block
-    ///   1        0               0
-    ///   1        1               1
-    ///   2        0               1
-    ///   2        1               0
-    ///   100      0              99
-    ///   100      1              98
-    /// Special case: tempo = 0, the network never runs.
-    ///
-    pub fn blocks_until_next_epoch(netuid: NetUid, tempo: u16, block_number: u64) -> u64 {
+    /// Returns the number of blocks remaining before the next automatic epoch under the
+    /// stateful scheduler (period `tempo + 1`, anchored on `LastEpochBlock`). Does NOT account for:
+    ///     - `PendingEpochAt` (owner-triggered manual fire — could happen sooner),
+    ///     - `BlocksSinceLastStep > MAX_TEMPO` safety-net,
+    ///     - per-block-cap defer (could push the actual fire one or more blocks later)
+    /// Used by the admin-freeze-window predicate and external tooling. Returns `u64::MAX` when
+    /// `tempo == 0` (legacy defensive short-circuit).
+    pub fn blocks_until_next_auto_epoch(netuid: NetUid, tempo: u16, block_number: u64) -> u64 {
         if tempo == 0 {
             return u64::MAX;
         }
-        let netuid_plus_one = (u16::from(netuid) as u64).saturating_add(1);
-        let tempo_plus_one = (tempo as u64).saturating_add(1);
-        let adjusted_block = block_number.wrapping_add(netuid_plus_one);
-        let remainder = adjusted_block.checked_rem(tempo_plus_one).unwrap_or(0);
-        (tempo as u64).saturating_sub(remainder)
+        let last = LastEpochBlock::<T>::get(netuid);
+        // Period is `tempo + 1`: next firing at `last + tempo + 1`.
+        let next_auto = last.saturating_add(tempo as u64).saturating_add(1);
+        next_auto.saturating_sub(block_number)
+    }
+
+    /// Returns the absolute block number at which the next epoch is expected to fire for the
+    /// given subnet, considering both the automatic schedule (`LastEpochBlock + tempo + 1`) and
+    /// any owner-triggered `PendingEpochAt`. Returns `None` if `tempo == 0` (subnet does not run).
+    /// Does NOT account for the per-block cap deferral or the `BlocksSinceLastStep > MAX_TEMPO`
+    /// safety-net (which can fire earlier under extreme drift).
+    pub fn get_next_epoch_start_block(netuid: NetUid) -> Option<u64> {
+        let tempo = Self::get_tempo(netuid);
+        if tempo == 0 {
+            return None;
+        }
+        let last = LastEpochBlock::<T>::get(netuid);
+        let auto_next = last.saturating_add(tempo as u64).saturating_add(1);
+
+        let pending = PendingEpochAt::<T>::get(netuid);
+        if pending > 0 {
+            Some(auto_next.min(pending))
+        } else {
+            Some(auto_next)
+        }
     }
 }