|
| 1 | +--- |
| 2 | +title: "Coldkey and Hotkey Workstation Security" |
| 3 | +--- |
| 4 | + |
| 5 | +# Coldkey and Hotkey Workstation Security |
| 6 | + |
| 7 | +This page goes into detail of security concerns for working with coldkeys and hotkeys in Bittensor. |
| 8 | + |
| 9 | +See also: |
| 10 | + |
| 11 | +- [Intro to Wallets, Coldkeys and Hotkeys in Bittensor](./wallets) |
| 12 | +- [Bittensor CLI: Permissions Guide](../btcli-permissions) |
| 13 | + |
| 14 | + |
| 15 | +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. |
| 16 | + |
| 17 | +The workstations you use to do this work can be referred to as a permissionless workstation (requiring neither private key), a coldkey workstation or a hotkey workstation, depending on which private key is provisioned. |
| 18 | + |
| 19 | +- [Permisionless workstation](#permissionless-workstation) |
| 20 | +- [Coldkey workstation](#permissionless-workstation) |
| 21 | +- [Hotkey workstation](#permissionless-workstation) |
| 22 | + |
| 23 | +## Permissionless workstation |
| 24 | + |
| 25 | +You can check public information about Bittensor wallets (including your TAO and alpha stake balances), subnets, validators, and more *without* using a (coldkey or hotkey) private key. This is because transaction information is public on the Bittensor blockchain, with parties being identified by their wallet's coldkey public key. |
| 26 | + |
| 27 | +When you use a website and apps with *only your public key*, this is considered "permissionless" work. Whenever possible, you should do permissionless work on a **permissionless workstation**, meaning a device (laptop or desktop computer, mobile phone, tablet, etc.) that does *not* have your coldkey private key loaded into it. |
| 28 | + |
| 29 | +In other words, don't use your coldkey private key when you don't have to, and avoiding loading it into devices unnecessarily. Every device that *does* have your coldkey private key loaded into it is a **coldkey workstation**, and should be used with security precautions. |
| 30 | + |
| 31 | +When you just want to read/check the state of the blockchain (balances, emissions, token prices, etc.) and you don't need to use your coldkey to *change* anything (for exmaple, to transfer TAO or move stake), it is preferable to use a permissionless workstation. |
| 32 | + |
| 33 | +To use the Bittensor CLI `btcli` as a permissionless workstation: |
| 34 | + |
| 35 | +1. Importing your coldkey ***public key*** (not private key) with: |
| 36 | + ```shell |
| 37 | + btcli w regen-coldkeypub --ss58 <YOUR COLDKEY PUBLIC KEY> |
| 38 | + ``` |
| 39 | + |
| 40 | +1. View your balances and stakes, as well as information about the Bittensor blockchain, subnets, miners, validators, etc., simply by running: |
| 41 | + ```shell |
| 42 | + btcli view dashboard |
| 43 | + ``` |
| 44 | + |
| 45 | +Websites that offer permissionless browsing of Bittensor data include: |
| 46 | + |
| 47 | +- [bittensor.com/scan](https://bittensor.com/scan) |
| 48 | +- [taostats.io](https://taostats.io/) |
| 49 | + |
| 50 | +## Coldkey workstation |
| 51 | + |
| 52 | +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. |
| 53 | + |
| 54 | +Because of these high stakes, best practices should be diligently followed. Always prioritize confidentiality and integrity over convenience when handling coldkeys. |
| 55 | + |
| 56 | +### Isolation of coldkey operations |
| 57 | + |
| 58 | +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. |
| 59 | + |
| 60 | +In short, you should approach all operations involving your coldkey management as high-value, mission-critical, and laden with inherant risk. |
| 61 | + |
| 62 | +Ensure a clear boundary between coldkey operations and the working environment you use to carry them out, and everything else. |
| 63 | + |
| 64 | +:::tip Coldkeys do not mine |
| 65 | + |
| 66 | +Miners will need coldkeys to manage their TAO and alpha currency, as well as hotkeys to serve requests. Ensure there is a clear boundary: The coldkey should **never** be on an environment with untrusted ML code from containers, frameworks, or libraries that might exfiltrate secrets. |
| 67 | +::: |
| 68 | + |
| 69 | +### Coldkey mobile device |
| 70 | + |
| 71 | +You can use the Bittensor mobile wallet app: [bittensor.com/wallet](https://bittensor.com/wallet). If so, it is recommended to use a dedicated mobile phone for the purpose that you do not install other software on, to minimize the risk of the coldkey or seed phrase being leaked. |
| 72 | + |
| 73 | +This option is suitable for alpha staking and TAO balance management. |
| 74 | + |
| 75 | +### Coldkey laptop |
| 76 | + |
| 77 | +This is required for using `btcli` or the Bittensor Python SDK for advanced use cases such as hotkey management and scripting. |
| 78 | + |
| 79 | +<!-- What is a minimal (?) recommended operating system for a bittensor coldkey workstation ??? --> |
| 80 | + |
| 81 | +### Operational Hygiene |
| 82 | + |
| 83 | +Even on a minimal or air-gapped machine, follow standard security hygiene: |
| 84 | +- Use strong passwords for your encryption passphrases. |
| 85 | +- Do not reuse credentials across different environments. |
| 86 | +- Keep your workstation’s operating system and critical software updated with the latest security patches. |
| 87 | +- Disable all network services (SSH, RDP, or anything else) that are not strictly needed. |
| 88 | +- Maintain logs of important oprations. |
| 89 | + |
| 90 | +### Your seed phrase |
| 91 | + |
| 92 | +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. |
| 93 | + |
| 94 | +### Do not leak your seed-phrase |
| 95 | + |
| 96 | +1. Do not keep paper/analog copies somewhere they can be accessed without your knowledge. |
| 97 | +1. Do not expose your seed-phrase to untrustworthy software by entering into apps: |
| 98 | + - messaging |
| 99 | + - email |
| 100 | + - online word processors |
| 101 | +1. Beware key-loggers, especially if you enter your seed phrase. |
| 102 | +1. Beward cameras and eye-balls (the "over the shoulder" attack) if you generate and export your seed phrase. |
| 103 | + |
| 104 | +### Do not lose your keys/seed-phrase |
| 105 | + |
| 106 | +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.). |
| 107 | + |
| 108 | +Common approaches: |
| 109 | +- **Paper backups** of the mnemonic phrase, sealed in tamper-evident envelopes and locked in a safety deposit box or safe. |
| 110 | +- **Encrypted USB drives** with strong passphrases stored in a safety deposit box or safe. |
| 111 | +- **Multiple locations strategy** so that a single disaster (fire or flood) cannot destroy all copies. |
| 112 | + |
| 113 | +### Rotating your coldkey |
| 114 | + |
| 115 | +If you suspect your coldkey may have been leaked, you can request to swap it out of your wallet, using an extrinsic blockchain transaction. This operation has a 5 day waiting period, during which your coldkey will be locked. The cost of this coldkey swap transaction is 0.1 TAO. |
| 116 | + |
| 117 | +See [Rotate/Swap your Coldkey](../subnets/schedule-coldkey-swap) |
| 118 | + |
| 119 | +Effectively, this transfers all of your TAO and alpha stake balances, as well as your `sudo` control over any subnets you have created: |
| 120 | + |
| 121 | +- For each hotkey owned by the old coldkey, its stake and block transfer to the new coldkey. |
| 122 | +- For each subnet, if the old coldkey is the owner, ownership transfers to the new coldkey. |
| 123 | +- For each hotkey staking for the old coldkey, transfer its stake to the new coldkey. |
| 124 | +- Total stake transfers from the old coldkey to the new coldkey. |
| 125 | +- The list of staking hotkeys transfers from the old coldkey to the new coldkey. |
| 126 | +- For each hotkey owned by the old coldkey, ownership transfers to the new coldkey. The list of owned hotkeys for both old and new coldkeys updates. |
| 127 | +- Any remaining balances transfer from the old coldkey to the new coldkey. |
| 128 | + |
| 129 | + |
| 130 | +### Hardware Wallets and Hardware Security Modules (HSMs) |
| 131 | + |
| 132 | +Ledger can be integrated with the Bittensor Chrome Extension. This may be a good option for managing stake and TAO balances, but does not allow for advanced functions such as hotkey management, subnet configuration, and governance. |
| 133 | + |
| 134 | +See [Using Ledger Hardware Wallet](../staking-and-delegation/using-ledger-hw-wallet). |
| 135 | + |
| 136 | +<!-- Enterprise-level hardware security modules? Are there services where you store private keys for signing without every exposing them and the company is insured for your value with them, does that exist? Do people use it? |
| 137 | +
|
| 138 | +What about Hashicorp Vault? Can you use that with HSM? AWS CloudHSM or Azure Key Vault with HSM-backed keys? How would the integration with `btcli` go |
| 139 | +
|
| 140 | +See: |
| 141 | +
|
| 142 | +- [AWS CloudHSM documentation](https://aws.amazon.com/cloudhsm/) |
| 143 | +- Oblique reference to [HashiCorp Vault with HSM integration](https://developer.hashicorp.com/vault/docs/configuration/seal) |
| 144 | + --> |
| 145 | + |
| 146 | +### Signing Policy and Governance |
| 147 | + |
| 148 | +If you work within a team or DAO environment that collectively manages a coldkey, consider implementing measures such as a multisig to avoid a compromise of a single individuals's keys from compromising the protected key. |
| 149 | + |
| 150 | +<!-- How to do this, Polkadot, EVM??? --> |
| 151 | + |
| 152 | +### Periodic Security Assessments |
| 153 | + |
| 154 | +Maintain a secure software environment: |
| 155 | +- Keep an eye on newly discovered OS or hardware vulnerabilities. |
| 156 | +- Run vulnerability scans on any machine that touches your coldkey. |
| 157 | +- Conduct red team exercises and penetration testing to identify weaknesses in your setup. |
| 158 | + |
| 159 | + |
| 160 | + |
| 161 | + |
| 162 | + |
| 163 | + |
| 164 | + |
| 165 | + |
| 166 | +## Hotkey workstation |
| 167 | + |
| 168 | +Hotkeys in Bittensor serve as the operational keys for mining, validation, and weight commits, which require moderately high availability. Because these keys do not control direct movement of TAO balances, they pose a lower risk if compromised. Nonetheless, a malicious actor who gains control of your hotkey can damage your reputation, submit invalid weights (if you are a validator) or serve malicious responses to requests as a miner. |
| 169 | + |
| 170 | +Overall, a hotkey workstation can be considered an “operational” environment. Losing a hotkey is less of a direct financial loss than losing a coldkey, but the reputational and operational risks can be serious. Use general best practices for managing secrets when handling your hotkeys. Include continuous monitoring of activity associated with your hotkey and have a rapid mitigation strategy in place in case your hotkey is compromised. |
| 171 | + |
| 172 | +### Secrets managements |
| 173 | + |
| 174 | +Bittensor miners must handle hotkeys in MLOps workflows. Hotkeys must be created in coldkey workstation environments and then provisioned to the mining/hotkey workstation environment, i.e. a server that will handle requests from validators, for example by querying an AI model to generate a response (a generated image or text response) to a text prompt from a user. |
| 175 | + |
| 176 | +- Secure secrets management solution (like [HashiCorp Vault](https://www.vaultproject.io/), [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/), or [GCP Secret Manager](https://cloud.google.com/secret-manager)) to provision the hotkey private key or seedphrase to the mining server. |
| 177 | +- Use ephemeral secret injection (CI/CD pipelines like GitLab or GitHub Actions allow storing secrets and injecting them at runtime). |
| 178 | +- Never put keys in code repositories |
| 179 | + |
| 180 | +### Hotkey rotation |
| 181 | + |
| 182 | +If you suspect that a hotkey (but not a coldkey) has been leaked, rotate it as soon as possible using `btcli wallet swap-hotkey`. This moves the registration to a newly created hotkey owned by the same coldkey, including all of the stake delegated by other users. |
| 183 | + |
| 184 | +Note that this operation incurs a $1 \tau$ recycling fee. |
| 185 | + |
| 186 | + |
| 187 | +### Minimize dependency risk |
| 188 | + |
| 189 | +Bittensor nodes often run complex software stacks with many dependencies. Take steps to reduce risk: |
| 190 | +- Keep your Python environment or Docker images updated with the latest patches. |
| 191 | +- Avoid installing unnecessary packages that might contain vulnerabilities. |
| 192 | +- Consider sandboxing the ML library if possible, using solutions like [PyPy sandboxing](https://doc.pypy.org/en/latest/sandbox.html) or custom Docker seccomp profiles. |
0 commit comments