Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 18 additions & 14 deletions docs/concepts/wallets.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
30 changes: 30 additions & 0 deletions docs/guides/subnets.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment on lines +49 to +51

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Security procedure links to nonexistent guides

Neither docs/guides/multisig.mdx nor docs/guides/proxies.mdx exists, and neither page is registered in docs/guides/meta.json. The same missing proxy guide is now referenced from docs/concepts/wallets.mdx. Consequently, subnet owners following this security-sensitive procedure reach 404s instead of the promised setup, migration, delay, and recovery instructions. Add and register both guides in this PR, or point these links to existing complete documentation.

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
Expand Down
Loading