Document how to multisig coldkeys, improve wallet docs (#535)

Author: MichaelTrestman

docs/getting-started/coldkey-hotkey-security.md

@@ -10,7 +10,7 @@ See also:
 
 - [Intro to Wallets, Coldkeys and Hotkeys in Bittensor](./wallets)
 - [Bittensor CLI: Permissions Guide](../btcli-permissions)
-
+- [Handle your Seed Phrase/Mnemonic Securely](../keys/handle-seed-phrase)
 
 Interacting with Bittensor generally falls into one of three levels of security, depending on whether you need to use your coldkey private key, hotkey private key, or neither.
 
@@ -49,10 +49,11 @@ Websites that offer permissionless browsing of Bittensor data include:
 
 ## Coldkey workstation
 
-Your coldkey private key, accessible with your recovery seed phrase, is the complete representation of your identity to Bittensor. In otherwords, holding the coldkey or seed phrase is the ultimate authority over your Bittensor wallet. If your coldkey key is leaked or stolen allows an attacker holder to transfer (steal) your TAO, redelegate your stakes, or take other actions that can’t be reversed. Conversely, without your coldkey private key or the seedphrase, there is no possible way to recover access to your wallet.
+Your coldkey private key, accessible with your recovery [seed phrase](./wallets#the-seed-phrase-aka-mnemonic), is the complete representation of your identity to Bittensor. In otherwords, holding the coldkey or seed phrase is the ultimate authority over your Bittensor wallet. If your coldkey key is leaked or stolen allows an attacker holder to transfer (steal) your TAO, redelegate your stakes, or take other actions that can’t be reversed. Conversely, without your coldkey private key or the seed phrase, there is no possible way to recover access to your wallet.
 
 Because of these high stakes, best practices should be diligently followed. Always prioritize confidentiality and integrity over convenience when handling coldkeys.
 
+
 ### Isolation of coldkey operations
 
 The first principle is to isolate coldkey operations from day-to-day or internet-exposed systems. This means using a dedicated machine that is minimally connected to the internet, protected with full disk encryption, and has only highly trusted software installed to minimize the risk of malware or keyloggers intercepting your coldkey.
@@ -81,34 +82,14 @@ This is required for using `btcli` or the Bittensor Python SDK for advanced use
 ### Operational Hygiene
 
 Even on a minimal or air-gapped machine, follow standard security hygiene:
+- Always [Handle your Seed Phrase/Mnemonic Securely](../keys/handle-seed-phrase).
 - Use strong passwords for your encryption passphrases.  
 - Do not reuse credentials across different environments.  
 - Keep your workstation’s operating system and critical software updated with the latest security patches.
 - Disable all network services (SSH, RDP, or anything else) that are not strictly needed.
 - Maintain logs of important oprations.
 
-### Your seed phrase
-
-The ***seed phrase*** (a.k.a. 'menemonic' or 'recovery phrase') is a series of (at least 12) words that is generated together with your wallet's cryptographic key pair, and which can be used to recover the coldkey private key. This seed phrase is therefore a human-usable way to save access to the cryptographic wallet offline, and to import the cryptographic wallet into a wallet application. 
-
-### Do not leak your seed-phrase
-
-1. Do not keep paper/analog copies somewhere they can be accessed without your knowledge.
-1. Do not expose your seed-phrase to untrustworthy software by entering into apps:
-	- messaging
-	- email
-	- online word processors
-1. Beware key-loggers, especially if you enter your seed phrase.
-1. Beward cameras and eye-balls (the "over the shoulder" attack) if you generate and export your seed phrase.
-
-### Do not lose your keys/seed-phrase
-
-You must keep redundant backups of your coldkey. If you lose all access to your seed-phrase/initialized wallets, you permanently and unrecoverably lose access to your account (TAO, stake, etc.). 
 
-Common approaches:
-- **Paper backups** of the mnemonic phrase, sealed in tamper-evident envelopes and locked in a safety deposit box or safe.
-- **Encrypted USB drives** with strong passphrases stored in a safety deposit box or safe.  
-- **Multiple locations strategy** so that a single disaster (fire or flood) cannot destroy all copies.
 
 ### Rotating your coldkey
 

docs/getting-started/wallets.md

@@ -22,6 +22,43 @@ The coldkey private key is needed to authorize highly sensitive operations invol
 
 The coldkey public key identifies a wallet to the internet, serving as an address. To transfer ownership of TAO or alpha stake from one wallet to another, the sender needs only the public key of the recipient, and their own private key.
 
+## Wallets and wallet applications
+
+We must be careful to distinguish two senses of the term 'wallet' that can otherwise be confusing:
+
+- The **cryptographic wallet** is one or more cryptographic key pairs that comprise an identity, and allow a person to sign transactions or be referred to in transactions signed by others. In this sense, the wallet is more or less synonymous with the unique **coldkey** that controls access to your assets and serves as your public identity.
+
+- The **wallet application** is software that runs on your device and allows you to interact with the blockchain by entering your keys. There are several officially supported Bittensor wallet applications:
+
+  - The Bittensor wallet app for mobile: [bittensor.com/wallet](https://bittensor.com/wallet)
+  - [The Chrome extension](https://chromewebstore.google.com/detail/bittensor-wallet/bdgmdoedahdcjmpmifafdhnffjinddgc), which is also compatible with use of a Ledger hardware wallet. See [Using Ledger Hardware Wallet](../staking-and-delegation/using-ledger-hw-wallet.md)
+  - The Bittensor Python SDK, which includes the secure [Bittensor Wallet module](https://docs.bittensor.com/btwallet-api/html/autoapi/btwallet/wallet/index.html).
+  - The Bittensor CLI, `btcli`, which uses the Bittensor Wallet module under the hood. 
+
+Every Bittensor user has one or more cryptographic wallets, i.e. one or more coldkey. Any cryptographic wallet can be loaded into any number of wallet applications. If every wallet application that has been initialized with your cryptographic wallet (i.e. signed into with your coldkey private key) is closed, logged out, etc., and the device incinerated, your cryptographic wallet exists on the blockchain, and can be recovered with your *seed phrase*.
+
+Different wallet applications have different levels of functionality:
+
+- The mobile app and Chrome extension allow for staking and transfer of TAO balalnces, but do not include any hotkey management or advanced functionality.
+
+  - Note that the Chome extension is compatible with a hardware wallet, which can be a strong security option. This implies using a laptop as your [coldkey workstation](../getting-started/coldkey-hotkey-security).
+
+  - The mobile app depends on using a secure phone as a [coldkey workstation](../getting-started/coldkey-hotkey-security).
+
+- `btcli` and the SDK allow for hotkey management and other advanced functionality. These require a laptop as a [coldkey workstation](../getting-started/coldkey-hotkey-security).
+
+:::tip
+Note that you can also check balances on an unsecure device without entering your coldkey private key. For example, using [https://bittensor.com/scan](https://bittensor.com/scan). These website can be considered permissionless wallet applications.
+
+See [Coldkey and Hotkey Workstation Security: Permissionless workstation](../getting-started/coldkey-hotkey-security#permissionless-workstation)
+:::
+
+## The seed phrase a.k.a. mnemonic
+
+The ***seed phrase*** (a.k.a. 'menemonic' or 'recovery phrase') is a series of (at least 12) words that is generated together with your wallet's cryptographic key pair, and which can be used to recover the coldkey private key. This seed phrase is therefore a human-usable way to save access to the cryptographic wallet offline, and to import the cryptographic wallet into a wallet application.
+
+Arguably the most important operational goal when handling Bittensor wallets is to avoid losing or leaking your seed phrase. Make sure you [Handle your Seed Phrase/Mnemonic Securely](../keys/handle-seed-phrase).
+
 ## Wallet applications
 
 There are many different applications that can interact with your public and/or private keys in some way.

docs/keys/handle-seed-phrase.md

@@ -0,0 +1,139 @@
+---
+title: "Handle your Seed Phrase/Mnemonic Securely"
+---
+
+# Handle your Seed Phrase/Mnemonic Securely
+
+The seed phrase (a.k.a. 'menemonic' or 'recovery phrase') is a series of (at least 12) words that is generated together with your wallet's cryptographic key pair, and which can be used to recover the coldkey private key. This seed phrase is therefore a human-usable way to save access to the cryptographic wallet offline, and to import the cryptographic wallet into a wallet application.
+
+Whoever holds the seed phrase has full control over the wallet, so you should treat it like the keys to your digital safe. If someone else gains access to it, they can steal your assets. If you lose it, your assets are lost forever.
+
+There are two categories of security failure with a secret like a seed phrase/mnemonic:
+
+- To *lose* the secret means no longer having access to it. This implies permanent, unrecoverable loss of the resources (TAO and alpha stake, subnet creator permissions on a subnet, etc.) controlled by a Bittensor coldkey private key.
+- To *leak* the secret means accidentally giving someone else access to it. This may result in them stealing your resources, or further leaking it to others who may in turn act maliciously. If your secret is leaked, you can (and should) rotate it, i.e. perform a coldkey swap.
+
+	See: [Rotating your coldkey](../getting-started/coldkey-hotkey-security#rotating-your-coldkey)
+
+## Do not leak your keys/seed phrase
+
+1. Do not keep paper/analog copies somewhere they can be accessed without your knowledge.
+1. Do not expose your seed phrase to untrustworthy software by entering into applications:
+	- messaging
+	- email
+	- online word processors
+1. Beware key-logging software if you enter your seed phrase. Never enter your seed phrase on a device that may be compromised with malware!
+1. Beware screen capture software if you generate and export your seed phrase. Never enter your seed phrase on a device that may be compromised with malware!
+1. Beware cameras and eye-balls (the "over the shoulder" attack) if you generate and export your seed phrase. Don’t write it down or display it on screen in public or semi-public places.
+
+## Do not lose your keys/seed phrase
+
+You must keep redundant backups of your coldkey. If you lose all access to your seed phrase/initialized wallets, you permanently and unrecoverably lose access to your account (TAO, stake, etc.). 
+
+## Backup tactics
+
+Every option for backing up a seed phrase has pros and cons, and a full backup strategy relies on a combination of tactics that offers you a reasonable balance of security and accessbility.
+
+### Multiple-locations
+
+Keep redundant backups in separate, secure physical locations.
+
+Ensure that a single point of failure—like fire, flood, or theft—cannot destroy all copies.
+
+### Paper
+
+Tactics:
+
+- Write your seed phrase on acid-free, archival-quality paper.
+- Store it in a tamper-evident envelope in a locked safe or safety deposit box.
+- Avoid common paper degradation risks: humidity, fire, ink fade, etc.
+
+Pros:
+
+- No risk of digital leak (except cameras).
+- Can be hard to lose if properly secured in a safe.
+
+Cons:
+- Easy to leak if physical security is compromised (anyone can read or take a picture of it when the paper is exposed).
+- Easy to lose to physical disaster (e.g. fire).
+
+### Metal
+
+Tactic: Etch or stamp your seed phrase onto a metal plate.
+
+Pros: Extremely resistant to loss by destruction (e.g. fire).
+
+Cons: Easy to leak if physical security is compromised (anyone can read or take a picture of it when the plate is exposed).
+
+### Encrypted drive
+
+Tactics:
+- Save the seed phrase in an encrypted text file on a USB drive.
+- Use strong, unique passphrases and encrypt using industry-standard tools (e.g., GPG, VeraCrypt).
+- Store the USB in a secure physical location—never leave it connected to a device.
+- Only connect the USB drive to secure coldkey workstations.
+
+### Hardware wallet
+
+A hardware wallet such as a Ledger device that has a coldkey loaded into it can act as a backup, in a sense. It cannot be used to exfiltrate the seed phrase, but it can be used to transfer out assets or even coldkey swap to a new coldkey.
+
+Pros:
+
+- Strong protection against leaks
+- Tamper-resistant, PIN-protected
+
+Cons:
+
+- Signing device, *not* full backup; cannot export seed phrase
+- If lost and not backed up elsewhere, access is lost
+- High risk of loss due to mistaken factory reset (e.g. wrong PIN too many times)
+
+:::danger
+Only to be used in addition to backups of the seed phrase.
+:::
+
+Here’s a concise, on-brand section you can drop into your doc, matching the tone and structure of the others:
+
+### Mobile phone vault (e.g. Polkadot Vault)
+
+[Polkadot Vault](https://wiki.polkadot.network/general/polkadot-vault/) turns a smartphone into an air-gapped signing device. It holds your private keys securely offline and is used only to sign transactions via QR code.
+
+Pros:
+
+- Strong protection against remote compromise (air-gapped and network-disabled).
+- No direct exposure of seed phrase during signing.
+- Can be used to sign extrinsics without revealing keys to online devices.
+
+Cons:
+
+- Signing device, *not* full backup; cannot export seed phrase
+- Physical access can compromise keys.
+- Requires careful configuration for offline mode.
+- App updates require full device reset and recovery from seed.
+
+:::tip
+Use only a repurposed device kept permanently offline.
+:::
+
+### Shamir's Secret Sharing
+
+[Shamir’s Secret Sharing (SSS)](https://en.wikipedia.org/wiki/Shamir%27s_secret_sharing) is a cryptographic method for securely splitting a secret—like your seed phrase—into multiple pieces or “shares.” A minimum number of these shares must be recombined to reconstruct the original secret. This offers strong protection against both loss and leak.
+
+For example, you might split a seed phrase into 5 shares, requiring any 3 to restore the secret. These can be stored separately or given to different custodians.
+
+Pros:
+
+- Extremely resistant to both single-point loss and leakage:
+	- The leak of any share does not compromise your wallet.
+	- The loss of any share does not result in loss of the wallet.
+- Shares can be safely distributed across multiple locations or people.
+
+Cons:
+- Imposes additional operational complexity.
+- Stored secret is no longer human readable. Can be remedied with [slip39](https://github.com/satoshilabs/slips/blob/master/slip-0039.md).
+
+Tools:
+- [`sssa-golang`](https://github.com/SSSaaS/sssa-golang): An implementation of Shamir's Secret Sharing Algorithm in Go.
+- [Banana Split](https://github.com/paritytech/banana_split): Open source tool that uses a variation of SSS to split a seed phrase into QR codes.
+- [PyCryptodome SSS](https://pycryptodome.readthedocs.io/en/latest/src/protocol/ss.html): A Python-based implementation of the Shamir scheme.
+