diff --git a/docs/concepts/wallets.mdx b/docs/concepts/wallets.mdx index 6b45127d0a..a6a6009461 100644 --- a/docs/concepts/wallets.mdx +++ b/docs/concepts/wallets.mdx @@ -98,17 +98,16 @@ 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/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 @@ -189,9 +188,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, hotkeys, registrations, - subnet ownership — to the destination, which must be an unused coldkey with - no existing stake, registrations, or child hotkeys. + 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 2342e97c49..592c4ad531 100644 --- a/docs/guides/subnets.mdx +++ b/docs/guides/subnets.mdx @@ -41,6 +41,36 @@ 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'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. + +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 Once the chain's activation delay has passed, flip the subnet on with