Root claim by shamil-gadelshin · Pull Request #2053 · opentensor/subtensor

shamil-gadelshin · 2025-09-12T10:25:46Z

Root Claim

This PR introduces a root claim mechanism. It replaces the automatic selling of root-alpha dividends with accumulation. Users can either:

Manually claim their accumulated share, or
Enable auto-sell, which automatically sells the accumulated share daily and transfers the proceeds to their account.

New extrinsics

set_root_claim_type — Set root-claim mode: auto or manual.
claim_root — Manually claim accumulated root dividends.

Storage changes

PendingRootAlphaDivs — Tracks root-alpha dividends between epochs.
RootClaimType — User’s preferred claim mode (auto or manual).
RootClaimable — User’s claimable share of alpha dividends.
RootClaimed — Accounting helper for alpha dividends (stake changes, claimed amounts).
StakingColdkeysByIndex — Supports randomized distribution of auto-claims per block.
StakingColdkeys — Supports root-dividends distribution.
NumStakingColdkeys — Count to support randomized auto-claim distribution per block.
NumRootClaim — Number of auto-claims to fulfill for a subnet in the current epoch.
AlphaMapLastKey — Supports staking coldkey migration.

Removed (obsolete storage maps)

TaoDividendsPerSubnet
PendingAlphaSwapped

Original PRs

…bnets

antlerminator · 2025-10-23T15:47:15Z

pallets/subtensor/src/coinbase/root.rs

        PendingEmission::<T>::remove(netuid);
-        PendingRootDivs::<T>::remove(netuid);
-        PendingAlphaSwapped::<T>::remove(netuid);
+        PendingRootAlphaDivs::<T>::remove(netuid);


PendingRootAlphaDivs::<T>::remove(netuid) is called twice: line 318 & 351

antlerminator

Pardon for the intrusion but I've heard this PR was close/ready to be merged yet after reading it I found a bunch of things that could be addressed 😬

pallets/subtensor/src/coinbase/run_coinbase.rs

antlerminator · 2025-10-23T19:35:48Z

pallets/subtensor/src/coinbase/run_coinbase.rs

-            log::debug!("hotkey: {hotkey:?} tao_take: {tao_take:?}");
-            let validator_stake = Self::increase_stake_for_hotkey_and_coldkey_on_subnet(
+            log::debug!("hotkey: {hotkey:?} alpha_take: {alpha_take:?}");
+            let _validator_stake = Self::increase_stake_for_hotkey_and_coldkey_on_subnet(


Suggested change

let _validator_stake = Self::increase_stake_for_hotkey_and_coldkey_on_subnet(

Self::increase_stake_for_hotkey_and_coldkey_on_subnet(

Is there a reason we keep the variable here?

antlerminator · 2025-10-23T20:05:04Z

pallets/subtensor/src/staking/claim_root.rs

+    pub fn add_stake_adjust_root_claimed_for_hotkey_and_coldkey(
+        hotkey: &T::AccountId,
+        coldkey: &T::AccountId,
+        amount: u64,


Shouldn't this be AlphaCurrency, similarly to how it's done in remove_stake_adjust_root_claimed_for_hotkey_and_coldkey?

pallets/subtensor/src/staking/helpers.rs

pallets/subtensor/src/tests/coinbase.rs

pallets/subtensor/src/lib.rs

antlerminator · 2025-10-23T20:18:07Z

pallets/subtensor/src/lib.rs

+    #[pallet::storage] // --- MAP ( hot ) --> MAP(netuid ) --> claimable_dividends | Root claimable dividends.
+    pub type RootClaimable<T: Config> = StorageMap<
+        _,
+        Blake2_128Concat,
+        T::AccountId,
+        BTreeMap<NetUid, I96F32>,
+        ValueQuery,
+        DefaultRootClaimable<T>,
+    >;


Shouldn't this be renamed to RootClaimableRatio to reflect it better what this exactly is? This wording is already used elsewhere in the code

shamil-gadelshin · 2025-10-24T11:17:02Z

Pardon for the intrusion but I've heard this PR was close/ready to be merged yet after reading it I found a bunch of things that could be addressed 😬

Thanks for the review. I addressed the majority of your comments.

pallets/subtensor/src/macros/dispatches.rs

antlerminator · 2025-10-28T17:39:36Z

Per discussion on the Open Dev call and the overall initiative of improvement of bookkeeping in Bittensor, can we please implement proper bookkeeping from the start for root claim? Back when I was reviewing this PR I saw two possibilities:

Emit event/events with the exact amounts of alpha that's being received or tao that was received due to selling
Add new storage variable that tracks the amount of alpha/tao that was just received, e.g., LastRootClaimed where for non-root netuids it'd track alpha received and for root netuid it'd track amount of tao received by selling other alphas (this name is not 100% ideal though)

Relevant discussion from CoR: https://discord.com/channels/1120750674595024897/1245487232928714863/1431026852008427572

dougsillars

it looks like root claim now charges fees to convert to tao?

dougsillars · 2025-10-29T11:56:23Z

pallets/subtensor/src/staking/claim_root.rs

+                    netuid,
+                    owed_u64.into(),
+                    T::SwapInterface::min_price::<TaoCurrency>(),
+                    false,


so we are charging a swap fee on root stakeholders now?

Adding fees has not been part of the public description of how this would function, afaik. Previous open discussions were that the default would function as it is now (just the option to continue to receive in TAO). The recent Discord announcement does say "If you do nothing, your claims use Swap", but this could be construed as the two options of root_claim_type and not the traditional swap with fees.
Is the intention for all root stakers to pay fees to receive dividends?

bdmason · 2025-10-29T13:07:03Z

Hey @shamil-gadelshin it looks like (apologies if I've misunderstood) the following is correct:

user unstakes from root
RootClaimed is reduced by what wasn't claimed but was claimable
user can restake and claim what they forgot to claim before step 1

If this is correct, there is likely to be an awful lot of dust that's effectively burned, but not actually burned as it's still technically accessible, though a user may have to earn more divs first to get over the threshold required to make a claim.

Would it not be better to just claim any outstanding divs when the user unstakes? Whilst there would be more operations on the unstake call, there won't be a never ending accumulation of storage in RootClaimed for all the dust left behind.

shamil-gadelshin · 2025-10-30T12:52:45Z

Per discussion on the Open Dev call and the overall initiative of improvement of bookkeeping in Bittensor, can we please implement proper bookkeeping from the start for root claim? Back when I was reviewing this PR I saw two possibilities:

Emit event/events with the exact amounts of alpha that's being received or tao that was received due to selling

Add new storage variable that tracks the amount of alpha/tao that was just received, e.g., LastRootClaimed where for non-root netuids it'd track alpha received and for root netuid it'd track amount of tao received by selling other alphas (this name is not 100% ideal though)

Relevant discussion from CoR: https://discord.com/channels/1120750674595024897/1245487232928714863/1431026852008427572

We plan to update this feature after the release.

leemcmullen · 2025-10-30T15:18:37Z

@shamil-gadelshin The PR description is confusing, it says:

set_root_claim_type — Set root-claim mode: auto or manual.

and

RootClaimType — User’s preferred claim mode (auto or manual).

Neither of which are true.

In fact, RootClaimType is either Swap or Keep. There is an enum with auto and manual options, but that's called RootClaimFrequencyEnum and doesn't seem to be used anywhere else in the subtensor codebase?

antlerminator · 2025-10-30T21:05:28Z

@shamil-gadelshin doing this after the release will mean that the off-chain bookkeeping is impossible between the release and that update... Basically the historical state will be "corrupted" so why not do it now? This is not a huge change in itself but it's impossible to do by non-core devs

shamil-gadelshin added 3 commits September 10, 2025 12:59

Add root claim infrastructure

2f7ea4b

Alter coinbase.rs

c579597

Alter tests

6c614fe

shamil-gadelshin requested a review from gztensor September 12, 2025 10:25

shamil-gadelshin self-assigned this Sep 12, 2025

shamil-gadelshin and others added 25 commits September 12, 2025 14:32

Remove comments

e04c8e9

Change TaoDividendsPerSubnet -> AlphaDividendsPerSubnet

f607993

Fix: PendingAlphaSwapped only needs to increase for non-subsidized su…

8877c40

…bnets

Update tests

e7605df

Update coinbase.rs

c48a9c4

Cargo fmt

9fa484a

Remove TaoDividendsPerSubnet

7f5dba4

Remove PendingAlphaSwapped

28e2f74

Rename RootDebt -> RootClaimed

eb32237

Fix RootClaimable map

2e613b0

Add root claim tests.

b125673

Add basic test with drain_emissions

0151f49

Update tests.

83b2b36

Update tests

c482f2f

Simplify tests

55c1b1d

Add disproportional stake test

a11d7a9

Add test with removed stake.

e3cc8e1

Fix existing tests

dd44dd8

Update tests

0b13d2e

Fix swap claim root

8d1140d

Add basic run_coinbase test

65bb4f0

Fix block indices to claim

1accdfa

Optimize RootClaimable

c09bcb3

Update benchmarks

fc161b3

Add coldkey to the new map.

b39d51c

shamil-gadelshin added the apply-benchmark-patch label Oct 23, 2025

github-actions bot removed the apply-benchmark-patch label Oct 23, 2025

shamil-gadelshin added the apply-benchmark-patch label Oct 23, 2025

auto-update benchmark weights

55f30b2

github-actions bot removed the apply-benchmark-patch label Oct 23, 2025

antlerminator reviewed Oct 23, 2025

View reviewed changes

shamil-gadelshin added 2 commits October 24, 2025 13:52

Apply review suggestions

558f908

Merge branch 'devnet-ready' into root-claim2

28deede

sam0x17 added the apply-benchmark-patch label Oct 27, 2025

auto-update benchmark weights

efbe782

github-actions bot removed the apply-benchmark-patch label Oct 27, 2025

basfroman mentioned this pull request Oct 27, 2025

[v10] Root claim/ Airdrop mechanism implementation opentensor/bittensor#3117

Merged

3 tasks

sam0x17 previously approved these changes Oct 27, 2025

View reviewed changes

basfroman reviewed Oct 28, 2025

View reviewed changes

pallets/subtensor/src/macros/dispatches.rs Outdated Show resolved Hide resolved

shamil-gadelshin added 2 commits October 28, 2025 12:36

Enable zero as sudo_set_num_root_claims param value.

f08ef46

Add subnets to claim_root extrinsic.

91e5776

shamil-gadelshin dismissed sam0x17’s stale review via 91e5776 October 28, 2025 12:14

dougsillars reviewed Oct 29, 2025

View reviewed changes

sam0x17 approved these changes Oct 29, 2025

View reviewed changes

sam0x17 merged commit f190dca into devnet-ready Oct 29, 2025
53 of 57 checks passed

sam0x17 mentioned this pull request Oct 29, 2025

mainnet deploy 11/04/2025 #2161

Merged

This was referenced Nov 5, 2025

Hotfix/vune/epoch sub fix #2185

Closed

hotfix: epoch w/subsidy fix #2187

Merged

	let _validator_stake = Self::increase_stake_for_hotkey_and_coldkey_on_subnet(
	Self::increase_stake_for_hotkey_and_coldkey_on_subnet(

Conversation

shamil-gadelshin commented Sep 12, 2025 • edited by sam0x17 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Root Claim

New extrinsics

Storage changes

Removed (obsolete storage maps)

Original PRs

Uh oh!

antlerminator Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

antlerminator left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

antlerminator Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

antlerminator Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

antlerminator Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

shamil-gadelshin commented Oct 24, 2025

Uh oh!

Uh oh!

antlerminator commented Oct 28, 2025

Uh oh!

dougsillars left a comment

Choose a reason for hiding this comment

Uh oh!

dougsillars Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Swamination-Yuma Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

bdmason commented Oct 29, 2025

Uh oh!

Uh oh!

shamil-gadelshin commented Oct 30, 2025

Uh oh!

leemcmullen commented Oct 30, 2025

Uh oh!

antlerminator commented Oct 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

shamil-gadelshin commented Sep 12, 2025 •

edited by sam0x17

Loading