Transactions

claim-root

Redeem accrued root dividends across every validator for the coldkey.

Root dividends accrue as shares of each validator's basket — an escrowed index fund of subnet alpha the chain builds from the validator's root dividends per its root weights (see set_root_weights). This call redeems the signing coldkey's owed shares on every validator it root-stakes to. The subnets argument is retained for call-data compatibility with pre-basket clients and is ignored — baskets have no per-subnet claim selection.

Prefer :class:ClaimRootWithHotkey to claim a single validator.

plan (and btcli root claim --dry-run) estimates the reserved inclusion fee versus the fee that will actually settle, compares that spent fee to accrued yield, warns when the claim loses money, and refuses when free TAO cannot cover the reserve.

Signer	Origin	Pallet	Wraps
`coldkey`	signed account (pallet role may apply)	SubtensorModule	`SubtensorModule.claim_root`

Parameters

Parameter	Type	Required	Description
`subnets`	array of integer	no	Ignored (kept for old-client call-data compatibility). Pass any non-empty netuid list; baskets claim fund-level.

Address parameters (--hotkey, --coldkey, --dest, ...) accept a raw ss58 address, an address-book or proxy-book name, or a local wallet/hotkey name.

CLI

Preview with --dry-run (shows fee, effects, and policy result without submitting), then submit:

btcli tx claim-root --dry-run
btcli tx claim-root -w my_coldkey

Python

import bittensor as bt
from bittensor.wallet import Wallet

wallet = Wallet(name="my_coldkey", hotkey="my_hotkey")
intent = bt.ClaimRoot()

sub = bt.Subtensor()
plan = sub.plan(intent, wallet)   # fee, effects, policy — no submission
result = sub.execute(intent, wallet)
if not result.success:
    print(result.error.code, result.error.remediation)

(bt.Subtensor is also the async client — async with bt.Subtensor() as client: — see The client.) Or build the intent by op name, as an agent would:

result = sub.execute_tool("claim_root", {...}, wallet)

On-chain implementation

SubtensorModule.claim_root — pallets/subtensor/src/macros/dispatches.rs#L1957:

#[pallet::call_index(121)]
// Signer is not in the call data, so admission uses the conservative
// MAX_ROOT_CLAIM_WORK envelope. Execution refuses a fat coldkey that
// would exceed it — use claim_root_with_hotkey per validator.
#[pallet::weight(
    <T as crate::pallet::Config>::WeightInfo::claim_root(Pallet::<T>::root_claim_declared_work())
)]
pub fn claim_root(
    origin: OriginFor<T>,
    subnets: BTreeSet<NetUid>,
) -> DispatchResultWithPostInfo {
    let coldkey: T::AccountId = ensure_signed(origin)?;
    let _ = subnets; // ignored: basket claims are fund-level, not per-subnet

    let hotkeys = StakingHotkeys::<T>::get(&coldkey);
    ensure!(
        Self::root_claim_fits_declared_budget(&hotkeys),
        Error::<T>::RootClaimTooHeavy
    );
    let hotkey_count = hotkeys.len() as u32;
    let outcome = Self::do_root_claim(coldkey.clone(), hotkeys)?;
    Self::maybe_add_coldkey_index(&coldkey);

    let weight = Self::root_claim_actual_weight(hotkey_count, &outcome);
    Ok((Some(weight), Pays::Yes).into())
}

Delegates to root_claim_fits_declared_budget, do_root_claim, maybe_add_coldkey_index.

Every file is browsable under /code exactly as built into the runtime, or as plain text under /code/raw/<path> (index: /code/index.json).