From 6ac66e26d992dbe13edaf01a740f18173843a3c6 Mon Sep 17 00:00:00 2001 From: UnArbosFive Date: Tue, 14 Jul 2026 17:14:57 +0200 Subject: [PATCH 1/3] Document subnet owner wallet security --- docs/concepts/wallets.mdx | 7 +++--- docs/guides/subnets.mdx | 45 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+), 3 deletions(-) diff --git a/docs/concepts/wallets.mdx b/docs/concepts/wallets.mdx index 6b45127d0a..21284ac100 100644 --- a/docs/concepts/wallets.mdx +++ b/docs/concepts/wallets.mdx @@ -189,9 +189,10 @@ swap is a two-step, delayed process: window the wallet is locked — no transfers or staking; the coldkey can only execute or dispute. 2. [`swap-coldkey-announced`](/docs/tx/swap-coldkey-announced) executes after - the delay, moving everything — balance, stake, hotkeys, registrations, - subnet ownership — to the destination, which must be an unused coldkey with - no existing stake, registrations, or child hotkeys. + the delay, moving everything — balance, stake, conviction locks (including + accrued conviction), hotkeys, registrations, and subnet ownership — to the + destination. The destination must be an unused coldkey with no existing + stake, registrations, child hotkeys, or active locked mass. Check a pending announcement with the [`coldkey-swap-announcement`](/docs/query/coldkey-swap-announcement) read. An diff --git a/docs/guides/subnets.mdx b/docs/guides/subnets.mdx index 2342e97c49..ade4631951 100644 --- a/docs/guides/subnets.mdx +++ b/docs/guides/subnets.mdx @@ -41,6 +41,51 @@ needs the [raw-call escape hatch](/docs/concepts/advanced). A new subnet is a two-step commitment: register, then activate with [`start-call`](/docs/tx/start-call) — until then it earns nothing. +## Secure the owner account + +A subnet owner controls its identity and owner-settable hyperparameters. Do not +keep that authority in a single coldkey on an operational machine. + +**Recommended setup.** For a conventionally funded subnet, use a multisig +address as the owner from registration and separate high-impact control from +routine operations: + +1. Make the owner a [**multisig**](/docs/concepts/advanced#multisig) whose + signatory keys are stored separately (ideally on hardware or air-gapped + signers). This is the recovery and high-impact control layer. +2. From the multisig, grant a dedicated operations key the narrow **Owner** + [proxy type](/docs/concepts/advanced#proxy-types). It can manage subnet + identity and owner-settable hyperparameters, but cannot transfer funds or + rotate the owner. +3. Use the proxy for routine changes and the multisig only to replace or revoke + that proxy. Add an announcement delay when the operational cadence permits, + and monitor announcements more frequently than the delay. + +For a new crowd-funded subnet, a +[crowdloan lease](#financing-leases-and-crowdloans) provides a different secure +ownership model: the chain creates the lease owner account and grants the +beneficiary a scoped `SubnetLeaseBeneficiary` proxy. + +**Migrating an existing owner.** If a subnet is already owned by a single +coldkey, adopting the setup above requires a one-time ownership migration. +Sending TAO to a multisig address is not enough: balance, stake, conviction, +and subnet ownership are separate on-chain state. Choose the transaction that +matches what you intend: + +| Operation | What moves | Effect on conviction locks | +| --- | --- | --- | +| [`transfer`](/docs/tx/transfer) | Transferable TAO only | None; stake, locks, conviction, and subnet ownership remain on the source coldkey. | +| [`transfer-stake`](/docs/tx/transfer-stake) | A stake position to another coldkey | If the transfer reaches locked stake, the corresponding locked mass and conviction move proportionally; a conflicting destination lock rejects the call. It does not transfer subnet ownership. | +| [Announced coldkey swap](/docs/tx/announce-coldkey-swap) | The complete coldkey state, including balance, stake, hotkeys, registrations, and subnet ownership | Locks and accrued conviction are preserved under the destination coldkey. Use this to migrate an existing owner to a multisig. | + +Before a coldkey swap, derive and verify the multisig address from the complete +signatory set and threshold. The destination must be a clean account: in +particular, it cannot already have stake, hotkey associations, or active locked +mass. The swap is delayed and irreversible; after it executes, all owner actions +must originate from the multisig (normally through its `Owner` proxy). See +[Wallet key rotation](/docs/concepts/wallets#key-rotation-and-recovery) for the +full safety procedure. + ## Activate Once the chain's activation delay has passed, flip the subnet on with From 7f91ace86720bb34bdf5c56b325fc94bc2738d0b Mon Sep 17 00:00:00 2001 From: UnArbosFive Date: Tue, 14 Jul 2026 18:31:25 +0200 Subject: [PATCH 2/3] Clarify subnet owner migration safeguards --- docs/concepts/wallets.mdx | 31 ++++++++++++++++--------------- docs/guides/subnets.mdx | 27 ++++++++++++++------------- 2 files changed, 30 insertions(+), 28 deletions(-) diff --git a/docs/concepts/wallets.mdx b/docs/concepts/wallets.mdx index 21284ac100..3a43d89876 100644 --- a/docs/concepts/wallets.mdx +++ b/docs/concepts/wallets.mdx @@ -98,17 +98,14 @@ Match each key to the least-trusted machine that needs it: 3. **Coldkey workstation** — a dedicated, clean machine for coldkey-signed operations, ideally holding only a scoped proxy key rather than the real coldkey. -4. **Primary coldkey in a hardware wallet** — Ledger works through - Talisman, Nova Wallet, or SubWallet; Polkadot Vault turns a permanently - offline phone into an air-gapped signer that can sign any extrinsic via QR - codes (Ledger apps cover a narrower operation set). - -This CLI and SDK cannot sign with hardware wallets. That is what the proxy -pattern is for: the hardware-held primary coldkey creates a single delayed -`NonTransfer` [proxy](/docs/concepts/advanced), and that proxy creates and -revokes narrower scoped proxies (`Staking`, `Registration`, ...) for daily -work. Only two operations ever strictly require the primary coldkey: the first -add-proxy, and coldkey rotation. +4. **Primary coldkey on a hardware or air-gapped signer** — a + [Ledger](/docs/guides/ledger) can sign CLI and SDK transactions through the + Polkadot generic app; Polkadot Vault signs by QR code from a permanently + offline phone. + +Keep the hardware-held key for recovery and high-impact operations. Use it to +create a delayed `NonTransfer` [proxy](/docs/concepts/advanced), which can create +and revoke narrower proxies (`Staking`, `Registration`, ...) for routine work. ### Supply-chain risk @@ -189,10 +186,14 @@ swap is a two-step, delayed process: window the wallet is locked — no transfers or staking; the coldkey can only execute or dispute. 2. [`swap-coldkey-announced`](/docs/tx/swap-coldkey-announced) executes after - the delay, moving everything — balance, stake, conviction locks (including - accrued conviction), hotkeys, registrations, and subnet ownership — to the - destination. The destination must be an unused coldkey with no existing - stake, registrations, child hotkeys, or active locked mass. + the delay, moving the coldkey's Subtensor-managed state — transferable TAO, + stake, conviction locks (including accrued conviction), hotkeys, + registrations, and subnet ownership — to the destination. Proxy grants and + reserved balances do not move. Before announcing, remove proxies whose + deposits you need to recover and leave enough transferable TAO to recreate + the proxies you still need. Use a verified destination that is not a hotkey + and has no stake or active locked mass; recreate required proxies after the + swap. Check a pending announcement with the [`coldkey-swap-announcement`](/docs/query/coldkey-swap-announcement) read. An diff --git a/docs/guides/subnets.mdx b/docs/guides/subnets.mdx index ade4631951..e249cab4db 100644 --- a/docs/guides/subnets.mdx +++ b/docs/guides/subnets.mdx @@ -50,16 +50,18 @@ keep that authority in a single coldkey on an operational machine. address as the owner from registration and separate high-impact control from routine operations: -1. Make the owner a [**multisig**](/docs/concepts/advanced#multisig) whose - signatory keys are stored separately (ideally on hardware or air-gapped - signers). This is the recovery and high-impact control layer. +1. Make the owner a [**multisig**](/docs/concepts/advanced#multisig) and keep + its signatory keys on separate devices and in separate locations. A + [Ledger](/docs/guides/ledger) can keep a signatory key off the computer while + displaying each approval on-device; keep an independent seed backup for every + signer. This is the recovery and high-impact control layer. 2. From the multisig, grant a dedicated operations key the narrow **Owner** [proxy type](/docs/concepts/advanced#proxy-types). It can manage subnet identity and owner-settable hyperparameters, but cannot transfer funds or rotate the owner. -3. Use the proxy for routine changes and the multisig only to replace or revoke - that proxy. Add an announcement delay when the operational cadence permits, - and monitor announcements more frequently than the delay. +3. Use the proxy for routine changes. Use the multisig to manage the proxy, veto + delayed calls, and perform actions outside the **Owner** scope. If you add an + announcement delay, monitor announcements more frequently than the delay. For a new crowd-funded subnet, a [crowdloan lease](#financing-leases-and-crowdloans) provides a different secure @@ -76,15 +78,14 @@ matches what you intend: | --- | --- | --- | | [`transfer`](/docs/tx/transfer) | Transferable TAO only | None; stake, locks, conviction, and subnet ownership remain on the source coldkey. | | [`transfer-stake`](/docs/tx/transfer-stake) | A stake position to another coldkey | If the transfer reaches locked stake, the corresponding locked mass and conviction move proportionally; a conflicting destination lock rejects the call. It does not transfer subnet ownership. | -| [Announced coldkey swap](/docs/tx/announce-coldkey-swap) | The complete coldkey state, including balance, stake, hotkeys, registrations, and subnet ownership | Locks and accrued conviction are preserved under the destination coldkey. Use this to migrate an existing owner to a multisig. | +| [Announced coldkey swap](/docs/tx/announce-coldkey-swap) | Subtensor-managed coldkey state, including subnet ownership; see [what moves](/docs/concepts/wallets#key-rotation-and-recovery). | Locks and accrued conviction are preserved. Use this to migrate an existing owner to a multisig. | -Before a coldkey swap, derive and verify the multisig address from the complete -signatory set and threshold. The destination must be a clean account: in -particular, it cannot already have stake, hotkey associations, or active locked -mass. The swap is delayed and irreversible; after it executes, all owner actions -must originate from the multisig (normally through its `Owner` proxy). See +Before the swap, derive and verify the multisig address, remove old proxy grants, +and ensure the destination is not a hotkey and has no stake or active locks. The +source is frozen during the delay. After execution, verify the migrated state and +use the multisig to recreate the **Owner** proxy. See [Wallet key rotation](/docs/concepts/wallets#key-rotation-and-recovery) for the -full safety procedure. +full procedure and balance requirements. ## Activate From 52fdd9a2e851e8b0dfad4bdc27e7281d1f8e030e Mon Sep 17 00:00:00 2001 From: unarbos Date: Tue, 14 Jul 2026 10:36:35 -0600 Subject: [PATCH 3/3] Defer wallet-security details to multisig and proxy guides Co-authored-by: Cursor --- docs/concepts/wallets.mdx | 6 ++-- docs/guides/subnets.mdx | 58 ++++++++++++++------------------------- 2 files changed, 25 insertions(+), 39 deletions(-) diff --git a/docs/concepts/wallets.mdx b/docs/concepts/wallets.mdx index 3a43d89876..a6a6009461 100644 --- a/docs/concepts/wallets.mdx +++ b/docs/concepts/wallets.mdx @@ -104,8 +104,10 @@ Match each key to the least-trusted machine that needs it: offline phone. Keep the hardware-held key for recovery and high-impact operations. Use it to -create a delayed `NonTransfer` [proxy](/docs/concepts/advanced), which can create -and revoke narrower proxies (`Staking`, `Registration`, ...) for routine work. +create a delayed `NonTransfer` [proxy](/docs/guides/proxies), which can create +and revoke narrower proxies (`Staking`, `Registration`, ...) for routine work — +the full layering is in the proxy guide's +[recommended architecture](/docs/guides/proxies#a-recommended-architecture). ### Supply-chain risk diff --git a/docs/guides/subnets.mdx b/docs/guides/subnets.mdx index e249cab4db..592c4ad531 100644 --- a/docs/guides/subnets.mdx +++ b/docs/guides/subnets.mdx @@ -43,49 +43,33 @@ A new subnet is a two-step commitment: register, then activate with ## Secure the owner account -A subnet owner controls its identity and owner-settable hyperparameters. Do not -keep that authority in a single coldkey on an operational machine. - -**Recommended setup.** For a conventionally funded subnet, use a multisig -address as the owner from registration and separate high-impact control from -routine operations: - -1. Make the owner a [**multisig**](/docs/concepts/advanced#multisig) and keep - its signatory keys on separate devices and in separate locations. A - [Ledger](/docs/guides/ledger) can keep a signatory key off the computer while - displaying each approval on-device; keep an independent seed backup for every - signer. This is the recovery and high-impact control layer. -2. From the multisig, grant a dedicated operations key the narrow **Owner** - [proxy type](/docs/concepts/advanced#proxy-types). It can manage subnet - identity and owner-settable hyperparameters, but cannot transfer funds or - rotate the owner. -3. Use the proxy for routine changes. Use the multisig to manage the proxy, veto - delayed calls, and perform actions outside the **Owner** scope. If you add an - announcement delay, monitor announcements more frequently than the delay. +A subnet owner's coldkey controls the subnet's identity and owner-settable +hyperparameters — authority that should never live in a single coldkey on an +operational machine. The standard layering: make the owner account a +[**multisig**](/docs/guides/multisig) from registration, and from it grant a +dedicated operations key the narrow **Owner** +[proxy type](/docs/guides/proxies#proxy-types) for routine changes. The ops +key can manage subnet identity and hyperparameters but cannot transfer funds +or rotate the owner; the multisig convenes only to manage that proxy, veto +delayed calls, and act outside the **Owner** scope. Both guides walk through +the setup — see +[Subnet owners specifically](/docs/guides/proxies#subnet-owners-specifically) +in the proxy guide for this exact pattern. For a new crowd-funded subnet, a [crowdloan lease](#financing-leases-and-crowdloans) provides a different secure ownership model: the chain creates the lease owner account and grants the beneficiary a scoped `SubnetLeaseBeneficiary` proxy. -**Migrating an existing owner.** If a subnet is already owned by a single -coldkey, adopting the setup above requires a one-time ownership migration. -Sending TAO to a multisig address is not enough: balance, stake, conviction, -and subnet ownership are separate on-chain state. Choose the transaction that -matches what you intend: - -| Operation | What moves | Effect on conviction locks | -| --- | --- | --- | -| [`transfer`](/docs/tx/transfer) | Transferable TAO only | None; stake, locks, conviction, and subnet ownership remain on the source coldkey. | -| [`transfer-stake`](/docs/tx/transfer-stake) | A stake position to another coldkey | If the transfer reaches locked stake, the corresponding locked mass and conviction move proportionally; a conflicting destination lock rejects the call. It does not transfer subnet ownership. | -| [Announced coldkey swap](/docs/tx/announce-coldkey-swap) | Subtensor-managed coldkey state, including subnet ownership; see [what moves](/docs/concepts/wallets#key-rotation-and-recovery). | Locks and accrued conviction are preserved. Use this to migrate an existing owner to a multisig. | - -Before the swap, derive and verify the multisig address, remove old proxy grants, -and ensure the destination is not a hotkey and has no stake or active locks. The -source is frozen during the delay. After execution, verify the migrated state and -use the multisig to recreate the **Owner** proxy. See -[Wallet key rotation](/docs/concepts/wallets#key-rotation-and-recovery) for the -full procedure and balance requirements. +If the subnet is already owned by a single coldkey, adopting this setup is a +one-time ownership migration via the announced **coldkey swap**. Sending TAO to +the multisig address is not enough: balance, stake, conviction locks, and +subnet ownership are separate on-chain state, and a plain +[`transfer`](/docs/tx/transfer) moves only the first. The full procedure — +verifying the derived address, what the swap moves, and the delay — is in +[Migrate an existing account to a multisig](/docs/guides/multisig#migrate-an-existing-account-to-a-multisig); +[Wallet key rotation](/docs/concepts/wallets#key-rotation-and-recovery) covers +what a coldkey swap does and doesn't move. ## Activate