claim-root-with-hotkey

Redeems the signing coldkey's owed shares on the given validator only: that basket pays out pro-rata (subnet alpha holdings are sold to TAO at the current pool price) and the proceeds are staked back to root on the same validator. Other validators' accrued yield is left untouched. Claims whose estimated payout is below the chain's claim threshold (see root_claim_threshold) are silently skipped and keep accruing. Orphaned dust holdings in the basket (subnets outside the validator's current weight vector, worth less than the same threshold) are consolidated into the fund's root (TAO) slot as a side effect, so the per-holding claim fee shrinks over time; curated positions are left to compound. Since spec 468 a claim also leaves dust rows unsold: a holding worth less than min(1 TAO, 0.1% of the fund's anchored NAV), or one where this claimant's own slice is worth less than 0.0001 TAO, is neither sold nor paid — provided the slice is worth at most 0.01 TAO (the forfeit cap; bigger slices of small rows are sold as before). The whole entitlement is still settled, so those slices stay in the fund for the remaining holders (event BasketClaimDustSkipped). The transaction fee is charged by work actually done: holdings redeemed pay full weight, holdings merely scanned (including skipped dust rows) pay a small per-row cost, and a claim that is admitted and then fails pays for the work it did rather than the declared envelope. The chain reserves a fixed 256-unit declared-work envelope plus a flat allowance for settling the validator's queued dividend credits first (the same allowance every basket call that flushes declares), counts only root-relevant hotkeys and their basket rows for admission, and separately caps classification of the staking-hotkey vector at 256. It refunds the unused part after. plan and btcli root claim --dry-run show reserved versus spent, warn when the spent fee exceeds accrued yield, and refuse when free TAO cannot cover the reserve. Preview per-validator payouts with root_basket_owed_breakdown.

Parameters

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-with-hotkey \
  --hotkey <ss58|name> --dry-run
btcli tx claim-root-with-hotkey \
  --hotkey <ss58|name> -w my_coldkey

Python

import bittensor as bt
from bittensor.wallet import Wallet

wallet = Wallet(name="my_coldkey", hotkey="my_hotkey")
intent = bt.ClaimRootWithHotkey(hotkey_ss58="5F...")

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_with_hotkey", {...}, wallet)

On-chain implementation

SubtensorModule.claim_root_with_hotkey — pallets/subtensor/src/macros/dispatches.rs#L2158:

#[pallet::call_index(148)]
#[pallet::weight(
    Pallet::<T>::root_claim_hotkey_declared_weight()
)]
pub fn claim_root_with_hotkey(
    origin: OriginFor<T>,
    hotkey: T::AccountId,
) -> DispatchResultWithPostInfo {
    let coldkey: T::AccountId = ensure_signed(origin)?;
    // Admission failures keep the declared envelope (see `claim_root`).
    ensure!(
        Self::root_claim_hotkey_fits_declared_budget(&hotkey),
        Error::<T>::RootClaimTooHeavy
    );

    let admitted =
        Self::root_claim_admission_weight(Self::root_claim_hotkey_declared_work());
    let outcome = Self::do_root_claim_tracked(coldkey.clone(), vec![hotkey]).map_err(
        |(done, error)| {
            Self::fail_with_weight(
                error,
                Self::root_claim_actual_weight(1, 0, &done).saturating_add(admitted),
            )
        },
    )?;
    Self::maybe_add_coldkey_index(&coldkey);

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

Delegates to root_claim_hotkey_fits_declared_budget, root_claim_admission_weight, root_claim_hotkey_declared_work.

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