improve docs about wallets and keys

docs/getting-started/wallets.md

@@ -4,6 +4,17 @@ title: "Wallets, Coldkeys and Hotkeys in Bittensor"
 import ThemedImage from '@theme/ThemedImage';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
+
+How do you recommend miners to store their cold keys?
+Ideally on an air gapped device or at least a device with minimal access / security risk involved. The coldkey must not be placed on a server used for mining as subnet code should not be considered safe code. Though most subnets take appropriate steps to ensure the security of their codebases, any time you have a port open and requests coming in there is risk.
+How often do miners have to use them and for what ops?
+The only operation miners need these for is to register onto the subnet. This should be done securely and not on servers that will be used for mining ops.
+And then so hotkeys as well, how in practical terms are people managing and propagating them
+Hotkeys are not encrypted by default (unlike coldkeys) and therefore have less security implications. Hotkeys do need to be present for a variety of operations which miner and validator software interact with such as axon serving, on-chain data commitments, and other functions. These essentially need to be present in the unsafe environment that is running subnet code on a machine but come with less risks if they do get compromised.
+What about rotation?
+Key rotation can add risk if the original coldkey is stored in a secure manner and is likely not too recommended unless there is a suspcicion or possibility that the original key has been or could have been compromised. An important note here is that specifically for validators, it is highly recommended to use a unique hotkey per subnet and rotate these when new subnets register. The reason being if a validator's single hotkey does get compromised, damage can be done by the attacker setting incorrect weights for miners or introducing a deadlock condition, effectively preventing normal operation.
+
+
 # Wallets, Coldkeys and Hotkeys in Bittensor
 
 In Bittensor (like other cryptocurrency applications), a *wallet* is a tool for managing the cryptographic key-pairs required to prove your identity, sign transactions, and access your TAO.
@@ -82,20 +93,9 @@ This dual-key system helps balance convenience and security, allowing you to par
 
 ## Operational uses of keys
 
-The below diagram shows a few operations you can do with a hotkey and coldkey. Not all possible operations are shown below. You can use the `btcli` to perform any of these operations. See [Bitttensor Wallet CLI](../btcli.md#wallets) for command syntax.
 
-<center>
-<ThemedImage
-alt="Coldkey and hotkey pairings"
-sources={{
-    light: useBaseUrl('/img/docs/1-operational-uses-of-keys.svg'),
-    dark: useBaseUrl('/img/docs/dark-1-operational-uses-of-keys.svg'),
-  }}
-style={{width: 850}}
-/>
-</center>
+WIP
 
-<br />
 
 The below numbered items describe the numbered sections in the above diagram:
 

docs/keys-questions.md

@@ -0,0 +1,244 @@
+---
+title: "Bittensor Wallets and Keys FAQ"
+--- 
+
+# Bittensor Wallets and Keys FAQ
+
+## Can polkadot multisigs be used for bittensor coldkeys?
+
+Maybe? Our old docs suggest so?
+
+https://wiki.polkadot.network/docs/learn-account-multisig
+
+## Can I check my TAO balance and stake without using my coldkey?
+
+Yes!
+https://bittensor.com/scan/address/5HHELoMy4QzWAjMwMsgnSqeWyWT9kfqByLLc2CKiziWmWgPj
+`btcli wallet balance --ss58-address COLDKEY`
+
+## Can I check my alpha without using my coldkey?
+
+Maybe in python? apparently not w btcli, i think apps let you do it?
+
+## Can I check the performance of miners and validators without a coldkey or hotkey
+
+yes you just need their hotkey address
+
+## Wallet Creation & Security
+
+### Can I create a coldkey without storing the mnemonic?
+
+No, you must store the mnemonic to recover your coldkey in case of loss.
+
+### What happens if someone steals my coldkey’s mnemonic?
+
+They can regenerate your key and access all your funds; you should move your funds immediately if compromised.
+
+### Is it safe to store my coldkey on an online machine?
+
+Not really, but depends on how much you care if your account gets hacked, ideally coldkeys should be stored offline on an air-gapped device to minimize risk.
+
+### How can I manage and back up my hotkey securely?
+
+Hashicorp Vault maybe? other secrets manager tools...
+
+### What are the different ways to create a wallet?
+
+   - btcli
+   - mobile app
+   - python
+
+
+### Can I change the password on my coldkey file?
+
+???
+
+
+### How do I securely delete an old coldkey?
+
+depends on what you mean...
+
+if you mean, a copy of a coldkey on a device that will allow you to sign transactions, you can delete the file, but it's really hard to make sure enough that it can't be recovered.
+
+
+the wallet in the sense of the key-pair and ledger entry is permanent. if you think your seed-phrase has been compromised, rotate your TAO and alpha stake holdings to another coldkey.
+
+
+
+
+
+### Are Bittensor wallets compatible with hardware wallets?
+
+Ledger works
+
+
+### What encryption algorithm does `btcli` use for wallets?
+
+???
+
+### Can I use multi-factor authentication (MFA) for my Bittensor wallet?
+
+Nope. There are a variety of security measures you can take, but not that.
+
+
+## Using Wallets Safely
+
+### Can I sign transactions without exposing my coldkey?
+
+Yes, use an air-gapped setup or a hardware signer.
+
+### How do I check if my coldkey has been compromised?
+
+that's tricky... if you suspect it has, rotate it by creating a new coldkey and transfering all your tao and stake to it, don't wait.
+
+
+### Can I use a Yubikey or other security key to protect my wallet?
+
+ Not natively, but you can use it for securing the storage of your encrypted coldkey file.
+
+
+### Can I generate a coldkey completely offline and import it to a live machine?
+
+Yes, this is recommended for maximum security.
+
+### Is it possible to use a different derivation path for generating wallet keys?
+???
+
+
+### What’s the best practice for using hotkeys in a cloud-hosted miner?
+
+Use separate hotkeys per subnet and rotate them periodically.
+
+### Can I revoke access to a hotkey without affecting my coldkey?
+
+No, hotkeys are permanently linked to the coldkey on-chain.
+
+### How can I check my coldkey’s stake without loading the wallet file?
+
+Use `btcli stake list --ss58 COLDKEY`.
+    NOPE this doesn't work? what about w python?
+
+
+## Transactions & Signing
+### Can I sign a transactions offline and then submit them
+
+Ledger?
+
+### How do I verify that a signed transaction was completed successfully?
+Check transaction history on `bittensor.com/scan`.
+
+### What happens if a malicious actor submits an invalid transaction using my coldkey?
+
+The transaction will fail.
+
+But keey in mind that anyone with your key (including recreating it from the seed phrase) can submit a transaction that is technically valid.
+
+
+
+### Can I set a spending limit for a coldkey?
+
+No, spending limits are not supported.
+
+### Are Bittensor transactions encrypted?
+No, they are public, but they are cryptographically signed onto the blockchain as part of a permanent, censorship-resistant record.
+
+### How do I track outgoing transactions from my wallet?
+
+Use `bittensor.com/scan` or query the chain with the following script...
+
+### Can I undo or reverse a transaction if I send it to the wrong address?
+
+No, blockchain transactions are irreversible.
+
+### How does the Bittensor network prevent double-spending attacks?
+
+Transactions are validated on-chain, ensuring spent TAO cannot be reused.
+
+
+## Staking & Security
+### Can I delegate my stake without exposing my wallet public address?
+
+no?
+
+### What’s the safest way to unstake my TAO?
+
+Use `btcli stake remove` on a secure machine.
+
+needs coldkey.
+
+
+### What happens if I stake to a malicious hotkey?
+
+???
+
+You might lose rewards but not your stake.
+
+
+
+### Can I set a whitelist of trusted hotkeys for staking?
+
+No, but you can manually choose validators.
+
+
+
+
+### Can I use a time-locked smart contract for staking security?
+
+???
+
+
+
+### What’s the process to recover staked funds if I lose my hotkey?
+
+You need access to the linked coldkey to withdraw.
+
+### How does the network verify stake transfers?
+
+Transfers are signed and recorded on-chain.
+
+### Can a subnet operator freeze or modify my stake?
+
+No, subnets cannot control individual stakes.
+
+
+## Hotkeys & Coldkeys
+### How does key rotation work in Bittensor?
+
+
+
+### Can I disable a hotkey without affecting my stake?
+
+
+
+### What’s the risk of exposing my hotkey’s address publicly?
+
+
+
+### Can I create a hotkey that only works for a specific subnet?
+
+.... no I think?
+
+### How do I securely transfer a wallet to another device?
+
+
+
+### Can I set an expiration date for a hotkey?
+
+No, hotkeys remain valid unless manually rotated.
+
+### If I delete my hotkey, can I recover it later?
+
+Only if you have the mnemonic backup.
+
+### What’s the safest way to store multiple hotkeys for different subnets?
+
+Use encrypted storage and air-gapped backups.
+
+### How can I confirm that a hotkey belongs to a particular coldkey?
+
+There is an identity thing I think in btcli.
+
+### Does Bittensor enforce rate limits on transactions from a single hotkey?
+
+Yes I think so? or maybe just coldkey?
+ions or modifications!

docs/miners/miners-guide-wallets-keys.md

@@ -0,0 +1,88 @@
+---
+title: "Miners Guide to Coldkeys and Hotkeys"
+---
+
+# Miners Guide to Coldkeys and Hotkeys
+
+[other stuff about keys](../keys-questions.md)
+
+Bittensor wallets have two different kinds of keys:
+- Every wallet has a unique **Coldkey**
+
+Bittensor uses a dual-key system to balance security and operational efficiency. As a miner, understanding how to manage your **coldkeys** and **hotkeys** is crucial. This guide explains their roles, proper storage practices, and key management strategies to help you secure your TAO and keep your mining operations running smoothly.
+
+
+## 1. Understanding the Dual-Key System
+
+### Coldkey
+- **Role**:  
+  - Acts as your wallet’s “safe” where your TAO funds are stored.  
+  - Used for high-risk operations like transferring funds, delegating tokens, and creating or registering subnets.
+- **Security**:  
+  - Always encrypted on your device.  
+  - Decrypted only in-memory and only when needed.
+- **Usage for Miners**:  
+  - **Rarely used** — primarily needed to register onto a subnet.  
+  - **Storage Recommendation**: Keep it on an air-gapped device or a machine with minimal network exposure. **Never** store your coldkey on a mining server, as the subnet code running on that server may present security risks.
+
+### Hotkey
+- **Role**:  
+  - Used for routine operational tasks, such as signing transactions and interacting with miner software (e.g., axon serving, on-chain data commitments).  
+  - When registering as a miner, the UID (unique identifier) is attached to the hotkey while the registration fee is drawn from the coldkey.
+- **Security**:  
+  - Typically unencrypted by default since it needs to be readily accessible for frequent use.  
+  - Although it has less stringent security requirements than the coldkey, keeping it secure is still important.
+- **Usage for Miners**:  
+  - Required to be present on your mining server to interact with the subnet.  
+  - Miners often manage multiple hotkeys linked to one coldkey, allowing flexibility across different subnets or operations.
+
+---
+
+## 2. Best Practices for Key Management
+
+### Storing Your Coldkey
+- **Use a Secure, Offline Environment**:  
+  - Store your coldkey on an air-gapped device or on a system with limited access to external networks.
+- **Avoid Exposure on Mining Servers**:  
+  - Do not place your coldkey on the same server running mining operations to reduce exposure to network threats.
+- **Additional Security Options**:  
+  - Consider using hardware signers (e.g., Ledger or Polkadot Vault) or advanced setups like MultiSig wallets and Proxy accounts.
+
+### Managing Your Hotkey
+- **Operational Availability**:  
+  - Since the hotkey is needed for day-to-day mining operations, it resides in a less secure (online) environment.
+- **Encryption Option**:  
+  - Although hotkeys are unencrypted by default, you have the option to encrypt them if you feel it’s necessary.
+- **Subnet Considerations**:  
+  - In a given subnet, each hotkey must be unique. While the same hotkey can be used for multiple UIDs in different subnets, never reuse a hotkey for multiple UIDs within the same subnet.
+
+### Key Rotation
+- **Coldkey Rotation**:  
+  - Generally not recommended unless there is clear evidence or suspicion that your coldkey has been compromised. Its secure storage and infrequent use make it inherently safer.
+- **Hotkey Rotation**:  
+  - For miners, maintain vigilance but avoid unnecessary rotation unless you have reasons to suspect compromise.
+
+---
+
+## 3. Operational Workflow for Miners
+
+1. **Initial Setup**:  
+
+   - Create your wallet with a coldkey and one or more hotkeys.
+   - Securely store the coldkey on an air-gapped device.
+2. **Subnet Registration**:  
+   - Use the coldkey from your secure environment to register onto the subnet. This is the only time you should use your coldkey for mining-related operations.
+3. **Daily Operations**:  
+   - Run your mining operations using the hotkey(s) stored on your mining server.
+   - Ensure that these hotkeys are managed responsibly, keeping in mind their exposure to the operational environment.
+4. **Ongoing Security Practices**:  
+   - Regularly review your setup and consider additional security measures if new threats arise.
+   - If you suspect any key has been compromised, act promptly to rotate or secure your keys, following best practices.
+
+---
+
+## Conclusion
+
+By separating the roles of coldkeys and hotkeys, Bittensor provides a robust security framework that allows miners to participate actively in the network while minimizing risk. Keep your coldkey secure and offline, use your hotkey for operational tasks on the mining server, and only rotate keys when necessary. Following these guidelines will help ensure that your mining operations are both secure and efficient.
+
+Happy mining!

sidebars.js

@@ -73,6 +73,7 @@ const sidebars = {
       link: {type: "doc", id: "miners/index",},
       items: [
       "miners/index",
+      "miners/miners-guide-wallets-keys"
       ],
     },
 
@@ -133,6 +134,7 @@ const sidebars = {
           items: [
             "getting-started/wallets",
             "working-with-keys",
+            "keys-questions"
           ]
         },
                 {