Skip to main content
SUBMIT A PRSUBMIT AN ISSUElast edit: Jan 13, 2025

Wallets and keys 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.

This page introduces the core concepts of Bittensor wallets. Procedures for handling wallets and keys are described in: Working with keys

Coldkey and hotkey​

A Bittensor wallet consists of a coldkey and a hotkey. Coldkeys and hotkeys are used for different operations in the Bittensor ecosystem. These key types are associated with eachother on the blockchain and can be conveniently managed with btcli, the Bittensor SDK, or other Bittensor wallet software.

tip

Most users won't need a hotkey—this is not required to hold TAO and delegate it to Validators hotkey.

Miners and validators must have both. Miners are likely to have multiple hotkeys per coldkey.

Each key is a pairing of two separate EdDSA cryptographic keypairs. Hence, a coldkey is a pairing of a private key and a public key. Similarly, a hotkey is a pairing of another set of private key and public key. In this sense, a coldkey or a hotkey is each analogous to an account on a blockchain, where the account is defined by a pair of a public and a private key.

Coldkey​

In btcli, the coldkey is synonymous with the wallet name. For example, the --wallet.name option in a btcli command always accepts only <coldkey> as its value and the --wallet.hotkey option only accepts <hotkey> as its value. This is because the coldkey holds the permissions and ownership over multiple hotkeys on-chain; hence, the wallet name is assigned to the coldkey.

Relationship to hotkey: A coldkey can exist without a hotkey or have multiple hotkeys. For example, to create a subnet, delegate stake, or simply hold balance you only need a coldkey, but if you want to validate or mine in a subnet, you need a hotkey paired with this coldkey.

Purpose: A coldkey is primarily for secure TAO storage and high-risk transactions, as described below (Also see in the diagram in Operational uses of keys):

  • Your wallet's funds (TAO) on the chain are controlled by a coldkey.
  • Transferring your TAO to other wallets/addresses.
  • Delegating and undelegating your TAO tokens.
  • Creating a subnet and obtaining a netuid for the newly-created subnet. The netuid is associated with the coldkey because subnet owner operations should be secure and conducted infrequently.
  • Emissions to the subnet owner are deposited directly to the subnet owner's coldkey.

Security: A coldkey is always encrypted when in your device storage. Only ever decrypted in-memory and only when needed.

A coldkey is like a highly secure key you use to access a safe where your valuables are stored. The coldkey is used less frequently than the hotkey, and is stored very securely to minimize the risk of unauthorized access.

To keep your coldkey more secure, you may consider a hardware signer.

A hardware signer is a secure method of storing your coldkey. It provides a separation between online devices and your private key. Some options include the Polkadot Vault application, a Ledger wallet, among others.

Additionally, you might consider using a MultiSig (multiple signature) wallet, or a Proxy account setup.

Existential deposit​

An existential deposit is the minumum required TAO in a wallet (i.e., in a coldkey). If a wallet balance goes below the existential deposit, then this wallet account is deactivated and the remaining TAO in it is destroyed. This is set to 500 RAO for any Bittensor wallet. Also see What is the Existential Deposit?.

Hotkey​

Relationship to coldkey: You can create multiple hotkeys paired to your single coldkey. However, when you are validating or mining in a subnet, you are identified by a hotkey in that subnet, so that your coldkey is not exposed. Hence, you cannot use the same hotkey for two UIDs in a given subnet. You can, however, use the same hotkey for multiple UIDs but with each UID in a separate subnet. Also see Register, Validate and Mine.

Purpose: Used for regular operational tasks in the Bittensor network, such as described below (Also see in the diagram in Operational uses of keys):

  • Signing transactions.
  • Registering and running subnet miners and subnet validators.
  • If you are a subnet validator, then you can nominate your own hotkey so that the TAO holders can send their TAO to the hotkey.
  • If you are a TAO holder, for example, with a coldkey where your TAO is stored, you can delegate your TAO to the hotkey of the validator-delegate. See item 10 in the diagram in Operational uses of keys.

Security: A hotkey is less secure than a coldkey. A hotkey is, by default, unencrypted, but you can encrypt it.

Why hotkey

Think of a hotkey as an everyday key you carry for tasks that require regular access. Because a hotkey is used more frequently and should be readily accessible, the hotkey carries a higher risk of exposure to potential threats. However, the permissions and scope of operations that can be performed with the hotkey are limited to operational activities, minimizing the risk of significant loss of TAO.

This dual-key system helps balance convenience and security, allowing you to participate actively in the Bittensor network without constantly exposing your primary TAO-holding coldkey.

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 for command syntax.

Coldkey and hotkey pairingsColdkey and hotkey pairings

The below numbered items describe the numbered sections in the above diagram:

  1. A coldkey can be paired with multiple hotkeys. A coldkey is a more secure key.
  2. In a given subnet, you can only use a hotkey for one UID. You cannot use the same hotkey for another UID in the same subnet. However, you can use a given hotkey for two different UIDs that are in two separate subnets.
  3. Transfer of TAO is always between one coldkey and another coldkey. That is, between one wallet and another wallet.
  4. When you create a subnet, the subnet registration costs are taken out of the subnet owner's cold key. The netuid of the subnet is associated with the coldkey only. This is because all subnet owner operations are highly secure and thus require the coldkey (which is always encrypted). The hotkey has no role here.
  5. When you register as a subnet miner or a subnet validator, the registration costs will come out of your coldkey, but the UID is attached to your hotkey. Note that this registration type differs from creating a subnet, which only requires your coldkey. See (4) above.
  6. Subnet owner emissions are deposited directly into the subnet owner's coldkey. The hotkey has no role here.
  7. Emissions to the subnet validator and subnet miner are deposited directly into the hotkey to which the UID is attached. See (5) above.
  8. As a validator, when you stake your TAO, your TAO will be transferred from your coldkey to your hotkey, which is attached to the UID. Similarly, unstaking will move the TAO from the hotkey attached to the UID into its coldkey.
  9. As a validator, you can nominate your hotkey attached to the UID. This will publish the hotkey. TAO holders will send their TAO to this hotkey. This is also referred to as TAO holders delegating their TAO, or staking their TAO, to you, the validator. Also see (10) below.
  10. As a TAO holder, you delegate your TAO to a validator's hotkey. The TAO you delegated will go from your coldkey into the validator's hotkey. This validator's hotkey is permanently attached to the validator's UID. Also see (9) above.