fix(sdk): enforce wrapped intent safety preflights

.github/scripts/test_docs_preview_workflows.py

@@ -119,6 +119,14 @@ def test_bundle_is_self_contained_and_validates_every_vercel_file_map(self):
         self.assertIn("docs_preview_bundle.py \\", self.request)
         self.assertIn("seal \\", self.request)
 
+    def test_trusted_extract_preserves_the_vercel_project_root_directory(self):
+        self.assertIn(
+            'output_root="${deploy_root}/website/apps/bittensor-website"',
+            self.deploy,
+        )
+        self.assertIn('"${output_root}"', self.deploy)
+        self.assertIn('echo "root=${deploy_root}"', self.deploy)
+
     def test_preview_environment_and_deployment_lifecycle_are_guarded(self):
         self.assertIn("audit-project", self.deploy)
         self.assertIn('--preview-domain "*.preview.${DOCS_DOMAIN}"', self.deploy)

.github/workflows/deploy-docs-preview.yml

@@ -99,11 +99,12 @@ jobs:
         run: |
           set -euo pipefail
           deploy_root="${RUNNER_TEMP}/docs-preview-deploy"
+          output_root="${deploy_root}/website/apps/bittensor-website"
           test ! -e "${deploy_root}"
           python3 trusted-source/.github/scripts/docs_preview_bundle.py \
             extract \
             "${GITHUB_WORKSPACE}/artifact/docs-preview-sealed.tgz" \
-            "${deploy_root}"
+            "${output_root}"
           echo "root=${deploy_root}" >> "${GITHUB_OUTPUT}"
 
       - name: Audit preview project and pre-provisioned domain

docs/concepts/advanced.mdx

@@ -37,7 +37,7 @@ Prefer the narrowest type that covers the job:
   **SmallTransfer** is the same but caps each transfer below 0.5 TAO
   (0.5 alpha for stake transfers).
 - **Staking** — stake operations only: add / remove / move / swap /
-  unstake-all and their limit variants, plus [`set_root_claim_type`](/code/pallets/subtensor/src/macros/dispatches.rs#L1937-L1951). The
+  unstake-all and their limit variants. The
   allowlist does **not** include `Utility.batch_all`, so batching staking
   calls through a Staking proxy fails with `CallFiltered` — use a NonTransfer
   proxy for batched staking.
@@ -130,6 +130,12 @@ pallet's [`EncryptedSubmitted`](/code/pallets/shield/src/lib.rs#L206) event, and
 `inner_extrinsic_hash` in the result data so the inner extrinsic can be
 located on chain.
 
+With `wait_for_finalization=True`, the SDK waits until the block containing
+the inner extrinsic is finalized, re-reads the canonical block hash at that
+height, and resumes the scan if a reorganization removed it. Finalized-head
+RPC failures and stalled finality are bounded; exhausting either retry budget
+raises a clear `ChainError` instead of waiting forever.
+
 Shield wraps the **already composed** call. `proxy_for=` / `--proxy-for`
 and a saved-multisig adapter are applied first; the encrypted inner
 extrinsic is `Proxy.proxy(...)` or `Multisig.as_multi(...)` when those

docs/errors/chain/RootClaimTooHeavy.mdx

@@ -5,7 +5,7 @@ description: "A chain-side capacity limit was hit; reduce the size or count of t
 
 {/* GENERATED by scripts/generate.py from the SDK registries — do not edit. */}
 
-Coldkey-wide `claim_root` would walk more work than the pre-dispatch weight envelope can admit (hotkeys × existing networks, or leftover basket rows, exceed `MAX_ROOT_CLAIM_WORK`). Claim each validator with `claim_root_with_hotkey` instead so admission matches the holdings walked.
+A root claim would walk more work than the fixed pre-dispatch weight envelope can admit. For coldkey-wide `claim_root`, hotkeys times existing networks or total basket rows can exceed `MAX_ROOT_CLAIM_WORK`; a single validator basket with too many rows can also make `claim_root_with_hotkey` fail. Split a coldkey-wide claim by validator where that fits, and investigate or consolidate an individually oversized basket.
 
 Declared by the `SubtensorModule` pallet; it classifies to the semantic code [`limit_exceeded`](/docs/errors/limit-exceeded).
 

docs/errors/chain/index.mdx

@@ -293,7 +293,7 @@ The exact chain error name (from the extrinsic receipt) maps to a semantic [code
 | [`RevealPeriodTooLarge`](/docs/errors/chain/RevealPeriodTooLarge) | [`invalid_argument`](/docs/errors/invalid-argument) | `set_reveal_period` was given a commit-reveal period above the compiled-in maximum number of epochs. Lower the `reveal_period` argument; the current setting is readable from `RevealPeriodEpochs` for the netuid. |
 | [`RevealPeriodTooSmall`](/docs/errors/chain/RevealPeriodTooSmall) | [`invalid_argument`](/docs/errors/invalid-argument) | `set_reveal_period` was given a commit-reveal period below the compiled-in minimum number of epochs. Raise the `reveal_period` argument; the current setting is readable from `RevealPeriodEpochs` for the netuid. |
 | [`RevealTooEarly`](/docs/errors/chain/RevealTooEarly) | [`too_early`](/docs/errors/too-early) | A weight reveal was submitted before the commit's reveal window: the current epoch must equal the commit epoch plus the reveal period. Check the commit in `WeightCommits` and the subnet's `RevealPeriodEpochs`, then wait for the reveal epoch. |
-| [`RootClaimTooHeavy`](/docs/errors/chain/RootClaimTooHeavy) | [`limit_exceeded`](/docs/errors/limit-exceeded) | Coldkey-wide `claim_root` would walk more work than the pre-dispatch weight envelope can admit (hotkeys × existing networks, or leftover basket rows, exceed `MAX_ROOT_CLAIM_WORK`). Claim each validator with `claim_root_with_hotkey` instead so admission matches the holdings walked. |
+| [`RootClaimTooHeavy`](/docs/errors/chain/RootClaimTooHeavy) | [`limit_exceeded`](/docs/errors/limit-exceeded) | A root claim would walk more work than the fixed pre-dispatch weight envelope can admit. For coldkey-wide `claim_root`, hotkeys times existing networks or total basket rows can exceed `MAX_ROOT_CLAIM_WORK`; a single validator basket with too many rows can also make `claim_root_with_hotkey` fail. Split a coldkey-wide claim by validator where that fits, and investigate or consolidate an individually oversized basket. |
 | [`RootNetUidNotAllowed`](/docs/errors/chain/RootNetUidNotAllowed) | [`invalid_argument`](/docs/errors/invalid-argument) | The order or batch targets the root subnet, netuid 0, which the limit orders pallet does not serve. Check the `netuid` field of the order payload or the `netuid` parameter of the batch call and target a non-root subnet. |
 | [`RootNetworkDoesNotExist`](/docs/errors/chain/RootNetworkDoesNotExist) | [`subnet_not_exists`](/docs/errors/subnet-not-exists) | Root registration or root stake claiming found no root network in chain state, which only happens on misconfigured or freshly bootstrapped chains. Verify netuid 0 exists in `NetworksAdded`. |
 | [`RootStakeLocked`](/docs/errors/chain/RootStakeLocked) | [`too_early`](/docs/errors/too-early) | A root (netuid 0) exit was attempted before `RootStakeUnlockInterval` blocks elapsed since the coldkey/hotkey's last root stake add, remove, or claim. Applies to `remove_stake` and to move/swap/transfer off root. Check `LastColdkeyHotkeyStakeBlock` against the current block and wait out the hold window (or leave the interval at 0 via sudo if the lock is not intended). |

docs/errors/limit-exceeded.mdx

@@ -36,7 +36,7 @@ The exact chain error names (from the extrinsic receipt) that classify to `limit
 | [`OutOfTransientStorage`](/docs/errors/chain/OutOfTransientStorage) | A write would exceed the per-execution byte limit for transient storage. Check how much data the contract places in transient storage during the call against the runtime's transient storage limit. |
 | [`RandomSubjectTooLong`](/docs/errors/chain/RandomSubjectTooLong) | The subject buffer given to the deprecated `seal_random` API exceeds the schedule's `subject_len` limit. Shorten the randomness subject the contract passes or check the schedule's limits section. |
 | [`RegistrationPriceLimitExceeded`](/docs/errors/chain/RegistrationPriceLimitExceeded) | `burned_register` with a price limit failed because the subnet's current registration burn cost exceeds the supplied `limit_price`. Check the current burn via `Burn` storage or `btcli subnets list` and raise the limit or wait for the cost to decay. |
-| [`RootClaimTooHeavy`](/docs/errors/chain/RootClaimTooHeavy) | Coldkey-wide `claim_root` would walk more work than the pre-dispatch weight envelope can admit (hotkeys × existing networks, or leftover basket rows, exceed `MAX_ROOT_CLAIM_WORK`). Claim each validator with `claim_root_with_hotkey` instead so admission matches the holdings walked. |
+| [`RootClaimTooHeavy`](/docs/errors/chain/RootClaimTooHeavy) | A root claim would walk more work than the fixed pre-dispatch weight envelope can admit. For coldkey-wide `claim_root`, hotkeys times existing networks or total basket rows can exceed `MAX_ROOT_CLAIM_WORK`; a single validator basket with too many rows can also make `claim_root_with_hotkey` fail. Split a coldkey-wide claim by validator where that fits, and investigate or consolidate an individually oversized basket. |
 | [`SpaceLimitExceeded`](/docs/errors/chain/SpaceLimitExceeded) | The commitment would push the account's byte quota for the current epoch over the cap; each `set_commitment` consumes at least 100 bytes. Check `UsedSpaceOf` for the netuid and account against `MaxSpace`, or wait for the next epoch to reset usage. |
 | [`StorageDepositLimitExhausted`](/docs/errors/chain/StorageDepositLimitExhausted) | The execution created more storage than the caller's `storage_deposit_limit` allows to be charged. Raise the `storage_deposit_limit` argument or reduce storage usage; a dry-run reports the required `storage_deposit`. |
 | [`SubnetLimitReached`](/docs/errors/chain/SubnetLimitReached) | `register_network` failed because the subnet count is at the network limit and no existing subnet is eligible to be pruned. Check the number of registered subnets (`btcli subnets list`) against the subnet limit and retry once a subnet becomes prunable. |

docs/guides/evm/precompiles/staking-v2.mdx

@@ -23,18 +23,22 @@ removeStakeLimit(bytes32 hotkey, uint256 amount_alpha, uint256 limit_price_rao_p
 removeStakeFull(bytes32 hotkey, uint256 netuid)
 removeStakeFullLimit(bytes32 hotkey, uint256 netuid, uint256 limit_price_rao_per_alpha)
 moveStake(bytes32 origin_hotkey, bytes32 destination_hotkey, uint256 origin_netuid, uint256 destination_netuid, uint256 amount_alpha)
+moveStakeLimit(bytes32 origin_hotkey, bytes32 destination_hotkey, uint16 origin_netuid, uint16 destination_netuid, uint64 amount_alpha, uint64 limit_price, bool allow_partial)
 transferStake(bytes32 destination_coldkey, bytes32 hotkey, uint256 origin_netuid, uint256 destination_netuid, uint256 amount_alpha)
 burnAlpha(bytes32 hotkey, uint256 amount_alpha, uint256 netuid)
 ```
 
-These functions are `payable`.
+The legacy-width functions in this list are `payable`. `moveStakeLimit` is
+non-payable and rejects attached value; its seven arguments use the exact
+`uint16`/`uint64` ABI widths shown above.
 
 Amounts are native runtime units, not 18-decimal EVM units: `amount_rao`
 parameters are TAO denominated in rao (10^-9 TAO), and `amount_alpha`
 parameters are subnet alpha in its native 10^-9 precision. Staking in (TAO
 side) takes rao; unstaking, moving, transferring, and burning operate on
-alpha. Do not scale these values by 10^9; see each function's NatSpec in
-`stakingV2.sol` for the authoritative unit contract.
+alpha. `moveStakeLimit.limit_price` is the minimum destination-alpha per
+origin-alpha ratio, scaled by 10^9. Do not scale amount values by 10^9; see
+each function's NatSpec in `stakingV2.sol` for the authoritative unit contract.
 
 ## Stake views
 

docs/guides/evm/stake-from-evm.mdx

@@ -49,12 +49,16 @@ through `btcli evm call` — same argument conveniences (ss58 accepted for
 btcli evm call staking-v2                       # list all functions
 btcli evm call staking-v2 getTotalHotkeyStake 5F4tQyWr…       # view, free
 btcli evm call staking-v2 moveStake 5Forigin… 5Fdest… 1 4 1000000000 --evm-key default
+btcli evm call staking-v2 moveStakeLimit 5Forigin… 5Fdest… 1 4 1000000000 950000000 false --evm-key default
 btcli evm call staking-v2 addStakeLimit 5F4tQyWr… 1000000000 250000000 true 1 --evm-key default
 ```
 
-`addStakeLimit`/`removeStakeLimit` are the price-protected variants
+`addStakeLimit`/`removeStakeLimit` and `moveStakeLimit` are the
+price-protected variants
 (`limit_price` in rao per alpha, `allow_partial` for partial fills) — the
-EVM mirror of [`add-stake`'s](/docs/tx/add-stake) limit options.
+EVM mirror of the native staking limit calls. For `moveStakeLimit`, the limit
+is instead the minimum destination-alpha per origin-alpha ratio, scaled by
+10^9; it is non-payable, so do not attach EVM value.
 
 ## From Python
 

docs/guides/root-reborn.mdx

@@ -167,7 +167,7 @@ btcli wallet overview                             # same yield line on the walle
 btcli root list                                   # staked + accrued τ per validator
 btcli root subscribe --amount 100 --hotkey 5F...  # assets in
 btcli root unstake --amount 40 --hotkey 5F...     # principal only; yield stays in the basket
-btcli root unstake --all --hotkey 5F... --claim   # claim whole basket, then unstake all
+btcli root unstake --all --hotkey 5F... --claim   # atomic only while RootStakeUnlockInterval is 0
 btcli root claim --dry-run --hotkey 5F...         # reserved vs spent fee, vs accrued
 btcli root claim                                  # pick wallet → validator → claim / withdraw
 btcli root claim --hotkey 5F... --amount all      # withdraw full position (accrued + staked)
@@ -176,10 +176,13 @@ btcli root claim --hotkey 5F...                   # claim accrued into stake onl
 
 Unstake returns principal. Basket yield stays owed. After a root unstake,
 `btcli` tells you if yield is still sitting there and offers `btcli root claim`.
-Pass `--claim` on the unstake to redeem that validator's **whole** entitlement
-first, then unstake, in one batch (`btcli stake remove --netuid 0 --claim` is
-the same). That is not a proportional payout: unstaking 40% still claims 100%
-of the basket. The chain has no "pay out 40% of the basket" call.
+When `RootStakeUnlockInterval` is zero, pass `--claim` on the unstake to redeem
+that validator's **whole** entitlement first, then unstake in one batch
+(`btcli stake remove --netuid 0 --claim` is the same). That is not a
+proportional payout: unstaking 40% still claims 100% of the basket. The chain
+has no "pay out 40% of the basket" call. When the interval is nonzero, the
+atomic form is unavailable because the claim starts a new hold window. Claim
+first, wait out the full interval, then unstake separately.
 
 `btcli root claim` is the yield-first exit. Omit `--amount` to realize accrued
 yield into root stake on that validator. Pass `--amount` / `all` to withdraw to
@@ -210,10 +213,11 @@ root-stakes to.
   the entitlement keeps accruing and pays out once it clears. There is no
   deadline and nothing expires.
 - **Claim fee.** The inclusion fee scales with how many ALPHA types the
-  basket holds. The chain reserves the declared-work fee at inclusion
-  (one unit per existing network, often around τ0.1) and refunds the
-  unused part after the claim. The amount you actually spend is smaller
-  (around τ0.057 on a full 128-holding basket).
+  basket holds. Both root-claim calls reserve a conservative 256-unit work
+  envelope at inclusion, independent of how many networks currently exist,
+  and refund the unused part after the claim. The amount you actually spend
+  follows the holdings scanned and redeemed (around τ0.057 on a full
+  128-holding basket).
   `btcli root claim --dry-run` shows reserved versus spent, compares the
   spent fee to accrued yield, warns if the claim loses money, and
   refuses if free TAO cannot cover the reserved amount.
@@ -250,9 +254,10 @@ root-stakes to.
   accruing — there is no deadline and nothing expires.
 - **Withdrawals can have a hold window.** If the network sets
   `RootStakeUnlockInterval`, root stake is locked for that many blocks after
-  your last stake change (anti-sniping around epoch boundaries). A claim
-  with `--amount` inside the window fails with `RootStakeLocked` — wait it
-  out and retry.
+  your last stake change (anti-sniping around epoch boundaries). A claim also
+  refreshes that window, so atomic claim-then-unstake is unavailable whenever
+  the interval is nonzero. Claim without withdrawing, wait out the full hold,
+  then unstake separately.
 
 ## Queries and runtime APIs