fix: alpha accounting precision and add repair mechanism

Author: leonace924

pallets/subtensor/src/lib.rs

@@ -2612,13 +2612,16 @@ impl<T: Config + pallet_balances::Config<Balance = u64>>
             Error::<T>::HotKeyAccountNotExists
         );
 
+        // Apply share-pool math first because the actual credited amount can differ due to
+        // rounding/precision.
+        let actual_alpha =
+            Self::increase_stake_for_hotkey_and_coldkey_on_subnet(hotkey, coldkey, netuid, alpha);
+
         // Increse alpha out counter
         SubnetAlphaOut::<T>::mutate(netuid, |total| {
-            *total = total.saturating_add(alpha);
+            *total = total.saturating_add(actual_alpha);
         });
 
-        Self::increase_stake_for_hotkey_and_coldkey_on_subnet(hotkey, coldkey, netuid, alpha);
-
         Ok(())
     }
 
@@ -2633,14 +2636,17 @@ impl<T: Config + pallet_balances::Config<Balance = u64>>
             Error::<T>::HotKeyAccountNotExists
         );
 
+        // Apply share-pool math first because the actual debited amount can differ due to
+        // rounding/precision.
+        let actual_alpha =
+            Self::decrease_stake_for_hotkey_and_coldkey_on_subnet(hotkey, coldkey, netuid, alpha);
+
         // Decrese alpha out counter
         SubnetAlphaOut::<T>::mutate(netuid, |total| {
-            *total = total.saturating_sub(alpha);
+            *total = total.saturating_sub(actual_alpha);
         });
 
-        Ok(Self::decrease_stake_for_hotkey_and_coldkey_on_subnet(
-            hotkey, coldkey, netuid, alpha,
-        ))
+        Ok(actual_alpha)
     }
 }
 

pallets/subtensor/src/macros/dispatches.rs

@@ -2431,5 +2431,26 @@ mod dispatches {
 
             Ok(())
         }
+
+        /// Set SubnetAlphaOut for a subnet (root only).
+        ///
+        /// This is an administrative escape hatch to repair alpha issuance / burn accounting
+        /// when historical drift is detected.
+        #[pallet::call_index(125)]
+        #[pallet::weight((\n            Weight::from_parts(6_000, 0)\n            .saturating_add(T::DbWeight::get().reads(1_u64))\n            .saturating_add(T::DbWeight::get().writes(1_u64)),\n            DispatchClass::Operational,\n            Pays::Yes\n        ))]
+        pub fn sudo_set_subnet_alpha_out(
+            origin: OriginFor<T>,
+            netuid: NetUid,
+            alpha_out: AlphaCurrency,
+        ) -> DispatchResult {
+            ensure_root(origin)?;
+
+            ensure!(Self::if_subnet_exist(netuid), Error::<T>::SubnetNotExists);
+
+            SubnetAlphaOut::<T>::insert(netuid, alpha_out);
+            Self::deposit_event(Event::SubnetAlphaOutSet(netuid, alpha_out));
+
+            Ok(())
+        }
     }
 }

pallets/subtensor/src/macros/events.rs

@@ -322,6 +322,12 @@ mod events {
         /// (coldkey, hotkey, amount, subnet_id)
         AlphaBurned(T::AccountId, T::AccountId, AlphaCurrency, NetUid),
 
+        /// Subnet alpha-out tracker has been updated via sudo.
+        ///
+        /// Parameters:
+        /// (netuid, alpha_out)
+        SubnetAlphaOutSet(NetUid, AlphaCurrency),
+
         /// An EVM key has been associated with a hotkey.
         EvmKeyAssociated {
             /// The subnet that the hotkey belongs to.

pallets/subtensor/src/staking/recycle_alpha.rs

@@ -45,18 +45,18 @@ impl<T: Config> Pallet<T> {
             Self::get_stake_for_hotkey_and_coldkey_on_subnet(&hotkey, &coldkey, netuid);
         let amount = amount.min(alpha_available);
 
-        ensure!(
-            SubnetAlphaOut::<T>::get(netuid) >= amount,
-            Error::<T>::InsufficientLiquidity
-        );
-
         // Deduct from the coldkey's stake.
         let actual_alpha_decrease = Self::decrease_stake_for_hotkey_and_coldkey_on_subnet(
             &hotkey, &coldkey, netuid, amount,
         );
 
+        ensure!(
+            SubnetAlphaOut::<T>::get(netuid) >= actual_alpha_decrease,
+            Error::<T>::NotEnoughAlphaOutToRecycle
+        );
+
         // Recycle means we should decrease the alpha issuance tracker.
-        Self::recycle_subnet_alpha(netuid, amount);
+        Self::recycle_subnet_alpha(netuid, actual_alpha_decrease);
 
         Self::deposit_event(Event::AlphaRecycled(
             coldkey,

pallets/subtensor/src/tests/recycle_alpha.rs

@@ -45,8 +45,19 @@ fn test_recycle_success() {
             netuid
         ));
 
-        assert!(TotalHotkeyAlpha::<Test>::get(hotkey, netuid) < initial_alpha);
-        assert!(SubnetAlphaOut::<Test>::get(netuid) < initial_net_alpha);
+        let new_alpha = TotalHotkeyAlpha::<Test>::get(hotkey, netuid);
+        let new_net_alpha = SubnetAlphaOut::<Test>::get(netuid);
+
+        assert!(new_alpha < initial_alpha);
+        assert!(new_net_alpha < initial_net_alpha);
+
+        // Accounting invariant: recycle should reduce SubnetAlphaOut by the *same* amount of alpha
+        // that was actually removed from the hotkey's total.
+        assert_eq!(
+            initial_net_alpha.saturating_sub(new_net_alpha),
+            initial_alpha.saturating_sub(new_alpha)
+        );
+
         assert!(
             SubtensorModule::get_stake_for_hotkey_and_coldkey_on_subnet(&hotkey, &coldkey, netuid)
                 < initial_alpha