Add pallet-derivatives: longs and shorts on subnet alpha (spec 455)

.github/docs-preview-vercel/package.json

@@ -22,6 +22,7 @@
     },
     "ajv": "8.18.0",
     "brace-expansion": "5.0.9",
+    "fast-uri": "3.1.7",
     "js-yaml": "4.3.1",
     "minimatch": "10.2.5",
     "path-to-regexp": "8.4.2",

.github/workflows/cargo-audit.yml

@@ -72,6 +72,9 @@ jobs:
           # RUSTSEC-2026-0258: h2 unbounded empty DATA frames. Fix is
           #   >=0.4.16; we still carry 0.3.27 (no 0.3 patch) via hyper in the
           #   fork tree — revisit when that stack moves off h2 0.3.
+          # RUSTSEC-2026-0269: wasmtime 8.0.1 filesystem sandbox escape via
+          #   trailing slashes in WASI paths. We never expose a filesystem to
+          #   the runtime WASM; same pin as the wasmtime entries above.
           cargo audit --ignore RUSTSEC-2023-0091 \
                       --ignore RUSTSEC-2024-0438 \
                       --ignore RUSTSEC-2025-0009 \
@@ -103,4 +106,5 @@ jobs:
                       --ignore RUSTSEC-2025-0020 \
                       --ignore RUSTSEC-2026-0177 \
                       --ignore RUSTSEC-2026-0235 \
-                      --ignore RUSTSEC-2026-0258
+                      --ignore RUSTSEC-2026-0258 \
+                      --ignore RUSTSEC-2026-0269

Cargo.toml

@@ -60,6 +60,7 @@ useless_conversion = "allow"     # until polkadot is patched
 pallet-alpha-assets = { path = "pallets/alpha-assets", default-features = false }
 node-subtensor-runtime = { path = "runtime", default-features = false }
 pallet-admin-utils = { path = "pallets/admin-utils", default-features = false }
+pallet-derivatives = { path = "pallets/derivatives", default-features = false }
 pallet-limit-orders = { path = "pallets/limit-orders", default-features = false }
 pallet-commitments = { path = "pallets/commitments", default-features = false }
 pallet-crowdloan = { path = "pallets/crowdloan", default-features = false }

chain-extensions/src/mock.rs

@@ -26,7 +26,9 @@ use sp_runtime::{
     traits::{BlakeTwo256, Convert, IdentityLookup},
 };
 use sp_std::{cell::RefCell, cmp::Ordering, sync::OnceLock};
-use subtensor_runtime_common::{AlphaBalance, AuthorshipInfo, NetUid, Saturating, TaoBalance};
+use subtensor_runtime_common::{
+    AlphaBalance, AuthorshipInfo, NetUid, Saturating, SubnetDissolveHook, TaoBalance,
+};
 
 type Block = frame_system::mocking::MockBlock<Test>;
 
@@ -425,6 +427,7 @@ impl pallet_subtensor::Config for Test {
     type Yuma3On = InitialYuma3On;
     type Preimages = Preimage;
     type AlphaAssets = AlphaAssets;
+    type Derivatives = ();
     type InitialColdkeySwapAnnouncementDelay = InitialColdkeySwapAnnouncementDelay;
     type InitialColdkeySwapReannouncementDelay = InitialColdkeySwapReannouncementDelay;
     type InitialDissolveNetworkScheduleDuration = InitialDissolveNetworkScheduleDuration;
@@ -478,14 +481,15 @@ impl PrivilegeCmp<OriginCaller> for OriginPrivilegeCmp {
 }
 
 pub struct CommitmentsI;
-impl CommitmentsInterface<AccountId> for CommitmentsI {
-    fn purge_netuid(
+impl SubnetDissolveHook for CommitmentsI {
+    fn on_subnet_dissolve(
         _netuid: NetUid,
         _weight_meter: &mut frame_support::weights::WeightMeter,
     ) -> bool {
         true
     }
-
+}
+impl CommitmentsInterface<AccountId> for CommitmentsI {
     fn purge_neuron(_netuid: NetUid, _account: &AccountId) {}
 }
 

common/src/lib.rs

@@ -171,6 +171,41 @@ pub trait AuthorshipInfo<AccountId> {
     fn author() -> Option<AccountId>;
 }
 
+/// Metered, resumable cleanup of a pallet's per-subnet state while that subnet is dissolved.
+/// Each implementer runs in its own `pallet-subtensor` dissolution phase, so the order between
+/// hooks is fixed there, not here.
+pub trait SubnetDissolveHook {
+    /// Clean up everything held on `netuid`, consuming weight from `meter`.
+    ///
+    /// Returns `true` once nothing remains for this subnet, `false` when the caller must call
+    /// again in a later block because the weight budget ran out.
+    fn on_subnet_dissolve(netuid: NetUid, meter: &mut WeightMeter) -> bool;
+}
+
+impl SubnetDissolveHook for () {
+    fn on_subnet_dissolve(_netuid: NetUid, _meter: &mut WeightMeter) -> bool {
+        true
+    }
+}
+
+/// What a derivatives pallet holds against a subnet's pool, as `pallet-subtensor` needs to see
+/// it. Use `()` when no such pallet is wired.
+pub trait DerivativesHook: SubnetDissolveHook {
+    /// Alpha the pool on `netuid` would hold if every open long handed its slice back in kind.
+    ///
+    /// A long lifts a slice of both reserves and spends the lifted TAO on alpha, so the pool
+    /// keeps its TAO and is short exactly this much alpha while the long is open. Emission
+    /// weights add it back before pricing the subnet, so a long cannot buy emission for its
+    /// own subnet. Shorts are not adjusted for: a short lowers the price on purpose.
+    fn long_alpha_outstanding(netuid: NetUid) -> AlphaBalance;
+}
+
+impl DerivativesHook for () {
+    fn long_alpha_outstanding(_netuid: NetUid) -> AlphaBalance {
+        AlphaBalance::ZERO
+    }
+}
+
 pub mod time {
     use super::*;
 

docs/errors/chain/BasketDepositPending.mdx

@@ -0,0 +1,18 @@
+---
+title: "BasketDepositPending"
+description: "The required window has not opened yet; wait some blocks and retry"
+---
+
+{/* GENERATED by scripts/generate.py from the SDK registries — do not edit. */}
+
+The validator has a queued root-dividend deposit that could not be settled yet, and the call would change the hotkey's root claimant base before it does. Check the pending basket deposits for the hotkey and retry once the deposit becomes executable.
+
+Declared by the `SubtensorModule` pallet; it classifies to the semantic code [`too_early`](/docs/errors/too-early).
+
+Declared at [`pallets/subtensor/src/macros/errors.rs#L377`](/code/pallets/subtensor/src/macros/errors.rs#L377).
+
+## Remediation
+
+The required window has not opened yet; wait some blocks and retry
+
+The same explanation is available in the terminal: `btcli explain BasketDepositPending`.

docs/errors/chain/DepositTooLow.mdx

@@ -7,9 +7,9 @@ description: "Check the argument values against the operation schema"
 
 The `deposit` argument to `create` is below the pallet's required minimum. Check the `MinimumDeposit` pallet constant and create the crowdloan with at least that initial deposit.
 
-Declared by the `Crowdloan` pallet; it classifies to the semantic code [`invalid_argument`](/docs/errors/invalid-argument).
+Declared by the `Crowdloan`, `Derivatives` pallets; it classifies to the semantic code [`invalid_argument`](/docs/errors/invalid-argument).
 
-Declared at [`pallets/crowdloan/src/lib.rs#L241`](/code/pallets/crowdloan/src/lib.rs#L241).
+Declared at [`pallets/crowdloan/src/lib.rs#L241`](/code/pallets/crowdloan/src/lib.rs#L241), [`pallets/derivatives/src/lib.rs#L233`](/code/pallets/derivatives/src/lib.rs#L233).
 
 ## Remediation
 

docs/errors/chain/LeverageOutOfRange.mdx

@@ -0,0 +1,18 @@
+---
+title: "LeverageOutOfRange"
+description: "Check the argument values against the operation schema"
+---
+
+{/* GENERATED by scripts/generate.py from the SDK registries — do not edit. */}
+
+The requested leverage is zero or above the side's maximum: 1x for shorts, 2x for longs (`max_short_leverage` / `max_long_leverage` in `deriv params`). Pass a `--leverage` at or below it.
+
+Declared by the `Derivatives` pallet; it classifies to the semantic code [`invalid_argument`](/docs/errors/invalid-argument).
+
+Declared at [`pallets/derivatives/src/lib.rs#L236`](/code/pallets/derivatives/src/lib.rs#L236).
+
+## Remediation
+
+Check the argument values against the operation schema
+
+The same explanation is available in the terminal: `btcli explain LeverageOutOfRange`.

docs/errors/chain/NoPosition.mdx

@@ -0,0 +1,18 @@
+---
+title: "NoPosition"
+description: "The referenced object is not on-chain; check the identifier"
+---
+
+{/* GENERATED by scripts/generate.py from the SDK registries — do not edit. */}
+
+That owner has no position on that subnet. Check the owner and netuid against `derivative-positions`; it may already have been closed, or forfeited once its cushion could no longer pay its interest.
+
+Declared by the `Derivatives` pallet; it classifies to the semantic code [`not_found`](/docs/errors/not-found).
+
+Declared at [`pallets/derivatives/src/lib.rs#L231`](/code/pallets/derivatives/src/lib.rs#L231).
+
+## Remediation
+
+The referenced object is not on-chain; check the identifier
+
+The same explanation is available in the terminal: `btcli explain NoPosition`.

docs/errors/chain/PalletHotkeyUnset.mdx

@@ -0,0 +1,18 @@
+---
+title: "PalletHotkeyUnset"
+description: "The required window has not opened yet; wait some blocks and retry"
+---
+
+{/* GENERATED by scripts/generate.py from the SDK registries — do not edit. */}
+
+The pallet has not claimed its custody hotkey yet, so nothing can be added. Check `Derivatives.PalletHotkey`; it is set by `on_runtime_upgrade` in the upgrade block.
+
+Declared by the `Derivatives` pallet; it classifies to the semantic code [`too_early`](/docs/errors/too-early).
+
+Declared at [`pallets/derivatives/src/lib.rs#L243`](/code/pallets/derivatives/src/lib.rs#L243).
+
+## Remediation
+
+The required window has not opened yet; wait some blocks and retry
+
+The same explanation is available in the terminal: `btcli explain PalletHotkeyUnset`.

docs/errors/chain/PoolCapExceeded.mdx

@@ -0,0 +1,18 @@
+---
+title: "PoolCapExceeded"
+description: "A chain-side capacity limit was hit; reduce the size or count of the request"
+---
+
+{/* GENERATED by scripts/generate.py from the SDK registries — do not edit. */}
+
+Open positions of this side would together borrow more than `pool_share` of the lent reserve, or the deposit alone would take the whole pool. A `pool_share` of zero means root has paused new positions. Check `deriv params`; try a smaller deposit or wait for other positions to close.
+
+Declared by the `Derivatives` pallet; it classifies to the semantic code [`limit_exceeded`](/docs/errors/limit-exceeded).
+
+Declared at [`pallets/derivatives/src/lib.rs#L241`](/code/pallets/derivatives/src/lib.rs#L241).
+
+## Remediation
+
+A chain-side capacity limit was hit; reduce the size or count of the request
+
+The same explanation is available in the terminal: `btcli explain PoolCapExceeded`.

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. */}
 
-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.
+A root claim would process more than the fixed 256-unit admission envelope. Only root-relevant validator hotkeys and their stored basket rows count as claim work; classifying the staking-hotkey relationship vector is separately capped at 256. Unrelated subnet stakes are not multiplied by the total network count. 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/SubnetNotDynamic.mdx

@@ -0,0 +1,18 @@
+---
+title: "SubnetNotDynamic"
+description: "The subnet is not active yet; wait for start_call"
+---
+
+{/* GENERATED by scripts/generate.py from the SDK registries — do not edit. */}
+
+The subnet does not exist, is not AMM-priced, has its subtoken disabled, or has an empty reserve. Check the subnet exists and that `subnets show` reports a live pool.
+
+Declared by the `Derivatives` pallet; it classifies to the semantic code [`subtoken_disabled`](/docs/errors/subtoken-disabled).
+
+Declared at [`pallets/derivatives/src/lib.rs#L229`](/code/pallets/derivatives/src/lib.rs#L229).
+
+## Remediation
+
+The subnet is not active yet; wait for start_call
+
+The same explanation is available in the terminal: `btcli explain SubnetNotDynamic`.

docs/errors/chain/ZeroExposure.mdx

@@ -0,0 +1,18 @@
+---
+title: "ZeroExposure"
+description: "Check the argument values against the operation schema"
+---
+
+{/* GENERATED by scripts/generate.py from the SDK registries — do not edit. */}
+
+Leverage times the deposit rounds to nothing against the pool reserve, or the pool would swap the lifted slice for nothing. Use a larger deposit relative to the pool.
+
+Declared by the `Derivatives` pallet; it classifies to the semantic code [`invalid_argument`](/docs/errors/invalid-argument).
+
+Declared at [`pallets/derivatives/src/lib.rs#L238`](/code/pallets/derivatives/src/lib.rs#L238).
+
+## Remediation
+
+Check the argument values against the operation schema
+
+The same explanation is available in the terminal: `btcli explain ZeroExposure`.